ctxman 3.0.0 → 3.1.1

package/lib/policy/audit.js

@@ -0,0 +1,312 @@
+/**
+ * Export audit log
+ *
+ * One JSON object per line, appended for every export (and every export the policy
+ * refused) while the policy enables `audit`. A record names the files and carries a
+ * SHA-256 of the exported text, never the text itself.
+ */
+
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { createRequire } from 'module';
+import { relativePathOf, loadPolicy, DEFAULT_AUDIT_PATH } from './policy.js';
+
+const { version: CTXMAN_VERSION } = createRequire(import.meta.url)('../../package.json');
+
+const defaultWarn = (message) => console.warn(message);
+
+/**
+ * SHA-256 of exported text; several parts (digest chunks) hash as their concatenation
+ * @param {string|Buffer|Array<string|Buffer>} text
+ * @returns {string} Hex digest
+ */
+export function sha256(text) {
+  const hash = crypto.createHash('sha256');
+  for (const part of Array.isArray(text) ? text : [text]) hash.update(part);
+  return hash.digest('hex');
+}
+
+/**
+ * Commit checked out in `dir`, or null outside a git repository
+ * @param {string} dir
+ * @returns {string|null}
+ */
+export function getGitHead(dir) {
+  try {
+    if (!dir || !fs.statSync(dir).isDirectory()) return null;
+    const head = execFileSync('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], {
+      cwd: dir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+    return /^[0-9a-f]{40,64}$/.test(head) ? head : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function currentUser() {
+  try {
+    return os.userInfo().username;
+  } catch (_error) {
+    // No passwd entry (some containers)
+    return process.env.USER || process.env.USERNAME || 'unknown';
+  }
+}
+
+function countRedactions(redactions) {
+  if (typeof redactions === 'number') return redactions;
+  if (redactions && typeof redactions === 'object') {
+    return Object.values(redactions).reduce((sum, count) => sum + (Number(count) || 0), 0);
+  }
+  return 0;
+}
+
+/**
+ * Build the audit record for an export event
+ * @param {import('./policy.js').Policy} policy
+ * @param {AuditEvent} event
+ * @returns {object}
+ */
+export function buildAuditRecord(policy, event = {}) {
+  const files = (event.files ?? []).map(relativePathOf);
+  const tokens =
+    typeof event.tokens === 'number'
+      ? event.tokens
+      : (event.files ?? []).reduce((sum, file) => sum + (Number(file?.tokens) || 0), 0);
+  const refused = event.outcome === 'refused';
+  const root = event.root ?? policy.root;
+
+  let digest = null;
+  if (!refused) {
+    if (event.sha256) digest = event.sha256;
+    else if (event.text !== undefined && event.text !== null) digest = sha256(event.text);
+  }
+
+  const record = {
+    id: crypto.randomUUID(),
+    timestamp: new Date().toISOString(),
+    outcome: refused ? 'refused' : 'exported',
+    command: event.command ?? null,
+    root,
+    user: currentUser(),
+    host: os.hostname(),
+    gitHead: event.gitHead !== undefined ? event.gitHead : getGitHead(root),
+    targetModel: event.targetModel ?? null,
+    format: event.format ?? null,
+    destination: event.destination ?? null,
+    fileCount: files.length,
+    totalTokens: tokens,
+    redactions: countRedactions(event.redactions),
+    removedByPolicy: event.removedByPolicy ?? 0,
+    files,
+    sha256: digest,
+    ctxmanVersion: CTXMAN_VERSION,
+  };
+  if (Array.isArray(event.outputFiles) && event.outputFiles.length > 0) {
+    record.outputFiles = event.outputFiles;
+  }
+  if (refused) {
+    record.violations = (event.violations ?? []).map(({ rule, message }) => ({ rule, message }));
+  }
+  return record;
+}
+
+/**
+ * @typedef {object} AuditEvent
+ * @property {string} command - What exported, e.g. "cli --context-export", "mcp generate_context"
+ * @property {string} [root] - Exported project (default: the policy root)
+ * @property {string|null} [targetModel]
+ * @property {string|null} [format] - Output format or style (json, toon, gitingest, xml, ...)
+ * @property {string} destination - "stdout", "clipboard", "mcp", "rest" or a file path
+ * @property {string[]} [outputFiles] - Every file written, when there are several (chunks)
+ * @property {Array<string|{relativePath?: string, path?: string, tokens?: number}>} [files]
+ * @property {number} [tokens] - Token total (default: sum of files[].tokens)
+ * @property {number|Object<string, number>} [redactions] - Count, or counts per secret type
+ * @property {number} [removedByPolicy] - Files dropped by the deny rules
+ * @property {string|Buffer|Array<string|Buffer>} [text] - Exported text; only its hash is kept
+ * @property {string} [sha256] - Precomputed hash instead of `text`
+ * @property {string|null} [gitHead] - Override the commit (default: HEAD of `root`)
+ * @property {'exported'|'refused'} [outcome]
+ * @property {Array<{rule: string, message: string}>} [violations] - For refused exports
+ */
+
+/**
+ * Append an export event to the policy's audit log(s). Does nothing unless the policy
+ * enables `audit`. Never throws: a log that cannot be written produces a warning.
+ * @param {import('./policy.js').Policy} policy - From loadPolicy()
+ * @param {AuditEvent} event
+ * @param {object} [options]
+ * @param {(message: string) => void} [options.warn=console.warn]
+ * @returns {object|null} The record written, or null when auditing is off
+ */
+export function recordExport(policy, event = {}, { warn = defaultWarn } = {}) {
+  if (!policy?.audit?.enabled) return null;
+
+  let record;
+  try {
+    record = buildAuditRecord(policy, event);
+  } catch (error) {
+    warn(`⚠️  Could not build the ctxman audit record: ${error.message}`);
+    return null;
+  }
+
+  const line = `${JSON.stringify(record)}\n`;
+  for (const file of policy.audit.paths) {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+    } catch (error) {
+      warn(`⚠️  Could not write the ctxman audit log ${file}: ${error.message}`);
+    }
+  }
+  return record;
+}
+
+/**
+ * The audit logs of a project's policy, or the default location when the policy names none
+ * @param {string} root - Project root
+ * @param {Object} [options]
+ * @param {object} [options.env=process.env] - Environment for loading the policy
+ * @returns {{files: string[], error: Error|null}} `error` when the policy could not be
+ *   loaded (the default location is returned then)
+ */
+export function auditLogFiles(root, { env = process.env } = {}) {
+  try {
+    const policy = loadPolicy(root, { env });
+    if (policy.audit.paths.length > 0) return { files: policy.audit.paths, error: null };
+    return { files: [path.join(root, DEFAULT_AUDIT_PATH)], error: null };
+  } catch (error) {
+    return { files: [path.join(root, DEFAULT_AUDIT_PATH)], error };
+  }
+}
+
+/**
+ * Read audit logs. Lines that are not JSON objects are skipped and counted; events that
+ * appear in several logs (organisation and project) are listed once.
+ * @param {string[]} files
+ * @returns {{events: object[], skipped: number, missing: string[]}} Events oldest first
+ */
+export function readAuditLog(files) {
+  const events = [];
+  const seen = new Set();
+  const missing = [];
+  let skipped = 0;
+
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (_error) {
+      missing.push(file);
+      continue;
+    }
+
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch (_error) {
+        skipped++;
+        continue;
+      }
+      if (!event || typeof event !== 'object' || Array.isArray(event)) {
+        skipped++;
+        continue;
+      }
+      if (event.id && seen.has(event.id)) continue;
+      if (event.id) seen.add(event.id);
+      events.push(event);
+    }
+  }
+
+  events.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+  return { events, skipped, missing };
+}
+
+/**
+ * Parse a --since value: a date ("2026-10-01", ISO timestamp) or an age ("30m", "12h",
+ * "7d", "2w")
+ * @param {string} value
+ * @param {Date} [now]
+ * @returns {Date}
+ * @throws {Error} For anything else
+ */
+export function parseSince(value, now = new Date()) {
+  const relative = /^(\d+)\s*([mhdw])$/i.exec(String(value).trim());
+  if (relative) {
+    const unit = { m: 60e3, h: 3600e3, d: 86400e3, w: 7 * 86400e3 }[relative[2].toLowerCase()];
+    return new Date(now.getTime() - Number(relative[1]) * unit);
+  }
+  const time = Date.parse(value);
+  if (Number.isNaN(time)) {
+    throw new Error(
+      `Invalid --since value ${JSON.stringify(value)}: use a date (2026-10-01) or an age (7d, 12h)`
+    );
+  }
+  return new Date(time);
+}
+
+/**
+ * Keep events at or after `since`, then the last `limit` of them
+ * @param {object[]} events - Oldest first
+ * @param {{since?: Date|null, limit?: number|null}} [options]
+ * @returns {object[]}
+ */
+export function filterAuditEvents(events, { since = null, limit = null } = {}) {
+  let result = events;
+  if (since) {
+    result = result.filter((event) => Date.parse(event.timestamp) >= since.getTime());
+  }
+  if (limit && limit > 0 && result.length > limit) result = result.slice(-limit);
+  return result;
+}
+
+const fit = (value, width, { keepEnd = false } = {}) => {
+  const text = value === null || value === undefined || value === '' ? '-' : String(value);
+  if (text.length <= width) return text.padEnd(width);
+  return keepEnd ? `…${text.slice(-(width - 1))}` : `${text.slice(0, width - 1)}…`;
+};
+
+// A file destination inside the exported project is shown relative to it
+const destinationOf = (event) => {
+  const destination = event.destination;
+  if (typeof destination !== 'string' || typeof event.root !== 'string') return destination;
+  const relative = path.relative(event.root, destination);
+  return path.isAbsolute(destination) && relative && !relative.startsWith('..')
+    ? relative
+    : destination;
+};
+
+/**
+ * Render events as a fixed-width table
+ * @param {object[]} events
+ * @returns {string}
+ */
+export function formatAuditTable(events) {
+  const columns = [
+    ['TIME (UTC)', 20, (e) => String(e.timestamp ?? '').replace(/\.\d+Z$/, 'Z')],
+    ['RESULT', 8, (e) => e.outcome],
+    ['USER', 12, (e) => e.user],
+    ['COMMAND', 26, (e) => e.command],
+    ['DESTINATION', 28, destinationOf, { keepEnd: true }],
+    ['MODEL', 16, (e) => e.targetModel],
+    ['FILES', 6, (e) => e.fileCount],
+    ['TOKENS', 10, (e) => (typeof e.totalTokens === 'number' ? e.totalTokens : null)],
+    ['REDACT', 6, (e) => e.redactions],
+    ['SHA256', 12, (e) => (e.sha256 ? e.sha256.slice(0, 12) : null)],
+  ];
+
+  const header = columns.map(([title, width]) => fit(title, width)).join(' ');
+  const rows = events.map((event) =>
+    columns.map(([, width, get, options]) => fit(get(event), width, options)).join(' ')
+  );
+  return [header, '-'.repeat(header.length), ...rows].map((line) => line.trimEnd()).join('\n');
+}
+
+export default { recordExport, readAuditLog, formatAuditTable, sha256 };

