@adhd/backlog 0.1.8 → 1.0.0

package/query/views/stats.d.ts

@@ -0,0 +1,109 @@
+import { IQueryStoreHandle } from '../query.js';
+import { IIssueFilter } from '../types.js';
+
+export interface IPriorityMatrixRow {
+    priority: string;
+    priorityUid: string;
+    /** `priority.meta.metadata.rank` (`nextPriorityRankTx`, §2) — lower is more urgent. Absent only for a malformed pre-existing row with no numeric rank; the count itself is still real. */
+    rank?: number;
+    count: number;
+}
+export interface IPriorityMatrixResult {
+    /** Sorted by `rank` ascending (a missing rank sorts last), mirroring `query.ts`'s own `sortByPriorityRank` convention. */
+    rows: IPriorityMatrixRow[];
+    /** In-scope issues carrying no live `has_priority` edge at all — never silently folded into a phantom priority row, never silently dropped from the total. */
+    unassigned: number;
+    /** The status scope actually applied. `'open'` when `filter?.status` was omitted (BUG-023's fix) — echoed here so a caller can never mistake a default-scoped result for an all-status one. */
+    statusScope: NonNullable<IIssueFilter['status']>;
+}
+export interface IPriorityMatrixInput {
+    /** `project`/`component`/`kind`/`status` only (§6.5 rule 3's edge-scoped dimensions, restricted to what a priority breakdown composes with) — any other key throws. */
+    filter?: IIssueFilter;
+}
+/** SPEC.md §5's status-aware priority matrix (BUG-023). */
+export declare function priorityMatrix(handle: IQueryStoreHandle, input?: IPriorityMatrixInput): Promise<IPriorityMatrixResult>;
+export interface IPartOfRollupInput {
+    /** The root issue's `uid` (§6.1). Throws `IssueNotFoundError` if it does not resolve to a live issue. */
+    uid: string;
+}
+export interface IPartOfRollupResult {
+    uid: string;
+    /** Every TRANSITIVE descendant via `part_of` (issue → issue, `n:1`, §3) — not just direct children. Counted exactly once each, regardless of chain depth. */
+    childrenTotal: number;
+    childrenOpen: number;
+    childrenClosed: number;
+    /** `uid`s of the still-open descendants — the actionable half, mirroring the `IIssueRef`-shaped convention `card.ts`'s `blockers`/`related` already use. */
+    childrenOpenUids: readonly string[];
+}
+/**
+ * SPEC.md §5's `part_of` + derived two-axis rollup (FEAT-005), realized as
+ * ONE axis here — children-open/closed over the FULL transitive subtree
+ * (the second axis, "does THIS item carry its own closing evidence," is a
+ * `get`/card-assembly concern over the root's own citations, out of scope
+ * for a rollup over its CHILDREN).
+ *
+ * Uses `getSubgraph(rootId, {rel:'part_of', direction:'in', depth:-1})` —
+ * the unbounded walk (verified: `getNeighbors`'s `depth` is a row BUDGET,
+ * not a depth bound, per `@adhd/sox-graph-store`'s own dist comment; only
+ * `getSubgraph`'s `-1` sentinel gives a genuine unbounded multi-level walk)
+ * with its own internal visited set, so a grandchild (or deeper) reached
+ * through exactly one path is collected into the SAME node set as a direct
+ * child — counted once, never re-added by also summing each child's own
+ * subtree size on top of a direct-children count. `getSubgraph` does NOT
+ * filter node liveness (documented on the library's own `getSubgraphIterative`:
+ * "an invalidated node behind a live edge IS part of the subgraph") — a
+ * soft-deleted descendant is explicitly filtered back out below, since a
+ * deleted issue is neither open work nor closed work, it is gone.
+ */
+export declare function partOfRollup(handle: IQueryStoreHandle, input: IPartOfRollupInput): Promise<IPartOfRollupResult>;
+export interface IOpenCurveInput {
+    /** `project`/`component`/`kind` only — `status` is rejected (`InvalidArgumentError`): this view computes openness itself, per sampled instant, so a caller-given status filter would silently conflict with that computation rather than compose with it. */
+    filter?: IIssueFilter;
+    /** ISO-8601 instants to sample, in the given order. Must be non-empty; each is parsed via `Date.parse` and normalized to a full ISO string for lexical comparison against stored `at` timestamps — an unparsable entry throws by name rather than silently producing `NaN`-derived output. */
+    at: readonly string[];
+}
+export interface IOpenCurvePoint {
+    at: string;
+    /** In-scope issues that EXISTED at this instant (`NodeFilter.validAt`: `t_created <= at` and `t_invalid` is null or after `at`) — exact, never reconstructed. */
+    existed: number;
+    /** Of `existed`, the count whose RECONSTRUCTED status was non-terminal at this instant (never the issue's CURRENT status) — see {@link reconstructStatusAt}. */
+    open: number;
+    /** `existed - open`. */
+    closed: number;
+}
+export interface IOpenCurveResult {
+    points: readonly IOpenCurvePoint[];
+}
+/**
+ * SPEC.md §5's `validAt`-driven cumulative-open curve.
+ *
+ * **Cost is bounded by the sampled-instant count and the size of the
+ * `has_status`/`audits` relations, never by (instants × existing-issue
+ * count).** The obvious shape — for each sampled instant, fetch the issues
+ * that existed then, per issue, fetch its current-status edge, its
+ * current-status node, and its full audit trail — is up to four sequential
+ * round trips PER ISSUE PER INSTANT. Ten sampled instants over a 5,000-issue
+ * store cost on the order of 200,000 serialized queries under that shape,
+ * even though nothing about "how open was the store on these ten dates"
+ * scales with store size on its own — it should scale with the number of
+ * dates the caller asked about. Worse, an issue's CURRENT status and full
+ * audit trail don't depend on `at` at all (`reconstructStatusAt` only reads
+ * them; it never asks the backend anything itself), so the naive per-instant
+ * loop was refetching the exact same unchanging per-issue data once per
+ * instant for nothing.
+ *
+ * Instead, both relations are fetched ONCE, before the instant loop, and
+ * grouped in memory — the same shape `query.ts`'s `queryReady` already uses
+ * for `blocks`/`has_status`: `getEdges({rel:'has_status'})` and
+ * `getEdges({rel:'audits'})` each take the WHOLE relation in a single call
+ * (there is no batch-by-many-`src` primitive — `getEdges` accepts only one
+ * `src`/`dst` at a time, which is exactly why fetching the whole relation
+ * once is the right move), plus one `getNodesByIds` each to resolve the
+ * status/audit-entry nodes those edges point at — see
+ * {@link resolveCurrentStatusAndAuditTrails}. That's four queries total for
+ * this cost, however many issues or instants are involved; the only
+ * per-instant cost left is the one `queryNodes({validAt})` call SPEC.md's own
+ * existence check requires. Total round trips: `4 + M` for `M` sampled
+ * instants — independent of N, the number of issues in the store.
+ */
+export declare function openCurve(handle: IQueryStoreHandle, input: IOpenCurveInput): Promise<IOpenCurveResult>;

