brains-mcp 1.61.2

package/dist/tools/resolveProject.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { StorageClient } from "../storage/client.js";
+export declare const resolveProjectInputSchema: z.ZodObject<{
+    context: z.ZodString;
+    platform: z.ZodDefault<z.ZodEnum<["claude", "gpt"]>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    platform: "claude" | "gpt";
+    context: string;
+}, {
+    context: string;
+    limit?: number | undefined;
+    platform?: "claude" | "gpt" | undefined;
+}>;
+export type ResolveProjectInput = z.infer<typeof resolveProjectInputSchema>;
+export interface ProjectMatch {
+    slug: string;
+    parentSlug?: string;
+    pageCount: number;
+    title?: string;
+    aliases?: string[];
+    instructionsPath: string;
+    projectPath: string;
+    score: number;
+    confidence: "high" | "medium" | "low";
+    matchedOn: string[];
+}
+export declare function tokenize(value: string): string[];
+/**
+ * Score a project against the context tokens.
+ *
+ * Ranking follows signal coverage measured across the production wiki, not
+ * intuition: the slug is present for 36 of 36 projects, a root readme for 23,
+ * a real title for 22, and a summary for only 6 (GH #430). A resolver built on
+ * readme metadata — the obvious design — would fail on a third of projects,
+ * including the largest. So slug and aliases dominate, content is the fallback
+ * that catches nicknames the slug does not contain, and title is a tiebreak.
+ */
+export declare function scoreProject(ctxTokens: Set<string>, project: {
+    slug: string;
+    title?: string;
+    aliases?: string[];
+    contentHits?: number;
+}): {
+    score: number;
+    matchedOn: string[];
+};
+/**
+ * Resolve freeform context to a project slug and its instruction file.
+ *
+ * Deliberately does not load anything. Resolution and loading stay separate so
+ * a wrong guess costs one call rather than a whole bundle of the wrong
+ * project's context, and so the caller can confirm with the user when the
+ * result is ambiguous.
+ */
+export declare function resolveProject(_drive: StorageClient, input: ResolveProjectInput, userId?: string): Promise<object>;
+//# sourceMappingURL=resolveProject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveProject.d.ts","sourceRoot":"","sources":["../../src/tools/resolveProject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,eAAO,MAAM,yBAAyB;;;;;;;;;;;;EAepC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAUD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAClF;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAiDxC;AAQD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,mBAAmB,EAC1B,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CAoFjB"}

