@gmickel/gno 0.3.0

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

@@ -0,0 +1,300 @@
+/**
+ * MCP config file operations.
+ * Shared between install/uninstall to avoid drift.
+ *
+ * @module src/cli/commands/mcp/config
+ */
+
+import { copyFile, mkdir, rename, stat, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { CliError } from '../../errors.js';
+import type { McpConfigFormat } from './paths.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Standard mcpServers entry (Claude Desktop, Cursor, Windsurf, LM Studio) */
+export interface StandardMcpEntry {
+  command: string;
+  args: string[];
+}
+
+/** OpenCode mcp entry (command is array, has type and enabled) */
+export interface OpenCodeMcpEntry {
+  type: 'local';
+  command: string[];
+  enabled: boolean;
+}
+
+/** Config with standard mcpServers key */
+export interface McpConfig {
+  mcpServers?: Record<string, StandardMcpEntry>;
+  [key: string]: unknown;
+}
+
+/** Zed config with context_servers key */
+export interface ZedConfig {
+  context_servers?: Record<string, StandardMcpEntry>;
+  [key: string]: unknown;
+}
+
+/** OpenCode config with mcp key */
+export interface OpenCodeConfig {
+  mcp?: Record<string, OpenCodeMcpEntry>;
+  [key: string]: unknown;
+}
+
+/** Amp config with amp.mcpServers key */
+export interface AmpConfig {
+  'amp.mcpServers'?: Record<string, StandardMcpEntry>;
+  [key: string]: unknown;
+}
+
+/** Union of all config types */
+export type AnyMcpConfig = McpConfig | ZedConfig | OpenCodeConfig | AmpConfig;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Read/Write Operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if path exists and is a file (not directory).
+ * Returns null if doesn't exist, throws if exists but not a file.
+ */
+async function checkConfigPath(
+  configPath: string
+): Promise<'file' | 'missing'> {
+  try {
+    const stats = await stat(configPath);
+    if (!stats.isFile()) {
+      throw new CliError(
+        'RUNTIME',
+        `Config path exists but is not a file: ${configPath}`
+      );
+    }
+    return 'file';
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return 'missing';
+    }
+    throw err;
+  }
+}
+
+/**
+ * Read and parse MCP config file.
+ * Returns empty config if file doesn't exist.
+ * Returns null if file doesn't exist AND returnNullOnMissing is true.
+ * Throws on malformed JSON/YAML or if path is a directory.
+ */
+export async function readMcpConfig(
+  configPath: string,
+  options?: { returnNullOnMissing?: boolean; yaml?: boolean }
+): Promise<McpConfig | null> {
+  const pathStatus = await checkConfigPath(configPath);
+
+  if (pathStatus === 'missing') {
+    return options?.returnNullOnMissing ? null : {};
+  }
+
+  const file = Bun.file(configPath);
+  const content = await file.text();
+
+  // Handle empty file
+  if (!content.trim()) {
+    return {};
+  }
+
+  try {
+    if (options?.yaml) {
+      return Bun.YAML.parse(content) as McpConfig;
+    }
+    return JSON.parse(content) as McpConfig;
+  } catch {
+    const format = options?.yaml ? 'YAML' : 'JSON';
+    throw new CliError(
+      'RUNTIME',
+      `Malformed ${format} in ${configPath}. Please fix or backup and delete the file.`
+    );
+  }
+}
+
+/**
+ * Write MCP config atomically via temp file + rename.
+ * Creates backup of existing file first.
+ */
+export async function writeMcpConfig(
+  configPath: string,
+  config: AnyMcpConfig,
+  options?: { yaml?: boolean }
+): Promise<void> {
+  const dir = dirname(configPath);
+
+  // Ensure directory exists
+  await mkdir(dir, { recursive: true });
+
+  // Create backup of existing file
+  try {
+    const stats = await stat(configPath);
+    if (stats.isFile()) {
+      await copyFile(configPath, `${configPath}.bak`);
+    }
+  } catch {
+    // File doesn't exist, no backup needed
+  }
+
+  // Serialize content
+  const content = options?.yaml
+    ? Bun.YAML.stringify(config)
+    : JSON.stringify(config, null, 2);
+
+  // Write to temp file first
+  const tmpPath = `${configPath}.tmp.${Date.now()}.${process.pid}`;
+  try {
+    await Bun.write(tmpPath, content);
+    // Atomic rename
+    await rename(tmpPath, configPath);
+  } catch (err) {
+    // Cleanup temp file on error
+    try {
+      await unlink(tmpPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Format-aware Operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the servers record key for a config format.
+ */
+export function getServersKey(
+  format: McpConfigFormat
+): 'mcpServers' | 'context_servers' | 'mcp' | 'amp.mcpServers' {
+  switch (format) {
+    case 'standard':
+    case 'yaml_standard':
+      return 'mcpServers';
+    case 'context_servers':
+      return 'context_servers';
+    case 'mcp':
+      return 'mcp';
+    case 'amp_mcp':
+      return 'amp.mcpServers';
+    default: {
+      const _exhaustive: never = format;
+      throw new Error(`Unknown format: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Check if format uses YAML.
+ */
+export function isYamlFormat(format: McpConfigFormat): boolean {
+  return format === 'yaml_standard';
+}
+
+/**
+ * Check if a server entry exists in config for given format.
+ */
+export function hasServerEntry(
+  config: AnyMcpConfig,
+  serverName: string,
+  format: McpConfigFormat
+): boolean {
+  const key = getServersKey(format);
+  const servers = config[key] as Record<string, unknown> | undefined;
+  return !!servers?.[serverName];
+}
+
+/**
+ * Get server entry from config.
+ */
+export function getServerEntry(
+  config: AnyMcpConfig,
+  serverName: string,
+  format: McpConfigFormat
+): StandardMcpEntry | OpenCodeMcpEntry | undefined {
+  const key = getServersKey(format);
+  const servers = config[key] as
+    | Record<string, StandardMcpEntry | OpenCodeMcpEntry>
+    | undefined;
+  return servers?.[serverName];
+}
+
+/**
+ * Build entry for a specific format from standard command/args.
+ */
+export function buildEntry(
+  command: string,
+  args: string[],
+  format: McpConfigFormat
+): StandardMcpEntry | OpenCodeMcpEntry {
+  if (format === 'mcp') {
+    // OpenCode: command is array [command, ...args]
+    return {
+      type: 'local',
+      command: [command, ...args],
+      enabled: true,
+    };
+  }
+  // All others use standard format
+  return { command, args };
+}
+
+/**
+ * Add or update server entry in config.
+ */
+export function setServerEntry(
+  config: AnyMcpConfig,
+  serverName: string,
+  entry: StandardMcpEntry | OpenCodeMcpEntry,
+  format: McpConfigFormat
+): void {
+  const key = getServersKey(format);
+
+  // Initialize servers record if needed
+  if (!config[key]) {
+    (config as Record<string, unknown>)[key] = {};
+  }
+
+  const servers = config[key] as Record<
+    string,
+    StandardMcpEntry | OpenCodeMcpEntry
+  >;
+  servers[serverName] = entry;
+}
+
+/**
+ * Remove server entry from config.
+ * Returns true if entry was removed, false if not found.
+ */
+export function removeServerEntry(
+  config: AnyMcpConfig,
+  serverName: string,
+  format: McpConfigFormat
+): boolean {
+  const key = getServersKey(format);
+  const servers = config[key] as
+    | Record<string, StandardMcpEntry | OpenCodeMcpEntry>
+    | undefined;
+
+  if (!servers?.[serverName]) {
+    return false;
+  }
+
+  delete servers[serverName];
+
+  // Clean up empty servers object
+  if (Object.keys(servers).length === 0) {
+    delete (config as Record<string, unknown>)[key];
+  }
+
+  return true;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * MCP command exports.
+ *
+ * @module src/cli/commands/mcp
+ */
+
+export { type InstallOptions, installMcp } from './install.js';
+export {
+  buildMcpServerEntry,
+  findBunPath,
+  getTargetDisplayName,
+  MCP_SERVER_NAME,
+  MCP_TARGETS,
+  type McpConfigPaths,
+  type McpPathOptions,
+  type McpScope,
+  type McpServerEntry,
+  type McpTarget,
+  resolveAllMcpPaths,
+  resolveMcpConfigPath,
+  TARGETS_WITH_PROJECT_SCOPE,
+} from './paths.js';
+export { type StatusOptions, statusMcp } from './status.js';
+export { type UninstallOptions, uninstallMcp } from './uninstall.js';

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

@@ -0,0 +1,203 @@
+/**
+ * Install gno as MCP server in client configurations.
+ *
+ * @module src/cli/commands/mcp/install
+ */
+
+import { CliError } from '../../errors.js';
+import { getGlobals } from '../../program.js';
+import {
+  type AnyMcpConfig,
+  buildEntry,
+  hasServerEntry,
+  isYamlFormat,
+  readMcpConfig,
+  type StandardMcpEntry,
+  setServerEntry,
+  writeMcpConfig,
+} from './config.js';
+import {
+  buildMcpServerEntry,
+  getTargetDisplayName,
+  MCP_SERVER_NAME,
+  type McpScope,
+  type McpTarget,
+  resolveMcpConfigPath,
+  TARGETS_WITH_PROJECT_SCOPE,
+} from './paths.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface InstallOptions {
+  target?: McpTarget;
+  scope?: McpScope;
+  force?: boolean;
+  dryRun?: boolean;
+  /** Override cwd (testing) */
+  cwd?: string;
+  /** Override home dir (testing) */
+  homeDir?: string;
+  /** JSON output */
+  json?: boolean;
+  /** Quiet mode */
+  quiet?: boolean;
+}
+
+interface InstallResult {
+  target: McpTarget;
+  scope: McpScope;
+  configPath: string;
+  action: 'created' | 'updated' | 'dry_run_create' | 'dry_run_update';
+  serverEntry: { command: string; args: string[] };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Install Logic
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Install gno to a single target.
+ */
+async function installToTarget(
+  target: McpTarget,
+  scope: McpScope,
+  serverEntry: StandardMcpEntry,
+  options: {
+    force?: boolean;
+    dryRun?: boolean;
+    cwd?: string;
+    homeDir?: string;
+  }
+): Promise<InstallResult> {
+  const { force = false, dryRun = false, cwd, homeDir } = options;
+
+  const { configPath, configFormat } = resolveMcpConfigPath({
+    target,
+    scope,
+    cwd,
+    homeDir,
+  });
+
+  // Read existing config (needed for both dry-run preview and actual install)
+  // readMcpConfig returns {} for missing files when returnNullOnMissing is not set
+  const useYaml = isYamlFormat(configFormat);
+  const config = ((await readMcpConfig(configPath, {
+    yaml: useYaml,
+  })) ?? {}) as AnyMcpConfig;
+
+  // Check if already exists using format-aware helper
+  const alreadyExists = hasServerEntry(config, MCP_SERVER_NAME, configFormat);
+  if (alreadyExists && !force) {
+    throw new CliError(
+      'VALIDATION',
+      `${getTargetDisplayName(target)} already has gno configured.\n` +
+        `  Config: ${configPath}\n` +
+        '  Use --force to overwrite.'
+    );
+  }
+
+  const wouldCreate = !alreadyExists;
+
+  if (dryRun) {
+    return {
+      target,
+      scope,
+      configPath,
+      action: wouldCreate ? 'dry_run_create' : 'dry_run_update',
+      serverEntry,
+    };
+  }
+
+  const action = wouldCreate ? 'created' : 'updated';
+
+  // Build format-specific entry and add to config
+  const entry = buildEntry(serverEntry.command, serverEntry.args, configFormat);
+  setServerEntry(config, MCP_SERVER_NAME, entry, configFormat);
+
+  // Write atomically
+  await writeMcpConfig(configPath, config, { yaml: useYaml });
+
+  return {
+    target,
+    scope,
+    configPath,
+    action,
+    serverEntry,
+  };
+}
+
+/**
+ * Get globals safely for testing.
+ */
+function safeGetGlobals(): { json: boolean; quiet: boolean } {
+  try {
+    return getGlobals();
+  } catch {
+    return { json: false, quiet: false };
+  }
+}
+
+/**
+ * Install gno MCP server.
+ */
+export async function installMcp(opts: InstallOptions = {}): Promise<void> {
+  const target = opts.target ?? 'claude-desktop';
+  const scope = opts.scope ?? 'user';
+  const force = opts.force ?? false;
+  const dryRun = opts.dryRun ?? false;
+  const globals = safeGetGlobals();
+  const json = opts.json ?? globals.json;
+  const quiet = opts.quiet ?? globals.quiet;
+
+  // Validate scope - only some targets support project scope
+  if (scope === 'project' && !TARGETS_WITH_PROJECT_SCOPE.includes(target)) {
+    throw new CliError(
+      'VALIDATION',
+      `${getTargetDisplayName(target)} does not support project scope. Use --scope user.`
+    );
+  }
+
+  // Build server entry (uses process.execPath, always succeeds)
+  const serverEntry = buildMcpServerEntry();
+
+  // Install
+  const result = await installToTarget(target, scope, serverEntry, {
+    force,
+    dryRun,
+    cwd: opts.cwd,
+    homeDir: opts.homeDir,
+  });
+
+  // Output
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ installed: result }, null, 2)}\n`);
+    return;
+  }
+
+  if (quiet) {
+    return;
+  }
+
+  if (dryRun) {
+    const dryRunVerb = result.action === 'dry_run_create' ? 'create' : 'update';
+    process.stdout.write('Dry run - no changes made.\n\n');
+    process.stdout.write(
+      `Would ${dryRunVerb} gno in ${getTargetDisplayName(target)}:\n`
+    );
+    process.stdout.write(`  Config: ${result.configPath}\n`);
+    process.stdout.write(`  Command: ${serverEntry.command}\n`);
+    process.stdout.write(`  Args: ${serverEntry.args.join(' ')}\n`);
+    return;
+  }
+
+  const verb = result.action === 'created' ? 'Installed' : 'Updated';
+  process.stdout.write(
+    `${verb} gno MCP server in ${getTargetDisplayName(target)}.\n`
+  );
+  process.stdout.write(`  Config: ${result.configPath}\n\n`);
+  process.stdout.write(
+    `Restart ${getTargetDisplayName(target)} to load the server.\n`
+  );
+}