diff --git a/context/CONTEXT_INDEX.md b/context/CONTEXT_INDEX.md index eed715f..8b0cab8 100644 --- a/context/CONTEXT_INDEX.md +++ b/context/CONTEXT_INDEX.md @@ -36,6 +36,13 @@ |----------|-------|---------| | `PROJECT_OVERVIEW.md` | ~150 | Lightweight project overview — architecture, key modules, dev setup, common commands. Read when new to the codebase. | | `CHANGELOG.md` | ~25+ | Change history. Use grep, don't read linearly as this file grows. | +| `ENHANCEMENTS.md` | ~50 | Known inconsistencies and planned improvements. Read before refactoring related areas. | + +### 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/) @@ -83,6 +90,7 @@ 4. **Every example MUST have its own `README.md`** explaining what it does 5. **Every example MUST have an entry in `examples/README.md`** (the top-level index) 6. **Terminology**: In READMEs, always refer to "environment variables" — never "dictionary variables". `dictionary` is the internal package name for accessing environment variables, not a user-facing concept +7. **Plugin sync**: If this example should feed into fastedge-plugin, read `context/PLUGIN_CONTRACT.md` for manifest and naming conventions ### Changing the Build System 1. Read `development/BUILD_SYSTEM.md` diff --git a/context/ENHANCEMENTS.md b/context/ENHANCEMENTS.md new file mode 100644 index 0000000..de91a0c --- /dev/null +++ b/context/ENHANCEMENTS.md @@ -0,0 +1,53 @@ +# Enhancements & Known Issues + +Tracked improvements that don't warrant external issues. Check items off or remove them as they're resolved. + +--- + +## Config Schema: `ignoreDirs` vs `ignorePaths` inconsistency + +**Status:** Open +**Identified:** 2026-04-08 (during plugin reference doc review) +**Affects:** `fastedge-init` scaffolder, `fastedge-build` static pipeline + +### Problem + +The init wizard (`src/cli/fastedge-init/create-config.ts`) generates static build configs using `ignoreDirs`: + +```js +// What fastedge-init writes to .fastedge/build-config.js +{ + type: "static", + ignoreDirs: ["./node_modules"] +} +``` + +But the formal `AssetCacheConfig` type (`src/server/static-assets/asset-manifest/types.ts`) defines `ignorePaths` and `assetManifestPath`: + +```ts +interface AssetCacheConfig { + assetManifestPath: string; + ignorePaths: string[]; + // ... +} +``` + +The build pipeline silently accepts both — `create-manifest-file-map.ts` merges `ignoreDirs` and `ignorePaths` into one array. But this means: + +1. Configs generated by `fastedge-init` use a field name (`ignoreDirs`) not present in the formal type +2. `assetManifestPath` is required in `AssetCacheConfig` but never emitted by `fastedge-init` +3. Docs for each tool are accurate to their respective source, but contradict each other + +### Suggested Fix + +Either: +- **Option A:** Update `create-config.ts` to emit `ignorePaths` + `assetManifestPath` (align init output with the formal type) +- **Option B:** Add `ignoreDirs` as an explicit field in `AssetCacheConfig` and make `assetManifestPath` optional + +Option A is cleaner — one canonical field name, init output matches the type system. + +### Files Involved + +- `src/cli/fastedge-init/create-config.ts` — generates the config (uses `ignoreDirs`) +- `src/server/static-assets/asset-manifest/types.ts` — defines `AssetCacheConfig` (uses `ignorePaths`) +- `src/server/static-assets/asset-manifest/create-manifest-file-map.ts` — consumes both (merges them) diff --git a/context/PLUGIN_CONTRACT.md b/context/PLUGIN_CONTRACT.md new file mode 100644 index 0000000..6d76c3e --- /dev/null +++ b/context/PLUGIN_CONTRACT.md @@ -0,0 +1,60 @@ +# 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-ts.md # Base skeleton + kv-store-ts.md # Feature blueprint + cdn/ # CDN app blueprints (future) + build-cli.md # Cross-cutting (no subfolder) + fastedge-docs/reference/ + http/ # HTTP app example patterns + examples-kv-store-js.md + cdn/ # CDN app example patterns (future) + sdk-reference-js.md # Cross-cutting (no subfolder) +``` + +## 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-ts.md` | +| Feature blueprint | `{appType}/{concept}-{lang}.md` | `http/kv-store-ts.md` | +| Docs pattern | `{appType}/examples-{concept}-{lang}.md` | `http/examples-kv-store-js.md` | +| Cross-cutting SDK ref | `sdk-reference-{lang}.md` | `sdk-reference-js.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/http/kv-store-ts.md` +- Path suffix: `http/kv-store-ts.md` +- Intent lookup: `agent-intent-skills/fastedge-sdk-js/http/kv-store-ts.md` + +## 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-js/{appType}/{concept}-{lang}.md` (scaffold) + - `agent-intent-skills/fastedge-sdk-js/{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 e648495..8226c75 100644 --- a/fastedge-plugin-source/manifest.json +++ b/fastedge-plugin-source/manifest.json @@ -140,7 +140,7 @@ }, "target_mapping": { "sdk-api": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference-js.md", "section": null }, "build-cli": { @@ -161,52 +161,52 @@ }, "hello-world-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/base-http-ts.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/base-ts.md", "section": null }, "kv-store-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-kv-store.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/kv-store-ts.md", "section": null }, "kv-store-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-kv-store.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-kv-store-js.md", "section": null }, "ab-testing-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-ab-testing.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/ab-testing-ts.md", "section": null }, "ab-testing-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-ab-testing.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-ab-testing-js.md", "section": null }, "fetch-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-fetch.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/fetch-ts.md", "section": null }, "fetch-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-fetch.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-fetch-js.md", "section": null }, "headers-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-headers.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/headers-ts.md", "section": null }, "headers-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-headers.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-headers-js.md", "section": null }, "geo-redirect-blueprint": { - "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-geo-redirect.md", + "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/geo-redirect-ts.md", "section": null }, "geo-redirect-pattern": { - "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-geo-redirect.md", + "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-geo-redirect-js.md", "section": null } },