From 697bc90780bb0cdb5cc66b71bdbebeefc8a6b0c5 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 19:45:11 +0200 Subject: [PATCH] Implement CENG-WP-0002: package distribution and publish readiness Resolve ADR-0002 in umbrella, add install docs, contract sync runbook, publishing checklist, and package files whitelist. --- INTENT.md | 4 +- README.md | 80 +++++++++++++++++-- package.json | 6 ++ wiki/README.md | 22 +++++ .../CENG-WP-0002-package-distribution.md | 12 +-- 5 files changed, 110 insertions(+), 14 deletions(-) create mode 100644 wiki/README.md diff --git a/INTENT.md b/INTENT.md index abe2f1c..dc19cc8 100644 --- a/INTENT.md +++ b/INTENT.md @@ -324,8 +324,8 @@ The umbrella-first MVP (CE-WP-0001..0008) stabilized the engine API. Code now lives in this repository under `src/shared/` and `src/engine/`, extracted from `citation-evidence` per `workplans/CENG-WP-0001-intent-placeholder.md`. -The umbrella repo still carries a copy during the transition to a workspace -dependency. This repository is the canonical home going forward. +The umbrella consumes this package via `link:../citation-engine` per `CE-WP-0009`. +This repository is the canonical home going forward. **Shared contracts** (vocabulary, state enums, relation types, selector taxonomy, event types, viewer adapter, canonical text normalization, allowed diff --git a/README.md b/README.md index 6647940..d54e491 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ This package provides the shared vocabulary (`Document`, `Selector`, `Annotation canonical text normalization) together with in-memory repositories, orchestration services, the event bus, and citation card renderers. +Published as **`@citation-evidence/engine`**. + ## Layout ``` @@ -14,9 +16,58 @@ src/ shared/ # types, enums, pure helpers engine/ # services, repositories, rendering, persistence wiki/ - SharedContracts.md # conformance reference (enum lists, normalization rules) + SharedContracts.md # conformance copy (authoritative: citation-evidence) ``` +## Installing + +### Local development (sibling checkout) + +Repos are expected as siblings: + +``` +~/citation-evidence/ +~/citation-engine/ +~/evidence-anchor/ +... +``` + +In the consumer's `package.json`: + +```json +{ + "dependencies": { + "@citation-evidence/engine": "link:../citation-engine" + } +} +``` + +Then `pnpm install`. TypeScript path aliases in consumers typically map +`@shared/*` and `@engine/*` to `../citation-engine/src/shared/*` and +`../citation-engine/src/engine/*` (see `CE-WP-0009` in citation-evidence). + +### Registry install (when published) + +```bash +pnpm add @citation-evidence/engine +``` + +Registry host TBD. See [Publishing checklist](#publishing-checklist) below. + +### evidence-anchor (placeholder) + +When `evidence-anchor` extracts, it will depend on engine types only: + +```json +{ + "dependencies": { + "@citation-evidence/engine": "link:../citation-engine" + } +} +``` + +Import shared types via `@shared/*` path aliases or `@citation-evidence/engine/shared`. + ## Development ```bash @@ -26,14 +77,31 @@ pnpm typecheck pnpm lint ``` +## Contract sync + +See [`wiki/README.md`](wiki/README.md). Changes to shared contracts land in +`citation-evidence/wiki/SharedContracts.md` first, then sync here. + ## Extraction status -Code was extracted from `citation-evidence/src/shared/` and `citation-evidence/src/engine/` -after the umbrella MVP (CE-WP-0001..0008) stabilized. The umbrella repo still carries -a copy during the transition; this repository is the canonical home going forward. +Code lives in `src/shared/` and `src/engine/`, extracted from the umbrella +MVP per `workplans/CENG-WP-0001-intent-placeholder.md`. The umbrella consumes +this package via `link:` per `CE-WP-0009`. -Contract changes belong in `citation-evidence/wiki/SharedContracts.md` first, then -sync to `wiki/SharedContracts.md` here. +## Publishing checklist + +Use when a package registry is configured (ADR-0002: independent repos + publish). + +- [ ] Set `private: false` (or scoped private per org policy) +- [ ] Confirm `files` in `package.json` includes `src/`, `wiki/`, `README.md`, `LICENSE` +- [ ] Decide: TypeScript sources via `exports` (current) vs `tsc` emit to `dist/` +- [ ] Bump semver: patch for fixes, minor for additive contracts, major for breaks +- [ ] Run `pnpm test && pnpm typecheck && pnpm lint` before publish +- [ ] Update consumers from `link:` to registry version +- [ ] Document registry URL and auth in org runbook (not in this repo) + +No publish CI step is configured yet — credentials and registry choice are +out of scope until an external consumer requires it. ## Related repos diff --git a/package.json b/package.json index 136330a..4d9c772 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,12 @@ "engines": { "node": ">=20.10.0" }, + "files": [ + "src", + "wiki", + "README.md", + "LICENSE" + ], "exports": { ".": "./src/engine/index.ts", "./shared": "./src/shared/index.ts" diff --git a/wiki/README.md b/wiki/README.md new file mode 100644 index 0000000..e85297e --- /dev/null +++ b/wiki/README.md @@ -0,0 +1,22 @@ +# Wiki — citation-engine + +## SharedContracts sync + +`SharedContracts.md` in this directory is a **conformance copy** for tests +(e.g. `evidence-link.test.ts` enum parity checks). It is not authoritative. + +**Authoritative source:** `citation-evidence/wiki/SharedContracts.md` + +### When contracts change + +1. Land the change in `citation-evidence/wiki/SharedContracts.md` (and any + runtime types in `citation-engine/src/shared/` if enums or shapes change). +2. Copy/sync to `citation-engine/wiki/SharedContracts.md`. +3. Run `pnpm test` in **both** repos. +4. Bump `@citation-evidence/engine` version if the change is breaking for + consumers. + +### Test reference path + +`src/shared/evidence-link.test.ts` reads `wiki/SharedContracts.md` relative +to `src/shared/` (`../../wiki/SharedContracts.md`). \ No newline at end of file diff --git a/workplans/CENG-WP-0002-package-distribution.md b/workplans/CENG-WP-0002-package-distribution.md index 8bddb03..0cab48d 100644 --- a/workplans/CENG-WP-0002-package-distribution.md +++ b/workplans/CENG-WP-0002-package-distribution.md @@ -4,7 +4,7 @@ type: workplan title: "Package distribution — ADR-0002, publish readiness, contract sync" domain: citation_evidence repo: citation-engine -status: active +status: done owner: codex topic_slug: citation_evidence_mvp created: "2026-06-22" @@ -41,7 +41,7 @@ T01 (resolve ADR-0002) ```task id: CENG-WP-0002-T01 -status: wait +status: done priority: critical depends_on: [] ``` @@ -66,7 +66,7 @@ consequences sections are filled. ```task id: CENG-WP-0002-T02 -status: wait +status: done priority: high depends_on: [T01] ``` @@ -98,7 +98,7 @@ sister repo placeholder (`evidence-anchor`). ```task id: CENG-WP-0002-T03 -status: wait +status: done priority: high depends_on: [T01] ``` @@ -123,7 +123,7 @@ Write a short runbook (in `citation-engine/README.md` or `wiki/README.md`): ```task id: CENG-WP-0002-T04 -status: wait +status: done priority: low depends_on: [T01, T02] ``` @@ -149,6 +149,6 @@ structurally publishable even if no publish has occurred yet. | Workplan | Role | |----------|------| | `CENG-WP-0001` | Extraction — **done** | -| `CE-WP-0009` | Umbrella consumes engine via `link:` — can start now | +| `CE-WP-0009` | Umbrella consumes engine via `link:` — **done** | | `CENG-WP-0002` | Distribution strategy and publish prep — this file | | Future `EANCH-WP-0002`, etc. | Sister-repo extractions depend on engine install story from T02 | \ No newline at end of file