package/dist/tools/resolveProject.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+export const resolveProjectInputSchema = z.object({
+    context: z
+        .string()
+        .min(1)
+        .describe("Freeform text describing what the user is working on — their request, a project name, a nickname, a vehicle or property. Matched against project slugs, aliases, titles and page content."),
+    platform: z
+        .enum(["claude", "gpt"])
+        .default("claude")
+        .describe("Which per-project instruction file to report the path of."),
+    limit: z
+        .number()
+        .default(5)
+        .describe("Maximum matches to return, best first."),
+});
+/** Words that carry no signal when matching a project. */
+const STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "of", "for", "to", "in", "on", "my", "our",
+    "is", "are", "was", "were", "it", "this", "that", "with", "about", "what",
+    "how", "can", "you", "i", "we", "me", "please", "help", "need", "want",
+    "project", "page", "pages", "note", "notes", "brain", "brains",
+]);
+export function tokenize(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+/**
+ * Score a project against the context tokens.
+ *
+ * Ranking follows signal coverage measured across the production wiki, not
+ * intuition: the slug is present for 36 of 36 projects, a root readme for 23,
+ * a real title for 22, and a summary for only 6 (GH #430). A resolver built on
+ * readme metadata — the obvious design — would fail on a third of projects,
+ * including the largest. So slug and aliases dominate, content is the fallback
+ * that catches nicknames the slug does not contain, and title is a tiebreak.
+ */
+export function scoreProject(ctxTokens, project) {
+    const matchedOn = [];
+    let score = 0;
+    // A sub-project's slug arrives as "parent/child" (e.g. "oio/apex"), and both
+    // halves are real signal: "oio apex" should match it as a whole, while a bare
+    // "apex" matches partially. tokenize splits on non-alphanumerics, so the
+    // slash already yields both.
+    const slugTokens = tokenize(project.slug);
+    const slugHits = slugTokens.filter((t) => ctxTokens.has(t));
+    if (slugHits.length > 0) {
+        // A whole-slug match beats a partial one, and among whole matches the more
+        // specific slug wins. Without the specificity term, "oio apex" scores
+        // oio-apex and oio identically — both are whole matches — and a
+        // single-token slug hijacks every context that happens to contain it.
+        // Conversely a bare "oio" still resolves to oio, because oio-apex only
+        // matches partially there.
+        const whole = slugHits.length === slugTokens.length;
+        score += whole
+            ? 100 + 15 * (slugTokens.length - 1)
+            : 60 * (slugHits.length / slugTokens.length);
+        matchedOn.push("slug");
+    }
+    for (const alias of project.aliases ?? []) {
+        const aliasTokens = tokenize(alias);
+        if (aliasTokens.length > 0 && aliasTokens.every((t) => ctxTokens.has(t))) {
+            score += 100;
+            matchedOn.push("alias");
+            break;
+        }
+    }
+    if (project.title) {
+        const titleHits = tokenize(project.title).filter((t) => ctxTokens.has(t));
+        if (titleHits.length > 0) {
+            score += Math.min(25, titleHits.length * 10);
+            matchedOn.push("title");
+        }
+    }
+    if (project.contentHits && project.contentHits > 0) {
+        // Capped: a large project will always have more hits than a small one, and
+        // volume is not relevance.
+        score += Math.min(30, project.contentHits * 6);
+        matchedOn.push("content");
+    }
+    return { score, matchedOn };
+}
+function confidenceFor(score, runnerUp) {
+    if (score >= 100 && score - runnerUp >= 40)
+        return "high";
+    if (score >= 60)
+        return "medium";
+    return "low";
+}
+/**
+ * Resolve freeform context to a project slug and its instruction file.
+ *
+ * Deliberately does not load anything. Resolution and loading stay separate so
+ * a wrong guess costs one call rather than a whole bundle of the wrong
+ * project's context, and so the caller can confirm with the user when the
+ * result is ambiguous.
+ */
+export async function resolveProject(_drive, input, userId = "") {
+    const index = getPostgresSearchIndex();
+    if (!index.isConfigured()) {
+        return {
+            ok: false,
+            error: "resolve_project requires the Postgres index. Use list_pages with folder='projects' to browse projects instead.",
+        };
+    }
+    const ctxTokens = new Set(tokenize(input.context));
+    if (ctxTokens.size === 0) {
+        return { ok: true, matches: [], ambiguous: false, note: "No usable terms in context." };
+    }
+    const inventory = await index.listProjectInventory(userId).catch(() => null);
+    if (!inventory) {
+        return { ok: false, error: "Could not read project inventory from the index." };
+    }
+    // Content hits only matter when the slug does not already name the project —
+    // this is the "the wagon" -> cressida case. One extra query, and only when
+    // needed.
+    const strongSlugMatch = inventory.some((p) => {
+        const st = tokenize(p.slug);
+        return st.length > 0 && st.every((t) => ctxTokens.has(t));
+    });
+    let contentHitsBySlug = new Map();
+    if (!strongSlugMatch) {
+        contentHitsBySlug = await index
+            .countProjectContentHits(input.context, userId)
+            .catch(() => new Map());
+    }
+    const scored = inventory
+        .map((p) => {
+        const { score, matchedOn } = scoreProject(ctxTokens, {
+            slug: p.slug,
+            title: p.title,
+            aliases: p.aliases,
+            contentHits: contentHitsBySlug.get(p.slug),
+        });
+        return { ...p, score, matchedOn };
+    })
+        .filter((p) => p.score > 0)
+        .sort((a, b) => b.score - a.score || b.pageCount - a.pageCount);
+    const top = scored.slice(0, input.limit);
+    const runnerUp = scored[1]?.score ?? 0;
+    const matches = top.map((p, i) => ({
+        slug: p.slug,
+        ...(p.parentSlug ? { parentSlug: p.parentSlug } : {}),
+        pageCount: p.pageCount,
+        ...(p.title ? { title: p.title } : {}),
+        ...(p.aliases && p.aliases.length > 0 ? { aliases: p.aliases } : {}),
+        projectPath: p.parentSlug
+            ? `projects/${p.parentSlug}/projects/${p.slug.split("/")[1]}`
+            : `projects/${p.slug}`,
+        instructionsPath: p.parentSlug
+            ? `projects/${p.parentSlug}/projects/${p.slug.split("/")[1]}/instructions/${input.platform}.md`
+            : `projects/${p.slug}/instructions/${input.platform}.md`,
+        score: Math.round(p.score),
+        confidence: i === 0 ? confidenceFor(p.score, runnerUp) : "low",
+        matchedOn: p.matchedOn,
+    }));
+    // Close scores mean the context genuinely does not distinguish them. Say so
+    // rather than letting the caller act on an arbitrary winner — loading the
+    // wrong project's context is quiet and hard for a user to notice.
+    const ambiguous = matches.length > 1 && scored[0].score - runnerUp < 40;
+    return {
+        ok: true,
+        matches,
+        ambiguous,
+        ...(matches.length === 0
+            ? { note: "No project matched. Use list_pages with folder='projects' to browse, or ask the user." }
+            : {}),
+        ...(ambiguous
+            ? { note: "Top matches score closely — confirm with the user before loading one." }
+            : {}),
+    };
+}
+//# sourceMappingURL=resolveProject.js.map

package/dist/tools/resolveProject.js.map

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

package/dist/tools/restorePage.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { StorageClient } from "../storage/client.js";
+export declare const restorePageBaseSchema: z.ZodObject<{
+    archiveId: z.ZodOptional<z.ZodString>;
+    originalPath: z.ZodOptional<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodString>;
+    targetPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}>;
+export declare const restorePageInputSchema: z.ZodEffects<z.ZodObject<{
+    archiveId: z.ZodOptional<z.ZodString>;
+    originalPath: z.ZodOptional<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodString>;
+    targetPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}>, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}, {
+    archiveId?: string | undefined;
+    originalPath?: string | undefined;
+    deletedAt?: string | undefined;
+    targetPath?: string | undefined;
+}>;
+export type RestorePageInput = z.infer<typeof restorePageInputSchema>;
+export declare function restorePage(drive: StorageClient, input: RestorePageInput, userId?: string): Promise<object>;
+//# sourceMappingURL=restorePage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"restorePage.d.ts","sourceRoot":"","sources":["../../src/tools/restorePage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAc1D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;EAMlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE,wBAAsB,WAAW,CAC/B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,gBAAgB,EACvB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CAqFjB"}

