project-athena 0.3.0 → 0.4.0

package/dist/chunk-UAZLPNVC.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import {
+  CONTEXT_MEMORY_LIMIT,
+  documentSections,
+  listMemory,
+  recall,
+  selectContext
+} from "./chunk-TDNZ2RYA.js";
+import {
+  projectSession
+} from "./chunk-WVQC2EGO.js";
+import {
+  analyzeProject
+} from "./chunk-MPG3IEGB.js";
+import {
+  GRAPH_FILE,
+  buildGraph,
+  saveGraph
+} from "./chunk-SVTEJYMS.js";
+import {
+  KNOWLEDGE_DOCS
+} from "./chunk-FQEGEVLY.js";
+import {
+  athenaDir
+} from "./chunk-2DY4PUR4.js";
+import {
+  readTextIfExists
+} from "./chunk-IQQBAWSM.js";
+import {
+  AthenaError
+} from "./chunk-AD4OZCU2.js";
+
+// src/services/context.ts
+import path from "path";
+async function refreshGraph(root, opts = {}) {
+  const session = projectSession(root);
+  const st = await session.state();
+  const analysis = await analyzeProject(root, { signal: opts.signal });
+  const files = analysis.files.map((f) => f.path);
+  const graph = await buildGraph(analysis.model, {
+    files,
+    signal: opts.signal,
+    read: async (rel) => readTextIfExists(path.join(root, rel)).catch(() => null)
+  });
+  await saveGraph(root, graph);
+  await session.remember(GRAPH_FILE, graph);
+  return graph;
+}
+async function getGraph(root, opts = {}) {
+  const existing = await projectSession(root).graph();
+  if (existing) return existing;
+  return opts.build ? refreshGraph(root, { signal: opts.signal }) : null;
+}
+async function getRelevantContext(root, task, opts = {}) {
+  if (!task.trim()) throw new AthenaError("Describe the task to get relevant context.", 'For example: athena context "add refunds to the payments API"');
+  const dir = athenaDir(root);
+  const documents = [];
+  for (const d of KNOWLEDGE_DOCS) {
+    if (d.id === "rules") continue;
+    const text = await readTextIfExists(path.join(dir, d.file));
+    if (text) documents.push({ id: d.id, file: d.file, sections: documentSections(text) });
+  }
+  if (!documents.length) throw new AthenaError("No knowledge documents found.", "Run `athena init` first.", 3);
+  return selectContext({
+    task,
+    documents,
+    rulesMarkdown: await readTextIfExists(path.join(dir, "rules.md")),
+    graph: await getGraph(root, { build: opts.buildGraph, signal: opts.signal }),
+    maxChars: opts.maxChars,
+    memories: await memoriesFor(root, task)
+  });
+}
+async function memoriesFor(root, task, files = []) {
+  let hits;
+  try {
+    hits = recall(await listMemory(root), { task, files, limit: CONTEXT_MEMORY_LIMIT * 2 });
+  } catch {
+    return [];
+  }
+  const rank = (s) => s === "confirmed" ? 0 : 1;
+  return hits.map((h, i) => ({ h, i })).sort((a, b) => rank(a.h.entry.status) - rank(b.h.entry.status) || a.i - b.i).slice(0, CONTEXT_MEMORY_LIMIT).map(({ h: { entry: e, why } }) => ({
+    id: e.id,
+    kind: e.kind,
+    status: e.status === "confirmed" ? "confirmed" : "unreviewed",
+    label: e.label,
+    stale: e.stale,
+    changedFiles: e.changedFiles,
+    source: e.source,
+    title: e.title,
+    details: e.details,
+    files: e.files,
+    evidence: e.evidence,
+    why
+  }));
+}
+async function graphSummary(root) {
+  const session = projectSession(root);
+  const [graph, hasModel] = await Promise.all([session.graph(), session.hasModel()]);
+  return { built: Boolean(graph), builtAt: graph?.builtAt ?? null, stats: graph?.stats ?? null, model: { hasModel } };
+}
+
+export {
+  refreshGraph,
+  getGraph,
+  getRelevantContext,
+  graphSummary
+};
+//# sourceMappingURL=chunk-UAZLPNVC.js.map