package/search-shortcut.d.ts

@@ -0,0 +1,79 @@
+/**
+ * search-shortcut.ts — `backlog search "<text>" [flags]`, a pure ARGV
+ * TRANSLATION onto the mounted `query` operation.
+ *
+ * ## Why a translation and not a seventh operation
+ *
+ * The apigen mount-surface spec §3 fixes the apigen mount surface at exactly six verbs
+ * (`get, query, create, update, relate, admin`) — `index.ts`'s own comment
+ * above those exports says "these, and only these". Adding a `search` export
+ * to `client.ts` would widen that surface for every transport (CLI, HTTP,
+ * MCP) to buy CLI ergonomics, which is the wrong trade. So `search` never
+ * becomes an operation: `runBacklogCli` rewrites its argv into
+ * `['query', '--input', '<json>']` and hands it to the SAME
+ * `@adhd/apigen-plugin-cli-output` dispatch every other command goes
+ * through. Store lifecycle, signal cleanup, `exitCodeForEnvelope` mapping and
+ * output shape are therefore reused unchanged rather than reimplemented —
+ * this module is a pure function over `string[]` and opens nothing.
+ *
+ * ## Why the positional compiles to `text`, not `filter.semantic`
+ *
+ * `IIssueQueryInput.text` is already specified as "the natural-language
+ * query; also the CLI positional form" (§2.1b) — this shortcut is the CLI
+ * form that field was written for. `resolveTextInput` (query/query.ts, called
+ * once from `queryIssues`) routes the whole string into `filter.semantic`
+ * when the vector space is readable and into `filter.grep` when it is NOT
+ * (RAG-SPEC §3.1 / BUG-045), and picks `sort: "relevance"` or `"textMatch"`
+ * to match. Compiling the positional straight to `filter.semantic` instead
+ * would hard-fail on an unconfigured or unbackfilled store, throwing away a
+ * working keyword answer — and would ALSO need this module to hardcode a
+ * `sort` default that `resolveTextInput` already derives correctly. Neither
+ * divergence is worth owning here.
+ *
+ * For the same reason there is no `fields` default: the `text` path's own
+ * projection is already the compact `uid/kind/title/status/priority`
+ * list (`DEFAULT_ISSUE_CARD_FIELDS`, query/types.ts), so a default invented
+ * here could only make it worse. `--fields` overrides it (add `_score` to
+ * see the ranking scores).
+ *
+ * ## Error parity
+ *
+ * The flags below are hand-parsed, not schema-derived, so every rejection
+ * mirrors `@adhd/apigen-plugin-cli-output`'s `parseArgs`/validate-Layer
+ * wording byte-for-byte: `Unknown option: --X. Available: …` (a REAL list, never a placebo),
+ * `Missing value for --X`, `Unexpected positional argument: "X"`. The caller
+ * prints them as `{"code":"invalid_argument","message":…}` on stderr with
+ * `process.exitCode = 2` (`CLI_EXIT_CODE['invalid_argument']`).
+ *
+ * DEBT-BACKLOG-001 (the backlog CLI's bespoke argv parsing diverging from the
+ * apigen-mounted surface) is enlarged by this file, deliberately and with the
+ * parity discipline above; see that item.
+ */
+/**
+ * The complete, REAL flag vocabulary — the `Available:` list an unknown-option
+ * rejection prints. Derived from the four arrays above rather than
+ * hand-maintained, so a flag can never be accepted but unlisted (or listed
+ * but unaccepted).
+ */
+export declare const SEARCH_FLAGS: readonly string[];
+export declare const SEARCH_HELP: string;
+/** A rendered `--help`, a rejection, or the rewritten argv to dispatch. */
+export type SearchShortcutOutcome = {
+    kind: 'help';
+    text: string;
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'argv';
+    argv: string[];
+};
+/**
+ * Translates `search`'s tokens (everything AFTER the `search` word) into the
+ * `['query', '--input', '<json>']` argv the apigen command table dispatches.
+ *
+ * Pure: reads no config, opens no store, touches no globals — so the caller
+ * can reject a bad invocation before any of `runBacklogCli`'s store lifecycle
+ * has started, and so every branch here is unit-testable on its own.
+ */
+export declare function buildSearchArgv(rest: readonly string[]): SearchShortcutOutcome;

