@seanmars/tospec 0.19.0-beta.8 → 0.21.0

package/dist/core/local-server.js

@@ -1,14 +1,10 @@
 /**
  * Plumbing shared by every local web command (`dashboard`, `metrics`).
  *
- * Two of these are trust boundaries, and that is the reason this module exists
- * rather than each command carrying its own copy: `isAllowedHostHeader` is a
- * DNS-rebinding guard and `serveAsset` is a path-escape guard. A second
- * implementation of either is a hole that survives fixing the first one.
- *
- * `serveAsset` takes its root directory as an argument — the commands serve
- * different asset trees, and parameterising the directory is what lets one
- * implementation serve both.
+ * Shared rather than copied per command because several of these are trust
+ * boundaries — `isAllowedHostHeader` (DNS rebinding), `serveAsset` (path
+ * escape), `assertBindableHost` (bind policy). A second implementation of any of
+ * them is a hole that survives fixing the first.
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
@@ -21,21 +17,12 @@ const ASSET_CONTENT_TYPES = {
 };
 /**
  * Canonical form of a bind address or Host-header name, so the sets below hold
- * addresses rather than spellings.
- *
- * `::`, `::0` and `0:0:0:0:0:0:0:0` are one address, and every one of them is
- * something a user can legitimately type after `--host`. Matching spellings
- * means the next one nobody thought to list silently takes the wrong branch —
- * which is how `--allow-remote --host ::0` bound every interface and then 403'd
- * every request that arrived on one.
+ * addresses rather than spellings: `::`, `::0` and `0:0:0:0:0:0:0:0` are one
+ * address a user may type after `--host`.
  *
- * The WHATWG URL parser is the normalizer because it is the only IPv6/IPv4
- * canonicalizer already in Node's core: it collapses every spelling above to
- * `::`, and the brackets it adds back are stripped here.
- *
- * Anything that does not parse as a host is returned lowercased and otherwise
- * untouched. Every check in this module treats an unrecognized value as neither
- * loopback nor wildcard, which is the refusing side of each of them.
+ * The WHATWG URL parser is the normalizer because it is Node's only built-in
+ * IPv6/IPv4 canonicalizer. An unparseable value is returned lowercased, and
+ * every check here treats it as neither loopback nor wildcard.
  */
 export function normalizeHost(host) {
     const bare = host.trim().toLowerCase().replace(/^\[|\]$/g, '');
@@ -55,64 +42,55 @@ export function normalizeHost(host) {
  */
 export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
 /**
- * Bind addresses that mean "every interface", canonical forms only. These are
- * not names any client sends as a Host header, which is what makes them the one
- * case the literal match in `isAllowedHostHeader` can never satisfy.
- *
- * `::ffff:0:0` is the IPv4-mapped spelling of the same unspecified address; it
- * is listed because it survives normalization as a distinct string, not because
- * it means anything different.
+ * Bind addresses meaning "every interface", canonical forms only. No client
+ * sends these as a Host header, which is why `isAllowedHostHeader`'s literal
+ * match can never satisfy them. `::ffff:0:0` is listed because it survives
+ * normalization as a distinct string.
  */
 export const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '::ffff:0:0']);
 /**
- * The bind guard, in one place because it is the third trust boundary this
- * module owns.
- *
- * It lived inline in `startDashboardServer`, so the metrics server — which takes
- * the same `host`, goes through the same `listenFrom`, and shares
- * `isAllowedHostHeader` and `serveAsset` from this module — had nothing to call
- * and bound `0.0.0.0` without objecting. That is exactly the hole this file's
- * header warns about: a guard with one implementation site cannot protect the
- * second caller that never reaches it.
+ * A URL a browser can actually open for a server bound to `host`. A wildcard
+ * bind has no connectable spelling — `http://0.0.0.0:5620` is not visitable —
+ * and `dashboard --list` reconstructs the loopback URL the same way.
+ */
+export function connectableUrl(host, port) {
+    // Normalized like every other check here: `::0` is a wildcard bind that
+    // `acceptsAnyHostHeader` recognises, so printing `http://[::0]:5620` for it
+    // handed the user a URL no browser can open.
+    const displayHost = WILDCARD_HOSTS.has(normalizeHost(host)) ? '127.0.0.1' : host;
+    // IPv6 literals need brackets in a URL; a bare `::1` parses as host `` with a
+    // port of `:1`.
+    const bracketed = displayHost.includes(':') ? `[${displayHost}]` : displayHost;
+    return `http://${bracketed}:${port}`;
+}
+/**
+ * The bind guard, shared so a new local server cannot silently bind `0.0.0.0`.
  *
- * `serverName` appears in the message so the refusal still names what refused,
- * and `remedy` is supplied by the caller for the same reason one step further:
- * the text used to hard-code "Pass `--allow-remote`", a flag `skill-metrics`
- * does not register, so the one command that could not act on the advice was the
- * one being told to. Making it a parameter means a new local server has to state
- * its own escape hatch rather than silently inherit one it may not have.
+ * `remedy` is the caller's: `--allow-remote` is a dashboard flag that
+ * `skill-metrics` does not register, so each server states its own escape hatch.
  */
 export function assertBindableHost(host, serverName, allowRemote, remedy) {
     if (LOOPBACK_HOSTS.has(normalizeHost(host)) || allowRemote)
         return;
     throw new Error(`Refusing to bind non-loopback host '${host}': the ${serverName} would be readable by anyone who can reach this machine. ${remedy}`);
 }