package/dist/tools/restorePage.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { parsePage } from "../wiki/frontmatter.js";
+import { upsertIndexEntry } from "../wiki/index.js";
+import { appendLogEntry } from "../wiki/log.js";
+import { assertPageLimit } from "../wiki/storageLimits.js";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+// Plain object shape — published to clients as the tool's JSON Schema.
+// The cross-field "archiveId OR originalPath" rule lives in the .refine() below
+// (restorePageInputSchema). A refined schema is a ZodEffects, not a ZodObject, and
+// zodToJsonSchema can emit an empty `{}` for it at module-load time — which fails
+// MCP client tool-list validation (inputSchema.type must be "object") and drops the
+// ENTIRE tool surface. JSON Schema can't express the OR constraint anyway, so the
+// published schema is generated from this base and the rule is enforced at parse().
+export const restorePageBaseSchema = z.object({
+    archiveId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("Archived row ID to restore."),
+    originalPath: z
+        .string()
+        .optional()
+        .describe("Original path to restore from when archiveId is not provided."),
+    deletedAt: z
+        .string()
+        .optional()
+        .describe("Optional deleted_at timestamp filter (ISO) when restoring by originalPath."),
+    targetPath: z
+        .string()
+        .optional()
+        .describe("Optional override path for restore destination (defaults to original path)."),
+});
+export const restorePageInputSchema = restorePageBaseSchema.refine((value) => Boolean(value.archiveId || value.originalPath), {
+    message: "Provide either archiveId or originalPath.",
+    path: ["archiveId"],
+});
+function normalizePagePath(name) {
+    return name.endsWith(".md") ? name : `${name}.md`;
+}
+export async function restorePage(drive, input, userId = "") {
+    const pgIndex = getPostgresSearchIndex();
+    if (!pgIndex.isConfigured()) {
+        return {
+            ok: false,
+            error: "Postgres archive store not configured. Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.",
+        };
+    }
+    if (!userId) {
+        return { ok: false, error: "userId is required to restore archived pages." };
+    }
+    const archived = await pgIndex.getArchivedPageForRestore({
+        userId,
+        ...(input.archiveId ? { archiveId: input.archiveId } : {}),
+        ...(input.originalPath ? { originalPath: normalizePagePath(input.originalPath) } : {}),
+        ...(input.deletedAt ? { deletedAt: input.deletedAt } : {}),
+    });
+    if (!archived) {
+        return { ok: false, error: "Archived page not found for the provided selector." };
+    }
+    if (archived.restoredAt) {
+        return {
+            ok: false,
+            error: `Archived page was already restored at ${archived.restoredAt}.`,
+            archiveId: archived.id,
+            restoredAt: archived.restoredAt,
+        };
+    }
+    await assertPageLimit(userId, 1);
+    const destination = input.targetPath ? normalizePagePath(input.targetPath) : archived.originalPath;
+    const writeResult = await drive.createFile(destination, archived.content);
+    const { frontmatter, content } = parsePage(archived.content);
+    // Full content (frontmatter included) — matches patchPage.ts's DB-primary
+    // convention, which read_page/patch_page read back as the complete file.
+    await pgIndex.upsertPage(destination, frontmatter, archived.content, writeResult.revision, writeResult.modifiedTime, userId);
+    // Fire-and-forget: the link graph is a derived index, and nothing in this
+    // response depends on it. Awaiting it put three sequential Supabase round
+    // trips (~350-525ms) on the caller's critical path purely to decide whether
+    // to attach a cosmetic warning (GH #424). Staleness is self-healing —
+    // links_extracted_at drives extract_links' catch-up pass.
+    pgIndex
+        .syncPageLinks(destination, content, userId)
+        .catch((err) => {
+        console.warn(`[links] sync failed for '${destination}'`, err instanceof Error ? err.message : err);
+    });
+    await pgIndex.markArchivedPageRestored(archived.id, userId, userId);
+    upsertIndexEntry(drive, {
+        name: destination,
+        title: String(frontmatter.title ?? destination),
+        summary: String(frontmatter.summary ?? ""),
+        updated: new Date().toISOString().slice(0, 10),
+    }).catch(() => { });
+    appendLogEntry(drive, {
+        type: "create",
+        title: `Restored ${destination}`,
+        detail: `Restored from archive ${archived.id}`,
+    }, userId).catch((err) => {
+        // Surfaced rather than swallowed: a silent stop here is how an
+        // oversized log.md would go unnoticed (GH #417).
+        console.warn("[log] append failed:", err instanceof Error ? err.message : err);
+    });
+    return {
+        ok: true,
+        restored: true,
+        archiveId: archived.id,
+        originalPath: archived.originalPath,
+        restoredPath: destination,
+        revision: writeResult.revision,
+        modifiedTime: writeResult.modifiedTime,
+    };
+}
+//# sourceMappingURL=restorePage.js.map

