ctxman 3.1.1 → 3.2.7

package/bin/cm-task.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * ctxman task - task-driven auto context pack
+ *
+ * stdout carries the context document (unless -o/--output or --copy); summary goes to stderr.
+ * Exit codes: 0 done, 1 error, 2 invalid arguments / options.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getLogger } from '../lib/utils/logger.js';
+
+function printHelp() {
+  process.stdout.write(`ctxman task - build task-driven context bundle around a goal
+
+Usage: ctxman task "<goal>" [root] [options]
+
+Discovers seed files and symbols via hybrid search, traverses 1-hop full code
+and 2-hop compressed signatures around them (across module imports and the
+cross-file AST symbol call graph), prepends an architectural repo map,
+and packs everything strictly within the token budget.
+
+Options:
+      --repo DIR           Additional repository root to include in workspace (repeatable)
+      --budget TOKENS      Token budget (e.g. 32000, 32k, 40k; default: 32000)
+      --model MODEL        Target model profile (e.g. claude-sonnet-4-5)
+      --format FORMAT      Output format: markdown (default), json, xml
+      --json               Shorthand for --format json
+      --search-mode MODE   Search mode: hybrid (default), bm25, semantic
+      --calls              Include cross-file AST symbol call graph edges (default)
+      --no-calls           Disable AST symbol call graph edges (module imports only)
+      --no-redact          Do not mask secrets
+  -o, --output FILE        Write output to FILE instead of stdout
+      --copy               Copy document to clipboard
+  -q, --quiet              Do not print summary to stderr
+  -h, --help               Show this help
+
+Examples:
+  ctxman task "Add SQLite vector store"
+  ctxman task "Fix OAuth token refresh" --budget 40k --format json
+  ctxman task "Add invoice checkout webhook" --repo ../billing-api --repo ../checkout-web
+  ctxman task "Refactor tokenizer" -o task-context.md
+`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  getLogger({ level: process.env.LOG_LEVEL || 'error', logToFile: false });
+  console.log = console.info = console.debug = console.error;
+
+  const { buildTaskContext, parseBudget } = await import('../lib/task/index.js');
+
+  let goal = null;
+  let root = process.cwd();
+  const repos = [];
+  let budget = 32000;
+  let model = null;
+  let format = 'markdown';
+  let searchMode = 'hybrid';
+  let callGraph = true;
+  let redact = true;
+  let outputFile = null;
+  let copy = false;
+  let quiet = false;
+
+  try {
+    for (let i = 0; i < argv.length; i++) {
+      const arg = argv[i];
+
+      if (arg === '--help' || arg === '-h') {
+        printHelp();
+        return;
+      } else if (arg === '--root' || arg === '-r') {
+        if (i + 1 >= argv.length) throw new Error('--root needs a directory path');
+        root = path.resolve(argv[++i]);
+      } else if (arg.startsWith('--root=')) {
+        root = path.resolve(arg.slice('--root='.length));
+      } else if (arg === '--repo') {
+        if (i + 1 >= argv.length) throw new Error('--repo needs a directory path');
+        repos.push(path.resolve(argv[++i]));
+      } else if (arg.startsWith('--repo=')) {
+        const val = arg.slice('--repo='.length);
+        if (!val) throw new Error('--repo needs a directory path');
+        repos.push(path.resolve(val));
+      } else if (arg === '--budget') {
+        budget = parseBudget(argv[++i]);
+      } else if (arg.startsWith('--budget=')) {
+        budget = parseBudget(arg.slice('--budget='.length));
+      } else if (arg === '--model' || arg === '--target-model') {
+        model = argv[++i];
+      } else if (arg.startsWith('--model=')) {
+        model = arg.slice('--model='.length);
+      } else if (arg === '--format') {
+        format = argv[++i];
+      } else if (arg.startsWith('--format=')) {
+        format = arg.slice('--format='.length);
+      } else if (arg === '--json') {
+        format = 'json';
+      } else if (arg === '--search-mode') {
+        searchMode = argv[++i];
+      } else if (arg.startsWith('--search-mode=')) {
+        searchMode = arg.slice('--search-mode='.length);
+      } else if (arg === '--calls' || arg === '--call-graph') {
+        callGraph = true;
+      } else if (arg === '--no-calls' || arg === '--no-call-graph') {
+        callGraph = false;
+      } else if (arg === '--no-redact') {
+        redact = false;
+      } else if (arg === '-o' || arg === '--output') {
+        outputFile = argv[++i];
+      } else if (arg.startsWith('-o=')) {
+        outputFile = arg.slice('-o='.length);
+      } else if (arg.startsWith('--output=')) {
+        outputFile = arg.slice('--output='.length);
+      } else if (arg === '--copy') {
+        copy = true;
+      } else if (arg === '-q' || arg === '--quiet') {
+        quiet = true;
+      } else if (!arg.startsWith('-')) {
+        if (goal === null) {
+          goal = arg;
+        } else if (fs.existsSync(arg) && fs.statSync(arg).isDirectory()) {
+          root = arg;
+        } else {
+          goal += ` ${arg}`;
+        }
+      } else {
+        process.stderr.write(`Unknown option: ${arg}\n`);
+        process.exitCode = 2;
+        return;
+      }
+    }
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (!goal) {
+    process.stderr.write('Error: A task goal is required.\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  try {
+    const result = await buildTaskContext(root, goal, {
+      repos,
+      budget,
+      model,
+      format,
+      searchMode,
+      callGraph,
+      redact,
+      output: outputFile,
+    });
+
+    if (copy) {
+      const { default: ClipboardUtils } = await import('../lib/utils/clipboard-utils.js');
+      await ClipboardUtils.copy(result.text);
+      if (!quiet) {
+        process.stderr.write(`Copied ${result.totalTokens} tokens to clipboard.\n`);
+      }
+    } else if (!outputFile) {
+      process.stdout.write(result.text + (result.text.endsWith('\n') ? '' : '\n'));
+    }
+
+    if (!quiet) {
+      const repoLabel = result.repos?.length > 1 ? ` across ${result.repos.length} repos` : '';
+      process.stderr.write(
+        `Task Context: ${result.files.length} file(s)${repoLabel}, ${result.totalTokens}/${result.budget} tokens (${result.format}).\n`
+      );
+      if (outputFile) {
+        process.stderr.write(`Saved to: ${outputFile}\n`);
+      }
+    }
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = error.exitCode ?? 1;
+  }
+}
+
+process.stdout.on('error', (error) => {
+  if (error.code !== 'EPIPE') throw error;
+  process.exit(process.exitCode ?? 0);
+});
+
+main();

package/bin/cm-who.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * ctxman who - "Who knows about this?" Expert Finder across git blame, recency-decayed commit history,
+ * CODEOWNERS stewardship, and natural-language topic search.
+ */
+
+import { parseArgs } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../lib/utils/logger.js';
+
+getLogger({ level: 'error', logToFile: false });
+const writeOut = (text) => process.stdout.write(text);
+console.log = console.info = console.debug = console.error;
+
+const { findExperts, WhoError, DEFAULT_WHO_LIMIT, DEFAULT_COMMIT_WINDOW, DEFAULT_HALF_LIFE_DAYS } =
+  await import('../lib/who/index.js');
+
+const HELP = `Usage: ctxman who <target-or-topic> [options]
+
+Find the code and domain experts for a file, symbol, line range, directory, or
+natural-language topic by fusing surviving git blame ownership, recency-decayed
+commit/churn depth, and CODEOWNERS stewardship (single-repo or multi-repo workspace).
+
+Targets:
+  <file>                    A single file (e.g. lib/why/index.js or <alias>/src/index.js)
+  <file>:<symbol>           A function, method, or class (e.g. lib/why/index.js:explainHistory)
+  <file>#L10-L40            A line range
+  <directory>               A directory / subsystem (e.g. lib/rag or <alias>/src)
+  "<topic query>"           A natural-language concept resolved via BM25 code search
+
+Options:
+      --root <dir>          Primary repository root (default: cwd)
+      --repo <dir>          Additional repository root for multi-repo workspace (repeatable)
+  -n, --limit <n>           Maximum experts to return (default: ${DEFAULT_WHO_LIMIT})
+      --commits <n>         Commit window to examine (default: ${DEFAULT_COMMIT_WINDOW})
+      --half-life <days>    Recency decay half-life in days (default: ${DEFAULT_HALF_LIFE_DAYS})
+      --since <date>        Only examine commits after this date
+      --style <style>       markdown (default), xml, or json
+      --json                Same as --style json
+  -o, --output <file>       Write output to a file instead of stdout
+  -h, --help                Show this help
+`;
+
+const OPTIONS = {
+  root: { type: 'string' },
+  repo: { type: 'string', multiple: true },
+  limit: { type: 'string', short: 'n' },
+  commits: { type: 'string' },
+  'half-life': { type: 'string' },
+  since: { type: 'string' },
+  style: { type: 'string' },
+  json: { type: 'boolean' },
+  output: { type: 'string', short: 'o' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+function fail(message, exitCode = 1) {
+  process.stderr.write(`ctxman who: ${message}\n`);
+  process.exitCode = exitCode;
+}
+
+async function run() {
+  let parsed;
+  try {
+    parsed = parseArgs({ options: OPTIONS, allowPositionals: true });
+  } catch (err) {
+    fail(err.message);
+    return;
+  }
+
+  const { values, positionals } = parsed;
+  if (values.help) {
+    writeOut(HELP);
+    return;
+  }
+
+  const target = positionals.join(' ').trim();
+  if (!target) {
+    fail('missing <target-or-topic>. Run `ctxman who --help` for usage.');
+    return;
+  }
+
+  const style = values.json ? 'json' : values.style || 'markdown';
+  if (!['markdown', 'xml', 'json'].includes(style)) {
+    fail(`unsupported --style "${style}" (expected markdown, xml, or json)`);
+    return;
+  }
+
+  const rootDir = values.root ? path.resolve(process.cwd(), values.root) : process.cwd();
+  const extraRepos = Array.isArray(values.repo)
+    ? values.repo.map((r) => path.resolve(process.cwd(), r))
+    : undefined;
+
+  try {
+    const result = await findExperts(rootDir, target, {
+      repos: extraRepos,
+      limit: values.limit ? Number(values.limit) : undefined,
+      commitWindow: values.commits ? Number(values.commits) : undefined,
+      halfLifeDays: values['half-life'] ? Number(values['half-life']) : undefined,
+      since: values.since,
+      style,
+    });
+
+    if (values.output) {
+      fs.writeFileSync(values.output, result.text, 'utf8');
+    } else {
+      writeOut(result.text);
+    }
+  } catch (err) {
+    if (err instanceof WhoError) {
+      fail(err.message);
+      return;
+    }
+    throw err;
+  }
+}
+
+await run();

package/bin/cm-why.js

@@ -30,22 +30,30 @@ Explain why code looks the way it does: the commits that shaped it (with their
 messages), the issues, tickets and URLs they reference, blame ownership, files
 that change together with it, docs / ADRs / changelog entries / comments that
 mention it, TODO-style notes inside it and the tests that reference it. Built
-from the local git history; no network access.
+from the local git history (offline by default; opt in to --discussions for
+GitHub/GitLab issue, PR and MR context).
 
-Targets (paths are relative to the current directory, inside the repository):
+Targets (paths are relative to the current directory, or <alias>/<file> with --repo):
   <file>                    The whole file (history follows renames)
   <file>:<symbol>           A function, method or class: total, Cart.total, Cart::total
   <file>#L10-L40            A line range (also <file>#L10 and <file>:10-40)
 
 Options:
+      --repo <dir>          Additional repository root for multi-repo workspaces (repeatable)
   -n, --limit <n>           Commits to include (default: 20)
       --since <date>        Only commits after this date ("2024-01-01", "6 months ago")
       --rev <ref>           Explain the code as of this revision (default: working tree)
       --patches             Include each commit's diff of the target
+      --analyzer-db <path>  Query @plansmithai/analyzer SQLite DB for institutional citations
+      --analyzer            Enable analyzer citations from .plansmith/analyzer.sqlite
+      --discussions         Fetch referenced GitHub/GitLab issue, PR and MR discussions
+                            (uses GITHUB_TOKEN/GH_TOKEN or GITLAB_TOKEN when set)
+      --max-discussions <n> Maximum remote discussions to fetch (default: 10)
+      --max-comments <n>    Maximum comments fetched per discussion (default: 5)
       --coupling-window <n> Commits of the file examined for co-changes (default: 500, 0 = off)
       --budget <tokens>     Keep the output within this many tokens (8000 or 8k); drops
-                            patches, related text, tests, coupling details and older
-                            commits first
+                            patches, discussions, related text, tests, coupling details
+                            and older commits first
       --style <style>       markdown (default), xml or json
       --json                Same as --style json
       --ask <question>      Append a question at the end of the document
@@ -56,16 +64,24 @@ Options:
 
 Examples:
   ctxman why src/cart.js:total
+  ctxman why backend/src/cart.js:total --repo ../docs-repo --repo ../e2e-tests
+  ctxman why src/cart.js:total --discussions
   ctxman why src/cart.js#L40-L72 --patches --budget 8000
   ctxman why lib/server.js --since "1 year ago" --style xml -o why.xml
   ctxman why src/cart.js:total --ask "Why do we round here instead of in applyDiscount?" --copy
 `;
 
 const OPTIONS = {
+  repo: { type: 'string', multiple: true },
   limit: { type: 'string', short: 'n' },
   since: { type: 'string' },
   rev: { type: 'string' },
   patches: { type: 'boolean' },
+  'analyzer-db': { type: 'string' },
+  analyzer: { type: 'boolean' },
+  discussions: { type: 'boolean' },
+  'max-discussions': { type: 'string' },
+  'max-comments': { type: 'string' },
   'coupling-window': { type: 'string' },
   budget: { type: 'string' },
   style: { type: 'string' },
@@ -108,6 +124,10 @@ function summarize(result) {
   const parts = [
     plural(data.history.commits.length, 'commit'),
     plural(references, 'reference'),
+    ...(data.institutionalCitations?.length
+      ? [plural(data.institutionalCitations.length, 'institutional citation')]
+      : []),
+    ...(data.discussions?.length ? [plural(data.discussions.length, 'discussion')] : []),
     plural(data.ownership?.authors.length ?? 0, 'author'),
     plural(data.coupling?.files.length ?? 0, 'co-changed file'),
     plural(data.related.length, 'related snippet'),
@@ -148,15 +168,31 @@ async function main() {
   }
 
   const cwd = process.cwd();
+  const extraRepos = values.repo?.length ? values.repo.map((r) => path.resolve(cwd, r)) : undefined;
   let result;
   try {
-    const root = findRepositoryRoot(cwd);
+    let root = cwd;
+    if (extraRepos) {
+      try {
+        root = findRepositoryRoot(cwd);
+      } catch {
+        root = cwd;
+      }
+    } else {
+      root = findRepositoryRoot(cwd);
+    }
     result = await explainHistory(root, positionals[0], {
       cwd,
+      repos: extraRepos,
       limit: values.limit,
       since: values.since,
       rev: values.rev,
       patches: values.patches,
+      discussions: values.discussions,
+      analyzerDb: values['analyzer-db'],
+      analyzer: values.analyzer,
+      maxDiscussions: values['max-discussions'],
+      maxComments: values['max-comments'],
       couplingWindow: values['coupling-window'],
       budget: parseTokenCount(values.budget),
       style: values.json ? 'json' : values.style,