claudeos-core 2.1.1 → 2.3.0

package/bin/lib/cli-utils.js

@@ -1,206 +1,206 @@
-/**
- * ClaudeOS-Core — CLI Utilities
- *
- * Shared constants, execution helpers, and filesystem utilities for the CLI.
- */
-
-const { execSync, spawn } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-const { ensureDir, existsSafe } = require("../../lib/safe-fs");
-
-// ─── Path configuration ──────────────────────────────────────────
-const TOOLS_DIR = path.resolve(__dirname, "../..");
-const PROJECT_ROOT = process.cwd();
-const GENERATED_DIR = path.join(PROJECT_ROOT, "claudeos-core/generated");
-
-// ─── Language configuration ──────────────────────────────────────
-// Single source of truth: lib/language-config.js. We re-export under the
-// historical name SUPPORTED_LANGS so existing imports keep working.
-const { LANGUAGES: SUPPORTED_LANGS, LANG_CODES, isValidLang } = require("../../lib/language-config");
-
-// ─── Output ─────────────────────────────────────────────────────
-function log(msg) {
-  console.log(msg);
-}
-
-function header(title) {
-  log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  log(title);
-  log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-}
-
-// ─── Execution ──────────────────────────────────────────────────
-function run(cmd, options = {}) {
-  try {
-    execSync(cmd, {
-      cwd: options.cwd || PROJECT_ROOT,
-      stdio: options.silent ? ["pipe", "pipe", "pipe"] : "inherit",
-      encoding: "utf-8",
-      timeout: options.timeout || 0,
-    });
-    return true;
-  } catch (e) {
-    if (options.ignoreError) return false;
-    throw e;
-  }
-}
-
-// Run claude -p: pass prompt via stdin (no shell pipe — avoids command injection)
-function runClaudePrompt(prompt, options = {}) {
-  try {
-    execSync("claude -p --dangerously-skip-permissions", {
-      input: prompt,
-      cwd: options.cwd || PROJECT_ROOT,
-      stdio: ["pipe", "inherit", "inherit"],
-      encoding: "utf-8",
-      timeout: 0,
-    });
-    return true;
-  } catch (e) {
-    if (options.ignoreError) return false;
-    throw e;
-  }
-}
-
-// Async variant of runClaudePrompt using spawn — does NOT block the event loop,
-// so the caller can run setInterval-based progress callbacks concurrently.
-// Resolves to true on exit code 0, false otherwise (no throw; mirrors ignoreError:true).
-// onTick is invoked every tickMs while claude is running; stopped on close.
-// shell:true on Windows so that `claude.cmd`/`claude.ps1` shims resolve via PATH.
-function runClaudePromptAsync(prompt, options = {}) {
-  return new Promise((resolve) => {
-    let child = null;
-    let tickTimer = null;
-    const cleanup = () => { if (tickTimer) { clearInterval(tickTimer); tickTimer = null; } };
-    const bail = () => {
-      cleanup();
-      // Best-effort kill so we don't leave orphaned claude processes when we
-      // fail to hand off the prompt or encounter an unexpected spawn error.
-      if (child && !child.killed) { try { child.kill(); } catch (_e) { /* ignore */ } }
-      resolve(false);
-    };
-    try {
-      // Node 18+ emits DEP0190 when mixing shell:true with an args array (the
-      // args aren't escaped — just concatenated). On Windows we need shell:true
-      // so `claude.cmd`/`claude.ps1` shims resolve via PATH, so we build the
-      // whole command as a single string there and pass an empty args array.
-      // The flags are hardcoded literals (no user input) so there's no
-      // injection surface either way; this just silences the warning.
-      const isWin = process.platform === "win32";
-      const spawnCmd = isWin ? "claude -p --dangerously-skip-permissions" : "claude";
-      const spawnArgs = isWin ? [] : ["-p", "--dangerously-skip-permissions"];
-      child = spawn(spawnCmd, spawnArgs, {
-        cwd: options.cwd || PROJECT_ROOT,
-        stdio: ["pipe", "inherit", "inherit"],
-        shell: isWin,
-      });
-      if (typeof options.onTick === "function" && options.tickMs > 0) {
-        // Fire once immediately so the user sees the progress line right away,
-        // instead of waiting a full tick interval for any feedback.
-        try { options.onTick(); } catch (_e) { /* swallow */ }
-        tickTimer = setInterval(() => {
-          try { options.onTick(); } catch (_e) { /* swallow — progress is best-effort */ }
-        }, options.tickMs);
-      }
-      child.on("close", (code) => { cleanup(); resolve(code === 0); });
-      child.on("error", () => { cleanup(); resolve(false); });
-      child.stdin.on("error", () => { bail(); });
-      child.stdin.write(prompt);
-      child.stdin.end();
-    } catch (_e) {
-      // Catches synchronous throws from spawn (e.g. ENAMETOOLONG on some
-      // platforms) or from the initial stdin.write before listeners were
-      // attached. Either way: no orphan child, no leaked interval.
-      bail();
-    }
-  });
-}
-
-// Run claude -p but CAPTURE stdout instead of inheriting it.
-// Returns the captured stdout string on success, or null on failure.
-// Used for short tasks where we need the response content (e.g. translation).
-// maxBuffer default is 10MB — enough for document translation.
-function runClaudeCapture(prompt, options = {}) {
-  try {
-    const out = execSync("claude -p --dangerously-skip-permissions", {
-      input: prompt,
-      cwd: options.cwd || PROJECT_ROOT,
-      stdio: ["pipe", "pipe", "pipe"],
-      encoding: "utf-8",
-      timeout: options.timeout || 0,
-      maxBuffer: options.maxBuffer || 10 * 1024 * 1024,
-    });
-    return out;
-  } catch (_e) {
-    return null;
-  }
-}
-
-// ─── Filesystem ─────────────────────────────────────────────────
-// ensureDir: delegated to lib/safe-fs.js (single source of truth)
-// fileExists: alias for existsSafe from lib/safe-fs.js
-const fileExists = existsSafe;
-
-// readFile: intentionally throws on error (CLI needs hard failure, unlike safe-fs fallback)
-function readFile(p) {
-  return fs.readFileSync(p, "utf-8");
-}
-
-function injectProjectRoot(text) {
-  // Normalize to forward slashes for prompts (Claude interprets backslashes as escapes)
-  const normalizedRoot = PROJECT_ROOT.replace(/\\/g, "/");
-  // Use a replacement function so that `$`, `$1`, `$&`, `$$` in the
-  // project path (rare but possible on some systems) are preserved as
-  // literal characters rather than interpreted as regex specials.
-  return text.replace(/\{\{PROJECT_ROOT\}\}/g, () => normalizedRoot);
-}
-
-// ─── Helpers ────────────────────────────────────────────────────
-function pad(str, len) {
-  return str.length >= len ? str : str + " ".repeat(len - str.length);
-}
-
-function countFiles() {
-  try {
-    let count = 0;
-    const skipDirs = ["node_modules", "generated"];
-    const visited = new Set();
-    const scan = (dir) => {
-      if (!fs.existsSync(dir)) return;
-      let realDir;
-      try { realDir = fs.realpathSync(dir); } catch (_e) { realDir = dir; }
-      if (visited.has(realDir)) return;
-      visited.add(realDir);
-      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        if (skipDirs.includes(entry.name)) continue;
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) scan(full);
-        else count++;
-      }
-    };
-    scan(path.join(PROJECT_ROOT, ".claude"));
-    scan(path.join(PROJECT_ROOT, "claudeos-core"));
-    return count;
-  } catch (e) {
-    return "?";
-  }
-}
-
-function countPass1Files() {
-  try {
-    return fs
-      .readdirSync(GENERATED_DIR)
-      .filter((f) => f.startsWith("pass1-") && f.endsWith(".json")).length;
-  } catch (e) {
-    return 0;
-  }
-}
-
-module.exports = {
-  TOOLS_DIR, PROJECT_ROOT, GENERATED_DIR,
-  SUPPORTED_LANGS, LANG_CODES, isValidLang,
-  log, header, run, runClaudePrompt, runClaudePromptAsync, runClaudeCapture,
-  ensureDir, fileExists, readFile, injectProjectRoot,
-  pad, countFiles, countPass1Files,
-};
+/**
+ * ClaudeOS-Core — CLI Utilities
+ *
+ * Shared constants, execution helpers, and filesystem utilities for the CLI.
+ */
+
+const { execSync, spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const { ensureDir, existsSafe } = require("../../lib/safe-fs");
+
+// ─── Path configuration ──────────────────────────────────────────
+const TOOLS_DIR = path.resolve(__dirname, "../..");
+const PROJECT_ROOT = process.cwd();
+const GENERATED_DIR = path.join(PROJECT_ROOT, "claudeos-core/generated");
+
+// ─── Language configuration ──────────────────────────────────────
+// Single source of truth: lib/language-config.js. We re-export under the
+// historical name SUPPORTED_LANGS so existing imports keep working.
+const { LANGUAGES: SUPPORTED_LANGS, LANG_CODES, isValidLang } = require("../../lib/language-config");
+
+// ─── Output ─────────────────────────────────────────────────────
+function log(msg) {
+  console.log(msg);
+}
+
+function header(title) {
+  log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  log(title);
+  log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+}
+
+// ─── Execution ──────────────────────────────────────────────────
+function run(cmd, options = {}) {
+  try {
+    execSync(cmd, {
+      cwd: options.cwd || PROJECT_ROOT,
+      stdio: options.silent ? ["pipe", "pipe", "pipe"] : "inherit",
+      encoding: "utf-8",
+      timeout: options.timeout || 0,
+    });
+    return true;
+  } catch (e) {
+    if (options.ignoreError) return false;
+    throw e;
+  }
+}
+
+// Run claude -p: pass prompt via stdin (no shell pipe — avoids command injection)
+function runClaudePrompt(prompt, options = {}) {
+  try {
+    execSync("claude -p --dangerously-skip-permissions", {
+      input: prompt,
+      cwd: options.cwd || PROJECT_ROOT,
+      stdio: ["pipe", "inherit", "inherit"],
+      encoding: "utf-8",
+      timeout: 0,
+    });
+    return true;
+  } catch (e) {
+    if (options.ignoreError) return false;
+    throw e;
+  }
+}
+
+// Async variant of runClaudePrompt using spawn — does NOT block the event loop,
+// so the caller can run setInterval-based progress callbacks concurrently.
+// Resolves to true on exit code 0, false otherwise (no throw; mirrors ignoreError:true).
+// onTick is invoked every tickMs while claude is running; stopped on close.
+// shell:true on Windows so that `claude.cmd`/`claude.ps1` shims resolve via PATH.
+function runClaudePromptAsync(prompt, options = {}) {
+  return new Promise((resolve) => {
+    let child = null;
+    let tickTimer = null;
+    const cleanup = () => { if (tickTimer) { clearInterval(tickTimer); tickTimer = null; } };
+    const bail = () => {
+      cleanup();
+      // Best-effort kill so we don't leave orphaned claude processes when we
+      // fail to hand off the prompt or encounter an unexpected spawn error.
+      if (child && !child.killed) { try { child.kill(); } catch (_e) { /* ignore */ } }
+      resolve(false);
+    };
+    try {
+      // Node 18+ emits DEP0190 when mixing shell:true with an args array (the
+      // args aren't escaped — just concatenated). On Windows we need shell:true
+      // so `claude.cmd`/`claude.ps1` shims resolve via PATH, so we build the
+      // whole command as a single string there and pass an empty args array.
+      // The flags are hardcoded literals (no user input) so there's no
+      // injection surface either way; this just silences the warning.
+      const isWin = process.platform === "win32";
+      const spawnCmd = isWin ? "claude -p --dangerously-skip-permissions" : "claude";
+      const spawnArgs = isWin ? [] : ["-p", "--dangerously-skip-permissions"];
+      child = spawn(spawnCmd, spawnArgs, {
+        cwd: options.cwd || PROJECT_ROOT,
+        stdio: ["pipe", "inherit", "inherit"],
+        shell: isWin,
+      });
+      if (typeof options.onTick === "function" && options.tickMs > 0) {
+        // Fire once immediately so the user sees the progress line right away,
+        // instead of waiting a full tick interval for any feedback.
+        try { options.onTick(); } catch (_e) { /* swallow */ }
+        tickTimer = setInterval(() => {
+          try { options.onTick(); } catch (_e) { /* swallow — progress is best-effort */ }
+        }, options.tickMs);
+      }
+      child.on("close", (code) => { cleanup(); resolve(code === 0); });
+      child.on("error", () => { cleanup(); resolve(false); });
+      child.stdin.on("error", () => { bail(); });
+      child.stdin.write(prompt);
+      child.stdin.end();
+    } catch (_e) {
+      // Catches synchronous throws from spawn (e.g. ENAMETOOLONG on some
+      // platforms) or from the initial stdin.write before listeners were
+      // attached. Either way: no orphan child, no leaked interval.
+      bail();
+    }
+  });
+}
+
+// Run claude -p but CAPTURE stdout instead of inheriting it.
+// Returns the captured stdout string on success, or null on failure.
+// Used for short tasks where we need the response content (e.g. translation).
+// maxBuffer default is 10MB — enough for document translation.
+function runClaudeCapture(prompt, options = {}) {
+  try {
+    const out = execSync("claude -p --dangerously-skip-permissions", {
+      input: prompt,
+      cwd: options.cwd || PROJECT_ROOT,
+      stdio: ["pipe", "pipe", "pipe"],
+      encoding: "utf-8",
+      timeout: options.timeout || 0,
+      maxBuffer: options.maxBuffer || 10 * 1024 * 1024,
+    });
+    return out;
+  } catch (_e) {
+    return null;
+  }
+}
+
+// ─── Filesystem ─────────────────────────────────────────────────
+// ensureDir: delegated to lib/safe-fs.js (single source of truth)
+// fileExists: alias for existsSafe from lib/safe-fs.js
+const fileExists = existsSafe;
+
+// readFile: intentionally throws on error (CLI needs hard failure, unlike safe-fs fallback)
+function readFile(p) {
+  return fs.readFileSync(p, "utf-8");
+}
+
+function injectProjectRoot(text) {
+  // Normalize to forward slashes for prompts (Claude interprets backslashes as escapes)
+  const normalizedRoot = PROJECT_ROOT.replace(/\\/g, "/");
+  // Use a replacement function so that `$`, `$1`, `$&`, `$$` in the
+  // project path (rare but possible on some systems) are preserved as
+  // literal characters rather than interpreted as regex specials.
+  return text.replace(/\{\{PROJECT_ROOT\}\}/g, () => normalizedRoot);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────
+function pad(str, len) {
+  return str.length >= len ? str : str + " ".repeat(len - str.length);
+}
+
+function countFiles() {
+  try {
+    let count = 0;
+    const skipDirs = ["node_modules", "generated"];
+    const visited = new Set();
+    const scan = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      let realDir;
+      try { realDir = fs.realpathSync(dir); } catch (_e) { realDir = dir; }
+      if (visited.has(realDir)) return;
+      visited.add(realDir);
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (skipDirs.includes(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) scan(full);
+        else count++;
+      }
+    };
+    scan(path.join(PROJECT_ROOT, ".claude"));
+    scan(path.join(PROJECT_ROOT, "claudeos-core"));
+    return count;
+  } catch (e) {
+    return "?";
+  }
+}
+
+function countPass1Files() {
+  try {
+    return fs
+      .readdirSync(GENERATED_DIR)
+      .filter((f) => f.startsWith("pass1-") && f.endsWith(".json")).length;
+  } catch (e) {
+    return 0;
+  }
+}
+
+module.exports = {
+  TOOLS_DIR, PROJECT_ROOT, GENERATED_DIR,
+  SUPPORTED_LANGS, LANG_CODES, isValidLang,
+  log, header, run, runClaudePrompt, runClaudePromptAsync, runClaudeCapture,
+  ensureDir, fileExists, readFile, injectProjectRoot,
+  pad, countFiles, countPass1Files,
+};

package/claude-md-validator/index.js

@@ -0,0 +1,184 @@
+/**
+ * claude-md-validator — Post-generation structural validation for CLAUDE.md.
+ *
+ * Runs language-invariant structural checks against a generated CLAUDE.md
+ * to detect the §9 re-declaration anti-pattern and other structural drift
+ * that the scaffold + prompt-level instructions alone cannot reliably
+ * prevent.
+ *
+ * Usage (as a library):
+ *   const { validate } = require("./claude-md-validator");
+ *   const report = validate("/path/to/CLAUDE.md");
+ *   if (!report.valid) { ... }
+ *
+ * Usage (as a CLI):
+ *   node claude-md-validator/index.js /path/to/CLAUDE.md
+ *   node claude-md-validator/index.js          # defaults to ./CLAUDE.md
+ *
+ * Design principle: every check here must pass/fail identically regardless
+ * of the language used to generate CLAUDE.md. See structural-checks.js
+ * for the rationale.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const checks = require("./structural-checks");
+const { formatReport } = require("./reporter");
+
+/**
+ * Validate a CLAUDE.md file.
+ *
+ * @param {string} claudeMdPath - Absolute or relative path to CLAUDE.md
+ * @returns {object} report with { valid, path, checksRun, errors, warnings, summary }
+ */
+function validate(claudeMdPath) {
+  // Guard against non-string inputs (null, undefined, numbers, objects).
+  // path.resolve() throws TypeError on these, which surfaces as a raw
+  // stack trace to CLI users. Returning a structured error keeps the
+  // validator's contract simple: every call returns a report object.
+  if (typeof claudeMdPath !== "string" || claudeMdPath.length === 0) {
+    return {
+      valid: false,
+      path: String(claudeMdPath),
+      checksRun: 0,
+      errors: [
+        {
+          id: "INVALID_PATH",
+          pass: false,
+          severity: "error",
+          message: `Path must be a non-empty string, got ${typeof claudeMdPath}: ${JSON.stringify(claudeMdPath)}`,
+          remediation: "Pass a filesystem path to a CLAUDE.md file.",
+        },
+      ],
+      warnings: [],
+      summary: "❌ Invalid path argument.",
+    };
+  }
+
+  const absPath = path.resolve(claudeMdPath);
+
+  if (!fs.existsSync(absPath)) {
+    return {
+      valid: false,
+      path: absPath,
+      checksRun: 0,
+      errors: [
+        {
+          id: "FILE_MISSING",
+          pass: false,
+          severity: "error",
+          message: `File not found: ${absPath}`,
+          remediation:
+            "Run `npx claudeos-core init --force` to generate CLAUDE.md.",
+        },
+      ],
+      warnings: [],
+      summary: "❌ File not found.",
+    };
+  }
+
+  // Guard against the user pointing the validator at a directory or an
+  // unreadable file. Without this guard `readFileSync` throws EISDIR /
+  // EACCES and the CLI exits with a raw stack trace, which looks like
+  // a validator bug to end users.
+  const stat = fs.statSync(absPath);
+  if (!stat.isFile()) {
+    return {
+      valid: false,
+      path: absPath,
+      checksRun: 0,
+      errors: [
+        {
+          id: "NOT_A_FILE",
+          pass: false,
+          severity: "error",
+          message: `Path is not a regular file: ${absPath}`,
+          remediation:
+            "Point the validator at a CLAUDE.md file, not a directory or special file.",
+        },
+      ],
+      warnings: [],
+      summary: "❌ Path is not a file.",
+    };
+  }
+
+  let rawContent;
+  try {
+    rawContent = fs.readFileSync(absPath, "utf8");
+  } catch (e) {
+    return {
+      valid: false,
+      path: absPath,
+      checksRun: 0,
+      errors: [
+        {
+          id: "FILE_UNREADABLE",
+          pass: false,
+          severity: "error",
+          message: `Could not read file: ${e.message || e}`,
+          remediation:
+            "Check file permissions and re-run, or regenerate via `npx claudeos-core init --force`.",
+        },
+      ],
+      warnings: [],
+      summary: "❌ File unreadable.",
+    };
+  }
+  // Strip UTF-8 BOM (U+FEFF) if present at the start of the file.
+  // Some Windows editors and cross-platform generators prepend a BOM to
+  // UTF-8 files; without this, the first `## ` line fails to match
+  // `^## ` regex checks and the section count is silently off by one.
+  const content = rawContent.charCodeAt(0) === 0xfeff ? rawContent.slice(1) : rawContent;
+  const sections = checks.splitByH2(content);
+
+  const results = [];
+
+  // Structural checks (order does not matter; reporter groups them)
+  results.push(checks.checkH2Count(sections));
+  results.push(...checks.checkH3Counts(sections));
+  results.push(...checks.checkH4Counts(sections));
+  results.push(...checks.checkMemoryFileUniqueness(content));
+  results.push(...checks.checkMemoryScopedToSection8(sections, content));
+  results.push(...checks.checkSectionsHaveContent(sections));
+  // Title-invariant check — English canonical token must appear in every
+  // `## N.` heading so that multi-repo grep stays consistent across
+  // projects generated in different output languages.
+  results.push(...checks.checkCanonicalHeadings(sections));
+
+  const errors = results.filter((r) => !r.pass && r.severity === "error");
+  const warnings = results.filter((r) => !r.pass && r.severity === "warning");
+  const valid = errors.length === 0;
+
+  return {
+    valid,
+    path: absPath,
+    checksRun: results.length,
+    errors,
+    warnings,
+    allResults: results,
+    summary: valid
+      ? `✅ ${results.length} structural checks passed` +
+        (warnings.length > 0 ? ` (${warnings.length} warning(s))` : "") +
+        "."
+      : `❌ ${errors.length} error(s), ${warnings.length} warning(s) out of ${results.length} checks.`,
+  };
+}
+
+// ─── CLI entry ────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const target = process.argv[2] || path.join(process.cwd(), "CLAUDE.md");
+  const report = validate(target);
+  console.log(formatReport(report));
+  process.exit(report.valid ? 0 : 1);
+}
+
+module.exports = {
+  validate,
+  // Expose checks for advanced callers / testing
+  checks,
+  formatReport,
+};