package/serve.d.ts

@@ -5,7 +5,25 @@ export interface RunServeCommandOpts {
     /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */
     adhdRoot?: string;
     cwd?: string;
+    /** Explicit-parameter-first namespace override — see
+     *  `BuildBacklogEnvOptions.namespace`'s doc comment. `--namespace sandbox
+     *  serve` (cli.ts) sets this to `'sandbox'`, along with minting a fresh
+     *  `adhdRoot` and writing D8's sandbox `config.yaml`. */
+    namespace?: string;
 }
+/**
+ * BUG-033: `backlog serve --help` used to throw a plain `Error` from
+ * `parseArgs` (unknown-argument), which `runServeCommand` neither caught nor
+ * short-circuited — the error propagated all the way to `index.ts`'s
+ * bin-entry guard, which prints `err.stack` unconditionally, so a completely
+ * ordinary "show me the help" request rendered as ten frames of minified
+ * dist. Mirrors `install.ts`'s established `--help` + `BacklogUsageError` +
+ * `failUsage` pattern exactly: `--help`/`-h` anywhere in argv short-circuits
+ * BEFORE parsing, and every argument-parsing failure is a `BacklogUsageError`
+ * (never a bare `Error`) so `runServeCommand` can catch it and hand it to
+ * `failUsage` instead of letting it reach the bin guard's stack-trace path.
+ */
+export declare const SERVE_HELP_TEXT = "backlog serve [--transport mcp|http|both] [--port N] [--host H]\n\nStarts the long-lived backlog server (MCP and/or HTTP), matching one of the\nprocess's own configured transports to the way an agent host or a script\nexpects to reach it.\n\n  --transport <name>  mcp | http | both (default: mcp)\n  --port <N>           HTTP listen port (default: 3300; ignored for mcp-only)\n  --host <name>         HTTP listen host (default: 127.0.0.1; ignored for mcp-only)\n\nExamples:\n  backlog serve\n  backlog serve --transport http --port 3300\n  backlog serve --transport both --host 0.0.0.0\n";
 /** Runs until the process receives SIGTERM/SIGINT (the normal way a host
  *  process manager — or `.mcp.json`'s own stdio transport lifecycle — stops
  *  a long-lived MCP/HTTP server), then resolves cleanly. */

