jeo-code 0.1.0 → 0.4.5

package/src/auth/storage.ts

@@ -1,9 +1,14 @@
-import { readGlobalConfig, saveGlobalConfig, type Config, type StoredOAuth } from "../agent/state";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as fs from "node:fs/promises";
+import { readGlobalConfig, readRawGlobalConfig, saveConfigPatch, type StoredOAuth } from "../agent/state";
+import { jeoEnv } from "../util/env";
 
-export type AuthProvider = "anthropic" | "openai" | "gemini";
+
+export type AuthProvider = "anthropic" | "openai" | "gemini" | "antigravity";
 
 export type Credential =
-  | { kind: "oauth"; provider: AuthProvider; token: string }
+  | { kind: "oauth"; provider: AuthProvider; token: string; projectId?: string }
   | { kind: "api_key"; provider: AuthProvider; token: string }
   | { kind: "none"; provider: AuthProvider };
 
@@ -17,17 +22,123 @@ export interface AuthSnapshot {
 }
 
 const inFlightRefresh = new Map<AuthProvider, Promise<any>>();
+function getLockPath(provider: AuthProvider): string {
+  const dir = jeoEnv("CONFIG_DIR") || path.join(os.homedir(), ".jeo");
+  return path.join(dir, `oauth-${provider}.lock`);
+}
+
+export async function acquireLock(provider: AuthProvider, timeoutMs = 5000): Promise<void> {
+  const lockPath = getLockPath(provider);
+  const dir = path.dirname(lockPath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+
+  // `timeoutMs` is the STALENESS threshold for a dead holder's lock file; the
+  // acquisition wait itself is bounded at 2× that. The previous unbounded 50ms
+  // retry loop spun forever when the stale lock could not be unlinked (or was
+  // recreated under churn by concurrent sessions) — a mid-turn OAuth refresh
+  // then froze the whole agent turn with no diagnostic.
+  const deadline = Date.now() + Math.max(timeoutMs * 2, 1_000);
+  while (true) {
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      const info = JSON.stringify({ pid: process.pid, createdAt: Date.now() });
+      await handle.writeFile(info, "utf-8");
+      await handle.close();
+      return;
+    } catch (err: any) {
+      if (err.code !== "EEXIST") {
+        throw err;
+      }
+      try {
+        const content = await fs.readFile(lockPath, "utf-8");
+        const info = JSON.parse(content);
+        if (typeof info.createdAt === "number" && info.createdAt + timeoutMs < Date.now()) {
+          await fs.unlink(lockPath).catch(() => {});
+        }
+      } catch {
+        try {
+          const stat = await fs.stat(lockPath);
+          if (stat.mtimeMs + timeoutMs < Date.now()) {
+            await fs.unlink(lockPath).catch(() => {});
+          }
+        } catch {}
+      }
+    }
+    if (Date.now() >= deadline) {
+      // Deadline reached: the holder is dead or wedged. Steal once — the lock
+      // guards a short config read-modify-write, so waiting longer only hangs
+      // the caller (and with it the live turn that triggered the refresh).
+      await fs.unlink(lockPath).catch(() => {});
+      const handle = await fs.open(lockPath, "wx").catch(() => null);
+      if (handle) {
+        await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: Date.now(), stolen: true }), "utf-8");
+        await handle.close();
+        return;
+      }
+      throw new Error(`OAuth lock for ${provider} could not be acquired within ${Math.max(timeoutMs * 2, 1_000)}ms (${lockPath})`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+export async function releaseLock(provider: AuthProvider): Promise<void> {
+  const lockPath = getLockPath(provider);
+  await fs.unlink(lockPath).catch(() => {});
+}
+
 
 function accessOf(stored: string | StoredOAuth | undefined): string | undefined {
   if (!stored) return undefined;
   return typeof stored === "string" ? stored : stored.access;
 }
 
-/** Single point of resolution: OAuth bearer beats API key when both exist. */
+/** Raw credential resolver: returns refreshable OAuth first; execution/status may override with an API key when both exist. */
 export async function resolveCredential(provider: AuthProvider): Promise<Credential> {
   const cfg = await readGlobalConfig();
-  const stored = cfg.oauth?.[provider];
+  let stored = cfg.oauth?.[provider];
+
+  // Auto-import gemini-cli credentials (~/.gemini/oauth_creds.json) when jeo has no
+  // gemini OAuth of its own — the out-of-the-box antigravity/gemini unlock. Hermetic
+  // under tests/custom config sandboxes: if JEO_CONFIG_DIR is explicitly set, only an
+  // explicit JEO_GEMINI_CREDS_PATH opts in, so tests never read the developer's real
+  // credentials or refresh real tokens.
+  const credsOverride = jeoEnv("GEMINI_CREDS_PATH");
+  const configDirOverridden = !!jeoEnv("CONFIG_DIR");
+  if (!stored && provider === "gemini" && (credsOverride || !configDirOverridden)) {
+    try {
+      const credsPath = jeoEnv("GEMINI_CREDS_PATH") || path.join(os.homedir(), ".gemini", "oauth_creds.json");
+      const content = await fs.readFile(credsPath, "utf-8");
+      const creds = JSON.parse(content);
+      if (creds && creds.access_token) {
+        let email: string | undefined;
+        if (creds.id_token) {
+          const parts = creds.id_token.split(".");
+          if (parts.length >= 2) {
+            try {
+              const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+              const payload = JSON.parse(atob(base64));
+              email = payload.email;
+            } catch {}
+          }
+        }
+        let expires = typeof creds.expiry_date === "number" ? creds.expiry_date : (typeof creds.expiry_date === "string" ? parseInt(creds.expiry_date, 10) : undefined);
+        if (isNaN(expires as number)) expires = undefined;
 
+        const imported: StoredOAuth = {
+          access: creds.access_token,
+          refresh: creds.refresh_token,
+          expires,
+          email,
+        };
+        await setOauthCredential("gemini", imported);
+        // stderr, NOT stdout: --json consumers (doctor, models) parse stdout.
+        console.error(`[NOTICE] Transparently imported Gemini OAuth credentials from ~/.gemini/oauth_creds.json`);
+        stored = imported;
+      }
+    } catch {
+      // never break existing resolution
+    }
+  }
   if (stored) {
     // Auto-refresh refreshable credentials that are past their expiry.
     if (typeof stored !== "string" && stored.refresh && stored.expires && stored.expires <= Date.now()) {
@@ -39,9 +150,10 @@ export async function resolveCredential(provider: AuthProvider): Promise<Credent
             return refreshOAuthToken(provider);
           })();
           inFlightRefresh.set(provider, refreshPromise);
-          refreshPromise.finally(() => {
+          // Cleanup must not create its own unobserved rejection if the refresh rejects.
+          void refreshPromise.finally(() => {
             inFlightRefresh.delete(provider);
-          });
+          }).catch(() => {});
         }
         const result = await refreshPromise;
         if (result.refreshed && result.credential.kind === "oauth") {
@@ -52,7 +164,14 @@ export async function resolveCredential(provider: AuthProvider): Promise<Credent
       }
     }
     const token = accessOf(stored);