package/lib/policy/enforce.js

@@ -0,0 +1,125 @@
+/**
+ * Export enforcement: checks an export request against the effective policy
+ */
+
+import { recordExport } from './audit.js';
+import { relativePathOf } from './policy.js';
+
+/** Exit code of a CLI export the policy refused */
+export const POLICY_VIOLATION_EXIT_CODE = 3;
+
+/**
+ * An export the policy does not allow
+ */
+export class PolicyViolationError extends Error {
+  /**
+   * @param {Array<{rule: string, message: string, sources: string[]}>} violations
+   */
+  constructor(violations) {
+    super(
+      `Export refused by the ctxman policy:\n${violations.map((v) => `  - ${v.message}`).join('\n')}`
+    );
+    this.name = 'PolicyViolationError';
+    this.code = 'POLICY_VIOLATION';
+    this.violations = violations;
+    this.statusCode = 403;
+    this.exitCode = POLICY_VIOLATION_EXIT_CODE;
+  }
+}
+
+const formatNumber = (value) => value.toLocaleString('en-US');
+const inFiles = (files) => (files.length > 0 ? ` (set in ${files.join(', ')})` : '');
+
+/**
+ * Check an export against the policy. Callers remove denied files before exporting; a
+ * denied file still in `files` is reported as a violation.
+ * @param {import('./policy.js').Policy} policy - From loadPolicy()
+ * @param {object} request
+ * @param {Array<string|{relativePath?: string, path?: string, tokens?: number}>} [request.files]
+ *   Files in the export
+ * @param {number} [request.tokens] - Token total of the export (default: sum of files[].tokens)
+ * @param {boolean} [request.redact=true] - False when secret redaction was turned off (--no-redact)
+ * @param {string|null} [request.targetModel] - Model named with --target-model, if any
+ * @throws {PolicyViolationError} Listing every rule the export breaks
+ */
+export function enforceExport(
+  policy,
+  { files = [], tokens, redact = true, targetModel = null } = {}
+) {
+  if (!policy?.active) return;
+
+  const violations = [];
+
+  const deniedSources = new Set();
+  let denied = 0;
+  for (const file of files) {
+    const source = policy.deniedBy(relativePathOf(file));
+    if (source) {
+      denied++;
+      deniedSources.add(source);
+    }
+  }
+  if (denied > 0) {
+    violations.push({
+      rule: 'deny',
+      message: `${denied} file${denied === 1 ? '' : 's'} in the export ${denied === 1 ? 'matches' : 'match'} the policy's deny rules and can never be exported${inFiles([...deniedSources])}`,
+      sources: [...deniedSources],
+    });
+  }
+
+  if (redact === false && policy.requireRedaction) {
+    violations.push({
+      rule: 'requireRedaction',
+      message: `secret redaction is required, so --no-redact is refused${inFiles(policy.requireRedactionSources)}`,
+      sources: policy.requireRedactionSources,
+    });
+  }
+
+  const total =
+    typeof tokens === 'number'
+      ? tokens
+      : files.reduce((sum, file) => sum + (Number(file?.tokens) || 0), 0);
+  if (policy.maxExportTokens !== null && total > policy.maxExportTokens) {
+    violations.push({
+      rule: 'maxExportTokens',
+      message: `the export has ${formatNumber(total)} tokens, over the limit of ${formatNumber(policy.maxExportTokens)}${inFiles([policy.maxExportTokensSource])}; narrow it with .contextinclude, --changed-only or a template`,
+      sources: [policy.maxExportTokensSource],
+    });
+  }
+
+  if (targetModel && !policy.isModelAllowed(targetModel)) {
+    const rejecting = policy.modelRules.filter(
+      (rule) => !rule.regexes.some((regex) => regex.test(targetModel))
+    );
+    const allowed = rejecting.map((rule) => rule.patterns.join(', ')).join('; and ');
+    violations.push({
+      rule: 'allowedTargetModels',
+      message: `target model "${targetModel}" is not allowed (allowed: ${allowed})${inFiles(rejecting.map((rule) => rule.file))}`,
+      sources: rejecting.map((rule) => rule.file),
+    });
+  }
+
+  if (violations.length > 0) throw new PolicyViolationError(violations);
+}
+
+/**
+ * enforceExport() followed by recordExport(): the usual call right before an export is
+ * handed out. A refused export is logged with outcome "refused" and the error re-thrown.
+ * @param {import('./policy.js').Policy} policy
+ * @param {import('./audit.js').AuditEvent & {redact?: boolean}} event
+ * @param {object} [options] - Passed to recordExport()
+ * @returns {object|null} The audit record, or null when auditing is off
+ * @throws {PolicyViolationError}
+ */
+export function guardExport(policy, event, options) {
+  if (!policy?.active) return null;
+  try {
+    enforceExport(policy, event);
+  } catch (error) {
+    if (error instanceof PolicyViolationError) {
+      recordExport(policy, { ...event, outcome: 'refused', violations: error.violations }, options);
+    }
+    throw error;
+  }
+  return recordExport(policy, event, options);
+}

