session-orchestrator 3.16.0

package/scripts/lib/claude-md-budget-lint.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * claude-md-budget-lint.mjs — #722 Epic A Wave 3.
+ *
+ * Raw-file-property lint for a CLAUDE.md / AGENTS.md instruction file: line
+ * count, per-line character length, and (optionally) a provenance-header
+ * check on line 1. Deliberately narrow scope — this module measures
+ * properties of the instruction file itself and is NOT a replacement for
+ * `instruction-budget-guard.mjs` (which measures always-on directive COUNT
+ * across `.claude/rules/*.md`). The two are complementary probes, not
+ * layered: this lint fires at bootstrap-scaffold time (before `.claude/rules/`
+ * even exists), the directive-budget guard fires at session-start once rules
+ * are synced.
+ *
+ * CLI target resolution mirrors the project-instruction alias rule: when
+ * `--file` is omitted, `--repo-root` is searched for `CLAUDE.md` first and
+ * `AGENTS.md` second.
+ *
+ * Stdlib-only, no third-party deps. `lintClaudeMd()` is pure computation and
+ * throws `ClaudeMdLintInfraError` on any unreadable/missing-file condition —
+ * the CLI (`main()`) is the sole place that catches this and maps it to
+ * exit 2, mirroring the `checker.mjs` contract below.
+ *
+ * Exit-code contract (mirrors skills/claude-md-drift-check/checker.mjs):
+ *   0 — no violations, OR violations present but --mode warn
+ *   1 — violations present AND --mode hard (the CLI default)
+ *   2 — infra error (missing file, unreadable file, invalid --mode)
+ *
+ * Cross-references:
+ * - scripts/lib/instruction-budget-guard.mjs (sibling directive-count probe)
+ * - skills/claude-md-drift-check/checker.mjs (exit-code contract this mirrors)
+ * - scripts/lib/rules-sync.mjs (PLUGIN_HEADER_PREFIX provenance-header convention)
+ * - skills/bootstrap/fast-template.md § Step 2c (bootstrap wiring)
+ * - skills/bootstrap/SKILL.md § Phase 4.5 (bootstrap wiring)
+ */
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { resolveInstructionFile } from './common.mjs';
+
+/** Thrown by `lintClaudeMd()` on any infra-level failure (missing/unreadable file). */
+export class ClaudeMdLintInfraError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ClaudeMdLintInfraError';
+  }
+}
+
+/** Default line-count ceiling — mirrors the "lean root" convention (pointers, not prose). */
+export const DEFAULT_MAX_LINES = 150;
+/** Default per-line character ceiling. */
+export const DEFAULT_MAX_LINE_CHARS = 400;
+
+/** First-line provenance-header probe — accepts ANY source attribution, not only
+ * the plugin's own string (a baseline-generated CLAUDE.md carries its own header). */
+const PROVENANCE_HEADER_RE = /^<!--\s*source:/;
+
+/**
+ * Lints a CLAUDE.md / AGENTS.md file's raw properties. Pure computation —
+ * never catches its own read failures; throws `ClaudeMdLintInfraError`.
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath - absolute or cwd-relative path to the file.
+ * @param {number} [opts.maxLines] - line-count ceiling (default 150).
+ * @param {number} [opts.maxLineChars] - per-line char ceiling (default 400).
+ * @param {boolean} [opts.requireProvenance] - when true, a missing/absent
+ *   provenance header on line 1 is a violation (default false).
+ * @returns {{
+ *   status: 'ok' | 'invalid',
+ *   file: string,
+ *   lineCount: number,
+ *   maxLineCharsSeen: number,
+ *   hasProvenance: boolean,
+ *   violations: Array<{ rule: 'max-lines' | 'max-line-chars' | 'provenance-header', message: string, line?: number }>,
+ * }}
+ * @throws {ClaudeMdLintInfraError} when filePath is missing, not a file, or unreadable.
+ */
+export function lintClaudeMd(opts = {}) {
+  const {
+    filePath,
+    maxLines = DEFAULT_MAX_LINES,
+    maxLineChars = DEFAULT_MAX_LINE_CHARS,
+    requireProvenance = false,
+  } = opts;
+
+  if (!filePath || typeof filePath !== 'string') {
+    throw new ClaudeMdLintInfraError('lintClaudeMd: opts.filePath is required');
+  }
+
+  let content;
+  try {
+    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+      throw new ClaudeMdLintInfraError(`file not found: ${filePath}`);
+    }
+    content = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err instanceof ClaudeMdLintInfraError) throw err;
+    throw new ClaudeMdLintInfraError(`failed to read ${filePath}: ${err.message}`);
+  }
+
+  const lines = content.split('\n');
+  const lineCount = lines.length;
+  const violations = [];
+  let maxLineCharsSeen = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const len = lines[i].length;
+    if (len > maxLineCharsSeen) maxLineCharsSeen = len;
+    if (len > maxLineChars) {
+      violations.push({
+        rule: 'max-line-chars',
+        message: `Line ${i + 1} is ${len} chars, exceeds max-line-chars ${maxLineChars}`,
+        line: i + 1,
+      });
+    }
+  }
+
+  if (lineCount > maxLines) {
+    violations.push({
+      rule: 'max-lines',
+      message: `File has ${lineCount} lines, exceeds max-lines ${maxLines} — consider trimming to pointers (lean-root convention)`,
+    });
+  }
+
+  const hasProvenance = lines.length > 0 && PROVENANCE_HEADER_RE.test(lines[0]);
+
+  if (requireProvenance && !hasProvenance) {
+    violations.push({
+      rule: 'provenance-header',
+      message: "Line 1 does not carry a provenance header (expected '<!-- source: ...')",
+      line: 1,
+    });
+  }
+
+  return {
+    status: violations.length === 0 ? 'ok' : 'invalid',
+    file: filePath,
+    lineCount,
+    maxLineCharsSeen,
+    hasProvenance,
+    violations,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {
+    file: null,
+    repoRoot: process.cwd(),
+    maxLines: DEFAULT_MAX_LINES,
+    maxLineChars: DEFAULT_MAX_LINE_CHARS,
+    requireProvenance: false,
+    mode: 'hard',
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file') out.file = argv[++i];
+    else if (a === '--repo-root') out.repoRoot = argv[++i];
+    else if (a === '--max-lines') out.maxLines = Number.parseInt(argv[++i], 10);
+    else if (a === '--max-line-chars') out.maxLineChars = Number.parseInt(argv[++i], 10);
+    else if (a === '--require-provenance') out.requireProvenance = true;
+    else if (a === '--mode') out.mode = argv[++i];
+    else if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        'Usage: claude-md-budget-lint.mjs [--file CLAUDE.md|AGENTS.md] [--repo-root PATH] [--max-lines 150] ' +
+          '[--max-line-chars 400] [--require-provenance] [--mode hard|warn] [--json]\n'
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(JSON.stringify({ status: 'infra-error', reason: `unknown arg: ${a}` }) + '\n');
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+function resolveLintTarget(args) {
+  if (args.file) return args.file;
+  const repoRoot = resolve(args.repoRoot);
+  const instructionFile = resolveInstructionFile(repoRoot);
+  if (!instructionFile) {
+    throw new ClaudeMdLintInfraError(`no CLAUDE.md or AGENTS.md found under ${repoRoot}`);
+  }
+  return instructionFile.path;
+}
+
+function formatHuman(result, mode) {
+  const lines = [
+    `Instruction budget lint: ${result.status} (file: ${result.file}, lines: ${result.lineCount}, ` +
+      `maxLineCharsSeen: ${result.maxLineCharsSeen}, provenance: ${result.hasProvenance}, mode: ${mode})`,
+  ];
+  for (const v of result.violations) {
+    lines.push(`  - [${v.rule}] ${v.message}`);
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!['hard', 'warn'].includes(args.mode)) {
+    process.stderr.write(JSON.stringify({ status: 'infra-error', reason: `invalid --mode: ${args.mode}` }) + '\n');
+    process.exit(2);
+  }
+  if (!Number.isFinite(args.maxLines) || !Number.isFinite(args.maxLineChars)) {
+    process.stderr.write(JSON.stringify({ status: 'infra-error', reason: 'invalid --max-lines/--max-line-chars' }) + '\n');
+    process.exit(2);
+  }
+
+  let result;
+  try {
+    const filePath = resolveLintTarget(args);
+    result = lintClaudeMd({
+      filePath,
+      maxLines: args.maxLines,
+      maxLineChars: args.maxLineChars,
+      requireProvenance: args.requireProvenance,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    process.stderr.write(JSON.stringify({ status: 'infra-error', reason }) + '\n');
+    process.exit(2);
+    return;
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+  } else {
+    process.stdout.write(formatHuman(result, args.mode) + '\n');
+  }
+
+  process.exit(result.violations.length > 0 && args.mode === 'hard' ? 1 : 0);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const isMain =
+  typeof process !== 'undefined' &&
+  process.argv[1] !== null &&
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(__filename);
+
+if (isMain) main();

package/scripts/lib/cli-flags.mjs

@@ -0,0 +1,158 @@
+/**
+ * cli-flags.mjs — shared CLI-flag parser for the column-style migration scripts.
+ *
+ * Issue #510: three (now four) scripts each hand-rolled their own argv parsing —
+ * `vault-consolidate.mjs` used `node:util` parseArgs strict, `vault-mirror.mjs`
+ * used a `getArg`/`includes` style that SILENTLY ignored unknown flags,
+ * `migrate-cold-start-seed.mjs` used `includes` + a `knownFlags` Set, and
+ * `migrate-vault-paths.mjs` used a custom for-loop. This module unifies the
+ * PARSING + unknown-flag rejection behind a single function so the CLI
+ * convention (reject-on-unknown, `--json`/`--dry-run`/`--apply` support) has
+ * one source of truth.
+ *
+ * `parseColumnFlags` is intentionally THIN: it owns argv tokenisation,
+ * known-flag declaration, defaults, and unknown-flag rejection. It does NOT
+ * own per-script semantics like int/float coercion, `--dry-run`/`--apply`
+ * mutex checks, `--repos` comma-splitting, or required-flag validation — those
+ * stay in each script's post-parse block because they differ per script. The
+ * reference implementation is `node:util` parseArgs in strict mode, matching
+ * `vault-consolidate.mjs`'s prior style.
+ *
+ * `--dry-run`/`--apply` mutex — why it is NOT a shared helper here (#589
+ * LOW-qa-5, document-as-accepted): the three scripts that carry the mutex
+ * (`vault-consolidate.mjs`, `migrate-cold-start-seed.mjs`,
+ * `migrate-vault-paths.mjs`) each emit DIVERGENT, test-pinned error prose
+ * (different script-name prefixes; `die()` vs raw `process.stderr.write`) and
+ * derive `apply`/`dryRun` at different points in their own entry-point flow.
+ * The detection predicate (`values['dry-run'] && values.apply`) is a one-liner
+ * per script; centralising only that predicate would yield a seam that no
+ * caller can use without ALSO duplicating the per-script message — i.e. it
+ * would reproduce the exact dead-but-tested speculative-seam smell that #589
+ * MED-1 removed (the old `onUnknown:'ignore'` option). The mutex stays
+ * per-script by design.
+ *
+ * Usage:
+ *   import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+ *
+ *   let values;
+ *   try {
+ *     ({ values } = parseColumnFlags({
+ *       argv: process.argv.slice(2),
+ *       knownBool: { 'dry-run': false, apply: false, json: false, help: { short: 'h', default: false } },
+ *       knownString: { source: null, repos: null },
+ *     }));
+ *   } catch (err) {
+ *     if (err instanceof CliFlagError) {
+ *       process.stderr.write(`${SCRIPT_NAME}: ${err.message}\n`);
+ *       process.exit(1);
+ *     }
+ *     throw err;
+ *   }
+ *
+ * Design note — why throw instead of exit:
+ *   The migration scripts run their parsing at module top-level (entry-point
+ *   style — `main()` runs on import), so we cannot make the parser call
+ *   `process.exit()` directly without making it untestable. Instead the parser
+ *   throws a typed `CliFlagError` on a parse failure (unknown flag, missing
+ *   value, etc.); each script catches it and maps to its own exit code (always
+ *   1 — argument error — per `.claude/rules/cli-design.md`). Tests assert on the
+ *   thrown error, which is the behaviour-equivalent of "exit 1 on unknown flag".
+ */
+
+import { parseArgs } from 'node:util';
+
+/**
+ * Typed error thrown by parseColumnFlags on any parse failure.
+ * Callers catch this and map to exit code 1 (argument error).
+ */
+export class CliFlagError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliFlagError';
+  }
+}
+
+/**
+ * Normalise a known-flag descriptor into a `node:util` parseArgs option entry.
+ *
+ * Accepts two shapes per flag:
+ *   - a bare default value (`false`, `null`, `[]`, …) → `{ default }`
+ *   - an object `{ short?, default?, multiple? }` → passed through
+ *
+ * @param {'boolean'|'string'} type
+ * @param {*} descriptor
+ * @returns {{type:string, short?:string, multiple?:boolean, default?:*}}
+ */
+function toParseArgsOption(type, descriptor) {
+  const opt = { type };
+  if (descriptor !== null && typeof descriptor === 'object' && !Array.isArray(descriptor)) {
+    if (typeof descriptor.short === 'string') opt.short = descriptor.short;
+    if (descriptor.multiple === true) opt.multiple = true;
+    if ('default' in descriptor) opt.default = descriptor.default;
+  } else if (descriptor !== undefined && descriptor !== null) {
+    // Bare default value (false, [], a string). `null` is treated as
+    // "no default" so a missing string flag reads back as undefined — callers
+    // apply their own `?? fallback` post-parse (e.g. vault-mirror required-flag
+    // checks rely on undefined, not "").
+    opt.default = descriptor;
+  } else if (Array.isArray(descriptor)) {
+    opt.default = descriptor;
+  }
+  return opt;
+}
+
+/**
+ * Parse column-style CLI flags via node:util parseArgs in strict mode.
+ *
+ * @param {object} spec
+ * @param {string[]} [spec.argv]                Token array (default: process.argv.slice(2)).
+ * @param {Object<string, *>} [spec.knownBool]  Boolean flags. Value = bare default OR { short, default }.
+ * @param {Object<string, *>} [spec.knownString] String flags. Value = bare default (string|null) OR { short, default, multiple }.
+ * @param {Object<string, *>} [spec.defaults]   Optional explicit default overrides, merged onto values AFTER parse
+ *                                               (only applied where parseArgs left the key undefined).
+ * @returns {{ values: object, positionals: string[] }}
+ * @throws {CliFlagError} on any parse failure (unknown flag, missing string value, …).
+ */
+export function parseColumnFlags({
+  argv = process.argv.slice(2),
+  knownBool = {},
+  knownString = {},
+  defaults = {},
+} = {}) {
+  const options = {};
+  for (const [name, descriptor] of Object.entries(knownBool)) {
+    options[name] = toParseArgsOption('boolean', descriptor);
+  }
+  for (const [name, descriptor] of Object.entries(knownString)) {
+    options[name] = toParseArgsOption('string', descriptor);
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options,
+      allowPositionals: false,
+      // strict=true rejects unknown flags AND missing values for string flags.
+      strict: true,
+    });
+  } catch (err) {
+    // Re-wrap node:util's ERR_PARSE_ARGS_* errors as our typed CliFlagError so
+    // callers have a single catch target regardless of the underlying cause.
+    throw new CliFlagError(err.message);
+  }
+
+  // Strict parseArgs only returns declared keys (unknown flags throw above), so
+  // parsed.values already contains exactly the declared set — copy it directly.
+  const values = { ...parsed.values };
+
+  // Apply explicit post-parse defaults only where parseArgs left the key
+  // undefined (a string flag with no `default` reads back undefined). This lets
+  // callers express "default to X" without baking X into the parseArgs option
+  // when they need to distinguish "flag absent" during the parse.
+  for (const [name, value] of Object.entries(defaults)) {
+    if (values[name] === undefined) values[name] = value;
+  }
+
+  return { values, positionals: parsed.positionals ?? [] };
+}