@adhd/backlog 0.1.3 → 0.1.4

package/cli.d.ts

@@ -1,4 +1,4 @@
-import { Operation } from '@adhd/apigen-core-client';
+import { Operation, Plugin } from '@adhd/apigen-core-client';
 import { Scope } from '@adhd/environment-base-spec';
 
 /**
@@ -26,6 +26,72 @@ import { Scope } from '@adhd/environment-base-spec';
  * table the way a hardcoded `['backlog']` constant would.
  */
 export declare function resolveCommandPrefix(operations: readonly Operation[]): string[];
+/**
+ * The exact `--use` mount-plugin array `runBacklogCli` hands to
+ * `cliPlugin.run()`'s `options.usePlugins` AND the array
+ * {@link resolveMountNamespaces} derives reserved top-level segments from —
+ * the SAME array reference, never two independently-written lists, so the
+ * two can never drift apart (that drift is exactly what made the old
+ * hand-maintained `MOUNT_COMMAND_NAMESPACES` constant go stale).
+ */
+export declare const USE_PLUGINS: readonly Plugin[];
+/**
+ * Derives the set of top-level command segments reserved by every mount
+ * plugin in `usePlugins`' own synthetic operations, registered SIBLING to
+ * (never nested under) `backlog`'s own `['backlog', ...]` namespace.
+ *
+ * Previously this repo (BUG-BACKLOG-CLI-BATCH-PREFIX-CLOBBER-001) hand-
+ * maintained a `MOUNT_COMMAND_NAMESPACES` constant with a doc comment
+ * claiming a mount plugin's real synthetic namespace "can only be known by
+ * actually invoking its `capabilities.mount.operations(descriptor, …)`, which
+ * needs a real `Descriptor` this file does not have before dispatch" — that
+ * claim was WRONG, verified by reading source rather than assumed:
+ *
+ *  1. `runBacklogCli` DOES have a real descriptor's ingredients at the exact
+ *     point this is called — `operations` (from `buildBacklogApigenPackage`)
+ *     is real, already-extracted `Operation[]`, and the host string is the
+ *     same `pkg.id` (`'backlog'`) that
+ *     `apigen-plugin-cli-output`'s `run()` itself uses for the identical
+ *     purpose (`packages/apigen/apigen-plugin-cli-output/src/lib/run.ts`:
+ *     `const mountHost = input.packages[0]?.id ?? 'ts';`).
+ *  2. `batchPlugin.capabilities.mount.operations(descriptor, opts, hostBridge)`
+ *     (`packages/apigen/apigen-plugin-batch/src/lib/plugin.ts`,
+ *     `buildBatchOperations`) delegates to `buildBatchMountedOperations`
+ *     (`packages/apigen/apigen-core-client/src/lib/batch.ts`) to compute
+ *     every mounted operation's SHAPE — including `namespace`/`path`, since
+ *     `MountedOperation extends Operation`
+ *     (`apigen-core-client/src/lib/plugin.ts:422`) — and only uses
+ *     `hostBridge` AFTERWARD, separately, to build each shape's `.handler`
+ *     (`buildBatchHandler(shape.operationIds, hostBridge)`, same file). The
+ *     handler closure simply captures `hostBridge` (including `undefined`)
+ *     without dereferencing it — `buildBatchOperations`/`operations()` never
+ *     throw when `hostBridge` is omitted; only actually CALLING the built
+ *     handler with a missing bridge throws
+ *     (`packages/apigen/apigen-plugin-batch/src/lib/plugin.ts:148`,
+ *     `if (!hostBridge) { throw … }` inside `buildBatchHandler`, never
+ *     inside `operations()`). So calling `operations(descriptor, opts)` with
+ *     `hostBridge` omitted is safe for path-derivation purposes: the
+ *     returned ops' handlers would be broken if invoked, but this function
+ *     never invokes them, only reads `.namespace`/`.path`.
+ *  3. `buildBatchMountedOperations` (`apigen-core-client/src/lib/batch.ts`)
+ *     is cheap — it groups already-extracted `descriptor.operations` by kind
+ *     and derives JSON-Schema fragments from them; it does no ts-morph
+ *     parsing or schema generation of its own, so calling it once per CLI
+ *     invocation (in addition to the identical call `run()` itself makes
+ *     later) has no measurable cost.
+ *
+ * So this is derived dynamically instead: for each plugin in `usePlugins`
+ * exposing a `mount` capability, call `capabilities.mount.operations(...)`
+ * (no `hostBridge`) and project each returned op's real CLI top-level
+ * segment via `@adhd/apigen-engine-naming`'s `project(op).cli.path[0]` — the
+ * SAME derivation `resolveCommandPrefix` above uses for `backlog`'s own
+ * prefix. Adding a future mount plugin to {@link USE_PLUGINS} now
+ * automatically and correctly extends the reserved set with zero separate
+ * bookkeeping — it can never again silently go stale the way the old
+ * hardcoded set did the moment a second mount plugin was added without
+ * remembering to update it too.
+ */
+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
@@ -44,8 +110,20 @@ export declare function resolveCommandPrefix(operations: readonly Operation[]):
  *    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`.
+ *  - Argv whose first token is a reserved mount-namespace segment (per
+ *    {@link resolveMountNamespaces}'s dynamically-derived set — currently
+ *    just `batch`, from {@link USE_PLUGINS}) is returned unchanged — that
+ *    command is registered at the CLI's top level by a mount plugin, never
+ *    under `backlog`'s own namespace; prefixing it would make it
+ *    unresolvable.
+ *
+ * `reservedNamespaces` has no default — the real call site
+ * (`runBacklogCli`) always passes a freshly-derived
+ * `resolveMountNamespaces(...)` result; the caller must supply one
+ * explicitly (an empty `Set` for a caller with no mount plugins) so this
+ * can never silently fall back to a stale hardcoded default.
  */
-export declare function prefixCommand(userArgv: readonly string[], prefix: readonly string[]): string[];
+export declare function prefixCommand(userArgv: readonly string[], prefix: readonly string[], reservedNamespaces: ReadonlySet<string>): string[];
 export interface RunBacklogCliOpts {
     scope?: Scope;
     /** Test-only override — see `buildBacklogEnv`'s `BuildBacklogEnvOptions`. */

package/client.d.ts

@@ -126,3 +126,20 @@ export declare function migrationStatus(ctx: BacklogCtx): Promise<MigrationStatu
  * DoD, never speculatively.
  */
 export declare function setMigrationPhase(ctx: BacklogCtx, phase: MigrationPhase): Promise<SetMigrationPhaseResult>;
+export interface BacklogVersionInfo {
+    /** This package's real `package.json` name, e.g. `"@adhd/backlog"`. */
+    name: string;
+    /** This package's real `package.json` version — never hardcoded. */
+    version: string;
+}
+/**
+ * Reports this running package's own real `name`/`version`, read fresh from
+ * `package.json` on every call (never a compiled-in constant, so a
+ * republished build can never drift from what this reports). `ctx` is
+ * unused — kept for signature consistency with every other `client.ts`
+ * export (the `ctx-name-only` invariant every extraction/mount/CLI-dispatch
+ * path in this package assumes, per this file's own top-of-file doc
+ * comment) rather than special-casing a bare, ctx-less export whose
+ * extraction/dispatch behavior has not been verified.
+ */
+export declare function version(ctx: BacklogCtx): Promise<BacklogVersionInfo>;

package/index.d.ts

@@ -1,5 +1,5 @@
-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 { 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 type { StartOpts } from './server.js';
 export { runBacklogCli, resolveCommandPrefix, prefixCommand } from './cli.js';