@gmickel/gno 0.8.6 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -54,6 +54,7 @@
     "website:dev": "cd website && make serve",
     "website:build": "cd website && make build",
     "website:demos": "cd website/demos && ./build-demos.sh",
+    "sync:agents": "scripts/sync-agents.sh",
     "build:css": "bunx @tailwindcss/cli -i src/serve/public/globals.css -o src/serve/public/globals.built.css --minify",
     "serve": "bun src/index.ts serve",
     "serve:dev": "NODE_ENV=development bun --hot src/index.ts serve",

package/src/cli/AGENTS.md

@@ -0,0 +1,96 @@
+# CLI Commands
+
+GNO command-line interface using Commander.js.
+
+## Architecture
+
+```
+src/cli/
+├── program.ts         # Main Commander program with all commands
+├── run.ts             # Entry point, error handling
+├── context.ts         # CliContext with adapters
+├── options.ts         # Shared option definitions
+├── errors.ts          # Error types and exit codes
+├── colors.ts          # Terminal color utilities
+├── progress.ts        # Progress indicators
+├── ui.ts              # User interaction helpers
+├── format/            # Output formatters (json, csv, md, xml)
+└── commands/          # Command implementations
+    ├── search.ts
+    ├── query.ts
+    ├── ask.ts
+    └── ...
+```
+
+## Specification
+
+See `spec/cli.md` for full CLI specification including:
+
+- Exit codes (0=success, 1=validation, 2=runtime)
+- Global flags (--index, --json, --verbose, etc.)
+- Output format support matrix
+- All command schemas
+
+**Always update spec/cli.md first** when adding/modifying commands.
+
+## Command Pattern
+
+Commands follow this structure in `program.ts`:
+
+```typescript
+program
+  .command("search <query>")
+  .description("BM25 keyword search")
+  .option("-l, --limit <n>", "Max results", "10")
+  .option("-c, --collection <name>", "Filter by collection")
+  .addOption(formatOption) // From options.ts
+  .action(async (query, opts) => {
+    await runSearch(query, opts);
+  });
+```
+
+## Exit Codes
+
+```typescript
+export const EXIT = {
+  SUCCESS: 0,    // Command completed successfully
+  VALIDATION: 1, // Bad args, missing params
+  RUNTIME: 2,    // IO, DB, model, network errors
+} as const;
+```
+
+## Output Formats
+
+All search/query commands support multiple formats:
+
+- `--json` - Machine-readable JSON
+- `--files` - Line protocol for piping
+- `--csv` - Spreadsheet compatible
+- `--md` - Markdown tables
+- `--xml` - XML format
+
+Format handlers in `src/cli/format/`.
+
+## CliContext
+
+Created at command execution, holds adapters:
+
+```typescript
+interface CliContext {
+  store: SqliteAdapter;
+  config: Config;
+  embedPort?: EmbeddingPort;
+  genPort?: GenerationPort;
+  rerankPort?: RerankPort;
+}
+```
+
+## Testing
+
+CLI tests in `test/cli/`:
+
+```bash
+bun test test/cli/
+```
+
+Use `--json` output for assertions in tests.