-// -----------------------------------------------------------------------------
-// Responses
-// -----------------------------------------------------------------------------
 export function sendJson(res, status, payload) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(payload));
 }
 /**
- * Absolute path to a shipped asset tree (`assets/<name>`), resolved relative to
- * this module's own URL.
- *
- * The depth is load-bearing: compiled to `dist/core/`, two levels up is the
- * package root, which is also what `dist/commands/` yields. Assets are shipped
- * as package `files` and never compiled, so moving this module to a different
- * depth would silently resolve outside the package. Every caller goes through
- * here so that constraint has exactly one home.
+ * Absolute path to a shipped asset tree (`assets/<name>`), resolved from this
+ * module's own URL. The depth is load-bearing: compiled to `dist/core/`, two
+ * levels up is the package root, so moving this module resolves outside it.
  */
 export function packageAssetsDir(name) {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.join(here, '..', '..', 'assets', name);
 }
 /**
- * Serves one file from `dir`. The requested name is confined to that directory:
- * URL parsing already normalises `..`, but a resolved path outside `dir` is
- * refused regardless, since this is the only thing standing between a crafted
- * request and the rest of the filesystem.
+ * Serves one file from `dir`. URL parsing already normalises `..`, but a
+ * resolved path outside `dir` is refused regardless: this is the only thing
+ * between a crafted request and the rest of the filesystem.
  */
 export async function serveAsset(res, dir, rawName) {
     const name = decodeURIComponent(rawName);
@@ -134,15 +112,11 @@ export async function serveAsset(res, dir, rawName) {
     res.writeHead(200, { 'content-type': `${type}; charset=utf-8` });
     res.end(content);
 }
-// -----------------------------------------------------------------------------
-// Trust boundary
-// -----------------------------------------------------------------------------
 /**
  * DNS-rebinding guard: only requests whose Host header names loopback (or the
  * explicitly bound non-loopback address) are served. A malicious page can make
  * a victim's browser resolve an attacker domain to 127.0.0.1 and read the
- * server's endpoints; the attacker domain in the Host header is what gives that
- * away.
+ * server's endpoints; the attacker domain in the Host header gives that away.
  */
 export function isAllowedHostHeader(hostHeader, boundHost, acceptAnyHost = false) {
     if (!hostHeader)
@@ -152,38 +126,31 @@ export function isAllowedHostHeader(hostHeader, boundHost, acceptAnyHost = false
     if (!match)
         return false;
     // Normalized on both sides so the comparison is between addresses, not
-    // between the spelling the client sent and the spelling the operator typed.
+    // between the client's spelling and the operator's.
     const name = normalizeHost(match[1]);
     if (LOOPBACK_HOSTS.has(name))
         return true;
-    // Still parsed and still last: an unparseable Host header is refused even
-    // here, so the opt-in widens who may be named, not what counts as a name.
+    // Last, and after parsing: the opt-in widens who may be named, not what counts
+    // as a name.
     if (acceptAnyHost)
         return true;
     return name === normalizeHost(boundHost);
 }
 /**
- * The Host-header policy, resolved once at startup rather than re-derived per
- * request — see decisions/20260910_150312-allow-remote-wildcard-host-policy.md.
+ * The Host-header policy, resolved once at startup rather than per request —
+ * see decisions/20260910_150312-allow-remote-wildcard-host-policy.md.
  *
  * A wildcard bind has no Host header that can literally match it, so
- * `--allow-remote --host 0.0.0.0` used to listen on every interface and then
- * 403 every request that arrived on one. Only that combination is relaxed: with
- * a concrete address the operator named the host worth accepting, and the
- * literal match is both free and still correct.
- *
- * Kept out of `isAllowedHostHeader` on purpose. That predicate cannot see
- * whether `--allow-remote` was passed, and burying "wildcard means trust
- * everyone" inside it would make the assumption invisible at the call site.
+ * `--allow-remote --host 0.0.0.0` would listen on every interface then 403 every
+ * request. Only that combination is relaxed; a concrete address names the host
+ * worth accepting. Kept out of `isAllowedHostHeader` so "wildcard means trust
+ * everyone" stays visible at the call site.
  */
 export function acceptsAnyHostHeader(boundHost, allowRemote) {
     if (!allowRemote)
         return false;
     return WILDCARD_HOSTS.has(normalizeHost(boundHost));
 }
-// -----------------------------------------------------------------------------
-// Lifecycle
-// -----------------------------------------------------------------------------
 /** Resolves once the server is listening, or rejects with the listen error. */
 export function listenOnce(server, port, host) {
     return new Promise((resolve, reject) => {
@@ -201,17 +168,12 @@ export function listenOnce(server, port, host) {
     });
 }
 /**
- * Binds `basePort`, advancing to the next port on `EADDRINUSE` until one is
- * free, and returns the port actually bound. Every local command wants the same
- * rule — a predictable port you can keep in your head, that still yields rather
- * than failing when something already holds it.
+ * Binds `basePort`, advancing on `EADDRINUSE` until one is free, and returns the
+ * port actually bound.
  *
- * `port: 0` is passed straight through: the OS picks a free port itself, so
- * there is nothing to retry and incrementing from whatever it chose would be
- * meaningless.
- *
- * The attempt bound is a backstop, not a policy: without it a machine that
- * refuses every bind for some other reason would spin through 65k ports.
+ * `port: 0` passes straight through — the OS picks a free port, so there is
+ * nothing to retry. `maxAttempts` stops a machine that refuses every bind from
+ * spinning through 65k ports.
  */
 export async function listenFrom(server, basePort, host, maxAttempts = 200) {
     let port = basePort;
@@ -232,14 +194,7 @@ export async function listenFrom(server, basePort, host, maxAttempts = 200) {
     const address = server.address();
     return typeof address === 'object' && address ? address.port : port;
 }
-// -----------------------------------------------------------------------------
-// Browser
-// -----------------------------------------------------------------------------
-/**
- * Builds the platform command that opens `url` in the default browser.
- * Pure (no side effects) so the platform branching is testable without
- * launching anything.
- */
+/** Pure, so the platform branching is testable without launching anything. */
 export function browserOpenCommand(url, platform = process.platform) {
     if (platform === 'win32')
         return `start "" "${url}"`;

package/dist/core/local-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-server.js","sourceRoot":"","sources":["../../src/core/local-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,MAAM,mBAAmB,GAA2B;IAClD,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,iBAAiB;IACxB,MAAM,EAAE,UAAU;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC;QACH,0EAA0E;QAC1E,4DAA4D;QAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1D,OAAO,IAAI,GAAG,CAAC,UAAU,SAAS,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,UAAkB,EAClB,WAAgC,EAChC,MAAc;IAEd,IAAI,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,WAAW;QAAE,OAAO;IACnE,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,UAAU,UAAU,4DAA4D,MAAM,EAAE,CACpI,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF,MAAM,UAAU,QAAQ,CAAC,GAAwB,EAAE,MAAc,EAAE,OAAgB;IACjF,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE,CAAC,CAAC;IAC7E,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAwB,EACxB,GAAW,EACX,OAAe;IAEf,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7D,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,GAAG,IAAI,iBAAiB,EAAE,CAAC,CAAC;IACjE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAA8B,EAC9B,SAAiB,EACjB,aAAa,GAAG,KAAK;IAErB,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,uEAAuE;IACvE,4EAA4E;IAC5E,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,0EAA0E;IAC1E,0EAA0E;IAC1E,IAAI,aAAa;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,IAAI,KAAK,aAAa,CAAC,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,WAAqB;IAC3E,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,MAAmB,EAAE,IAAY,EAAE,IAAY;IACxE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;YAC7B,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAChD,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACxC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAmB,EACnB,QAAgB,EAChB,IAAY,EACZ,WAAW,GAAG,GAAG;IAEjB,IAAI,IAAI,GAAG,QAAQ,CAAC;IACpB,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACrC,MAAM;QACR,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,CAAC,IAAI,OAAO,GAAG,WAAW,EAAE,CAAC;gBAChG,IAAI,EAAE,CAAC;gBACP,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IACD,kEAAkE;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,QAAQ,GAAoB,OAAO,CAAC,QAAQ;IAE5C,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,aAAa,GAAG,GAAG,CAAC;IACrD,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,SAAS,GAAG,GAAG,CAAC;IAClD,OAAO,aAAa,GAAG,GAAG,CAAC;AAC7B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,EAAE,EAAE;QAC3D,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,CAAC,IAAI,CAAC,2CAA2C,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"local-server.js","sourceRoot":"","sources":["../../src/core/local-server.ts"],"names":[],"mappings":"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"}

package/dist/core/markdown-render.d.ts

@@ -1,31 +1,23 @@
 /**
- * Markdown → HTML for the dashboard's `/api/render`.
+ * Markdown → HTML for the dashboard's `/api/render`, and a trust boundary rather
+ * than a formatting detail: the output is assigned with `innerHTML`, so it runs
+ * in the same origin that answers `POST /api/task`. The CSRF defence on
+ * `handleTaskUpdate` only stops *cross-origin* callers, so a handler smuggled in
+ * through a markdown file would sit inside it.
  *
- * The output is assigned with `innerHTML`, so everything this module emits runs
- * in the dashboard's own origin — the same origin that answers `POST /api/task`.
- * That makes the renderer a trust boundary, not a formatting detail: the CSRF
- * defence documented on `handleTaskUpdate` only stops *cross-origin* callers, so
- * a handler smuggled in through a markdown file would sit on the inside of it.
- *
- * Raw HTML is escaped rather than allowlisted. An allowlist has to be kept
- * ahead of every attribute and scheme that can execute, and the documents this
- * renders — proposals, specs, tasks, ADRs — have no reason to carry markup that
- * markdown cannot already express. Escaping needs no such upkeep and shows the
- * author exactly what they wrote.
+ * Raw HTML is escaped, not allowlisted: an allowlist has to stay ahead of every
+ * attribute and scheme that can execute, and these documents need no markup
+ * markdown cannot express.
  */
 /**
- * Returns the URL when it is safe to emit as an attribute, otherwise null.
- *
- * Two rules do the work, and both exist because of spellings a naive scheme
- * regex waves through:
+ * The URL when it is safe to emit as an attribute, otherwise null. Two rules,
+ * both against spellings a naive scheme regex waves through:
  *
- * 1. Tabs and newlines are removed first. `java	script:alert(1)` does not
- *    match `^javascript:` in any regex, but the URL parser — and therefore the
- *    browser reading the attribute — strips those characters and is left with
- *    `javascript:`. Stripping before validating is what makes the value checked
- *    here the same value the browser resolves.
- * 2. The scheme comes from `URL`, not from the raw text, so case variants and
- *    percent-encoded forms normalize before they are compared.
+ * 1. Tabs and newlines are stripped first. `java	script:alert(1)` matches no
+ *    `^javascript:` regex, but the URL parser — and the browser — strips them
+ *    and is left with `javascript:`.
+ * 2. The scheme comes from `URL`, not the raw text, so case variants and
+ *    percent-encoded forms normalize before comparison.
  */
 export declare function safeUrl(href: string): string | null;
 /** Renders markdown to HTML with raw HTML escaped and URL schemes restricted. */

package/dist/core/markdown-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-render.d.ts","sourceRoot":"","sources":["../../src/core/markdown-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA8BH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAenD;AA+BD,iFAAiF;AACjF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}
+{"version":3,"file":"markdown-render.d.ts","sourceRoot":"","sources":["../../src/core/markdown-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA6BH;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAenD;AA+BD,iFAAiF;AACjF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/core/markdown-render.js

@@ -1,25 +1,21 @@
 /**
- * Markdown → HTML for the dashboard's `/api/render`.
+ * Markdown → HTML for the dashboard's `/api/render`, and a trust boundary rather
+ * than a formatting detail: the output is assigned with `innerHTML`, so it runs
+ * in the same origin that answers `POST /api/task`. The CSRF defence on
+ * `handleTaskUpdate` only stops *cross-origin* callers, so a handler smuggled in
+ * through a markdown file would sit inside it.
  *
- * The output is assigned with `innerHTML`, so everything this module emits runs
- * in the dashboard's own origin — the same origin that answers `POST /api/task`.
- * That makes the renderer a trust boundary, not a formatting detail: the CSRF
- * defence documented on `handleTaskUpdate` only stops *cross-origin* callers, so
- * a handler smuggled in through a markdown file would sit on the inside of it.
- *
- * Raw HTML is escaped rather than allowlisted. An allowlist has to be kept
- * ahead of every attribute and scheme that can execute, and the documents this
- * renders — proposals, specs, tasks, ADRs — have no reason to carry markup that
- * markdown cannot already express. Escaping needs no such upkeep and shows the
- * author exactly what they wrote.
+ * Raw HTML is escaped, not allowlisted: an allowlist has to stay ahead of every
+ * attribute and scheme that can execute, and these documents need no markup
+ * markdown cannot express.
  */
 import { Marked } from 'marked';
 /**
  * Schemes a link or image may keep. Relative paths and fragments carry no
  * scheme and are allowed by falling through the `URL` parse below.
  *
- * `data:` is excluded on purpose: `data:text/html` navigates to attacker markup
- * in this origin, and no spec document needs an inline blob.
+ * `data:` is excluded: `data:text/html` navigates to attacker markup in this
+ * origin, and no spec document needs an inline blob.
  */
 const SAFE_URL_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
 function escapeHtml(text) {
@@ -31,29 +27,24 @@ function escapeHtml(text) {
         .replace(/'/g, ''');
 }
 /**
- * Base for resolving relative hrefs. A relative URL inherits this scheme, so
- * `parsed.protocol` lands in the allowlist and the same check covers both
- * absolute and relative inputs. The host is never emitted — only the caller's
- * original (stripped) text is returned.
+ * Base for resolving relative hrefs: a relative URL inherits this scheme, so
+ * `parsed.protocol` lands in the allowlist and one check covers both absolute
+ * and relative inputs. The host is never emitted.
  */
 const RELATIVE_BASE = 'https://tospec.invalid/';
 /**
- * Returns the URL when it is safe to emit as an attribute, otherwise null.
- *
- * Two rules do the work, and both exist because of spellings a naive scheme
- * regex waves through:
+ * The URL when it is safe to emit as an attribute, otherwise null. Two rules,
+ * both against spellings a naive scheme regex waves through:
  *
- * 1. Tabs and newlines are removed first. `java	script:alert(1)` does not
- *    match `^javascript:` in any regex, but the URL parser — and therefore the
- *    browser reading the attribute — strips those characters and is left with
- *    `javascript:`. Stripping before validating is what makes the value checked
- *    here the same value the browser resolves.
- * 2. The scheme comes from `URL`, not from the raw text, so case variants and
- *    percent-encoded forms normalize before they are compared.
+ * 1. Tabs and newlines are stripped first. `java	script:alert(1)` matches no
+ *    `^javascript:` regex, but the URL parser — and the browser — strips them
+ *    and is left with `javascript:`.
+ * 2. The scheme comes from `URL`, not the raw text, so case variants and
+ *    percent-encoded forms normalize before comparison.
  */
 export function safeUrl(href) {
-    // C0 controls and space are trimmed from both ends, tab/LF/CR removed
-    // throughout — the same normalization the URL parser applies.
+    // The same normalization the URL parser applies: C0 controls and space
+    // trimmed from both ends, tab/LF/CR removed throughout.
     const cleaned = href.replace(/[\x00- ]+$/, '').replace(/^[\x00- ]+/, '').replace(/[\t\n\r]/g, '');
     if (cleaned === '')
         return null;
@@ -67,7 +58,7 @@ export function safeUrl(href) {
     if (!SAFE_URL_SCHEMES.has(parsed.protocol))
         return null;
     // The cleaned form, not the input: what was validated has to be what is
-    // emitted, or the browser re-reads characters this function removed.
+    // emitted, or the browser re-reads the characters removed above.
     return cleaned;
 }
 const renderer = new Marked({
@@ -79,8 +70,8 @@ const renderer = new Marked({
         link(token) {
             const body = this.parser.parseInline(token.tokens);
             const href = safeUrl(token.href);
-            // A rejected scheme keeps the text and loses the link. Dropping the whole
-            // node would hide that the author wrote something the renderer refused.
+            // A rejected scheme keeps the text and loses the link; dropping the node
+            // would hide that the author wrote something the renderer refused.
             if (href === null)
                 return body;
             const title = token.title ? ` title="${escapeHtml(token.title)}"` : '';

package/dist/core/markdown-render.js.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-render.js","sourceRoot":"","sources":["../../src/core/markdown-render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown-render.js","sourceRoot":"","sources":["../../src/core/markdown-render.ts"],"names":[],"mappings":"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"}

package/dist/core/migrate.d.ts

@@ -21,18 +21,18 @@ export interface MigrateSummary {
     context: 'carried' | 'conflict' | 'empty' | 'absent';
     /** REMOVED requirements dropped during main-spec normalization (`spec/name`). */
     removedRequirements: string[];
-    /** RENAMED requirement blocks kept as MODIFIED content (`spec/name`). */
+    /** Renames a RENAMED section asked for and normalization applied (`spec/from -> to`). */
+    renamedRequirements: string[];
+    /**
+     * RENAMED entries normalization could not act on, so the old name stands
+     * (`spec/name`). Reported for manual review rather than dropped.
+     */
     renamedKept: string[];
 }
 export declare class MigrateError extends Error {
     /**
-     * A full `CommandDiagnostic`, not the bare `{ fix }` it used to hold.
-     *
-     * `asStatus` recognises an error's diagnostic by `typeof diagnostic.code ===
-     * 'string'`, so the partial shape failed that test and every migrate failure
-     * fell through to the generic branch — which builds a status entry from the
-     * message alone. The `fix` was constructed at each throw site and then
-     * silently discarded on the way out.
+     * A full `CommandDiagnostic`: `asStatus` recognises one by `typeof
+     * diagnostic.code === 'string'`, so a bare `{ fix }` is dropped.
      */
     readonly diagnostic: CommandDiagnostic;
     constructor(message: string, options?: {
@@ -42,9 +42,8 @@ export declare class MigrateError extends Error {
 }
 /**
  * Converts an OpenSpec archive dir name (`YYYY-MM-DD-<name>`) to the tospec
- * stamp form (`YYYYMMDD_000000-<name>`). OpenSpec only recorded the date, so
- * the time part is zero-filled. Names without the date prefix pass through
- * unchanged (they already parse as `<stamp>-<name>` no worse than before).
+ * stamp form (`YYYYMMDD_000000-<name>`). OpenSpec only recorded the date, so the
+ * time part is zero-filled. Names without the date prefix pass through.
  */
 export declare function convertArchiveDirName(dirName: string): string;
 /**
@@ -57,7 +56,12 @@ export declare function normalizeMainSpec(content: string, capabilityName: strin
     fixed: 'delta' | 'headerless';
     /** Names of requirements a REMOVED section dropped (recorded, not silent). */
     removed: string[];
-    /** Names of RENAMED requirement blocks whose content was kept as MODIFIED. */
+    /** Renames a RENAMED section asked for and this rebuild applied. */
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** RENAMED entries nothing could be applied for; the old name stands. */
     renamedKept: string[];
 } | null;
 export declare class MigrateCommand {
@@ -73,10 +77,9 @@ export declare class MigrateCommand {
      */
     private migrateMetadata;
     /**
-     * Promote the fully-built staging tree into the target. When the target
-     * doesn't exist, one move does it; when an (verified content-free) tospec/
-     * dir exists — e.g. from `tospec init` — each staged top-level entry
-     * replaces its counterpart. Reuses archive's EPERM/EXDEV-safe move helpers.
+     * Promotes the built staging tree into the target: one move when the target is
+     * absent, else entry-by-entry replacement into the content-free tospec/ that
+     * `tospec init` leaves. Uses archive's EPERM/EXDEV-safe helpers.
      */
     private promoteStaging;
 }

package/dist/core/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/core/migrate.ts"],"names":[],"mappings":"AAMA,OAAO,EAAe,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AA8BnF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAiC,CAAC;AAE9F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACvG,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kDAAkD;IAClD,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EASrE;CACF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GAAG,IAAI,CA4GP;AAqCD,qBAAa,cAAc;IACnB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA+KzE;IAED,mGAAmG;YACrF,aAAa;IA+B3B;;;;;;OAMG;YACW,eAAe;IAe7B;;;;;OAKG;YACW,cAAc;CAiB7B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/core/migrate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAe,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAkCnF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAiC,CAAC;AAE9F,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACvG,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kDAAkD;IAClD,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,yFAAyF;IACzF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EASrE;CACF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,GAAG,IAAI,CAqFP;AAqED,qBAAa,cAAc;IACnB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAsLzE;IAED,mGAAmG;YACrF,aAAa;IA6B3B;;;;;;OAMG;YACW,eAAe;IAe7B;;;;OAIG;YACW,cAAc;CAiB7B"}