project-athena 0.2.0 → 0.3.0

package/dist/chunk-RXNRMIZP.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import {
+  readLocalConfig
+} from "./chunk-PVCIGUIT.js";
+import {
+  redact,
+  scanText
+} from "./chunk-JCGDR4UV.js";
+import {
+  KNOWLEDGE_DOCS
+} from "./chunk-FQEGEVLY.js";
+import {
+  athenaDir,
+  loadConfig
+} from "./chunk-2DY4PUR4.js";
+import {
+  readTextIfExists,
+  writeFileAtomic
+} from "./chunk-IQQBAWSM.js";
+import {
+  AthenaError
+} from "./chunk-AD4OZCU2.js";
+
+// src/services/ai.ts
+import os from "os";
+import path from "path";
+import { z as z2 } from "zod";
+
+// src/ai/provider.ts
+import { z } from "zod";
+var AiConfig = z.object({
+  provider: z.enum(["anthropic", "openai", "google", "ollama"]).default("anthropic"),
+  model: z.string().optional(),
+  /** cloud: a hosted API · local: a model on this machine (Ollama). */
+  mode: z.enum(["cloud", "local"]).default("cloud"),
+  /** Must be true (or --consent passed) before any project content leaves the machine. */
+  consent: z.boolean().default(false),
+  /** Upper bound on characters of knowledge sent in one request. */
+  maxChars: z.number().int().min(500).max(2e5).default(24e3),
+  /**
+   * Ollama base URL, or a custom compatible endpoint. Only ever set from a trusted,
+   * machine-local source (see resolveAiConfig in src/services/ai.ts) — never from the
+   * committed .athena/config.json, which anyone with push access controls.
+   */
+  baseUrl: z.string().optional(),
+  /** Where baseUrl came from. Providers refuse a baseUrl without a trusted source. */
+  baseUrlSource: z.enum(["env", "local", "user"]).optional()
+});
+var AiError = class extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.hint = hint;
+    this.name = "AiError";
+  }
+  hint;
+};
+function isLoopbackUrl(url) {
+  try {
+    const host = new URL(url).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost" || host === "::1" || host === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function providerBase(config, fallback) {
+  if (!config.baseUrl) return fallback;
+  if (!config.baseUrlSource) {
+    throw new AiError("Refusing to use an AI base URL that did not come from a trusted source.", 'Set ATHENA_AI_BASE_URL, or "ai.baseUrl" in .athena/local.json or your user config.');
+  }
+  return config.baseUrl.replace(/\/+$/, "");
+}
+async function postJson(url, body, headers, req) {
+  const timeout = AbortSignal.timeout(req.timeoutMs ?? 12e4);
+  const signal = req.signal ? AbortSignal.any([req.signal, timeout]) : timeout;
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body), signal });
+  } catch (err) {
+    throw new AiError(`Could not reach ${new URL(url).host}: ${err.message}`);
+  }
+  const text = await res.text();
+  if (!res.ok) {
+    const detail = text.slice(0, 300);
+    throw new AiError(`${new URL(url).host} returned ${res.status}`, detail || void 0);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new AiError("Provider returned a non-JSON response");
+  }
+}
+function envKey(name) {
+  return name ? process.env[name]?.trim() || void 0 : void 0;
+}
+
+// src/ai/providers.ts
+var str = (v) => typeof v === "string" ? v : "";
+function keyAvailability(provider, endpoint) {
+  const key = envKey(provider.keyEnvVar);
+  return key ? { ok: true, endpoint, keyEnvVar: provider.keyEnvVar } : { ok: false, reason: `${provider.keyEnvVar} is not set`, endpoint, keyEnvVar: provider.keyEnvVar };
+}
+var anthropicProvider = {
+  id: "anthropic",
+  name: "Anthropic (Claude)",
+  remote: true,
+  defaultModel: "claude-sonnet-5",
+  keyEnvVar: "ANTHROPIC_API_KEY",
+  async available(config) {
+    return keyAvailability(anthropicProvider, providerBase(config, "https://api.anthropic.com"));
+  },
+  async complete(config, req) {
+    const key = envKey(anthropicProvider.keyEnvVar);
+    if (!key) throw new AiError("ANTHROPIC_API_KEY is not set");
+    const model = config.model ?? anthropicProvider.defaultModel;
+    const json = await postJson(
+      `${providerBase(config, "https://api.anthropic.com")}/v1/messages`,
+      { model, max_tokens: req.maxTokens ?? 2e3, system: req.system, messages: [{ role: "user", content: req.prompt }] },
+      { "x-api-key": key, "anthropic-version": "2023-06-01" },
+      req
+    );
+    const content = Array.isArray(json.content) ? json.content : [];
+    const text = content.map((c) => c && typeof c === "object" ? str(c.text) : "").join("");
+    const usage = json.usage ?? {};
+    return { text, model: str(json.model) || model, provider: "anthropic", usage: { inputTokens: usage.input_tokens, outputTokens: usage.output_tokens } };
+  }
+};
+var openaiProvider = {
+  id: "openai",
+  name: "OpenAI",
+  remote: true,
+  defaultModel: "gpt-4.1-mini",
+  keyEnvVar: "OPENAI_API_KEY",
+  async available(config) {
+    return keyAvailability(openaiProvider, providerBase(config, "https://api.openai.com"));
+  },
+  async complete(config, req) {
+    const key = envKey(openaiProvider.keyEnvVar);
+    if (!key) throw new AiError("OPENAI_API_KEY is not set");
+    const model = config.model ?? openaiProvider.defaultModel;
+    const json = await postJson(
+      `${providerBase(config, "https://api.openai.com")}/v1/chat/completions`,
+      { model, max_completion_tokens: req.maxTokens ?? 2e3, messages: [{ role: "system", content: req.system }, { role: "user", content: req.prompt }] },
+      { authorization: `Bearer ${key}` },
+      req
+    );
+    const choices = Array.isArray(json.choices) ? json.choices : [];
+    const first = choices[0] ?? {};
+    const message = first.message ?? {};
+    const usage = json.usage ?? {};
+    return { text: str(message.content), model: str(json.model) || model, provider: "openai", usage: { inputTokens: usage.prompt_tokens, outputTokens: usage.completion_tokens } };
+  }
+};
+var googleProvider = {
+  id: "google",
+  name: "Google (Gemini)",
+  remote: true,
+  defaultModel: "gemini-2.5-flash",
+  keyEnvVar: "GEMINI_API_KEY",
+  async available(config) {
+    const key = envKey("GEMINI_API_KEY") ?? envKey("GOOGLE_API_KEY");
+    const endpoint = providerBase(config, "https://generativelanguage.googleapis.com");
+    return key ? { ok: true, endpoint, keyEnvVar: "GEMINI_API_KEY" } : { ok: false, reason: "GEMINI_API_KEY (or GOOGLE_API_KEY) is not set", endpoint, keyEnvVar: "GEMINI_API_KEY" };
+  },
+  async complete(config, req) {
+    const key = envKey("GEMINI_API_KEY") ?? envKey("GOOGLE_API_KEY");
+    if (!key) throw new AiError("GEMINI_API_KEY is not set");
+    const model = config.model ?? googleProvider.defaultModel;
+    const json = await postJson(
+      `${providerBase(config, "https://generativelanguage.googleapis.com")}/v1beta/models/${encodeURIComponent(model)}:generateContent`,
+      { systemInstruction: { parts: [{ text: req.system }] }, contents: [{ role: "user", parts: [{ text: req.prompt }] }], generationConfig: { maxOutputTokens: req.maxTokens ?? 2e3 } },
+      { "x-goog-api-key": key },
+      req
+    );
+    const candidates = Array.isArray(json.candidates) ? json.candidates : [];
+    const parts = candidates[0]?.content?.parts;
+    const text = Array.isArray(parts) ? parts.map((p) => str(p.text)).join("") : "";
+    return { text, model, provider: "google" };
+  }
+};
+var ollamaProvider = {
+  id: "ollama",
+  name: "Ollama (local)",
+  remote: false,
+  defaultModel: "llama3.1",
+  async available(config) {
+    const endpoint = ollamaEndpoint(config);
+    try {
+      const res = await fetch(`${endpoint}/api/tags`, { signal: AbortSignal.timeout(2e3) });
+      if (!res.ok) return { ok: false, reason: `Ollama responded ${res.status}`, endpoint };
+      const json = await res.json();
+      const models = (json.models ?? []).map((m) => m.name).filter(Boolean);
+      return models.length ? { ok: true, endpoint } : { ok: false, reason: "Ollama is running but has no models pulled (try `ollama pull llama3.1`)", endpoint };
+    } catch {
+      return { ok: false, reason: "Ollama is not reachable (start it with `ollama serve`)", endpoint };
+    }
+  },
+  async complete(config, req) {
+    const endpoint = ollamaEndpoint(config);
+    const model = config.model ?? ollamaProvider.defaultModel;
+    const json = await postJson(
+      `${endpoint}/api/chat`,
+      { model, stream: false, options: { num_predict: req.maxTokens ?? 2e3 }, messages: [{ role: "system", content: req.system }, { role: "user", content: req.prompt }] },
+      {},
+      req
+    );
+    const message = json.message ?? {};
+    return { text: str(message.content), model, provider: "ollama" };
+  }
+};
+function ollamaEndpoint(config) {
+  const env = process.env.OLLAMA_HOST?.trim();
+  const fromEnv = env ? /^https?:\/\//i.test(env) ? env : `http://${env}` : void 0;
+  return providerBase(config, fromEnv ?? "http://127.0.0.1:11434").replace(/\/+$/, "");
+}
+function isRemote(provider, config) {
+  if (provider.id === "ollama") return !isLoopbackUrl(ollamaEndpoint(config));
+  return provider.remote;
+}
+var PROVIDERS = [anthropicProvider, openaiProvider, googleProvider, ollamaProvider];
+function getProvider(id) {
+  const p = PROVIDERS.find((x) => x.id === id);
+  if (!p) throw new AiError(`Unknown AI provider: ${id}`, `Supported: ${PROVIDERS.map((x) => x.id).join(", ")}`);
+  return p;
+}
+
+// src/services/ai.ts
+var SUGGESTIONS_FILE = "ai-suggestions.md";
+var TrustedAi = z2.object({ baseUrl: z2.string().optional(), consent: z2.boolean().optional() });
+function userConfigPath(env = process.env, platform = process.platform) {
+  if (platform === "win32") {
+    const base2 = env.APPDATA?.trim() || path.join(os.homedir(), "AppData", "Roaming");
+    return path.win32.join(base2, "athena", "config.json");
+  }
+  const base = env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+  return path.join(base, "athena", "config.json");
+}
+async function readUserAi() {
+  const text = await readTextIfExists(userConfigPath()).catch(() => null);
+  if (!text) return {};
+  try {
+    const parsed = TrustedAi.safeParse(JSON.parse(text)?.ai ?? {});
+    return parsed.success ? parsed.data : {};
+  } catch {
+    return {};
+  }
+}
+function envConsent() {
+  const v = process.env.ATHENA_AI_CONSENT?.trim().toLowerCase();
+  if (!v) return void 0;
+  if (v === "1" || v === "true") return true;
+  if (v === "0" || v === "false") return false;
+  return void 0;
+}
+function validBaseUrl(raw) {
+  const v = raw?.trim();
+  if (!v) return void 0;
+  try {
+    const u = new URL(v);
+    return u.protocol === "http:" || u.protocol === "https:" ? v.replace(/\/+$/, "") : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var MOVE_AI_HINT = 'Set ATHENA_AI_BASE_URL / ATHENA_AI_CONSENT=1, or put them under "ai" in .athena/local.json (gitignored) or ~/.config/athena/config.json.';
+async function committedAiWarning(root) {
+  const { config } = await loadConfig(root);
+  const ignored = [config.ai?.baseUrl !== void 0 ? "ai.baseUrl" : "", config.ai?.consent !== void 0 ? "ai.consent" : ""].filter(Boolean);
+  if (!ignored.length) return void 0;
+  return `Ignoring ${ignored.join(" and ")} in .athena/config.json: that file is committed, so anyone who can push to the repository could redirect your API key and knowledge. ${MOVE_AI_HINT}`;
+}
+async function resolveAiConfig(root) {
+  const { config } = await loadConfig(root);
+  const warnings = [];
+  const committedWarning = await committedAiWarning(root);
+  if (committedWarning) warnings.push(committedWarning);
+  const { baseUrl: _ignoredUrl, consent: _ignoredConsent, ...committed } = config.ai ?? {};
+  const local = (await readLocalConfig(root)).ai ?? {};
+  const user = await readUserAi();
+  let baseUrl;
+  let baseUrlSource;
+  const candidates = [
+    ["env", process.env.ATHENA_AI_BASE_URL, "ATHENA_AI_BASE_URL"],
+    ["local", local.baseUrl, ".athena/local.json"],
+    ["user", user.baseUrl, userConfigPath()]
+  ];
+  for (const [source, raw, where] of candidates) {
+    if (!raw?.trim()) continue;
+    const url = validBaseUrl(raw);
+    if (!url) {
+      warnings.push(`Ignoring the AI base URL from ${where}: it must be an http(s) URL.`);
+      continue;
+    }
+    baseUrl = url;
+    baseUrlSource = source;
+    break;
+  }
+  let consent = false;
+  let consentSource;
+  for (const [source, value] of [["env", envConsent()], ["local", local.consent], ["user", user.consent]]) {
+    if (value === void 0) continue;
+    consent = value;
+    consentSource = value ? source : void 0;
+    break;
+  }
+  const cfg = AiConfig.parse({ ...committed, consent, ...baseUrl ? { baseUrl, baseUrlSource } : {} });
+  return { config: cfg, consentSource, warnings };
+}
+async function aiConfig(root) {
+  return (await resolveAiConfig(root)).config;
+}
+async function aiStatus(root) {
+  const { config: cfg, consentSource, warnings } = await resolveAiConfig(root);
+  const providers = [];
+  for (const p of PROVIDERS) providers.push({ id: p.id, name: p.name, remote: isRemote(p, cfg), defaultModel: p.defaultModel, keyEnvVar: p.keyEnvVar, availability: await p.available(cfg), selected: p.id === cfg.provider });
+  return { configured: cfg, providers, consent: cfg.consent, consentSource, warnings };
+}
+async function buildEnrichPayload(root, opts = {}) {
+  const { config: cfg, warnings } = await resolveAiConfig(root);
+  const provider = getProvider(cfg.provider);
+  const wanted = opts.docs?.length ? opts.docs : ["project", "architecture", "database", "api"];
+  const parts = [];
+  const included = [];
+  for (const id of wanted) {
+    const doc = KNOWLEDGE_DOCS.find((d) => d.id === id);
+    if (!doc) throw new AthenaError(`Unknown document: ${id}`, `Available: ${KNOWLEDGE_DOCS.map((d) => d.id).join(", ")}`);
+    const text = await readTextIfExists(path.join(athenaDir(root), doc.file));
+    if (!text) continue;
+    included.push(doc.file);
+    parts.push(`--- ${doc.file} ---
+${text.replace(/<!--[\s\S]*?-->/g, "").trim()}`);
+  }
+  if (!included.length) throw new AthenaError("No knowledge documents to send.", "Run `athena init` first.", 3);
+  let content = redact(parts.join("\n\n"));
+  if (content.length > cfg.maxChars) content = `${content.slice(0, cfg.maxChars)}
+
+[truncated to ${cfg.maxChars} characters]`;
+  const leftover = scanText(content);
+  if (leftover.length) throw new AthenaError("Refusing to send: the knowledge still contains values that look like secrets.", "Fix them in .athena/*.md first.");
+  const availability = await provider.available(cfg);
+  return { content, chars: content.length, documents: included, provider, endpoint: availability.endpoint, remote: isRemote(provider, cfg), model: cfg.model ?? provider.defaultModel, warnings };
+}
+var SYSTEM = [
+  "You help maintain a project knowledge base for AI coding agents.",
+  "You will be given generated documentation about a software project.",
+  "Suggest concise, high-value additions a developer might record: the project purpose, architectural decisions worth documenting, risky areas, and candidate project rules.",
+  "Rules: never invent facts that are not supported by the provided material; where you are unsure, say what is unknown and what would confirm it; do not restate the documents; no code.",
+  'Output GitHub-flavoured Markdown with these sections: "## Suggested project summary", "## Questions Athena could not answer", "## Candidate rules" (as a bullet list).'
+].join(" ");
+async function enrich(root, opts = {}) {
+  const cfg = await aiConfig(root);
+  const payload = await buildEnrichPayload(root, { docs: opts.docs });
+  const availability = await payload.provider.available(cfg);
+  if (!availability.ok) throw new AthenaError(`${payload.provider.name} is not available: ${availability.reason}`, payload.provider.keyEnvVar ? `Set ${payload.provider.keyEnvVar}, or choose another provider in .athena/config.json.` : void 0);
+  if (payload.remote && !cfg.consent && !opts.consent) {
+    throw new AthenaError(
+      `Sending project knowledge to ${payload.endpoint} requires consent.`,
+      'Re-run with `athena ai enrich --consent`, set ATHENA_AI_CONSENT=1, or set "ai": { "consent": true } in .athena/local.json (machine-local, gitignored). Use a local Ollama to keep everything on this machine.'
+    );
+  }
+  let result;
+  try {
+    result = await payload.provider.complete(cfg, { system: SYSTEM, prompt: payload.content, maxTokens: 2e3, signal: opts.signal });
+  } catch (err) {
+    if (err instanceof AiError) throw new AthenaError(err.message, err.hint);
+    throw err;
+  }
+  const body = redact(result.text.trim());
+  if (!body) throw new AthenaError("The provider returned an empty response.");
+  const markdown = [
+    "# AI suggestions (INFERRED \u2014 not project knowledge)",
+    "",
+    `> Generated ${(/* @__PURE__ */ new Date()).toISOString()} by ${result.provider} (${result.model}) from ${payload.documents.join(", ")}.`,
+    ">",
+    "> **Status: INFERRED.** Nothing here was verified against the code. Move anything useful into a document's Developer Notes or `rules.md` yourself; Athena will not do it for you.",
+    "",
+    body,
+    ""
+  ].join("\n");
+  const file = path.join(athenaDir(root), SUGGESTIONS_FILE);
+  await writeFileAtomic(file, markdown);
+  return { markdown, file: SUGGESTIONS_FILE, provider: result.provider, model: result.model, chars: payload.chars, documents: payload.documents };
+}
+
+export {
+  committedAiWarning,
+  aiStatus,
+  buildEnrichPayload,
+  enrich
+};
+//# sourceMappingURL=chunk-RXNRMIZP.js.map

package/dist/chunk-S7T6VX56.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import {
+  c,
+  dim,
+  isJson,
+  json,
+  line,
+  ok
+} from "./chunk-Z6QWMJLK.js";
+import {
+  requireProjectRoot
+} from "./chunk-XFN7UZCS.js";
+import {
+  ADAPTERS
+} from "./chunk-2RS6TA3D.js";
+import {
+  athenaDir
+} from "./chunk-2DY4PUR4.js";
+import {
+  AthenaError
+} from "./chunk-AD4OZCU2.js";
+
+// src/cli/commands/clean.ts
+import { promises as fs } from "fs";
+import { createInterface } from "readline/promises";
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question} ${dim("[y/N]")} `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+async function cleanCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  if (!opts.yes) {
+    if (!process.stdin.isTTY) throw new AthenaError("Refusing to delete .athena/ without confirmation.", "Re-run with --yes in non-interactive environments.");
+    line(`This removes ${c.bold(".athena/")} (including rules.md and your Developer Notes)${opts.keepAgents ? "" : " and Athena blocks/files in agent configurations"}.`);
+    line(dim("If .athena/ is committed to Git you can restore it from history."));
+    if (!await confirm("Continue?")) {
+      line("Cancelled.");
+      return;
+    }
+  }
+  const touched = [];
+  if (!opts.keepAgents) for (const a of ADAPTERS) touched.push(...await a.remove(root));
+  await fs.rm(athenaDir(root), { recursive: true, force: true });
+  if (isJson()) json({ ok: true, removed: [".athena/", ...touched] });
+  else {
+    ok("Removed .athena/");
+    for (const t of touched) ok(`Removed Athena integration from ${t}`);
+  }
+}
+
+export {
+  confirm,
+  cleanCommand
+};
+//# sourceMappingURL=chunk-S7T6VX56.js.map