package/src/cli/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLI Commands
+
+GNO command-line interface using Commander.js.
+
+## Architecture
+
+```
+src/cli/
+├── program.ts         # Main Commander program with all commands
+├── run.ts             # Entry point, error handling
+├── context.ts         # CliContext with adapters
+├── options.ts         # Shared option definitions
+├── errors.ts          # Error types and exit codes
+├── colors.ts          # Terminal color utilities
+├── progress.ts        # Progress indicators
+├── ui.ts              # User interaction helpers
+├── format/            # Output formatters (json, csv, md, xml)
+└── commands/          # Command implementations
+    ├── search.ts
+    ├── query.ts
+    ├── ask.ts
+    └── ...
+```
+
+## Specification
+
+See `spec/cli.md` for full CLI specification including:
+
+- Exit codes (0=success, 1=validation, 2=runtime)
+- Global flags (--index, --json, --verbose, etc.)
+- Output format support matrix
+- All command schemas
+
+**Always update spec/cli.md first** when adding/modifying commands.
+
+## Command Pattern
+
+Commands follow this structure in `program.ts`:
+
+```typescript
+program
+  .command("search <query>")
+  .description("BM25 keyword search")
+  .option("-l, --limit <n>", "Max results", "10")
+  .option("-c, --collection <name>", "Filter by collection")
+  .addOption(formatOption) // From options.ts
+  .action(async (query, opts) => {
+    await runSearch(query, opts);
+  });
+```
+
+## Exit Codes
+
+```typescript
+export const EXIT = {
+  SUCCESS: 0,    // Command completed successfully
+  VALIDATION: 1, // Bad args, missing params
+  RUNTIME: 2,    // IO, DB, model, network errors
+} as const;
+```
+
+## Output Formats
+
+All search/query commands support multiple formats:
+
+- `--json` - Machine-readable JSON
+- `--files` - Line protocol for piping
+- `--csv` - Spreadsheet compatible
+- `--md` - Markdown tables
+- `--xml` - XML format
+
+Format handlers in `src/cli/format/`.
+
+## CliContext
+
+Created at command execution, holds adapters:
+
+```typescript
+interface CliContext {
+  store: SqliteAdapter;
+  config: Config;
+  embedPort?: EmbeddingPort;
+  genPort?: GenerationPort;
+  rerankPort?: RerankPort;
+}
+```
+
+## Testing
+
+CLI tests in `test/cli/`:
+
+```bash
+bun test test/cli/
+```
+
+Use `--json` output for assertions in tests.

package/src/cli/commands/mcp/install.ts

@@ -35,6 +35,7 @@ export interface InstallOptions {
   scope?: McpScope;
   force?: boolean;
   dryRun?: boolean;
+  enableWrite?: boolean;
   /** Override cwd (testing) */
   cwd?: string;
   /** Override home dir (testing) */
@@ -147,6 +148,7 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
   const scope = opts.scope ?? "user";
   const force = opts.force ?? false;
   const dryRun = opts.dryRun ?? false;
+  const enableWrite = opts.enableWrite ?? false;
   const globals = safeGetGlobals();
   const json = opts.json ?? globals.json;
   const quiet = opts.quiet ?? globals.quiet;
@@ -160,7 +162,7 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
   }
 
   // Build server entry (uses process.execPath, always succeeds)
