ctxman 3.0.0 → 3.1.0

package/bin/cm-map.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * ctxman map - ranked repository map trimmed to a token budget
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getLogger } from '../lib/utils/logger.js';
+import { exitOnBrokenPipe } from '../lib/utils/cli-output.js';
+
+// `ctxman ... | head` closes stdout early; stop quietly instead of throwing EPIPE
+exitOnBrokenPipe();
+
+const STYLES = ['text', 'markdown', 'json', 'dot'];
+const ORDERS = ['rank', 'path'];
+
+function printHelp() {
+  console.log(`Repository map - the most important files and their signatures, within a token budget
+
+Usage: ctxman map [path] [options]
+
+Files are ranked by PageRank over the import graph (importer -> imported), blended with
+git change frequency and how often other files mention their functions. The best files
+are listed with one line per function (line, signature, tokens) until the budget is full.
+
+Options:
+  -t, --tokens N           Token budget for the map (default: 2048)
+  -f, --focus PATH         Bias the ranking toward a file or folder and its neighbours
+                           (repeatable)
+      --history N          Commits of git history to mine for change frequency
+                           (default: 300, 0 disables)
+      --order rank|path    Order of the files in the output (default: rank)
+      --important-last     Highest-ranked file at the end (rank order only)
+      --style STYLE        text (default), markdown, json, dot (Graphviz)
+      --json               Same as --style json
+      --graph              Print the dependency edges instead of the map
+  -o, --output FILE        Write to FILE instead of stdout
+      --copy               Copy to the clipboard instead of stdout
+      --no-redact          Do not mask secrets in signatures
+  -q, --quiet              No summary on stderr
+  -h, --help               Show this help
+
+Score:
+  0.70 x PageRank + 0.25 x change frequency + 0.05 x symbol references, each scaled to 0..1
+  (without git history: the other two, renormalised). See docs/commands/map.md.
+
+Examples:
+  ctxman map                                # map of the current directory, 2048 tokens
+  ctxman map --tokens 4096 --style markdown
+  ctxman map src --focus src/server.js      # around the file you are working on
+  ctxman map --important-last -o map.txt    # best files last, next to your question
+  ctxman map --graph --style dot | dot -Tsvg > deps.svg
+`);
+}
+
+/**
+ * Parse the command line
+ * @param {string[]} argv
+ * @returns {Object}
+ */
+function parseArgs(argv) {
+  const options = {
+    root: null,
+    tokens: undefined,
+    focus: [],
+    history: undefined,
+    order: undefined,
+    importantLast: false,
+    style: undefined,
+    graph: false,
+    output: null,
+    copy: false,
+    redact: true,
+    quiet: false,
+    help: false,
+  };
+  const integer = (name, value, minimum) => {
+    if (!/^\d+$/.test(value ?? '') || Number(value) < minimum) {
+      throw new Error(`${name} needs an integer >= ${minimum}, got ${JSON.stringify(value)}`);
+    }
+    return Number(value);
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    let arg = argv[i];
+    let inline;
+    if (arg.startsWith('--') && arg.includes('=')) {
+      inline = arg.slice(arg.indexOf('=') + 1);
+      arg = arg.slice(0, arg.indexOf('='));
+    }
+    const value = () => {
+      if (inline !== undefined) return inline;
+      if (i + 1 >= argv.length) throw new Error(`${arg} needs a value`);
+      return argv[++i];
+    };
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+      case '-t':
+      case '--tokens':
+        options.tokens = integer(arg, value(), 1);
+        break;
+      case '-f':
+      case '--focus':
+        options.focus.push(value());
+        break;
+      case '--history':
+        options.history = integer(arg, value(), 0);
+        break;
+      case '--order':
+        options.order = value();
+        if (!ORDERS.includes(options.order)) {
+          throw new Error(`--order must be one of ${ORDERS.join(', ')}`);
+        }
+        break;
+      case '--important-last':
+        options.importantLast = true;
+        break;
+      case '--style':
+        options.style = value();
+        if (!STYLES.includes(options.style)) {
+          throw new Error(`--style must be one of ${STYLES.join(', ')}`);
+        }
+        break;
+      case '--json':
+        options.style = 'json';
+        break;
+      case '--graph':
+        options.graph = true;
+        break;
+      case '-o':
+      case '--output':
+        options.output = value();
+        break;
+      case '--copy':
+        options.copy = true;
+        break;
+      case '--no-redact':
+        options.redact = false;
+        break;
+      case '-q':
+      case '--quiet':
+        options.quiet = true;
+        break;
+      default:
+        if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+        if (options.root !== null) throw new Error(`Unexpected argument: ${arg}`);
+        options.root = arg;
+    }
+  }
+  if (options.importantLast && options.order === 'path') {
+    throw new Error('--important-last cannot be combined with --order path');
+  }
+  return options;
+}
+
+/**
+ * A focus path is project-relative when it exists under the project, otherwise taken
+ * from the current directory (`ctxman map ../app --focus ../app/src/a.js`)
+ */
+function focusPath(root, entry) {
+  if (path.isAbsolute(entry) || fs.existsSync(path.resolve(root, entry))) return entry;
+  const fromCwd = path.resolve(entry);
+  return fs.existsSync(fromCwd) ? fromCwd : entry;
+}
+
+function formatMs(ms) {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    console.error('Run "ctxman map --help" for usage.');
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  // stdout carries only the map: logger lines and ignore-file notices go to stderr, and
+  // the map writes no log files into the project
+  getLogger({ level: process.env.LOG_LEVEL || 'warn', logToFile: false });
+  console.log = console.info = console.debug = console.error;
+  const { renderRepoMap } = await import('../lib/map/index.js');
+  const { default: ClipboardUtils } = await import('../lib/utils/clipboard-utils.js');
+
+  const root = path.resolve(options.root ?? '.');
+  const result = renderRepoMap(root, {
+    tokens: options.tokens,
+    focus: options.focus.map((entry) => focusPath(root, entry)),
+    history: options.history,
+    order: options.order,
+    importantLast: options.importantLast,
+    style: options.style,
+    graph: options.graph,
+    redact: options.redact,
+  });
+
+  if (options.output) {
+    fs.writeFileSync(options.output, result.output);
+  }
+  if (options.copy && !ClipboardUtils.copy(result.output)) {
+    process.exitCode = 1;
+  }
+  if (!options.output && !options.copy) {
+    process.stdout.write(result.output);
+  }
+
+  if (options.quiet) return;
+  for (const warning of result.warnings) console.error(`warning: ${warning}`);
+  const { stats } = result;
+  const parts = [];
+  if (options.graph || result.style === 'dot') {
+    parts.push(`${stats.edges} edges between ${stats.files} files`);
+  } else {
+    parts.push(`${result.files.length} of ${stats.files} files`);
+    parts.push(`${result.tokens}/${result.budget} tokens`);
+    parts.push(`${stats.edges} import edges`);
+  }
+  const history = result.graph.history;
+  if (history.available) parts.push(`history ${history.commits} commits`);
+  if (stats.skipped.length > 0) parts.push(`${stats.skipped.length} large/minified files left out`);
+  const redacted = Object.values(stats.redactions).reduce((sum, count) => sum + count, 0);
+  if (redacted > 0) parts.push(`${redacted} secrets redacted`);
+  parts.push(formatMs(stats.timings.total));
+  console.error(`ctxman map: ${parts.join(' · ')}`);
+  if (options.output) console.error(`Map written to ${options.output}`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/cm-mcp.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+/**
+ * ctxman mcp: start the MCP server, or add it to an MCP client's configuration
+ *
+ *   ctxman mcp [--transport stdio|sse] [--port N] [--host H] [--api-key K] [--cors] [--root DIR]
+ *   ctxman mcp install   --client NAME [--scope user|project] [--name N] [--dry-run] [--print]
+ *   ctxman mcp uninstall --client NAME [--scope user|project] [--name N] [--dry-run]
+ *   ctxman mcp config    --client NAME [--scope user|project] [--name N]
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parseArgs } from 'util';
+import { parseServerArgs, startMcpServer } from '../lib/api/mcp/start.js';
+import {
+  CLIENTS,
+  DEFAULT_SERVER_NAME,
+  SCOPES,
+  buildServerEntry,
+  buildSnippet,
+  getClient,
+  installServer,
+  manualCommands,
+  resolveConfigPath,
+  uninstallServer,
+} from '../lib/api/mcp/install.js';
+
+const SETUP_COMMANDS = ['install', 'uninstall', 'config'];
+
+const SETUP_OPTIONS = {
+  client: { type: 'string' },
+  scope: { type: 'string' },
+  name: { type: 'string' },
+  project: { type: 'string' },
+  file: { type: 'string' },
+  root: { type: 'string' },
+  npx: { type: 'boolean' },
+  force: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  print: { type: 'boolean' },
+  json: { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+// What to do after the config file changed
+const NEXT_STEPS = {
+  'claude-desktop': 'Restart Claude Desktop to load the server.',
+  'claude-code':
+    'Claude Code asks you to approve servers from .mcp.json on its next start; `claude mcp list` shows them.',
+  cursor: 'Restart Cursor (or toggle the server in Settings > MCP) to load it.',
+  vscode: 'Start the server from the .vscode/mcp.json editor or the "MCP: List Servers" command.',
+  windsurf: 'Refresh the MCP servers in Cascade to load it.',
+};
+
+function printHelp() {
+  const clientLines = Object.entries(CLIENTS).map(([id, info]) => {
+    const scopes = SCOPES.filter((scope) => [...info.scopes, ...info.manualScopes].includes(scope))
+      .map((scope) => {
+        const mark = scope === info.defaultScope ? `${scope}*` : scope;
+        return info.scopes.includes(scope) ? mark : `${mark} (prints instructions)`;
+      })
+      .join(', ');
+    return `  ${id.padEnd(16)}${scopes}`;
+  });
+
+  console.log(`ctxman mcp - Model Context Protocol server for AI assistants
+
+Usage:
+  ctxman mcp [options]                      Start the server (stdio by default)
+  ctxman mcp install --client <name>        Add the server to an MCP client's configuration
+  ctxman mcp uninstall --client <name>      Remove it again
+  ctxman mcp config --client <name>         Print the configuration snippet
+
+Server options:
+  --transport <stdio|sse>   Transport (default: stdio); sse serves streamable HTTP on /mcp
+  --port <n>                HTTP port (default: 3000)
+  --host <address>          HTTP address (default: 127.0.0.1)
+  --api-key <key>           Require this key (x-api-key header) on HTTP
+  --cors                    Send CORS headers on HTTP (off by default)
+  --root <dir>              Confine every tool path to <dir> (or set CTXMAN_MCP_ROOT)
+
+Client setup options:
+  --client <name>           ${Object.keys(CLIENTS).join(', ')}
+  --scope <user|project>    Which configuration (default: the starred scope below)
+  --name <name>             Server name in the configuration (default: ${DEFAULT_SERVER_NAME})
+  --project <dir>           Project directory for --scope project (default: current directory)
+  --file <path>             Use this configuration file instead of the client's default
+  --npx                     Run \`npx -y ctxman mcp\` instead of this installation
+  --root <dir>              Start the server with --root <dir>
+  --force                   Replace an existing, different entry of the same name
+  --dry-run                 Show the result without writing anything
+  --print                   Print the snippet instead of writing (same as \`config\`)
+  --json                    Print the result as JSON (install, uninstall)
+
+Clients and scopes:
+${clientLines.join('\n')}
+
+Before writing, the previous file is kept as <file>.bak. Other servers stay as they are.
+
+Examples:
+  ctxman mcp install --client claude-desktop
+  ctxman mcp install --client claude-code --scope project --npx
+  ctxman mcp install --client cursor --dry-run
+  ctxman mcp config --client vscode
+  ctxman mcp --transport sse --port 3333 --api-key secret
+  ctxman mcp --root ~/code/my-project`);
+}
+
+class UsageError extends Error {}
+
+/**
+ * Describe where the entry goes when ctxman does not write the file itself
+ */
+function printManual(client, scope, name, entry, target, uninstall = false) {
+  const info = getClient(client);
+  console.error(`${info.label} (${scope} scope): ${target.reason}`);
+  if (uninstall) {
+    if (client === 'claude-code') {
+      console.log(`claude mcp remove --scope user ${name}`);
+    } else {
+      console.error(`Remove the "${name}" entry under "${info.key}" by hand.`);
+    }
+    return;
+  }
+  const commands = manualCommands(client, scope, name, entry);
+  if (commands.length > 0) {
+    console.error('Run:');
+    for (const command of commands) console.log(command);
+    console.error('Or add this to the configuration:');
+  } else {
+    console.error('Add this to the configuration:');
+  }
+  console.log(JSON.stringify(buildSnippet(client, name, entry), null, 2));
+}
+
+function runSetup(command, argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({ args: argv, options: SETUP_OPTIONS, strict: true }));
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  if (values.help) {
+    printHelp();
+    return 0;
+  }
+  if (!values.client) throw new UsageError('--client is required');
+  let info;
+  try {
+    info = getClient(values.client);
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  const client = values.client;
+  const scope = values.scope ?? info.defaultScope;
+  if (!SCOPES.includes(scope)) {
+    throw new UsageError(`Unknown scope "${scope}" (expected user or project)`);
+  }
+  if (!values.file && ![...info.scopes, ...info.manualScopes].includes(scope)) {
+    throw new UsageError(`${info.label} has no ${scope} configuration`);
+  }
+  const name = values.name ?? DEFAULT_SERVER_NAME;
+  if (!/^[\w.-]+$/.test(name)) {
+    throw new UsageError(`Invalid server name "${name}" (letters, digits, _ . - only)`);
+  }
+  const projectDir = path.resolve(values.project ?? process.cwd());
+  if (scope === 'project' && !fs.statSync(projectDir, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new UsageError(`Project directory does not exist: ${projectDir}`);
+  }
+  let root;
+  if (values.root) {
+    root = path.resolve(values.root);
+    if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+      throw new UsageError(`--root is not an existing directory: ${root}`);
+    }
+  }
+
+  const entry = buildServerEntry(client, { npx: values.npx, root });
+  const target = values.file
+    ? { path: path.resolve(values.file) }
+    : resolveConfigPath(client, scope, { projectDir });
+
+  if (command === 'config' || values.print) {
+    if (target.path) {
+      console.error(`Add this to ${target.path} (${info.label}, ${scope} scope):`);
+      console.log(JSON.stringify(buildSnippet(client, name, entry), null, 2));
+    } else {
+      printManual(client, scope, name, entry, target);
+    }
+    return 0;
+  }
+
+  if (!target.path) {
+    printManual(client, scope, name, entry, target, command === 'uninstall');
+    return 0;
+  }
+
+  const dryRun = values['dry-run'] === true;
+  const result =
+    command === 'install'
+      ? installServer({ client, file: target.path, entry, name, force: values.force, dryRun })
+      : uninstallServer({ client, file: target.path, name, dryRun });
+
+  if (values.json) {
+    console.log(JSON.stringify({ client, scope, name, dryRun, ...result }, null, 2));
+    return result.status === 'conflict' ? 1 : 0;
+  }
+
+  const where = `${target.path} (${info.label}, ${scope} scope)`;
+  switch (result.status) {
+    case 'conflict':
+      console.error(`${where} already has a different "${name}" entry:`);
+      console.error(JSON.stringify(result.existing, null, 2));
+      console.error('Use --force to replace it (the old file is kept as .bak), or --name.');
+      return 1;
+    case 'unchanged':
+      console.log(`"${name}" is already set up in ${where}; nothing changed.`);
+      return 0;
+    case 'absent':
+      console.log(`No "${name}" entry in ${where}; nothing changed.`);
+      return 0;
+    default:
+      break;
+  }
+
+  const verb = { created: 'Created', added: 'Added', updated: 'Replaced', removed: 'Removed' }[
+    result.status
+  ];
+  if (dryRun) {
+    console.log(`Dry run: would write ${target.path}:`);
+    console.log(result.content.trimEnd());
+    return 0;
+  }
+  const subject = result.status === 'created' ? where : `"${name}" in ${where}`;
+  console.log(`${verb} ${subject}`);
+  if (result.backup) console.log(`Previous version: ${result.backup}`);
+  if (command === 'install') {
+    if (scope === 'project' && !values.npx) {
+      console.log(
+        'The entry holds absolute paths of this machine; use --npx for a file you commit.'
+      );
+    }
+    console.log(NEXT_STEPS[client]);
+  }
+  return 0;
+}
+
+async function runServer(argv) {
+  let options;
+  try {
+    options = parseServerArgs(argv, { strict: true });
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  try {
+    await startMcpServer(options);
+  } catch (error) {
+    console.error('Fatal error running MCP server:', error.message);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const [first, ...rest] = argv;
+  try {
+    if (first === 'help') {
+      printHelp();
+    } else if (SETUP_COMMANDS.includes(first)) {
+      process.exitCode = runSetup(first, rest);
+    } else if (first !== undefined && !first.startsWith('-')) {
+      throw new UsageError(`Unknown mcp command "${first}"`);
+    } else {
+      await runServer(argv);
+    }
+  } catch (error) {
+    if (error instanceof UsageError) {
+      console.error(`Error: ${error.message}`);
+      console.error('Run `ctxman mcp --help` for usage.');
+      process.exitCode = 2;
+      return;
+    }
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();