package/dist/tools/restorePage.js.map

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

package/dist/tools/searchPages.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { StorageClient } from "../storage/client.js";
+import { type AccessContext } from "../governance/accessControl.js";
+export declare const searchPagesInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    tag: z.ZodOptional<z.ZodString>;
+    folder: z.ZodOptional<z.ZodString>;
+    maxCandidates: z.ZodDefault<z.ZodNumber>;
+    maxResults: z.ZodDefault<z.ZodNumber>;
+    maxConcurrency: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    maxCandidates: number;
+    maxResults: number;
+    maxConcurrency: number;
+    tag?: string | undefined;
+    folder?: string | undefined;
+}, {
+    query: string;
+    tag?: string | undefined;
+    folder?: string | undefined;
+    maxCandidates?: number | undefined;
+    maxResults?: number | undefined;
+    maxConcurrency?: number | undefined;
+}>;
+export type SearchPagesInput = z.infer<typeof searchPagesInputSchema>;
+export declare function searchPages(drive: StorageClient, input: SearchPagesInput, userId?: string, accessCtx?: AccessContext): Promise<object>;
+//# sourceMappingURL=searchPages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"searchPages.d.ts","sourceRoot":"","sources":["../../src/tools/searchPages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAW1D,OAAO,EACL,KAAK,aAAa,EAOnB,MAAM,gCAAgC,CAAC;AAExC,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;EAoCjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAyBtE,wBAAsB,WAAW,CAC/B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,gBAAgB,EACvB,MAAM,SAAK,EACX,SAAS,GAAE,aAAsC,GAChD,OAAO,CAAC,MAAM,CAAC,CAmEjB"}