etymd 0.1.0

package/dist/chunk-WVYKYPKS.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { promises } from 'node:fs';
+import { promisify } from 'node:util';
+import pc from 'picocolors';
+
+var pExecFile = promisify(execFile);
+async function pathExists(p) {
+  try {
+    await promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(p) {
+  try {
+    const raw = await promises.readFile(p, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function readText(p) {
+  try {
+    return await promises.readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function isDirectory(p) {
+  try {
+    return (await promises.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function git(root, args) {
+  try {
+    const { stdout } = await pExecFile("git", args, { cwd: root, timeout: 4e3 });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+function wordCount(text) {
+  const m = text.trim().match(/\S+/g);
+  return m ? m.length : 0;
+}
+function approxTokens(words) {
+  return Math.round(words / 0.75);
+}
+var CI_ENV_VARS = [
+  "CI",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "BUILDKITE",
+  "CIRCLECI",
+  "JENKINS_URL",
+  "TF_BUILD"
+];
+function isCiEnvironment() {
+  return CI_ENV_VARS.some((v) => Boolean(process.env[v]));
+}
+function normalizeRelPath(p) {
+  return p.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        i += 1;
+        if (glob[i + 1] === "/") {
+          i += 1;
+          re += "(?:.*/)?";
+        } else {
+          re += ".*";
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function matchesGlob(p, glob) {
+  const target = normalizeRelPath(p);
+  const pattern = normalizeRelPath(glob);
+  if (!pattern) return false;
+  if (!/[*?]/.test(pattern)) return target === pattern || target.startsWith(pattern + "/");
+  return globToRegExp(pattern).test(target);
+}
+function matchesAnyGlob(p, globs) {
+  return globs.some((g) => matchesGlob(p, g));
+}
+var theme = {
+  brand: (s) => pc.magenta(pc.bold(s)),
+  heading: (s) => pc.bold(s),
+  dim: (s) => pc.dim(s),
+  ok: (s) => pc.green(s),
+  warn: (s) => pc.yellow(s),
+  bad: (s) => pc.red(s),
+  info: (s) => pc.cyan(s),
+  accent: (s) => pc.cyan(s),
+  code: (s) => pc.cyan(s),
+  count: (s) => pc.bold(String(s))
+};
+var glyph = {
+  ok: pc.green("\u25CF"),
+  partial: pc.yellow("\u25D0"),
+  bad: pc.red("\u25CB"),
+  bullet: pc.dim("\xB7"),
+  arrow: pc.dim("\u2192")
+};
+function width(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function pad(s, len) {
+  return s + " ".repeat(Math.max(0, len - width(s)));
+}
+function maxWidth(items) {
+  return items.length ? Math.max(...items.map(width)) : 0;
+}
+function print(line = "") {
+  process.stdout.write(line + "\n");
+}
+function section(title) {
+  print();
+  print(theme.heading(title));
+}
+function keyValues(rows) {
+  const keyWidth = maxWidth(rows.map(([k]) => k));
+  for (const [k, v] of rows) {
+    print(`  ${theme.dim(pad(k, keyWidth))}  ${v}`);
+  }
+}
+function renderFacts(facts) {
+  section(`Reckoning \u2014 ${theme.brand(facts.name)}`);
+  keyValues([
+    ["package manager", theme.info(facts.packageManager)],
+    [
+      "workspace",
+      facts.workspace.kind === "none" ? "single package" : `${theme.info(facts.workspace.kind)}${facts.packages.length ? ` (${facts.packages.length} packages)` : ""}`
+    ],
+    [
+      "frameworks",
+      facts.frameworks.length ? facts.frameworks.map((f) => theme.info(f)).join(theme.dim(", ")) : theme.dim("none detected")
+    ],
+    ["ci", facts.ci.system === "none" ? theme.dim("none") : theme.info(facts.ci.system)],
+    [
+      "git hooks",
+      facts.hooks.source === "none" ? theme.dim("none") : theme.info(facts.hooks.source)
+    ],
+    [
+      "branch",
+      facts.git.branch ? `${facts.git.branch}${facts.git.head ? theme.dim(` @ ${facts.git.head}`) : ""}` : theme.dim("\u2014")
+    ]
+  ]);
+  const cmds = facts.commands;
+  const cmdRows = [];
+  for (const role of [
+    "test",
+    "lint",
+    "typecheck",
+    "format",
+    "formatCheck",
+    "build",
+    "dev"
+  ]) {
+    if (cmds[role]) cmdRows.push([role, theme.code(cmds[role])]);
+  }
+  if (cmdRows.length) {
+    section("Discovered commands (Done =)");
+    keyValues(cmdRows);
+  }
+  const present = facts.artifacts.filter((a) => a.exists);
+  section("Agent artifacts");
+  if (present.length) {
+    for (const a of present) print(`  ${glyph.ok} ${a.label} ${theme.dim(a.path)}`);
+  } else {
+    print(`  ${theme.dim("none \u2014 this is a fresh project for agentic setup")}`);
+  }
+  if (facts.tree.dirs.length) {
+    section("Top-level layout");
+    const nameWidth = maxWidth(facts.tree.dirs.slice(0, 12).map((d) => d.name + "/"));
+    for (const d of facts.tree.dirs.slice(0, 12)) {
+      print(`  ${pad(theme.info(d.name + "/"), nameWidth + 2)} ${theme.dim(`${d.files} files`)}`);
+    }
+    if (facts.tree.truncated) print(`  ${theme.dim("\u2026 counts capped (large repo)")}`);
+  }
+}
+function renderContext(budget, threshold) {
+  section("Context budget (always-loaded footprint)");
+  if (!budget.files.length) {
+    print(`  ${theme.dim("no always-loaded agent files found \u2014 nothing loads every session yet")}`);
+    return;
+  }
+  const pathWidth = maxWidth(budget.files.map((f) => f.path));
+  for (const f of budget.files) {
+    const heavy = f.words >= threshold;
+    const words = heavy ? theme.warn(`${f.words} w`) : `${f.words} w`;
+    print(`  ${pad(theme.info(f.path), pathWidth)}  ${pad(words, 12)} ${theme.dim(f.role)}`);
+  }
+  print();
+  keyValues([
+    [
+      "total",
+      `${theme.count(budget.totalWords)} words ${theme.dim(`(~${budget.totalApproxTokens} tokens)`)} loaded every session`
+    ]
+  ]);
+  if (budget.extractionCandidates.length) {
+    section("Extraction candidates");
+    print(
+      `  ${theme.dim("These load every session but are rarely all needed. Move to an on-demand skill:")}`
+    );
+    for (const f of budget.extractionCandidates) {
+      print(`  ${glyph.arrow} ${theme.info(f.path)} ${theme.dim(`(${f.words} words)`)}`);
+    }
+  } else {
+    print(`  ${glyph.ok} ${theme.dim("lean \u2014 no single file is heavy enough to extract yet")}`);
+  }
+}
+function renderPlan(files) {
+  section("Plan");
+  for (const f of files) {
+    const tag = !f.exists ? theme.ok("create") : f.differs ? theme.warn("differs") : theme.dim("same");
+    print(`  ${pc.dim("[")}${tag}${pc.dim("]")} ${theme.info(f.path)}  ${theme.dim(f.label)}`);
+  }
+}
+var TIER_BADGE = {
+  risk: pc.red(pc.bold("RISK  ")),
+  gap: pc.yellow(pc.bold("GAP   ")),
+  polish: pc.dim(pc.bold("POLISH"))
+};
+function renderFindings(findings) {
+  if (!findings.length) {
+    print(`  ${glyph.ok} ${theme.dim("no findings \u2014 everything examined holds up")}`);
+    return;
+  }
+  for (const f of findings) {
+    print();
+    print(`  ${TIER_BADGE[f.tier]} ${theme.heading(f.claim)}`);
+    print(`         ${theme.dim("evidence")}  ${f.evidence.join(theme.dim(" \xB7 "))}`);
+    print(`         ${theme.dim("why")}       ${f.why}`);
+    if (f.action) print(`         ${theme.dim("action")}    ${f.action}`);
+    print(
+      `         ${theme.dim(`effort ${f.effort} \xB7 confidence ${f.confidence} \xB7 ${f.lens} \xB7 ${theme.dim(f.id)}`)}`
+    );
+  }
+}
+function renderLensCoverage(reports) {
+  section("Lens coverage");
+  const titleWidth = maxWidth(reports.map((r) => r.title));
+  for (const r of reports) {
+    const status = r.status === "skipped" ? theme.bad(`could not run \u2014 ${r.reason ?? "unknown"}`) : r.findings.length ? theme.warn(`${r.findings.length} finding(s)`) : theme.ok("clean");
+    print(
+      `  ${r.status === "skipped" ? glyph.bad : glyph.ok}  ${pad(r.title, titleWidth)}  ${status}`
+    );
+    for (const d of r.disclosures) print(`       ${theme.dim(`\u25E6 ${d}`)}`);
+  }
+}
+function renderLedgerDiff(diff) {
+  const parts = [];
+  if (diff.new.length) parts.push(theme.warn(`${diff.new.length} new`));
+  if (diff.stillOpen.length) parts.push(`${diff.stillOpen.length} still open`);
+  if (diff.regressed.length) parts.push(theme.bad(`${diff.regressed.length} regressed`));
+  if (diff.resolved.length) parts.push(theme.ok(`${diff.resolved.length} resolved`));
+  if (diff.dismissed.length) parts.push(theme.dim(`${diff.dismissed.length} dismissed (hidden)`));
+  if (diff.accepted.length) parts.push(theme.dim(`${diff.accepted.length} accepted (hidden)`));
+  if (diff.outOfScope.length)
+    parts.push(theme.dim(`${diff.outOfScope.length} held (excluded from this audit, not fixed)`));
+  if (parts.length) {
+    print();
+    print(`  ${theme.dim("since last audit:")} ${parts.join(theme.dim(" \xB7 "))}`);
+  }
+}
+var STATUS_ORDER = ["regressed", "open", "accepted", "dismissed", "done"];
+var STATUS_LABEL = {
+  regressed: theme.bad,
+  open: theme.warn,
+  accepted: theme.info,
+  dismissed: theme.dim,
+  done: theme.ok
+};
+function renderBaselineDrift(drift) {
+  section("Changes since the approved baseline");
+  const line = (glyphStr, label, detail) => print(`  ${glyphStr} ${theme.dim(label)} ${detail}`);
+  for (const c of drift.commands) {
+    if (c.from && c.to)
+      line(glyph.arrow, `${c.role} command`, `${theme.code(c.from)} \u2192 ${theme.code(c.to)}`);
+    else if (c.to) line(theme.ok("+"), `${c.role} command`, theme.code(c.to));
+    else if (c.from)
+      line(theme.bad("\u2212"), `${c.role} command`, `${theme.code(c.from)} ${theme.dim("(gone)")}`);
+  }
+  for (const a of drift.artifactsAdded) line(theme.ok("+"), "artifact", a);
+  for (const a of drift.artifactsRemoved)
+    line(theme.bad("\u2212"), "artifact", `${a} ${theme.dim("(gone)")}`);
+  for (const d of drift.dirsAdded) line(theme.ok("+"), "top-level", theme.info(d + "/"));
+  for (const d of drift.dirsRemoved)
+    line(theme.bad("\u2212"), "top-level", `${theme.info(d + "/")} ${theme.dim("(gone)")}`);
+}
+function renderLedger(ledger) {
+  section(`Ledger ${theme.dim(`\xB7 ${ledger.entries.length} tracked finding(s)`)}`);
+  if (!ledger.entries.length) {
+    print(`  ${theme.dim("empty \u2014 run `etymd audit` to record the current findings")}`);
+    return;
+  }
+  const byStatus = /* @__PURE__ */ new Map();
+  for (const e of ledger.entries) {
+    const list = byStatus.get(e.status) ?? [];
+    list.push(e);
+    byStatus.set(e.status, list);
+  }
+  for (const status of STATUS_ORDER) {
+    const entries = byStatus.get(status);
+    if (!entries?.length) continue;
+    print();
+    print(`  ${STATUS_LABEL[status](status)} ${theme.dim(`(${entries.length})`)}`);
+    for (const e of entries) {
+      print(`    ${theme.dim(e.tier)}  ${e.claim}`);
+      print(`         ${theme.dim(e.id)}${e.reason ? theme.dim(` \u2014 \u201C${e.reason}\u201D`) : ""}`);
+    }
+  }
+}
+
+export { approxTokens, git, glyph, isCiEnvironment, isDirectory, matchesAnyGlob, normalizeRelPath, pathExists, print, readJson, readText, renderBaselineDrift, renderContext, renderFacts, renderFindings, renderLedger, renderLedgerDiff, renderLensCoverage, renderPlan, section, theme, wordCount };

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { VERSION } from './chunk-U33XLT5I.js';
+import path from 'node:path';
+import { Command } from 'commander';
+import pc from 'picocolors';
+
+function resolveCwd(cmd) {
+  const opts = cmd.optsWithGlobals();
+  return path.resolve(opts.cwd ?? process.cwd());
+}
+async function action(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`
+${pc.red("\u2716")} ${message}
+`);
+    process.exitCode = 1;
+  }
+}
+var program = new Command();
+program.name("etymd").description(
+  "Keep your agent instructions true \u2014 verify AGENTS.md & friends against the actual repo, on a budget, with drift caught over time."
+).version(VERSION, "-v, --version").option("--cwd <dir>", "run against a different project directory", process.cwd());
+program.command("audit").description("Verify every instruction claim against the repo: ranked findings + ledger diff").option("--json", "print the machine-stable audit result as JSON").option("--truth", "truth lenses only (the doctor subset)").option("--lens <id>", "run a single lens (instruction-truth | gate-integrity | context-economy)").option("--no-ledger", "read-only: do not persist the reconciled ledger").option(
+  "--fail-on <tier>",
+  "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
+).action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./audit-OHOSWOWA.js');
+    await run({
+      cwd: resolveCwd(cmd),
+      json: opts.json,
+      truth: opts.truth,
+      lens: opts.lens,
+      noLedger: !opts.ledger,
+      failOn: opts.failOn
+    });
+  })
+);
+program.command("init").description("Onboard the truth guard: approve the baseline; scaffold AGENTS.md only if missing").option("-y, --yes", "accept defaults without prompting (never overwrites)").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./init-V627UXKU.js');
+    await run({ cwd: resolveCwd(cmd), yes: opts.yes });
+  })
+);
+program.command("approve").description(
+  "Re-approve the committed baseline after intentional structural changes (non-interactive)"
+).action(
+  (_opts, cmd) => action(async () => {
+    const { run } = await import('./approve-WM6OJHQG.js');
+    await run({ cwd: resolveCwd(cmd) });
+  })
+);
+program.command("scan").description("Deterministically reckon the project into a facts index").option("--json", "print the raw facts as JSON").option("--no-save", "do not write the .etymd cache").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./scan-YL7JHLUA.js');
+    await run({ cwd: resolveCwd(cmd), json: opts.json, save: opts.save });
+  })
+);
+program.command("doctor").description('Alias for `audit --truth` \u2014 "are the recorded instructions still true?"').option("--json", "print findings as JSON").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./doctor-NNRJTNIY.js');
+    await run({ cwd: resolveCwd(cmd), json: opts.json });
+  })
+);
+program.command("context").description("Measure the always-loaded context footprint and flag extraction candidates").option("--json", "print the budget as JSON").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./context-TT5H76LA.js');
+    await run({ cwd: resolveCwd(cmd), json: opts.json });
+  })
+);
+program.command("brief").description("Emit a grounded briefing for the in-repo agent to complete the semantic layer").option("--human", "write a human onboarding brief instead of the agent briefing").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./brief-2MPNTITQ.js');
+    await run({ cwd: resolveCwd(cmd), human: opts.human });
+  })
+);
+program.command("ledger").description("List every tracked finding grouped by status (open \xB7 accepted \xB7 dismissed \xB7 \u2026)").option("--json", "print the raw ledger as JSON").action(
+  (opts, cmd) => action(async () => {
+    const { list } = await import('./ledger-YFTYCOIC.js');
+    await list({ cwd: resolveCwd(cmd), json: opts.json });
+  })
+);
+program.command("dismiss").argument("<finding-id>", "the finding id (from `etymd audit`) to dismiss").description("Dismiss a finding as a false positive / not applicable (hidden from future audits)").requiredOption("--reason <text>", "why it is dismissed \u2014 recorded so the decision survives").action(
+  (id, opts, cmd) => action(async () => {
+    const { dismiss } = await import('./ledger-YFTYCOIC.js');
+    await dismiss({ cwd: resolveCwd(cmd), id, reason: opts.reason });
+  })
+);
+program.command("accept").argument("<finding-id>", "the finding id (from `etymd audit`) to accept").description("Accept a real finding as a known trade-off (hidden from future audits)").option("--reason <text>", "optional note on why the trade-off is accepted").action(
+  (id, opts, cmd) => action(async () => {
+    const { accept } = await import('./ledger-YFTYCOIC.js');
+    await accept({ cwd: resolveCwd(cmd), id, reason: opts.reason });
+  })
+);
+program.command("gates").description("Install the local git-hook gates (process \u2192 pre-commit, correctness \u2192 pre-push)").option("--ci", "note about the CI review gate (ships later; local gates install now)").option("-y, --yes", "skip prompts; never overwrites a hand-edited hook").action(
+  (opts, cmd) => action(async () => {
+    const { run } = await import('./gates-KPDEUC36.js');
+    await run({ cwd: resolveCwd(cmd), ci: opts.ci, yes: opts.yes });
+  })
+);
+program.parseAsync(process.argv);