package/server.d.ts

@@ -1,5 +1,6 @@
-import { BacklogCtx } from './client.js';
-import { composeSchemas, Operation, Logger, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
+import { BacklogCtx } from './api.js';
+import { HttpVerb } from '@adhd/apigen-engine-naming';
+import { composeSchemas, Operation, Plugin, Logger, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
 import { Scope } from '@adhd/environment-base-spec';
 
 /**
@@ -37,6 +38,117 @@ export declare function requireRun(plugin: OutputPlugin): (input: RunInput) => P
  * `undefined` and the real pino default logger is used, unchanged.
  */
 export declare function testSilentLogger(): Logger | undefined;
+/**
+ * SPEC.md §6.6's "host-command carve-out" — the commands that are
+ * deliberately NOT part of the mounted data surface, pinned as a value so the
+ * refusal is enforceable rather than prose.
+ *
+ * `install`/`install-skill` are pure filesystem/config operations that must
+ * never open the store (cli.ts:243-256 special-cases them BEFORE the apigen
+ * command table is ever built — that is what closes
+ * DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001), and `serve` is a long-lived
+ * listener launcher with a completely different lifecycle (cli.ts:262-265).
+ * Neither is a data op, so neither may ever appear as an apigen operation on
+ * ANY of the four mounts.
+ *
+ * `assertHostCarveOut` turns §6.6's negative assertion ("`install`/`serve` are
+ * NOT among the mounted verbs") into a mount-time invariant: a future refactor that
+ * accidentally exports a host command from the mounted client module fails at
+ * `buildBacklogApigenPackage()` — in every transport at once — instead of
+ * silently shipping a `backlog_serve` MCP tool that would open a second
+ * concurrent writer against the store via a completely different lifecycle
+ * path than the one `startBacklogServer` itself expects.
+ */
+export declare const BACKLOG_HOST_COMMANDS: readonly string[];
+/**
+ * SPEC.md §6.7 — the data verbs the whole surface consolidates onto:
+ * the nine issue verbs plus `lookup`, §3a's registry CRUD verbs, and the
+ * three §5 stats/rollup reads (`priority-matrix`/`part-of-rollup`/
+ * `open-curve`), mounted as `backlog_<verb>`. Pinned here, next to the
+ * carve-out it is the complement of, because it is the ONE list four separate
+ * surfaces are
+ * checked against: the three apigen mounts derive their names from the
+ * operation descriptors via `describeMountedSurface`, and `cli.ts`'s argv
+ * parser — which is deliberately NOT an apigen mount, because apigen's
+ * `parseArgs` cannot express the §2.1b positional form, projects `string[]`
+ * as a JSON-valued flag where §7.3 wants comma-separated, and only sets
+ * `process.exitCode` on a thrown `ApiError` (so an `ok:false` envelope would
+ * exit 0, contradicting `BACKLOG_EXIT_CODE`) — has to be checked against this list rather than
+ * derived from the mount.
+ *
+ * That asymmetry is exactly how a split brain starts, and this repo already
+ * has one open as BUG-BACKLOG-MCP-CLI-SPLIT-BRAIN-001. `server.verbs.spec.ts`
+ * asserts BOTH sides against this constant so a verb added to one surface and
+ * forgotten on the other fails a test instead of shipping.
+ *
+ * Order is the SPEC.md §4/§6 declaration order, not alphabetical; compare as sets.
+ */
+export declare const BACKLOG_VERBS: readonly string[];
+/**
+ * One mounted operation, projected to all four transports backlog serves.
+ *
+ * Every field here is computed by `@adhd/apigen-engine-naming`'s `project()`
+ * — the SAME function `apigen-plugin-api-fastify` (`run.ts:214-215` via
+ * `routeFor`), `apigen-plugin-mcp` (tool registration), `apigen-plugin-cli-output`
+ * (command table) and `@adhd/apigen-codegen-openapi`'s `toOpenApi`
+ * (`to-openapi.ts:131` → `paths[route]`) each call independently. That shared
+ * projector is *why* the four surfaces agree: there is one operation
+ * descriptor list and one naming function, never a per-transport definition
+ * and never a hand-maintained OpenAPI document.
+ */
+export interface IMountedOperationSurface {
+    /** Canonical apigen operation id (e.g. `backlog/get-item`). */
+    id: string;
+    /** CLI command as a human types it, e.g. `backlog get-item`. */
+    cliCommand: string;
+    /** CLI command segments, e.g. `['backlog','get-item']`. */
+    cliPath: string[];
+    /** MCP tool name as a host loads it, e.g. `backlog_get_item`. */
+    mcpTool: string;
+    /** HTTP verb the fastify mount registers. */
+    httpVerb: HttpVerb;
+    /** HTTP route the fastify mount registers AND the OpenAPI `paths` key. */
+    httpRoute: string;
+}
+/**
+ * Projects the extracted operation descriptors onto the four transports
+ * backlog mounts, returning the single expected surface.
+ *
+ * This is the mechanical statement of SPEC.md §6.7: *one* operation
+ * definition serves CLI, MCP, REST and OpenAPI. A test (or an operator) can
+ * call this once and compare it against what each live transport actually
+ * advertises; a divergence means some transport grew its own definition,
+ * which is precisely what §6.7 forbids.
+ *
+ * Only `kind: 'action'` operations are mounted — the same filter
+ * `buildBacklogApigenPackage` applies when it builds `generated.schemas`, so
+ * this never claims a surface the package does not actually compose.
+ *
+ * @param operations the descriptor list returned by `buildBacklogApigenPackage`
+ * @returns one entry per mounted operation, sorted by canonical id for stable
+ *   comparison
+ */
+export declare function describeMountedSurface(operations: readonly Operation[]): IMountedOperationSurface[];
+/**
+ * Derives the FULL set of MCP tool names the real `serve --transport mcp`
+ * process advertises — every mounted `client.ts` verb (via
+ * `describeMountedSurface`'s `mcpTool`, itself `project(op).mcp.name`) PLUS
+ * every tool a mount plugin (currently just `apigen-plugin-batch`'s
+ * `batch_action`) contributes, using the exact same `project(op).mcp.name`
+ * derivation `cli.ts`'s `resolveMountNamespaces` uses for the CLI's own
+ * top-level segments.
+ *
+ * Exists so a test can assert against a LIVE-derived tool set instead of a
+ * hardcoded literal array/count — a hardcoded `['backlog_get', …]` (or a bare
+ * `.length === 7`) silently stops meaning anything the moment a `client.ts`
+ * export is added, renamed, or removed, and would then either falsely fail
+ * (a legitimate, intended surface change) or — worse — falsely pass (typo'd
+ * to match the wrong new count) with no signal that the assertion itself
+ * needs updating. Deriving it here, from the same `operations`/`usePlugins`
+ * every transport is actually built from, means the assertion tracks the
+ * shipped surface automatically.
+ */
+export declare function resolveExpectedMcpToolNames(operations: readonly Operation[], usePlugins?: readonly Plugin[]): string[];
 export interface StartOpts {
     transport: 'http' | 'mcp' | 'both';
     port?: number;
@@ -46,6 +158,9 @@ export interface StartOpts {
     adhdRoot?: string;
     cwd?: string;
     signal: AbortSignal;
+    /** Explicit-parameter-first namespace override — see
+     *  `BuildBacklogEnvOptions.namespace`'s doc comment. */
+    namespace?: string;
 }
 /**
  * Builds the composed, apigen-ready package descriptor for `client.ts`'s
@@ -56,18 +171,38 @@ export interface StartOpts {
  * when a dispatched command actually reaches the real function, which never
  * happens for `--help`/no-args/an unknown command. This is what closes
  * DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001: `operations`/`schemas` below are
- * computed purely from the built `client.d.ts` (via `extractClientOperations`)
+ * computed purely from the built `api.d.ts` (via `extractApiOperations`)
  * and never touch `ctx` at all, so a lazy caller can defer opening the real
  * backing store until a command that actually needs it is dispatched.
+ *
+ * @param opts.adhdRoot/instanceId BUG-BACKLOG-SANDBOX-IRCACHE-001 — forwarded
+ *   verbatim to `extractApiOperations`/the IR-cache plugin, so a caller
+ *   already isolating its real store via `adhdRoot` (`--namespace sandbox`, or any
+ *   other test-isolation caller of `buildBacklogEnv`) gets the extract-stage
+ *   IR cache isolated the SAME way, instead of it silently falling through
+ *   to the real machine `HOME`. Optional and additive — every existing call
+ *   site that omits it keeps its prior (real-`HOME`, shared-cache) behavior
+ *   exactly.
  */
-export declare function buildBacklogApigenPackage(ctx: BacklogCtx | (() => BacklogCtx | Promise<BacklogCtx>)): Promise<{
+export declare function buildBacklogApigenPackage(ctx: BacklogCtx | (() => BacklogCtx | Promise<BacklogCtx>), opts?: {
+    adhdRoot?: string;
+    instanceId?: string;
+}): Promise<{
     pkg: {
         id: string;
+        version: string;
         schemas: ReturnType<typeof composeSchemas>;
         importPath: string;
         fns: Record<string, (...args: unknown[]) => unknown>;
         createClient: () => Promise<BacklogCtx>;
     };
+    /**
+     * §6.7: the four-transport projection of `operations`, computed once here
+     * so CLI, MCP, REST and OpenAPI are provably reading ONE definition. Callers
+     * that need to know "what is mounted" must read this rather than
+     * re-deriving names per transport.
+     */
+    surface: IMountedOperationSurface[];
     operations: Operation[];
 }>;
 /**