From 1658b5456f5bf875e6ccb938b49cef330292eb80 Mon Sep 17 00:00:00 2001 From: Gordon Farquharson Date: Thu, 9 Apr 2026 08:05:28 +0100 Subject: [PATCH 1/2] update plugin manifest --- context/CONTEXT_INDEX.md | 7 +++ context/PLUGIN_CONTRACT.md | 68 ++++++++++++++++++++++++++++ fastedge-plugin-source/manifest.json | 28 ++++++------ 3 files changed, 89 insertions(+), 14 deletions(-) create mode 100644 context/PLUGIN_CONTRACT.md diff --git a/context/CONTEXT_INDEX.md b/context/CONTEXT_INDEX.md index 52057cb..edbfc69 100644 --- a/context/CONTEXT_INDEX.md +++ b/context/CONTEXT_INDEX.md @@ -67,6 +67,12 @@ Contract directory consumed by the fastedge-plugin sync pipeline. Contains `mani | `fastedge-plugin-source/.generation-config.md` | Generation instructions for each docs/ file (Global Rules, per-file specs) | | `fastedge-plugin-source/generate-docs.sh` | Tiered parallel generation script | +### Plugin Integration (read when modifying manifest or examples) + +| Document | Lines | Purpose | +|----------|-------|---------| +| `PLUGIN_CONTRACT.md` | ~70 | Naming conventions, manifest rules, intent file matching for the fastedge-plugin sync pipeline. Read when adding examples to `manifest.json` or changing `fastedge-plugin-source/`. | + ### External (not in context/) | Resource | Location | Purpose | @@ -127,6 +133,7 @@ Contract directory consumed by the fastedge-plugin sync pipeline. Contains `mani 4. Read `PROJECT_OVERVIEW.md` (examples section) 5. Read `development/BUILD_AND_CI.md` (example build pattern) 6. **Logging:** Use `println!` only — `eprintln!` output is lost on the platform +7. **Plugin sync**: If this example should feed into fastedge-plugin, read `context/PLUGIN_CONTRACT.md` for manifest and naming conventions ### Understanding the System (New to Codebase) 1. Read `PROJECT_OVERVIEW.md` (~149 lines) diff --git a/context/PLUGIN_CONTRACT.md b/context/PLUGIN_CONTRACT.md new file mode 100644 index 0000000..d3857f3 --- /dev/null +++ b/context/PLUGIN_CONTRACT.md @@ -0,0 +1,68 @@ +# Plugin Source Contract — Naming Conventions + +This document describes the naming and structure conventions for `manifest.json` in this repo. These rules ensure the sync-reference-docs pipeline correctly maps source files to plugin reference docs and intent skills. + +## Reference File Structure + +Reference files in the plugin repo are organized by app_type: + +``` +plugins/gcore-fastedge/skills/ + scaffold/reference/ + http/ # HTTP app blueprints + base-rust.md # Base skeleton + kv-store-rust.md # Feature blueprint + cdn/ # CDN app blueprints + base-rust.md # Base skeleton + body-rust.md # Feature blueprint + fastedge-docs/reference/ + http/ # HTTP app example patterns + examples-kv-store-rust.md + cdn/ # CDN app example patterns + examples-body-rust.md + sdk-reference-rust.md # Cross-cutting (no subfolder) + host-services-rust.md # Cross-cutting (no subfolder) +``` + +Note: `http/base-rust.md` and `cdn/base-rust.md` have the same filename but live in different subfolders. The pipeline's path-based intent matching resolves them to different intent files. + +## File Naming Convention + +**`{concept}-{lang}.md`** — concept first, language last. The subfolder provides the app_type context. + +| Type | Pattern | Example | +|---|---|---| +| Base skeleton | `{appType}/base-{lang}.md` | `http/base-rust.md`, `cdn/base-rust.md` | +| Feature blueprint | `{appType}/{concept}-{lang}.md` | `cdn/body-rust.md` | +| Docs pattern | `{appType}/examples-{concept}-{lang}.md` | `cdn/examples-body-rust.md` | +| Cross-cutting SDK ref | `sdk-reference-{lang}.md` | `sdk-reference-rust.md` | +| Cross-cutting host services | `host-services-{lang}.md` | `host-services-rust.md` | + +## Manifest target_mapping Rules + +1. **reference_file** paths must include the `http/` or `cdn/` subfolder for app_type-specific content +2. **section** should be `null` for all entries (each file is owned by one repo — no splicing) +3. **Dual-intent pattern**: each example gets two entries with the same `files` array: + - `{name}-blueprint` → `scaffold/reference/{appType}/{concept}-{lang}.md` + - `{name}-pattern` → `fastedge-docs/reference/{appType}/examples-{concept}-{lang}.md` + +## Intent File Matching + +The pipeline resolves intent files by extracting the path suffix after `reference/` from the `reference_file` path. It looks for that same relative path inside the plugin's intent directory for this repo. + +Example: +- `reference_file`: `plugins/.../scaffold/reference/cdn/body-rust.md` +- Path suffix: `cdn/body-rust.md` +- Intent lookup: `agent-intent-skills/fastedge-sdk-rust/cdn/body-rust.md` + +This is why `http/base-rust.md` and `cdn/base-rust.md` can coexist — they resolve to `agent-intent-skills/fastedge-sdk-rust/http/base-rust.md` and `agent-intent-skills/fastedge-sdk-rust/cdn/base-rust.md` respectively. + +## When Adding New Examples + +1. Add source entries (paired `-blueprint` and `-pattern`) to `manifest.json` +2. Add target_mapping entries pointing to `{appType}/{concept}-{lang}.md` paths +3. Request intent files be created in `fastedge-plugin` repo (or create via PR): + - `agent-intent-skills/fastedge-sdk-rust/{appType}/{concept}-{lang}.md` (scaffold) + - `agent-intent-skills/fastedge-sdk-rust/{appType}/examples-{concept}-{lang}.md` (docs) + - Each should reference `../_scaffold-blueprint-base.md` or `../_docs-pattern-base.md` +4. Create placeholder reference files at the target paths in the plugin repo diff --git a/fastedge-plugin-source/manifest.json b/fastedge-plugin-source/manifest.json index 75013cd..d424117 100644 --- a/fastedge-plugin-source/manifest.json +++ b/fastedge-plugin-source/manifest.json @@ -107,12 +107,12 @@ }, "target_mapping": { "sdk-api": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference.md", - "section": "Rust SDK" + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference-rust.md", + "section": null }, "host-services": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference.md", - "section": "Rust SDK" + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/host-services-rust.md", + "section": null }, "cdn-apps": { "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/cdn-apps-rust.md", @@ -120,48 +120,48 @@ }, "http-hello-world-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/base-http-rust.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/base-rust.md", "section": null }, "cdn-hello-world-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/base-cdn-rust.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn/base-rust.md", "section": null }, "cdn-body-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn-rust-body.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn/body-rust.md", "section": null }, "cdn-body-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-rust-body.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/cdn/examples-body-rust.md", "section": null }, "http-key-value-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-rust-kv-store.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/kv-store-rust.md", "section": null }, "http-key-value-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-rust-kv-store.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-kv-store-rust.md", "section": null }, "cdn-jwt-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn-rust-auth-jwt.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn/auth-jwt-rust.md", "section": null }, "cdn-jwt-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-rust-auth-jwt.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/cdn/examples-auth-jwt-rust.md", "section": null }, "cdn-geoblock-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn-rust-geoblock.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/cdn/geoblock-rust.md", "section": null }, "cdn-geoblock-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-rust-geoblock.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/cdn/examples-geoblock-rust.md", "section": null } }, From 59df2adcac9d01aeb6e59b8d1b66d7bb42daac32 Mon Sep 17 00:00:00 2001 From: Gordon Farquharson Date: Thu, 9 Apr 2026 08:30:47 +0100 Subject: [PATCH 2/2] copilot --- context/PLUGIN_CONTRACT.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/context/PLUGIN_CONTRACT.md b/context/PLUGIN_CONTRACT.md index d3857f3..59255cb 100644 --- a/context/PLUGIN_CONTRACT.md +++ b/context/PLUGIN_CONTRACT.md @@ -22,6 +22,7 @@ plugins/gcore-fastedge/skills/ examples-body-rust.md sdk-reference-rust.md # Cross-cutting (no subfolder) host-services-rust.md # Cross-cutting (no subfolder) + cdn-apps-rust.md # Cross-cutting app-type guide (no subfolder) ``` Note: `http/base-rust.md` and `cdn/base-rust.md` have the same filename but live in different subfolders. The pipeline's path-based intent matching resolves them to different intent files. @@ -37,15 +38,18 @@ Note: `http/base-rust.md` and `cdn/base-rust.md` have the same filename but live | Docs pattern | `{appType}/examples-{concept}-{lang}.md` | `cdn/examples-body-rust.md` | | Cross-cutting SDK ref | `sdk-reference-{lang}.md` | `sdk-reference-rust.md` | | Cross-cutting host services | `host-services-{lang}.md` | `host-services-rust.md` | +| Cross-cutting app-type guide | `{appType}-apps-{lang}.md` | `cdn-apps-rust.md` | ## Manifest target_mapping Rules -1. **reference_file** paths must include the `http/` or `cdn/` subfolder for app_type-specific content +1. **reference_file** paths must include the `http/` or `cdn/` subfolder for per-example content (blueprints and patterns). Cross-cutting references (`sdk-reference`, `host-services`, `cdn-apps`) live directly under `fastedge-docs/reference/` with no subfolder 2. **section** should be `null` for all entries (each file is owned by one repo — no splicing) -3. **Dual-intent pattern**: each example gets two entries with the same `files` array: +3. **Dual-intent pattern**: each **feature** example gets two entries with the same `files` array: - `{name}-blueprint` → `scaffold/reference/{appType}/{concept}-{lang}.md` - `{name}-pattern` → `fastedge-docs/reference/{appType}/examples-{concept}-{lang}.md` + **Exception**: Base skeleton examples (`http-hello-world`, `cdn-hello-world`) only get a `-blueprint` entry pointing to `scaffold/reference/{appType}/base-{lang}.md`. They have no `-pattern` counterpart because they don't demonstrate a reusable feature pattern. + ## Intent File Matching The pipeline resolves intent files by extracting the path suffix after `reference/` from the `reference_file` path. It looks for that same relative path inside the plugin's intent directory for this repo. @@ -59,7 +63,7 @@ This is why `http/base-rust.md` and `cdn/base-rust.md` can coexist — they reso ## When Adding New Examples -1. Add source entries (paired `-blueprint` and `-pattern`) to `manifest.json` +1. Add source entries (paired `-blueprint` and `-pattern` for feature examples; `-blueprint` only for base skeletons) to `manifest.json` 2. Add target_mapping entries pointing to `{appType}/{concept}-{lang}.md` paths 3. Request intent files be created in `fastedge-plugin` repo (or create via PR): - `agent-intent-skills/fastedge-sdk-rust/{appType}/{concept}-{lang}.md` (scaffold)