@adhd/backlog 0.1.8 → 1.0.0

package/cli.d.ts

@@ -94,11 +94,11 @@ export declare const USE_PLUGINS: readonly Plugin[];
 export declare function resolveMountNamespaces(usePlugins: readonly Plugin[], operations: readonly Operation[], host: string): Set<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', 'get-item']`).
+ * every `api.ts` export shares — see {@link resolveCommandPrefix}) to a
+ * user-typed argv, so `backlog get --input '{"uid":"…"}'` (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', 'get']`).
  *
  * Idempotent / defensive:
  *  - Empty argv is returned unchanged — `run()` treats `argv.length === 0`
@@ -130,20 +130,47 @@ export interface RunBacklogCliOpts {
     adhdRoot?: string;
     cwd?: string;
     signal?: AbortSignal;
+    /** Explicit-parameter-first namespace override — see
+     *  `BuildBacklogEnvOptions.namespace`'s doc comment and `--namespace`
+     *  (SPEC.md §5c). A parsed `--namespace <value>` (or a programmatic
+     *  caller's `optsIn.namespace`) sets this directly; a programmatic caller
+     *  may also pass it without going through argv at all. */
+    namespace?: string;
 }
 /**
- * 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.
+ * backlog CLI had no isolation mode at all originally, so trying a
+ * destructive or unfamiliar command meant either risking the real graph or
+ * hand-rolling env-var isolation (`ADHD_BACKLOG_SCOPE`/`ADHD_ROOT`) from
+ * scratch. `--namespace <value>` (SPEC.md §5c), recognized ANYWHERE in argv
+ * (like `--help`), strips itself out and validates against
+ * `backlogEnvironmentSpec.namespaces` (`'production'` | `'test'` |
+ * `'sandbox'`). Omitted ⇒ `'production'` (D2) — no behavior change for the
+ * overwhelmingly common case.
  *
- * @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.
+ * `--namespace sandbox` additionally layers ephemeral-root-minting on top of
+ * namespace selection (D5): it points the SAME `adhdRoot` test-isolation
+ * knob `BuildBacklogEnvOptions` already exposes (previously test-only —
+ * `cli.spec.ts`'s `runBin` is the proof this mechanism genuinely isolates)
+ * at a freshly created, per-invocation temp directory: `backlog --namespace
+ * sandbox create …` writes into a throwaway store, never the real one, and
+ * prints exactly where so a caller can inspect or clean it up. It is NOT
+ * auto-deleted — a caller may want to re-run further commands against the
+ * SAME sandbox by passing `ADHD_ROOT=<printed path>` explicitly on a later
+ * invocation; deleting it behind the caller's back the moment this process
+ * exits would defeat that.
  */
-export declare function runBacklogCli(argv?: string[], opts?: RunBacklogCliOpts): Promise<void>;
+export declare function stripNamespaceFlag(argv: readonly string[]): {
+    argv: string[];
+    namespace: string | undefined;
+    /** `true` iff `--namespace`/`--namespace=` was present but supplied no
+     *  value (bare trailing flag, or `--namespace=` with nothing after `=`) —
+     *  distinct from "flag absent" so the caller can reject it (D3) instead of
+     *  silently falling through to the default. */
+    missingValue: boolean;
+    /** `true` iff `--namespace`/`--namespace=` appeared MORE THAN ONCE with
+     *  two DIFFERING values. Every occurrence is always stripped from the
+     *  returned `argv` regardless of count. Two occurrences with the SAME
+     *  value are not a conflict (idempotent). */
+    conflicting: boolean;
+};
+export declare function runBacklogCli(argvIn?: string[], optsIn?: RunBacklogCliOpts): Promise<void>;

package/env.d.ts

@@ -9,8 +9,16 @@ export interface BacklogConfig {
     readonly logging: {
         readonly level: string;
     };
-    readonly migration: {
-        readonly phase: string;
+    /**
+     * RAG-SPEC.md §1.6 — the opt-in embedding/vector stack. `enabled` defaults
+     * to FALSE: an unconfigured build must behave exactly as it did before RAG
+     * existed (every semantic input answers `RagNotConfiguredError`, §5a), so
+     * a host opts IN deliberately and nothing is ever switched on implicitly.
+     */
+    readonly embedding: {
+        readonly enabled: boolean;
+        readonly provider: string;
+        readonly model: string;
     };
 }
 export declare const backlogEnvironmentSpec: EnvironmentSpec<BacklogConfig>;
@@ -24,16 +32,28 @@ export declare function resolveBacklogScope(explicit?: Scope): Scope;
  * `instanceId` exist purely for test isolation (constructing an `Environment`
  * rooted at a temp directory instead of the real machine's `~/.adhd`), mirror
  * `EnvironmentOptions`'s own test-isolation fields.
+ *
+ * `namespace` is EXPLICIT-PARAMETER-FIRST, deliberately with no env-var
+ * fallback (unlike `scope`'s `resolveBacklogScope` cascade above) — a
+ * namespace selection must be threaded as a real function parameter (CLI
+ * flag → this field → `EnvironmentOptions.namespace`), never resolved from
+ * ambient `process.env`, so it can never be silently defeated by a shell
+ * variable a caller forgot was set the way `ADHD_ROOT` previously defeated
+ * `--sandbox` (`BUG-BACKLOG-SANDBOX-SILENT-BYPASS-001`, cli.ts). Omitted ⇒
+ * `'production'` (the first-declared namespace — see `backlogEnvironmentSpec`
+ * — every existing caller that never passes this keeps resolving there,
+ * unchanged).
  */
 export interface BuildBacklogEnvOptions {
     scope?: Scope;
     adhdRoot?: string;
     cwd?: string;
     instanceId?: string;
+    namespace?: string;
 }
 export declare function buildBacklogEnv(options?: BuildBacklogEnvOptions): Environment<BacklogConfig>;
 /**
- * BUG-002: the effective SQLite backlog-graph DB path. Every store-open site
+ * BUG-002: the effective backlog graph DB path. Every store-open site
  * (`cli.ts`'s `runBacklogCli`, `server.ts`'s `startBacklogServer`) must
  * resolve the path through THIS helper — never `env.files.db` directly —
  * or a consumer setting `ADHD_BACKLOG_DATABASE_PATH` silently hits the

package/envelope.d.ts

@@ -0,0 +1,163 @@
+/**
+ * envelope.ts — the transport-facing response envelope: its closed error-code
+ * union, the exit codes a CLI host keys off, and the constructors/guards every
+ * surface (CLI, MCP, HTTP) branches on.
+ *
+ * **Why this is its own module.** This machinery previously lived in a
+ * 2,936-line god-module alongside the entire superseded application layer. It
+ * is the one piece of that module the replacement layer genuinely needs, so
+ * keeping it there meant the god-module could never be deleted. Nothing here
+ * depends on any item/store type — the envelope is deliberately about SHAPE,
+ * not about what is being carried — so it has zero internal imports and sits
+ * at the bottom of the dependency graph.
+ *
+ * **The error-code union is DERIVED, not curated.** The set below is exactly
+ * the image of {@link toEnvelopeCode}'s class→code mapping. That rule matters:
+ * an earlier attempt to prune the union by grepping for literal code strings
+ * found four codes "unused" and would have deleted two that are load-bearing,
+ * because codes are never written as literals at the throw site — they are
+ * produced by mapping a thrown error class. A code belongs here if and only if
+ * some error class maps to it. Add a class, add its code; delete the last
+ * class that maps to a code, delete the code.
+ */
+/**
+ * The closed union of envelope error codes.
+ *
+ * Each member names the error class(es) that produce it, so the derivation
+ * rule in this file's header can be checked by reading rather than inferred.
+ */
+export declare const BACKLOG_ERROR_CODES: readonly ["not_found", "item_not_found", "invalid_argument", "validation", "store_busy", "rag_not_configured", "conflict", "precondition_failed", "internal"];
+/** The closed union of envelope error codes. See {@link BACKLOG_ERROR_CODES}. */
+export type BacklogErrorCode = (typeof BACKLOG_ERROR_CODES)[number];
+/**
+ * Runtime membership test for the closed union. The union is only genuinely
+ * "closed" if something checks it at runtime — a transport that hand-built an
+ * envelope with a typo'd code would otherwise ship an error no agent can
+ * switch on, and TypeScript cannot see across a JSON boundary.
+ */
+export declare function isBacklogErrorCode(value: unknown): value is BacklogErrorCode;
+/**
+ * Error code → CLI process exit code.
+ *
+ * Verified against `@adhd/apigen-base-errors`' `CLI_EXIT_CODE`
+ * (`invalid_argument: 2, not_found: 4, internal: 1`); these codes extend that
+ * table without remapping any of it.
+ *
+ * The load-bearing property is that a caller can distinguish outcomes the
+ * exit code alone collapses: `item_not_found` and `internal` both exit 1, so
+ * they MUST remain distinct `code` values.
+ */
+export declare const BACKLOG_EXIT_CODE: Readonly<Record<BacklogErrorCode, number>>;
+/**
+ * `error.details`. `retryable`/`retryAfterMs` exist so an agent knows whether
+ * to retry a `store_busy` and with what backoff instead of hot-looping.
+ * Open-ended beyond those: individual codes attach their own evidence.
+ */
+export interface IOutcomeErrorDetails {
+    /** True only for transient codes (today: `store_busy`). */
+    retryable?: boolean;
+    /** Suggested backoff in milliseconds; only meaningful when `retryable`. */
+    retryAfterMs?: number;
+    /**
+     * Internal doc/plan reference for an `invalid_argument` whose underlying
+     * reason cites internal terminology (a plan id, a spec section) that does
+     * not belong in the user-facing `message`.
+     */
+    internalRef?: string;
+    [key: string]: unknown;
+}
+/** The error arm's payload. */
+export interface IOutcomeError {
+    code: BacklogErrorCode;
+    message: string;
+    details?: IOutcomeErrorDetails;
+}
+/**
+ * Pagination truth carried beside the data. `total` is the count BEFORE
+ * `limit`/`offset`; `returned` is `data.length`. A silently-truncated list is
+ * indistinguishable from a complete one unless the envelope says how many
+ * there really were.
+ */
+export interface IQueryEnvelopeMeta {
+    /** Matching rows before limit/offset — the TRUE count. */
+    total: number;
+    /** Rows actually in `data`. */
+    returned: number;
+    limit?: number;
+    offset?: number;
+    /**
+     * Set when the result set was cut short by anything other than the caller's
+     * own `limit`. A silent cap is forbidden — if it happens, it is stated here.
+     */
+    truncated?: boolean;
+}
+/** The success arm. `data` is always present (never `null` as a stand-in for "missing"). */
+export interface IOutcomeSuccess<T> {
+    ok: true;
+    data: T;
+    /** Non-fatal ambiguity surfaced at resolution time. A read NEVER silently narrows. */
+    warnings?: string[];
+    /** Present on list-shaped reads. */
+    meta?: IQueryEnvelopeMeta;
+}
+/** The failure arm. There is no `data` on this arm at all. */
+export interface IOutcomeFailure {
+    ok: false;
+    error: IOutcomeError;
+    warnings?: string[];
+}
+/**
+ * THE response envelope for every mounted verb.
+ *
+ * A `void`/`null` return is rendered by apigen as `{"result": null}` for BOTH
+ * success and failure, which makes a write unverifiable. This union has no arm
+ * that can express that: success carries `data`, failure carries `error`, and
+ * `ok` discriminates them.
+ *
+ * It is a discriminated union rather than `{ ok, data?, error? }` on purpose —
+ * `{ ok: true, data: null }` for a missing item is not assignable when `T` is
+ * a real item type.
+ */
+export type IOutcomeEnvelope<T> = IOutcomeSuccess<T> | IOutcomeFailure;
+/** Narrow an envelope to its success arm. */
+export declare function isOutcomeOk<T>(env: IOutcomeEnvelope<T>): env is IOutcomeSuccess<T>;
+/**
+ * Narrow an envelope to its failure arm.
+ *
+ * Deliberately structural (`ok === false` AND a well-formed `error`) — a
+ * malformed half-envelope is neither ok nor a usable error, and callers must
+ * not treat it as success by accident.
+ */
+export declare function isOutcomeError<T>(env: IOutcomeEnvelope<T>): env is IOutcomeFailure;
+/** Build a success envelope. */
+export declare function okEnvelope<T>(data: T, extra?: {
+    warnings?: string[];
+    meta?: IQueryEnvelopeMeta;
+}): IOutcomeSuccess<T>;
+/** Build a failure envelope. `store_busy` is stamped retryable by default. */
+export declare function errorEnvelope(code: BacklogErrorCode, message: string, details?: IOutcomeErrorDetails): IOutcomeFailure;
+/** The process exit code a CLI host must use for an envelope. Success is always 0. */
+export declare function exitCodeForEnvelope<T>(env: IOutcomeEnvelope<T>): number;
+/**
+ * Structural guard for a value that came back from a transport, where the
+ * static type is erased. Recognises BOTH arms.
+ *
+ * Used by the CLI's `options.exitCode` hook — a non-envelope result (a `--use`
+ * mount, a plugin's own synthetic op) must fall through to apigen's default
+ * exit-0-on-return, never be mapped by this table.
+ */
+export declare function isOutcomeEnvelope(value: unknown): value is IOutcomeEnvelope<unknown>;
+/** Why a similarity-ranked read cannot be served. */
+export type RagUnavailableReason = 'not_configured' | 'empty_vector_space';
+/**
+ * A similarity-ranked read was requested but cannot be served.
+ *
+ * Distinguishes "no backend at all" from "a backend exists but nothing has
+ * been embedded yet" — an unbackfilled space would otherwise return an empty
+ * result set, which reads as "no matches" when the truth is "this ranking is
+ * not available." Reporting it as disabled is the honest answer.
+ */
+export declare class RagNotConfiguredError extends Error {
+    readonly reason: RagUnavailableReason;
+    constructor(feature: string, reason?: RagUnavailableReason);
+}

package/index.d.ts

@@ -1,17 +1,18 @@
-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, version, } from './client.js';
-export type { BacklogCtx, BacklogVersionInfo } from './client.js';
-export { startBacklogServer, buildBacklogApigenPackage } from './server.js';
+export { get, query, priorityMatrix, partOfRollup, openCurve, lookup, create, update, transition, claim, relate, move, upsertProject, upsertComponent, upsertLocation, rmLocation, delete, } from './api.js';
+export type { BacklogCtx } from './api.js';
+export * from './envelope.js';
+export { startBacklogServer, buildBacklogApigenPackage, resolveExpectedMcpToolNames, } from './server.js';
 export type { StartOpts } from './server.js';
-export { runBacklogCli, resolveCommandPrefix, prefixCommand } from './cli.js';
+export { runBacklogCli, resolveCommandPrefix, prefixCommand, stripNamespaceFlag, } from './cli.js';
 export type { RunBacklogCliOpts } from './cli.js';
+export { buildSearchArgv, SEARCH_FLAGS, SEARCH_HELP, } from './search-shortcut.js';
+export type { SearchShortcutOutcome } from './search-shortcut.js';
 export { installSkill, runInstallSkillCommand } from './install-skill.js';
-export type { InstallSkillResult, SkillHost, SkillScope } 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, resolveBacklogDbPath, suggestClaimantIdentity, backlogEnvironmentSpec } from './env.js';
+export { buildBacklogEnv, resolveBacklogScope, resolveBacklogDbPath, suggestClaimantIdentity, backlogEnvironmentSpec, } from './env.js';
 export type { BacklogConfig, BuildBacklogEnvOptions } from './env.js';
-export { openGraphBacklogStore, closeGraphBacklogStore } from './store/graph-backlog-store.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';
+export { readBacklogVersionInfo } from './version-info.js';