feat: package the official versioned API contract #299

Merged

erik merged 1 commit from feat/task-a0aa9f9e-api-contract into main

2026-10-13 12:29:17 -05:00

erik commented

2026-10-13 12:26:22 -05:00

Owner

The API package exports the document and ships a static openapi.json plus a digest manifest mapping contract version to package version. Contract versions remain independent of package/template versions; legacy sites without a declaration stay unknown. Build and Git-history guards detect artifact drift, immutable-version reuse, and version bumps inconsistent with the reviewed change classification. CI fetches full history for these checks and retains deterministic tests only. Release helper tests now exclude integration tests as well.

Validation: ./scripts/pre-pr.sh (build, formatting, lint, types, full local tests); package dry-run; actual npm tarball extraction verifies document equality, package mapping and SHA-256 digest. Focused tests cover served identity, metadata opt-in, static artifact identity and release-policy failures.

Release order: publish slug-core 0.1.2 before slug-api 0.2.0, then publish the template artifact with its pinned dependencies. This PR does not publish packages or deploy sites. Archive hosting, slugkit.com adoption, Doctor conformance and CLI compatibility remain separate tasks.

Task: task-a0aa9f9e

Generated sites currently maintain their own OpenAPI definition and advertise only the ambiguous legacy API version. This moves the official contract into @evcraddock/slug-api: generated sites import and serve that document and explicitly advertise `slugkit-management-api` contract `1.1.0` in `/api/v1/meta`. The API package exports the document and ships a static `openapi.json` plus a digest manifest mapping contract version to package version. Contract versions remain independent of package/template versions; legacy sites without a declaration stay unknown. Build and Git-history guards detect artifact drift, immutable-version reuse, and version bumps inconsistent with the reviewed change classification. CI fetches full history for these checks and retains deterministic tests only. Release helper tests now exclude integration tests as well. Validation: `./scripts/pre-pr.sh` (build, formatting, lint, types, full local tests); package dry-run; actual npm tarball extraction verifies document equality, package mapping and SHA-256 digest. Focused tests cover served identity, metadata opt-in, static artifact identity and release-policy failures. Release order: publish slug-core 0.1.2 before slug-api 0.2.0, then publish the template artifact with its pinned dependencies. This PR does not publish packages or deploy sites. Archive hosting, slugkit.com adoption, Doctor conformance and CLI compatibility remain separate tasks. Task: task-a0aa9f9e

erik added 1 commit

2026-10-13 12:26:22 -05:00

feat: package the official versioned API contract

CI / build-lint-test (pull_request) Successful in 59s

Details

fa79cc7701

Task: #task-a0aa9f9e

erik commented

2026-10-13 12:28:42 -05:00

Author

Owner

Review update

PR: #299, open; independently reviewed head fa79cc7701 against task task-a0aa9f9e.
Summary: The authoritative OpenAPI definition moves into the API package. Generated sites directly serve its export and explicitly declare contract identity/version. Static JSON and the digest manifest provide archive-consumable release artifacts without bundling history.
Acceptance criterion 1 — met: Package exports the spec; template route imports it directly, and the former local definition is a re-export. Served-document equality is tested.
Acceptance criterion 2 — met: API metadata and OpenAPI expose identity/version. Documentation defines immutable contract versions, change classification, package/template relationships, legacy unknown contracts and adoption.
Acceptance criterion 3 — met: Focused tests cover explicit metadata adoption, served identity, static artifact equality/digest and release-policy rejection paths. Build manifest validation and Git-history checks guard drift and immutable-version reuse; semantic change classification remains an explicit reviewer responsibility.
Acceptance criterion 4 — met: Published package exports openapi.json and contract.json, including package version and SHA-256 mapping, for extraction by the separate archive publication process.
Validation evidence: Reported full local pre-PR verification passed 1232 tests; actual tarball equality/digest verification passed; Forgejo CI task #511 for this head is green. Review inspected the changes without rerunning the full suite.
Blocking issues: None.
Warnings: None.
Final verdict: approved (4/4 criteria met).
Follow-up: Await explicit human merge approval. Package publication remains ordered: slug-core 0.1.2, slug-api 0.2.0, then the template release. No merge, package publication or deployment performed by this review.

### Review update - PR: [#299](https://forge.caradoc.com/erik/slugkit/pulls/299), open; independently reviewed head fa79cc7701 against task task-a0aa9f9e. - Summary: The authoritative OpenAPI definition moves into the API package. Generated sites directly serve its export and explicitly declare contract identity/version. Static JSON and the digest manifest provide archive-consumable release artifacts without bundling history. - Acceptance criterion 1 — met: Package exports the spec; template route imports it directly, and the former local definition is a re-export. Served-document equality is tested. - Acceptance criterion 2 — met: API metadata and OpenAPI expose identity/version. Documentation defines immutable contract versions, change classification, package/template relationships, legacy unknown contracts and adoption. - Acceptance criterion 3 — met: Focused tests cover explicit metadata adoption, served identity, static artifact equality/digest and release-policy rejection paths. Build manifest validation and Git-history checks guard drift and immutable-version reuse; semantic change classification remains an explicit reviewer responsibility. - Acceptance criterion 4 — met: Published package exports openapi.json and contract.json, including package version and SHA-256 mapping, for extraction by the separate archive publication process. - Validation evidence: Reported full local pre-PR verification passed 1232 tests; actual tarball equality/digest verification passed; Forgejo CI task #511 for this head is green. Review inspected the changes without rerunning the full suite. - Blocking issues: None. - Warnings: None. - Final verdict: approved (4/4 criteria met). - Follow-up: Await explicit human merge approval. Package publication remains ordered: slug-core 0.1.2, slug-api 0.2.0, then the template release. No merge, package publication or deployment performed by this review.

erik merged commit bda8da3c77 into main

2026-10-13 12:29:17 -05:00

erik deleted branch feat/task-a0aa9f9e-api-contract

2026-10-13 12:29:17 -05:00

erik referenced this pull request from a commit

2026-10-13 12:29:19 -05:00

Merge pull request 'feat: package the official versioned API contract' (#299) from feat/task-a0aa9f9e-api-contract into main