@gmickel/gno 0.8.6 → 0.9.0

package/src/core/job-manager.ts

@@ -0,0 +1,215 @@
+/**
+ * Background job manager for MCP write operations.
+ *
+ * @module src/core/job-manager
+ */
+
+import type { SyncResult } from "../ingestion";
+
+import { MCP_ERRORS } from "./errors";
+import { acquireWriteLock, type WriteLockHandle } from "./file-lock";
+
+const JOB_EXPIRATION_MS = 60 * 60 * 1000;
+const JOB_MAX_RECENT = 100;
+const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+
+export type JobType = "add" | "sync";
+
+export type JobStatus = "running" | "completed" | "failed";
+
+export interface JobRecord {
+  id: string;
+  type: JobType;
+  status: JobStatus;
+  startedAt: number;
+  completedAt?: number;
+  result?: SyncResult;
+  error?: string;
+  serverInstanceId: string;
+}
+
+export interface JobManagerOptions {
+  lockPath: string;
+  serverInstanceId: string;
+  toolMutex: {
+    acquire: () => Promise<() => void>;
+  };
+  lockTimeoutMs?: number;
+}
+
+export class JobError extends Error {
+  code: "LOCKED" | "JOB_CONFLICT";
+
+  constructor(code: "LOCKED" | "JOB_CONFLICT", message: string) {
+    super(message);
+    this.code = code;
+    this.name = "JobError";
+  }
+}
+
+export class JobManager {
+  #lockPath: string;
+  #serverInstanceId: string;
+  #toolMutex: JobManagerOptions["toolMutex"];
+  #lockTimeoutMs: number;
+  #activeJobId: string | null = null;
+  #jobs = new Map<string, JobRecord>();
+  #activeJobs = new Set<Promise<void>>();
+
+  constructor(options: JobManagerOptions) {
+    this.#lockPath = options.lockPath;
+    this.#serverInstanceId = options.serverInstanceId;
+    this.#toolMutex = options.toolMutex;
+    this.#lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  }
+
+  async startJob(
+    type: JobType,
+    fn: () => Promise<SyncResult>
+  ): Promise<string> {
+    this.#cleanupExpiredJobs();
+
+    if (this.#activeJobId) {
+      throw new JobError(
+        "JOB_CONFLICT",
+        `${MCP_ERRORS.JOB_CONFLICT.message} (${this.#activeJobId})`
+      );
+    }
+
+    const lock = await acquireWriteLock(this.#lockPath, this.#lockTimeoutMs);
+    if (!lock) {
+      throw new JobError("LOCKED", MCP_ERRORS.LOCKED.message);
+    }
+
+    return this.#startJobWithLock(type, fn, lock);
+  }
+
+  async startJobWithLock(
+    type: JobType,
+    lock: WriteLockHandle,
+    fn: () => Promise<SyncResult>
+  ): Promise<string> {
+    this.#cleanupExpiredJobs();
+
+    if (this.#activeJobId) {
+      throw new JobError(
+        "JOB_CONFLICT",
+        `${MCP_ERRORS.JOB_CONFLICT.message} (${this.#activeJobId})`
+      );
+    }
+
+    return this.#startJobWithLock(type, fn, lock);
+  }
+
+  getJob(jobId: string): JobRecord | undefined {
+    this.#cleanupExpiredJobs();
+    return this.#jobs.get(jobId);
+  }
+
+  listJobs(limit: number = 10): { active: JobRecord[]; recent: JobRecord[] } {
+    this.#cleanupExpiredJobs();
+
+    const jobs = Array.from(this.#jobs.values());
+    const active = jobs
+      .filter((job) => job.status === "running")
+      .sort((a, b) => a.startedAt - b.startedAt);
+
+    const recent = jobs
+      .filter((job) => job.status !== "running")
+      .sort((a, b) => (b.completedAt ?? 0) - (a.completedAt ?? 0))
+      .slice(0, limit);
+
+    return { active, recent };
+  }
+
+  async shutdown(): Promise<void> {
+    await Promise.allSettled(this.#activeJobs);
+  }
+
+  #track(jobPromise: Promise<void>): void {
+    const tracked = jobPromise.catch(() => undefined);
+    this.#activeJobs.add(tracked);
+    void tracked.finally(() => {
+      this.#activeJobs.delete(tracked);
+    });
+  }
+
+  async #runJob(
+    job: JobRecord,
+    fn: () => Promise<SyncResult>,
+    lock: { release: () => Promise<void> }
+  ): Promise<void> {
+    try {
+      const release = await this.#toolMutex.acquire();
+      try {
+        const result = await fn();
+        job.status = "completed";
+        job.result = result;
+      } catch (e) {
+        job.status = "failed";
+        job.error = e instanceof Error ? e.message : String(e);
+      } finally {
+        release();
+      }
+    } catch (e) {
+      job.status = "failed";
+      job.error = e instanceof Error ? e.message : String(e);
+    } finally {
+      job.completedAt = Date.now();
+      this.#activeJobId = null;
+      await lock.release().catch(() => undefined);
+      this.#cleanupExpiredJobs();
+    }
+  }
+
+  #startJobWithLock(
+    type: JobType,
+    fn: () => Promise<SyncResult>,
+    lock: WriteLockHandle
+  ): string {
+    const jobId = crypto.randomUUID();
+    const job: JobRecord = {
+      id: jobId,
+      type,
+      status: "running",
+      startedAt: Date.now(),
+      serverInstanceId: this.#serverInstanceId,
+    };
+
+    this.#jobs.set(jobId, job);
+    this.#activeJobId = jobId;
+
+    const jobPromise = this.#runJob(job, fn, lock);
+    this.#track(jobPromise);
+
+    return jobId;
+  }
+
+  #cleanupExpiredJobs(now: number = Date.now()): void {
+    for (const [id, job] of this.#jobs) {
+      if (job.status === "running") {
+        continue;
+      }
+      const completedAt = job.completedAt ?? job.startedAt;
+      if (now - completedAt > JOB_EXPIRATION_MS) {
+        this.#jobs.delete(id);
+      }
+    }
+
+    const completed = Array.from(this.#jobs.values())
+      .filter((job) => job.status !== "running")
+      .sort((a, b) => (a.completedAt ?? 0) - (b.completedAt ?? 0));
+
+    if (completed.length <= JOB_MAX_RECENT) {
+      return;
+    }
+
+    const toRemove = completed.length - JOB_MAX_RECENT;
+    for (let i = 0; i < toRemove; i++) {
+      const job = completed[i];
+      if (job) {
+        this.#jobs.delete(job.id);
+      }
+    }
+  }
+}

package/src/core/validation.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared validation helpers for MCP and Web UI.
+ *
+ * @module src/core/validation
+ */
+
+// node:fs/promises for realpath (no Bun equivalent)
+import { realpath } from "node:fs/promises";
+// node:os for homedir (no Bun os utils)
+import { homedir } from "node:os";
+// node:path for path utils (no Bun path utils)
+import { isAbsolute, join, normalize, sep } from "node:path";
+
+import { toAbsolutePath } from "../config/paths";
+
+const DANGEROUS_ROOT_PATTERNS = [
+  "/",
+  homedir(),
+  "/etc",
+  "/usr",
+  "/bin",
+  "/var",
+  "/System",
+  "/Library",
+  join(homedir(), ".config"),
+  join(homedir(), ".local"),
+  join(homedir(), ".ssh"),
+  join(homedir(), ".gnupg"),
+];
+
+async function resolveRealPathSafe(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return path;
+  }
+}
+
+export function normalizeCollectionName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+export function validateRelPath(relPath: string): string {
+  if (isAbsolute(relPath)) {
+    throw new Error("relPath must be relative");
+  }
+  if (relPath.includes("\0")) {
+    throw new Error("relPath contains invalid characters");
+  }
+
+  const normalized = normalize(relPath);
+  const segments = normalized.split(sep);
+  if (segments.includes("..")) {
+    throw new Error("relPath cannot escape collection root");
+  }
+
+  return normalized;
+}
+
+export async function validateCollectionRoot(
+  inputPath: string
+): Promise<string> {
+  const absPath = toAbsolutePath(inputPath);
+  const realPath = await resolveRealPathSafe(absPath);
+
+  const dangerousRoots = await Promise.all(
+    DANGEROUS_ROOT_PATTERNS.map((p) => resolveRealPathSafe(p))
+  );
+
+  if (dangerousRoots.includes(realPath)) {
+    throw new Error(`Cannot add ${inputPath}: resolves to dangerous root`);
+  }
+
+  return realPath;
+}