-  const serverEntry = buildMcpServerEntry();
+  const serverEntry = buildMcpServerEntry({ enableWrite });
 
   // Install
   const result = await installToTarget(target, scope, serverEntry, {

package/src/cli/commands/mcp/paths.ts

@@ -398,7 +398,11 @@ export function findBunPath(): string {
  * Uses absolute paths because Claude Desktop has a limited PATH.
  * Cross-platform: avoids shelling out to `which`.
  */
-export function buildMcpServerEntry(): McpServerEntry {
+export function buildMcpServerEntry(
+  options: {
+    enableWrite?: boolean;
+  } = {}
+): McpServerEntry {
   const bunPath = findBunPath();
   const home = homedir();
   const isWindows = platform() === "win32";
@@ -411,7 +415,11 @@ export function buildMcpServerEntry(): McpServerEntry {
   ) {
     // Dev mode: run the entry script directly with bun
     const entryScript = scriptPath.replace(COMMANDS_PATH_PATTERN, "/index.ts");
-    return { command: bunPath, args: ["run", entryScript, "mcp"] };
+    const args = ["run", entryScript, "mcp"];
+    if (options.enableWrite) {
+      args.push("--enable-write");
+    }
+    return { command: bunPath, args };
   }
 
   // 2. Check common gno install locations (cross-platform)
@@ -428,13 +436,21 @@ export function buildMcpServerEntry(): McpServerEntry {
 
   for (const gnoPath of gnoCandidates) {
     if (existsSync(gnoPath)) {
-      return { command: bunPath, args: [gnoPath, "mcp"] };
+      const args = [gnoPath, "mcp"];
+      if (options.enableWrite) {
+        args.push("--enable-write");
+      }
+      return { command: bunPath, args };
     }
   }
 
   // 3. Fallback to bunx (works if gno is published to npm)
   // Note: This may trigger network access on first run
-  return { command: bunPath, args: ["x", "@gmickel/gno", "mcp"] };
+  const args = ["x", "@gmickel/gno", "mcp"];
+  if (options.enableWrite) {
+    args.push("--enable-write");
+  }
+  return { command: bunPath, args };
 }
 
 /**

package/src/cli/commands/mcp.ts

@@ -10,11 +10,15 @@ import type { GlobalOptions } from "../context";
  * Start the MCP server.
  * Reads global options for --index and --config flags.
  */
-export async function mcpCommand(options: GlobalOptions): Promise<void> {
+export async function mcpCommand(
+  options: GlobalOptions,
+  commandOptions: { enableWrite?: boolean } = {}
+): Promise<void> {
   const { startMcpServer } = await import("../../mcp/server.js");
   await startMcpServer({
     indexName: options.index,
     configPath: options.config,
     verbose: options.verbose,
+    enableWrite: commandOptions.enableWrite,
   });
 }

package/src/cli/program.ts

@@ -766,11 +766,17 @@ function wireMcpCommand(program: Command): void {
     .command("serve", { isDefault: true })
     .description("Start MCP server (stdio transport)")
     .helpOption(false)
-    .action(async () => {
+    .option(
+      "--enable-write",
+      "Enable write operations (capture, add-collection, sync, remove-collection)"
+    )
+    .action(async (cmdOpts: Record<string, unknown>) => {
       const { mcpCommand } = await import("./commands/mcp.js");
       const globalOpts = program.opts();
       const globals = parseGlobalOptions(globalOpts);
-      await mcpCommand(globals);
+      await mcpCommand(globals, {
+        enableWrite: cmdOpts.enableWrite === true ? true : undefined,
+      });
     });
 
   // install - Install gno MCP server to client configs
@@ -789,6 +795,10 @@ function wireMcpCommand(program: Command): void {
     )
     .option("-f, --force", "overwrite existing configuration")
     .option("--dry-run", "show what would be done without making changes")
+    .option(
+      "--enable-write",
+      "Enable write operations in installed MCP configuration"
+    )
     .option("--json", "JSON output")
     .action(async (cmdOpts: Record<string, unknown>) => {
       const target = cmdOpts.target as string;
@@ -820,6 +830,7 @@ function wireMcpCommand(program: Command): void {
         scope: scope as "user" | "project",
         force: Boolean(cmdOpts.force),
         dryRun: Boolean(cmdOpts.dryRun),
+        enableWrite: Boolean(cmdOpts.enableWrite),
         // Pass undefined if not set, so global --json can take effect
         json: cmdOpts.json === true ? true : undefined,
       });

package/src/core/config-mutation.ts

@@ -0,0 +1,110 @@
+/**
+ * Config mutation helper shared by Web UI and MCP.
+ *
+ * @module src/core/config-mutation
+ */
+
+import type { Config } from "../config/types";
+import type { SqliteAdapter } from "../store/sqlite/adapter";
+
+import { loadConfig, saveConfig } from "../config";
+
+export interface ConfigMutationContext {
+  store: SqliteAdapter;
+  configPath?: string;
+  onConfigUpdated: (config: Config) => void;
+}
+
+export type MutationResult<T = void> =
+  | { ok: true; config: Config; value?: T }
+  | { ok: false; error: string; code: string };
+
+export type ApplyConfigResult<T = void> =
+  | { ok: true; config: Config; value?: T }
+  | { ok: false; error: string; code: string };
+
+/**
+ * In-memory mutex for serializing config mutations.
+ * Prevents lost updates when multiple requests try to modify config concurrently.
+ */
+let configMutex: Promise<void> = Promise.resolve();
+
+export async function applyConfigChange<T = void>(
+  ctx: ConfigMutationContext,
+  mutate: (config: Config) => Promise<MutationResult<T>> | MutationResult<T>
+): Promise<ApplyConfigResult<T>> {
+  const previousMutex = configMutex;
+  let resolveMutex: () => void = () => {
+    /* no-op until assigned */
+  };
+
+  configMutex = new Promise((resolve) => {
+    resolveMutex = resolve;
+  });
+
+  try {
+    await previousMutex;
+
+    const loadResult = await loadConfig(ctx.configPath);
+    if (!loadResult.ok) {
+      return {
+        ok: false,
+        error: loadResult.error.message,
+        code: "LOAD_ERROR",
+      };
+    }
+
+    const mutationResult = await mutate(loadResult.value);
+    if (!mutationResult.ok) {
+      return {
+        ok: false,
+        error: mutationResult.error,
+        code: mutationResult.code,
+      };
+    }
+
+    const newConfig = mutationResult.config;
+    const saveResult = await saveConfig(newConfig, ctx.configPath);
+    if (!saveResult.ok) {
+      return {
+        ok: false,
+        error: saveResult.error.message,
+        code: "SAVE_ERROR",
+      };
+    }
+
+    const syncCollResult = await ctx.store.syncCollections(
+      newConfig.collections
+    );
+    if (!syncCollResult.ok) {
+      console.warn(
+        `Config saved but DB sync failed: ${syncCollResult.error.message}`
+      );
+      return {
+        ok: false,
+        error: `DB sync failed: ${syncCollResult.error.message}`,
+        code: "SYNC_ERROR",
+      };
+    }
+
+    const syncCtxResult = await ctx.store.syncContexts(
+      newConfig.contexts ?? []
+    );
+    if (!syncCtxResult.ok) {
+      console.warn(
+        `Config saved but context sync failed: ${syncCtxResult.error.message}`
+      );
+      return {
+        ok: false,
+        error: `Context sync failed: ${syncCtxResult.error.message}`,
+        code: "SYNC_ERROR",
+      };
+    }
+
+    ctx.onConfigUpdated(newConfig);
+
+    return { ok: true, config: newConfig, value: mutationResult.value };
+  } finally {
+    resolveMutex();
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,40 @@
+/**
+ * Standardized error codes/messages for MCP write operations.
+ *
+ * @module src/core/errors
+ */
+
+export const MCP_ERRORS = {
+  LOCKED: {
+    code: "LOCKED",
+    message: "Another GNO write operation is running. Try again later.",
+  },
+  JOB_CONFLICT: {
+    code: "JOB_CONFLICT",
+    message: "Another job is already running.",
+  },
+  INVALID_PATH: {
+    code: "INVALID_PATH",
+    message: "Path violates safety rules.",
+  },
+  PATH_NOT_FOUND: {
+    code: "PATH_NOT_FOUND",
+    message: "Path not found.",
+  },
+  DUPLICATE: {
+    code: "DUPLICATE",
+    message: "Resource already exists.",
+  },
+  NOT_FOUND: {
+    code: "NOT_FOUND",
+    message: "Resource not found.",
+  },
+  CONFLICT: {
+    code: "CONFLICT",
+    message: "Conflict with existing resource.",
+  },
+  HAS_REFERENCES: {
+    code: "HAS_REFERENCES",
+    message: "Resource has references.",
+  },
+};

package/src/core/file-lock.ts

@@ -0,0 +1,144 @@
+/**
+ * OS-backed advisory file locking for MCP write operations.
+ *
+ * @module src/core/file-lock
+ */
+
+// node:fs/promises for mkdir (no Bun equivalent for recursive dir creation)
+import { mkdir } from "node:fs/promises";
+// node:path for dirname (no Bun path utils)
+import { dirname } from "node:path";
+
+import { MCP_ERRORS } from "./errors";
+const DEFAULT_TIMEOUT_MS = 5000;
+const HOLD_SECONDS = 60 * 60 * 24 * 365;
+const READY_TOKEN = "READY";
+
+export interface WriteLockHandle {
+  release: () => Promise<void>;
+}
+
+interface LockCommand {
+  path: string;
+  args: (
+    lockPath: string,
+    timeoutSeconds: number,
+    holdCommand: string
+  ) => string[];
+}
+
+function resolveLockCommand(): LockCommand | null {
+  const lockfPath = Bun.which("lockf");
+  if (lockfPath) {
+    return {
+      path: lockfPath,
+      args: (lockPath, timeoutSeconds, holdCommand) => [
+        "-t",
+        String(timeoutSeconds),
+        lockPath,
+        "sh",
+        "-c",
+        holdCommand,
+      ],
+    };
+  }
+
+  const flockPath = Bun.which("flock");
+  if (flockPath) {
+    return {
+      path: flockPath,
+      args: (lockPath, timeoutSeconds, holdCommand) => [
+        "-w",
+        String(timeoutSeconds),
+        lockPath,
+        "sh",
+        "-c",
+        holdCommand,
+      ],
+    };
+  }
+
+  return null;
+}
+
+function buildHoldCommand(): string {
+  return `printf '${READY_TOKEN}\\n'; exec sleep ${HOLD_SECONDS}`;
+}
+
+async function waitForReady(
+  proc: ReturnType<typeof Bun.spawn>
+): Promise<boolean> {
+  if (!proc.stdout || typeof proc.stdout === "number") {
+    return false;
+  }
+
+  const reader = proc.stdout.getReader();
+  try {
+    const result = await Promise.race([
+      reader.read(),
+      proc.exited.then(() => null),
+    ]);
+
+    if (!result || result.done || !result.value) {
+      return false;
+    }
+
+    const text = new TextDecoder().decode(result.value);
+    return text.includes(READY_TOKEN);
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+export async function acquireWriteLock(
+  lockPath: string,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS
+): Promise<WriteLockHandle | null> {
+  const cmd = resolveLockCommand();
+  if (!cmd) {
+    throw new Error("No lockf/flock available for write locking");
+  }
+
+  await mkdir(dirname(lockPath), { recursive: true });
+
+  const timeoutSeconds = Math.max(0, Math.ceil(timeoutMs / 1000));
+  const holdCommand = buildHoldCommand();
+  const proc = Bun.spawn(
+    [cmd.path, ...cmd.args(lockPath, timeoutSeconds, holdCommand)],
+    {
+      stdout: "pipe",
+      stderr: "pipe",
+    }
+  );
+
+  const ready = await waitForReady(proc);
+  if (!ready) {
+    proc.kill();
+    await proc.exited.catch(() => undefined);
+    return null;
+  }
+
+  return {
+    release: async () => {
+      proc.kill();
+      await proc.exited.catch(() => undefined);
+    },
+  };
+}
+
+export async function withWriteLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS
+): Promise<T> {
+  const lock = await acquireWriteLock(lockPath, timeoutMs);
+  if (!lock) {
+    throw new Error(`${MCP_ERRORS.LOCKED.code}: ${MCP_ERRORS.LOCKED.message}`);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await lock.release();
+  }
+}

package/src/core/file-ops.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared file operations.
+ *
+ * @module src/core/file-ops
+ */
+
+// node:fs/promises for rename/unlink (no Bun equivalent for structure ops)
+import { rename, unlink } from "node:fs/promises";
+
+export async function atomicWrite(
+  path: string,
+  content: string
+): Promise<void> {
+  const tempPath = `${path}.tmp.${crypto.randomUUID()}`;
+  await Bun.write(tempPath, content);
+  try {
+    await rename(tempPath, path);
+  } catch (e) {
+    await unlink(tempPath).catch(() => {
+      /* ignore cleanup errors */
+    });
+    throw e;
+  }
+}