72 lines
5.1 KiB
Markdown
72 lines
5.1 KiB
Markdown
# Tasks — `@suaveplan/api-manifest`
|
|
|
|
> Every checkbox MUST reflect work actually done in this change.
|
|
|
|
## 0. Pre-flight (non-negotiable)
|
|
|
|
- [x] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
|
- [x] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
|
- [x] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
|
|
|
## 1. Spec authoring
|
|
|
|
- [x] 1.1 Read design doc §3 (manifest schema), §4 (lifecycle reinstall criteria), §5.2 (capability resolution), §8.1a (manifest hash)
|
|
- [x] 1.2 Read `openspec/specs/api-manifest/spec.md` (does not exist yet — net-new)
|
|
- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
|
|
- [x] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
|
|
- [x] 1.5 Source-mapping table — every requirement cites a design-doc section
|
|
- [x] 1.6 Draft `specs/api-manifest/spec.md` from `openspec/templates/spec-delta.md`
|
|
- [x] 1.7 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles
|
|
|
|
## 2. Implementation
|
|
|
|
- [x] 2.1 Scaffold `packages/api/api-manifest/` (`"version": "0.1.0"`, `"sideEffects": false`, deps: `@suaveplan/api-types` workspace, `@suaveplan/error` workspace, `zod` catalog, `@suaveplan/types` workspace)
|
|
- [x] 2.2 `src/schema/` — one file per top-level manifest key (`identity.ts`, `compat.ts`, `isolation.ts`, `permissions.ts`, `dependsOn.ts`, `routes.ts`, `graphql.ts`, `websockets.ts`, `sse.ts`, `sagas.ts`, `twoPhaseCommit.ts`, `database.ts`, `jobs.ts`, `events.ts`, `secrets.ts`, `config.ts`, `scopes.ts`, `telemetry.ts`, `openapi.ts`, `errors.ts`, `uninstall.ts`); composite `plugin-manifest.ts` joining them. Always `import z from "zod"`.
|
|
- [x] 2.3 `src/parse/` — `parseManifest`, `parseManifestSafe`
|
|
- [x] 2.4 `src/validators/` — `validate-saga-ownership`, `validate-permissions-when-sandboxed`, `validate-openapi-requires-graphql-or-routes`, `validate-error-status-map-shape`
|
|
- [x] 2.5 `src/dep-graph/` — Kahn's-algorithm topological sort with cycle detection; semver-range matcher
|
|
- [x] 2.6 `src/capability-resolver/` — required vs optional resolution against a `CapabilityDescriptor[]` source
|
|
- [x] 2.7 `src/hash/` — canonical-JSON serializer + sha256 (from `@suaveplan/crypto-hash`)
|
|
- [x] 2.8 `src/error-codes/` — `MANIFEST_CODES` registry: `PARSE_FAILED`, `DEPENDENCY_CYCLE`, `MISSING_DEPENDENCY`, `DEPENDENCY_VERSION_MISMATCH`, `CAPABILITY_REQUIRED_MISSING`, `CAPABILITY_VERSION_MISMATCH`, `INVALID_SAGA_OWNERSHIP`, `SANDBOX_REQUIRES_BUDGETS`, `INVALID_ERROR_STATUS_MAP`
|
|
- [x] 2.9 `src/testing/` — `runManifestConformance(parse)` harness
|
|
- [x] 2.10 `src/index.ts` — explicit named re-exports (rule 10); namespace re-exports per subpath
|
|
- [x] 2.11 `package.json` `exports` — one subpath per category
|
|
|
|
## 3. Tests
|
|
|
|
- [x] 3.1 Schema unit tests per feature (`<feature>.test.ts`) — golden fixtures
|
|
- [x] 3.2 Spec-conformance tests (`<feature>.spec-conformance.test.ts`) — type-level + code-registry pinning
|
|
- [x] 3.3 Property tests (`fast-check`) on `dep-graph` topological sort + `hash` key-order stability
|
|
- [x] 3.4 Every `it(...)` carries `{ timeout: 5000 }`
|
|
|
|
## 4. Documentation
|
|
|
|
- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced)
|
|
- [x] 4.2 `README.md` at root linking every co-located `.md` under `## Modules`
|
|
- [x] 4.3 No CLAUDE.md update needed (covered by umbrella entry)
|
|
|
|
## 5. Pre-archive verification (the 5-gate triple)
|
|
|
|
- [x] 5.1 `bun run check` — Biome 0/0/0
|
|
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-manifest` — green
|
|
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-manifest` — 100/100/100/100
|
|
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-manifest` — exit 0
|
|
- [x] 5.5 `bunx turbo build --filter=@suaveplan/api-manifest` — green
|
|
|
|
## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
|
|
|
- [x] 6.1 Generics on `parseManifest<T extends PluginManifest>`; `expectTypeOf` on inferred Zod outputs vs `api-types` shape
|
|
- [x] 6.2 Zod schemas wired at the public boundary (`parseManifest`); every input goes through Zod
|
|
- [x] 6.3 Every `MANIFEST_CODES` entry thrown by a production path with a test asserting it
|
|
- [x] 6.4 Strict-mode behavior — Zod `.strict()` rejecting unknown top-level keys is tested both with strict on and off (per-field override)
|
|
- [x] 6.5 OTel instruments — N/A (this is a pure parser; instrumentation lives in `api-host` callers)
|
|
- [x] 6.6 Lifecycle dedup — N/A (no async lifecycle in this package)
|
|
- [x] 6.7 No retroactive tick
|
|
|
|
## 7. Archive
|
|
|
|
- [x] 7.1 Fold spec delta into `openspec/specs/api-manifest/spec.md`
|
|
- [x] 7.2 Move `openspec/changes/api-manifest/` → `openspec/archive/<yyyy-mm-dd>-api-manifest/`
|
|
- [x] 7.3 Tick `1.2` in umbrella `openspec/changes/api-plugin-foundation/tasks.md`
|
|
- [x] 7.4 Refresh `MANIFEST.md`
|