@skill-map/spec 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Spec changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- 68c5e28: Step 14.1 — `sm serve` + Hono BFF skeleton
+
+  Adds `src/server/` Hono workspace with single-port wiring (`/api/health` real,
+  `/api/*` 404 stubs, `/ws` no-op upgrade, `serveStatic` + SPA fallback). Real
+  `ServeCommand` extracted from stub at `cli/commands/stubs.ts` to dedicated
+  `cli/commands/serve.ts` extending `SmCommand`. Loopback-only through v0.6.0
+  (Decision #119). Boot resilient to missing DB — `/api/health` reports
+  `db: 'missing'`. Spec `cli-contract.md` `sm serve` row updated to full flag
+  set; new `### Server` subsection (skeleton — endpoints fill at 14.2).
+
+  **Files added (server)**
+
+  - `src/server/index.ts` — `createServer(opts)` factory returning `ServerHandle` (`{ address, close }`); resolves spec version, builds the Hono app, instantiates a `WebSocketServer({ noServer: true })`, hands both to `@hono/node-server`'s `serve({ websocket: { server: wss } })`. Closing the http server tears down the WSS automatically (node-server registers the `'close'` hook internally); `close()` calls `wss.close()` defensively for forward-compatibility.
+  - `src/server/app.ts` — Hono app construction. Routes registered in single-port order: `GET /api/health` → real, `ALL /api/*` → structured 404, `GET /ws` via the injected `attachWs` registrar, static handler + SPA fallback. Global `app.onError` formats every uncaught throw into the error envelope.
+  - `src/server/options.ts` — `IServerOptions` + `validateServerOptions(input)`. Loopback-only check for `--dev-cors`; port range check `[0, 65535]`; scope validation.
+  - `src/server/paths.ts` — `resolveDefaultUiDist(ctx)` walks upwards from cwd looking for `ui/dist/browser/index.html`; `resolveExplicitUiDist(ctx, raw)` honours absolute paths for `--ui-dist`.
+  - `src/server/static.ts` — wraps `@hono/node-server`'s `serveStatic` middleware with the SPA-fallback layer (`serveStatic` does not do SPA fallback — it `next()`s on miss, which is exactly the seam we hook into). Absolute `root` paths work on POSIX in node-server@2.0.1 (verified runtime probe — implementation is `path.join(root, filename)`); the `.d.ts` "Absolute paths are not supported" string is stale (upstream issue honojs/node-server#187 still open). When the bundle is missing (`uiDist === null`), a tiny placeholder middleware serves the boot-without-bundle hint at `/`.
+  - `src/server/ws.ts` — `noopWebSocketRoute(app)` registers `GET /ws` via the official `upgradeWebSocket` re-exported from `@hono/node-server@2.x`. The 14.1 handler closes the connection in `onOpen` with code 1000 + reason `'no broadcaster yet'`. 14.4 swaps this registrar for the chokidar-fed broadcaster — one-line change in `index.ts`, `app.ts` untouched.
+  - `src/server/health.ts` — `buildHealth(deps)` synchronous; `resolveSpecVersion()` async, called once at boot.
+  - `src/server/i18n/server.texts.ts` — `SERVER_TEXTS` catalog.
+
+  **Files added (CLI)**
+
+  - `src/cli/commands/serve.ts` — `ServeCommand extends SmCommand`. Parses flags, validates, calls `createServer`, registers SIGINT/SIGTERM handlers, awaits shutdown. `protected emitElapsed = false` (long-running daemon).
+  - `src/cli/i18n/serve.texts.ts` — `SERVE_TEXTS` catalog.
+
+  **Tests added (15)**
+
+  - `src/test/server-boot.test.ts` (7) — boot/listen/health JSON, custom port, db state present/missing, structured 404, /ws upgrade closes with code 1000 + reason 'no broadcaster yet' (uses real `WebSocket` client from `ws`), shutdown < 1s + idempotent close, inline placeholder when uiDist null.
+  - `src/test/server-flags.test.ts` (6) — host non-loopback + dev-cors rejection, port out-of-range, port non-numeric, scope invalid, ui-dist missing, ui-dist with valid bundle.
+  - `src/test/server-db-missing.test.ts` (2) — `--db <missing>` exits 5, default boots cleanly with db:missing.
+
+  **Files edited**
+
+  - `src/cli/commands/stubs.ts` — `ServeCommand` removed; replaced with a comment pointer.
+  - `src/cli/entry.ts` — registers the new `ServeCommand`.
+  - `src/package.json` — adds `hono@4.12.16`, `@hono/node-server@2.0.1`, `ws@8.20.0` (deps); `@types/ws@8.18.1` (dev). All exact-pinned per AGENTS.md.
+  - `spec/cli-contract.md` — `sm serve` row replaced with the full 14.1 flag set; new `#### Server` subsection (stability: experimental).
+  - `spec/CHANGELOG.md` — `[Unreleased]` `### Minor` entry for the spec change.
+  - `spec/index.json` — regenerated (40 files hashed; previous head was 215 lines).
+
+  **Decisions during implementation (flag for orchestrator)**
+
+  - WebSocket support uses `@hono/node-server@2.x`'s built-in `upgradeWebSocket` plus the canonical `ws@8.20.0` Node WebSocket library, per the official README pattern. The previously-published `@hono/node-ws` adapter was deprecated when node-server@2.0 absorbed WebSocket support natively (PR honojs/node-server#328). The 14.4 broadcaster will replace `noopWebSocketRoute` with its own one-line registrar — no API churn between 14.1 and 14.4.
+  - The `/api/*` catch-all is wired with `app.all('/api/*', ...)` BEFORE the `/ws` registrar and the static handler so neither a `serveStatic` filesystem hit nor the SPA fallback can shadow API endpoints. `/ws` is registered BEFORE the static handler so a literal `/ws` path on disk inside `uiDist` cannot accidentally shadow the upgrade route.
+  - `serveStatic` from `@hono/node-server/serve-static` accepts absolute root paths at runtime on POSIX (its implementation is `path.join(root, filename)`); the `.d.ts` string saying otherwise is documentation drift, not a runtime contract. Verified with a runtime probe and cross-referenced against the open upstream issue (honojs/node-server#187). Documented in `src/server/static.ts` so future contributors don't re-investigate.
+
 ## 0.11.0
 
 ### Minor Changes
@@ -172,6 +223,25 @@ list`, `sm plugins doctor`, `sm db prune` plugin filter, runtime
 
 ## [Unreleased]
 
+### Minor
+
+- **`sm serve` row + `### Server` subsection** in `cli-contract.md` —
+  Step 14.1 promotes `sm serve` from an implementation-defined stub to a
+  documented surface. The verb row at `§Verb catalog` › `### Server`
+  expands the flag set to the full 14.1 contract: `--port` (default
+  `4242`), `--host` (default `127.0.0.1`, loopback-only through v0.6.0),
+  `--scope project|global`, `--db <path>`, `--no-built-ins`,
+  `--no-plugins`, `--open` / `--no-open`, `--dev-cors`, `--ui-dist
+<path>` (hidden). New `#### Server` subsection documents the
+  single-port mandate, the boot-with-missing-DB resilience contract
+  (`/api/health` returns `db: 'missing'`), the v14.1 endpoint surface
+  (`GET /api/health` real, `ALL /api/*` 404 stubs, `GET /ws` upgrade-only,
+  static + SPA fallback), the structured error envelope shape, and the
+  flag table. Marked `*(Stability: experimental — locks at v0.6.0.)*` —
+  endpoints fill at v14.2, broadcaster at v14.4. Additive minor per
+  `versioning.md` § Pre-1.0 (no breaking change to the existing row's
+  semantics; the old wording was strictly less specific).
+
 ### Minor (breaking, pre-1.0)
 
 - **`Node.kind` opens to any non-empty string (was the closed enum
@@ -1159,9 +1229,9 @@ kind, normalizedTrigger)` and prints one row per group with the
       (`Links out (12, 9 unique)`). When N > 1 detector emits the same
       logical link, the row also gets a `(×N)` suffix.
 
-                                   `--json` output is byte-identical to before — raw rows, no merge.
-                                   Storage is byte-identical to before. The grouping is purely a
-                                   read-time presentation choice for human eyes.
+                                         `--json` output is byte-identical to before — raw rows, no merge.
+                                         Storage is byte-identical to before. The grouping is purely a
+                                         read-time presentation choice for human eyes.
 
   **Spec changes (patch)**:
 

package/cli-contract.md

@@ -316,7 +316,55 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 
 | Command | Purpose |
 |---|---|
-| `sm serve [--port N] [--host ...] [--no-open]` | Start Hono + WebSocket for the Web UI. Default port is implementation-defined but MUST be the same across runs. Implementations MUST NOT bind 0.0.0.0 by default. |
+| `sm serve [--port N] [--host ...] [--scope project\|global] [--db <path>] [--no-built-ins] [--no-plugins] [--open\|--no-open] [--dev-cors] [--ui-dist <path>]` | Start Hono + WebSocket for the Web UI. Single-port mandate: SPA + REST + WS under one listener. Default port 4242, default host 127.0.0.1 (loopback-only through v0.6.0; multi-host deferred — see §Server). |
+
+#### Server
+
+*(Stability: experimental — locks at v0.6.0.)*
+
+The reference implementation ships a Hono BFF rooted at `src/server/`. One Node process serves the Angular SPA, the REST API under `/api/*`, and the WebSocket at `/ws` — single-port mandate, no proxy. Loopback-only assumption through v0.6.0: no per-connection auth on `/ws`; combining `--dev-cors` with a non-loopback `--host` is rejected (exit 2).
+
+**Boot resilience**: `sm serve` boots even when the project DB is missing. `/api/health` reports `db: 'missing'` so the SPA can render an empty-state CTA instead of failing the connection. Explicit `--db <path>` that doesn't exist is the exception — that exits 5 (NotFound) per `§Exit codes`.
+
+**Endpoints (v14.1 surface)**:
+
+| Path | Status | Shape |
+|---|---|---|
+| `GET /api/health` | implemented | `{ ok: true, schemaVersion, specVersion, implVersion, scope: 'project'\|'global', db: 'present'\|'missing' }` |
+| `ALL /api/*` (other) | reserved | structured 404 envelope (see below); real endpoints land at v14.2 |
+| `GET /ws` | upgrade-only | accepts WebSocket upgrade and immediately closes; broadcaster lands at v14.4 |
+| `GET *` | implemented | static asset from the resolved UI bundle, falling back to `index.html` for SPA deep links |
+
+**Error envelope** (mirrors `§Machine-readable output rules`):
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "not-found" | "bad-query" | "db-missing" | "internal",
+    "message": "<human-readable>",
+    "details": { ... } | null
+  }
+}
+```
+
+HTTP status mapping: `400` → `bad-query`, `404` → `not-found`, `500` → `internal` / `db-missing`.
+
+**Flag surface**:
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--port N` | `4242` | Listening port. `0` = OS-assigned (handle reports the bound port). |
+| `--host <ip>` | `127.0.0.1` | Listening host. Implementations MUST NOT bind `0.0.0.0` by default. |
+| `--scope project\|global` | `project` | Effective scope for `/api/*` reads. Alias for `-g/--global`. |
+| `--db <path>` | resolved per spec § Global flags | Override the DB file location. Missing explicit `--db` exits 5. |
+| `--no-built-ins` | off | Skip built-in plugin registration (parity with `sm scan --no-built-ins`). |
+| `--no-plugins` | off | Skip drop-in plugin discovery. |
+| `--open` / `--no-open` | `--open` | Auto-open the SPA in the user's default browser after listen. |
+| `--dev-cors` | off | Enable permissive CORS for the Angular dev-server proxy workflow. Loopback-only when set. |
+| `--ui-dist <path>` | auto | Override the UI bundle directory. Hidden flag — used by the demo build pipeline + tests; everyday users never need it. |
+
+**Graceful shutdown**: SIGINT / SIGTERM trigger a graceful close; the verb returns exit 0 on clean shutdown. Bind failure (port in use, EACCES) returns exit 2.
 
 ---
 

package/index.json

@@ -166,14 +166,14 @@
       }
     ]
   },
-  "specPackageVersion": "0.11.0",
+  "specPackageVersion": "0.12.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "11a95c44a9dd97180d2e281ba652b53e530020c592763113874a8c8bbd65ece8",
+      "CHANGELOG.md": "c85703fa37d3c084e2251c0b77626c94fa5c6897289c1534432ae45ac168762b",
       "README.md": "bd30780525e75379eaeb5f8a903bdc601daf3862f3ec69dffc96c437e8d476fc",
       "architecture.md": "9a6d96d150af60ed8d476af572d07dcce605f116fde720bebb2662b11250bf4b",
-      "cli-contract.md": "62a0f89f4da6207499b26c4ca8e35f3d59054a7521834698e5007f697b514af2",
+      "cli-contract.md": "89dcd366624821c1ab77d1014229b4c209953f337d0c62d16b24472c64c3bad4",
       "conformance/README.md": "838b1247e1ffb402d96bd8a0fe9c1c0f4a99ed0fbc4bf8156f7a58330cac27f5",
       "conformance/cases/kernel-empty-boot.json": "ad4bbe9d637537625025c8bdb61285b1433568a2544b1ce0248f304ccff8c350",
       "conformance/coverage.md": "4df23b78ec44887dc355e0622b9008bb2514f3b8e9c302db18eb51532fda5275",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",