etymd 0.1.0

package/dist/chunk-FXL4554F.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { PACK_VERSION } from './chunk-TCWKIMCU.js';
+import { pathExists, readText } from './chunk-WVYKYPKS.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+async function applyFiles(root, files, overwrite = /* @__PURE__ */ new Set()) {
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    if (file.exists && !overwrite.has(file.path)) {
+      skipped.push(file.path);
+      continue;
+    }
+    const abs = path.join(root, file.path);
+    await promises.mkdir(path.dirname(abs), { recursive: true });
+    await promises.writeFile(abs, file.contents, "utf8");
+    if (file.executable) await promises.chmod(abs, 493);
+    written.push(file.path);
+  }
+  return { written, skipped };
+}
+
+// src/pack/templates.ts
+function runPrefix(pm) {
+  switch (pm) {
+    case "pnpm":
+      return "pnpm";
+    case "yarn":
+      return "yarn";
+    case "bun":
+      return "bun run";
+    case "npm":
+    case "unknown":
+    default:
+      return "npm run";
+  }
+}
+function isSafeGateCommand(value) {
+  if (!value) return false;
+  return !/--write|--fix|\bcodegen\b|\bgenerate\b|-w\s|--watch/.test(value);
+}
+function mapVerifyCommand(facts) {
+  switch (facts.workspace.kind) {
+    case "nx":
+      return `${facts.packageManager === "yarn" ? "yarn" : "npx"} nx show projects`;
+    case "pnpm":
+      return "pnpm -r ls --depth -1";
+    case "yarn":
+      return "yarn workspaces info";
+    case "npm":
+      return "npm ls --workspaces --depth=0";
+    case "turbo":
+    case "lerna":
+      return "git ls-files '*/package.json'";
+    default:
+      return "git ls-files | head -50";
+  }
+}
+function doneDefinition(facts) {
+  const run = runPrefix(facts.packageManager);
+  const parts = [];
+  const c = facts.commands;
+  const formatCmd = c.formatCheck ?? (isSafeGateCommand(c.format ? c.raw[c.format] : void 0) ? c.format : void 0);
+  if (formatCmd) parts.push(`\`${run} ${formatCmd}\``);
+  if (c.typecheck) parts.push(`\`${run} ${c.typecheck}\``);
+  if (c.lint) parts.push(`\`${run} ${c.lint}\``);
+  if (c.test) parts.push(`\`${run} ${c.test}\``);
+  return parts;
+}
+function generateAgentsMd(facts) {
+  const run = runPrefix(facts.packageManager);
+  const done = doneDefinition(facts);
+  const frameworks = facts.frameworks.length ? facts.frameworks.join(", ") : "none detected";
+  const workspace = facts.workspace.kind === "none" ? "single package" : `${facts.workspace.kind} workspace`;
+  const topDirs = facts.tree.dirs.slice(0, 14);
+  return `# AGENTS.md
+
+Operating contract for AI agents working in **${facts.name}**. One source of truth \u2014 most agents
+(Claude Code, Codex, Cursor, Copilot, Gemini, \u2026) read this file natively. Kept true by
+[etymd](https://www.npmjs.com/package/etymd): the commands, paths, and claims below are audited
+against the actual repo \u2014 update this file when the repo changes, or \`etymd audit\` will tell you.
+
+## What this project is
+
+<!-- One paragraph: what this does and who it is for. Run \`etymd brief\` to have your agent
+draft it from the reckoning; refine by hand. -->
+
+## Stack
+
+- **Shape:** ${workspace}${facts.packages.length ? ` (${facts.packages.length} packages)` : ""}, package manager **${facts.packageManager}**${facts.node ? `, Node ${facts.node}` : ""}.
+- **Frameworks:** ${frameworks}.
+- **CI:** ${facts.ci.system === "none" ? "none detected" : facts.ci.system}.
+
+## Working rules
+
+- **Reuse-first.** Before writing any new helper/component/type: check the map below and the
+  surrounding code \u2014 a "new" thing usually exists.
+- **Minimal diffs.** Never touch files outside the task's scope.
+<!-- Add your project's own rules: commit/branch conventions, what the agent may and may not do,
+org tooling constraints. Keep every rule TRUE \u2014 stale rules erode trust in the rest. -->
+
+## Repo map
+
+> **Advisory, not authoritative** \u2014 re-verify with \`${mapVerifyCommand(facts)}\` before
+> structure-sensitive changes, and update this section in the same change that moves files.
+
+${topDirs.length ? topDirs.map((d) => `- \`${d.name}/\` \u2014 ${d.files} files`).join("\n") : "- (single package; list the key files here)"}
+
+## Done =
+
+${done.length ? `A change is done when these are green:
+
+${done.map((d) => `- ${d}`).join("\n")}` : `Define the check commands that gate a change (test / lint / typecheck / format).`}
+
+## Commands
+
+\`\`\`bash
+${[
+    facts.commands.dev && `${run} ${facts.commands.dev}`,
+    facts.commands.build && `${run} ${facts.commands.build}`,
+    facts.commands.test && `${run} ${facts.commands.test}`,
+    facts.commands.lint && `${run} ${facts.commands.lint}`,
+    facts.commands.typecheck && `${run} ${facts.commands.typecheck}`
+  ].filter(Boolean).join("\n") || "# add the project's key commands"}
+\`\`\`
+
+<!-- etymd pack v${PACK_VERSION} -->
+`;
+}
+function generatePreCommitHook() {
+  return `#!/usr/bin/env sh
+# etymd: process gate. Cheap, locally-knowable checks belong here (fast, blocks the commit).
+exit 0
+`;
+}
+function generatePrePushHook(facts) {
+  const run = runPrefix(facts.packageManager);
+  const c = facts.commands;
+  const candidates = [c.formatCheck, c.typecheck, c.lint];
+  const steps = candidates.filter((key) => Boolean(key) && isSafeGateCommand(c.raw[key])).map((key) => `${run} ${key}`);
+  const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
+${s} || exit 1`).join("\n") : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
+  return `#!/usr/bin/env sh
+# etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
+${body}
+`;
+}
+
+// src/core/generate.ts
+async function planWorkflow(root, facts, opts) {
+  const out = [];
+  const add = async (rel, contents, label, executable = false) => {
+    const abs = path.join(root, rel);
+    const exists = await pathExists(abs);
+    const existing = exists ? await readText(abs) : null;
+    out.push({
+      path: rel,
+      contents,
+      exists,
+      differs: exists ? existing !== contents : void 0,
+      executable,
+      label
+    });
+  };
+  if (opts.agents) {
+    await add("AGENTS.md", generateAgentsMd(facts), "Minimal operating contract (scaffold)");
+  }
+  if (opts.gates) {
+    await add(".githooks/pre-commit", generatePreCommitHook(), "Process gate (pre-commit)", true);
+    await add(".githooks/pre-push", generatePrePushHook(facts), "Correctness gate (pre-push)", true);
+  }
+  return out;
+}
+
+export { applyFiles, planWorkflow };

package/dist/chunk-I566LDX7.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { ETYMD_DIR } from './chunk-SMM2TW35.js';
+import { pathExists, readText, wordCount, approxTokens } from './chunk-WVYKYPKS.js';
+import path2 from 'node:path';
+import { promises } from 'node:fs';
+
+var CONFIG_FILE = path2.join(ETYMD_DIR, "config.json");
+var DEFAULT_CONFIG = {
+  instructions: { include: [], exclude: [] },
+  context: { perFileWords: 4e3, totalWords: 8e3 }
+};
+function configPath(root) {
+  return path2.join(root, CONFIG_FILE);
+}
+function readGlobList(value, key, problems) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    problems.push(`${CONFIG_FILE}: \`${key}\` must be an array of glob strings \u2014 ignored.`);
+    return void 0;
+  }
+  return value.map((g) => g.trim()).filter(Boolean);
+}
+function readBudget(value, key, problems) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    problems.push(`${CONFIG_FILE}: \`${key}\` must be a positive number \u2014 ignored.`);
+    return void 0;
+  }
+  return value;
+}
+async function readConfig(root) {
+  const target = configPath(root);
+  const problems = [];
+  if (!await pathExists(target)) {
+    return { config: DEFAULT_CONFIG, present: false, problems };
+  }
+  const raw = await readText(target);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw ?? "");
+  } catch (err) {
+    problems.push(
+      `${CONFIG_FILE} exists but is not valid JSON (${err instanceof Error ? err.message : String(err)}) \u2014 defaults used.`
+    );
+    return { config: DEFAULT_CONFIG, present: true, problems };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${CONFIG_FILE} must contain a JSON object \u2014 defaults used.`);
+    return { config: DEFAULT_CONFIG, present: true, problems };
+  }
+  const obj = parsed;
+  const instructions = obj.instructions ?? {};
+  const context = obj.context ?? {};
+  return {
+    present: true,
+    problems,
+    config: {
+      instructions: {
+        include: readGlobList(instructions.include, "instructions.include", problems) ?? DEFAULT_CONFIG.instructions.include,
+        exclude: readGlobList(instructions.exclude, "instructions.exclude", problems) ?? DEFAULT_CONFIG.instructions.exclude
+      },
+      context: {
+        perFileWords: readBudget(context.perFileWords, "context.perFileWords", problems) ?? DEFAULT_CONFIG.context.perFileWords,
+        totalWords: readBudget(context.totalWords, "context.totalWords", problems) ?? DEFAULT_CONFIG.context.totalWords
+      }
+    }
+  };
+}
+var ALWAYS_LOADED = [
+  { path: "AGENTS.md", role: "operating contract" },
+  { path: "CLAUDE.md", role: "Claude Code pointer" },
+  { path: "GEMINI.md", role: "Gemini pointer" },
+  { path: ".github/copilot-instructions.md", role: "Copilot instructions" },
+  { path: ".cursorrules", role: "Cursor rules (legacy)" }
+];
+var EXTRACTION_THRESHOLD = DEFAULT_CONFIG.context.perFileWords;
+function isAlwaysAppliedCursorRule(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return true;
+  const frontmatter = fm[1] ?? "";
+  return /^\s*alwaysApply\s*:\s*true\s*$/m.test(frontmatter);
+}
+async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
+  const files = [];
+  for (const spec of ALWAYS_LOADED) {
+    const abs = path2.join(root, spec.path);
+    const text = await readText(abs);
+    if (text === null) continue;
+    const words = wordCount(text);
+    files.push({ path: spec.path, role: spec.role, words, approxTokens: approxTokens(words) });
+  }
+  const rulesDir = path2.join(root, ".cursor", "rules");
+  if (await pathExists(rulesDir)) {
+    try {
+      for (const entry of await promises.readdir(rulesDir)) {
+        if (!entry.endsWith(".mdc") && !entry.endsWith(".md")) continue;
+        const text = await readText(path2.join(rulesDir, entry));
+        if (text === null || !isAlwaysAppliedCursorRule(text)) continue;
+        const words = wordCount(text);
+        files.push({
+          path: `.cursor/rules/${entry}`,
+          role: "Cursor rule (always applied)",
+          words,
+          approxTokens: approxTokens(words)
+        });
+      }
+    } catch {
+    }
+  }
+  const totalWords = files.reduce((s, f) => s + f.words, 0);
+  return {
+    files: files.sort((a, b) => b.words - a.words),
+    totalWords,
+    totalApproxTokens: approxTokens(totalWords),
+    perFileWords,
+    extractionCandidates: files.filter((f) => f.words >= perFileWords)
+  };
+}
+
+export { CONFIG_FILE, DEFAULT_CONFIG, measureContext, readConfig };

package/dist/chunk-N64ZTBCW.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { readJson } from './chunk-WVYKYPKS.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+function ledgerPath(root) {
+  return path.join(root, ".etymd", "ledger.json");
+}
+async function readLedger(root) {
+  return await readJson(ledgerPath(root)) ?? { version: 1, entries: [] };
+}
+async function writeLedger(root, ledger) {
+  const target = ledgerPath(root);
+  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.writeFile(target, JSON.stringify(ledger, null, 2) + "\n", "utf8");
+}
+function belongsToAny(id, paths) {
+  return paths.some((p) => id.includes(`:${p}`));
+}
+function reconcileLedger(ledger, findings, now = (/* @__PURE__ */ new Date()).toISOString(), outOfScope = []) {
+  const byId = new Map(ledger.entries.map((e) => [e.id, e]));
+  const seen = /* @__PURE__ */ new Set();
+  const diff = {
+    new: [],
+    stillOpen: [],
+    regressed: [],
+    resolved: [],
+    dismissed: [],
+    accepted: [],
+    outOfScope: []
+  };
+  const entries = [];
+  for (const f of findings) {
+    seen.add(f.id);
+    const prev = byId.get(f.id);
+    if (!prev) {
+      diff.new.push(f);
+      entries.push({
+        id: f.id,
+        status: "open",
+        tier: f.tier,
+        claim: f.claim,
+        firstSeen: now,
+        lastSeen: now
+      });
+      continue;
+    }
+    if (prev.status === "dismissed") {
+      diff.dismissed.push(f);
+      entries.push({ ...prev, lastSeen: now });
+      continue;
+    }
+    if (prev.status === "accepted") {
+      diff.accepted.push(f);
+      entries.push({ ...prev, tier: f.tier, claim: f.claim, lastSeen: now });
+      continue;
+    }
+    if (prev.status === "done") {
+      diff.regressed.push(f);
+      entries.push({ ...prev, status: "regressed", tier: f.tier, claim: f.claim, lastSeen: now });
+      continue;
+    }
+    diff.stillOpen.push(f);
+    entries.push({ ...prev, tier: f.tier, claim: f.claim, lastSeen: now });
+  }
+  for (const prev of ledger.entries) {
+    if (seen.has(prev.id)) continue;
+    if (outOfScope.length && belongsToAny(prev.id, outOfScope)) {
+      diff.outOfScope.push(prev);
+      entries.push(prev);
+      continue;
+    }
+    if (prev.status === "open" || prev.status === "accepted" || prev.status === "regressed") {
+      diff.resolved.push(prev);
+      entries.push({ ...prev, status: "done", lastSeen: now });
+    } else {
+      entries.push(prev);
+    }
+  }
+  return { ledger: { version: 1, entries }, diff };
+}
+function visibleFindings(findings, ledger) {
+  const quieted = new Set(
+    ledger.entries.filter((e) => e.status === "dismissed" || e.status === "accepted").map((e) => e.id)
+  );
+  return findings.filter((f) => !quieted.has(f.id));
+}
+function resolveEntry(ledger, id, status, reason, now = (/* @__PURE__ */ new Date()).toISOString()) {
+  let updated = null;
+  const entries = ledger.entries.map((e) => {
+    if (e.id !== id) return e;
+    updated = {
+      ...e,
+      status,
+      // Keep an existing reason if none is supplied (e.g. re-accepting a once-dismissed item).
+      reason: reason ?? e.reason,
+      lastSeen: now
+    };
+    return updated;
+  });
+  if (!updated) return { ledger, entry: null };
+  return { ledger: { version: 1, entries }, entry: updated };
+}
+
+export { readLedger, reconcileLedger, resolveEntry, visibleFindings, writeLedger };

package/dist/chunk-SMM2TW35.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { readJson } from './chunk-WVYKYPKS.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+var ETYMD_DIR = ".etymd";
+var CACHE_DIR = path.join(ETYMD_DIR, "cache");
+var CACHE_FACTS_FILE = path.join(CACHE_DIR, "facts.json");
+var BASELINE_FILE = path.join(ETYMD_DIR, "baseline.json");
+function cacheFactsPath(root) {
+  return path.join(root, CACHE_FACTS_FILE);
+}
+function baselinePath(root) {
+  return path.join(root, BASELINE_FILE);
+}
+async function writeJsonFile(target, data) {
+  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.writeFile(target, JSON.stringify(data, null, 2) + "\n", "utf8");
+  return target;
+}
+async function writeCachedFacts(root, facts) {
+  return writeJsonFile(cacheFactsPath(root), facts);
+}
+function withoutMachinePath(facts) {
+  return { ...facts, root: "." };
+}
+function baselineCarriesMachinePath(baseline) {
+  const root = baseline.facts?.root;
+  return typeof root === "string" && root !== "." && (root.startsWith("/") || /^[A-Za-z]:[\\/]/.test(root));
+}
+async function writeBaseline(root, baseline) {
+  return writeJsonFile(baselinePath(root), {
+    ...baseline,
+    facts: withoutMachinePath(baseline.facts)
+  });
+}
+async function readBaseline(root) {
+  return readJson(baselinePath(root));
+}
+function deriveProfile(facts) {
+  return (facts.git.recentAuthors ?? 1) > 2 ? "team" : "solo";
+}
+var DRIFT_ROLES = ["test", "lint", "typecheck", "format", "formatCheck", "build", "dev"];
+function summarizeBaselineDrift(old, fresh) {
+  const commands = [];
+  for (const role of DRIFT_ROLES) {
+    const from = old.commands[role];
+    const to = fresh.commands[role];
+    if (from !== to) commands.push({ role, from, to });
+  }
+  const presentIds = (f) => new Set(f.artifacts.filter((a) => a.exists).map((a) => a.id));
+  const oldArtifacts = presentIds(old);
+  const freshArtifacts = presentIds(fresh);
+  const labelOf = (id) => fresh.artifacts.find((a) => a.id === id)?.label ?? old.artifacts.find((a) => a.id === id)?.label ?? id;
+  const artifactsAdded = [...freshArtifacts].filter((id) => !oldArtifacts.has(id)).map(labelOf);
+  const artifactsRemoved = [...oldArtifacts].filter((id) => !freshArtifacts.has(id)).map(labelOf);
+  const oldDirs = new Set(old.tree.dirs.map((d) => d.name));
+  const freshDirs = new Set(fresh.tree.dirs.map((d) => d.name));
+  const dirsAdded = [...freshDirs].filter((d) => !oldDirs.has(d));
+  const dirsRemoved = [...oldDirs].filter((d) => !freshDirs.has(d));
+  return { commands, artifactsAdded, artifactsRemoved, dirsAdded, dirsRemoved };
+}
+function isDriftEmpty(d) {
+  return d.commands.length === 0 && d.artifactsAdded.length === 0 && d.artifactsRemoved.length === 0 && d.dirsAdded.length === 0 && d.dirsRemoved.length === 0;
+}
+
+export { BASELINE_FILE, CACHE_DIR, ETYMD_DIR, baselineCarriesMachinePath, deriveProfile, isDriftEmpty, readBaseline, summarizeBaselineDrift, writeBaseline, writeCachedFacts };