Skip to main content

offline_registry/
model.rs

1//! Data model for the Offline Protocol registry: packages, workflows,
2//! skills, and template metadata.
3
4use std::collections::BTreeMap;
5
6use serde::{Deserialize, Serialize};
7
8/// A published Offline Protocol package (npm, crates.io, PyPI, a Swift
9/// package or a release download) and the metadata the CLI / MCP server uses
10/// to recommend and wire it into projects.
11#[derive(Debug, Clone, Serialize, Deserialize)]
12#[serde(rename_all = "camelCase")]
13pub struct PackageManifest {
14    /// Package name as published (e.g. `@offline-protocol/mesh-sdk`).
15    pub name: String,
16    /// Latest known-good version the registry pins to.
17    pub version: String,
18    pub description: String,
19    /// Platforms this package supports: `react-native`, `web`, `nextjs`,
20    /// `react-vite`, `rust`, or one of the package-only platforms
21    /// (`python`, `ios-native`, `android-native`, `embedded`, `flutter`,
22    /// `java`, `c`, `ruby`, `csharp`), which have packages but no starter
23    /// templates.
24    pub platforms: Vec<String>,
25    /// Where it ships: `npm`, `crates`, `pypi`, `swiftpm` (a Swift package
26    /// pulled by URL), `maven` (Maven Central, a Gradle dependency),
27    /// `github-release` (a release asset to download), `source` (built
28    /// from a checkout of a tagged release, such as a path dependency) or
29    /// `rubygems` (a Ruby gem).
30    #[serde(default = "default_npm")]
31    pub registry: String,
32    /// Install instruction, verbatim, when the registry's default command
33    /// (`npm install`, `cargo add`, `pip install`) does not apply. Required
34    /// for `swiftpm`, `maven`, `github-release`, `source` and `rubygems`; it
35    /// must name `version`.
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    pub install: Option<String>,
38    /// Other names the package is known by (a Swift product, Maven
39    /// coordinates, a Python import name), accepted by name lookups.
40    #[serde(default, skip_serializing_if = "Vec::is_empty")]
41    pub aliases: Vec<String>,
42    pub license: String,
43    /// Extra licensing context (e.g. commercial dual-license availability).
44    #[serde(default, skip_serializing_if = "Option::is_none")]
45    pub license_note: Option<String>,
46    #[serde(default, skip_serializing_if = "Option::is_none")]
47    pub repository: Option<String>,
48    /// Capability identifiers this package provides (e.g. `mesh-networking`).
49    #[serde(default)]
50    pub capabilities: Vec<String>,
51    /// Other registry packages that must be installed alongside this one.
52    #[serde(default)]
53    pub requires: Vec<String>,
54    /// Non-registry peer dependencies (name -> version range).
55    #[serde(default)]
56    pub peer_dependencies: BTreeMap<String, String>,
57    /// Skill documents that teach how to use this package.
58    #[serde(default)]
59    pub skills: Vec<String>,
60    #[serde(default)]
61    pub keywords: Vec<String>,
62    #[serde(default)]
63    pub examples: Vec<Example>,
64    /// `stable`, `beta`, `preview` (published, API not settled) or
65    /// `pre-release`.
66    #[serde(default = "default_stable")]
67    pub status: String,
68    /// Free-form integration notes surfaced during `offline add` / planning.
69    #[serde(default)]
70    pub notes: Vec<String>,
71}
72
73fn default_npm() -> String {
74    "npm".to_string()
75}
76
77fn default_stable() -> String {
78    "stable".to_string()
79}
80
81#[derive(Debug, Clone, Serialize, Deserialize)]
82#[serde(rename_all = "camelCase")]
83pub struct Example {
84    pub name: String,
85    pub description: String,
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub source: Option<String>,
88    /// P2P pattern tag for example discovery (e.g. `mesh-services + host-authority`).
89    #[serde(default, skip_serializing_if = "Option::is_none")]
90    pub pattern: Option<String>,
91}
92
93/// A workflow maps a product intent ("community app") to capabilities,
94/// packages, and a starter template per platform.
95#[derive(Debug, Clone, Serialize, Deserialize)]
96#[serde(rename_all = "camelCase")]
97pub struct Workflow {
98    pub name: String,
99    pub title: String,
100    pub description: String,
101    #[serde(default)]
102    pub capabilities: Vec<String>,
103    /// Keywords used by the planner to score prompts against workflows.
104    #[serde(default)]
105    pub keywords: Vec<String>,
106    /// Skills to read for this workflow, in order. When empty, the planner
107    /// lists the skills of the workflow's packages instead.
108    #[serde(default, skip_serializing_if = "Vec::is_empty")]
109    pub skills: Vec<String>,
110    /// platform -> ordered package list.
111    #[serde(default)]
112    pub packages: BTreeMap<String, Vec<String>>,
113    /// platform -> template name.
114    #[serde(default)]
115    pub templates: BTreeMap<String, String>,
116    #[serde(default)]
117    pub architecture: Architecture,
118}
119
120#[derive(Debug, Clone, Default, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122pub struct Architecture {
123    #[serde(default)]
124    pub screens: Vec<String>,
125    #[serde(default)]
126    pub services: Vec<String>,
127    #[serde(default)]
128    pub events: Vec<String>,
129    #[serde(default)]
130    pub data_models: Vec<String>,
131    #[serde(default)]
132    pub notes: Vec<String>,
133}
134
135/// A skill is a markdown knowledge document with YAML frontmatter.
136#[derive(Debug, Clone, Serialize)]
137pub struct Skill {
138    pub name: String,
139    pub title: String,
140    pub description: String,
141    pub use_when: Vec<String>,
142    pub packages: Vec<String>,
143    pub platforms: Vec<String>,
144    /// Markdown body (frontmatter stripped).
145    pub body: String,
146}
147
148/// Frontmatter section of a skill document.
149#[derive(Debug, Clone, Deserialize)]
150pub struct SkillFrontmatter {
151    pub name: String,
152    pub title: String,
153    pub description: String,
154    #[serde(default)]
155    pub use_when: Vec<String>,
156    #[serde(default)]
157    pub packages: Vec<String>,
158    #[serde(default)]
159    pub platforms: Vec<String>,
160}
161
162/// Metadata for a starter template (`registry/templates/<name>/template.json`).
163#[derive(Debug, Clone, Serialize, Deserialize)]
164#[serde(rename_all = "camelCase")]
165pub struct TemplateMeta {
166    pub name: String,
167    pub title: String,
168    pub description: String,
169    pub platform: String,
170    #[serde(default, skip_serializing_if = "Option::is_none")]
171    pub workflow: Option<String>,
172    /// The template is built on `@offline-protocol/mesh-sdk` throughout, so
173    /// mesh support (and its native permission setup) is always on.
174    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
175    pub requires_mesh: bool,
176    #[serde(default)]
177    pub variables: Vec<TemplateVariable>,
178    /// Commands the developer should run after generation, in order.
179    #[serde(default)]
180    pub post_generate: Vec<String>,
181    #[serde(default)]
182    pub notes: Vec<String>,
183    /// Whether the generated app needs hosted Offline Protocol services (a
184    /// portal application id or API key), so `offline create` must sign in
185    /// first. Local-only starters (BLE mesh without hosted services) set this
186    /// to `false` and can be scaffolded without an account. Defaults to `true`.
187    #[serde(default = "default_true")]
188    pub requires_login: bool,
189    /// Full example application from offline-app-examples (includes native
190    /// android/ios and vendored packages/). Listed as `offline create <id>`.
191    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
192    pub example_app: bool,
193}
194
195fn default_true() -> bool {
196    true
197}
198
199#[derive(Debug, Clone, Serialize, Deserialize)]
200#[serde(rename_all = "camelCase")]
201pub struct TemplateVariable {
202    pub name: String,
203    pub prompt: String,
204    #[serde(default, skip_serializing_if = "Option::is_none")]
205    pub default: Option<String>,
206    #[serde(default)]
207    pub required: bool,
208}
209
210/// Curated search vocabulary for one capability, from
211/// `registry/capabilities.json`: the words a developer types when they want
212/// it ("bluetooth", "login") but that the capability name does not contain.
213#[derive(Debug, Clone, Default, Serialize, Deserialize)]
214#[serde(rename_all = "camelCase", deny_unknown_fields)]
215pub struct CapabilityTerms {
216    #[serde(default)]
217    pub keywords: Vec<String>,
218    /// Skills that cover the capability when no skill has its name (for
219    /// example `offline-messaging` -> `messaging`). Used to resolve a
220    /// capability name given where a skill name is expected.
221    #[serde(default, skip_serializing_if = "Vec::is_empty")]
222    pub skills: Vec<String>,
223}
224
225/// A capability aggregated across packages and workflows.
226#[derive(Debug, Clone, Serialize)]
227pub struct Capability {
228    pub name: String,
229    pub packages: Vec<String>,
230    pub workflows: Vec<String>,
231    /// The skill with the capability's name, then the curated skills from
232    /// `capabilities.json`.
233    pub skills: Vec<String>,
234}