package/dist/chunk-WVQC2EGO.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import {
+  SCAN_FILE,
+  SecurityScan
+} from "./chunk-MPG3IEGB.js";
+import {
+  GRAPH_FILE,
+  ProjectGraph
+} from "./chunk-SVTEJYMS.js";
+import {
+  ProjectModel
+} from "./chunk-QCC4VJUH.js";
+import {
+  athenaDir,
+  readState
+} from "./chunk-2DY4PUR4.js";
+import {
+  AthenaError
+} from "./chunk-AD4OZCU2.js";
+
+// src/services/project-session.ts
+import { promises as fs } from "fs";
+import path from "path";
+var fileKey = (st) => `${st.ino}:${st.size}:${st.mtimeNs}`;
+var ProjectSession = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  cache = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  stateEntry = null;
+  get dir() {
+    return athenaDir(this.root);
+  }
+  /** model.json, or why it can't be used. */
+  readModel() {
+    return this.read("model.json", ProjectModel);
+  }
+  /** The parsed model, or null when missing or unusable. */
+  async model() {
+    const r = await this.readModel();
+    return r.kind === "ok" ? r.value : null;
+  }
+  /** The parsed model; throws an AthenaError with a hint when it is missing or corrupted. */
+  async requireModel() {
+    const r = await this.readModel();
+    if (r.kind === "ok") return r.value;
+    if (r.kind === "missing") throw new AthenaError("model.json is missing.", "Run `athena analyze` (or re-analyze from the overview) first.");
+    throw new AthenaError(`model.json is corrupted (${r.reason}).`, "Run `athena analyze` to rebuild it.");
+  }
+  /** Cheap existence check (a stat, no parsing). */
+  async hasModel() {
+    return this.exists("model.json");
+  }
+  readGraph() {
+    return this.read(GRAPH_FILE, ProjectGraph);
+  }
+  async graph() {
+    const r = await this.readGraph();
+    return r.kind === "ok" ? r.value : null;
+  }
+  readScan() {
+    return this.read(SCAN_FILE, SecurityScan);
+  }
+  async scan() {
+    const r = await this.readScan();
+    return r.kind === "ok" ? r.value : null;
+  }
+  /** state.json via `readState`, memoized like the other artifacts. */
+  async state() {
+    const file = path.join(this.dir, "state.json");
+    const st = await fs.stat(file, { bigint: true }).catch(() => null);
+    if (!st) return readState(this.dir);
+    const key = fileKey(st);
+    if (this.stateEntry?.key === key) return this.stateEntry.state;
+    const state = await readState(this.dir);
+    const after = await fs.stat(file, { bigint: true }).catch(() => null);
+    if (after && fileKey(after) === key) this.stateEntry = { key, state };
+    return state;
+  }
+  /**
+   * Record a value this process just wrote to `.athena/<name>`, so the next
+   * read doesn't parse it again. The file must already be on disk.
+   */
+  async remember(name, value) {
+    const st = await fs.stat(path.join(this.dir, name), { bigint: true }).catch(() => null);
+    if (st) this.cache.set(name, { key: fileKey(st), result: { kind: "ok", value } });
+    else this.cache.delete(name);
+  }
+  /** Drop memoized results (all, or one file). */
+  invalidate(name) {
+    if (!name || name === "state.json") this.stateEntry = null;
+    if (name) this.cache.delete(name);
+    else this.cache.clear();
+  }
+  async exists(name) {
+    const st = await fs.stat(path.join(this.dir, name)).catch(() => null);
+    return Boolean(st?.isFile());
+  }
+  read(name, schema) {
+    const running = this.inflight.get(name);
+    if (running) return running;
+    const p = this.load(name, schema).finally(() => this.inflight.delete(name));
+    this.inflight.set(name, p);
+    return p;
+  }
+  async load(name, schema) {
+    const file = path.join(this.dir, name);
+    let st;
+    try {
+      st = await fs.stat(file, { bigint: true });
+    } catch (err) {
+      const code = err.code;
+      this.cache.delete(name);
+      if (code === "ENOENT" || code === "ENOTDIR") return { kind: "missing" };
+      return { kind: "corrupted", reason: `unreadable (${code})` };
+    }
+    const key = fileKey(st);
+    const hit = this.cache.get(name);
+    if (hit?.key === key) return hit.result;
+    let raw;
+    try {
+      raw = await fs.readFile(file, "utf8");
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return { kind: "missing" };
+      return { kind: "corrupted", reason: `unreadable (${code})` };
+    }
+    const result = parseArtifact(raw, schema);
+    const after = await fs.stat(file, { bigint: true }).catch(() => null);
+    if (after && fileKey(after) === key) this.cache.set(name, { key, result });
+    return result;
+  }
+};
+function parseArtifact(raw, schema) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return { kind: "corrupted", reason: "invalid JSON" };
+  }
+  const parsed = schema.safeParse(json);
+  if (parsed.success) return { kind: "ok", value: parsed.data };
+  const issue = parsed.error.issues[0];
+  return { kind: "corrupted", reason: `schema mismatch at ${issue?.path.map(String).join(".") || "(root)"}: ${issue?.message}` };
+}
+var sessions = /* @__PURE__ */ new Map();
+function projectSession(root) {
+  const key = path.resolve(root);
+  let s = sessions.get(key);
+  if (!s) {
+    s = new ProjectSession(key);
+    sessions.set(key, s);
+  }
+  return s;
+}
+function releaseProjectSession(root) {
+  sessions.delete(path.resolve(root));
+}
+
+export {
+  projectSession,
+  releaseProjectSession
+};
+//# sourceMappingURL=chunk-WVQC2EGO.js.map

