@adhd/backlog 0.0.2 → 0.1.1

package/CHANGELOG.md

@@ -1 +1,66 @@
+## 0.1.1 (2026-07-27)
+
+
+### 🩹 Fixes
+
+- **backlog:** fix published tarball crashing at mount — `backlogDistDir()` resolved `client.d.ts` via `import.meta.url + '../dist'`, which escaped to the nonexistent `node_modules/@adhd/dist` once `dist-manifest` rebased the package to its root; now probes for the sibling `client.d.ts` (BUG-012). Adds `server.published-layout.spec.ts` reproducing the published rebased-to-root layout.
+
+
+### ❤️  Thank You
+
+- pseudosky
+
+## 0.0.3 (2026-07-25)
+
+
+### 🩹 Fixes
+
+- **apigen,backlog:** killable serve, configurable namespace, flaky test + log spam
+
+- **backlog:** match archived-item exclusion between render and its verify
+
+
+### ❤️  Thank You
+
+- pseudosky
+
+## 0.0.2 (2026-07-24)
+
+
+### 🚀 Features
+
+- **backlog:** add CLI entrypoint + bin (live apigen cli-output mount)
+
+- **backlog:** add migration.phase signal + migrationStatus op (MIGRATION.md §4.4)
+
+- **backlog:** Phase 1/2 apigen import + CI parity gate + durable migration.phase admin write
+
+- **backlog:** author backlog-usage skill + install-skill CLI (MIGRATION.md sec 4.2/4.3)
+
+- **backlog:** add `serve` CLI command so .mcp.json has a real entry to spawn (MIGRATION.md sec 4.5)
+
+- **backlog:** rootLevel projection filter so new tool items reach root
+
+
+### 🩹 Fixes
+
+- **backlog:** close Phase-3 migration gate — CI Node floor, content-hash collision verified, FTS content immutability, bounded busy-retry; plus import provenance/silent-drop fixes
+
+- **backlog:** runBacklogCli no longer eagerly opens the store for --help/no-args (DEBT-BACKLOG-CLI-EAGER-STORE-OPEN-001)
+
+- **backlog:** concurrent createItem id-collision + FTS sanitizer gap (MIGRATION.md sec 3.3 scale test)
+
+- **backlog:** implement real transition/claim audit-log (DEBT-BACKLOG-AUDIT-TRAIL-PARTIAL-001)
+
+- **backlog:** importFromMarkdown upserts on re-import instead of insert-only
+
+- **backlog:** sourcepath-ownership gate for importFromMarkdown (DEBT-BACKLOG-IMPORT-SCOPE-CROSSFILE-001)
+
+- **backlog:** re-import backfills ownership + resurrects superseded ids
+
+
+### ❤️  Thank You
+
+- pseudosky
+
 ## Unreleased

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

@@ -8,33 +8,22 @@ import { Scope } from '@adhd/environment-base-spec';
  * `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.
+ * Currently simply `['backlog']`: `server.ts`'s `extractClientOperations()`
+ * calls `extract({ …, dropFileSegment: true })`, so every `client.ts`
+ * export's `path` is just `[exportSegment]` (no `client.d.ts`-derived
+ * `'client-d'` segment — see that call site's doc comment for why it's safe
+ * to drop here: one source file, no cross-file names to disambiguate), and
+ * `project(op).cli.path` is `['backlog', '<kebab-export-name>']`.
  *
- * 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.
+ * This is still derived from the live `operations` list rather than
+ * hardcoded, on purpose: since every `client.ts` export shares the same
+ * namespace + same source, 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
+ * on every call (never cached as a literal) so a future change to the
+ * extraction call site (e.g. re-enabling the file segment, or adding a
+ * second source file) can never silently desync this from the real command
+ * table the way a hardcoded `['backlog']` constant would.
  */
 export declare function resolveCommandPrefix(operations: readonly Operation[]): string[];
 /**
@@ -43,7 +32,7 @@ export declare function resolveCommandPrefix(operations: readonly Operation[]):
  * 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']`).
+ * the FULL internal path (`['backlog', 'get-item']`).
  *
  * Idempotent / defensive:
  *  - Empty argv is returned unchanged — `run()` treats `argv.length === 0`

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

@@ -26,7 +26,23 @@ export interface BacklogCtx {
  * idOverride is given.
  */
 export declare function createItem(ctx: BacklogCtx, input: CreateItemInput): Promise<CreateItemResult>;
-/** repo is required — humanId alone is not globally unique. */
+/**
+ * repo is required — humanId alone is not globally unique. A genuine miss
+ * (humanId doesn't exist under ANY repo) still returns `null` — unchanged,
+ * every existing caller relying on nullable-not-throwing keeps working.
+ *
+ * BUG-BACKLOG-REPO-LOOKUP-UX-001: previously a repo/humanId MISMATCH (the
+ * item is live, just filed under a different `repo` string) was
+ * indistinguishable from a genuine miss — both silently returned `null`,
+ * which is worse than `appendNote`'s bare-but-at-least-thrown
+ * `BacklogItemNotFoundError` (and, before this fix, could surface through
+ * apigen's MCP layer as the unrelated broken int64/null encoding,
+ * BUG-APIGEN-LOGICAL-NULL-OBJECT-RESULT-INT64-001 — out of scope here, but
+ * this fix removes the only path that made this lookup look like that bug).
+ * Now: a real cross-repo match THROWS the same informative
+ * `BacklogItemNotFoundError` (with `foundInRepos` naming the actual repo) the
+ * mutating lookups already throw, instead of masquerading as "not found".
+ */
 export declare function getItem(ctx: BacklogCtx, repo: string, humanId: string): Promise<BacklogItem | null>;
 export declare function updateItem(ctx: BacklogCtx, repo: string, humanId: string, patch: UpdateItemInput): Promise<BacklogItem>;
 export declare function listItems(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
@@ -77,7 +93,16 @@ export declare function setPriority(ctx: BacklogCtx, repo: string, humanId: stri
 /** MEMBER_OF edge to a plan node (auto-created if the plan slug hasn't been seen before). */
 export declare function attachToPlan(ctx: BacklogCtx, repo: string, humanId: string, planSlug: string): Promise<void>;
 export declare function importFromMarkdown(ctx: BacklogCtx, input: ImportMarkdownInput): Promise<ImportResult>;
-/** Excludes archived items (SPEC.md §5.4 archiveResolved) — see markdown.ts's renderItemsToMarkdown doc comment. */
+/**
+ * Excludes archived items (SPEC.md §5.4 archiveResolved) — see markdown.ts's
+ * renderItemsToMarkdown doc comment. Archival exclusion goes through
+ * `BacklogFilter.excludeArchived` (query.ts's `applyExcludeArchivedFilter`)
+ * rather than a private scan here, so a caller comparing this output
+ * against `listItems`/`queryItemNodes` for the SAME filter (e.g.
+ * `render-projections.mjs`'s round-trip verify) can reproduce this exact
+ * item set by passing `{ ...filter, excludeArchived: true }` themselves —
+ * see BUG-BACKLOG-RENDER-VERIFY-ARCHIVED-MISMATCH-001.
+ */
 export declare function renderToMarkdown(ctx: BacklogCtx, filter?: BacklogFilter): Promise<string>;
 export declare function exportJson(ctx: BacklogCtx, filter?: BacklogFilter): Promise<BacklogItem[]>;
 /** Bi-temporal history + supersession chain. */