project-athena 0.2.1 → 0.4.0

package/dist/chunk-KHMBNT66.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+import {
+  projectSession
+} from "./chunk-WVQC2EGO.js";
+import {
+  impactOf
+} from "./chunk-GR4DL2VM.js";
+import {
+  composeState,
+  ensureRules,
+  indexWithIntegrations,
+  planKnowledge,
+  writePlannedKnowledge
+} from "./chunk-GGXPG6OE.js";
+import {
+  analyzeProject
+} from "./chunk-MPG3IEGB.js";
+import {
+  headMovement
+} from "./chunk-OLPSEQS5.js";
+import {
+  KNOWLEDGE_DOCS
+} from "./chunk-FQEGEVLY.js";
+import {
+  athenaDir,
+  backupCorruptedState,
+  buildFileIndex,
+  diffFileIndex,
+  readFileIndex,
+  readState,
+  writeState
+} from "./chunk-2DY4PUR4.js";
+import {
+  readTextIfExists,
+  sha256,
+  writeFileAtomic
+} from "./chunk-IQQBAWSM.js";
+import {
+  AthenaError,
+  conflict
+} from "./chunk-AD4OZCU2.js";
+
+// src/services/sync.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { createTwoFilesPatch } from "diff";
+
+// src/core/impact/model-diff.ts
+var named = (i) => String(i.name ?? i.path ?? JSON.stringify(i));
+var MODEL_SECTIONS = [
+  { label: "Project identity", keys: ["name", "description"], docs: ["project"] },
+  { label: "Languages", keys: ["languages"], docs: ["project"], identity: named, unit: ["language", "languages"] },
+  { label: "Project structure", keys: ["topLevelDirs", "stats"], docs: ["project"] },
+  { label: "Dependencies & manifests", keys: ["manifests"], docs: ["project", "security"], identity: (i) => String(i.path), unit: ["manifest", "manifests"] },
+  { label: "Package managers & build tools", keys: ["packageManagers", "buildSystems"], docs: ["project"], identity: named, unit: ["tool", "tools"] },
+  { label: "Workspace packages", keys: ["workspace"], docs: ["project", "architecture", "code-review", "testing"] },
+  { label: "Frameworks", keys: ["frameworks"], docs: ["project", "architecture", "api", "security", "code-review", "performance"], identity: (i) => `${i.name}@${i.root}`, display: (i) => String(i.name), unit: ["framework", "frameworks"] },
+  { label: "Entry points", keys: ["entryPoints"], docs: ["project"], identity: (i) => String(i.path), unit: ["entry point", "entry points"] },
+  { label: "Commands", keys: ["commands"], docs: ["project", "testing", "debugging", "deployment", "code-review", "database"], identity: (i) => `${i.source}:${i.name}`, display: (i) => String(i.name), unit: ["command", "commands"] },
+  { label: "Database technology", keys: ["databases"], docs: ["database", "architecture", "security", "code-review", "performance"], identity: named, unit: ["technology", "technologies"] },
+  { label: "Database schema", keys: ["dbEntities"], docs: ["database", "auth", "performance"], identity: (i) => `${i.name}@${i.file}`, display: (i) => String(i.name), unit: ["entity", "entities"] },
+  { label: "Migrations", keys: ["migrations"], docs: ["database", "deployment"], identity: (i) => `${i.tool}:${i.path}`, display: (i) => String(i.path), unit: ["migration directory", "migration directories"] },
+  { label: "API routes", keys: ["routes"], docs: ["api", "security", "testing", "code-review"], identity: (i) => `${i.method} ${i.path} ${i.file}`, display: (i) => `${i.method} ${i.path}`, unit: ["route", "routes"] },
+  { label: "API specifications", keys: ["apiSpecs"], docs: ["api", "security"], identity: (i) => String(i.path), unit: ["spec", "specs"] },
+  { label: "Authentication", keys: ["auth"], docs: ["auth", "security", "architecture"], identity: named, unit: ["auth signal", "auth signals"] },
+  { label: "Containers", keys: ["containers"], docs: ["deployment", "architecture", "security"] },
+  { label: "Infrastructure", keys: ["infrastructure"], docs: ["deployment", "architecture"], identity: (i) => `${i.name}@${i.file}`, display: (i) => String(i.name), unit: ["resource", "resources"] },
+  { label: "CI/CD", keys: ["ci"], docs: ["deployment"], identity: (i) => `${i.system}:${i.file}:${i.name}`, unit: ["CI job", "CI jobs"] },
+  { label: "Tests", keys: ["tests"], docs: ["testing", "code-review"] },
+  { label: "Environment variables", keys: ["env"], docs: ["deployment", "project", "security"] },
+  { label: "Security findings & controls", keys: ["security"], docs: ["security"] },
+  { label: "Caching & queues", keys: ["caching", "queues"], docs: ["performance", "architecture", "security"], identity: named, unit: ["technology", "technologies"] },
+  { label: "Observability", keys: ["observability"], docs: ["debugging", "architecture"], identity: named, unit: ["tool", "tools"] },
+  { label: "Git hotspots", keys: ["git"], docs: ["debugging"] },
+  { label: "Analysis warnings", keys: ["warnings"], docs: ["project"] }
+];
+function stable(v) {
+  return JSON.stringify(v, (_k, val) => val && typeof val === "object" && !Array.isArray(val) ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b))) : val);
+}
+function normalize(key, value) {
+  if (key === "git" && value && typeof value === "object") return { hotspots: value.hotspots };
+  if (key === "root") return null;
+  return value;
+}
+function diffModels(prev, next) {
+  if (!prev) return [{ label: "Previous analysis", summary: "no previous model.json to compare against \u2014 full comparison of rendered documents used", docs: [] }];
+  const changes = [];
+  for (const spec of MODEL_SECTIONS) {
+    const differing = spec.keys.filter((k) => stable(normalize(k, prev[k])) !== stable(normalize(k, next[k])));
+    if (!differing.length) continue;
+    const parts = [];
+    for (const k of differing) {
+      const a = prev[k];
+      const b = next[k];
+      if (Array.isArray(a) && Array.isArray(b) && spec.identity) {
+        const labels = /* @__PURE__ */ new Map();
+        const ids = (xs) => new Map(
+          xs.map((x) => {
+            const item = x;
+            const id = spec.identity(item);
+            labels.set(id, (spec.display ?? spec.identity)(item));
+            return [id, stable(x)];
+          })
+        );
+        const ma = ids(a);
+        const mb = ids(b);
+        const show = (xs) => [...new Set(xs.map((x) => labels.get(x) ?? x))];
+        const added = show([...mb.keys()].filter((x) => !ma.has(x)));
+        const removed = show([...ma.keys()].filter((x) => !mb.has(x)));
+        const changed = show([...mb.keys()].filter((x) => ma.has(x) && ma.get(x) !== mb.get(x)));
+        const [one, many] = spec.unit ?? ["item", "items"];
+        const fmt = (n, verb, list) => n ? `${n} ${n === 1 ? one : many} ${verb}${list.length <= 3 ? ` (${list.join(", ")})` : ""}` : "";
+        parts.push(...[fmt(added.length, "added", added), fmt(removed.length, "removed", removed), fmt(changed.length, "changed", changed)].filter(Boolean));
+      } else if (k === "stats") {
+        const sa = a;
+        const sb = b;
+        if (sa.filesScanned !== sb.filesScanned) parts.push(`files analyzed ${sa.filesScanned} \u2192 ${sb.filesScanned}`);
+        else parts.push("file statistics changed");
+      } else {
+        parts.push(describeObjectChange(k, a, b));
+      }
+    }
+    changes.push({ label: spec.label, summary: parts.join("; ") || "changed", docs: spec.docs });
+  }
+  return changes;
+}
+function names(xs) {
+  return new Set(xs.map((x) => x.name));
+}
+function setDelta(label, a, b) {
+  const added = [...b].filter((x) => !a.has(x));
+  const removed = [...a].filter((x) => !b.has(x));
+  const out = [];
+  const list = (xs) => xs.length <= 3 ? ` (${xs.join(", ")})` : "";
+  if (added.length) out.push(`${added.length} ${label} added${list(added)}`);
+  if (removed.length) out.push(`${removed.length} ${label} removed${list(removed)}`);
+  return out;
+}
+function describeObjectChange(key, a, b) {
+  const parts = [];
+  switch (key) {
+    case "env": {
+      const ea = a;
+      const eb = b;
+      parts.push(...setDelta("variable name(s)", names(ea.vars), names(eb.vars)));
+      parts.push(...setDelta("env file(s)", new Set(ea.envFilesPresent), new Set(eb.envFilesPresent)));
+      if (!parts.length) parts.push("variable references moved");
+      break;
+    }
+    case "security": {
+      const sa = a;
+      const sb = b;
+      if (sa.secrets.length !== sb.secrets.length) parts.push(`potential secrets ${sa.secrets.length} \u2192 ${sb.secrets.length}`);
+      parts.push(...setDelta("control(s)", names(sa.controls), names(sb.controls)));
+      parts.push(...setDelta("tool(s)", names(sa.tooling), names(sb.tooling)));
+      if (!parts.length) parts.push("evidence locations changed");
+      break;
+    }
+    case "tests": {
+      const ta = a;
+      const tb = b;
+      if (ta.testFileCount !== tb.testFileCount) parts.push(`test files ${ta.testFileCount} \u2192 ${tb.testFileCount}`);
+      parts.push(...setDelta("framework(s)", names(ta.frameworks), names(tb.frameworks)));
+      if (!parts.length) parts.push("test layout changed");
+      break;
+    }
+    case "containers": {
+      const ca = a;
+      const cb = b;
+      parts.push(...setDelta("Dockerfile(s)", new Set(ca.dockerfiles.map((d) => d.path)), new Set(cb.dockerfiles.map((d) => d.path))));
+      parts.push(...setDelta("service(s)", names(ca.services), names(cb.services)));
+      if (!parts.length) parts.push("container configuration changed");
+      break;
+    }
+    case "workspace": {
+      const wa = a;
+      const wb = b;
+      parts.push(...setDelta("package(s)", names(wa.packages), names(wb.packages)));
+      if (!parts.length) parts.push("package dependencies changed");
+      break;
+    }
+    case "topLevelDirs":
+      parts.push(...setDelta("top-level director(ies)", new Set(a), new Set(b)));
+      break;
+    case "git":
+      parts.push("change hotspots updated from recent commits");
+      break;
+    case "name":
+    case "description":
+      parts.push(`${key} changed`);
+      break;
+    default:
+      parts.push(`${String(key)} changed`);
+  }
+  return parts.join("; ");
+}
+
+// src/services/sync.ts
+var IGNORE_FILE = ".sync-ignore.json";
+var MAX_DIFF_CHARS = 6e4;
+var internals = /* @__PURE__ */ new WeakMap();
+var hashOf = (text) => text === null ? null : sha256(text).slice(0, 16);
+function countLines(patch) {
+  let additions = 0;
+  let deletions = 0;
+  for (const line of patch.split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) additions++;
+    else if (line.startsWith("-") && !line.startsWith("---")) deletions++;
+  }
+  return { additions, deletions };
+}
+function detectRenames(prev, next, added, deleted) {
+  const byHash = /* @__PURE__ */ new Map();
+  for (const d of deleted) {
+    const h = prev[d]?.h.slice(0, 16);
+    if (h && !h.startsWith("meta:")) byHash.set(h, [...byHash.get(h) ?? [], d]);
+  }
+  const renamed = [];
+  const remainingAdded = [];
+  const usedDeleted = /* @__PURE__ */ new Set();
+  for (const a of added) {
+    const candidates = byHash.get(next[a]?.h.slice(0, 16) ?? "")?.filter((d) => !usedDeleted.has(d));
+    if (candidates?.length) {
+      usedDeleted.add(candidates[0]);
+      renamed.push({ from: candidates[0], to: a });
+    } else remainingAdded.push(a);
+  }
+  return { added: remainingAdded, modified: [], deleted: deleted.filter((d) => !usedDeleted.has(d)), renamed };
+}
+async function readIgnored(dir) {
+  const raw = await readTextIfExists(path.join(dir, IGNORE_FILE));
+  if (!raw) return null;
+  try {
+    const j = JSON.parse(raw);
+    return typeof j.planId === "string" ? j.planId : null;
+  } catch {
+    return null;
+  }
+}
+async function planSync(root, opts = {}) {
+  const started = Date.now();
+  const dir = athenaDir(root);
+  const st = await readState(dir);
+  if (st.kind === "missing" && !await readTextIfExists(path.join(dir, "rules.md"))) {
+    throw new AthenaError("Athena is not initialized in this project.", "Run `athena init` first.", 3);
+  }
+  const prevState = st.kind === "ok" ? st.state : null;
+  const warnings = [];
+  if (st.kind === "corrupted") warnings.push(`state.json is corrupted (${st.reason}); it will be rebuilt on apply.`);
+  const prevIndex = prevState ? await readFileIndex(dir) : {};
+  const [prevModel, analysis] = await Promise.all([projectSession(root).model(), analyzeProject(root, { signal: opts.signal, reuse: prevIndex, incremental: opts.incremental })]);
+  opts.signal?.throwIfAborted();
+  const previousBlocks = prevState ? Object.fromEntries(Object.entries(prevState.documents).map(([k, v]) => [k, v.blocks])) : void 0;
+  const plans = await planKnowledge(dir, analysis.model, { force: opts.force, previousBlocks });
+  const nextIndex = buildFileIndex(analysis.files);
+  const rawDiff = diffFileIndex(prevIndex, nextIndex);
+  const managed = new Set(Object.values(prevState?.agents ?? {}).flatMap((a) => a.files));
+  const idxChanges = { added: rawDiff.added.filter((p) => !managed.has(p)), modified: rawDiff.modified.filter((p) => !managed.has(p)), deleted: rawDiff.deleted.filter((p) => !managed.has(p)) };
+  const renames = detectRenames(prevIndex, nextIndex, idxChanges.added, idxChanges.deleted);
+  const fileChanges = { ...renames, modified: idxChanges.modified };
+  const modelChanges = diffModels(prevModel, analysis.model);
+  const allPaths = [...fileChanges.added, ...fileChanges.modified, ...fileChanges.deleted, ...fileChanges.renamed.flatMap((r) => [r.from, r.to])];
+  const pathImpact = impactOf(allPaths, { structural: [...fileChanges.added, ...fileChanges.deleted, ...fileChanges.renamed.map((r) => r.to)] });
+  const documents = [];
+  for (const p of plans) {
+    if (p.status === "unchanged") continue;
+    const doc = KNOWLEDGE_DOCS.find((d) => d.id === p.id);
+    const reasons = [
+      ...modelChanges.filter((c) => c.docs.includes(p.id)).map((c) => `${c.label}: ${c.summary}`),
+      ...(pathImpact.reasons[p.id] ?? []).map((r) => `Changed files (${r})`)
+    ];
+    if (p.status === "created") reasons.unshift("Document is missing and will be recreated");
+    if (!reasons.length) reasons.push("Rendered content differs from the file on disk (for example after an Athena upgrade or a manual edit outside sections)");
+    let patch = createTwoFilesPatch(`a/.athena/${p.file}`, `b/.athena/${p.file}`, p.before ?? "", p.after, void 0, void 0, { context: 3 });
+    const counts = countLines(patch);
+    const diffTruncated = patch.length > MAX_DIFF_CHARS;
+    if (diffTruncated) patch = `${patch.slice(0, MAX_DIFF_CHARS)}
+\u2026 diff truncated \u2026
+`;
+    documents.push({
+      id: p.id,
+      file: p.file,
+      title: doc.title,
+      status: p.status,
+      reasons: [...new Set(reasons)],
+      changedSections: p.changedBlocks,
+      preservedSections: p.preservedModified,
+      diff: patch,
+      diffTruncated,
+      ...counts,
+      baseHash: hashOf(p.before)
+    });
+  }
+  const git = {
+    isRepo: analysis.model.git.isRepo,
+    previousHead: prevState?.git.head ?? null,
+    head: analysis.model.git.head ?? null,
+    previousBranch: prevState?.git.branch ?? null,
+    branch: analysis.model.git.branch ?? null,
+    branchChanged: Boolean(prevState?.git.branch && analysis.model.git.branch && prevState.git.branch !== analysis.model.git.branch),
+    commits: [],
+    diverged: false,
+    truncated: false
+  };
+  if (git.isRepo && git.previousHead && git.head && git.previousHead !== git.head) {
+    const mv = await headMovement(root, git.previousHead, git.head);
+    if (mv) Object.assign(git, { commits: mv.commits, diverged: mv.diverged, truncated: mv.truncated });
+  }
+  const id = sha256(JSON.stringify(documents.map((d) => [d.file, d.baseHash, hashOf(plans.find((p) => p.id === d.id).after)]))).slice(0, 16);
+  const upToDate = documents.length === 0;
+  const plan = {
+    id,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    previousAnalysisAt: prevState?.analyzedAt ?? null,
+    upToDate,
+    fileChanges,
+    git,
+    modelChanges: prevModel ? modelChanges : [],
+    documents,
+    checkedUnchanged: pathImpact.docs.map((d) => KNOWLEDGE_DOCS.find((k) => k.id === d).file).filter((f) => !documents.some((d) => d.file === f)),
+    ignored: !upToDate && await readIgnored(dir) === id,
+    durationMs: Date.now() - started,
+    warnings
+  };
+  internals.set(plan, { analysis, plans, prevState });
+  return plan;
+}
+function planSnapshot(plan) {
+  const a = internals.get(plan)?.analysis;
+  return a ? { snapshot: a.snapshot, walkMode: a.walkMode } : null;
+}
+async function applySync(root, plan) {
+  const inner = internals.get(plan);
+  if (!inner) throw new AthenaError("This sync plan is no longer available.", "Create a new plan and try again.", 1, "conflict");
+  const dir = athenaDir(root);
+  for (const d of plan.documents) {
+    const current = hashOf(await readTextIfExists(path.join(dir, d.file)));
+    if (current !== d.baseHash) {
+      throw conflict(`${d.file} changed after the sync plan was created.`, "Review the new plan before applying.", { file: d.file });
+    }
+  }
+  const st = await readState(dir);
+  if (st.kind === "corrupted") await backupCorruptedState(dir);
+  const prevState = st.kind === "ok" ? st.state : inner.prevState;
+  await fs.mkdir(dir, { recursive: true });
+  const docs = await writePlannedKnowledge(dir, inner.plans);
+  docs.push(await ensureRules(dir, inner.analysis.model));
+  await writeFileAtomic(path.join(dir, "model.json"), `${JSON.stringify(inner.analysis.model, null, 2)}
+`);
+  const managedFiles = Object.values(prevState?.agents ?? {}).flatMap((a) => a.files);
+  const state = composeState({
+    prevState,
+    analysis: inner.analysis,
+    docs,
+    agents: prevState?.agents ?? {},
+    fileIndex: await indexWithIntegrations(root, inner.analysis.files, managedFiles)
+  });
+  await writeState(dir, state);
+  await fs.rm(path.join(dir, IGNORE_FILE), { force: true });
+  internals.delete(plan);
+  return {
+    applied: plan.documents.map((d) => d.file),
+    preserved: plan.documents.filter((d) => d.preservedSections.length).map((d) => ({ file: d.file, sections: d.preservedSections })),
+    analyzedAt: state.analyzedAt
+  };
+}
+async function ignorePlan(root, planId) {
+  if (!/^[a-f0-9]{16}$/.test(planId)) throw new AthenaError("Invalid plan id");
+  await writeFileAtomic(path.join(athenaDir(root), IGNORE_FILE), `${JSON.stringify({ planId, ignoredAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
+`);
+}
+function fileChangeCount(plan) {
+  const c = plan.fileChanges;
+  return c.added.length + c.modified.length + c.deleted.length + c.renamed.length;
+}
+function needsIndexRefreshOnly(plan) {
+  return plan.upToDate && (fileChangeCount(plan) > 0 || plan.git.head !== plan.git.previousHead);
+}
+function summarizePlan(plan) {
+  const { documents, ...rest } = plan;
+  return { ...rest, documents: documents.map(({ diff: _diff, ...d }) => d) };
+}
+var HISTORY_SECTIONS = /* @__PURE__ */ new Set(["hotspots"]);
+function staleForCheck(plan) {
+  return plan.documents.filter((d) => d.status === "created" || !d.changedSections.length || d.changedSections.some((s) => !HISTORY_SECTIONS.has(s)));
+}
+
+export {
+  planSync,
+  planSnapshot,
+  applySync,
+  ignorePlan,
+  fileChangeCount,
+  needsIndexRefreshOnly,
+  summarizePlan,
+  HISTORY_SECTIONS,
+  staleForCheck
+};
+//# sourceMappingURL=chunk-KHMBNT66.js.map

