@adhd/backlog 0.0.1 → 0.0.2

package/README.md

@@ -54,10 +54,46 @@ const abort = new AbortController();
 await startBacklogServer({ transport: 'both', port: 3400, signal: abort.signal });
 ```
 
-- `POST /backlog/createItem`, `GET /backlog/getItem`, ... — every `client.ts`
-  export, mounted live via `@adhd/apigen-plugin-api-fastify`.
-- Every export is also available as an MCP tool via `@adhd/apigen-plugin-mcp`
-  (stdio transport by default).
+- `POST /backlog/client-d/create-item`, `GET /backlog/client-d/get-item`, ... —
+  every `client.ts` export, mounted live via `@adhd/apigen-plugin-api-fastify`.
+  (The `client-d` route segment is not a typo — see `DESIGN.md` §7's CLI
+  section / `SPEC.md` §7's transport table for why it's there.)
+- Every export is also available as an MCP tool (e.g. `backlog_client_d_get_item`)
+  via `@adhd/apigen-plugin-mcp` (stdio transport by default).
+
+## CLI (`backlog`, live apigen mount — no codegen)
+
+```bash
+pnpm add -g @adhd/backlog   # installs the `backlog` bin
+backlog --help              # live-derived command listing
+backlog create-item --input '{"family":"BUG-EXAMPLE","title":"t","body":"b","repo":"org/repo"}'
+backlog get-item --repo org/repo --human-id BUG-EXAMPLE-001
+backlog list-items --filter '{"status":"OPEN"}'
+```
+
+- Same architecture as the HTTP/MCP transports above — `entrypoint/backlog/src/cli.ts`'s
+  `runBacklogCli()` reuses `buildBacklogApigenPackage()` and hands it straight
+  to `@adhd/apigen-plugin-cli-output`'s `run()`. No `apigen generate`, no
+  bespoke argument parsing — routing, flag parsing, validation, dispatch, and
+  exit codes all come from that plugin.
+- **You type `backlog <command>`, never the internal `client-d` segment.**
+  `runBacklogCli` derives the real command-table prefix from the live
+  `operations` list at runtime (`resolveCommandPrefix`) and prepends it before
+  dispatch — so `backlog get-item …` resolves even though the plugin's real
+  command table is keyed `backlog client-d get-item` internally (same
+  `client-d` artifact as the HTTP/MCP routes above; the CLI is the one
+  transport that hides it from the caller).
+- Flags are the schema's domain params, kebab-cased (`humanId` → `--human-id`);
+  object/array-typed params take a JSON string (`--input '{...}'`,
+  `--filter '{...}'`).
+- Exit codes follow `@adhd/apigen-base-errors`'s `CLI_EXIT_CODE` table: `0`
+  success, `2` invalid argument (bad/unknown flag, failed validation), `4`
+  unknown command, etc. Result is printed as JSON to stdout; errors as JSON to
+  stderr.
+- Honors the same `ADHD_BACKLOG_SCOPE`/`ADHD_ENV_SCOPE` scope env vars as the
+  library API (see Scope below) — there is no separate CLI-only config.
+- `runBacklogCli(argv?, opts?)` is also exported for in-process programmatic
+  use (e.g. a test harness), symmetric with `startBacklogServer`.
 
 ## Scope
 

package/dist/cli.d.ts

@@ -0,0 +1,82 @@
+import { Operation } from '@adhd/apigen-core-client';
+import { Scope } from '@adhd/environment-base-spec';
+
+/**
+ * Derives the internal command-path PREFIX every `client.ts` operation
+ * shares in `@adhd/apigen-plugin-cli-output`'s command table
+ * (`buildCommandTable()`: `cliPath = project(op).cli.path`, and
+ * `project()`'s `cli.path = [namespace, ...path].map(toKebab)` —
+ * `@adhd/apigen-engine-naming`'s `naming.ts`).
+ *
+ * NOT simply `['backlog']`. `extract()` (`@adhd/apigen-core-client`'s
+ * `extract.ts`) unconditionally builds every operation's `path` as
+ * `[fileSegment, exportSegment]`, where `fileSegment` is derived from the
+ * EXTRACTED SOURCE FILE's own name (`normalizeFileName('client.d.ts')` →
+ * `'client-d'` — strips one extension, then folds remaining `.`/`_` to `-`).
+ * `server.ts`'s `extractClientOperations()` always points extraction at the
+ * built `client.d.ts` (see that file's DEVIATION doc comment), so EVERY
+ * `client.ts` export's real `cli.path` is
+ * `['backlog', 'client-d', '<kebab-export-name>']` — confirmed empirically
+ * (not assumed) by inspecting a real built `pkg`/`operations` pair; see
+ * `cli.spec.ts`'s "command-prefix derivation" suite. The HTTP
+ * (`apigen-plugin-api-fastify`) and MCP (`apigen-plugin-mcp`) transports
+ * both route by bare `fnName` and never consult `project(op)` at all, so
+ * this `client-d` segment is INVISIBLE on those two transports — it is
+ * cli-output-specific, and would leak into every command a user types
+ * (`backlog client-d get-item …`) if this file naively hardcoded a
+ * single-segment `'backlog'` prefix instead of deriving the REAL prefix from
+ * the live `operations` list.
+ *
+ * Since every `client.ts` export shares the same namespace + same source
+ * file, every operation's `cli.path` differs ONLY in its final (export)
+ * segment — so the shared prefix is simply "everything but the last
+ * segment" of any one operation's projected `cli.path`. Computed fresh from
+ * `operations` on every call (never cached as a literal), so a future change
+ * to the extraction source file name, or to `apigen-core-client`'s file-
+ * segment derivation, can never silently desync this from the real command
+ * table the way a hardcoded constant would.
+ */
+export declare function resolveCommandPrefix(operations: readonly Operation[]): string[];
+/**
+ * Prepends `prefix` (the real, namespace-qualified command path segments
+ * every `client.ts` export shares — see {@link resolveCommandPrefix}) to a
+ * user-typed argv, so `backlog get-item --repo … --human-id …` (what a
+ * consumer actually types — the bin's own name is never part of `argv`)
+ * resolves against the cli-output plugin's command table, which is keyed by
+ * the FULL internal path (`['backlog', 'client-d', 'get-item']`).
+ *
+ * Idempotent / defensive:
+ *  - Empty argv is returned unchanged — `run()` treats `argv.length === 0`
+ *    as the usage listing regardless of any prefix.
+ *  - Argv already starting with the full `prefix` (in order) is returned
+ *    unchanged — never double-prefixed.
+ *  - A leading flag (`--help`, `-h`, or any other top-level `-`-prefixed
+ *    token) is returned unchanged — `run()` special-cases `--help`/`-h`
+ *    BEFORE ever consulting the command table
+ *    (`if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h')`),
+ *    so prefixing here would shadow that check and break `backlog --help`.
+ */
+export declare function prefixCommand(userArgv: readonly string[], prefix: readonly string[]): string[];
+export interface RunBacklogCliOpts {
+    scope?: Scope;
+    /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */
+    adhdRoot?: string;
+    cwd?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Opens (or reuses) the backlog store + env, then dispatches EXACTLY ONE CLI
+ * command live through `@adhd/apigen-plugin-cli-output`'s `run()` — no code
+ * generation, no bespoke argument parsing. Mirrors `startBacklogServer`'s
+ * env→store→ctx→`buildBacklogApigenPackage` setup precisely; the only
+ * divergence is transport-specific: `cliPlugin.run()` is one-shot (it
+ * resolves after dispatching a single command rather than listening), so
+ * there is no `Promise.all` of long-lived transports to await here.
+ *
+ * @param argv Command + flags, WITHOUT the `backlog` bin name (e.g.
+ *   `['get-item', '--repo', 'org/repo', '--human-id', 'BUG-1']`). Defaults
+ *   to `process.argv.slice(2)` — the real CLI invocation's own argv — when
+ *   omitted, matching `cliPlugin.run()`'s own `resolveArgv()` fallback
+ *   convention.
+ */
+export declare function runBacklogCli(argv?: string[], opts?: RunBacklogCliOpts): Promise<void>;

package/{client.d.ts → dist/client.d.ts}

@@ -1,12 +1,24 @@
 import { GraphBacklogStore } from './store/graph-backlog-store.js';
 import { BacklogConfig } from './env.js';
-import { ArchiveOpts, ArchiveResult, AuditTrailResult, BacklogFilter, BacklogItem, BacklogStats, BacklogStatus, ClaimOpts, ClaimResult, Citation, CreateItemInput, CreateItemResult, DependencyGraph, ImportMarkdownInput, ImportResult, Priority, ReleaseResult, StatsScope, TopoOrderResult, TransitionOpts, UpdateItemInput } from './model.js';
+import { ArchiveOpts, ArchiveResult, AuditTrailResult, BacklogFilter, BacklogItem, BacklogStats, BacklogStatus, ClaimOpts, ClaimResult, Citation, CreateItemInput, CreateItemResult, DependencyGraph, ImportMarkdownInput, ImportResult, MigrationPhase, MigrationStatusResult, Priority, ReleaseResult, SetMigrationPhaseResult, StatsScope, TopoOrderResult, TransitionOpts, UpdateItemInput } from './model.js';
 import { Environment } from '@adhd/environment';
 
 /** The one type apigen special-cases via the `ctx-name-only` invariant. */
 export interface BacklogCtx {
     store: GraphBacklogStore;
     env: Environment<BacklogConfig>;
+    /**
+     * Test-isolation escape hatch ONLY — mirrors `BuildBacklogEnvOptions.adhdRoot`
+     * (the same value passed to `buildBacklogEnv({ adhdRoot })` when constructing
+     * `env`). NEVER set this in production code (`server.ts`/`cli.ts` never do).
+     * `setMigrationPhase` threads it through to `writeMigrationPhase` so a
+     * temp-rooted test `ctx` can never write to the real machine-global
+     * `~/.adhd` — omitting this on a real ctx write is exactly the bug
+     * `migration-admin.spec.ts`'s negative control caught (a test run wrote
+     * `phase-4` to the real `~/.adhd/backlog/production/config.yaml` before
+     * this field existed; reverted, see CHANGELOG).
+     */
+    adhdRoot?: string;
 }
 /**
  * Dedupe-scans (FTS + symbol/path/errorText metadata match) before writing.
@@ -70,3 +82,22 @@ export declare function renderToMarkdown(ctx: BacklogCtx, filter?: BacklogFilter
 export declare function exportJson(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
 /** Bi-temporal history + supersession chain. */
 export declare function auditTrail(ctx: BacklogCtx, repo: string, humanId: string): Promise<AuditTrailResult>;
+/**
+ * MIGRATION.md §4.4 — a QUERIED signal, never hardcoded prose: reports the
+ * live `migration.phase` config value (`env.ts`, env-overridable via
+ * `ADHD_BACKLOG_MIGRATION_PHASE`) plus a human-readable meaning, so an agent
+ * (or the `backlog-usage` skill) always asks the tool which of BACKLOG.md or
+ * the tool is authoritative right now, instead of trusting a stale doc
+ * sentence. NOT yet per-repo-keyed (MIGRATION.md §9 open decision 6) — one
+ * global value for the whole machine.
+ */
+export declare function migrationStatus(ctx: BacklogCtx): Promise<MigrationStatusResult>;
+/**
+ * MIGRATION.md §4.4's "admin CLI call" half: writes `migration.phase`
+ * THROUGH to the GLOBAL layer's `config.yaml` (`migration-admin.ts`) so the
+ * new value is a durable, cross-process, cross-repo signal — not merely an
+ * env var scoped to whoever's shell happened to export it. Whoever executes
+ * a phase's Definition of Done calls this exactly once, after verifying the
+ * DoD, never speculatively.
+ */
+export declare function setMigrationPhase(ctx: BacklogCtx, phase: MigrationPhase): Promise<SetMigrationPhaseResult>;

package/{env.d.ts → dist/env.d.ts}

@@ -4,10 +4,14 @@ import { Environment } from '@adhd/environment';
 export interface BacklogConfig {
     readonly db: {
         readonly path: string | undefined;
+        readonly busyTimeoutMs: number;
     };
     readonly logging: {
         readonly level: string;
     };
+    readonly migration: {
+        readonly phase: string;
+    };
 }
 export declare const backlogEnvironmentSpec: EnvironmentSpec<BacklogConfig>;
 /**

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { addCitation, addDependency, appendNote, archiveResolved, assignItem, attachToPlan, auditTrail, blockers, claimItem, createItem, dependencyGraph, exportJson, getItem, importFromMarkdown, linkRelated, listItems, mergeItems, migrationStatus, readyItems, releaseClaim, removeDependency, renderToMarkdown, renewClaim, resolveItem, setMigrationPhase, setPriority, softDeleteItem, spotlight, splitItem, staleClaims, startWork, stats, supersedeItem, topoOrder, transitionStatus, updateItem, } from './client.js';
+export type { BacklogCtx } from './client.js';
+export { startBacklogServer, buildBacklogApigenPackage } from './server.js';
+export type { StartOpts } from './server.js';
+export { runBacklogCli, resolveCommandPrefix, prefixCommand } from './cli.js';
+export type { RunBacklogCliOpts } from './cli.js';
+export { installSkill, runInstallSkillCommand } from './install-skill.js';
+export type { InstallSkillResult, SkillHost, SkillScope } from './install-skill.js';
+export { runServeCommand } from './serve.js';
+export type { RunServeCommandOpts } from './serve.js';
+export { buildBacklogEnv, resolveBacklogScope, suggestClaimantIdentity, backlogEnvironmentSpec } from './env.js';
+export type { BacklogConfig, BuildBacklogEnvOptions } from './env.js';
+export { openGraphBacklogStore, closeGraphBacklogStore } from './store/graph-backlog-store.js';
+export type { GraphBacklogStore } from './store/graph-backlog-store.js';
+export { buildChangelogSection, classifyStatus, detectPriority, detectStatus, normalizeLegacyStatus, parseBacklogMarkdown, parseBacklogMarkdownWithDiagnostics, renderItemsToMarkdown, toImportItems, } from './markdown.js';
+export type { ParsedImportItem, ParsedMarkdownItem, ParseWithDiagnosticsResult } from './markdown.js';
+export * from './model.js';