package/src/ingestion/sync.ts

@@ -5,6 +5,11 @@
  * @module src/ingestion/sync
  */
 
+// node:fs/promises for stat (no Bun equivalent for file stats)
+import { stat } from "node:fs/promises";
+// node:path for join (no Bun path utils)
+import { join } from "node:path";
+
 import type { Collection } from "../config/types";
 import type {
   ChunkInput,
@@ -411,6 +416,56 @@ export class SyncService {
     }
   }
 
+  /**
+   * Sync a specific set of files within a collection.
+   */
+  async syncFiles(
+    collection: Collection,
+    store: StorePort,
+    relPaths: string[],
+    options: SyncOptions = {}
+  ): Promise<FileSyncResult[]> {
+    const results: FileSyncResult[] = [];
+
+    for (const relPath of relPaths) {
+      const absPath = join(collection.path, relPath);
+      let stats: Awaited<ReturnType<typeof stat>>;
+      try {
+        stats = await stat(absPath);
+      } catch {
+        results.push({
+          relPath,
+          status: "error",
+          errorCode: "NOT_FOUND",
+          errorMessage: "File not found",
+        });
+        continue;
+      }
+
+      if (!stats.isFile()) {
+        results.push({
+          relPath,
+          status: "error",
+          errorCode: "NOT_FILE",
+          errorMessage: "Path is not a file",
+        });
+        continue;
+      }
+
+      const entry: WalkEntry = {
+        absPath,
+        relPath,
+        size: stats.size,
+        mtime: stats.mtime.toISOString(),
+      };
+
+      const result = await this.processFile(collection, entry, store, options);
+      results.push(result);
+    }
+
+    return results;
+  }
+
   /**
    * Sync a single collection.
    */