package/dist/{chunk-DOQMAZL5.js → chunk-XDCKZ5TV.js}

@@ -33,11 +33,11 @@ import {
 } from "./chunk-XFN7UZCS.js";
 import {
   runPipeline
-} from "./chunk-SJOOXO34.js";
+} from "./chunk-GGXPG6OE.js";
 import {
   ADAPTERS,
   resolveAdapters
-} from "./chunk-2RS6TA3D.js";
+} from "./chunk-YRIS7ZS6.js";
 import {
   KNOWLEDGE_DOCS
 } from "./chunk-FQEGEVLY.js";
@@ -433,4 +433,4 @@ export {
   printSummary,
   summarize
 };
-//# sourceMappingURL=chunk-DOQMAZL5.js.map
+//# sourceMappingURL=chunk-XDCKZ5TV.js.map

package/dist/{chunk-2RS6TA3D.js → chunk-YRIS7ZS6.js}

@@ -12,6 +12,13 @@ import {
   removeJsonHooks,
   stripMcpServers
 } from "./chunk-GHFRQAYT.js";
+import {
+  CLAUDE_HOOK_EVENTS,
+  CODEX_HOOK_EVENTS,
+  COPILOT_HOOK_EVENTS,
+  CURSOR_HOOK_EVENTS,
+  GEMINI_HOOK_EVENTS
+} from "./chunk-INT3IGMQ.js";
 import {
   INTEGRATION_END,
   INTEGRATION_START,
@@ -27,13 +34,6 @@ import {
   readTextIfExists,
   writeFileAtomic
 } from "./chunk-IQQBAWSM.js";
-import {
-  CLAUDE_HOOK_EVENTS,
-  CODEX_HOOK_EVENTS,
-  COPILOT_HOOK_EVENTS,
-  CURSOR_HOOK_EVENTS,
-  GEMINI_HOOK_EVENTS
-} from "./chunk-INT3IGMQ.js";
 import {
   resolveInside
 } from "./chunk-XW3MLHI2.js";
@@ -49,14 +49,16 @@ import path2 from "path";
 function workflowSteps() {
   return [
     "1. Read `.athena/rules.md` and follow every enabled rule (lines marked `[disabled]` do not apply).",
-    "2. Classify the task and read only the relevant Athena documents (see the relevance map below).",
-    "3. Identify the affected modules and architecture boundaries.",
-    "4. Check security implications (`.athena/security.md`, `.athena/auth.md`) when touching input handling, auth, data access or secrets.",
-    "5. Check database and API implications when the change touches schema, queries or endpoints.",
-    "6. For non-trivial work, state a short implementation plan before editing.",
-    "7. Implement only the required changes.",
-    "8. Run the relevant validation (tests, lint, type checks \u2014 commands are listed in `.athena/project.md` and `.athena/testing.md`).",
-    "9. If you changed project structure, dependencies, routes, schema or infrastructure, run `athena sync --dry-run` to see which knowledge is affected, and tell the developer to review it with `athena sync` (apply it yourself only if permitted)."
+    "2. Recall project memory for the task and files: call the Athena `recall` MCP tool, or skim `.athena/memory/` if MCP is unavailable.",
+    "3. Classify the task and read only the relevant Athena documents (see the relevance map below).",
+    "4. Identify the affected modules and architecture boundaries.",
+    "5. Check security implications (`.athena/security.md`, `.athena/auth.md`) when touching input handling, auth, data access or secrets.",
+    "6. Check database and API implications when the change touches schema, queries or endpoints.",
+    "7. For non-trivial work, state a short implementation plan before editing.",
+    "8. Implement only the required changes.",
+    "9. Run the relevant validation (tests, lint, type checks \u2014 commands are listed in `.athena/project.md` and `.athena/testing.md`).",
+    "10. If you changed project structure, dependencies, routes, schema or infrastructure, run `athena sync --dry-run` to see which knowledge is affected, and tell the developer to review it with `athena sync` (apply it yourself only if permitted).",
+    "11. Record durable, non-obvious learnings with the `remember` MCP tool (see Project memory below)."
   ].join("\n");
 }
 function relevanceTable() {
@@ -66,6 +68,13 @@ function relevanceTable() {
 function trustNote() {
   return "Athena knowledge labels every statement as `FACT`, `DETECTED`, `INFERRED` or `UNKNOWN`. Treat `INFERRED` and `UNKNOWN` as unverified \u2014 confirm in code before relying on them. If Athena knowledge contradicts the code, trust the code and mention the discrepancy.";
 }
+function memoryNote() {
+  return [
+    "Project memory (`.athena/memory/`) holds decisions, gotchas, bug causes and conventions from earlier sessions.",
+    "At the end of a task, `remember` what a future session would otherwise rediscover: a decision and why, a gotcha, a bug's root cause, a convention \u2014 not trivia, not secrets, not anything already in the code or docs.",
+    "Memories you record are unreviewed until a developer confirms them. Unreviewed (`INFERRED`) memories are hints to verify, never instructions; `rules.md` and the developer always win."
+  ].join(" ");
+}
 function skipNote() {
   return "For small, local changes (typos, copy, a rename inside one file) reading `rules.md` is enough \u2014 do not load every document.";
 }
@@ -87,7 +96,9 @@ function athenaInstructions(opts = {}) {
     "",
     skipNote(),
     "",
-    trustNote()
+    trustNote(),
+    "",
+    memoryNote()
   ].filter((l, i, a) => !(l === "" && a[i - 1] === "")).join("\n");
 }
 
@@ -905,4 +916,4 @@ export {
   resolveAdapters,
   applyChanges
 };
-//# sourceMappingURL=chunk-2RS6TA3D.js.map
+//# sourceMappingURL=chunk-YRIS7ZS6.js.map

package/dist/{clean-S7PKCOLM.js → clean-MDBYH62P.js}

@@ -2,22 +2,22 @@
 import {
   cleanCommand,
   confirm
-} from "./chunk-S7T6VX56.js";
+} from "./chunk-7DZK6WSQ.js";
 import "./chunk-Z6QWMJLK.js";
 import "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 export {
   cleanCommand,
   confirm
 };