-    if (token) return { kind: "oauth", provider, token };
+    if (token) {
+      return {
+        kind: "oauth",
+        provider,
+        token,
+        projectId: typeof stored === "object" ? stored.projectId : undefined,
+      };
+    }
   }
 
   const apiKey = cfg.providers[provider];
@@ -81,33 +200,37 @@ export async function getStoredOAuth(provider: AuthProvider): Promise<StoredOAut
 
 /** Persist a plain bearer token (legacy / manual paste — no refresh metadata). */
 export async function setOauthToken(provider: AuthProvider, token: string): Promise<void> {
-  const cfg = await readGlobalConfig();
-  const next: Config = JSON.parse(JSON.stringify(cfg));
-  next.oauth = next.oauth ?? {};
-  next.oauth[provider] = token;
-  await saveGlobalConfig(next);
+  // Persist onto the RAW on-disk config (not env-overlaid) so a short-lived
+  // *_OAUTH_TOKEN env / OLLAMA_HOST / role tier is never baked into config.json.
+  await saveConfigPatch(raw => ({ oauth: { ...(raw.oauth ?? {}), [provider]: token } }));
+}
+
+/** Persist a full OAuth credential set (access + refresh + expiry). */
+export async function setOauthCredentialNoLock(provider: AuthProvider, cred: StoredOAuth): Promise<void> {
+  await saveConfigPatch(raw => ({ oauth: { ...(raw.oauth ?? {}), [provider]: cred } }));
 }
 
 /** Persist a full OAuth credential set (access + refresh + expiry). */
 export async function setOauthCredential(provider: AuthProvider, cred: StoredOAuth): Promise<void> {
-  const cfg = await readGlobalConfig();
-  const next: Config = JSON.parse(JSON.stringify(cfg));
-  next.oauth = next.oauth ?? {};
-  next.oauth[provider] = cred;
-  await saveGlobalConfig(next);
+  await acquireLock(provider);
+  try {
+    await setOauthCredentialNoLock(provider, cred);
+  } finally {
+    await releaseLock(provider);
+  }
 }
 
 export async function clearOauthToken(provider: AuthProvider): Promise<boolean> {
-  const cfg = await readGlobalConfig();
-  if (!cfg.oauth?.[provider]) return false;
-  delete cfg.oauth[provider];
-  await saveGlobalConfig(cfg);
+  const raw = await readRawGlobalConfig();
+  if (!raw.oauth?.[provider]) return false;
+  await saveConfigPatch(r => {
+    const oauth = { ...(r.oauth ?? {}) };
+    delete oauth[provider];
+    return { oauth };
+  });
   return true;
 }
 
 export async function setApiKey(provider: AuthProvider, key: string): Promise<void> {
-  const cfg = await readGlobalConfig();
-  const next: Config = JSON.parse(JSON.stringify(cfg));
-  next.providers[provider] = key;
-  await saveGlobalConfig(next);
+  await saveConfigPatch(raw => ({ providers: { ...(raw.providers ?? {}), [provider]: key } }));
 }