package/src/mcp/AGENTS.md

@@ -0,0 +1,86 @@
+# MCP Server
+
+GNO's Model Context Protocol server for AI agent integration.
+
+## Architecture
+
+```
+src/mcp/
+├── server.ts          # MCP server setup, stdio transport
+├── tools/             # Tool implementations
+│   ├── index.ts       # Tool registry
+│   ├── search.ts      # gno_search (BM25)
+│   ├── vsearch.ts     # gno_vsearch (vector)
+│   ├── query.ts       # gno_query (hybrid)
+│   ├── get.ts         # gno_get (single doc)
+│   ├── multi-get.ts   # gno_multi_get (batch)
+│   └── status.ts      # gno_status
+└── resources/         # Resource implementations
+    └── index.ts       # gno:// URI scheme
+```
+
+## Specification
+
+See `spec/mcp.md` for full MCP specification including:
+
+- Tool schemas and responses
+- Resource URI schemes
+- Error codes
+- Versioning
+
+**Always update spec/mcp.md first** when adding/modifying tools.
+
+## Tool Pattern
+
+Each tool follows this structure:
+
+```typescript
+export const toolName: Tool = {
+  name: "gno_toolname",
+  description: "What this tool does",
+  inputSchema: {
+    type: "object",
+    properties: { /* ... */ },
+    required: ["query"],
+  },
+};
+
+export async function handleToolName(
+  args: ToolArgs,
+  store: SqliteAdapter,
+  // ... other ports
+): Promise<CallToolResult> {
+  // 1. Validate args
+  // 2. Execute operation
+  // 3. Return { content: [...], structuredContent: {...} }
+}
+```
+
+## Response Format
+
+All tools return both human-readable and structured content:
+
+```typescript
+return {
+  content: [{ type: "text", text: "Human readable summary" }],
+  structuredContent: {
+    // Machine-readable data matching spec schemas
+  },
+};
+```
+
+## Resources
+
+Resources use `gno://` URI scheme:
+
+- `gno://work/path/to/doc.md` - Document content
+- `gno://collections` - List collections
+- `gno://schemas/*` - JSON schemas
+
+## Testing
+
+MCP tests in `test/mcp/`:
+
+```bash
+bun test test/mcp/
+```

package/src/mcp/CLAUDE.md

