@adhd/backlog 0.0.2 → 0.1.1

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

@@ -61,8 +61,19 @@ export interface BacklogItem {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * BUG-BACKLOG-REPO-LOOKUP-UX-001: a `(repo, humanId)` miss is frequently NOT
+ * "this item doesn't exist" but "this item exists under a DIFFERENT `repo`
+ * string" (e.g. `"adhd"` vs `"PseudoSky/adhd"` both live in the same store
+ * for what is logically one project). `foundInRepos` — populated by
+ * `store/query.ts`'s `buildNotFoundError` helper, which every throw site now
+ * calls instead of constructing this directly — carries the OTHER repo
+ * value(s) the humanId actually lives under, so the thrown message names the
+ * fix instead of leaving the caller to guess.
+ */
 export declare class BacklogItemNotFoundError extends Error {
-    constructor(repo: string, humanId: string);
+    readonly foundInRepos: string[];
+    constructor(repo: string, humanId: string, foundInRepos?: string[]);
 }
 export declare class CitationRequiredError extends Error {
     constructor(status: BacklogStatus);
@@ -104,6 +115,14 @@ export interface CreateItemResult {
     item: BacklogItem;
     created: boolean;
     duplicateCandidates: BacklogItem[];
+    /**
+     * BUG-BACKLOG-REPO-LOOKUP-UX-001: set (soft warning, never blocks the
+     * write) when `input.repo` doesn't match any repo value already known to
+     * this store — a likely typo/inconsistent-repo-string drift (e.g. filing
+     * under `"adhd"` when every existing item uses `"PseudoSky/adhd"`) rather
+     * than a genuine first-time-use of a new repo, which is always allowed.
+     */
+    repoWarning?: string;
 }
 export interface UpdateItemInput {
     title?: string;
@@ -155,6 +174,19 @@ export interface BacklogFilter {
      * duplicated into root.
      */
     rootLevel?: boolean;
+    /**
+     * Drops items with `metadata.archivedAt` set (BACKLOG-adoption's
+     * `archiveResolved` — SPEC.md §5.4). `renderToMarkdown` always applies
+     * this internally (a markdown projection never shows archived rows), but
+     * `listItems`/`queryItemNodes` do NOT default to it — auditing/reporting
+     * consumers legitimately need to see archived items too. A caller that
+     * needs to reproduce `renderToMarkdown`'s exact item set through
+     * `listItems` (e.g. `render-projections.mjs`/`parity-check.mjs` verifying
+     * a rendered projection against the graph's own view of the same filter —
+     * BUG-BACKLOG-RENDER-VERIFY-ARCHIVED-MISMATCH-001) must set this
+     * explicitly; otherwise the two queries diverge on every archived row.
+     */
+    excludeArchived?: boolean;
     limit?: number;
     offset?: number;
 }
@@ -269,6 +301,8 @@ export interface ImportResult {
     }>;
     /** Headers that look like a corrupted/typo'd id and were dropped instead of parsed — never silent (DEBT-BACKLOG-IMPORT-SILENT-DROP-001). */
     malformedHeaders: MalformedHeaderInfo[];
+    /** See `CreateItemResult.repoWarning` (BUG-BACKLOG-REPO-LOOKUP-UX-001) — computed once for `input.repo`, not per item. */
+    repoWarning?: string;
 }
 export interface AuditTrailEntry {
     at: string;

package/package.json

@@ -1,34 +1,29 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "bin": {
-    "backlog": "./dist/index.js"
+    "backlog": "index.js"
   },
   "dependencies": {
     "@adhd/sox-graph-store": "^0.3.0",
     "better-sqlite3": "^12.10.0",
-    "@adhd/environment": "0.0.2",
-    "@adhd/environment-base-spec": "0.0.3",
-    "@adhd/apigen-core-client": "^0.1.1",
-    "@adhd/apigen-plugin-api-fastify": "^0.1.2",
-    "@adhd/apigen-plugin-openapi": "^0.1.3",
-    "@adhd/apigen-plugin-mcp": "^0.1.2",
-    "@adhd/apigen-plugin-cli-output": "^0.1.3",
-    "@adhd/apigen-engine-naming": "^0.1.3",
-    "yaml": "1.10.3"
+    "@adhd/environment": "^0.1.1",
+    "@adhd/environment-base-spec": "^0.1.0",
+    "@adhd/apigen-core-client": "^0.2.1",
+    "@adhd/apigen-plugin-api-fastify": "^0.2.1",
+    "@adhd/apigen-plugin-openapi": "^0.2.1",
+    "@adhd/apigen-plugin-mcp": "^0.2.1",
+    "@adhd/apigen-plugin-batch": "^0.2.0",
+    "@adhd/apigen-plugin-cli-output": "^0.2.1",
+    "@adhd/apigen-engine-naming": "^0.2.1",
+    "yaml": "1.10.3",
+    "pino": "10.3.1",
+    "pino-pretty": "13.1.3"
   },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "typings": "./dist/index.d.ts",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
   "publishConfig": {
     "access": "public"
-  },
-  "files": [
-    "dist",
-    "CHANGELOG.md",
-    "skill"
-  ]
+  }
 }

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

@@ -1,5 +1,5 @@
 import { BacklogCtx } from './client.js';
