@gmickel/gno 1.43.0 → 1.45.0

package/src/mcp/tools/capture.ts

@@ -15,16 +15,21 @@ import type { ToolContext } from "../server";
 
 import {
   buildCaptureReceipt,
+  CaptureSyncError,
+  ensureCapturedFileIndexed,
   listCaptureDiskRelPaths,
   planCapture,
+  syncCapturedFile,
   type CaptureInput as SharedCaptureInput,
   type CaptureReceipt,
+  type SyncCapturedFileResult,
 } from "../../core/capture";
 import { writeCapturePlanFile } from "../../core/capture-write";
 import { MCP_ERRORS } from "../../core/errors";
 import { withWriteLock } from "../../core/file-lock";
+import { recordContentMutation } from "../../core/mutation-generations";
 import { normalizeCollectionName } from "../../core/validation";
-import { defaultSyncService, withContentTypeRules } from "../../ingestion";
+import { DEFAULT_LOCK_WAIT_MS } from "../../core/write-lease";
 import { runTool, type ToolResult } from "./index";
 
 interface CaptureInput extends Omit<
@@ -102,6 +107,14 @@ function buildSharedInput(
   };
 }
 
+/** Surface a sync failure as an MCP tool error the `CODE: message` way. */
+function rethrowCaptureError(error: unknown): never {
+  if (error instanceof CaptureSyncError) {
+    throw new Error(`${error.code}: ${error.message}`);
+  }
+  throw error;
+}
+
 export function handleCapture(
   args: CaptureInput,
   ctx: ToolContext
@@ -114,154 +127,96 @@ export function handleCapture(
         throw new Error("Write tools disabled. Start MCP with --enable-write.");
       }
 
-      return await withWriteLock(ctx.writeLockPath, async () => {
-        const collectionName = normalizeCollectionName(args.collection);
-        const collection = ctx.collections.find(
-          (c) => c.name.toLowerCase() === collectionName
+      const collectionName = normalizeCollectionName(args.collection);
+      const collection = ctx.collections.find(
+        (c) => c.name.toLowerCase() === collectionName
+      );
+      if (!collection) {
+        throw new Error(
+          `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${args.collection}`
         );
-        if (!collection) {
-          throw new Error(
-            `${MCP_ERRORS.NOT_FOUND.code}: Collection not found: ${args.collection}`
-          );
-        }
-
-        const existingDocs = await ctx.store.listDocuments(collectionName);
-        if (!existingDocs.ok) {
-          throw new Error(existingDocs.error.message);
-        }
+      }
 
-        let plan;
-        try {
-          plan = planCapture({
-            input: buildSharedInput(args, collection.name),
-            existingRelPaths: existingDocs.value.map((doc) => doc.relPath),
-            diskRelPaths: await listCaptureDiskRelPaths(collection.path),
-          });
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : String(error);
-          throw new Error(`${MCP_ERRORS.INVALID_INPUT.code}: ${message}`);
-        }
+      // Write + lexical sync complete under the shared write lease: the tool
+      // succeeds only once the capture is retrievable (v1.38 contention
+      // contract: wait for the lease, LOCKED when it stays busy).
+      return await withWriteLock(
+        ctx.writeLockPath,
+        async () => {
+          const existingDocs = await ctx.store.listDocuments(collectionName);
+          if (!existingDocs.ok) {
+            throw new Error(existingDocs.error.message);
+          }
 
-        assertNotSensitive(plan.relPath);
+          let plan;
+          try {
+            plan = planCapture({
+              input: buildSharedInput(args, collection.name),
+              existingRelPaths: existingDocs.value.map((doc) => doc.relPath),
+              diskRelPaths: await listCaptureDiskRelPaths(collection.path),
+            });
+          } catch (error) {
+            const message =
+              error instanceof Error ? error.message : String(error);
+            throw new Error(`${MCP_ERRORS.INVALID_INPUT.code}: ${message}`);
+          }
 
-        const absPath = join(collection.path, plan.relPath);
-        const existingFile = Bun.file(absPath);
-        const exists = await existingFile.exists();
+          assertNotSensitive(plan.relPath);
 
-        if (plan.openedExisting) {
-          const docResult = await ctx.store.getDocument(
-            collectionName,
-            plan.relPath
-          );
-          const existingDoc = docResult.ok ? docResult.value : undefined;
-          return buildCaptureReceipt({
-            plan,
+          const absPath = join(collection.path, plan.relPath);
+          const syncInput = {
+            collection,
+            store: ctx.store,
+            relPath: plan.relPath,
             absPath,
-            docid: existingDoc?.docid ?? "",
-            sync: {
-              status: existingDoc ? "completed" : "skipped",
-              reason: existingDoc
-                ? "Existing capture already indexed."
-                : "Existing capture opened from disk but is not indexed yet.",
-            },
-            serverInstanceId: ctx.serverInstanceId,
-          }) as McpCaptureResult;
-        }
-
-        await mkdir(dirname(absPath), { recursive: true });
-        await writeCapturePlanFile(plan, absPath);
+            config: ctx.config,
+          };
+
+          let synced: SyncCapturedFileResult;
+          let overwritten = false;
+          try {
+            if (plan.openedExisting) {
+              synced = await ensureCapturedFileIndexed(syncInput);
+            } else {
+              overwritten =
+                (await Bun.file(absPath).exists()) && args.overwrite === true;
+              await mkdir(dirname(absPath), { recursive: true });
+              await writeCapturePlanFile(plan, absPath);
+              synced = await syncCapturedFile(syncInput);
+            }
+          } catch (error) {
+            rethrowCaptureError(error);
+          }
+          if (synced.result) {
+            recordContentMutation(synced.result, ctx.markContentMutation);
+          }
 
-        const results = await defaultSyncService.syncFiles(
-          collection,
-          ctx.store,
-          [plan.relPath],
-          withContentTypeRules(
-            { runUpdateCmd: false, gitPull: false },
-            ctx.config
-          )
-        );
-        const syncResult = results[0];
-        if (!syncResult) {
-          return buildCaptureReceipt({
-            plan,
-            absPath,
-            docid: "",
-            sync: {
-              status: "failed",
-              error: "RUNTIME: Sync result missing",
-            },
-            overwritten: exists && args.overwrite === true,
-            serverInstanceId: ctx.serverInstanceId,
-          }) as McpCaptureResult;
-        }
-        if (syncResult.status === "error") {
-          return buildCaptureReceipt({
-            plan,
-            absPath,
-            docid: "",
-            sync: {
-              status: "failed",
-              error: `INGEST_ERROR: ${syncResult.errorCode ?? "ERROR"} - ${
-                syncResult.errorMessage ?? "Unknown error"
-              }`,
-            },
-            overwritten: exists && args.overwrite === true,
-            serverInstanceId: ctx.serverInstanceId,
-          }) as McpCaptureResult;
-        }
-        if (syncResult.status === "added" || syncResult.status === "updated") {
-          ctx.markContentMutation?.();
-        }
+          const isMarkdown =
+            plan.relPath.endsWith(".md") || plan.relPath.endsWith(".markdown");
+          if (!isMarkdown && !plan.openedExisting && plan.tags.length > 0) {
+            const tagResult = await ctx.store.setDocTags(
+              synced.documentId,
+              plan.tags,
+              "user"
+            );
+            if (!tagResult.ok) {
+              console.error(
+                `[MCP] Warning: Document created but tags not stored: ${tagResult.error.message}`
+              );
+            }
+          }
 
-        let docid = syncResult.docid;
-        let documentId: number | undefined;
-        const docResult = await ctx.store.getDocument(
-          collectionName,
-          plan.relPath
-        );
-        if (docResult.ok && docResult.value) {
-          docid = docid ?? docResult.value.docid;
-          documentId = docResult.value.id;
-        }
-        if (!docid) {
           return buildCaptureReceipt({
             plan,
             absPath,
-            docid: "",
-            sync: {
-              status: "failed",
-              error: "RUNTIME: Document missing after sync",
-            },
-            overwritten: exists && args.overwrite === true,
+            docid: synced.docid,
+            sync: synced.sync,
+            overwritten,
             serverInstanceId: ctx.serverInstanceId,
           }) as McpCaptureResult;
-        }
-
-        const isMarkdown =
-          plan.relPath.endsWith(".md") || plan.relPath.endsWith(".markdown");
-        if (!isMarkdown && plan.tags.length > 0 && documentId) {
-          const tagResult = await ctx.store.setDocTags(
-            documentId,
-            plan.tags,
-            "user"
-          );
-          if (!tagResult.ok) {
-            console.error(
-              `[MCP] Warning: Document created but tags not stored: ${tagResult.error.message}`
-            );
-          }
-        }
-
-        return buildCaptureReceipt({
-          plan,
-          absPath,
-          docid,
-          sync: { status: "completed" },
-          overwritten: exists && args.overwrite === true,
-          serverInstanceId: ctx.serverInstanceId,
-        }) as McpCaptureResult;
-      });
+        },
+        DEFAULT_LOCK_WAIT_MS
+      );
     },
     formatCaptureResult
   );

