project-athena 0.2.0 → 0.3.0

package/dist/chunk-TGJUUB44.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+import {
+  projectSession
+} from "./chunk-PDFQ5BFG.js";
+import {
+  impactOf
+} from "./chunk-GR4DL2VM.js";
+import {
+  composeState,
+  ensureRules,
+  indexWithIntegrations,
+  planKnowledge,
+  writePlannedKnowledge
+} from "./chunk-SJOOXO34.js";
+import {
+  analyzeProject
+} from "./chunk-PANVPNYF.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-TGJUUB44.js.map

package/dist/chunk-VSYBC3VY.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// src/services/which.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function whichExecutable(command) {
+  if (command.includes("/") || command.includes("\\")) {
+    return await fs.access(command).then(() => true).catch(() => false) ? command : null;
+  }
+  const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, command + ext.toLowerCase());
+      try {
+        const st = await fs.stat(candidate);
+        if (st.isFile()) return candidate;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+
+export {
+  whichExecutable
+};
+//# sourceMappingURL=chunk-VSYBC3VY.js.map

package/dist/chunk-XB66PZ6Z.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import {
+  planSnapshot,
+  planSync
+} from "./chunk-TGJUUB44.js";
+
+// src/services/scheduler.ts
+var DEFAULT_FULL_WALK_EVERY_MS = 5 * 6e4;
+function abortError() {
+  const e = new Error("The analysis was cancelled.");
+  e.name = "AbortError";
+  return e;
+}
+var defaultPlanner = async (root, input) => {
+  const plan = await planSync(root, { signal: input.signal, incremental: input.incremental });
+  return { plan, snapshot: planSnapshot(plan)?.snapshot ?? null };
+};
+var AnalysisScheduler = class {
+  constructor(root, opts = {}) {
+    this.root = root;
+    this.planner = opts.planner ?? defaultPlanner;
+    this.maxConsecutiveAborts = opts.maxConsecutiveAborts ?? 2;
+    this.fullWalkEveryMs = opts.fullWalkEveryMs ?? DEFAULT_FULL_WALK_EVERY_MS;
+  }
+  root;
+  hooks = {};
+  planner;
+  maxConsecutiveAborts;
+  fullWalkEveryMs;
+  current = null;
+  next = null;
+  /** Serializes runs and exclusive writers. */
+  lock = Promise.resolve();
+  closed = false;
+  consecutiveAborts = 0;
+  // Change tracking (incremental analysis).
+  tracking = false;
+  /** What the tracker (watcher) was set up with: a walk made under other ignore rules is not trusted. */
+  guard = null;
+  epoch = 0;
+  noted = /* @__PURE__ */ new Set();
+  baseline = null;
+  forceFullNext = false;
+  /** Counters (tests, diagnostics). */
+  stats = { runs: 0, aborted: 0, incremental: 0, coalesced: 0 };
+  get busy() {
+    return this.current !== null;
+  }
+  /**
+   * Turn change tracking on (a watcher that is ready and will report every change)
+   * or off. Either way the baseline is dropped: the next run walks the whole tree.
+   */
+  setTracking(on, guard) {
+    this.tracking = on;
+    this.guard = on ? guard ?? null : null;
+    this.resetBaseline();
+  }
+  /** Forget the previous walk (watcher error, missed events): the next run walks the whole tree. */
+  resetBaseline() {
+    this.epoch++;
+    this.baseline = null;
+    this.noted.clear();
+  }
+  /** Record changed paths without requesting a plan (a watcher calls this on every event). */
+  noteChanges(paths) {
+    for (const p of paths) this.noted.add(p);
+  }
+  /** Request a plan. Resolves with the plan of the run that covers this request. */
+  request(req) {
+    if (this.closed) return Promise.reject(abortError());
+    if (req.paths?.length) this.noteChanges(req.paths);
+    if (req.full) this.forceFullNext = true;
+    return new Promise((resolve, reject) => {
+      const waiter = { resolve, reject };
+      if (!this.current) {
+        const run = this.newRun(req.reason);
+        run.waiters.push(waiter);
+        this.start(run);
+        return;
+      }
+      this.stats.coalesced++;
+      if (this.current.phase === "queued" && !this.current.superseded) {
+        this.current.reasons.push(req.reason);
+        this.current.waiters.push(waiter);
+        return;
+      }
+      if (!this.next) this.next = this.newRun(req.reason);
+      else this.next.reasons.push(req.reason);
+      this.next.waiters.push(waiter);
+      const cur = this.current;
+      if (req.supersede && (req.paths?.length || this.noted.size) && cur.phase === "planning" && !cur.superseded && this.consecutiveAborts < this.maxConsecutiveAborts) {
+        cur.superseded = true;
+        this.consecutiveAborts++;
+        this.stats.aborted++;
+        this.next.waiters.unshift(...cur.waiters.splice(0));
+        cur.controller.abort();
+      }
+    });
+  }
+  /**
+   * Run `fn` with no plan in flight; plans requested meanwhile wait for it.
+   * For writers (apply, full analysis) that must not interleave with planning.
+   */
+  exclusive(fn) {
+    const result = this.lock.then(fn);
+    this.lock = result.catch(() => {
+    });
+    return result;
+  }
+  /** Abort everything and reject pending requests. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    const err = abortError();
+    for (const run of [this.current, this.next]) {
+      if (!run) continue;
+      run.superseded = true;
+      for (const w of run.waiters.splice(0)) w.reject(err);
+      run.controller.abort();
+    }
+    this.next = null;
+  }
+  newRun(reason) {
+    return { reasons: [reason], waiters: [], controller: new AbortController(), phase: "queued", superseded: false, claimed: [], forceFull: false };
+  }
+  start(run) {
+    this.current = run;
+    const task = this.lock.then(() => this.execute(run));
+    this.lock = task.catch(() => {
+    });
+  }
+  /** The run is over: free the slot (starting the follow-up), then settle its waiters. */
+  finish(run, outcome) {
+    if (this.current === run) this.current = null;
+    const next = this.next;
+    this.next = null;
+    if (next && !this.closed) this.start(next);
+    for (const w of run.waiters.splice(0)) {
+      if ("plan" in outcome) w.resolve(outcome.plan);
+      else w.reject(outcome.error);
+    }
+  }
+  async execute(run) {
+    if (run.superseded || this.closed) {
+      this.finish(run, { error: abortError() });
+      return;
+    }
+    this.stats.runs++;
+    const epoch = this.epoch;
+    run.claimed = [...this.noted];
+    this.noted.clear();
+    run.forceFull = this.forceFullNext;
+    this.forceFullNext = false;
+    const base = this.baseline;
+    const guard = this.guard;
+    const useIncremental = this.tracking && !run.forceFull && base !== null && base.epoch === epoch && Date.now() - base.snapshot.takenAt < this.fullWalkEveryMs && (!guard || guard.configHash === base.snapshot.configHash && guard.excludeText === base.snapshot.excludeText);
+    const info = { reason: run.reasons.join(","), paths: run.claimed, incremental: useIncremental };
+    run.phase = "planning";
+    try {
+      this.hooks.onStart?.(info);
+      const out = await this.planner(this.root, {
+        signal: run.controller.signal,
+        incremental: useIncremental ? { snapshot: base.snapshot, changedPaths: run.claimed } : void 0
+      });
+      run.controller.signal.throwIfAborted();
+      if (useIncremental && out.snapshot?.takenAt === base.snapshot.takenAt) this.stats.incremental++;
+      if (this.tracking && out.snapshot && this.epoch === epoch) this.baseline = { snapshot: out.snapshot, epoch };
+      run.phase = "finishing";
+      await this.hooks.onPlan?.(out.plan, info);
+      this.consecutiveAborts = 0;
+      this.finish(run, { plan: out.plan });
+    } catch (err) {
+      if (this.epoch === epoch) for (const p of run.claimed) this.noted.add(p);
+      this.finish(run, { error: run.superseded ? abortError() : err });
+    }
+  }
+};
+
+export {
+  AnalysisScheduler
+};
+//# sourceMappingURL=chunk-XB66PZ6Z.js.map

package/dist/chunk-XFN7UZCS.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import {
+  findProjectRoot
+} from "./chunk-KBO7XRBW.js";
+import {
+  AthenaError,
+  EXIT
+} from "./chunk-AD4OZCU2.js";
+
+// src/cli/context.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function resolveCwd(opts) {
+  const dir = path.resolve(opts.cwd ?? process.cwd());
+  try {
+    const st = await fs.stat(dir);
+    if (!st.isDirectory()) throw new AthenaError(`Not a directory: ${dir}`);
+    return await fs.realpath(dir);
+  } catch (err) {
+    if (err instanceof AthenaError) throw err;
+    throw new AthenaError(`Directory not accessible: ${dir}`, "Check the path and your permissions.");
+  }
+}
+async function requireProjectRoot(opts) {
+  const cwd = await resolveCwd(opts);
+  const root = await findProjectRoot(cwd);
+  if (!root) throw new AthenaError("Athena is not initialized in this project.", "Run `athena init` in the project root.", EXIT.NOT_INITIALIZED);
+  return root;
+}
+
+export {
+  resolveCwd,
+  requireProjectRoot
+};
+//# sourceMappingURL=chunk-XFN7UZCS.js.map

package/dist/chunk-XW3MLHI2.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+// src/core/util/paths.ts
+import path from "path";
+function toPosix(p) {
+  return p.split(path.sep).join("/").replace(/\\/g, "/");
+}
+function resolveInside(root, candidate) {
+  if (candidate.includes("\0")) return null;
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, candidate);
+  const rel = path.relative(resolvedRoot, resolved);
+  if (rel === "") return resolved;
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return resolved;
+}
+function dirOf(posixPath) {
+  const i = posixPath.lastIndexOf("/");
+  return i === -1 ? "." : posixPath.slice(0, i);
+}
+function baseName(posixPath) {
+  const i = posixPath.lastIndexOf("/");
+  return i === -1 ? posixPath : posixPath.slice(i + 1);
+}
+
+export {
+  toPosix,
+  resolveInside,
+  dirOf,
+  baseName
+};
+//# sourceMappingURL=chunk-XW3MLHI2.js.map