brains-mcp 1.61.2

package/dist/tools/movePage.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import { resolveIndexOwnerSubject } from "../storage/client.js";
+import { parsePage, serializePage } from "../wiki/frontmatter.js";
+import { removeIndexEntry } from "../wiki/index.js";
+import { upsertIndexEntry } from "../wiki/index.js";
+import { appendLogEntry } from "../wiki/log.js";
+import { getPostgresSearchIndex } from "../search/postgresIndex.js";
+import { lintLayout } from "../wiki/layoutLint.js";
+export const movePageInputSchema = z.object({
+    name: z.string().describe("Current relative path of the page"),
+    action: z
+        .enum(["archive", "rename"])
+        .describe("'archive' moves the page to history/archive-<name> and sets status=archived; 'rename' gives it a new path"),
+    newName: z
+        .string()
+        .regex(/^(?:[a-z0-9-]+\/)*[a-z0-9-]+\.md$/, "newName must be lowercase kebab-case path ending in .md")
+        .optional()
+        .describe("Required when action='rename'. New relative path (e.g. 'projects/new-name.md')"),
+});
+export async function movePage(drive, input, userId = "") {
+    if (input.action === "rename" && !input.newName) {
+        throw new Error("newName is required when action='rename'");
+    }
+    const name = input.name.endsWith(".md") ? input.name : `${input.name}.md`;
+    const existing = await drive.readFile(name);
+    const { frontmatter, content } = parsePage(existing.content);
+    let targetName;
+    // Full content (frontmatter included) to store in Postgres — matches patchPage.ts's
+    // DB-primary convention, which read_page/patch_page read back as the complete file.
+    let finalContent = existing.content;
+    let updateResult;
+    if (input.action === "archive") {
+        const baseName = (name.split("/").pop() ?? name).replace(/\.md$/, "");
+        const archiveSlug = baseName.startsWith("archive-") ? baseName : `archive-${baseName}`;
+        targetName = `history/${archiveSlug}.md`;
+        // Update status in frontmatter
+        frontmatter.status = "archived";
+        finalContent = serializePage(frontmatter, content);
+        updateResult = await drive.updateFile(existing.fileId, finalContent, existing.revision);
+    }
+    else {
+        targetName = input.newName;
+    }
+    // A move to where the page already is must not touch storage or delete an
+    // index row — there is nothing to move, and every step of the move is
+    // destructive when source and destination are the same object:
+    //
+    //   SupabaseStorageClient.renameFile does uploadObject(new) then
+    //   deleteObject(old). With one name that deletes the object it just wrote.
+    //   The index delete then removes the row that was the last surviving copy.
+    //
+    // Reachable today: archiving a page already at history/archive-<x>.md, where
+    // the dedup above leaves targetName identical to name. Also any rename whose
+    // newName equals the current path — nothing rejects it.
+    //
+    // For the archive case the frontmatter edit above has already been written,
+    // so the index still needs the refreshed content; only the rename and the
+    // delete are skipped.
+    const isSelfMove = targetName === name;
+    const writeResult = isSelfMove
+        ? (updateResult ?? { fileId: existing.fileId, revision: existing.revision, modifiedTime: existing.modifiedTime })
+        : await drive.renameFile(existing.fileId, targetName);
+    // Cross-account sharing (BRA-381): attribute index writes to the true storage
+    // owner. A rename that crosses a project-share boundary already throws inside
+    // drive.renameFile above, so old/new path resolve to the same owner here.
+    const indexOwner = resolveIndexOwnerSubject(drive, name, userId);
+    const pgIndex = getPostgresSearchIndex();
+    // Insert the new index row BEFORE deleting the old one, and await both.
+    //
+    // The reverse order — delete awaited, insert fire-and-forget — loses pages.
+    // Any upsert failure left the row deleted and never replaced, so the page
+    // stayed readable via read_page (which falls back to Storage) while being
+    // absent from list_pages, search_pages, tag queries and resolve_project. The
+    // tool returned success and emitted no warning, because the failure went into
+    // a `.catch(() => {})`. That is how a missing `aliases` column froze the whole
+    // production index for an hour without a single error surfacing (#450).
+    //
+    // Ordering matters more than either call succeeding. Of the reachable states:
+    //
+    //   insert ok, delete fails  -> old row is a ghost, page visible at new path.
+    //                               audit_index cleans ghosts. Recoverable.
+    //   insert fails             -> old row deliberately KEPT below, so the page
+    //                               is still indexed under its old name rather
+    //                               than vanishing. Recoverable.
+    //   (old behaviour)          -> deleted and not replaced. Invisible. Lost.
+    //
+    // So: never delete until the replacement is confirmed.
+    const indexInsertError = await pgIndex
+        .upsertPage(targetName, frontmatter, finalContent, writeResult.revision, writeResult.modifiedTime, indexOwner)
+        .then(() => null)
+        .catch((err) => (err instanceof Error ? err.message : String(err)));
+    if (indexInsertError !== null) {
+        console.error(`[index] upsert failed for '${targetName}' during move from '${name}': ${indexInsertError}`);
+    }
+    // Only retire the old row once the new one exists. If the insert failed, the
+    // stale row is the only thing keeping this page discoverable at all — and on
+    // a self-move the "old" row IS the row just written.
+    const indexDeleteError = indexInsertError !== null || isSelfMove
+        ? null
+        : await pgIndex
+            .deletePage(name, indexOwner)
+            .then(() => null)
+            .catch((err) => (err instanceof Error ? err.message : String(err)));
+    // 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.
+    // Skipped when the insert failed: edges for the old source were never removed
+    // (the delete was deliberately skipped), so adding edges for the new source
+    // would leave the page counted twice in get_backlinks.
+    if (indexInsertError === null) {
+        pgIndex
+            .syncPageLinks(targetName, content, indexOwner)
+            .catch((err) => {
+            console.warn(`[links] sync failed for '${targetName}'`, err instanceof Error ? err.message : err);
+        });
+    }
+    // index.md must not advance past Postgres. If the index insert failed, the
+    // authoritative row still names the old path, and moving the human-readable
+    // index on to the new one makes the two disagree with no way to tell which is
+    // right. On a self-move there is no old entry to remove.
+    if (indexInsertError === null) {
+        if (!isSelfMove) {
+            removeIndexEntry(drive, name).catch((err) => {
+                console.warn(`[index.md] remove failed for '${name}'`, err instanceof Error ? err.message : err);
+            });
+        }
+        upsertIndexEntry(drive, {
+            name: targetName,
+            title: String(frontmatter.title ?? targetName),
+            summary: String(frontmatter.summary ?? ""),
+            updated: new Date().toISOString().slice(0, 10),
+        }).catch((err) => {
+            console.warn(`[index.md] upsert failed for '${targetName}'`, err instanceof Error ? err.message : err);
+        });
+    }
+    appendLogEntry(drive, {
+        type: "move",
+        title: String(frontmatter.title ?? name),
+        detail: `Moved ${name} → ${targetName} (${input.action})`,
+    }, indexOwner).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);
+    });
+    const warnings = [];
+    if (indexInsertError !== null) {
+        // Loud on purpose, and deliberately not claiming the old row exists. It
+        // usually does — the delete is skipped precisely to keep it — but a page
+        // created while the index was down has no row to fall back on, and in that
+        // case the page is now completely invisible. Asserting a fallback that
+        // isn't there would describe the safe outcome while the unsafe one happened.
+        warnings.push(`Index insert for '${targetName}' failed: ${indexInsertError}. ` +
+            `The page moved in storage but the index was not updated, so search and ` +
+            `list_pages will disagree with reality — the page may appear under its old ` +
+            `name '${name}', or not at all. Re-run the move, or run audit_index.`);
+    }
+    if (indexDeleteError !== null) {
+        warnings.push(`Index delete for old path failed: ${indexDeleteError}. Run audit_index to clean up.`);
+    }
+    return {
+        success: true,
+        oldName: name,
+        newName: targetName,
+        fileId: writeResult.fileId,
+        revision: writeResult.revision,
+        // Machine-readable, because `warnings` is prose and callers branch on
+        // `success`. The storage move genuinely did happen, so success stays true —
+        // but an agent summarising this result needs a field it can test to know the
+        // index is not consistent with it.
+        ...(indexInsertError !== null ? { indexHealthy: false } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+        // A move is the other way a page reaches a path the spec forbids — and the
+        // way it happens during exactly the migrations meant to fix layout.
+        ...(() => {
+            const layoutWarnings = lintLayout(targetName);
+            return layoutWarnings.length > 0 ? { layoutWarnings } : {};
+        })(),
+    };
+}
+//# sourceMappingURL=movePage.js.map