@@ -0,0 +1,86 @@
+# MCP Server
+
+GNO's Model Context Protocol server for AI agent integration.
+
+## Architecture
+
+```
+src/mcp/
+├── server.ts          # MCP server setup, stdio transport
+├── tools/             # Tool implementations
+│   ├── index.ts       # Tool registry
+│   ├── search.ts      # gno_search (BM25)
+│   ├── vsearch.ts     # gno_vsearch (vector)
+│   ├── query.ts       # gno_query (hybrid)
+│   ├── get.ts         # gno_get (single doc)
+│   ├── multi-get.ts   # gno_multi_get (batch)
+│   └── status.ts      # gno_status
+└── resources/         # Resource implementations
+    └── index.ts       # gno:// URI scheme
+```
+
+## Specification
+
+See `spec/mcp.md` for full MCP specification including:
+
+- Tool schemas and responses
+- Resource URI schemes
+- Error codes
+- Versioning
+
+**Always update spec/mcp.md first** when adding/modifying tools.
+
+## Tool Pattern
+
+Each tool follows this structure:
+
+```typescript
+export const toolName: Tool = {
+  name: "gno_toolname",
+  description: "What this tool does",
+  inputSchema: {
+    type: "object",
+    properties: { /* ... */ },
+    required: ["query"],
+  },
+};
+
+export async function handleToolName(
+  args: ToolArgs,
+  store: SqliteAdapter,
+  // ... other ports
+): Promise<CallToolResult> {
+  // 1. Validate args
+  // 2. Execute operation
+  // 3. Return { content: [...], structuredContent: {...} }
+}
+```
+
+## Response Format
+
+All tools return both human-readable and structured content:
+
+```typescript
+return {
+  content: [{ type: "text", text: "Human readable summary" }],
+  structuredContent: {
+    // Machine-readable data matching spec schemas
+  },
+};
+```
+
+## Resources
+
+Resources use `gno://` URI scheme:
+
+- `gno://work/path/to/doc.md` - Document content
+- `gno://collections` - List collections
+- `gno://schemas/*` - JSON schemas
+
+## Testing
+
+MCP tests in `test/mcp/`:
+
+```bash
+bun test test/mcp/
+```

package/src/mcp/server.ts

@@ -7,11 +7,15 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// node:path for join/dirname (no Bun path utils)
+import { dirname, join } from "node:path";
 
 import type { Collection, Config } from "../config/types";
 import type { SqliteAdapter } from "../store/sqlite/adapter";
 
-import { MCP_SERVER_NAME, VERSION } from "../app/constants";
+import { MCP_SERVER_NAME, VERSION, getIndexDbPath } from "../app/constants";
+import { JobManager } from "../core/job-manager";
+import { envIsSet } from "../llm/policy";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Simple Promise Mutex (avoids async-mutex dependency)
@@ -54,6 +58,10 @@ export interface ToolContext {
   collections: Collection[];
   actualConfigPath: string;
   toolMutex: Mutex;
+  jobManager: JobManager;
+  serverInstanceId: string;
+  writeLockPath: string;
+  enableWrite: boolean;
   isShuttingDown: () => boolean;
 }
 
@@ -65,6 +73,7 @@ export interface McpServerOptions {
   indexName?: string;
   configPath?: string;
   verbose?: boolean;
+  enableWrite?: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -133,6 +142,19 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
   // Sequential execution mutex
   const toolMutex = new Mutex();
 
+  // Server instance ID (per-process)
+  const serverInstanceId = crypto.randomUUID();
+
+  const enableWrite =
+    options.enableWrite ?? envIsSet(process.env, "GNO_MCP_ENABLE_WRITE");
+  const dbPath = getIndexDbPath(options.indexName);
+  const writeLockPath = join(dirname(dbPath), ".mcp-write.lock");
+  const jobManager = new JobManager({
+    lockPath: writeLockPath,
+    serverInstanceId,
+    toolMutex,
+  });
+
   // Shutdown state
   let shuttingDown = false;
 
@@ -143,6 +165,10 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
     collections,
     actualConfigPath,
     toolMutex,
+    jobManager,
+    serverInstanceId,
+    writeLockPath,
+    enableWrite,
     isShuttingDown: () => shuttingDown,
   };
 
@@ -176,17 +202,20 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
     const release = await toolMutex.acquire();
     release();
 
-    // 2. Close MCP server/transport (flush buffers, clean disconnect)
+    // 2. Wait for background jobs before closing DB
+    await jobManager.shutdown();
+
+    // 3. Close MCP server/transport (flush buffers, clean disconnect)
     try {
       await server.close();
     } catch {
       // Best-effort - server may already be closed
     }
 
-    // 3. Close DB (safe now - no tool is running)
+    // 4. Close DB (safe now - no tool or job is running)
     await store.close();
 
-    // 4. Exit
+    // 5. Exit
     process.exit(0);
   };