package/src/auth/types.ts

@@ -1,4 +1,4 @@
-/** OAuth flow types, mirroring gjc's oauth/types.ts (trimmed to joc's surface). */
+/** OAuth flow types, mirroring gjc's oauth/types.ts (trimmed to jeo's surface). */
 
 export interface OAuthCredentials {
   access: string;

package/src/autopilot.ts

@@ -0,0 +1,362 @@
+/**
+ * jeo autopilot — autonomous build loop hardened with autoresearch ratcheting.
+ *
+ * Fuses two skills:
+ *  - /skill:autopilot  : end-to-end plan -> implement -> verify -> stop loop
+ *  - /skill:autoresearch : frozen evaluator, one change per step, keep-if-improved /
+ *                          revert-otherwise by score, append-only log, baseline-first,
+ *                          convergence/stop discipline.
+ *
+ * The engine owns the RATCHET BRAIN (decision + evidence ledger), not destructive
+ * git ops. Mutation ("make one change") is supplied by the operator/agent via a
+ * runner command; reverts run an operator-supplied --on-revert hook.
+ *
+ * State (per cwd):
+ *   .jeo/autopilot/session.json   frozen contract (immutable for the session)
+ *   .jeo/autopilot/log.jsonl      append-only attempt log (baseline, steps, stops)
+ *
+ * No external dependencies (Node stdlib only). Runs under Bun or Node.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import { renderAutopilotStatusPanel, type AutopilotStatusPanelData } from "./tui/components/autopilot-status";
+
+const AP_DIR = path.join(".jeo", "autopilot");
+const SESSION = path.join(AP_DIR, "session.json");
+const LOG = path.join(AP_DIR, "log.jsonl");
+function getShell(): string | undefined {
+  if (process.platform === "win32") return undefined;
+  return process.env.SHELL || "/bin/bash";
+}
+
+type Goal = "min" | "max" | "gate";
+
+interface Session {
+  task: string;
+  evalCmd: string;
+  goal: Goal;
+  timeoutSec: number;
+  patience: number;
+  createdAt: string;
+  frozen: true;
+}
+
+interface LogEvent {
+  ts: string;
+  type: "baseline" | "step" | "stop";
+  [k: string]: unknown;
+}
+
+type LogEventInput = {
+  type: LogEvent["type"];
+  [k: string]: unknown;
+};
+
+function die(msg: string): never {
+  console.error(`jeo autopilot: ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv: string[]): { positionals: string[]; flags: Record<string, string> } {
+  const positionals: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) flags[key] = "true";
+      else {
+        flags[key] = next;
+        i++;
+      }
+    } else positionals.push(a);
+  }
+  return { positionals, flags };
+}
+
+function loadSession(): Session {
+  if (!fs.existsSync(SESSION)) die("no session — run: jeo autopilot init --task <t> --eval <cmd>");
+  return JSON.parse(fs.readFileSync(SESSION, "utf8")) as Session;
+}
+
+function appendLog(ev: LogEventInput): LogEvent {
+  const full: LogEvent = { ts: new Date().toISOString(), ...ev };
+  fs.appendFileSync(LOG, JSON.stringify(full) + "\n");
+  return full;
+}
+
+function readLog(): LogEvent[] {
+  if (!fs.existsSync(LOG)) return [];
+  return fs
+    .readFileSync(LOG, "utf8")
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l) as LogEvent);
+}
+
+/** Run the frozen eval. Returns { score, passed }. score is NaN when no score: line. */
+function runEval(s: Session): { score: number; passed: boolean; output: string } {
+  let output = "";
+  let passed = true;
+  try {
+    output = execSync(s.evalCmd, {
+      encoding: "utf8",
+      timeout: s.timeoutSec * 1000,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: getShell(),
+    });
+  } catch (e: unknown) {
+    passed = false;
+    const err = e as { stdout?: string; stderr?: string };
+    output = (err.stdout ?? "") + (err.stderr ?? "");
+  }
+  const matches = [...output.matchAll(/score:\s*(-?\d+(?:\.\d+)?)/gi)];
+  const score = matches.length ? Number(matches[matches.length - 1][1]) : NaN;
+  return { score, passed, output: output.trim() };
+}
+
+/** Best kept score so far, folding baseline + kept steps. undefined if none. */
+function currentBest(s: Session): number | undefined {
+  let best: number | undefined;
+  for (const ev of readLog()) {
+    if (ev.type === "baseline" || (ev.type === "step" && ev.decision === "keep")) {
+      const sc = ev.score as number;
+      if (typeof sc === "number" && !Number.isNaN(sc)) {
+        if (best === undefined) best = sc;
+        else if (s.goal === "min") best = Math.min(best, sc);
+        else if (s.goal === "max") best = Math.max(best, sc);
+        else best = sc;
+      }
+    }
+  }
+  return best;
+}
+
+function isImprovement(goal: Goal, score: number, best: number | undefined): boolean {
+  if (best === undefined) return true;
+  if (goal === "min") return score < best;
+  if (goal === "max") return score > best;
+  return true; // gate handled via passed, not score
+}
+
+function hasBaseline(): boolean {
+  return readLog().some((e) => e.type === "baseline");
+}
+
+// ── commands ──────────────────────────────────────────────────────────────
+
+function cmdInit(flags: Record<string, string>): void {
+  if (fs.existsSync(SESSION) && flags.force !== "true") {
+    die(`session already frozen at ${SESSION} (use --force to overwrite)`);
+  }
+  if (!flags.task) die("init requires --task");
+  if (!flags.eval) die("init requires --eval <command that prints 'score: N' or exits 0/1>");
+  const goal = (flags.goal ?? "min") as Goal;
+  if (!["min", "max", "gate"].includes(goal)) die("--goal must be min|max|gate");
+  fs.mkdirSync(AP_DIR, { recursive: true });
+  const session: Session = {
+    task: flags.task,
+    evalCmd: flags.eval,
+    goal,
+    timeoutSec: flags.timeout ? Number(flags.timeout) : 300,
+    patience: flags.patience ? Number(flags.patience) : 3,
+    createdAt: new Date().toISOString(),
+    frozen: true,
+  };
+  fs.writeFileSync(SESSION, JSON.stringify(session, null, 2) + "\n");
+  // fresh log on (re)init
+  fs.writeFileSync(LOG, "");
+  console.log(`jeo autopilot: session frozen → ${SESSION}`);
+  console.log(`  task=${session.task}`);
+  console.log(`  eval=${session.evalCmd}  goal=${session.goal}  timeout=${session.timeoutSec}s  patience=${session.patience}`);
+}
+
+function cmdBaseline(): void {
+  const s = loadSession();
+  if (hasBaseline()) die("baseline already recorded (re-init to reset)");
+  const { score, passed, output } = runEval(s);
+  appendLog({ type: "baseline", score, passed, output });
+  console.log(`jeo autopilot: baseline score=${fmt(score)} passed=${passed}`);
+}
+
+function cmdStep(flags: Record<string, string>): void {
+  const s = loadSession();
+  if (s.goal !== "gate" && !hasBaseline()) die("record a baseline first: jeo autopilot baseline");
+  const change = flags.change ?? "(unspecified change)";
+  const best = currentBest(s);
+  const { score, passed, output } = runEval(s);
+
+  let decision: "keep" | "revert";
+  if (s.goal === "gate") {
+    decision = passed ? "keep" : "revert";
+  } else if (Number.isNaN(score)) {
+    decision = "revert"; // no measurable score => cannot prove improvement
+  } else {
+    decision = isImprovement(s.goal, score, best) ? "keep" : "revert";
+  }
+
+  if (decision === "revert" && flags["on-revert"]) {
+    try {
+      execSync(flags["on-revert"], { stdio: "inherit", shell: getShell() });
+    } catch {
+      console.error("jeo autopilot: --on-revert hook failed (decision still logged)");
+    }
+  }
+
+  appendLog({ type: "step", change, score, passed, decision, prevBest: best ?? null, output });
+  const cmp =
+    s.goal === "gate"
+      ? passed ? "pass" : "fail"
+      : `${fmt(score)} vs best ${fmt(best)}`;
+  console.log(`jeo autopilot: step ${decision.toUpperCase()}  (${cmp})  — ${change}`);
+}
+
+function cmdLoop(flags: Record<string, string>): void {
+  const s = loadSession();
+  const runner = flags.runner;
+  if (!runner) die("loop requires --runner <command that makes ONE change>");
+  const max = flags.max ? Number(flags.max) : 10;
+  if (s.goal !== "gate" && !hasBaseline()) {
+    const { score, passed, output } = runEval(s);
+    appendLog({ type: "baseline", score, passed, output });
+    console.log(`jeo autopilot: auto-baseline score=${fmt(score)}`);
+  }
+
+  let sinceImprove = 0;
+  for (let i = 1; i <= max; i++) {
+    // mutate: runner makes exactly one change
+    let runnerOk = true;
+    try {
+      execSync(runner, { stdio: "inherit", timeout: s.timeoutSec * 1000, shell: getShell() });
+    } catch {
+      runnerOk = false;
+    }
+    if (!runnerOk) {
+      appendLog({ type: "stop", reason: "runner_failed", iteration: i });
+      console.log(`jeo autopilot: stop — runner failed at iteration ${i}`);
+      return;
+    }
+
+    const best = currentBest(s);
+    const { score, passed, output } = runEval(s);
+    let decision: "keep" | "revert";
+    if (s.goal === "gate") decision = passed ? "keep" : "revert";
+    else if (Number.isNaN(score)) decision = "revert";
+    else decision = isImprovement(s.goal, score, best) ? "keep" : "revert";
+
+    if (decision === "revert" && flags["on-revert"]) {
+      try {
+        execSync(flags["on-revert"], { stdio: "inherit", shell: getShell() });
+      } catch {
+        /* logged below regardless */
+      }
+    }
+    appendLog({ type: "step", iteration: i, change: `loop#${i}`, score, passed, decision, prevBest: best ?? null, output });
+    const improved = decision === "keep" && (s.goal === "gate" || !Number.isNaN(score));
+    sinceImprove = improved && (best === undefined || s.goal === "gate" || isImprovement(s.goal, score, best)) ? 0 : sinceImprove + 1;
+    console.log(`jeo autopilot: loop ${i}/${max} ${decision.toUpperCase()} score=${fmt(score)} (sinceImprove=${sinceImprove})`);
+
+    if (s.goal !== "gate" && sinceImprove >= s.patience) {
+      appendLog({ type: "stop", reason: "converged", iteration: i, patience: s.patience });
+      console.log(`jeo autopilot: stop — converged (no improvement in ${s.patience} steps)`);
+      return;
+    }
+  }
+  appendLog({ type: "stop", reason: "max_iterations", iteration: max });
+  console.log(`jeo autopilot: stop — reached max ${max} iterations`);
+}
+
+function cmdStatus(flags: Record<string, string>): void {
+  const s = loadSession();
+  const log = readLog();
+  const steps = log.filter((e) => e.type === "step");
+  const kept = steps.filter((e) => e.decision === "keep").length;
+  const reverted = steps.filter((e) => e.decision === "revert").length;
+  const baseline = log.find((e) => e.type === "baseline");
+  const best = currentBest(s);
+  const stop = [...log].reverse().find((e) => e.type === "stop");
+
+  // convergence: steps since last keep-with-improvement
+  let sinceImprove = 0;
+  for (const e of steps) {
+    if (e.decision === "keep") sinceImprove = 0;
+    else sinceImprove++;
+  }
+  const converged = s.goal !== "gate" && sinceImprove >= s.patience;
+
+  let recommendation: string;
+  if (stop) recommendation = `stopped: ${stop.reason as string}`;
+  else if (converged) recommendation = "converged — stop or change strategy";
+  else recommendation = "continue";
+
+  const out: AutopilotStatusPanelData = {
+    task: s.task,
+    goal: s.goal,
+    eval: s.evalCmd,
+    baseline: fmt(baseline ? (baseline.score as number) : null),
+    best: fmt(best ?? null),
+    attempts: steps.length,
+    kept,
+    reverted,
+    sinceImprove,
+    converged,
+    recommendation,
+  };
+
+  if (flags.json === "true") {
+    console.log(JSON.stringify({
+      ...out,
+      baseline: baseline ? (baseline.score as number) : null,
+      best: best ?? null,
+    }, null, 2));
+    return;
+  }
+  console.log(renderAutopilotStatusPanel(out, {
+    cols: process.stdout.columns || 88,
+    color: !!process.stdout.isTTY,
+    unicode: true,
+  }).join("\n"));
+}
+
+function fmt(n: number | null | undefined): string {
+  if (n === null || n === undefined || Number.isNaN(n)) return "—";
+  return String(n);
+}
+
+function help(): void {
+  console.log(
+    [
+      "jeo autopilot — autonomous build loop with autoresearch ratcheting",
+      "",
+      "  init --task <t> --eval <cmd> [--goal min|max|gate] [--timeout S] [--patience N]",
+      "  baseline",
+      "  step --change <desc> [--on-revert <cmd>]",
+      "  loop --runner <cmd> [--max N] [--on-revert <cmd>]",
+      "  status [--json]",
+      "",
+      "eval contract: command prints 'score: <number>' (min/max goals) or exits 0/1 (gate goal).",
+    ].join("\n"),
+  );
+}
+
+export function runAutopilot(argv: string[]): void {
+  const [cmd, ...rest] = argv;
+  const { flags } = parseArgs(rest);
+  switch (cmd) {
+    case "init": cmdInit(flags); break;
+    case "baseline": cmdBaseline(); break;
+    case "step": cmdStep(flags); break;
+    case "loop": cmdLoop(flags); break;
+    case "status": cmdStatus(flags); break;
+    case undefined:
+    case "help":
+    case "--help": help(); break;
+    default: die(`unknown subcommand: ${cmd} (try: jeo autopilot help)`);
+  }
+}
+
+// allow running this module directly: bun src/autopilot.ts <args>
+if (import.meta.main) runAutopilot(process.argv.slice(2));

package/src/bun-imports.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/cli/AGENTS.md

@@ -0,0 +1,39 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# cli
+
+## Purpose
+Command-line interface routing, argument parsing, and initialization logic. Defines the shape of the `jeo` binary interface.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `parser.ts` | Argument parsing and flag validation |
+| `router.ts` | Dispatches CLI commands to their respective implementations |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Keep parsing logic declarative.
+- Ensure all flags have clear help text and defaults.
+- Delegate actual command execution to `src/commands/`.
+
+### Testing Requirements
+- Test CLI arg parsing with various flag combinations.
+
+### Common Patterns
+- Early exit for `--help` and `--version`.
+
+## Dependencies
+
+### Internal
+- Routes to `src/commands/`.
+
+### External
+- Standard CLI arg parsing libraries or custom minimal parsers.
+
+<!-- MANUAL: -->