package/dist/tools/movePage.js.map

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

package/dist/tools/pageHistory.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { StorageClient } from "../storage/client.js";
+export declare function versionPath(name: string, ts: string): string;
+/** Saves a snapshot before overwrite. Fire-and-forget — never throws. */
+export declare function snapshotPage(drive: StorageClient, name: string, content: string): Promise<void>;
+export declare const listPageHistoryInputSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+export type ListPageHistoryInput = z.infer<typeof listPageHistoryInputSchema>;
+export interface VersionEntry {
+    path: string;
+    timestamp: string;
+    size: number;
+    modifiedTime: string;
+}
+export declare function listPageHistory(drive: StorageClient, input: ListPageHistoryInput): Promise<{
+    name: string;
+    versions: VersionEntry[];
+}>;
+export declare const readPageVersionInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    timestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    timestamp: string;
+}, {
+    name: string;
+    timestamp: string;
+}>;
+export type ReadPageVersionInput = z.infer<typeof readPageVersionInputSchema>;
+export declare function readPageVersion(drive: StorageClient, input: ReadPageVersionInput): Promise<object>;
+//# sourceMappingURL=pageHistory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageHistory.d.ts","sourceRoot":"","sources":["../../src/tools/pageHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAkB1D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,yEAAyE;AACzE,wBAAsB,YAAY,CAChC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,eAAO,MAAM,0BAA0B;;;;;;EAErC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAcrD;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;EAGrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/tools/pageHistory.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+const VERSIONS_DIR = "page-versions";
+function slugifyName(name) {
+    // canonical/brains-dev.md → canonical-brains-dev
+    return name.replace(/\.md$/, "").replace(/\//g, "-").replace(/[^a-z0-9-]/g, "-");
+}
+function timestampKey() {
+    // 2026-06-16T12:34:56.789Z → 2026-06-16t123456z
+    return new Date().toISOString()
+        .replace("T", "t")
+        .replace(/:/g, "")
+        .replace(/\.\d+/, "")
+        .replace("Z", "z");
+}
+export function versionPath(name, ts) {
+    return `${VERSIONS_DIR}/${slugifyName(name)}/${ts}.md`;
+}
+/** Saves a snapshot before overwrite. Fire-and-forget — never throws. */
+export async function snapshotPage(drive, name, content) {
+    try {
+        const ts = timestampKey();
+        await drive.createFile(versionPath(name, ts), content);
+    }
+    catch {
+        // best-effort; snapshot failure must never block the write
+    }
+}
+export const listPageHistoryInputSchema = z.object({
+    name: z.string().describe("Relative path of the page (e.g. 'canonical/brains-dev-workflow.md')"),
+});
+export async function listPageHistory(drive, input) {
+    const prefix = `${VERSIONS_DIR}/${slugifyName(input.name)}/`;
+    const all = await drive.listFiles();
+    const versions = all
+        .filter((f) => f.name.startsWith(prefix))
+        .map((f) => ({
+        path: f.name,
+        timestamp: f.name.replace(prefix, "").replace(".md", ""),
+        size: f.size,
+        modifiedTime: f.modifiedTime,
+    }))
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp)); // newest-first
+    return { name: input.name, versions };
+}
+export const readPageVersionInputSchema = z.object({
+    name: z.string().describe("Relative path of the page"),
+    timestamp: z.string().describe("Timestamp key from list_page_history (e.g. '2026-06-16t123456z')"),
+});
+export async function readPageVersion(drive, input) {
+    const path = versionPath(input.name, input.timestamp);
+    const file = await drive.readFile(path);
+    return {
+        name: input.name,
+        timestamp: input.timestamp,
+        path: file.name,
+        content: file.content,
+        modifiedTime: file.modifiedTime,
+    };
+}
+//# sourceMappingURL=pageHistory.js.map