-import { composeSchemas, Operation, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
+import { composeSchemas, Operation, Logger, OutputPlugin, RunInput } from '@adhd/apigen-core-client';
 import { Scope } from '@adhd/environment-base-spec';
 
 /**
@@ -13,6 +13,30 @@ import { Scope } from '@adhd/environment-base-spec';
  * plain re-export instead.
  */
 export declare function requireRun(plugin: OutputPlugin): (input: RunInput) => Promise<void>;
+/**
+ * Test-only `RunInput.logger` override (exported for `cli.ts`'s identical
+ * third-transport mount). Every one of the three apigen output plugins
+ * (`apigen-plugin-api-fastify`, `-mcp`, `-cli-output`) falls back to its own
+ * `createLogger()` — real pino, level `info`, writing jsonl to stderr —
+ * whenever `input.logger` is absent, which floods the console on every test
+ * run that actually mounts a transport (`server.spec.ts`, `server.mcp.spec.ts`,
+ * `serve.spec.ts`, and `cli.spec.ts`'s spawned-binary cases, since
+ * `spawnSync`'s `env: { ...process.env }` inherits vitest's own
+ * `VITEST=true`). None of those specs assert on log content — they assert
+ * status codes and response bodies — so under vitest this swaps in a no-op
+ * logger. `mcpPlugin`/`cliPlugin` only ever call `.info`/`.error` on it, but
+ * `apiFastifyPlugin` hands it straight to `Fastify({ logger })`, whose own
+ * `validateLogger` (`fastify/lib/logger.js`) REQUIRES the full pino surface
+ * (`info,error,debug,fatal,warn,trace,child`) or throws
+ * `FST_ERR_LOG_INVALID_LOGGER` — confirmed empirically, not guessed, by a
+ * first cut here that only stubbed `info`/`error` and blew up every
+ * `server.spec.ts` HTTP test with exactly that error. `child()` returns the
+ * same no-op instance (fastify calls it per-request to derive a child
+ * logger; a self-referencing no-op keeps every descendant silent too).
+ * Outside vitest (a real `backlog serve` or CLI invocation) this returns
+ * `undefined` and the real pino default logger is used, unchanged.
+ */
+export declare function testSilentLogger(): Logger | undefined;
 export interface StartOpts {
     transport: 'http' | 'mcp' | 'both';
     port?: number;

package/{dist/store → store}/query.d.ts

@@ -1,12 +1,38 @@
 import { BacklogNodeMeta } from './mapping.js';
 import { GraphBacklogStore } from './graph-backlog-store.js';
-import { AuditTrailResult, BacklogFilter, BacklogItem, DependencyGraph, StatsScope, TopoOrderResult } from '../model.js';
+import { AuditTrailResult, BacklogFilter, BacklogItem, DependencyGraph, StatsScope, TopoOrderResult, BacklogItemNotFoundError } from '../model.js';
 import { NodeRecord } from '@adhd/sox-graph-store';
 
 /** Raw NodeRecord query — used internally where the full node (not just the mapped BacklogItem) is needed. */
 export declare function queryItemNodes(store: GraphBacklogStore, filter?: BacklogFilter): NodeRecord[];
 export declare function listItems(store: GraphBacklogStore, filter?: BacklogFilter): BacklogItem[];
 export declare function findItemNode(store: GraphBacklogStore, repo: string, humanId: string): NodeRecord | null;
+/**
+ * Finds every LIVE node carrying this `humanId`, across ALL repos (no
+ * `namespace` filter) — BUG-BACKLOG-REPO-LOOKUP-UX-001's "did you mean repo
+ * X?" hint needs this to distinguish "this humanId truly doesn't exist" from
+ * "it exists, just filed under a different repo string than the caller
+ * passed." Used only on the miss path (`buildNotFoundError`) — never on the
+ * hot successful-lookup path, so it costs nothing when a lookup is correct.
+ */
+export declare function findHumanIdInAnyRepo(store: GraphBacklogStore, humanId: string): NodeRecord[];
+/**
+ * Every distinct repo value any LIVE backlog item is currently filed under.
+ * Used by `createItemNode`'s soft repo-drift warning (write-time half of
+ * BUG-BACKLOG-REPO-LOOKUP-UX-001) — an empty store (no items yet) has no
+ * "known" repos, so the very first item filed under any repo string never
+ * triggers a false-positive warning.
+ */
+export declare function knownRepos(store: GraphBacklogStore): Set<string>;
+/**
+ * Builds the `BacklogItemNotFoundError` every miss site throws — the single
+ * place that decides whether a "did you mean repo X?" hint is warranted
+ * (BUG-BACKLOG-REPO-LOOKUP-UX-001, read-time half). Callers pass the SAME
+ * `(repo, humanId)` they just failed to find via `findItemNode` — this
+ * re-queries WITHOUT the `namespace` restriction to see if the humanId lives
+ * under a different repo string instead.
+ */
+export declare function buildNotFoundError(store: GraphBacklogStore, repo: string, humanId: string): BacklogItemNotFoundError;
 export declare function computeStats(store: GraphBacklogStore, scope?: StatsScope): import('../model.js').BacklogStats;
 export declare function spotlight(store: GraphBacklogStore, scope?: StatsScope, limit?: number): BacklogItem[];
 export declare function blockers(store: GraphBacklogStore, repo: string, humanId: string): BacklogItem[];