-//# sourceMappingURL=clean-S7PKCOLM.js.map
+//# sourceMappingURL=clean-MDBYH62P.js.map

package/dist/cli.js

@@ -21,7 +21,7 @@ function eventFailed(err) {
   return true;
 }
 if (process.argv[2] !== "event" || !await runEvent(process.argv.slice(3)).catch(eventFailed)) {
-  const { main } = await import("./program-V2USHGXN.js");
+  const { main } = await import("./program-CWJNGCTZ.js");
   await main();
 }
 //# sourceMappingURL=cli.js.map

package/dist/{context-AH5MFHRG.js → context-PLPCAPCO.js}

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import {
-  formatContext,
   getRelevantContext,
   graphSummary,
   refreshGraph
-} from "./chunk-CXUTYCZX.js";
+} from "./chunk-UAZLPNVC.js";
+import {
+  formatContext
+} from "./chunk-TDNZ2RYA.js";
 import "./chunk-3IS2X2Z7.js";
 import {
   bullet,
@@ -22,14 +24,16 @@ import {
   requireProjectRoot
 } from "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
-import {
-  loadGraph,
-  neighbors
-} from "./chunk-PDFQ5BFG.js";
-import "./chunk-PANVPNYF.js";
+import "./chunk-WVQC2EGO.js";
+import "./chunk-MPG3IEGB.js";
 import "./chunk-ELKFRTZT.js";
 import "./chunk-PVCIGUIT.js";
 import "./chunk-OLPSEQS5.js";
+import {
+  loadGraph,
+  neighbors
+} from "./chunk-SVTEJYMS.js";
+import "./chunk-QCC4VJUH.js";
 import "./chunk-JCGDR4UV.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
@@ -70,11 +74,21 @@ async function contextCommand(task, opts) {
     for (const n of ctx.graphNodes.slice(0, 12)) line(`  ${dim(`${n.kind}:`)} ${n.name}${n.path ? dim(` (${n.path})`) : ""}`);
     if (ctx.graphNodes.length > 12) line(dim(`  +${ctx.graphNodes.length - 12} more`));
   }
+  if (ctx.memories.length) {
+    line();
+    heading("Project memory");
+    for (const m of ctx.memories) {
+      const label = m.label === "FACT" ? c.green(m.label) : c.yellow(m.label);
+      line(`  ${label} ${m.title} ${dim(`(${m.id}, ${m.kind}${m.status === "unreviewed" ? ", unreviewed" : ""}${m.stale ? ", stale" : ""})`)}`);
+      line(dim(`    ${m.why.join("; ")}`));
+    }
+    if (ctx.memories.some((m) => m.status === "unreviewed")) line(dim("  Unreviewed memories were written by an agent; confirm or forget them with `athena memory`."));
+  }
   line();
   heading("Sections selected");
   for (const s of ctx.sections) line(`  ${dim(`${s.file} \u2192`)} ${s.section}`);
   line();
-  line(dim(`${ctx.sections.length} sections \xB7 ~${ctx.approxChars} characters \xB7 ${ctx.rules.length} rules${ctx.truncated ? " \xB7 some sections omitted for budget" : ""}`));
+  line(dim(`${ctx.sections.length} sections \xB7 ${ctx.memories.length} memories \xB7 ~${ctx.approxChars} characters \xB7 ${ctx.rules.length} rules${ctx.truncated ? " \xB7 some content omitted for budget" : ""}`));
   line(dim("Use --full to print the context an agent would read, or --json for tooling."));
 }
 async function graphCommand(opts) {
@@ -144,4 +158,4 @@ export {
   contextCommand,
   graphCommand
 };
-//# sourceMappingURL=context-AH5MFHRG.js.map
+//# sourceMappingURL=context-PLPCAPCO.js.map

package/dist/{doctor-RSJMLE2P.js → doctor-BX677KRE.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   runDoctor
-} from "./chunk-PR53DT7I.js";
+} from "./chunk-3XSDI5WF.js";
 import "./chunk-RXNRMIZP.js";
 import "./chunk-VSYBC3VY.js";