package/dist/tools/pageHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageHistory.js","sourceRoot":"","sources":["../../src/tools/pageHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,YAAY,GAAG,eAAe,CAAC;AAErC,SAAS,WAAW,CAAC,IAAY;IAC/B,iDAAiD;IACjD,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;AACnF,CAAC;AAED,SAAS,YAAY;IACnB,gDAAgD;IAChD,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC5B,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC;SACjB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;SACjB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,EAAU;IAClD,OAAO,GAAG,YAAY,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;AACzD,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAoB,EACpB,IAAY,EACZ,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;QAC1B,MAAM,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qEAAqE,CAAC;CACjG,CAAC,CAAC;AAWH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,KAA2B;IAE3B,MAAM,MAAM,GAAG,GAAG,YAAY,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;IAC7D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAmB,GAAG;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACxD,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY;KAC7B,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,eAAe;IAE1E,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACtD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kEAAkE,CAAC;CACnG,CAAC,CAAC;AAIH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,KAA2B;IAE3B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC"}

package/dist/tools/patchPage.d.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { type StorageClient } from "../storage/client.js";
+export declare const patchPageInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    operations: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"insert_after">;
+        anchor: z.ZodString;
+        text: z.ZodString;
+        occurrence: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        anchor: string;
+        type: "insert_after";
+        text: string;
+        occurrence: number;
+    }, {
+        anchor: string;
+        type: "insert_after";
+        text: string;
+        occurrence?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"insert_before">;
+        anchor: z.ZodString;
+        text: z.ZodString;
+        occurrence: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        anchor: string;
+        type: "insert_before";
+        text: string;
+        occurrence: number;
+    }, {
+        anchor: string;
+        type: "insert_before";
+        text: string;
+        occurrence?: number | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"replace">;
+        find: z.ZodString;
+        replace: z.ZodString;
+        occurrence: z.ZodDefault<z.ZodNumber>;
+        all: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        replace: string;
+        find: string;
+        type: "replace";
+        occurrence: number;
+        all: boolean;
+    }, {
+        replace: string;
+        find: string;
+        type: "replace";
+        occurrence?: number | undefined;
+        all?: boolean | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"append">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "append";
+        text: string;
+    }, {
+        type: "append";
+        text: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"replace_lines">;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "replace_lines";
+        text: string;
+        startLine: number;
+        endLine: number;
+    }, {
+        type: "replace_lines";
+        text: string;
+        startLine: number;
+        endLine: number;
+    }>]>, "many">;
+    lineNumbersAre: z.ZodDefault<z.ZodEffects<z.ZodEnum<["file"]>, "file", unknown>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    operations: ({
+        anchor: string;
+        type: "insert_after";
+        text: string;
+        occurrence: number;
+    } | {
+        anchor: string;
+        type: "insert_before";
+        text: string;
+        occurrence: number;
+    } | {
+        replace: string;
+        find: string;
+        type: "replace";
+        occurrence: number;
+        all: boolean;
+    } | {
+        type: "append";
+        text: string;
+    } | {
+        type: "replace_lines";
+        text: string;
+        startLine: number;
+        endLine: number;
+    })[];
+    lineNumbersAre: "file";
+    summary?: string | undefined;
+}, {
+    name: string;
+    operations: ({
+        anchor: string;
+        type: "insert_after";
+        text: string;
+        occurrence?: number | undefined;
+    } | {
+        anchor: string;
+        type: "insert_before";
+        text: string;
+        occurrence?: number | undefined;
+    } | {
+        replace: string;
+        find: string;
+        type: "replace";
+        occurrence?: number | undefined;
+        all?: boolean | undefined;
+    } | {
+        type: "append";
+        text: string;
+    } | {
+        type: "replace_lines";
+        text: string;
+        startLine: number;
+        endLine: number;
+    })[];
+    summary?: string | undefined;
+    lineNumbersAre?: unknown;
+}>;
+export type PatchPageInput = z.infer<typeof patchPageInputSchema>;
+export declare function patchPage(drive: StorageClient, input: PatchPageInput, userId?: string): Promise<object>;
+//# sourceMappingURL=patchPage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"patchPage.d.ts","sourceRoot":"","sources":["../../src/tools/patchPage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,aAAa,EAA4B,MAAM,sBAAsB,CAAC;AA6CpF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiC/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAGlE,wBAAsB,SAAS,CAC7B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,cAAc,EACrB,MAAM,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CA6JjB"}