chainlesschain 0.162.39 → 0.162.40

package/src/lib/project-instructions.js

@@ -0,0 +1,275 @@
+/**
+ * Project-memory loader — file-based project instructions for `cc agent`
+ * (Claude-Code CLAUDE.md-hierarchy parity, with our own file name).
+ *
+ * The primary instruction file is **`cc.md`** (ChainlessChain branding);
+ * `CLAUDE.md` and `AGENTS.md` are accepted as compatibility fallbacks so any
+ * repo that already carries Claude-Code/agent memory works with zero setup.
+ *
+ * Discovery order (first existing name wins per location):
+ *
+ *   1. user scope   : `~/.chainlesschain/cc.md`, else `~/.claude/CLAUDE.md`
+ *   2. project scope: per directory from <git-root> down to <cwd> —
+ *                     `cc.md` → `CLAUDE.md` → `AGENTS.md`
+ *                     (root-first, so deeper files refine shallower ones)
+ *   3. local scope  : `cc.local.md` → `CLAUDE.local.md` next to each project
+ *                     file (gitignored personal notes)
+ *
+ * `@path` import lines inside an instruction file pull in the referenced file
+ * (resolved relative to the importing file; `~/` works too), recursively up to
+ * MAX_IMPORT_DEPTH with cycle protection. Tokens inside fenced code blocks and
+ * tokens that don't resolve to a real file (npm scopes like `@scope/pkg`,
+ * emails) are ignored silently.
+ *
+ * Loading is fail-open: any I/O error yields an empty block — composing the
+ * system prompt must never crash because of a bad memory file. All fs access
+ * goes through an injectable `deps` seam (project `_deps` philosophy) and all
+ * reads are explicit UTF-8 (encoding.md rule).
+ *
+ * Disable globally with `CC_PROJECT_MEMORY=0`, per-call with
+ * `projectMemory: false` on composeSystemPrompt.
+ */
+
+import fsDefault from "fs";
+import pathDefault from "path";
+import osDefault from "os";
+
+export const DEFAULT_MAX_FILE_BYTES = 48 * 1024; // per instruction/import file
+export const DEFAULT_MAX_TOTAL_BYTES = 192 * 1024; // whole block budget
+export const MAX_IMPORT_DEPTH = 5;
+
+/** Per-directory project file names, first match wins. */
+export const PROJECT_FILE_NAMES = ["cc.md", "CLAUDE.md", "AGENTS.md"];
+/** Local (gitignored) companion names, first match wins. */
+export const LOCAL_FILE_NAMES = ["cc.local.md", "CLAUDE.local.md"];
+
+// Same boundary rule as file-ref-expander: `@` at start / after whitespace or
+// an opening bracket-quote, so emails and decorative @ never match.
+const IMPORT_TOKEN_RE = /(^|[\s("'`[{])@([^\s"'`)\]}]+)/g;
+
+function resolveDeps(opts) {
+  return {
+    fs: opts.deps?.fs || fsDefault,
+    path: opts.deps?.path || pathDefault,
+    os: opts.deps?.os || osDefault,
+  };
+}
+
+function isFile(fs, p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** First existing candidate among `names` inside `dir`, or null. */
+function firstExisting(fs, path, dir, names) {
+  for (const name of names) {
+    const p = path.join(dir, name);
+    if (isFile(fs, p)) return p;
+  }
+  return null;
+}
+
+/** Walk up from cwd looking for a `.git` marker; null when not in a repo. */
+export function findProjectRoot(cwd, opts = {}) {
+  const { fs, path } = resolveDeps(opts);
+  let dir = path.resolve(cwd);
+  for (;;) {
+    try {
+      if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    } catch {
+      /* keep walking */
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Ordered instruction-file discovery (user → project root → … → cwd, with the
+ * local companion right after its project file). Only existing files are
+ * returned. Deduped by absolute path (covers cwd == home corner cases).
+ *
+ * @returns {Array<{path:string, scope:"user"|"project"|"local"|"rules"}>}
+ */
+export function findInstructionFiles(opts = {}) {
+  const { fs, path, os } = resolveDeps(opts);
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const home = opts.home || os.homedir() || "";
+
+  const seen = new Set();
+  const out = [];
+  const push = (p, scope) => {
+    if (!p) return;
+    const abs = path.resolve(p);
+    if (seen.has(abs) || !isFile(fs, abs)) return;
+    seen.add(abs);
+    out.push({ path: abs, scope });
+  };
+
+  if (home) {
+    push(
+      firstExisting(fs, path, home, [
+        path.join(".chainlesschain", "cc.md"),
+        path.join(".claude", "CLAUDE.md"),
+      ]),
+      "user",
+    );
+  }
+
+  const root = findProjectRoot(cwd, opts) || cwd;
+  const chain = [];
+  let dir = cwd;
+  for (;;) {
+    chain.unshift(dir);
+    if (dir === root) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const d of chain) {
+    push(firstExisting(fs, path, d, PROJECT_FILE_NAMES), "project");
+    push(firstExisting(fs, path, d, LOCAL_FILE_NAMES), "local");
+    // Template-scaffolded project rules (`cc init -t` writes these) join the
+    // chain too, so scaffold-flow and memory-flow projects both feed the agent.
+    push(path.join(d, ".chainlesschain", "rules.md"), "rules");
+  }
+  return out;
+}
+
+/**
+ * Collect `@path` import tokens from instruction text, skipping fenced code
+ * blocks (``` / ~~~). Line-level scanning is good enough for memory files,
+ * which use imports on their own prose lines.
+ */
+export function collectImportTokens(text) {
+  const found = [];
+  let inFence = false;
+  for (const line of String(text).split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    IMPORT_TOKEN_RE.lastIndex = 0;
+    let m;
+    while ((m = IMPORT_TOKEN_RE.exec(line)) !== null) {
+      if (m[2]) found.push(m[2]);
+    }
+  }
+  return found;
+}
+
+function readCapped(fs, abs, maxFileBytes) {
+  const buf = fs.readFileSync(abs);
+  const truncated = buf.length > maxFileBytes;
+  const content = (truncated ? buf.slice(0, maxFileBytes) : buf).toString(
+    "utf-8",
+  );
+  return { content, bytes: buf.length, truncated };
+}
+
+/**
+ * Load the full instruction set: hierarchy files + recursive imports.
+ *
+ * @param {object} [opts] { cwd, home, deps, maxFileBytes, maxTotalBytes }
+ * @returns {{ files: Array<{path,scope,bytes,truncated,content}>, warnings: string[] }}
+ */
+export function loadProjectInstructions(opts = {}) {
+  const { fs, path, os } = resolveDeps(opts);
+  const home = opts.home || os.homedir() || "";
+  const maxFileBytes = Number.isFinite(opts.maxFileBytes)
+    ? opts.maxFileBytes
+    : DEFAULT_MAX_FILE_BYTES;
+  const maxTotalBytes = Number.isFinite(opts.maxTotalBytes)
+    ? opts.maxTotalBytes
+    : DEFAULT_MAX_TOTAL_BYTES;
+
+  const roots = findInstructionFiles(opts);
+  const visited = new Set(roots.map((r) => r.path));
+  const out = [];
+  const warnings = [];
+  let total = 0;
+
+  // Queue of { abs, scope, depth } — imports inherit "import" scope.
+  const queue = roots.map((r) => ({ abs: r.path, scope: r.scope, depth: 0 }));
+
+  while (queue.length) {
+    const { abs, scope, depth } = queue.shift();
+    if (total >= maxTotalBytes) {
+      warnings.push(
+        `project-memory budget (${maxTotalBytes} bytes) exhausted — remaining files skipped`,
+      );
+      break;
+    }
+    let entry;
+    try {
+      entry = readCapped(fs, abs, maxFileBytes);
+    } catch (err) {
+      warnings.push(`${abs} — cannot read: ${err.message}`);
+      continue;
+    }
+    total += Math.min(entry.bytes, maxFileBytes);
+    out.push({ path: abs, scope, ...entry });
+
+    if (depth >= MAX_IMPORT_DEPTH) continue;
+    const baseDir = path.dirname(abs);
+    for (const raw of collectImportTokens(entry.content)) {
+      let target = raw;
+      if (target.startsWith("~/") || target === "~") {
+        if (!home) continue;
+        target = path.join(home, target.slice(1));
+      }
+      const resolved = path.resolve(baseDir, target);
+      if (visited.has(resolved) || !isFile(fs, resolved)) continue; // silent:
+      // non-files are decorative @tokens (npm scopes, emails), not imports.
+      visited.add(resolved);
+      queue.push({ abs: resolved, scope: "import", depth: depth + 1 });
+    }
+  }
+  return { files: out, warnings };
+}
+
+function escapeAttr(s) {
+  return String(s).replace(/"/g, "&quot;");
+}
+
+/** Render loaded instructions as a single system-prompt block ("" if none). */
+export function renderProjectInstructionsBlock(loaded) {
+  const files = loaded?.files || [];
+  if (!files.length) return "";
+  const parts = [
+    '<project-instructions note="project memory auto-loaded from cc.md / CLAUDE.md / AGENTS.md; follow these as authoritative project conventions">',
+  ];
+  for (const f of files) {
+    const attrs =
+      `path="${escapeAttr(f.path)}" scope="${f.scope}"` +
+      (f.truncated ? ` truncated="true" total-bytes="${f.bytes}"` : "");
+    parts.push(`<file ${attrs}>`);
+    parts.push(f.content.trimEnd());
+    if (f.truncated) {
+      parts.push(`… [truncated — file is ${f.bytes} bytes]`);
+    }
+    parts.push(`</file>`);
+  }
+  parts.push("</project-instructions>");
+  return parts.join("\n");
+}
+
+/**
+ * One-call convenience for composeSystemPrompt: returns the rendered block or
+ * "" — and never throws (fail-open by design).
+ */
+export function loadProjectInstructionsBlock(opts = {}) {
+  try {
+    const loaded = loadProjectInstructions(opts);
+    return renderProjectInstructionsBlock(loaded);
+  } catch {
+    return "";
+  }
+}
+
+export const _deps = { fs: fsDefault, path: pathDefault, os: osDefault };

package/src/lib/project-inventory.js

@@ -0,0 +1,355 @@
+/**
+ * Project inventory — offline resource census for `cc init --memory`.
+ *
+ * Scans the target folder (bounded walk: depth/entry caps, heavy dirs
+ * skipped) and produces a deterministic snapshot of what is already there:
+ * languages by extension, package manager, npm scripts, workspaces/monorepo
+ * layout, notable tool configs (TS/bundlers/docker/CI/lint), test runners and
+ * a README summary. `renderMemoryFile` turns that snapshot into a starter
+ * `cc.md` project-memory file (the file `cc agent` auto-loads — see
+ * project-instructions.js). No LLM, no network: the census is pure I/O and
+ * unit-testable via the `deps` seam; reads are explicit UTF-8 (encoding.md).
+ */
+
+import fsDefault from "fs";
+import pathDefault from "path";
+
+export const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".nuxt",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "target",
+  ".gradle",
+  ".idea",
+  ".vscode",
+  "Pods",
+  "DerivedData",
+]);
+
+export const DEFAULT_MAX_DEPTH = 4;
+export const DEFAULT_MAX_ENTRIES = 20000;
+
+const EXT_LANG = {
+  ".js": "JavaScript",
+  ".cjs": "JavaScript",
+  ".mjs": "JavaScript",
+  ".ts": "TypeScript",
+  ".tsx": "TypeScript",
+  ".jsx": "JavaScript",
+  ".vue": "Vue",
+  ".py": "Python",
+  ".java": "Java",
+  ".kt": "Kotlin",
+  ".kts": "Kotlin",
+  ".swift": "Swift",
+  ".go": "Go",
+  ".rs": "Rust",
+  ".rb": "Ruby",
+  ".php": "PHP",
+  ".cs": "C#",
+  ".c": "C",
+  ".h": "C/C++ header",
+  ".cpp": "C++",
+  ".cc": "C++",
+  ".m": "Objective-C",
+  ".sql": "SQL",
+  ".sh": "Shell",
+  ".ps1": "PowerShell",
+  ".md": "Markdown",
+};
+
+const CONFIG_MARKERS = [
+  ["tsconfig.json", "TypeScript"],
+  ["vite.config.js", "Vite"],
+  ["vite.config.ts", "Vite"],
+  ["webpack.config.js", "Webpack"],
+  ["rollup.config.js", "Rollup"],
+  ["next.config.js", "Next.js"],
+  ["nuxt.config.ts", "Nuxt"],
+  ["docker-compose.yml", "Docker Compose"],
+  ["docker-compose.yaml", "Docker Compose"],
+  ["Dockerfile", "Docker"],
+  ["pom.xml", "Maven"],
+  ["build.gradle", "Gradle"],
+  ["build.gradle.kts", "Gradle (Kotlin DSL)"],
+  ["settings.gradle.kts", "Gradle (Kotlin DSL)"],
+  ["Cargo.toml", "Cargo / Rust"],
+  ["go.mod", "Go modules"],
+  ["pyproject.toml", "Python (pyproject)"],
+  ["requirements.txt", "Python (requirements)"],
+  ["pubspec.yaml", "Flutter/Dart"],
+  [".eslintrc.json", "ESLint"],
+  ["eslint.config.js", "ESLint"],
+  [".prettierrc", "Prettier"],
+  ["vitest.config.js", "Vitest"],
+  ["vitest.config.ts", "Vitest"],
+  ["jest.config.js", "Jest"],
+  ["playwright.config.ts", "Playwright"],
+  ["electron-builder.yml", "electron-builder"],
+];
+
+const LOCKFILE_PM = [
+  ["package-lock.json", "npm"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lockb", "bun"],
+];
+
+function resolveDeps(opts) {
+  return {
+    fs: opts.deps?.fs || fsDefault,
+    path: opts.deps?.path || pathDefault,
+  };
+}
+
+function readJson(fs, p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function readText(fs, p) {
+  try {
+    return fs.readFileSync(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** First markdown paragraph after the title — a cheap README synopsis. */
+export function readmeSynopsis(text, maxChars = 400) {
+  if (!text) return null;
+  const lines = String(text).split(/\r?\n/);
+  const out = [];
+  let started = false;
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) {
+      if (started) break;
+      continue;
+    }
+    if (/^#/.test(t) || /^!\[/.test(t) || /^<.*>$/.test(t) || /^\[!\[/.test(t))
+      continue; // headings / badges / bare HTML
+    out.push(t);
+    started = true;
+  }
+  const para = out.join(" ").trim();
+  if (!para) return null;
+  return para.length > maxChars ? `${para.slice(0, maxChars)}…` : para;
+}
+
+/**
+ * Walk the tree (bounded) counting files per language and remembering
+ * top-level directories with file counts.
+ */
+function census(root, { fs, path, maxDepth, maxEntries }) {
+  const languages = new Map(); // lang -> count
+  const topDirs = new Map(); // top-level dir -> file count
+  let entries = 0;
+  let truncated = false;
+
+  const walk = (dir, depth, top) => {
+    if (entries >= maxEntries) {
+      truncated = true;
+      return;
+    }
+    let list;
+    try {
+      list = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of list) {
+      if (entries >= maxEntries) {
+        truncated = true;
+        return;
+      }
+      entries += 1;
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+        if (depth < maxDepth) {
+          walk(path.join(dir, e.name), depth + 1, top || e.name);
+        }
+      } else if (e.isFile()) {
+        if (top) topDirs.set(top, (topDirs.get(top) || 0) + 1);
+        const ext = path.extname(e.name).toLowerCase();
+        const lang = EXT_LANG[ext];
+        if (lang) languages.set(lang, (languages.get(lang) || 0) + 1);
+      }
+    }
+  };
+  walk(root, 0, null);
+  return { languages, topDirs, truncated };
+}
+
+/**
+ * Inventory the folder. Pure data out — rendering is separate.
+ *
+ * @param {string} cwd
+ * @param {object} [opts] { deps, maxDepth, maxEntries }
+ */
+export function inventoryProject(cwd, opts = {}) {
+  const { fs, path } = resolveDeps(opts);
+  const root = path.resolve(cwd);
+  const maxDepth = Number.isFinite(opts.maxDepth)
+    ? opts.maxDepth
+    : DEFAULT_MAX_DEPTH;
+  const maxEntries = Number.isFinite(opts.maxEntries)
+    ? opts.maxEntries
+    : DEFAULT_MAX_ENTRIES;
+
+  const pkg = readJson(fs, path.join(root, "package.json"));
+
+  let packageManager = null;
+  for (const [lock, pm] of LOCKFILE_PM) {
+    if (fs.existsSync(path.join(root, lock))) {
+      packageManager = pm;
+      break;
+    }
+  }
+
+  const configs = [];
+  for (const [file, label] of CONFIG_MARKERS) {
+    if (fs.existsSync(path.join(root, file)) && !configs.includes(label)) {
+      configs.push(label);
+    }
+  }
+
+  let ciWorkflows = 0;
+  try {
+    ciWorkflows = fs
+      .readdirSync(path.join(root, ".github", "workflows"))
+      .filter((f) => /\.ya?ml$/.test(f)).length;
+  } catch {
+    /* no CI dir */
+  }
+
+  const readme =
+    readText(fs, path.join(root, "README.md")) ||
+    readText(fs, path.join(root, "readme.md"));
+
+  const { languages, topDirs, truncated } = census(root, {
+    fs,
+    path,
+    maxDepth,
+    maxEntries,
+  });
+
+  const workspaces = Array.isArray(pkg?.workspaces)
+    ? pkg.workspaces
+    : Array.isArray(pkg?.workspaces?.packages)
+      ? pkg.workspaces.packages
+      : [];
+
+  const scripts = pkg?.scripts ? Object.entries(pkg.scripts) : [];
+
+  const existingMemory = ["cc.md", "CLAUDE.md", "AGENTS.md"].filter((f) =>
+    fs.existsSync(path.join(root, f)),
+  );
+
+  return {
+    root,
+    name: pkg?.name || path.basename(root),
+    description: pkg?.description || null,
+    synopsis: readmeSynopsis(readme),
+    packageManager,
+    configs,
+    ciWorkflows,
+    workspaces,
+    scripts,
+    languages: [...languages.entries()].sort((a, b) => b[1] - a[1]),
+    topDirs: [...topDirs.entries()].sort((a, b) => b[1] - a[1]),
+    truncated,
+    existingMemory,
+  };
+}
+
+/** Render the inventory as a starter cc.md project-memory file. */
+export function renderMemoryFile(inv, opts = {}) {
+  const today = opts.date || new Date().toISOString().slice(0, 10);
+  const L = [];
+  L.push(`# ${inv.name} — Project Memory`);
+  L.push("");
+  L.push(
+    `> Generated by \`cc init --memory\` on ${today} from an inventory of this folder.`,
+  );
+  L.push(
+    "> `cc agent` auto-loads this file as authoritative project context — edit freely.",
+  );
+  L.push("");
+
+  // cc.md outranks CLAUDE.md/AGENTS.md in discovery — import any existing
+  // memory file so generating cc.md never shadows hand-maintained content.
+  const existing = (inv.existingMemory || []).filter((f) => f !== "cc.md");
+  if (existing.length) {
+    L.push("## Existing project memory (imported)");
+    L.push("");
+    for (const f of existing) L.push(`@${f}`);
+    L.push("");
+  }
+
+  if (inv.synopsis || inv.description) {
+    L.push("## Overview");
+    L.push("");
+    L.push(inv.synopsis || inv.description);
+    L.push("");
+  }
+
+  L.push("## Stack");
+  L.push("");
+  if (inv.languages.length) {
+    const langs = inv.languages
+      .slice(0, 8)
+      .map(([lang, n]) => `${lang} (${n})`)
+      .join(", ");
+    L.push(`- Languages by file count: ${langs}${inv.truncated ? " — scan truncated" : ""}`);
+  }
+  if (inv.packageManager) L.push(`- Package manager: ${inv.packageManager}`);
+  if (inv.configs.length) L.push(`- Tooling: ${inv.configs.join(", ")}`);
+  if (inv.ciWorkflows)
+    L.push(`- CI: GitHub Actions (${inv.ciWorkflows} workflows)`);
+  L.push("");
+
+  if (inv.scripts.length) {
+    L.push("## Commands");
+    L.push("");
+    const pm = inv.packageManager || "npm";
+    for (const [name, cmd] of inv.scripts.slice(0, 12)) {
+      L.push(`- \`${pm} run ${name}\` — \`${cmd}\``);
+    }
+    if (inv.scripts.length > 12) {
+      L.push(`- … ${inv.scripts.length - 12} more scripts in package.json`);
+    }
+    L.push("");
+  }
+
+  if (inv.workspaces.length || inv.topDirs.length) {
+    L.push("## Layout");
+    L.push("");
+    if (inv.workspaces.length) {
+      L.push(`- Workspaces: ${inv.workspaces.join(", ")}`);
+    }
+    for (const [dir, n] of inv.topDirs.slice(0, 10)) {
+      L.push(`- \`${dir}/\` — ${n} files`);
+    }
+    L.push("");
+  }
+
+  L.push("## Conventions");
+  L.push("");
+  L.push("- (add project rules here — code style, commit format, test policy)");
+  L.push("");
+  return L.join("\n");
+}
+
+export const _deps = { fs: fsDefault, path: pathDefault };