offline-registry 0.4.0

Registry of Offline Protocol packages, skills, workflows, and templates
Documentation
//! Data model for the Offline Protocol registry: packages, workflows,
//! skills, and template metadata.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

/// A published Offline Protocol package (npm, crates.io, PyPI, a Swift
/// package or a release download) and the metadata the CLI / MCP server uses
/// to recommend and wire it into projects.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PackageManifest {
    /// Package name as published (e.g. `@offline-protocol/mesh-sdk`).
    pub name: String,
    /// Latest known-good version the registry pins to.
    pub version: String,
    pub description: String,
    /// Platforms this package supports: `react-native`, `web`, `nextjs`,
    /// `react-vite`, `rust`, or one of the package-only platforms
    /// (`python`, `ios-native`, `android-native`, `embedded`, `flutter`,
    /// `java`, `c`, `ruby`, `csharp`), which have packages but no starter
    /// templates.
    pub platforms: Vec<String>,
    /// Where it ships: `npm`, `crates`, `pypi`, `swiftpm` (a Swift package
    /// pulled by URL), `maven` (Maven Central, a Gradle dependency),
    /// `github-release` (a release asset to download), `source` (built
    /// from a checkout of a tagged release, such as a path dependency) or
    /// `rubygems` (a Ruby gem).
    #[serde(default = "default_npm")]
    pub registry: String,
    /// Install instruction, verbatim, when the registry's default command
    /// (`npm install`, `cargo add`, `pip install`) does not apply. Required
    /// for `swiftpm`, `maven`, `github-release`, `source` and `rubygems`; it
    /// must name `version`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub install: Option<String>,
    /// Other names the package is known by (a Swift product, Maven
    /// coordinates, a Python import name), accepted by name lookups.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub aliases: Vec<String>,
    pub license: String,
    /// Extra licensing context (e.g. commercial dual-license availability).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub license_note: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub repository: Option<String>,
    /// Capability identifiers this package provides (e.g. `mesh-networking`).
    #[serde(default)]
    pub capabilities: Vec<String>,
    /// Other registry packages that must be installed alongside this one.
    #[serde(default)]
    pub requires: Vec<String>,
    /// Non-registry peer dependencies (name -> version range).
    #[serde(default)]
    pub peer_dependencies: BTreeMap<String, String>,
    /// Skill documents that teach how to use this package.
    #[serde(default)]
    pub skills: Vec<String>,
    #[serde(default)]
    pub keywords: Vec<String>,
    #[serde(default)]
    pub examples: Vec<Example>,
    /// `stable`, `beta`, `preview` (published, API not settled) or
    /// `pre-release`.
    #[serde(default = "default_stable")]
    pub status: String,
    /// Free-form integration notes surfaced during `offline add` / planning.
    #[serde(default)]
    pub notes: Vec<String>,
}

fn default_npm() -> String {
    "npm".to_string()
}

fn default_stable() -> String {
    "stable".to_string()
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Example {
    pub name: String,
    pub description: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<String>,
    /// P2P pattern tag for example discovery (e.g. `mesh-services + host-authority`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pattern: Option<String>,
}

/// A workflow maps a product intent ("community app") to capabilities,
/// packages, and a starter template per platform.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Workflow {
    pub name: String,
    pub title: String,
    pub description: String,
    #[serde(default)]
    pub capabilities: Vec<String>,
    /// Keywords used by the planner to score prompts against workflows.
    #[serde(default)]
    pub keywords: Vec<String>,
    /// Skills to read for this workflow, in order. When empty, the planner
    /// lists the skills of the workflow's packages instead.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub skills: Vec<String>,
    /// platform -> ordered package list.
    #[serde(default)]
    pub packages: BTreeMap<String, Vec<String>>,
    /// platform -> template name.
    #[serde(default)]
    pub templates: BTreeMap<String, String>,
    #[serde(default)]
    pub architecture: Architecture,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Architecture {
    #[serde(default)]
    pub screens: Vec<String>,
    #[serde(default)]
    pub services: Vec<String>,
    #[serde(default)]
    pub events: Vec<String>,
    #[serde(default)]
    pub data_models: Vec<String>,
    #[serde(default)]
    pub notes: Vec<String>,
}

/// A skill is a markdown knowledge document with YAML frontmatter.
#[derive(Debug, Clone, Serialize)]
pub struct Skill {
    pub name: String,
    pub title: String,
    pub description: String,
    pub use_when: Vec<String>,
    pub packages: Vec<String>,
    pub platforms: Vec<String>,
    /// Markdown body (frontmatter stripped).
    pub body: String,
}

/// Frontmatter section of a skill document.
#[derive(Debug, Clone, Deserialize)]
pub struct SkillFrontmatter {
    pub name: String,
    pub title: String,
    pub description: String,
    #[serde(default)]
    pub use_when: Vec<String>,
    #[serde(default)]
    pub packages: Vec<String>,
    #[serde(default)]
    pub platforms: Vec<String>,
}

/// Metadata for a starter template (`registry/templates/<name>/template.json`).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TemplateMeta {
    pub name: String,
    pub title: String,
    pub description: String,
    pub platform: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workflow: Option<String>,
    /// The template is built on `@offline-protocol/mesh-sdk` throughout, so
    /// mesh support (and its native permission setup) is always on.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub requires_mesh: bool,
    #[serde(default)]
    pub variables: Vec<TemplateVariable>,
    /// Commands the developer should run after generation, in order.
    #[serde(default)]
    pub post_generate: Vec<String>,
    #[serde(default)]
    pub notes: Vec<String>,
    /// Whether the generated app needs hosted Offline Protocol services (a
    /// portal application id or API key), so `offline create` must sign in
    /// first. Local-only starters (BLE mesh without hosted services) set this
    /// to `false` and can be scaffolded without an account. Defaults to `true`.
    #[serde(default = "default_true")]
    pub requires_login: bool,
    /// Full example application from offline-app-examples (includes native
    /// android/ios and vendored packages/). Listed as `offline create <id>`.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub example_app: bool,
}

fn default_true() -> bool {
    true
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TemplateVariable {
    pub name: String,
    pub prompt: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
    #[serde(default)]
    pub required: bool,
}

/// Curated search vocabulary for one capability, from
/// `registry/capabilities.json`: the words a developer types when they want
/// it ("bluetooth", "login") but that the capability name does not contain.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CapabilityTerms {
    #[serde(default)]
    pub keywords: Vec<String>,
    /// Skills that cover the capability when no skill has its name (for
    /// example `offline-messaging` -> `messaging`). Used to resolve a
    /// capability name given where a skill name is expected.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub skills: Vec<String>,
}

/// A capability aggregated across packages and workflows.
#[derive(Debug, Clone, Serialize)]
pub struct Capability {
    pub name: String,
    pub packages: Vec<String>,
    pub workflows: Vec<String>,
    /// The skill with the capability's name, then the curated skills from
    /// `capabilities.json`.
    pub skills: Vec<String>,
}