@noesis-brain/mcp-server 2.0.0 → 2.1.0

package/dist/resolve/noteRef.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Unified note-reference resolution (single-vault refactor, M1).
+ *
+ * Pure logic — no network, no filesystem, no process state. Everything the
+ * resolver needs arrives in a ResolverContext built by the caller (M2 wires
+ * this to `GET /api/mcp/roots?includeArchived=1`, which since V3 returns the
+ * archived translation entries plus `{vault_root_id, device_home_dirs}`).
+ *
+ * Accepted reference forms (the plan's reference grammar):
+ *   - note URLs on any host:  https://noesisbrain.com/notes/2761[#bm=...]
+ *   - noesis://note/2761[/optional-slug]
+ *   - bare numeric ids: "2761"
+ *   - absolute paths of ANY OS shape: /Users/me/Noesis/x.md,
+ *     c:/Users/me/Noesis/x.md, C:\temp_cGit\.noesis\x.md
+ *   - tilde / %USERPROFILE% forms: ~/Noesis/x.md, %USERPROFILE%\Noesis\x.md
+ *   - LEGACY pre-migration absolute paths, translated through archived roots
+ *     (vault_subfolder + '.noesis/'-collapse candidates, collapsed first)
+ *
+ * Fixes the pre-M1 footgun where a root with an empty current-OS path
+ * resolved to process.cwd(): empty/missing slots never produce a comparable
+ * form here, and local paths are composed (never path.resolve'd) from a
+ * verified non-empty base.
+ */
+export type OsKey = 'win32' | 'darwin' | 'linux';
+export interface ResolverRoot {
+    id: number;
+    name: string;
+    local_paths: Record<string, string>;
+    archived_at?: string | null;
+    vault_subfolder?: string | null;
+}
+export interface ResolverContext {
+    /** This machine's OS family (CLIENT_OS). */
+    clientOs: OsKey;
+    /** This machine's home directory (os.homedir()). */
+    homeDir: string;
+    /** The user's designated vault root id (V3 roots meta), if known. */
+    vaultRootId: number | null;
+    /** Per-OS home dirs of the user's machines (V3 roots meta), if known. */
+    deviceHomeDirs: Record<string, string> | null;
+    /** Active + archived roots (GET /roots?includeArchived=1). */
+    roots: ResolverRoot[];
+}
+export type NoteRef = {
+    kind: 'id';
+    id: number;
+} | {
+    kind: 'path';
+    path: string;
+};
+export interface ResolvedPathRef {
+    /** Root to look candidates up under (the matched root, or the vault). */
+    rootId: number;
+    /** relative_path candidates, in lookup priority order. */
+    candidates: string[];
+    via: 'active-root' | 'legacy-translation';
+    /** Set when the input matched an archived root. */
+    archivedRootId?: number;
+}
+/** Forward slashes + lowercase drive letter (win32 canonical compare form). */
+export declare function normalizePath(p: string): string;
+/** Shape-sniff which OS family a path belongs to (mirrors the backend). */
+export declare function detectPathOsKey(p: string): OsKey;
+/**
+ * Parse an input string into a note reference. URLs and ids resolve by note
+ * id (the caller fetches the note to learn its relative_path); everything
+ * else is treated as a path.
+ */
+export declare function parseNoteReference(input: string): NoteRef;
+interface ComparableForm {
+    cmp: string;
+    orig: string;
+}
+/**
+ * Comparable spellings of one path under an OS family: the normalized raw
+ * form plus one home-expanded form per known home dir for that family (this
+ * machine's home when the family is the client OS, and the cloud-cached
+ * device home). Empty inputs produce NO forms (the cwd-footgun fix).
+ */
+export declare function comparableForms(p: string | null | undefined, osKey: OsKey, homes: string[]): ComparableForm[];
+/**
+ * Resolve a path-form reference against the context's roots: longest-prefix
+ * across active + archived roots on the sniffed OS family, tilde/home
+ * expansion on both sides, legacy translation into the vault for archived
+ * matches. Null when nothing matches (or an archived match has no
+ * translation target).
+ */
+export declare function resolvePathReference(ctx: ResolverContext, inputPath: string): ResolvedPathRef | null;
+/**
+ * The local base directory (this machine, CLIENT_OS) of a root — tilde-form
+ * expanded against THIS machine's home dir — or null when the root has no
+ * usable path on this OS (never a cwd-relative guess).
+ */
+export declare function rootLocalBase(ctx: ResolverContext, rootId: number): string | null;
+/**
+ * The local absolute path (this machine, CLIENT_OS) for a note of `rootId` at
+ * `relativePath` — or null when that root has no usable path on this OS.
+ */
+export declare function localAbsFor(ctx: ResolverContext, rootId: number, relativePath: string): string | null;
+export {};
+//# sourceMappingURL=noteRef.d.ts.map

package/dist/resolve/noteRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noteRef.d.ts","sourceRoot":"","sources":["../../src/resolve/noteRef.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,QAAQ,EAAE,KAAK,CAAC;IAChB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,8DAA8D;IAC9D,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAAC;IAC1C,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,CAKhD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAgBzD;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAiB7G;AAYD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAwCpG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAejF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrG"}

package/dist/resolve/noteRef.js

@@ -0,0 +1,186 @@
+/**
+ * Unified note-reference resolution (single-vault refactor, M1).
+ *
+ * Pure logic — no network, no filesystem, no process state. Everything the
+ * resolver needs arrives in a ResolverContext built by the caller (M2 wires
+ * this to `GET /api/mcp/roots?includeArchived=1`, which since V3 returns the
+ * archived translation entries plus `{vault_root_id, device_home_dirs}`).
+ *
+ * Accepted reference forms (the plan's reference grammar):
+ *   - note URLs on any host:  https://noesisbrain.com/notes/2761[#bm=...]
+ *   - noesis://note/2761[/optional-slug]
+ *   - bare numeric ids: "2761"
+ *   - absolute paths of ANY OS shape: /Users/me/Noesis/x.md,
+ *     c:/Users/me/Noesis/x.md, C:\temp_cGit\.noesis\x.md
+ *   - tilde / %USERPROFILE% forms: ~/Noesis/x.md, %USERPROFILE%\Noesis\x.md
+ *   - LEGACY pre-migration absolute paths, translated through archived roots
+ *     (vault_subfolder + '.noesis/'-collapse candidates, collapsed first)
+ *
+ * Fixes the pre-M1 footgun where a root with an empty current-OS path
+ * resolved to process.cwd(): empty/missing slots never produce a comparable
+ * form here, and local paths are composed (never path.resolve'd) from a
+ * verified non-empty base.
+ */
+/** Forward slashes + lowercase drive letter (win32 canonical compare form). */
+export function normalizePath(p) {
+    let normalized = p.replace(/\\/g, '/');
+    if (normalized.length >= 2 && normalized[1] === ':') {
+        normalized = normalized[0].toLowerCase() + normalized.slice(1);
+    }
+    return normalized;
+}
+/** Shape-sniff which OS family a path belongs to (mirrors the backend). */
+export function detectPathOsKey(p) {
+    if (/^[A-Za-z]:[\\/]/.test(p))
+        return 'win32';
+    if (p.startsWith('/Users/') || p.startsWith('~/'))
+        return 'darwin';
+    if (p.startsWith('/'))
+        return 'linux';
+    return 'win32';
+}
+/**
+ * Parse an input string into a note reference. URLs and ids resolve by note
+ * id (the caller fetches the note to learn its relative_path); everything
+ * else is treated as a path.
+ */
+export function parseNoteReference(input) {
+    const s = input.trim();
+    if (/^\d+$/.test(s))
+        return { kind: 'id', id: parseInt(s, 10) };
+    const noesisScheme = s.match(/^noesis:\/\/note\/(\d+)(?:[/#?].*)?$/i);
+    if (noesisScheme)
+        return { kind: 'id', id: parseInt(noesisScheme[1], 10) };
+    if (/^https?:\/\//i.test(s)) {
+        // Anchored: the /notes/{id} segment must end the path (fragment/query
+        // tolerated) — '/a/notes/12.png' is NOT a note reference.
+        const urlNote = s.match(/\/notes\/(\d+)(?:[/#?].*)?$/i);
+        if (urlNote)
+            return { kind: 'id', id: parseInt(urlNote[1], 10) };
+    }
+    return { kind: 'path', path: s };
+}
+function expandHomePrefix(p, home) {
+    if (p === '~' || p.startsWith('~/'))
+        return home + p.slice(1);
+    if (/^%USERPROFILE%/i.test(p))
+        return home + p.slice('%USERPROFILE%'.length);
+    return null;
+}
+/**
+ * Comparable spellings of one path under an OS family: the normalized raw
+ * form plus one home-expanded form per known home dir for that family (this
+ * machine's home when the family is the client OS, and the cloud-cached
+ * device home). Empty inputs produce NO forms (the cwd-footgun fix).
+ */
+export function comparableForms(p, osKey, homes) {
+    const raw = (p ?? '').trim();
+    if (!raw)
+        return [];
+    const base = normalizePath(raw);
+    const variants = new Set([base]);
+    for (const home of homes) {
+        const h = normalizePath(home).replace(/\/+$/, '');
+        if (!h)
+            continue;
+        const expanded = expandHomePrefix(base, h);
+        if (expanded)
+            variants.add(expanded);
+    }
+    return [...variants].map((v) => {
+        const trimmed = v.length > 1 ? v.replace(/\/+$/, '') : v;
+        return { orig: trimmed, cmp: osKey === 'win32' ? trimmed.toLowerCase() : trimmed };
+    });
+}
+function homesFor(ctx, osKey) {
+    const homes = [];
+    if (osKey === ctx.clientOs && ctx.homeDir)
+        homes.push(ctx.homeDir);
+    const cloudHome = ctx.deviceHomeDirs?.[osKey];
+    if (typeof cloudHome === 'string' && cloudHome.trim())
+        homes.push(cloudHome);
+    return homes;
+}
+const NOESIS_SEG = '.noesis/';
+/**
+ * Resolve a path-form reference against the context's roots: longest-prefix
+ * across active + archived roots on the sniffed OS family, tilde/home
+ * expansion on both sides, legacy translation into the vault for archived
+ * matches. Null when nothing matches (or an archived match has no
+ * translation target).
+ */
+export function resolvePathReference(ctx, inputPath) {
+    const osKey = detectPathOsKey(inputPath);
+    const homes = homesFor(ctx, osKey);
+    const inputForms = comparableForms(inputPath, osKey, homes);
+    if (inputForms.length === 0)
+        return null;
+    let best = null;
+    for (const root of ctx.roots) {
+        for (const rootForm of comparableForms(root.local_paths?.[osKey], osKey, homes)) {
+            for (const input of inputForms) {
+                const isMatch = input.cmp === rootForm.cmp || input.cmp.startsWith(rootForm.cmp + '/');
+                if (!isMatch)
+                    continue;
+                if (!best || rootForm.cmp.length > best.rootLen) {
+                    const rel = input.orig.slice(rootForm.orig.length).replace(/^\//, '');
+                    best = { root, rootLen: rootForm.cmp.length, rel };
+                }
+            }
+        }
+    }
+    if (!best)
+        return null;
+    const rel = best.rel;
+    if (!best.root.archived_at) {
+        return { rootId: best.root.id, candidates: [rel], via: 'active-root' };
+    }
+    const subfolder = best.root.vault_subfolder?.replace(/^\/+|\/+$/g, '');
+    if (!subfolder || ctx.vaultRootId == null)
+        return null;
+    // F8: when the input EXPLICITLY names a `.noesis/` dot path, try the
+    // UNCOLLAPSED candidate first. In a collapse-fallback pair (a different file
+    // won the collapsed slot at migration, so this note kept its `.noesis/`
+    // prefix), collapsed-first would wrongly return the native sibling; the
+    // dot-path the caller typed is the one they mean. Harmless in the common
+    // case: the uncollapsed candidate simply misses and falls to the collapsed.
+    const candidates = rel.startsWith(NOESIS_SEG)
+        ? [`${subfolder}/${rel}`, `${subfolder}/${rel.slice(NOESIS_SEG.length)}`]
+        : [`${subfolder}/${rel}`];
+    return { rootId: ctx.vaultRootId, candidates, via: 'legacy-translation', archivedRootId: best.root.id };
+}
+/**
+ * The local base directory (this machine, CLIENT_OS) of a root — tilde-form
+ * expanded against THIS machine's home dir — or null when the root has no
+ * usable path on this OS (never a cwd-relative guess).
+ */
+export function rootLocalBase(ctx, rootId) {
+    const root = ctx.roots.find((r) => r.id === rootId);
+    const rawBase = root?.local_paths?.[ctx.clientOs]?.trim();
+    if (!rawBase)
+        return null;
+    let base = normalizePath(rawBase);
+    const home = normalizePath(ctx.homeDir ?? '').replace(/\/+$/, '');
+    const expanded = home ? expandHomePrefix(base, home) : null;
+    if (expanded)
+        base = expanded;
+    if (base.startsWith('~'))
+        return null; // home unknown — refuse to guess
+    // Any unexpanded %TOKEN% (e.g. a stored literal %USERNAME% template) would
+    // otherwise mkdir a literal '%USERNAME%' directory on materialize.
+    if (/%[^%/\\]+%/.test(base))
+        return null;
+    return base.length > 1 ? base.replace(/\/+$/, '') : base;
+}
+/**
+ * The local absolute path (this machine, CLIENT_OS) for a note of `rootId` at
+ * `relativePath` — or null when that root has no usable path on this OS.
+ */
+export function localAbsFor(ctx, rootId, relativePath) {
+    const base = rootLocalBase(ctx, rootId);
+    if (!base)
+        return null;
+    const rel = relativePath.replace(/^\/+/, '');
+    return `${base}/${rel}`;
+}
+//# sourceMappingURL=noteRef.js.map

package/dist/resolve/noteRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noteRef.js","sourceRoot":"","sources":["../../src/resolve/noteRef.ts"],"names":[],"mappings":"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"}

package/dist/resolve/rootsFormat.d.ts

@@ -0,0 +1,12 @@
+import { type ResolverContext } from './noteRef.js';
+/**
+ * Pure renderer for the `list_roots` tool output (single-vault, M3).
+ *
+ * Shows the vault (with its per-OS tilde paths AND this machine's resolved
+ * absolute base), any other still-active roots, and the archived roots as the
+ * legacy-path translation table — old absolute paths under an archived root
+ * keep resolving via get_note/sync_notes, translated into the vault subfolder
+ * shown here.
+ */
+export declare function formatRootsList(ctx: ResolverContext): string;
+//# sourceMappingURL=rootsFormat.d.ts.map

package/dist/resolve/rootsFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rootsFormat.d.ts","sourceRoot":"","sources":["../../src/resolve/rootsFormat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,eAAe,EAAc,MAAM,cAAc,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CA0D5D"}

package/dist/resolve/rootsFormat.js

@@ -0,0 +1,63 @@
+import { rootLocalBase } from './noteRef.js';
+/**
+ * Pure renderer for the `list_roots` tool output (single-vault, M3).
+ *
+ * Shows the vault (with its per-OS tilde paths AND this machine's resolved
+ * absolute base), any other still-active roots, and the archived roots as the
+ * legacy-path translation table — old absolute paths under an archived root
+ * keep resolving via get_note/sync_notes, translated into the vault subfolder
+ * shown here.
+ */
+export function formatRootsList(ctx) {
+    if (ctx.roots.length === 0) {
+        return 'No root directories configured. A vault (~/Noesis) is designated automatically on first use.';
+    }
+    const OS_LABELS = [
+        ['win32', 'Windows'],
+        ['darwin', 'macOS  '],
+        ['linux', 'Linux  '],
+    ];
+    const active = ctx.roots.filter((r) => !r.archived_at);
+    const archived = ctx.roots.filter((r) => r.archived_at);
+    const lines = [];
+    let anyMissing = false;
+    active.forEach((root, index) => {
+        const isVault = ctx.vaultRootId != null && root.id === ctx.vaultRootId;
+        lines.push(`${index + 1}. **${root.name}**${isVault ? '  ← YOUR VAULT' : ''}`);
+        for (const [key, label] of OS_LABELS) {
+            const v = root.local_paths?.[key];
+            const marker = key === ctx.clientOs ? '  [active]' : '';
+            if (v) {
+                lines.push(`   ${label}: ${v}${marker}`);
+            }
+            else if (key === ctx.clientOs) {
+                lines.push(`   ${label}: (not configured for this OS)${marker}`);
+                anyMissing = true;
+            }
+        }
+        const resolved = rootLocalBase(ctx, root.id);
+        if (resolved) {
+            lines.push(`   On this machine: ${resolved}`);
+        }
+        lines.push('');
+    });
+    let text = `Watched directories (${active.length}):\n\n${lines.join('\n').trimEnd()}`;
+    if (archived.length > 0) {
+        const rows = archived.map((r) => {
+            const oldPaths = OS_LABELS.map(([key]) => r.local_paths?.[key])
+                .filter((v) => !!v)
+                .join(' | ');
+            const target = r.vault_subfolder ? `→ vault: ${r.vault_subfolder}/` : '→ (notes trashed at migration)';
+            return `- ${r.name}: ${oldPaths} ${target}`;
+        });
+        text +=
+            `\n\nArchived roots — legacy path translation (${archived.length}):\n` +
+                rows.join('\n') +
+                `\n\nOld paths under these roots still work: get_note/sync_notes translate them into the vault automatically.`;
+    }
+    if (anyMissing) {
+        text += `\n\nTip: an ACTIVE root missing a path for this OS (${ctx.clientOs}) can't sync on this machine — add the path in the Noesis Dashboard.`;
+    }
+    return text;
+}
+//# sourceMappingURL=rootsFormat.js.map

package/dist/resolve/rootsFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rootsFormat.js","sourceRoot":"","sources":["../../src/resolve/rootsFormat.ts"],"names":[],"mappings":"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"}

package/dist/services/embedding.js

@@ -77,25 +77,25 @@ export async function generateMetadata(content) {
     if (contentToAnalyze.length > maxChars) {
         contentToAnalyze = contentToAnalyze.substring(0, maxChars) + '...';
     }
-    const prompt = `Analyze this markdown document and generate metadata for it.
-
-Document content:
----
-${contentToAnalyze}
----
-
-Generate the following metadata in JSON format:
-1. title: A concise, descriptive title (max 80 chars). IMPORTANT: If the document starts with a # heading on the first line, use that FIRST heading as the title (clean it up if needed). Only generate a new title if there's no H1 heading at the start.
-2. description: A brief summary of what this document is about (1-2 sentences, max 200 chars)
-3. keywords: An array of 5-15 relevant keywords/tags including:
-   - Main topics and concepts
-   - Technical terms and technologies (Redis, SignalR, MongoDB, etc.)
-   - Component/service/class names found in code (e.g., PrintController, BtXmlExecutor, DevicesInternalController)
-   - Include BOTH CamelCase (PrintController) AND space-separated (Print Controller) versions of component names
-   - API endpoint patterns or route names if mentioned
-   Avoid generic words like "document", "file", "note", "example", "sample".
-
-Respond with ONLY valid JSON in this exact format, no markdown code blocks:
+    const prompt = `Analyze this markdown document and generate metadata for it.
+
+Document content:
+---
+${contentToAnalyze}
+---
+
+Generate the following metadata in JSON format:
+1. title: A concise, descriptive title (max 80 chars). IMPORTANT: If the document starts with a # heading on the first line, use that FIRST heading as the title (clean it up if needed). Only generate a new title if there's no H1 heading at the start.
+2. description: A brief summary of what this document is about (1-2 sentences, max 200 chars)
+3. keywords: An array of 5-15 relevant keywords/tags including:
+   - Main topics and concepts
+   - Technical terms and technologies (Redis, SignalR, MongoDB, etc.)
+   - Component/service/class names found in code (e.g., PrintController, BtXmlExecutor, DevicesInternalController)
+   - Include BOTH CamelCase (PrintController) AND space-separated (Print Controller) versions of component names
+   - API endpoint patterns or route names if mentioned
+   Avoid generic words like "document", "file", "note", "example", "sample".
+
+Respond with ONLY valid JSON in this exact format, no markdown code blocks:
 {"title": "...", "description": "...", "keywords": ["...", "..."]}`;
     try {
         const result = await genAI.models.generateContent({

package/dist/tools/backlog.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { NoesisClient } from '../api/NoesisClient.js';
+export declare function registerBacklogTools(server: McpServer, client: NoesisClient): void;
+//# sourceMappingURL=backlog.d.ts.map

package/dist/tools/backlog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.d.ts","sourceRoot":"","sources":["../../src/tools/backlog.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAe3D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiLlF"}

package/dist/tools/backlog.js

@@ -0,0 +1,157 @@
+/**
+ * Backlog v2 MCP tools — the loop's view of /api/mcp/backlog. Thin wrappers:
+ * every rule (stage legality, OWNER_GATE, freeze, park guards) is enforced
+ * server-side; these tools shape requests and return compact JSON text that a
+ * driving loop can parse. The owner-only acts (approve / reject / cancel) have
+ * NO tool here by design — they exist only on the owner's page.
+ */
+import { z } from 'zod';
+const STAGE_ENUM = z.enum(['jot', 'refined', 'materialized', 'approved', 'running', 'implemented', 'shipped']);
+const KIND_ENUM = z.enum(['feature', 'bug', 'design', 'process', 'research']);
+const SIZE_ENUM = z.enum(['S', 'M', 'L']);
+function jsonText(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function errText(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: 'text', text: `Backlog tool failed: ${msg}` }], isError: true };
+}
+export function registerBacklogTools(server, client) {
+    server.tool('backlog_get', 'Read the Backlog: without a key, list issues (+ per-stage counts, optionally filtered by stage or a text query); with a key (TCK-<n>), the full issue including increments and open owner questions.', {
+        key: z.string().optional().describe('Issue key like TCK-7 (omit to list)'),
+        stage: STAGE_ENUM.optional().describe('List filter: only this stage'),
+        query: z.string().optional().describe('List filter: title/body text search'),
+    }, async (args) => {
+        try {
+            const data = args.key
+                ? await client.backlogGet(args.key)
+                : await client.backlogList({ stage: args.stage, q: args.query });
+            return jsonText(data);
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_upsert_issue', 'Create a Backlog issue (no key; groom may create in jot/refined/materialized) or update an existing one (with key; content fields only before approval, bookkeeping fields until terminal).', {
+        key: z.string().optional().describe('Existing issue key to update; omit to create'),
+        title: z.string().optional(),
+        kind: KIND_ENUM.optional(),
+        size: SIZE_ENUM.optional(),
+        origin_jot: z.string().optional().describe('Verbatim original memo text'),
+        body_md: z.string().optional().describe('Requirement markdown (Problem / Current / Proposed / Acceptance criteria / NOT-do)'),
+        stage: z.enum(['jot', 'refined', 'materialized']).optional().describe('Create-only: initial stage'),
+        branch: z.string().optional(),
+        worktree: z.string().optional(),
+        pr_number: z.number().int().optional(),
+    }, async (args) => {
+        try {
+            if (args.key) {
+                const { key, stage: _ignored, ...patch } = args;
+                const body = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+                return jsonText(await client.backlogPatch(key, body));
+            }
+            if (!args.title)
+                return errText(new Error('title is required to create an issue'));
+            const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
+            return jsonText(await client.backlogCreate(body));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_set_stage', "Move an issue through its lifecycle on the loop surface: jot->refined, refined->materialized (send-back too), approved->running, running->approved (STOP-acknowledge), running->implemented, implemented->shipped. Cannot approve/reject/cancel — those are the owner's page buttons (OWNER_GATE).", {
+        key: z.string().describe('Issue key like TCK-7'),
+        to: STAGE_ENUM.describe('Target stage (approve only as the running->approved stop-ack)'),
+        reason: z.string().optional().describe('Reason for send-backs'),
+    }, async (args) => {
+        try {
+            return jsonText(await client.backlogSetStage(args.key, args.to, args.reason));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_plan_increments', 'Register or refresh the planned increment list for an issue (upsert by sequence; rows that already started are never rewritten).', {
+        key: z.string(),
+        increments: z
+            .array(z.object({
+            sequence: z.number().int().positive(),
+            name: z.string(),
+            type: z.enum(['spike', 'implementation', 'verification', 'refactor']).optional(),
+        }))
+            .min(1),
+    }, async (args) => {
+        try {
+            return jsonText(await client.backlogPlanIncrements(args.key, args.increments));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_report_increment', "Report an increment lifecycle edge. phase 'start': marks it running, bumps attempts, stamps model/effort. phase 'finish': status passed|failed|parked|skipped + telemetry (verifier_verdict, gate_results, commits, evidence_md, obstacles_md); duration lands in the trace automatically.", {
+        key: z.string(),
+        sequence: z.number().int().positive(),
+        phase: z.enum(['start', 'finish']),
+        model: z.string().optional(),
+        effort: z.string().optional(),
+        status: z.enum(['passed', 'failed', 'parked', 'skipped']).optional(),
+        verifier_verdict: z.enum(['pass', 'fail']).optional(),
+        gate_results: z.record(z.string(), z.unknown()).optional(),
+        commits: z.array(z.object({ sha: z.string(), message: z.string() })).optional(),
+        evidence_md: z.string().optional(),
+        obstacles_md: z.string().optional(),
+    }, async (args) => {
+        try {
+            const { key, sequence, ...body } = args;
+            const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+            return jsonText(await client.backlogReportIncrement(key, sequence, clean));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_control', 'The iteration-boundary poll: requested control state (run/pause/stop/cancel), stage, frozen vs CURRENT spec hash (both server-computed — compare the two strings; a mismatch means the requirement changed), unanswered owner questions, and discussion since a message cursor.', {
+        key: z.string(),
+        after_message_id: z.number().int().optional().describe('Return thread messages newer than this id'),
+    }, async (args) => {
+        try {
+            return jsonText(await client.backlogControl(args.key, args.after_message_id));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_post_message', "The loop's voice on an issue: kind 'answer' + answer_to replies to an owner question WITHOUT stopping work; kind 'question' (+ parks_sequence) asks the owner and parks that increment ([Q] park); kind 'comment' leaves a note.", {
+        key: z.string(),
+        body_md: z.string(),
+        kind: z.enum(['answer', 'question', 'comment']),
+        answer_to: z.number().int().optional().describe('Message id of the owner question being answered'),
+        parks_sequence: z.number().int().optional().describe("With kind 'question': increment sequence to park"),
+    }, async (args) => {
+        try {
+            const { key, ...body } = args;
+            const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+            return jsonText(await client.backlogPostMessage(key, clean));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool('backlog_append_event', "Append a free-form trace event to an issue (dot-namespaced type like 'gate.result' or 'loop.note'; optional payload, actor claude|verifier|system, and increment sequence linkage).", {
+        key: z.string(),
+        type: z.string().describe('Dot-namespaced lowercase type, e.g. loop.note'),
+        payload: z.record(z.string(), z.unknown()).optional(),
+        actor: z.enum(['claude', 'verifier', 'system']).optional(),
+        increment_seq: z.number().int().optional(),
+    }, async (args) => {
+        try {
+            const { key, ...body } = args;
+            const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+            return jsonText(await client.backlogAppendEvent(key, clean));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+}
+//# sourceMappingURL=backlog.js.map

package/dist/tools/backlog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.js","sourceRoot":"","sources":["../../src/tools/backlog.ts"],"names":[],"mappings":"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"}