@adhd/backlog 0.1.0 → 0.1.1

package/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;
@@ -282,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,20 +1,21 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bin": {
     "backlog": "index.js"
   },
   "dependencies": {
     "@adhd/sox-graph-store": "^0.3.0",
     "better-sqlite3": "^12.10.0",
-    "@adhd/environment": "^0.1.0",
+    "@adhd/environment": "^0.1.1",
     "@adhd/environment-base-spec": "^0.1.0",
-    "@adhd/apigen-core-client": "^0.2.0",
-    "@adhd/apigen-plugin-api-fastify": "^0.2.0",
-    "@adhd/apigen-plugin-openapi": "^0.2.0",
-    "@adhd/apigen-plugin-mcp": "^0.2.0",
-    "@adhd/apigen-plugin-cli-output": "^0.2.0",
-    "@adhd/apigen-engine-naming": "^0.2.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"

package/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[];