package/dist/context-TT5H76LA.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { readConfig, measureContext } from './chunk-I566LDX7.js';
+import './chunk-SMM2TW35.js';
+import { print, renderContext } from './chunk-WVYKYPKS.js';
+
+// src/commands/context.ts
+async function run(opts) {
+  const { config, problems } = await readConfig(opts.cwd);
+  const budget = await measureContext(opts.cwd, config.context.perFileWords);
+  if (opts.json) {
+    print(JSON.stringify(budget, null, 2));
+    return;
+  }
+  for (const problem of problems) print(problem);
+  renderContext(budget, budget.perFileWords);
+}
+
+export { run };

package/dist/doctor-NNRJTNIY.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { run } from './chunk-5D7WNJ6N.js';
+import './chunk-N64ZTBCW.js';
+import './chunk-I566LDX7.js';
+import './chunk-TCWKIMCU.js';
+import './chunk-U33XLT5I.js';
+import './chunk-SMM2TW35.js';
+import './chunk-WVYKYPKS.js';
+
+// src/commands/doctor.ts
+async function run2(opts) {
+  await run({ cwd: opts.cwd, json: opts.json, truth: true });
+}
+
+export { run2 as run };

package/dist/gates-KPDEUC36.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { planWorkflow, applyFiles } from './chunk-FXL4554F.js';
+import { scanProject } from './chunk-TCWKIMCU.js';
+import './chunk-U33XLT5I.js';
+import { section, print, glyph, theme, renderPlan, git } from './chunk-WVYKYPKS.js';
+import { confirm, isCancel, cancel } from '@clack/prompts';
+
+async function run(opts) {
+  const facts = await scanProject(opts.cwd);
+  if (opts.ci) {
+    section("CI review gate");
+    print(
+      `  ${glyph.partial} ${theme.dim("The advisory AI-review CI job (bring-your-own-key) ships in a later release \u2014 installing the free local gates below.")}`
+    );
+  }
+  if (!facts.git.isRepo) {
+    print(
+      `  ${glyph.bad} ${theme.dim("Not a git repository \u2014 local hooks need git. Run `git init` first.")}`
+    );
+    return;
+  }
+  if (facts.hooks.source === "husky" || facts.hooks.source === "husky-legacy" || facts.hooks.source === "custom") {
+    print(
+      `  ${glyph.partial} ${theme.warn(`${facts.hooks.source} already manages hooks here.`)} ${theme.dim("git runs ONE hook path \u2014 installing .githooks + core.hooksPath takes over. Fold the existing hook logic in first.")}`
+    );
+    if (!opts.yes) {
+      const go = await confirm({ message: "Proceed with .githooks anyway?", initialValue: false });
+      if (isCancel(go) || !go) {
+        cancel("No changes made.");
+        return;
+      }
+    }
+  }
+  const files = await planWorkflow(opts.cwd, facts, { agents: false, gates: true });
+  const gateFiles = files.filter((f) => f.executable);
+  renderPlan(gateFiles);
+  const overwrite = /* @__PURE__ */ new Set();
+  for (const f of gateFiles) {
+    if (!f.exists) continue;
+    if (!f.differs) {
+      overwrite.add(f.path);
+      continue;
+    }
+    if (opts.yes) continue;
+    const ow = await confirm({
+      message: `${f.path} exists with different content (hand-edited?). Overwrite with the pack version?`,
+      initialValue: false
+    });
+    if (isCancel(ow)) {
+      cancel("No changes made.");
+      return;
+    }
+    if (ow) overwrite.add(f.path);
+  }
+  if (!opts.yes) {
+    const ok = await confirm({ message: "Install these git hooks and point git at .githooks?" });
+    if (isCancel(ok) || !ok) {
+      cancel("No changes made.");
+      return;
+    }
+  }
+  const result = await applyFiles(opts.cwd, gateFiles, overwrite);
+  await git(opts.cwd, ["config", "core.hooksPath", ".githooks"]);
+  section("Done");
+  for (const w of result.written) print(`  ${glyph.ok} ${theme.dim("wrote")} ${theme.info(w)}`);
+  for (const sk of result.skipped)
+    print(`  ${glyph.bullet} ${theme.dim("kept (hand-edited)")} ${theme.dim(sk)}`);
+  print(`  ${glyph.ok} ${theme.dim("set")} ${theme.code("core.hooksPath = .githooks")}`);
+}
+
+export { run };