auggy 0.3.0

package/src/cli/commands/eval.ts

@@ -0,0 +1,180 @@
+/**
+ * auggy eval [suite|agent] — run an eval suite.
+ *
+ * Suite routing:
+ *   auggy eval auto-save                # auto-save fixture validation (dry-run)
+ *   auggy eval auto-save --dry-run      # explicit dry-run (same as above)
+ *
+ * Security eval (default when no suite name is given):
+ *   auggy eval                          # default fixture (canonical test agent)
+ *   auggy eval zip                      # registered agent
+ *   auggy eval --config path/to/agent.yaml
+ *   auggy eval zip --suite security-only
+ *   auggy eval zip --trials 5
+ *
+ * Config-path resolution order (highest precedence first):
+ *   1. --config <path>  (resolved against cwd)
+ *   2. [agent] argument (looked up in `~/.auggy/agents.json`)
+ *   3. Default: the canonical fixture at `evals/security/fixtures/test-agent.yaml`
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Command } from "commander";
+import { runEvalSuite, getDefaultFixtureConfigPath } from "../../../evals/security/run";
+import { runAutoSaveEval } from "../../../evals/auto-save/run";
+import { getAgent } from "../agent-index";
+
+/** Known suite names that route to specialized runners (not the security runner). */
+const NAMED_SUITES = ["auto-save"] as const;
+type NamedSuite = (typeof NAMED_SUITES)[number];
+
+interface ResolveEvalConfigOptions {
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+  /** Inject a fixture-path resolver for tests. Defaults to the runner's resolver. */
+  defaultFixtureConfigPath?: () => string;
+}
+
+/**
+ * Resolve the agent.yaml path for `auggy eval`. Mirrors `resolveConfigPath`
+ * but allows the agent name to be omitted — falling back to the bundled
+ * fixture when neither name nor explicit --config is supplied.
+ */
+export function resolveEvalConfigPath(
+  args: { agentName?: string; explicitConfig?: string },
+  opts: ResolveEvalConfigOptions = {},
+): string {
+  if (args.explicitConfig) {
+    const absPath = resolve(args.explicitConfig);
+    if (!existsSync(absPath)) {
+      throw new Error(`Config file not found: ${absPath}`);
+    }
+    return absPath;
+  }
+
+  if (args.agentName) {
+    const entry = getAgent(args.agentName, opts);
+    if (!entry) {
+      throw new Error(
+        `Agent "${args.agentName}" not found.\n\n` +
+          `  Run \`auggy ls\` to see registered agents,\n` +
+          `  or use --config <path> for a one-off path.`,
+      );
+    }
+    const cfg = join(entry.localDir, "agent.yaml");
+    if (!existsSync(cfg)) {
+      throw new Error(
+        `agent.yaml missing at indexed path: ${cfg}\n\n` +
+          `  The agent directory may have been deleted or moved manually.\n` +
+          `  Run \`auggy remove ${args.agentName}\` to clean up the index entry.`,
+      );
+    }
+    return cfg;
+  }
+
+  const fixtureResolver = opts.defaultFixtureConfigPath ?? getDefaultFixtureConfigPath;
+  return fixtureResolver();
+}
+
+export interface EvalCommandDeps {
+  /** Inject for tests so we don't make real API calls. */
+  runEvalSuite?: typeof runEvalSuite;
+  /** Inject auto-save runner for tests. */
+  runAutoSaveEval?: typeof runAutoSaveEval;
+  /** Override exit so tests can assert the exit code without crashing the runner. */
+  exit?: (code: number) => void;
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+}
+
+export function evalCommand(deps: EvalCommandDeps = {}): Command {
+  const runner = deps.runEvalSuite ?? runEvalSuite;
+  const autoSaveRunner = deps.runAutoSaveEval ?? runAutoSaveEval;
+  const exit = deps.exit ?? ((code: number) => process.exit(code));
+
+  return new Command("eval")
+    .description("Run an eval suite: auto-save (fixture validation) or security (default)")
+    .argument(
+      "[suite-or-agent]",
+      "suite name (auto-save) or registered agent name for security eval (defaults to the bundled fixture)",
+    )
+    .option(
+      "--config <path>",
+      "explicit agent.yaml path (overrides agent name lookup; security eval only)",
+    )
+    .option(
+      "--suite <which>",
+      "security-only | benign-only | all (default; security eval only)",
+      "all",
+    )
+    .option("--trials <n>", "trials per case (default: 3; security eval only)")
+    .option("--dry-run", "validate auto-save fixtures without LLM calls (auto-save suite only)")
+    .action(
+      async (
+        suiteOrAgent: string | undefined,
+        opts: { config?: string; suite: string; trials?: string; dryRun?: boolean },
+      ) => {
+        // Route named suites to their own runners.
+        if (suiteOrAgent != null && NAMED_SUITES.includes(suiteOrAgent as NamedSuite)) {
+          const suiteName = suiteOrAgent as NamedSuite;
+
+          if (suiteName === "auto-save") {
+            const result = await autoSaveRunner({ dryRun: opts.dryRun !== false });
+            exit(result.exitCode);
+            return;
+          }
+
+          // Future named suites routed here.
+          console.error(`Error: unknown suite "${suiteName}"`);
+          exit(1);
+          return;
+        }
+
+        // Security eval path (default when no named suite is given).
+        const agentName = suiteOrAgent;
+        let configPath: string;
+        try {
+          configPath = resolveEvalConfigPath(
+            { agentName, explicitConfig: opts.config },
+            { auggyDir: deps.auggyDir },
+          );
+        } catch (err) {
+          console.error(`Error: ${(err as Error).message}`);
+          exit(1);
+          return;
+        }
+
+        if (
+          opts.suite !== "all" &&
+          opts.suite !== "security-only" &&
+          opts.suite !== "benign-only"
+        ) {
+          console.error(
+            `Error: --suite must be one of: all, security-only, benign-only (got "${opts.suite}")`,
+          );
+          exit(1);
+          return;
+        }
+
+        let trialsOverride: number | undefined;
+        if (opts.trials !== undefined) {
+          const n = Number.parseInt(opts.trials, 10);
+          if (!Number.isInteger(n) || n < 1) {
+            console.error(`Error: --trials must be a positive integer (got "${opts.trials}")`);
+            exit(1);
+            return;
+          }
+          trialsOverride = n;
+        }
+
+        const result = await runner({
+          configPath,
+          runSecurity: opts.suite !== "benign-only",
+          runBenign: opts.suite !== "security-only",
+          trialsOverride,
+        });
+        exit(result.exitCode);
+      },
+    );
+}