package/dist/chunk-LEMPCNAY.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import {
+  addRule,
+  listRules,
+  parseRules,
+  removeRule,
+  serializeRules,
+  updateRule
+} from "./chunk-3IS2X2Z7.js";
+import {
+  git
+} from "./chunk-OLPSEQS5.js";
+import {
+  scanText
+} from "./chunk-JCGDR4UV.js";
+import {
+  isBlockModified,
+  parseBlocks
+} from "./chunk-673EPYYH.js";
+import {
+  KNOWLEDGE_DOCS
+} from "./chunk-FQEGEVLY.js";
+import {
+  athenaDir,
+  readState
+} from "./chunk-2DY4PUR4.js";
+import {
+  readTextIfExists,
+  sha256,
+  writeFileAtomic
+} from "./chunk-IQQBAWSM.js";
+import {
+  AthenaError,
+  conflict,
+  notFound
+} from "./chunk-AD4OZCU2.js";
+
+// src/services/rules.ts
+import path2 from "path";
+
+// src/services/knowledge.ts
+import path from "path";
+var MAX_DOC_BYTES = 1e6;
+function resolveDoc(id) {
+  const doc = KNOWLEDGE_DOCS.find((d) => d.id === id);
+  if (!doc) throw notFound(`Unknown knowledge document: ${id.slice(0, 64)}`);
+  return doc;
+}
+function contentHash(text) {
+  return sha256(text).slice(0, 16);
+}
+function segmentDocument(text) {
+  const segments = [];
+  let cursor = 0;
+  for (const b of parseBlocks(text)) {
+    const before = text.slice(cursor, b.start);
+    if (before.trim()) segments.push({ kind: "developer", content: before });
+    segments.push({ kind: "generated", id: b.id, modified: isBlockModified(b), content: b.content });
+    cursor = b.end;
+  }
+  const rest = text.slice(cursor);
+  if (rest.trim()) segments.push({ kind: "developer", content: rest });
+  return segments;
+}
+async function meta(root, id, text) {
+  const doc = resolveDoc(id);
+  const st = await readState(athenaDir(root));
+  const ds = st.kind === "ok" ? st.state.documents[id] : void 0;
+  const blocks = text ? parseBlocks(text) : [];
+  return {
+    id,
+    file: doc.file,
+    title: doc.title,
+    purpose: doc.purpose,
+    present: text !== null,
+    bytes: text ? Buffer.byteLength(text) : 0,
+    hash: text === null ? null : contentHash(text),
+    lastGeneratedAt: ds?.lastGeneratedAt ?? (st.kind === "ok" && id === "rules" ? st.state.createdAt : null),
+    lastChangedAt: ds?.lastChangedAt ?? null,
+    generatedSections: blocks.length,
+    editedSections: blocks.filter(isBlockModified).map((b) => b.id)
+  };
+}
+async function listDocs(root) {
+  const out = [];
+  for (const d of KNOWLEDGE_DOCS) out.push(await meta(root, d.id, await readTextIfExists(path.join(athenaDir(root), d.file))));
+  return out;
+}
+async function readDoc(root, id) {
+  const doc = resolveDoc(id);
+  const text = await readTextIfExists(path.join(athenaDir(root), doc.file));
+  if (text === null) throw notFound(`${doc.file} does not exist. Run \`athena analyze\` to regenerate it.`);
+  return { ...await meta(root, doc.id, text), content: text, segments: segmentDocument(text) };
+}
+async function saveDoc(root, id, content, baseHash) {
+  const doc = resolveDoc(id);
+  if (typeof content !== "string") throw new AthenaError("content must be a string");
+  if (Buffer.byteLength(content) > MAX_DOC_BYTES) throw new AthenaError(`Document exceeds ${MAX_DOC_BYTES} bytes`, void 0, 1, "unprocessable");
+  const file = path.join(athenaDir(root), doc.file);
+  const current = await readTextIfExists(file);
+  const currentHash = current === null ? null : contentHash(current);
+  if (currentHash !== baseHash) {
+    throw conflict(`${doc.file} was changed on disk since you opened it.`, "Reload to see the latest version, then re-apply your edits.", { currentHash });
+  }
+  const secrets = scanText(content);
+  if (secrets.length) {
+    throw new AthenaError(
+      `Refusing to save: ${secrets.length} likely secret(s) found (${[...new Set(secrets.map((s) => s.type))].join(", ")}).`,
+      "Knowledge files must never contain secrets. Replace values with placeholders such as <configured externally>.",
+      1,
+      "unprocessable",
+      { secrets: secrets.map((s) => ({ type: s.type, line: s.line })) }
+    );
+  }
+  const normalized = content.replace(/\r\n/g, "\n");
+  await writeFileAtomic(file, normalized.endsWith("\n") ? normalized : `${normalized}
+`);
+  return readDoc(root, doc.id);
+}
+async function searchDocs(root, query, limit = 50) {
+  const q = query.trim().toLowerCase();
+  if (q.length < 2) return [];
+  const hits = [];
+  for (const d of KNOWLEDGE_DOCS) {
+    const text = await readTextIfExists(path.join(athenaDir(root), d.file));
+    if (!text) continue;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length && hits.length < limit; i++) {
+      const line = lines[i];
+      if (line.startsWith("<!-- athena:")) continue;
+      if (line.toLowerCase().includes(q)) hits.push({ id: d.id, file: d.file, title: d.title, line: i + 1, text: line.trim().slice(0, 240) });
+    }
+    if (d.title.toLowerCase().includes(q) && !hits.some((h) => h.id === d.id)) hits.unshift({ id: d.id, file: d.file, title: d.title, line: 1, text: d.purpose });
+  }
+  return hits.slice(0, limit);
+}
+async function docHistory(root, id, limit = 50) {
+  const doc = resolveDoc(id);
+  const rel = `.athena/${doc.file}`;
+  const r = await git(root, ["log", `-n${limit}`, "--follow", "--format=%H%x1f%cI%x1f%s", "--", rel]);
+  if (!r.ok) return { available: false, reason: "Git history is not available (not a Git repository, or git is not installed).", entries: [] };
+  const entries = r.stdout.split("\n").filter(Boolean).map((l) => {
+    const [sha, date, subject] = l.split("");
+    return { sha, date, subject: subject ?? "" };
+  });
+  if (!entries.length) return { available: true, reason: `${rel} has not been committed yet.`, entries };
+  return { available: true, entries };
+}
+async function docAtRevision(root, id, sha) {
+  const doc = resolveDoc(id);
+  if (!/^[0-9a-f]{7,64}$/i.test(sha)) throw new AthenaError("Invalid revision");
+  const prefix = (await git(root, ["rev-parse", "--show-prefix"])).stdout.trim();
+  const r = await git(root, ["show", `${sha}:${prefix}.athena/${doc.file}`]);
+  if (!r.ok) throw notFound(`${doc.file} does not exist at revision ${sha.slice(0, 12)}`);
+  return r.stdout;
+}
+
+// src/services/rules.ts
+async function load(root) {
+  const file = path2.join(athenaDir(root), "rules.md");
+  const text = await readTextIfExists(file);
+  if (text === null) throw notFound(".athena/rules.md not found. Run `athena analyze` to recreate it.");
+  return { file, text, doc: parseRules(text) };
+}
+function view(text, doc) {
+  const rules = listRules(doc);
+  const sections = [.../* @__PURE__ */ new Set([...doc.lines.flatMap((l) => l.kind === "other" ? /^##\s+(.+?)\s*#*\s*$/.exec(l.raw)?.[1] ?? [] : []), ...rules.map((r) => r.section)])];
+  return { hash: contentHash(text), rules, sections };
+}
+async function getRules(root) {
+  const { text, doc } = await load(root);
+  return view(text, doc);
+}
+async function mutateRules(root, baseHash, fn) {
+  const { file, text, doc } = await load(root);
+  if (baseHash !== void 0 && baseHash !== contentHash(text)) {
+    throw conflict("rules.md changed since it was loaded.", "Reload the rules and try again.", { currentHash: contentHash(text) });
+  }
+  let next;
+  try {
+    next = fn(doc);
+  } catch (err) {
+    throw new AthenaError(err.message);
+  }
+  const out = serializeRules(next);
+  const secrets = scanText(out).filter((s) => !scanText(text).some((o) => o.fingerprint === s.fingerprint));
+  if (secrets.length) throw new AthenaError("Refusing to save a rule that appears to contain a secret.", "Rules must never contain credentials.", 1, "unprocessable");
+  await writeFileAtomic(file, out);
+  return view(out, next);
+}
+var rulesAdd = (root, baseHash, section, text) => mutateRules(root, baseHash, (d) => addRule(d, section, text));
+var rulesUpdate = (root, baseHash, index, patch) => mutateRules(root, baseHash, (d) => updateRule(d, index, patch));
+var rulesRemove = (root, baseHash, index) => mutateRules(root, baseHash, (d) => removeRule(d, index));
+
+export {
+  contentHash,
+  listDocs,
+  readDoc,
+  saveDoc,
+  searchDocs,
+  docHistory,
+  docAtRevision,
+  getRules,
+  mutateRules,
+  rulesAdd,
+  rulesUpdate,
+  rulesRemove
+};
+//# sourceMappingURL=chunk-LEMPCNAY.js.map