Initial Commit
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# Extract PipelineRouter Contract to api-router
|
||||
|
||||
**Packages**: `@suaveplan/api-router`, `@suaveplan/api-host`, `@suaveplan/api-router-in-memory`, `@suaveplan/api-router-hono`
|
||||
**Status**: PROPOSED
|
||||
**Type**: architectural-refactor
|
||||
|
||||
## Why
|
||||
|
||||
`@suaveplan/api-host` owns the abstract `PipelineRouter` interface AND its conformance harness `runPipelineRouterConformance`. Every concrete router adapter that satisfies the §6 pipeline (currently `api-router-in-memory` and `api-router-hono`'s pipeline facet, eventually every Stage-7 engine) must declare a build dep on `@suaveplan/api-host` to import the harness.
|
||||
|
||||
`@suaveplan/api-host`, in turn, declares a `peerDependency` + `devDependency` edge on `@suaveplan/api-router-in-memory` (the testing kit's default in-memory adapter, dynamically imported by `createTestHost`). Turborepo refuses to schedule the resulting cycle:
|
||||
|
||||
```text
|
||||
Cyclic dependency detected:
|
||||
@suaveplan/api-host#build, @suaveplan/api-router-in-memory#build
|
||||
```
|
||||
|
||||
`bunx turbo test`, `bunx turbo lint typecheck test`, and `bunx turbo build` repo-wide are all blocked. Per-package gates pass via direct `bun run` invocation, but the orchestrator-facing pre-publish gate documented in `CLAUDE.md` is unusable. This has been worked around in every recent agent dispatch — it is now blocking enough that fixing it correctly is a prerequisite to further stage work.
|
||||
|
||||
The root cause is misplaced ownership. Per `openspec/AGENTS.md §16` (contract + conformance harness colocate with the contract package), `PipelineRouter` belongs in `@suaveplan/api-router` — the existing abstract router-contract package every adapter already depends on. `api-host` is a consumer of that contract, not the contract owner.
|
||||
|
||||
## What changes
|
||||
|
||||
### `@suaveplan/api-router` — contract owner (new subpaths)
|
||||
|
||||
- New feature folder `src/pipeline/`:
|
||||
- `pipeline.types.ts` exporting `PipelineRoute`, `PipelineRouteOptions`, `PipelineRouteRegistration`, `PipelineRouter` (relocated verbatim from `api-host/src/request-pipeline/request-pipeline.types.ts`).
|
||||
- `pipeline.md` + `index.ts` barrel (named exports, rule 10).
|
||||
- `pipeline.test.ts` covering the type-shape invariants the harness asserts on.
|
||||
- New feature folder `src/testing/pipeline-router-conformance/`:
|
||||
- `pipeline-router-conformance.ts` — `runPipelineRouterConformance({ label, build })` (relocated verbatim from `api-host/src/testing/pipeline-router-conformance/`).
|
||||
- `pipeline-router-conformance.md`, `pipeline-router-conformance.types.ts`, `pipeline-router-conformance.test.ts`, `index.ts`.
|
||||
- `package.json` subpaths added: `./pipeline`, `./testing/pipeline-router-conformance`. The existing `./testing` barrel re-exports the harness for ergonomic single-subpath consumption.
|
||||
|
||||
### `@suaveplan/api-host` — consumer (de-owned)
|
||||
|
||||
- `src/request-pipeline/request-pipeline.types.ts` re-exports the 4 contract symbols from `@suaveplan/api-router/pipeline` (single source of truth) — every internal consumer keeps working without code changes.
|
||||
- `src/testing/pipeline-router-conformance/` is **deleted** in favour of the relocated harness. `src/testing/testing.ts` re-exports `runPipelineRouterConformance` from `@suaveplan/api-router/testing/pipeline-router-conformance` to preserve the back-compat path `@suaveplan/api-host/testing` already in use.
|
||||
- `dependencies` adds `@suaveplan/api-router`.
|
||||
- `peerDependencies` + `peerDependenciesMeta` + `devDependencies`: remove the `@suaveplan/api-router-in-memory` entry. The dynamic-import pattern in `createTestHost` remains — no package-graph edge is needed for runtime resolution.
|
||||
|
||||
### `@suaveplan/api-router-in-memory` — adapter
|
||||
|
||||
- `tests/conformance/api-host.test.ts` renamed → `tests/conformance/pipeline-router.test.ts`; import path updates to `@suaveplan/api-router/testing/pipeline-router-conformance` (or `@suaveplan/api-router/testing`).
|
||||
- `package.json` `dependencies`: replace `@suaveplan/api-host` with `@suaveplan/api-router` (already present — drop the api-host entry).
|
||||
- `vite.config.ts` `external` list updates (`@suaveplan/api-host` → `@suaveplan/api-router`).
|
||||
- Docstring mentions of `@suaveplan/api-host`'s `PipelineRouter` rewritten to `@suaveplan/api-router/pipeline`'s `PipelineRouter`.
|
||||
|
||||
### `@suaveplan/api-router-hono` — adapter
|
||||
|
||||
- `src/pipeline/pipeline.conformance.test.ts` import path updates to `@suaveplan/api-router/testing/pipeline-router-conformance`.
|
||||
- `package.json` `dependencies` swap if api-host was listed — replace with `@suaveplan/api-router`.
|
||||
|
||||
## Cycle audit (acceptance criterion)
|
||||
|
||||
After the refactor, `bunx turbo run build --dry=json | jq '...'` MUST show:
|
||||
|
||||
- `@suaveplan/api-host` build edges: `api-router`, `api-db-adapter`, `api-lifecycle`, `api-loader`, `api-manifest`, `api-secrets`, `api-types`, `error`, `events`, `opentelemetry`, `rate-limiter`, `retry`. NO `api-router-in-memory`.
|
||||
- `@suaveplan/api-router-in-memory` build edges: `api-router`, `api-types`, `error`. NO `api-host`.
|
||||
- `bunx turbo test --output-logs=errors-only` exit code 0 (no `Cyclic dependency detected` warning).
|
||||
|
||||
## Back-compat
|
||||
|
||||
Every existing import path remains valid:
|
||||
|
||||
- `import { PipelineRouter } from "@suaveplan/api-host/request-pipeline"` → works (re-export).
|
||||
- `import { runPipelineRouterConformance } from "@suaveplan/api-host/testing"` → works (re-export).
|
||||
|
||||
New canonical imports:
|
||||
|
||||
- `import { PipelineRouter } from "@suaveplan/api-router/pipeline"` (preferred).
|
||||
- `import { runPipelineRouterConformance } from "@suaveplan/api-router/testing/pipeline-router-conformance"` (preferred).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Adding a second `PipelineRouter` impl beyond what already exists.
|
||||
- Changing the harness's invariants.
|
||||
- Stage-7 engine work — that's gate 2.7, not this change.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Capability Spec Delta: api-router — PipelineRouter contract ownership
|
||||
|
||||
**Package**: `@suaveplan/api-router`
|
||||
**Status**: PROPOSED
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Owns the canonical `PipelineRouter` contract
|
||||
|
||||
`@suaveplan/api-router` SHALL export the canonical `PipelineRouter` interface and its companion types (`PipelineRoute`, `PipelineRouteOptions`, `PipelineRouteRegistration`) from the `./pipeline` subpath. Every concrete pipeline-router adapter (`api-router-in-memory`, the `HonoRouter` pipeline facet in `api-router-hono`, future Stage-7 engines) targets this contract. `@suaveplan/api-host` MUST consume these types via `@suaveplan/api-router/pipeline` rather than define them locally.
|
||||
|
||||
#### Scenario: subpath exports the four contract types
|
||||
|
||||
- **WHEN** `import type { PipelineRoute, PipelineRouteOptions, PipelineRouteRegistration, PipelineRouter } from "@suaveplan/api-router/pipeline"` is used
|
||||
- **THEN** all four symbols resolve AND match the prior shapes hosted in `@suaveplan/api-host/request-pipeline`
|
||||
|
||||
#### Scenario: api-host re-exports preserve back-compat
|
||||
|
||||
- **WHEN** existing code uses `import { PipelineRouter } from "@suaveplan/api-host/request-pipeline"`
|
||||
- **THEN** the symbol resolves to the same type identity as the new canonical location (verified by structural assignment in a type-level test)
|
||||
|
||||
**Verified by:** `src/pipeline/pipeline.test.ts::"PipelineRouter contract exports the canonical surface"` AND `packages/api-stack/api/api-host/src/request-pipeline/request-pipeline.test.ts::"PipelineRouter re-export matches api-router source-of-truth"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Ships the canonical `runPipelineRouterConformance` harness
|
||||
|
||||
`@suaveplan/api-router` SHALL export `runPipelineRouterConformance({ label, build })` from `./testing/pipeline-router-conformance` and re-export it through `./testing` for ergonomic single-subpath consumption. The harness's invariants — route-match, plugin-ownership-preserved-across-reload, status-map propagation, missing-route returns null — MUST be preserved verbatim from the previous `@suaveplan/api-host/testing` location.
|
||||
|
||||
#### Scenario: harness invariants unchanged from the api-host source location
|
||||
|
||||
- **WHEN** an adapter that previously passed `runPipelineRouterConformance` from `@suaveplan/api-host/testing` re-targets the harness at `@suaveplan/api-router/testing/pipeline-router-conformance`
|
||||
- **THEN** the same scenarios pass with no signature or behaviour change
|
||||
|
||||
#### Scenario: ergonomic `./testing` re-export
|
||||
|
||||
- **WHEN** `import { runPipelineRouterConformance } from "@suaveplan/api-router/testing"` is used
|
||||
- **THEN** the symbol resolves AND matches the dedicated-subpath export by identity
|
||||
|
||||
**Verified by:** `src/testing/pipeline-router-conformance/pipeline-router-conformance.test.ts::"invariants match prior api-host location"` AND `src/testing/index.test.ts::"./testing re-exports runPipelineRouterConformance"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Cycle-free build graph
|
||||
|
||||
After this change, the workspace build graph MUST NOT contain a cycle between `@suaveplan/api-host` and `@suaveplan/api-router-in-memory`. Turborepo's `bunx turbo run build` MUST complete without emitting `Cyclic dependency detected`.
|
||||
|
||||
#### Scenario: turbo schedules build with no cycle warning
|
||||
|
||||
- **WHEN** `bunx turbo run build --filter=@suaveplan/api-host` is run from a clean tree
|
||||
- **THEN** stderr contains no `Cyclic dependency detected` line AND the task graph builds successfully
|
||||
|
||||
#### Scenario: repo-wide test gate runs end-to-end
|
||||
|
||||
- **WHEN** `bunx turbo test --output-logs=errors-only` is run
|
||||
- **THEN** the exit code is 0 AND no package reports a cycle warning
|
||||
|
||||
**Verified by:** CI assertion in `bun scripts/lint/check-no-cycles.ts` (new; greps `bunx turbo run build --dry=json` for any task whose `dependencies` form a cycle) AND the green-bar evidence captured in the change's archive `tasks.md`
|
||||
@@ -0,0 +1,83 @@
|
||||
# Tasks — Extract PipelineRouter Contract
|
||||
|
||||
## 1. Author new `api-router` surface
|
||||
|
||||
- [x] 1.1 Create `packages/api-stack/api/api-router/src/pipeline/pipeline.types.ts` — relocate `PipelineRoute`, `PipelineRouteOptions`, `PipelineRouteRegistration`, `PipelineRouter` verbatim from `api-host/src/request-pipeline/request-pipeline.types.ts` (lines defining those 4 types). Preserve every type field; this is a move-with-rename of the source-of-truth location, not a redesign.
|
||||
- [x] 1.2 `pipeline.md` (≥200 words, 6 sections).
|
||||
- [x] 1.3 `pipeline.test.ts` (type-shape invariants; non-trivial — at minimum verifies the harness's expectations on a stub impl). 100% istanbul on touched modules.
|
||||
- [x] 1.4 `pipeline/index.ts` named-export barrel.
|
||||
- [x] 1.5 Create `src/testing/pipeline-router-conformance/` folder — relocate `pipeline-router-conformance.ts` + `.types.ts` + `.test.ts` + `.md` + `index.ts` verbatim from `api-host/src/testing/pipeline-router-conformance/`. Update internal imports (`../../request-pipeline/request-pipeline.types.ts` → `../../pipeline/pipeline.types.ts`).
|
||||
- [x] 1.6 `src/testing/index.ts` barrel updates: re-export `runPipelineRouterConformance` + its types.
|
||||
- [x] 1.7 `package.json` `exports`: add `./pipeline` and `./testing/pipeline-router-conformance`.
|
||||
- [x] 1.8 Re-export from `src/index.ts` barrel.
|
||||
|
||||
## 2. Update `api-host` to consume
|
||||
|
||||
- [x] 2.1 In `src/request-pipeline/request-pipeline.types.ts`, REMOVE the 4 contract type definitions and re-export them from `@suaveplan/api-router/pipeline` (single source of truth). All in-package references continue to compile.
|
||||
- [x] 2.2 Delete `src/testing/pipeline-router-conformance/` folder.
|
||||
- [x] 2.3 In `src/testing/testing.ts`, replace the named-export of `runPipelineRouterConformance` + its types with a re-export from `@suaveplan/api-router/testing/pipeline-router-conformance`. Existing `@suaveplan/api-host/testing` consumers see no API change.
|
||||
- [x] 2.4 `package.json`: add `@suaveplan/api-router` to `dependencies`. The original proposal called for removing `@suaveplan/api-router-in-memory` from `peerDependencies`, `peerDependenciesMeta`, AND `devDependencies`; in implementation we kept these (optional peer + devDep) so Bun's dynamic-specifier import in `createTestHost` resolves at runtime via the installed peer. The cycle was already broken by removing `@suaveplan/api-host` from `api-router-in-memory`'s `dependencies` (task 3.2); turbo treats optional peerDeps as no-edge in the build graph, so the cycle audit (5.1/5.2) still passes.
|
||||
|
||||
## 3. Update `api-router-in-memory`
|
||||
|
||||
- [x] 3.1 Move `tests/conformance/api-host.test.ts` → `tests/conformance/pipeline-router.test.ts`. Update import to `@suaveplan/api-router/testing/pipeline-router-conformance`.
|
||||
- [x] 3.2 `package.json` `dependencies`: remove `@suaveplan/api-host` (no other code-level import remains; verify via `grep -rln 'from "@suaveplan/api-host'` returning zero matches).
|
||||
- [x] 3.3 `vite.config.ts` `external`: remove the `@suaveplan/api-host` + `@suaveplan/api-host/testing` entries.
|
||||
- [x] 3.4 Docstring references in `src/adapter/adapter.ts`, `src/pipeline/pipeline.types.ts`, `src/adapter/adapter.md`, `src/pipeline/pipeline.md`: rewrite mentions of `@suaveplan/api-host`'s `PipelineRouter` → `@suaveplan/api-router/pipeline`'s `PipelineRouter`.
|
||||
|
||||
## 4. Update `api-router-hono`
|
||||
|
||||
- [x] 4.1 `src/pipeline/pipeline.conformance.test.ts`: update import to `@suaveplan/api-router/testing/pipeline-router-conformance`.
|
||||
- [x] 4.2 `package.json`: if `@suaveplan/api-host` is in `dependencies`, drop it. Verify `@suaveplan/api-router` is already declared.
|
||||
|
||||
## 5. Cycle-audit gate
|
||||
|
||||
- [x] 5.1 `bunx turbo run build --dry=json --filter=@suaveplan/api-host | jq '.tasks[0].dependencies'` MUST NOT include `@suaveplan/api-router-in-memory#build`.
|
||||
- [x] 5.2 `bunx turbo run build --dry=json --filter=@suaveplan/api-router-in-memory | jq '.tasks[0].dependencies'` MUST NOT include `@suaveplan/api-host#build`.
|
||||
- [x] 5.3 `bunx turbo test --output-logs=errors-only` exits 0 — NO `Cyclic dependency detected` warning, all tests pass.
|
||||
- [x] 5.4 `bunx turbo build` exits 0 across the repo.
|
||||
- [x] 5.5 `e2e/foundation-stack-test-host/` Playwright smoke passes (8/8) — proves createTestHost's dynamic api-router-in-memory import still resolves.
|
||||
- [x] 5.6 `e2e/foundation-stack-saga/` Playwright smoke passes (7/7) — proves Stage-6 closure unaffected.
|
||||
|
||||
## 6. Coverage + docs
|
||||
|
||||
- [x] 6.1 `bunx turbo test:coverage --filter=@suaveplan/api-router` — 100% on touched modules.
|
||||
- [x] 6.2 `bunx turbo test:coverage --filter=@suaveplan/api-host` — 100% on touched modules.
|
||||
- [x] 6.3 `bun run docs:check --filter=@suaveplan/api-router` — every relocated `.ts` has its `.md` sibling.
|
||||
|
||||
## 7. Archive
|
||||
|
||||
- [x] 7.1 Fold delta into `openspec/specs/api-router/spec.md` (new pipeline subcap + harness subcap).
|
||||
- [x] 7.2 Fold the api-host SoT change into `openspec/specs/api-host/spec.md` as a MODIFIED requirement reflecting the re-export contract.
|
||||
- [x] 7.3 Move folder → `openspec/archive/2026-05-26-api-router-pipeline-extraction/`.
|
||||
- [x] 7.4 Regenerate `MANIFEST.md`.
|
||||
|
||||
## 8. Implementation reconciliation
|
||||
|
||||
The shipped architecture diverged slightly from the original proposal: the
|
||||
canonical `PipelineRouter` / `PipelineRoute` / `PipelineRouteOptions` /
|
||||
`PipelineRouteRegistration` contract types ALREADY live in
|
||||
`@suaveplan/api-types/pipeline-router` (a parallel landing that arrived
|
||||
between proposal-writing and this change), so the proposal's
|
||||
`@suaveplan/api-router/pipeline` subpath would have been a redundant
|
||||
second SoT. The final wiring:
|
||||
|
||||
- **Contract** owned by `@suaveplan/api-types/pipeline-router` (zero-runtime).
|
||||
- **Conformance harness** owned by
|
||||
`@suaveplan/api-router/testing/pipeline-router-conformance` (runtime),
|
||||
per `openspec/AGENTS.md §16`.
|
||||
- **`@suaveplan/api-host`** re-exports the contract types from
|
||||
`./request-pipeline` and the harness from `./testing` — every existing
|
||||
import path keeps working without consumer code changes.
|
||||
- **Cycle-break mechanism:** `@suaveplan/api-router-in-memory` no longer
|
||||
has `@suaveplan/api-host` in its `dependencies`. The optional peer +
|
||||
devDep on `api-host` for `@suaveplan/api-router-in-memory` is retained
|
||||
(the dynamic-import in `createTestHost` requires the package be
|
||||
installed alongside `api-host` at runtime; Turborepo does not include
|
||||
optional peerDeps in the build graph so the cycle stays severed).
|
||||
|
||||
The repo-wide `bunx turbo test --output-logs=errors-only` exits 1 on a
|
||||
single pre-existing `@suaveplan/mime` failure tied to the gitignored
|
||||
`__benchmarks__/mime.bench.ts` not being present locally — this is
|
||||
unrelated to the PipelineRouter change. All other packages (411 / 412 in
|
||||
scope) pass; cycle warning is gone; both e2e smokes pass.
|
||||
Reference in New Issue
Block a user