package/claude-md-validator/reporter.js

@@ -0,0 +1,66 @@
+/**
+ * reporter.js — Human-readable formatter for validator reports.
+ *
+ * Keeps all user-facing messages in one place so the CLI and the
+ * plan-installer integration produce consistent output.
+ *
+ * No color codes by default — the goal is to work in any terminal
+ * without ANSI dependencies and to be easy to grep in CI logs.
+ */
+
+"use strict";
+
+function formatReport(report) {
+  const lines = [];
+  lines.push("");
+  lines.push(`  🔍 Validating: ${report.path}`);
+  lines.push("");
+  lines.push(`  ${report.summary}`);
+
+  if (report.errors.length > 0) {
+    lines.push("");
+    lines.push("  Errors:");
+    for (const err of report.errors) {
+      lines.push(`    ❌ [${err.id}] ${err.message || "(no message)"}`);
+      if (err.remediation) {
+        lines.push(`       → ${err.remediation}`);
+      }
+    }
+  }
+
+  if (report.warnings.length > 0) {
+    lines.push("");
+    lines.push("  Warnings:");
+    for (const warn of report.warnings) {
+      lines.push(`    ⚠️  [${warn.id}] ${warn.message || "(no message)"}`);
+      if (warn.remediation) {
+        lines.push(`       → ${warn.remediation}`);
+      }
+    }
+  }
+
+  if (!report.valid) {
+    lines.push("");
+    lines.push("  To regenerate CLAUDE.md from scratch:");
+    lines.push("    npx claudeos-core init --force");
+    lines.push("");
+    lines.push("  To inspect the scaffold requirements:");
+    lines.push("    See pass-prompts/templates/common/claude-md-scaffold.md");
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Short one-line summary suitable for inline output during pipeline runs.
+ */
+function formatSummaryLine(report) {
+  if (report.valid) {
+    const warn = report.warnings.length > 0 ? ` (${report.warnings.length} warning(s))` : "";
+    return `✅ CLAUDE.md structure valid (${report.checksRun} checks)${warn}`;
+  }
+  return `⚠️  CLAUDE.md structure: ${report.errors.length} error(s), ${report.warnings.length} warning(s)`;
+}
+
+module.exports = { formatReport, formatSummaryLine };