@gmickel/gno 1.7.1 → 1.8.0

package/src/core/file-ops.ts

@@ -4,8 +4,8 @@
  * @module src/core/file-ops
  */
 
-// node:fs/promises for rename/unlink (no Bun equivalent for structure ops)
-import { copyFile, mkdir, rename, unlink } from "node:fs/promises";
+// node:fs/promises for rename/unlink/link (no Bun equivalent for structure ops or exclusive hard-link create)
+import { copyFile, link, mkdir, rename, unlink } from "node:fs/promises";
 // node:os platform/homedir/tmpdir: no Bun equivalent
 import { homedir, platform as getPlatform, tmpdir } from "node:os";
 // node:path dirname/join/parse: no Bun equivalent
@@ -27,6 +27,25 @@ export async function atomicWrite(
   }
 }
 
+export async function atomicCreate(
+  path: string,
+  content: string
+): Promise<void> {
+  const tempPath = `${path}.tmp.${crypto.randomUUID()}`;
+  await Bun.write(tempPath, content);
+  try {
+    await link(tempPath, path);
+  } catch (e) {
+    await unlink(tempPath).catch(() => {
+      /* ignore cleanup errors */
+    });
+    throw e;
+  }
+  await unlink(tempPath).catch(() => {
+    /* ignore cleanup errors */
+  });
+}
+
 async function runCommand(cmd: string[]): Promise<void> {
   const proc = Bun.spawn({
     cmd,

package/src/mcp/tools/capture.ts

@@ -9,54 +9,39 @@ import { mkdir } from "node:fs/promises";
 // node:path for path utils (no Bun path utils)
 import { dirname, extname, join } from "node:path";
 
+import type { NoteCollisionPolicy } from "../../core/note-creation";
+import type { NotePresetId } from "../../core/note-presets";
 import type { ToolContext } from "../server";
 
-import { buildUri } from "../../app/constants";
+import {
+  buildCaptureReceipt,
+  listCaptureDiskRelPaths,
+  planCapture,
+  type CaptureInput as SharedCaptureInput,
+  type CaptureReceipt,
+} from "../../core/capture";
+import { writeCapturePlanFile } from "../../core/capture-write";
 import { MCP_ERRORS } from "../../core/errors";
 import { withWriteLock } from "../../core/file-lock";
-import { atomicWrite } from "../../core/file-ops";
-import {
-  resolveNoteCreatePlan,
-  type NoteCollisionPolicy,
-} from "../../core/note-creation";
-import {
-  getNotePreset,
-  resolveNotePreset,
-  type NotePresetId,
-} from "../../core/note-presets";
-import { normalizeTag, validateTag } from "../../core/tags";
-import {
-  normalizeCollectionName,
-  validateRelPath,
-} from "../../core/validation";
+import { normalizeCollectionName } from "../../core/validation";
 import { defaultSyncService } from "../../ingestion";
-import { updateFrontmatterTags } from "../../ingestion/frontmatter";
-import { extractTitle } from "../../pipeline/contextual";
 import { runTool, type ToolResult } from "./index";
 
-interface CaptureInput {
-  collection: string;
-  content?: string;
-  title?: string;
+interface CaptureInput extends Omit<
+  SharedCaptureInput,
+  "relPath" | "collisionPolicy" | "presetId"
+> {
   path?: string;
-  overwrite?: boolean;
-  folderPath?: string;
   collisionPolicy?: NoteCollisionPolicy;
   presetId?: NotePresetId;
-  tags?: string[];
 }
 
-interface CaptureResult {
+type McpCaptureResult = CaptureReceipt & {
   docid: string;
-  uri: string;
   absPath: string;
-  collection: string;
-  relPath: string;
-  created: boolean;
   overwritten: boolean;
   serverInstanceId: string;
-  tags?: string[];
-}
+};
 
 const SENSITIVE_SUBPATHS = new Set([
   ".ssh",
@@ -67,51 +52,56 @@ const SENSITIVE_SUBPATHS = new Set([
   "node_modules",
 ]);
 
-function sanitizeFilename(title: string): string {
-  return title
-    .toLowerCase()
-    .trim()
-    .replaceAll(/[^\w\s-]/g, "")
-    .replaceAll(/\s+/g, "-")
-    .replaceAll(/-+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
 function ensureMarkdownExtension(relPath: string): string {
   return extname(relPath) ? relPath : `${relPath}.md`;
 }
 
 function assertNotSensitive(relPath: string): void {
-  const firstSegment = relPath.split(/[\\/]/)[0];
-  if (firstSegment && SENSITIVE_SUBPATHS.has(firstSegment)) {
-    throw new Error(
-      `${MCP_ERRORS.INVALID_PATH.code}: Cannot write to sensitive directory: ${firstSegment}`
-    );
+  for (const segment of relPath.split(/[\\/]/)) {
+    if (segment && SENSITIVE_SUBPATHS.has(segment)) {
+      throw new Error(
+        `${MCP_ERRORS.INVALID_PATH.code}: Cannot write to sensitive directory: ${segment}`
+      );
+    }
   }
 }
 
-function generateFilename(title: string | undefined, content: string): string {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const fallback = `note-${timestamp}.md`;
-  const baseTitle = title?.trim() || extractTitle(content, fallback);
-  const slug = sanitizeFilename(baseTitle);
-  const safeSlug = slug || `note-${timestamp}`;
-  return `${safeSlug}.md`;
-}
-
-function formatCaptureResult(result: CaptureResult): string {
+function formatCaptureResult(result: McpCaptureResult): string {
   const lines: string[] = [];
   lines.push(`Doc: ${result.docid}`);
   lines.push(`URI: ${result.uri}`);
   lines.push(`Path: ${result.absPath}`);
   lines.push(`Created: ${result.created ? "yes" : "no"}`);
+  lines.push(`Opened existing: ${result.openedExisting ? "yes" : "no"}`);
   lines.push(`Overwritten: ${result.overwritten ? "yes" : "no"}`);
-  if (result.tags && result.tags.length > 0) {
+  lines.push(`Collision: ${result.collisionPolicyResult}`);
+  lines.push(`Sync: ${result.sync.status}`);
+  lines.push(`Embed: ${result.embed.status}`);
+  lines.push(`Content hash: ${result.contentHash}`);
+  if (result.tags.length > 0) {
     lines.push(`Tags: ${result.tags.join(", ")}`);
   }
   return lines.join("\n");
 }
 
+function buildSharedInput(
+  args: CaptureInput,
+  collectionName: string
+): SharedCaptureInput {
+  return {
+    collection: collectionName,
+    content: args.content,
+    title: args.title,
+    relPath: args.path ? ensureMarkdownExtension(args.path) : undefined,
+    folderPath: args.folderPath,
+    collisionPolicy: args.collisionPolicy,
+    presetId: args.presetId,
+    tags: args.tags,
+    source: args.source,
+    overwrite: args.overwrite,
+  };
+}
+
 export function handleCapture(
   args: CaptureInput,
   ctx: ToolContext
@@ -135,183 +125,136 @@ export function handleCapture(
           );
         }
 
-        if (args.presetId && !getNotePreset(args.presetId)) {
-          throw new Error(
-            `${MCP_ERRORS.INVALID_INPUT.code}: Unknown presetId: ${args.presetId}`
-          );
-        }
-
         const existingDocs = await ctx.store.listDocuments(collectionName);
         if (!existingDocs.ok) {
           throw new Error(existingDocs.error.message);
         }
 
-        let relPath: string;
+        let plan;
         try {
-          const plan = resolveNoteCreatePlan(
-            {
-              collection: collection.name,
-              relPath: args.path
-                ? ensureMarkdownExtension(validateRelPath(args.path))
-                : undefined,
-              title:
-                args.title?.trim() ||
-                generateFilename(args.title, args.content ?? "").replace(
-                  /\.md$/u,
-                  ""
-                ),
-              folderPath: args.folderPath,
-              collisionPolicy: args.collisionPolicy,
-            },
-            existingDocs.value.map((doc) => doc.relPath)
-          );
-          if (plan.openedExisting) {
-            throw new Error(
-              `${MCP_ERRORS.CONFLICT.code}: Existing note resolution is not supported through gno_capture yet`
-            );
-          }
-          relPath = plan.relPath;
+          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_PATH.code}: ${message}`);
+          throw new Error(`${MCP_ERRORS.INVALID_INPUT.code}: ${message}`);
         }
 
-        assertNotSensitive(relPath);
+        assertNotSensitive(plan.relPath);
 
-        // Validate and normalize tags
-        let normalizedTags: string[] = [];
-        if (args.tags && args.tags.length > 0) {
-          for (const tag of args.tags) {
-            const normalized = normalizeTag(tag);
-            if (!validateTag(normalized)) {
-              throw new Error(
-                `${MCP_ERRORS.INVALID_INPUT.code}: Invalid tag "${tag}". Tags must be lowercase, alphanumeric with hyphens/dots/slashes.`
-              );
-            }
-            normalizedTags.push(normalized);
-          }
-          // Dedupe
-          normalizedTags = [...new Set(normalizedTags)];
-        }
-
-        const absPath = join(collection.path, relPath);
-        const file = Bun.file(absPath);
-        const exists = await file.exists();
-        if (exists && !args.overwrite) {
-          throw new Error(
-            `${MCP_ERRORS.CONFLICT.code}: File exists: ${relPath}`
-          );
-        }
+        const absPath = join(collection.path, plan.relPath);
+        const existingFile = Bun.file(absPath);
+        const exists = await existingFile.exists();
 
-        // Update frontmatter with tags for Markdown files
-        const resolvedPreset = resolveNotePreset({
-          presetId: args.presetId,
-          title:
-            args.title?.trim() ||
-            relPath
-              .split("/")
-              .pop()
-              ?.replace(/\.[^.]+$/u, "") ||
-            "Untitled",
-          tags: normalizedTags,
-          body: args.content,
-        });
-        let contentToWrite =
-          resolvedPreset?.content ??
-          args.content ??
-          `# ${args.title?.trim() || "Untitled"}\n`;
-        const isMarkdown =
-          relPath.endsWith(".md") || relPath.endsWith(".markdown");
-        if (isMarkdown && normalizedTags.length > 0) {
-          // Use shared utility that handles all frontmatter edge cases
-          contentToWrite = updateFrontmatterTags(
-            contentToWrite,
-            normalizedTags
+        if (plan.openedExisting) {
+          const docResult = await ctx.store.getDocument(
+            collectionName,
+            plan.relPath
           );
+          const existingDoc = docResult.ok ? docResult.value : undefined;
+          return buildCaptureReceipt({
+            plan,
+            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 atomicWrite(absPath, contentToWrite);
+        await writeCapturePlanFile(plan, absPath);
 
         const results = await defaultSyncService.syncFiles(
           collection,
           ctx.store,
-          [relPath],
+          [plan.relPath],
           { runUpdateCmd: false, gitPull: false }
         );
         const syncResult = results[0];
         if (!syncResult) {
-          throw new Error("RUNTIME: Sync result missing");
+          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") {
-          throw new Error(
-            `INGEST_ERROR: ${syncResult.errorCode ?? "ERROR"} - ${
-              syncResult.errorMessage ?? "Unknown 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;
         }
 
         let docid = syncResult.docid;
         let documentId: number | undefined;
-        if (!docid) {
-          const docResult = await ctx.store.getDocument(
-            collectionName,
-            relPath
-          );
-          if (!docResult.ok) {
-            throw new Error(docResult.error.message);
-          }
-          if (!docResult.value) {
-            throw new Error("RUNTIME: Document missing after sync");
-          }
-          docid = docResult.value.docid;
+        const docResult = await ctx.store.getDocument(
+          collectionName,
+          plan.relPath
+        );
+        if (docResult.ok && docResult.value) {
+          docid = docid ?? docResult.value.docid;
           documentId = docResult.value.id;
-        } else {
-          // Get document id for tag storage
-          const docResult = await ctx.store.getDocument(
-            collectionName,
-            relPath
-          );
-          if (docResult.ok && docResult.value) {
-            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,
+            serverInstanceId: ctx.serverInstanceId,
+          }) as McpCaptureResult;
         }
 
-        // For non-markdown files, store tags as user-source in DB
-        // (Markdown files get tags from frontmatter during sync)
-        let tagsStored = isMarkdown; // Markdown tags stored via frontmatter sync
-        if (!isMarkdown && normalizedTags.length > 0 && documentId) {
+        const isMarkdown =
+          plan.relPath.endsWith(".md") || plan.relPath.endsWith(".markdown");
+        if (!isMarkdown && plan.tags.length > 0 && documentId) {
           const tagResult = await ctx.store.setDocTags(
             documentId,
-            normalizedTags,
+            plan.tags,
             "user"
           );
-          if (tagResult.ok) {
-            tagsStored = true;
-          } else {
-            // Log warning - document created but tags not stored
+          if (!tagResult.ok) {
             console.error(
               `[MCP] Warning: Document created but tags not stored: ${tagResult.error.message}`
             );
           }
         }
 
-        // Only include tags in response if confirmed stored
-        const confirmedTags =
-          tagsStored && normalizedTags.length > 0 ? normalizedTags : undefined;
-
-        return {
-          docid,
-          uri: buildUri(collectionName, relPath),
+        return buildCaptureReceipt({
+          plan,
           absPath,
-          collection: collectionName,
-          relPath,
-          created: !exists,
-          overwritten: exists,
+          docid,
+          sync: { status: "completed" },
+          overwritten: exists && args.overwrite === true,
           serverInstanceId: ctx.serverInstanceId,
-          tags: confirmedTags,
-        };
+        }) as McpCaptureResult;
       });
     },
     formatCaptureResult

package/src/mcp/tools/index.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 
 import type { ToolContext } from "../server";
 
+import { CAPTURE_MAX_TEXT_BYTES } from "../../core/capture";
 import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
 import { handleCapture } from "./capture";
@@ -148,6 +149,7 @@ const captureInputSchema = z.object({
     .describe("Target collection name (must already exist)"),
   content: z
     .string()
+    .max(CAPTURE_MAX_TEXT_BYTES)
     .optional()
     .describe(
       "Document content (markdown or plain text). Optional when presetId provides a scaffold."
@@ -189,6 +191,39 @@ const captureInputSchema = z.object({
     .array(z.string())
     .optional()
     .describe("Tags to apply to the new document"),
+  source: z
+    .object({
+      kind: z
+        .enum([
+          "direct",
+          "web",
+          "email",
+          "meeting",
+          "chat",
+          "file",
+          "api",
+          "unknown",
+        ])
+        .optional()
+        .describe("Capture source kind"),
+      title: z.string().optional().describe("Human source title"),
+      url: z.string().optional().describe("Source URL"),
+      uri: z.string().optional().describe("Source URI"),
+      docid: z.string().optional().describe("Source GNO doc ID"),
+      mime: z.string().optional().describe("Source MIME type"),
+      ext: z.string().optional().describe("Source file extension"),
+      author: z.string().optional().describe("Source author"),
+      observedAt: z
+        .string()
+        .optional()
+        .describe("When the source was observed"),
+      capturedAt: z.string().optional().describe("Capture timestamp override"),
+      externalId: z.string().optional().describe("External system/source ID"),
+    })
+    .optional()
+    .describe(
+      "Structured provenance metadata written under source frontmatter"
+    ),
 });
 
 const addCollectionInputSchema = z.object({

package/src/sdk/client.ts

@@ -15,6 +15,8 @@ import type { IndexStatus, StoreResult } from "../store/types";
 import type { VectorIndexPort } from "../store/vector";
 import type {
   GnoAskOptions,
+  GnoCaptureOptions,
+  GnoCaptureResult,
   GnoClient,
   GnoCreateFolderOptions,
   GnoCreateFolderResult,
@@ -43,6 +45,13 @@ import {
   parseUri,
 } from "../app/constants";
 import { ConfigSchema, loadConfig } from "../config";
+import {
+  buildCaptureReceipt,
+  type CapturePlan,
+  listCaptureDiskRelPaths,
+  planCapture,
+} from "../core/capture";
+import { writeCapturePlanFile } from "../core/capture-write";
 import {
   atomicWrite,
   copyFilePath,
@@ -822,6 +831,106 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
+  async capture(options: GnoCaptureOptions): Promise<GnoCaptureResult> {
+    this.assertOpen();
+    const collection = this.getCollections(options.collection)[0];
+    if (!collection) {
+      throw sdkError(
+        "VALIDATION",
+        `Collection not found: ${options.collection}`
+      );
+    }
+
+    const existingList = await this.store.listDocuments(collection.name);
+    if (!existingList.ok) {
+      throw sdkError("STORE", existingList.error.message, {
+        cause: existingList.error.cause,
+      });
+    }
+    const { overwrite: _unsupportedOverwrite, ...captureOptions } =
+      options as GnoCaptureOptions & { overwrite?: unknown };
+    if (_unsupportedOverwrite !== undefined) {
+      throw sdkError(
+        "VALIDATION",
+        "overwrite is not supported by client.capture(); use collisionPolicy instead"
+      );
+    }
+
+    let plan: CapturePlan;
+    try {
+      plan = planCapture({
+        input: {
+          ...captureOptions,
+          collection: collection.name,
+        },
+        existingRelPaths: existingList.value.map((doc) => doc.relPath),
+        diskRelPaths: await listCaptureDiskRelPaths(collection.path),
+      });
+    } catch (error) {
+      throw sdkError(
+        "VALIDATION",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+
+    const fullPath = `${collection.path}/${plan.relPath}`;
+    if (plan.openedExisting) {
+      const existingDoc = await this.store.getDocument(
+        collection.name,
+        plan.relPath
+      );
+      if (!existingDoc.ok) {
+        throw sdkError("STORE", existingDoc.error.message, {
+          cause: existingDoc.error.cause,
+        });
+      }
+      return buildCaptureReceipt({
+        plan,
+        absPath: fullPath,
+        docid: existingDoc.value?.docid,
+        sync: existingDoc.value
+          ? { status: "completed" }
+          : {
+              status: "skipped",
+              reason: "Existing file is not indexed yet.",
+            },
+      });
+    }
+
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeCapturePlanFile(plan, fullPath);
+    const syncResults = await defaultSyncService.syncFiles(
+      collection,
+      this.store,
+      [plan.relPath],
+      {
+        runUpdateCmd: false,
+        gitPull: false,
+      }
+    );
+    const syncResult = syncResults[0];
+    const docResult = await this.store.getDocument(
+      collection.name,
+      plan.relPath
+    );
+    const docid = docResult.ok ? docResult.value?.docid : undefined;
+    return buildCaptureReceipt({
+      plan,
+      absPath: fullPath,
+      docid: syncResult?.docid ?? docid,
+      sync:
+        syncResult?.status === "error"
+          ? {
+              status: "failed",
+              error:
+                syncResult.errorMessage ??
+                syncResult.errorCode ??
+                "Unknown sync error",
+            }
+          : { status: "completed" },
+    });
+  }
+
   async createFolder(
     options: GnoCreateFolderOptions
   ): Promise<GnoCreateFolderResult> {

package/src/sdk/index.ts

@@ -29,6 +29,8 @@ export { GnoSdkError, sdkError } from "./errors";
 export { createGnoClient } from "./client";
 export type {
   GnoAskOptions,
+  GnoCaptureOptions,
+  GnoCaptureResult,
   GnoClient,
   GnoClientInitOptions,
   GnoEmbedOptions,

package/src/sdk/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Config } from "../config/types";
+import type { CaptureInput, CaptureReceipt } from "../core/capture";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type { DocumentSection } from "../core/sections";
@@ -130,6 +131,10 @@ export interface GnoCreateNoteResult {
   createdWithSuffix?: boolean;
 }
 
+export interface GnoCaptureOptions extends Omit<CaptureInput, "overwrite"> {}
+
+export type GnoCaptureResult = CaptureReceipt;
+
 export interface GnoCreateFolderOptions {
   collection: string;
   name: string;
@@ -194,6 +199,7 @@ export interface GnoClient {
   update(options?: GnoUpdateOptions): Promise<SyncResult>;
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;
+  capture(options: GnoCaptureOptions): Promise<GnoCaptureResult>;
   createNote(options: GnoCreateNoteOptions): Promise<GnoCreateNoteResult>;
   createFolder(options: GnoCreateFolderOptions): Promise<GnoCreateFolderResult>;
   renameNote(options: GnoRenameNoteOptions): Promise<GnoRefactorNoteResult>;