-import "./chunk-3IS2X2Z7.js";
 import "./chunk-65TSRDQ3.js";
+import "./chunk-3IS2X2Z7.js";
 import {
   c,
   dim,
@@ -23,21 +23,28 @@ import "./chunk-2R6PXY6Z.js";
 import "./chunk-PVCIGUIT.js";
 import "./chunk-OLPSEQS5.js";
 import "./chunk-JCGDR4UV.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 
 // src/cli/commands/doctor.ts
 async function doctorCommand(opts) {
   const cwd = await resolveCwd(opts);
-  const { checks } = await runDoctor(cwd);
+  const { checks, root } = await runDoctor(cwd);
+  if (root) {
+    const m = await (await import("./memory-VSVNLEJC.js")).memorySummary(root);
+    if (m?.total) {
+      const pending = [m.unreviewed ? `${m.unreviewed} unreviewed` : "", m.stale ? `${m.stale} stale` : ""].filter(Boolean);
+      checks.push({ area: "Memory", level: "info", message: `${m.total} project memory ${m.total === 1 ? "entry" : "entries"}${pending.length ? ` (${pending.join(", ")})` : ""}`, hint: pending.length ? "Review with `athena memory review` and `athena memory stale`." : void 0 });
+    }
+  }
   const errors = checks.filter((c2) => c2.level === "error").length;
   if (isJson()) {
     json({ ok: errors === 0, checks });
@@ -59,4 +66,4 @@ async function doctorCommand(opts) {
 export {
   doctorCommand
 };
-//# sourceMappingURL=doctor-RSJMLE2P.js.map
+//# sourceMappingURL=doctor-BX677KRE.js.map

package/dist/{init-2V34DVRQ.js → init-WQCAOJ2R.js}

@@ -5,26 +5,27 @@ import {
   printSummary,
   runWithProgress,
   summarize
-} from "./chunk-DOQMAZL5.js";
+} from "./chunk-XDCKZ5TV.js";
 import "./chunk-SHKXELUX.js";
 import "./chunk-Z6QWMJLK.js";
 import "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
-import "./chunk-SJOOXO34.js";
-import "./chunk-PANVPNYF.js";
+import "./chunk-GGXPG6OE.js";
+import "./chunk-MPG3IEGB.js";
 import "./chunk-ELKFRTZT.js";
 import "./chunk-2R6PXY6Z.js";
 import "./chunk-PVCIGUIT.js";
 import "./chunk-OLPSEQS5.js";
+import "./chunk-QCC4VJUH.js";
 import "./chunk-JCGDR4UV.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 export {
@@ -34,4 +35,4 @@ export {
   runWithProgress,
   summarize
 };
-//# sourceMappingURL=init-2V34DVRQ.js.map
+//# sourceMappingURL=init-WQCAOJ2R.js.map