package/src/cli/commands/ls.ts

@@ -0,0 +1,66 @@
+/**
+ * auggy ls — list all registered agents with their location and status.
+ *
+ * Status is derived from PID manifests + filesystem: running, stopped, or
+ * missing-dir (indexed but localDir gone).
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { listAgents } from "../agent-index";
+import { readPidManifest, isProcessAlive } from "../pid-registry";
+
+interface LsOptions {
+  auggyDir?: string;
+}
+
+interface AgentRow {
+  name: string;
+  location: string;
+  status: string;
+}
+
+function tildify(path: string): string {
+  const home = homedir();
+  if (path === home || path.startsWith(`${home}/`)) {
+    return `~${path.slice(home.length)}`;
+  }
+  return path;
+}
+
+function statusFor(name: string, localDir: string): string {
+  if (!existsSync(localDir)) return "missing-dir";
+  const pid = readPidManifest(name);
+  if (pid && isProcessAlive(pid.pid)) {
+    return `running (${pid.mode}, :${pid.port})`;
+  }
+  return "stopped";
+}
+
+export async function runLs(opts: LsOptions = {}): Promise<void> {
+  const agents = listAgents({ auggyDir: opts.auggyDir });
+
+  if (agents.length === 0) {
+    console.log("No agents registered.");
+    console.log();
+    console.log("Run `auggy create <name>` to scaffold one.");
+    return;
+  }
+
+  const rows: AgentRow[] = agents.map((a) => ({
+    name: a.name,
+    location: tildify(a.localDir),
+    status: statusFor(a.name, a.localDir),
+  }));
+
+  // Compute column widths.
+  const nameW = Math.max(4, ...rows.map((r) => r.name.length));
+  const locW = Math.max(8, ...rows.map((r) => r.location.length));
+
+  const pad = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length));
+
+  console.log(`${pad("NAME", nameW)}  ${pad("LOCATION", locW)}  STATUS`);
+  for (const row of rows) {
+    console.log(`${pad(row.name, nameW)}  ${pad(row.location, locW)}  ${row.status}`);
+  }
+}

package/src/cli/commands/remove.ts

@@ -0,0 +1,95 @@
+/**
+ * auggy remove <name> — delete an agent directory and clear the index entry.
+ *
+ * Refuses if the agent is running. Prompts before deletion (skipped with
+ * --yes). Tolerates missing localDir (still cleans the index entry).
+ */
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { confirm } from "@inquirer/prompts";
+import { getAgent, removeAgent } from "../agent-index";
+import { readPidManifest, isProcessAlive, removePidManifest } from "../pid-registry";
+
+function readConfigName(localDir: string): string | null {
+  try {
+    const yamlPath = join(localDir, "agent.yaml");
+    if (!existsSync(yamlPath)) return null;
+    const content = readFileSync(yamlPath, "utf-8");
+    const match = content.match(/^name:\s*(.+)$/m);
+    return match?.[1]?.trim() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+interface RemoveOptions {
+  /** Skip the y/N prompt. */
+  yes?: boolean;
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+}
+
+export async function runRemove(name: string, opts: RemoveOptions = {}): Promise<void> {
+  const entry = getAgent(name, { auggyDir: opts.auggyDir });
+  if (!entry) {
+    throw new Error(
+      `Agent "${name}" is not registered.\n\n  Run \`auggy ls\` to see registered agents.`,
+    );
+  }
+
+  // Refuse if the agent is running. Stale manifests (dead PID) are tolerated
+  // — we clean them up below. Check under both the CLI-arg name AND the
+  // agent.yaml's config.name (operator may have edited the yaml after create,
+  // in which case `auggy dev` writes the manifest under config.name).
+  const pidByCli = readPidManifest(name);
+  const configName = readConfigName(entry.localDir);
+  const pidByConfig = configName && configName !== name ? readPidManifest(configName) : null;
+
+  const aliveCli = pidByCli && isProcessAlive(pidByCli.pid);
+  const aliveConfig = pidByConfig && isProcessAlive(pidByConfig.pid);
+
+  if (aliveCli || aliveConfig) {
+    const liveName = aliveCli ? name : configName!;
+    throw new Error(`Agent "${liveName}" is running. Stop it first:\n\n  auggy stop ${liveName}`);
+  }
+
+  if (!opts.yes) {
+    const ok = await confirm({
+      message:
+        `This will permanently delete:\n  ${entry.localDir}\n\n` +
+        `And remove the registry entry for "${name}".\n\nContinue?`,
+      default: false,
+    });
+    if (!ok) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  // Delete the local dir if present (tolerate missing). Sanity-check that the
+  // dir contains agent.yaml first — refuse to recursively delete if not, since
+  // a tampered or corrupt index entry could otherwise nuke arbitrary paths.
+  if (existsSync(entry.localDir)) {
+    const yamlPath = join(entry.localDir, "agent.yaml");
+    if (!existsSync(yamlPath)) {
+      throw new Error(
+        `Refusing to delete "${entry.localDir}" — it does not contain agent.yaml.\n\n` +
+          `  This may indicate a tampered or stale index entry. If the agent dir was\n` +
+          `  modified outside auggy, clean up manually and re-run \`auggy remove\` to\n` +
+          `  clear the index entry.`,
+      );
+    }
+    rmSync(entry.localDir, { recursive: true, force: true });
+  }
+
+  // Clean up stale PID manifest(s) if any. Remove under whichever name we
+  // actually found a manifest at.
+  if (pidByCli) removePidManifest(name);
+  if (pidByConfig && configName) removePidManifest(configName);
+
+  // Clear index entry.
+  removeAgent(name, { auggyDir: opts.auggyDir });
+
+  console.log(`Removed agent "${name}" (was at ${entry.localDir}).`);
+}

package/src/cli/commands/restart.ts

@@ -0,0 +1,40 @@
+/**
+ * auggy restart <name> — stop + start in one command.
+ *
+ * Reads the PID manifest to determine mode (dev vs launchd),
+ * stops the agent, then restarts it in the same mode.
+ */
+
+import { readPidManifest } from "../pid-registry";
+import { runStop } from "./stop";
+import { runStart } from "./start";
+import { runDev } from "./dev";
+
+export async function runRestart(name: string, opts: { config?: string }): Promise<void> {
+  const manifest = readPidManifest(name);
+
+  if (!manifest) {
+    console.log(
+      `Agent "${name}" is not running. Use "auggy dev ${name}" or "auggy start ${name}" to start it.`,
+    );
+    return;
+  }
+
+  const mode = manifest.mode;
+  const configPath = opts.config ?? manifest.configPath;
+
+  console.log(`Restarting "${name}" (${mode} mode)...`);
+
+  // Stop the agent.
+  await runStop(name);
+
+  // Brief pause for port release.
+  await Bun.sleep(1000);
+
+  // Restart in the same mode.
+  if (mode === "launchd") {
+    await runStart(name, { config: configPath });
+  } else {
+    await runDev(name, { config: configPath });
+  }
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,123 @@
+/**
+ * auggy start <name> — install an agent as a launchd service.
+ *
+ * Generates a plist, symlinks it to ~/Library/LaunchAgents/, and
+ * loads it via launchctl. The plist invokes `auggy dev <name>` so
+ * launchd handles daemonization and restart.
+ */
+
+import { mkdirSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { $ } from "bun";
+import { parseConfig } from "../config-parser";
+import {
+  generatePlist,
+  plistLabel,
+  plistStorePath,
+  plistInstallPath,
+  logDir,
+} from "../plist-generator";
+import { readPidManifest, tryClaimName } from "../pid-registry";
+import { resolveConfigPath } from "../resolve-config";
+
+function resolveBunPath(): string {
+  return process.execPath;
+}
+
+function resolveCliEntryPoint(): string {
+  return resolve(import.meta.dir, "../index.ts");
+}
+
+export async function runStart(name: string, opts: { config?: string }): Promise<void> {
+  const configPath = resolveConfigPath(name, opts.config);
+  const agentDir = dirname(configPath);
+
+  // Validate config before installing.
+  const config = parseConfig(configPath);
+  const agentName = config.name;
+
+  // Check if already running.
+  if (!tryClaimName(agentName)) {
+    throw new Error(
+      `Agent "${agentName}" is already running. Use "auggy stop ${agentName}" first.`,
+    );
+  }
+
+  // Unload existing plist if present.
+  const label = plistLabel(agentName);
+  const installPath = plistInstallPath(agentName);
+  try {
+    const result = await $`launchctl list`.quiet();
+    if (result.stdout.toString().includes(label)) {
+      await $`launchctl unload ${installPath}`.quiet();
+    }
+  } catch {}
+
+  // Clean up old plist files.
+  const storePath = plistStorePath(agentName);
+  try {
+    unlinkSync(installPath);
+  } catch {}
+  try {
+    unlinkSync(storePath);
+  } catch {}
+
+  // Generate plist.
+  const plist = generatePlist({
+    name: agentName,
+    agentDir: resolve(agentDir),
+    configPath: resolve(configPath),
+    bunPath: resolveBunPath(),
+    cliEntryPoint: resolveCliEntryPoint(),
+  });
+
+  // Ensure directories exist.
+  mkdirSync(dirname(storePath), { recursive: true });
+  mkdirSync(dirname(installPath), { recursive: true });
+  mkdirSync(logDir(), { recursive: true });
+
+  // Write plist and symlink to LaunchAgents.
+  writeFileSync(storePath, plist);
+  symlinkSync(storePath, installPath);
+
+  // Load into launchd.
+  try {
+    await $`launchctl load ${installPath}`.quiet();
+  } catch (err: unknown) {
+    const stderr = (err as { stderr?: { toString(): string } }).stderr?.toString() ?? "";
+    if (!stderr.includes("service already loaded")) {
+      throw new Error(`launchctl load failed: ${stderr.trim() || (err as Error).message}`);
+    }
+  }
+
+  // Poll for the agent to start.
+  const MAX_WAIT = 8_000;
+  const POLL_INTERVAL = 500;
+  let waited = 0;
+
+  while (waited < MAX_WAIT) {
+    await Bun.sleep(POLL_INTERVAL);
+    waited += POLL_INTERVAL;
+
+    const manifest = readPidManifest(agentName);
+    if (manifest) {
+      console.log(`Agent "${agentName}" installed and running (PID ${manifest.pid})`);
+      console.log();
+      console.log(`  Mode:    always-on (launchd-managed)`);
+      console.log(`  Restart: automatic on crash`);
+      if (manifest.port) {
+        console.log(`  URL:     http://localhost:${manifest.port}`);
+      }
+      console.log(`  Logs:    ${logDir()}/${agentName}.{log,err}`);
+      console.log();
+      console.log(`  To stop:   auggy stop ${agentName}`);
+      console.log(`  To status: auggy status ${agentName}`);
+      console.log(`  To logs:   tail -f ${logDir()}/${agentName}.log`);
+      return;
+    }
+  }
+
+  console.error(`Agent "${agentName}" did not start within ${MAX_WAIT / 1000}s.`);
+  console.error(`Check logs: tail -20 ${logDir()}/${agentName}.err`);
+  process.exit(1);
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,104 @@
+/**
+ * auggy status [name] — show running agents or detail one.
+ *
+ * With no name: list all running agents in a table.
+ * With a name: show detailed status including health check.
+ */
+
+import { listPidManifests, readPidManifest, isProcessAlive } from "../pid-registry";
+
+function formatUptime(startedAt: string): string {
+  const ms = Date.now() - new Date(startedAt).getTime();
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h`;
+}
+
+async function fetchHealth(port: number): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await fetch(`http://localhost:${port}/health`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    if (res.ok) return (await res.json()) as Record<string, unknown>;
+  } catch {}
+  return null;
+}
+
+export async function runStatus(name?: string): Promise<void> {
+  if (name) {
+    await showDetail(name);
+  } else {
+    await showAll();
+  }
+}
+
+async function showAll(): Promise<void> {
+  const manifests = listPidManifests();
+
+  if (manifests.length === 0) {
+    console.log("No agents running.");
+    console.log('Run "auggy create <name>" to create one.');
+    return;
+  }
+
+  // Table header.
+  console.log(
+    pad("NAME", 20) +
+      pad("STATUS", 10) +
+      pad("PID", 8) +
+      pad("PORT", 8) +
+      pad("MODE", 10) +
+      pad("UPTIME", 10),
+  );
+  console.log("-".repeat(66));
+
+  for (const m of manifests) {
+    const alive = isProcessAlive(m.pid);
+    const status = alive ? "running" : "dead";
+    console.log(
+      pad(m.name, 20) +
+        pad(status, 10) +
+        pad(String(m.pid), 8) +
+        pad(m.port ? String(m.port) : "-", 8) +
+        pad(m.mode, 10) +
+        pad(formatUptime(m.startedAt), 10),
+    );
+  }
+}
+
+async function showDetail(name: string): Promise<void> {
+  const manifest = readPidManifest(name);
+
+  if (!manifest) {
+    console.log(`Agent "${name}" is not running.`);
+    return;
+  }
+
+  const alive = isProcessAlive(manifest.pid);
+  console.log(`Agent: ${manifest.name}`);
+  console.log(`Status: ${alive ? "running" : "dead"}`);
+  console.log(`PID: ${manifest.pid}`);
+  console.log(`Mode: ${manifest.mode}`);
+  console.log(`Uptime: ${formatUptime(manifest.startedAt)}`);
+  console.log(`Config: ${manifest.configPath}`);
+  console.log(`Agent dir: ${manifest.agentDir}`);
+
+  if (manifest.port) {
+    console.log(`Port: ${manifest.port}`);
+    const health = await fetchHealth(manifest.port);
+    if (health) {
+      console.log(`Health: ${JSON.stringify(health)}`);
+    } else {
+      console.log("Health: unreachable");
+    }
+  }
+}
+
+function pad(str: string, width: number): string {
+  return str.padEnd(width);
+}

package/src/cli/commands/stop.ts

@@ -0,0 +1,84 @@
+/**
+ * auggy stop <name> — stop a running agent.
+ *
+ * Handles both dev (foreground) and launchd modes:
+ *   - dev: send SIGTERM, wait, SIGKILL if needed
+ *   - launchd: launchctl unload, clean up plist + symlink
+ */
+
+import { unlinkSync } from "node:fs";
+import { $ } from "bun";
+import { readPidManifest, removePidManifest, isProcessAlive } from "../pid-registry";
+import { plistStorePath, plistInstallPath } from "../plist-generator";
+
+export async function runStop(name: string): Promise<void> {
+  const manifest = readPidManifest(name);
+
+  if (!manifest) {
+    console.log(`Agent "${name}" is not running.`);
+    return;
+  }
+
+  if (manifest.mode === "launchd") {
+    await stopLaunchd(name, manifest.pid);
+  } else {
+    await stopDev(name, manifest.pid);
+  }
+}
+
+async function stopLaunchd(name: string, pid: number): Promise<void> {
+  const installPath = plistInstallPath(name);
+  const storePath = plistStorePath(name);
+
+  // Unload the launchd service.
+  try {
+    await $`launchctl unload ${installPath}`.quiet();
+  } catch {}
+
+  // Wait for the process to exit.
+  let waited = 0;
+  while (isProcessAlive(pid) && waited < 5000) {
+    await Bun.sleep(250);
+    waited += 250;
+  }
+
+  // Clean up plist files.
+  try {
+    unlinkSync(installPath);
+  } catch {}
+  try {
+    unlinkSync(storePath);
+  } catch {}
+
+  // Clean up PID manifest.
+  removePidManifest(name);
+
+  console.log(`Agent "${name}" stopped (was launchd-managed).`);
+}
+
+async function stopDev(name: string, pid: number): Promise<void> {
+  if (!isProcessAlive(pid)) {
+    removePidManifest(name);
+    console.log(`Agent "${name}" was not running (stale PID ${pid} cleaned up).`);
+    return;
+  }
+
+  // Send SIGTERM for graceful shutdown.
+  process.kill(pid, "SIGTERM");
+
+  // Wait up to 5s for graceful shutdown.
+  let waited = 0;
+  while (isProcessAlive(pid) && waited < 5000) {
+    await Bun.sleep(250);
+    waited += 250;
+  }
+
+  // Force kill if still alive.
+  if (isProcessAlive(pid)) {
+    process.kill(pid, "SIGKILL");
+    await Bun.sleep(500);
+  }
+
+  removePidManifest(name);
+  console.log(`Agent "${name}" stopped.`);
+}