ctxman 3.1.1 → 3.2.8

package/bin/cm-pack.js

@@ -25,6 +25,8 @@ and .contextinclude decide which files are included; binary files and files over
 are skipped. Secrets (API keys, tokens, private keys) are masked.
 
 Selection:
+      --repo DIR           Pack multiple repository roots into one document under a
+                           shared token budget, prefixed by repo name (repeatable)
       --include GLOB       Only files matching GLOB (repeatable or comma-separated)
       --exclude GLOB       Leave out files matching GLOB (repeatable or comma-separated)
       --stdin              Read the file list from stdin, one path per line, instead of
@@ -62,6 +64,7 @@ Output:
 
 Examples:
   ctxman pack -o context.xml
+  ctxman pack --repo ../api --repo ../web --budget 80k -o workspace.xml
   ctxman pack src --include "**/*.ts" --exclude "**/*.test.ts" --style markdown
   ctxman pack --compress --budget 100k --instructions task.md --copy
   git ls-files -z -- '*.py' | ctxman pack --stdin -0 --line-numbers
@@ -93,6 +96,7 @@ function parseSize(text, flag) {
 }
 
 const VALUE_OPTIONS = {
+  '--repo': 'repos',
   '--include': 'include',
   '--exclude': 'exclude',
   '--max-file-size': 'maxFileSize',
@@ -131,7 +135,7 @@ const FLAG_OPTIONS = {
  * @returns {object}
  */
 function parseArgs(argv) {
-  const options = { include: [], exclude: [], tree: true, redact: true, paths: [] };
+  const options = { repos: [], include: [], exclude: [], tree: true, redact: true, paths: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--') {
@@ -146,7 +150,9 @@ function parseArgs(argv) {
       else if (i + 1 < argv.length) value = argv[++i];
       else throw new Error(`${name} needs a value`);
       const key = VALUE_OPTIONS[name];
-      if (key === 'include' || key === 'exclude') {
+      if (key === 'repos') {
+        options.repos.push(value);
+      } else if (key === 'include' || key === 'exclude') {
         options[key].push(...value.split(',').filter((glob) => glob.trim()));
       } else {
         options[key] = value;
@@ -164,6 +170,9 @@ function parseArgs(argv) {
   if (options.paths.length > 1) {
     throw new Error(`Expected one project path, got ${options.paths.length}`);
   }
+  if (options.repos.length > 0 && options.stdin) {
+    throw new Error('--repo cannot be combined with --stdin');
+  }
   if (options.style !== undefined && !STYLES.includes(options.style)) {
     throw new Error(`--style must be one of ${STYLES.join(', ')}`);
   }
@@ -220,8 +229,10 @@ function display(file) {
 function printSummary(result, extras) {
   const lines = [];
   const style = result.style;
+  const repoLabel =
+    result.repos?.length > 1 ? ` across ${formatNumber(result.repos.length)} repos` : '';
   lines.push(
-    `ctxman pack: ${formatNumber(result.files.length)} file(s), ` +
+    `ctxman pack: ${formatNumber(result.files.length)} file(s)${repoLabel}, ` +
       `${formatNumber(result.totalTokens)} tokens (${style}, ${result.encoding})`
   );
   if (result.budget) {
@@ -313,7 +324,8 @@ async function main() {
 
   try {
     const { packContext } = await import('../lib/pack/index.js');
-    const root = path.resolve(args.paths[0] ?? '.');
+    const { packWorkspace } = await import('../lib/workspace/index.js');
+    const { PolicyConfigError, PolicyViolationError } = await import('../lib/policy/index.js');
     const output = args.output ? path.resolve(args.output) : null;
 
     const options = {
@@ -344,7 +356,26 @@ async function main() {
       options.cwd = process.cwd();
     }
 
-    const result = await packContext(root, options);
+    let result;
+    try {
+      if (args.repos.length > 0) {
+        const repoList = [
+          ...(args.paths.length > 0 ? [path.resolve(args.paths[0])] : []),
+          ...args.repos.map((r) => path.resolve(r)),
+        ];
+        result = await packWorkspace(repoList, options);
+      } else {
+        const root = path.resolve(args.paths[0] ?? '.');
+        result = await packContext(root, options);
+      }
+    } catch (error) {
+      if (error instanceof PolicyConfigError || error instanceof PolicyViolationError) {
+        process.stderr.write(`Error: ${error.message}\n`);
+        process.exitCode = error.exitCode;
+        return;
+      }
+      throw error;
+    }
     const extras = [];
 
     if (args.maxTokens && result.totalTokens > args.maxTokens) {

package/bin/cm-policy.js

@@ -11,12 +11,34 @@ import {
   loadPolicy,
   createStarterPolicy,
   loadIgnoreFileRules,
+  checkWorkspacePolicies,
   POLICY_FILE,
   POLICY_ENV,
   POLICY_DOCS_URL,
   PolicyConfigError,
 } from '../lib/policy/index.js';
 
+function collectRepos(args) {
+  const repos = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--repo') {
+      const next = args[++i];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--repo needs a directory path');
+      }
+      repos.push(next);
+    } else if (arg.startsWith('--repo=')) {
+      const value = arg.slice('--repo='.length);
+      if (!value) {
+        throw new Error('--repo needs a directory path');
+      }
+      repos.push(value);
+    }
+  }
+  return repos;
+}
+
 function main() {
   const args = process.argv.slice(2);
 
@@ -25,13 +47,27 @@ function main() {
     return;
   }
 
+  let repos = [];
+  try {
+    repos = collectRepos(args);
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+
   const command = args[0] && !args[0].startsWith('-') ? args[0] : 'check';
 
   switch (command) {
     case 'check':
-      check(args.includes('--json'));
+      check(args.includes('--json'), repos);
       break;
     case 'init':
+      if (repos.length > 0) {
+        console.error("❌ --repo is only supported with 'ctxman policy check'");
+        process.exitCode = 2;
+        return;
+      }
       init(args.includes('--force') || args.includes('-f'));
       break;
     default:
@@ -41,8 +77,76 @@ function main() {
   }
 }
 
-function check(json) {
+function checkWorkspace(root, json, repos) {
+  let result;
+  try {
+    result = checkWorkspacePolicies(root, repos);
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (!result.valid) {
+    process.exitCode = 2;
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const label = (text) => `${text}:`.padEnd(24);
+  console.log('🛡️  ctxman workspace export policy');
+  console.log(`Repositories (${result.repos.length}):`);
+  for (const repo of result.repos) {
+    if (!repo.valid) {
+      console.log(`  ❌ [${repo.alias}] ${repo.root}`);
+      console.error(`❌ [${repo.alias}] ${repo.message}`);
+      continue;
+    }
+    const state = repo.active
+      ? `active (${repo.sources.map((s) => s.scope).join(', ')})`
+      : 'no policy (unrestricted)';
+    console.log(`  ✅ [${repo.alias}] ${repo.root} — ${state}`);
+  }
+  console.log();
+  console.log(
+    label('Require redaction') + (result.requireRedaction ? 'yes (--no-redact is refused)' : 'no')
+  );
+  console.log(
+    label('Max export tokens') +
+      (result.maxExportTokens === null
+        ? 'no limit'
+        : result.maxExportTokens.toLocaleString('en-US'))
+  );
+  console.log(
+    label('Allowed target models') +
+      (!result.allowedTargetModels
+        ? 'any'
+        : result.allowedTargetModels
+            .map((rule) => `${rule.patterns.join(', ')} [${rule.repo}:${rule.scope}]`)
+            .join(' AND '))
+  );
+  console.log(
+    label('AI-tool ignore files') +
+      (result.ignoreFiles.length === 0 ? 'none' : result.ignoreFiles.join(', '))
+  );
+  console.log();
+  if (result.valid) {
+    console.log('✅ All workspace policies are valid.');
+  } else {
+    console.error('❌ One or more workspace policy files are invalid.');
+  }
+}
+
+function check(json, repos = []) {
   const root = process.cwd();
+  if (repos.length > 0) {
+    checkWorkspace(root, json, repos);
+    return;
+  }
+
   let policy;
   try {
     policy = loadPolicy(root);
@@ -156,6 +260,7 @@ function printHelp() {
   console.log('                       (default)');
   console.log(`  init                 Write a starter ${POLICY_FILE}\n`);
   console.log('Options:');
+  console.log('  --repo DIR           check: include another repository (repeatable)');
   console.log('  --json               check: print the effective policy as JSON');
   console.log('  -f, --force          init: overwrite an existing policy file');
   console.log('  -h, --help           Show this help\n');

package/bin/cm-pr.js

@@ -53,7 +53,7 @@ const FLAG_OPTIONS = {
  * @returns {object}
  */
 function parseArgs(argv) {
-  const parsed = { paths: [] };
+  const parsed = { paths: [], repos: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--') {
@@ -62,7 +62,13 @@ function parseArgs(argv) {
     }
     const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
     const name = eq > 0 ? arg.slice(0, eq) : arg;
-    if (VALUE_OPTIONS[name]) {
+    if (name === '--repo') {
+      let value;
+      if (eq > 0) value = arg.slice(eq + 1);
+      else if (i + 1 < argv.length) value = argv[++i];
+      else throw new Error('--repo needs a value');
+      parsed.repos.push(value);
+    } else if (VALUE_OPTIONS[name]) {
       let value;
       if (eq > 0) value = arg.slice(eq + 1);
       else if (i + 1 < argv.length) value = argv[++i];
@@ -109,6 +115,11 @@ function printSummary(result, extras) {
     const what = result.mode === 'staged' ? 'staged changes' : 'working tree';
     lines.push(`ctxman pr: ${what} against ${result.base.ref} (${result.mergeBase.short})`);
   }
+  if (Array.isArray(result.repos) && result.repos.length > 0) {
+    lines.push(
+      `  Repositories (${result.repos.length}): ${result.repos.map((r) => r.alias).join(', ')}`
+    );
+  }
   lines.push(
     `  ${stats.commits} commit(s), ${stats.files} file(s) (+${stats.additions} -${stats.deletions}), ` +
       `${stats.changedMethods} changed method(s), ${stats.deletedMethods} deleted, ` +
@@ -150,6 +161,7 @@ Arguments:
                            directory); a subdirectory limits the change to that directory
 
 What to compare:
+  --repo DIR               Additional repository root for multi-repo PR review (repeatable)
   --base REF               Base branch/commit (default: origin/HEAD, else main, else master)
   --head REF               Head branch/commit (default: HEAD)
   --staged                 Staged changes (index) against HEAD, or against --base
@@ -181,6 +193,7 @@ diff, methods and contents included; excluded files are still listed.
 Examples:
   ctxman pr                                  # current branch against the default branch
   ctxman pr --base main --head feature/login -o review.md
+  ctxman pr --repo ../api --repo ../web --base main --budget 16k
   ctxman pr --working --ask "Anything risky in these changes?"
   ctxman pr --budget 16k --style xml --with-tests --copy
 `);
@@ -201,6 +214,7 @@ async function main() {
   }
 
   try {
+    const cwd = process.cwd();
     const options = {
       base: args.base,
       head: args.head,
@@ -212,6 +226,7 @@ async function main() {
       redact: args.redact,
       style: args.style,
       ask: args.ask,
+      repos: args.repos.length > 0 ? args.repos.map((r) => path.resolve(cwd, r)) : undefined,
     };
     if (args.unified !== undefined) options.unified = parseCount(args.unified, '--unified');
     if (args.budget !== undefined) options.budget = parseTokenCount(args.budget);
@@ -220,7 +235,7 @@ async function main() {
     }
 
     const { buildPrContext } = await import('../lib/pr/pr-context.js');
-    const result = await buildPrContext(args.paths[0] || process.cwd(), options);
+    const result = await buildPrContext(args.paths[0] || cwd, options);
 
     const extras = [];
     let toStdout = !args.output && !args.copy;

package/bin/cm-search.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * ctxman search: ranked (BM25) search over the methods and code chunks of a project
+ * ctxman search: ranked (BM25, semantic, or RRF hybrid) search over methods and code chunks
  *
- *   ctxman search "<query>" [path] [--limit N] [--max-tokens N] [--json] [--full]
+ *   ctxman search "<query>" [path] [--repo DIR] [--hybrid | --mode bm25|semantic|hybrid]
+ *                 [--limit N] [--max-tokens N] [--json] [--full]
  *                 [--no-redact] [-o FILE] [--copy]
  */
 
@@ -11,6 +12,8 @@ import fs from 'fs';
 import path from 'path';
 import { parseArgs } from 'util';
 import { searchProject, DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from '../lib/search/bm25.js';
+import { hybridSearch, SEARCH_MODES } from '../lib/search/hybrid.js';
+import { searchWorkspace } from '../lib/workspace/index.js';
 import { getLogger } from '../lib/utils/logger.js';
 import ClipboardUtils from '../lib/utils/clipboard-utils.js';
 import { exitOnBrokenPipe } from '../lib/utils/cli-output.js';
@@ -23,6 +26,9 @@ const PREVIEW_LINES = 8;
 const OPTIONS = {
   limit: { type: 'string', short: 'n' },
   'max-tokens': { type: 'string' },
+  repo: { type: 'string', multiple: true },
+  hybrid: { type: 'boolean' },
+  mode: { type: 'string' },
   json: { type: 'boolean' },
   full: { type: 'boolean' },
   'no-redact': { type: 'boolean' },
@@ -36,19 +42,22 @@ const write = (text) => process.stdout.write(text);
 console.log = console.info = console.debug = console.error;
 
 function printHelp() {
-  write(`ctxman search - Ranked code search (BM25 over methods and code chunks)
+  write(`ctxman search - Ranked code search (BM25, semantic, or Reciprocal Rank Fusion hybrid)
 
 Usage:
   ctxman search "<query>" [path] [options]
 
-The query is a few words or identifiers. Identifiers are split into words (getUserName,
-get_user_name and get-user-name all mean "get user name"), and a chunk is a method or
-function, or a window of up to 40 lines of the code outside them. .gitignore,
-.contextignore and .contextinclude apply.
+The query is a few words, identifiers, or a natural-language phrase. Identifiers are split
+into words (getUserName, get_user_name and get-user-name all mean "get user name"), and a
+chunk is a method or function, or a window of up to 40 lines of the code outside them.
+.gitignore, .contextignore, .contextinclude, and .ctxman/policy.json apply.
 
 Options:
   -n, --limit <n>        Number of results (default: ${DEFAULT_LIMIT})
   --max-tokens <n>       Token budget for the returned code (default: ${DEFAULT_MAX_TOKENS})
+  --repo <dir>           Search across multiple repository roots under one token budget (repeatable)
+  --hybrid               Fuse BM25 lexical search with local vector embeddings via RRF
+  --mode <mode>          bm25 (default), hybrid, or semantic
   --full                 Print whole chunks instead of the first ${PREVIEW_LINES} lines
   --json                 Print the results as JSON
   --no-redact            Do not redact secrets in the returned code
@@ -58,6 +67,8 @@ Options:
 
 Examples:
   ctxman search "parse config file"
+  ctxman search "how authentication sessions expire" --hybrid
+  ctxman search "invoice total" --repo ../api --repo ../billing
   ctxman search getUserName ./services/api --limit 5
   ctxman search "retry backoff" --json | jq '.results[].file'
 `);
@@ -73,14 +84,29 @@ function positiveInteger(value, name) {
   return number;
 }
 
+function resolveMode(values) {
+  if (values.hybrid && values.mode !== undefined && values.mode !== 'hybrid') {
+    throw new UsageError(`Cannot combine --hybrid with --mode ${values.mode}`);
+  }
+  const mode = values.hybrid ? 'hybrid' : (values.mode ?? 'bm25');
+  if (!SEARCH_MODES.includes(mode)) {
+    throw new UsageError(`--mode must be one of ${SEARCH_MODES.join(', ')}, got "${mode}"`);
+  }
+  return mode;
+}
+
 /**
  * Human-readable listing
- * @param {ReturnType<typeof searchProject>} result
+ * @param {object} result
  * @param {boolean} full - Whole chunks instead of a preview
  * @returns {string}
  */
 function formatResults(result, full) {
-  const header = `Ranked search for "${result.query}" in ${result.root} (${result.files} files, ${result.chunks} chunks)\n`;
+  const modeLabel =
+    result.effectiveMode && result.effectiveMode !== 'bm25'
+      ? `${result.effectiveMode === 'hybrid' ? 'Hybrid (BM25 + semantic RRF)' : 'Semantic'} search`
+      : 'Ranked search';
+  const header = `${modeLabel} for "${result.query}" in ${result.root} (${result.files} files, ${result.chunks} chunks)\n`;
   if (result.results.length === 0) return `${header}\nNo matches.\n`;
 
   const width = String(result.results.length).length;
@@ -88,8 +114,17 @@ function formatResults(result, full) {
     const label = hit.name
       ? `  ${hit.parent ? `${hit.parent}.` : ''}${hit.name} (${hit.kind})`
       : '';
+    const ranks =
+      hit.bm25Rank !== undefined || hit.semanticRank !== undefined
+        ? ` [${[
+            hit.bm25Rank ? `bm25 #${hit.bm25Rank}` : null,
+            hit.semanticRank ? `sem #${hit.semanticRank}` : null,
+          ]
+            .filter(Boolean)
+            .join(', ')}]`
+        : '';
     const lines = [
-      `${String(i + 1).padStart(width)}. ${hit.file}:${hit.startLine}-${hit.endLine}${label}  score ${hit.score}`,
+      `${String(i + 1).padStart(width)}. ${hit.file}:${hit.startLine}-${hit.endLine}${label}  score ${hit.score}${ranks}`,
     ];
     if (hit.text === null) {
       lines.push('    (code left out: token budget reached)');
@@ -110,7 +145,7 @@ function formatResults(result, full) {
   return `${header}\n${blocks.join('\n\n')}\n`;
 }
 
-function main() {
+async function main() {
   let values;
   let positionals;
   try {
@@ -128,12 +163,19 @@ function main() {
     return;
   }
 
+  const mode = resolveMode(values);
+  const extraRepos = values.repo ?? [];
+  if (extraRepos.length > 0 && mode !== 'bm25') {
+    throw new UsageError('Multi-repository --repo search currently uses BM25 lexical mode');
+  }
+
   // A last positional that names a directory is the project; the rest is the query
-  let root = process.cwd();
+  let explicitRoot = null;
   const last = positionals.at(-1);
   if (positionals.length > 1 && fs.statSync(last, { throwIfNoEntry: false })?.isDirectory()) {
-    root = path.resolve(positionals.pop());
+    explicitRoot = path.resolve(positionals.pop());
   }
+  const root = explicitRoot ?? process.cwd();
   const query = positionals.join(' ').trim();
   if (!query) throw new UsageError('Missing query: ctxman search "<query>" [path]');
 
@@ -146,11 +188,34 @@ function main() {
 
   // Scan and analyzer progress lines are noise here; LOG_LEVEL still overrides
   getLogger().level = process.env.LOG_LEVEL || 'warn';
-  const result = searchProject(root, query, {
-    limit,
-    maxTokens,
-    redact: values['no-redact'] !== true,
-  });
+  const redact = values['no-redact'] !== true;
+
+  let result;
+  if (extraRepos.length > 0) {
+    const repoList = [
+      ...(explicitRoot ? [explicitRoot] : []),
+      ...extraRepos.map((r) => path.resolve(r)),
+    ];
+    result = searchWorkspace(repoList, query, { limit, maxTokens, redact });
+  } else if (mode === 'bm25') {
+    result = searchProject(root, query, { limit, maxTokens, redact });
+  } else {
+    result = await hybridSearch(root, query, {
+      mode,
+      limit,
+      maxTokens,
+      redact,
+      onProgress: (event) => {
+        if (event === 'indexing') {
+          console.error('Building local semantic embedding index (.ctxman/self-knowledge)...');
+        }
+      },
+    });
+  }
+
+  if (Array.isArray(result.warnings)) {
+    for (const warning of result.warnings) console.error(`Warning: ${warning}`);
+  }
 
   const output = values.json
     ? `${JSON.stringify(result, null, 2)}\n`
@@ -166,7 +231,7 @@ function main() {
 }
 
 try {
-  main();
+  await main();
 } catch (error) {
   console.error(`Error: ${error.message}`);
   if (error instanceof UsageError) {