package/lib/policy/ignore-files.js

@@ -0,0 +1,169 @@
+/**
+ * AI-tool ignore files
+ *
+ * Other coding assistants keep their own ignore file next to .gitignore. A team that already
+ * lists its sensitive paths there can have ctxman honour the same lists instead of copying
+ * them into .contextignore. All of them use .gitignore syntax, so the existing parser reads
+ * them; only the files in the project root are read.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import GitIgnoreParser from '../parsers/gitignore-parser.js';
+
+/**
+ * Known ignore files, with the tool that reads each one
+ * @type {ReadonlyArray<{file: string, tool: string, emptyMeansAll?: boolean}>}
+ */
+export const KNOWN_IGNORE_FILES = Object.freeze([
+  { file: '.cursorignore', tool: 'Cursor' },
+  { file: '.cursorindexingignore', tool: 'Cursor (indexing only)' },
+  // Gemini Code Assist / Android Studio: an empty .aiexclude blocks its whole directory
+  { file: '.aiexclude', tool: 'Gemini Code Assist', emptyMeansAll: true },
+  { file: '.geminiignore', tool: 'Gemini CLI' },
+  { file: '.augmentignore', tool: 'Augment Code' },
+  { file: '.tabnineignore', tool: 'Tabnine' },
+  { file: '.devinignore', tool: 'Devin' },
+  { file: '.codeiumignore', tool: 'Windsurf (Codeium)' },
+  { file: '.aiderignore', tool: 'Aider' },
+  { file: '.clineignore', tool: 'Cline' },
+  { file: '.rooignore', tool: 'Roo Code' },
+  { file: '.continueignore', tool: 'Continue' },
+  { file: '.repomixignore', tool: 'Repomix' },
+  { file: '.gitingestignore', tool: 'Gitingest' },
+]);
+
+const KNOWN_BY_NAME = new Map(KNOWN_IGNORE_FILES.map((entry) => [entry.file, entry]));
+
+/**
+ * Whether a name can be used as an ignore file: a bare file name in the project root
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isValidIgnoreFileName(name) {
+  return (
+    typeof name === 'string' &&
+    name.length > 0 &&
+    name !== '.' &&
+    name !== '..' &&
+    !/[/\\\0]/.test(name)
+  );
+}
+
+/**
+ * Turn a --respect-ignore-files value or a policy `ignoreFiles` list into file names.
+ * "all" stands for every known file; names are deduplicated and keep their order.
+ * @param {string|string[]|null|undefined} spec - "all", "a,b" or ["a", "b"]
+ * @returns {string[]}
+ * @throws {Error} For a name with a path separator or `..`
+ */
+export function resolveIgnoreFileNames(spec) {
+  if (spec === null || spec === undefined || spec === false) return [];
+
+  const items = (Array.isArray(spec) ? spec : String(spec).split(','))
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+
+  const names = [];
+  for (const item of items) {
+    const expanded = item === 'all' ? KNOWN_IGNORE_FILES.map((entry) => entry.file) : [item];
+    for (const name of expanded) {
+      if (!isValidIgnoreFileName(name)) {
+        throw new Error(
+          `Invalid ignore file name ${JSON.stringify(name)}: expected a file name in the project root, such as .cursorignore, or "all"`
+        );
+      }
+      if (!names.includes(name)) names.push(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Patterns of the given ignore files in `root`. Each file is applied on its own: a path is
+ * ignored when any of the files ignores it, and a `!` line only re-includes paths matched
+ * earlier in the same file.
+ * @param {string} root - Project root
+ * @param {string[]} names - File names from resolveIgnoreFileNames()
+ * @returns {IgnoreFileRules}
+ */
+export function loadIgnoreFileRules(root, names) {
+  const parser = new GitIgnoreParser(null, null, null);
+  const files = names.map((name) => {
+    const filePath = path.join(root, name);
+    const known = KNOWN_BY_NAME.get(name);
+    const exists = isFile(filePath);
+    let patterns = exists ? parser.parsePatternFile(filePath) : [];
+    if (exists && patterns.length === 0 && known?.emptyMeansAll) {
+      patterns = [parser.convertToRegex('**')];
+    }
+    return { name, path: filePath, tool: known?.tool ?? null, exists, patterns };
+  });
+
+  return new IgnoreFileRules(parser, files);
+}
+
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (_error) {
+    return false;
+  }
+}
+
+/**
+ * Loaded ignore files and the matcher over them
+ */
+export class IgnoreFileRules {
+  /**
+   * @param {GitIgnoreParser} parser - Supplies the pattern matching
+   * @param {Array<{name: string, path: string, tool: string|null, exists: boolean, patterns: object[]}>} files
+   */
+  constructor(parser, files) {
+    this.parser = parser;
+    this.files = files;
+  }
+
+  /** @returns {boolean} True when at least one of the files exists */
+  get active() {
+    return this.files.some((file) => file.exists);
+  }
+
+  /**
+   * @param {string} relativePath - Path relative to the project root (file or directory)
+   * @returns {string|null} Name of the first ignore file that ignores the path, or null
+   */
+  match(relativePath) {
+    const rel = relativePath.split(path.sep).join('/');
+    for (const file of this.files) {
+      if (file.patterns.length > 0 && this.parser.testPatterns(file.patterns, rel, file.name)) {
+        return file.name;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * @param {string} relativePath
+   * @returns {boolean}
+   */
+  isIgnored(relativePath) {
+    return this.match(relativePath) !== null;
+  }
+
+  /**
+   * One line per file for console output, e.g. ".cursorignore (3 patterns)"
+   * @returns {string}
+   */
+  describe() {
+    return this.files
+      .map((file) =>
+        file.exists
+          ? `${file.name} (${file.patterns.length} pattern${file.patterns.length === 1 ? '' : 's'})`
+          : `${file.name} (not found)`
+      )
+      .join(', ');
+  }
+}
+
+export default { KNOWN_IGNORE_FILES, resolveIgnoreFileNames, loadIgnoreFileRules };

package/lib/policy/index.js

@@ -0,0 +1,53 @@
+/**
+ * Export policy and audit log
+ *
+ * The calls an exporting command makes:
+ *
+ *   const policy = loadPolicy(root);                 // once, before scanning
+ *   const scanner = new Scanner(root, { policy });   // drops denied files
+ *   ...build the export...
+ *   guardExport(policy, { command, destination, format, targetModel, files, tokens,
+ *                         redact, redactions, text });  // throws PolicyViolationError
+ *   ...write / send the export...
+ *
+ * guardExport() is enforceExport() plus recordExport(); call the two separately when the
+ * export must be checked before it is built.
+ */
+
+export {
+  loadPolicy,
+  Policy,
+  PolicyConfigError,
+  validatePolicyDocument,
+  createStarterPolicy,
+  normalizeRelativePath,
+  relativePathOf,
+  modelGlobToRegex,
+  POLICY_FILE,
+  POLICY_ENV,
+  DEFAULT_AUDIT_PATH,
+  POLICY_DOCS_URL,
+} from './policy.js';
+export {
+  enforceExport,
+  guardExport,
+  PolicyViolationError,
+  POLICY_VIOLATION_EXIT_CODE,
+} from './enforce.js';
+export {
+  recordExport,
+  buildAuditRecord,
+  readAuditLog,
+  auditLogFiles,
+  filterAuditEvents,
+  formatAuditTable,
+  parseSince,
+  getGitHead,
+  sha256,
+} from './audit.js';
+export {
+  KNOWN_IGNORE_FILES,
+  resolveIgnoreFileNames,
+  loadIgnoreFileRules,
+  IgnoreFileRules,
+} from './ignore-files.js';