package/src/serve/capture-service.ts

@@ -20,15 +20,23 @@ import type { DocumentEventBus } from "./doc-events";
 import type { EmbedScheduler } from "./embed-scheduler";
 import type { CollectionWatchService } from "./watch-service";
 
+import { getIndexDbPath } from "../app/constants";
 import {
   buildCaptureReceipt,
+  CaptureSyncError,
+  type CaptureSyncPaths,
+  ensureCapturedFileIndexed,
   extractCaptureSourceFromFrontmatter,
   hashCaptureContent,
   listCaptureDiskRelPaths,
   planCapture,
+  syncCapturedFile,
 } from "../core/capture";
 import { writeCapturePlanFile } from "../core/capture-write";
+import { MCP_ERRORS } from "../core/errors";
+import { withWriteLock } from "../core/file-lock";
 import { recordContentMutation } from "../core/mutation-generations";
+import { DEFAULT_LOCK_WAIT_MS, writeLeasePath } from "../core/write-lease";
 import {
   type CollectionSyncResult,
   defaultSyncService,
@@ -40,6 +48,8 @@ import { startJob } from "./jobs";
 
 export interface ResidentCaptureContext {
   config: Config;
+  /** Resident server context; only the index name is read (lease path). */
+  current?: { indexName?: string };
   scheduler: EmbedScheduler | null;
   eventBus: DocumentEventBus | null;
   watchService: CollectionWatchService | null;
@@ -47,6 +57,78 @@ export interface ResidentCaptureContext {
   markContentMutation?: () => void;
 }
 
+export interface ResidentCaptureDependencies {
+  /**
+   * `await-sync` (the `/api/capture` contract): write + lexical sync complete
+   * under the shared write lease before the response, `201` on create.
+   * `job` (browser clipper): write, then `202` with a sync job to poll.
+   */
+  mode?: "await-sync" | "job";
+  syncPaths?: CaptureSyncPaths;
+  syncCollection?: typeof defaultSyncService.syncCollection;
+  /** Shared `.mcp-write.lock` path; defaults to the resident index's lease. */
+  lockPath?: string;
+  lockWaitMs?: number;
+}
+
+export interface ResidentCaptureErrorShape {
+  code: string;
+  message: string;
+  status: number;
+  details?: Record<string, unknown>;
+}
+
+const HTTP_OK = 200;
+const HTTP_CREATED = 201;
+const HTTP_ACCEPTED = 202;
+const HTTP_CONFLICT = 409;
+const HTTP_INTERNAL = 500;
+
+/**
+ * Map a capture execution failure to its wire shape: lease busy is `LOCKED`
+ * (409, the MCP write-lock code), a written-but-unsynced capture is
+ * `CAPTURE_SYNC_FAILED` (500) carrying the write half of the receipt, and
+ * anything else is `RUNTIME` (500).
+ */
+export const classifyResidentCaptureError = (
+  error: unknown,
+  planned?: Extract<ResidentCapturePlanResult, { ok: true }>
+): ResidentCaptureErrorShape => {
+  const message = error instanceof Error ? error.message : String(error);
+  if (error instanceof CaptureSyncError) {
+    return {
+      code: error.code,
+      message,
+      status: HTTP_INTERNAL,
+      details: {
+        absPath: error.absPath,
+        relPath: error.relPath,
+        ...(planned
+          ? {
+              uri: `gno://${planned.collection.name}/${planned.plan.relPath}`,
+              contentHash: planned.plan.contentHash,
+            }
+          : {}),
+      },
+    };
+  }
+  if (message.startsWith(`${MCP_ERRORS.LOCKED.code}:`)) {
+    return { code: MCP_ERRORS.LOCKED.code, message, status: HTTP_CONFLICT };
+  }
+  return {
+    code: "RUNTIME",
+    message: `Failed to capture document: ${message}`,
+    status: HTTP_INTERNAL,
+  };
+};
+
+const resolveCaptureLockPath = (
+  context: ResidentCaptureContext,
+  dependencies: ResidentCaptureDependencies
+): string =>
+  dependencies.lockPath ??
+  writeLeasePath(getIndexDbPath(context.current?.indexName));
+
 export type ResidentCapturePlanResult =
   | {
       ok: true;
@@ -172,57 +254,36 @@ const syncResidentCollection = async (
   return result;
 };
 
-export const executeResidentCapturePlan = async (
+const emitCaptureCreated = (
+  context: ResidentCaptureContext,
+  collection: Collection,
+  relPath: string
+): void => {
+  context.scheduler?.notifySyncComplete([relPath]);
+  context.eventBus?.emit({
+    type: "document-changed",
+    uri: `gno://${collection.name}/${relPath}`,
+    collection: collection.name,
+    relPath,
+    origin: "create",
+    changedAt: new Date().toISOString(),
+  });
+};
+
+/**
+ * Write the planned capture, then start the legacy sync job (browser
+ * clipper contract: `202` + `sync.status: "pending"`).
+ */
+const executeCaptureAsJob = async (
   context: ResidentCaptureContext,
   store: SqliteAdapter,
   planned: Extract<ResidentCapturePlanResult, { ok: true }>,
-  dependencies: {
-    syncCollection?: typeof defaultSyncService.syncCollection;
-  } = {}
+  dependencies: ResidentCaptureDependencies
 ): Promise<{ body: unknown; status: number }> => {
   const { collection, fullPath, plan } = planned;
-  if (plan.provenanceConflict) {
-    return {
-      body: buildCaptureReceipt({
-        plan,
-        absPath: fullPath,
-        sync: {
-          status: "skipped",
-          reason:
-            "Existing capture has absent or different browser provenance.",
-        },
-      }),
-      status: 409,
-    };
-  }
-  if (plan.openedExisting) {
-    const existingDocument = await store.getDocument(
-      collection.name,
-      plan.relPath
-    );
-    if (!existingDocument.ok) {
-      throw new Error(existingDocument.error.message);
-    }
-    return {
-      body: buildCaptureReceipt({
-        plan,
-        absPath: fullPath,
-        docid: existingDocument.value?.docid,
-        sync: existingDocument.value
-          ? { status: "completed" }
-          : {
-              status: "skipped",
-              reason: "Existing file is not indexed yet.",
-            },
-      }),
-      status: 200,
-    };
-  }
-
   await mkdir(dirname(fullPath), { recursive: true });
   context.watchService?.suppress(fullPath);
   await writeCapturePlanFile(plan, fullPath);
-  const gnoUri = `gno://${collection.name}/${plan.relPath}`;
   const syncCollection =
     dependencies.syncCollection ??
     defaultSyncService.syncCollection.bind(defaultSyncService);
@@ -235,15 +296,7 @@ export const executeResidentCapturePlan = async (
         store,
         syncCollection
       );
-      context.scheduler?.notifySyncComplete([plan.relPath]);
-      context.eventBus?.emit({
-        type: "document-changed",
-        uri: gnoUri,
-        collection: collection.name,
-        relPath: plan.relPath,
-        origin: "create",
-        changedAt: new Date().toISOString(),
-      });
+      emitCaptureCreated(context, collection, plan.relPath);
       return {
         collections: [result],
         totalDurationMs: result.durationMs,
@@ -274,10 +327,131 @@ export const executeResidentCapturePlan = async (
             error: jobResult.error,
           },
     }),
-    status: 202,
+    status: HTTP_ACCEPTED,
   };
 };
 
+/**
+ * Write + lexical sync under the shared write lease; the response is sent
+ * only once the capture is retrievable. Throws `CaptureSyncError` when the
+ * file landed but sync failed, and the `LOCKED` error when the lease stays
+ * busy past `lockWaitMs`.
+ */
+const executeCaptureAwaitingSync = async (
+  context: ResidentCaptureContext,
+  store: SqliteAdapter,
+  planned: Extract<ResidentCapturePlanResult, { ok: true }>,
+  dependencies: ResidentCaptureDependencies
+): Promise<{ body: unknown; status: number }> => {
+  const { collection, fullPath, plan } = planned;
+  return withWriteLock(
+    resolveCaptureLockPath(context, dependencies),
+    async () => {
+      await mkdir(dirname(fullPath), { recursive: true });
+      context.watchService?.suppress(fullPath);
+      await writeCapturePlanFile(plan, fullPath);
+      const synced = await syncCapturedFile({
+        collection,
+        store,
+        relPath: plan.relPath,
+        absPath: fullPath,
+        config: context.config,
+        syncPaths: dependencies.syncPaths,
+      });
+      if (synced.result) {
+        recordContentMutation(synced.result, context.markContentMutation);
+      }
+      emitCaptureCreated(context, collection, plan.relPath);
+      return {
+        body: buildCaptureReceipt({
+          plan,
+          absPath: fullPath,
+          docid: synced.docid,
+          sync: synced.sync,
+        }),
+        status: HTTP_CREATED,
+      };
+    },
+    dependencies.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS
+  );
+};
+
+/**
+ * `open_existing`: an indexed file needs no lease; a disk-only file is synced
+ * under the lease so opening it is also a retrievable success.
+ */
+const openExistingCapture = async (
+  context: ResidentCaptureContext,
+  store: SqliteAdapter,
+  planned: Extract<ResidentCapturePlanResult, { ok: true }>,
+  dependencies: ResidentCaptureDependencies
+): Promise<{ body: unknown; status: number }> => {
+  const { collection, fullPath, plan } = planned;
+  const syncInput = {
+    collection,
+    store,
+    relPath: plan.relPath,
+    absPath: fullPath,
+    config: context.config,
+    syncPaths: dependencies.syncPaths,
+  };
+  const existingDocument = await store.getDocument(
+    collection.name,
+    plan.relPath
+  );
+  if (!existingDocument.ok) {
+    throw new Error(existingDocument.error.message);
+  }
+  const synced = existingDocument.value
+    ? await ensureCapturedFileIndexed(syncInput)
+    : await withWriteLock(
+        resolveCaptureLockPath(context, dependencies),
+        () => ensureCapturedFileIndexed(syncInput),
+        dependencies.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS
+      );
+  if (synced.result) {
+    recordContentMutation(synced.result, context.markContentMutation);
+  }
+  return {
+    body: buildCaptureReceipt({
+      plan,
+      absPath: fullPath,
+      docid: synced.docid,
+      sync: synced.sync,
+    }),
+    status: HTTP_OK,
+  };
+};
+
+export const executeResidentCapturePlan = async (
+  context: ResidentCaptureContext,
+  store: SqliteAdapter,
+  planned: Extract<ResidentCapturePlanResult, { ok: true }>,
+  dependencies: ResidentCaptureDependencies = {}
+): Promise<{ body: unknown; status: number }> => {
+  const { fullPath, plan } = planned;
+  if (plan.provenanceConflict) {
+    return {
+      body: buildCaptureReceipt({
+        plan,
+        absPath: fullPath,
+        sync: {
+          status: "skipped",
+          reason:
+            "Existing capture has absent or different browser provenance.",
+        },
+      }),
+      status: HTTP_CONFLICT,
+    };
+  }
+  if (plan.openedExisting) {
+    return openExistingCapture(context, store, planned, dependencies);
+  }
+  return (dependencies.mode ?? "job") === "job"
+    ? executeCaptureAsJob(context, store, planned, dependencies)
+    : executeCaptureAwaitingSync(context, store, planned, dependencies);
+};
+
 export const browserClipIdempotencyPlan = (
   planned: Extract<ResidentCapturePlanResult, { ok: true }>
 ): ClipperIdempotencyPlan => {