auggy 0.3.0

package/src/cli/commands/add-skill.ts

@@ -0,0 +1,194 @@
+/**
+ * auggy add-skill <augment> — install a bundled augment skill into an agent.
+ *
+ * Companion command to the boot-time skill validator (PR α task 7) and the
+ * scaffold-time auto-copy in `auggy create` / `auggy add`. When an operator
+ * has an augment configured but no `skills/<augment>/SKILL.md` mounted (the
+ * augment was added before bundled-skill copying existed, an upgrade brought
+ * a new skill the operator wants, or the operator manually deleted the
+ * folder), this command copies `src/augments/<augment>/skill/*` into the
+ * agent directory at `<agent-dir>/skills/<augment>/`.
+ *
+ * The argument is the augment FOLDER NAME (kebab-case) — what the boot-time
+ * validator emits in its remediation hint and what shows up under
+ * `<agent-dir>/skills/`. Example: `auggy add-skill web-fetch`, NOT
+ * `auggy add-skill webFetch` (the camelCase YAML `type:` field).
+ *
+ * Per ADR-025 Decision 5 + spec Decision 7. Idempotent — re-running
+ * overwrites existing skill files (operator opt-in to updates).
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Command } from "commander";
+import { copyBundledSkill, augmentFolderForType } from "../scaffold-skills";
+import { getAgent } from "../agent-index";
+
+/**
+ * Inverse of `TYPE_TO_AUGMENT_FOLDER` exported via `augmentFolderForType`:
+ * we need the camelCase `type:` for `copyBundledSkill`, but the operator
+ * passes the folder name. The set of folder names is the canonical list of
+ * valid `<augment>` arguments. Built lazily so the data lives in one place
+ * (scaffold-skills.ts) and we don't drift.
+ */
+const KNOWN_TYPES = [
+  "filesystem",
+  "layeredMemory",
+  "webFetch",
+  "orgContext",
+  "bash",
+  "notify",
+  "turnControl",
+  "fileMemory",
+  "supabaseMemory",
+  "budgets",
+  "webTransport",
+  "telegramTransport",
+] as const;
+
+function buildFolderToTypeMap(): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const type of KNOWN_TYPES) {
+    const folder = augmentFolderForType(type);
+    if (folder) map.set(folder, type);
+  }
+  return map;
+}
+
+/**
+ * Resolve the on-disk path to the bundled skill SKILL.md for a folder, used
+ * to verify the augment ships a skill at all before attempting to copy.
+ */
+function bundledSkillExists(folder: string): boolean {
+  const dir = resolve(import.meta.dir, "../../augments", folder, "skill", "SKILL.md");
+  return existsSync(dir);
+}
+
+interface ResolveAgentDirOptions {
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+  /** Override CWD for tests. Defaults to process.cwd(). */
+  cwd?: string;
+}
+
+/**
+ * Resolve the agent directory from the optional --agent flag or CWD.
+ *
+ * - With `--agent <name>`: look up the registered agent in the index.
+ * - Without: use CWD; require an `agent.yaml` to be present so we don't
+ *   silently create a `skills/` directory in the wrong place.
+ */
+export function resolveAgentDir(
+  agentNameFlag: string | undefined,
+  opts: ResolveAgentDirOptions = {},
+): string {
+  if (agentNameFlag) {
+    const entry = getAgent(agentNameFlag, { auggyDir: opts.auggyDir });
+    if (!entry) {
+      throw new Error(
+        `Agent "${agentNameFlag}" is not registered.\n\n` +
+          `  Run \`auggy ls\` to see registered agents.`,
+      );
+    }
+    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 ${agentNameFlag}\` to clean up the index entry.`,
+      );
+    }
+    return entry.localDir;
+  }
+
+  const cwd = opts.cwd ?? process.cwd();
+  const agentYaml = join(cwd, "agent.yaml");
+  if (!existsSync(agentYaml)) {
+    throw new Error(
+      `Not an agent directory: no agent.yaml in ${cwd}.\n\n` +
+        `  Run from inside an agent dir, or pass \`--agent <name>\` to target a registered agent.`,
+    );
+  }
+  return cwd;
+}
+
+interface AddSkillCommandDeps {
+  /** Override exit so tests can assert the exit code without crashing the runner. */
+  exit?: (code: number) => void;
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+  /** Override CWD for tests. */
+  cwd?: string;
+}
+
+export function addSkillCommand(deps: AddSkillCommandDeps = {}): Command {
+  const exit = deps.exit ?? ((code: number) => process.exit(code));
+
+  return new Command("add-skill")
+    .description("Install a bundled augment skill into an existing agent")
+    .argument("<augment>", "augment folder name (kebab-case), e.g. web-fetch, layered-memory, bash")
+    .option("--agent <name>", "registered agent name (defaults to current directory)")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Examples:",
+        "  cd my-agent && auggy add-skill web-fetch",
+        "  auggy add-skill layered-memory --agent zip",
+      ].join("\n"),
+    )
+    .action(async (augment: string, opts: { agent?: string }) => {
+      // 1. Resolve agent dir.
+      let agentDir: string;
+      try {
+        agentDir = resolveAgentDir(opts.agent, { auggyDir: deps.auggyDir, cwd: deps.cwd });
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        exit(1);
+        return;
+      }
+
+      // 2. Validate the augment folder name.
+      const folderToType = buildFolderToTypeMap();
+      const type = folderToType.get(augment);
+      if (!type) {
+        const valid = [...folderToType.keys()].sort().join(", ");
+        console.error(
+          `Error: Unknown augment "${augment}".\n\n` + `  Valid augment folder names: ${valid}`,
+        );
+        exit(1);
+        return;
+      }
+
+      // 3. Verify the augment ships a bundled skill.
+      if (!bundledSkillExists(augment)) {
+        console.error(`Error: "${augment}" augment ships no bundled skill. Nothing to add-skill.`);
+        exit(1);
+        return;
+      }
+
+      // 4. Copy via the shared helper. Idempotent (overwrites existing files).
+      let copied: boolean;
+      try {
+        copied = copyBundledSkill(type, agentDir);
+      } catch (err) {
+        console.error(`Error: failed to copy skill files: ${(err as Error).message}`);
+        exit(2);
+        return;
+      }
+
+      if (!copied) {
+        // Defensive — the bundledSkillExists check above should make this
+        // unreachable, but if copyBundledSkill returns false for any reason
+        // (e.g. mid-call filesystem disappearance) surface it as an error.
+        console.error(`Error: failed to copy bundled skill for "${augment}" (source not found).`);
+        exit(2);
+        return;
+      }
+
+      console.log(
+        `Installed bundled skill for "${augment}" -> ${join(agentDir, "skills", augment)}/`,
+      );
+      exit(0);
+    });
+}

package/src/cli/commands/add.ts

@@ -0,0 +1,87 @@
+/**
+ * auggy add — add augments to an existing agent.
+ *
+ * Lists currently installed vs available augments. User selects from
+ * available. Updates agent.yaml and copies bundled
+ * `src/augments/<name>/skill/` folders into the agent dir. Per ADR-030
+ * the skill listing is owned by the runtime's 'skills' augment surface,
+ * NOT injected into identity.md — so no identity-file rewrite happens
+ * here. The model picks up new skills automatically because the 'skills'
+ * augment rescans its mounted dir at every context() call.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { checkbox } from "@inquirer/prompts";
+import { getAvailableAugments, type CatalogEntry } from "../augment-catalog";
+import { copyBundledSkill } from "../scaffold-skills";
+import { resolveConfigPath } from "../resolve-config";
+
+export async function runAdd(name: string, opts: { config?: string }): Promise<void> {
+  const configPath = resolveConfigPath(name, opts.config);
+  const agentDir = dirname(configPath);
+
+  // Parse current config.
+  const raw = parseYaml(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+  const currentAugments = (raw.augments ?? []) as Array<{ type: string; name: string }>;
+
+  console.log(`Currently installed: ${currentAugments.map((a) => a.name).join(", ")}`);
+
+  // Find what's available to add.
+  const available = getAvailableAugments(currentAugments);
+
+  if (available.length === 0) {
+    console.log("All built-in augments are already installed.");
+    return;
+  }
+
+  // Interactive selection.
+  const selected = await checkbox<CatalogEntry>({
+    message: "Select augments to add:",
+    choices: available.map((entry) => ({
+      name: `${entry.label} — ${entry.description}`,
+      value: entry,
+    })),
+  });
+
+  if (selected.length === 0) {
+    console.log("No augments selected.");
+    return;
+  }
+
+  // Add to agent.yaml.
+  for (const entry of selected) {
+    currentAugments.push({
+      name: entry.defaultName,
+      type: entry.type,
+      ...({ options: entry.defaultOptions } as Record<string, unknown>),
+    } as { type: string; name: string });
+  }
+  raw.augments = currentAugments;
+
+  writeFileSync(configPath, `# Agent configuration\n\n${stringifyYaml(raw)}`);
+
+  // Install skills — copy the bundled `src/augments/<name>/skill/` folder
+  // for each selected augment that ships one. Idempotent. Per ADR-030 the
+  // 'skills' augment surfaces them to the model automatically by rescanning
+  // the skills/ dir on every context() call; no identity.md edit needed.
+  console.log();
+  for (const entry of selected) {
+    copyBundledSkill(entry.type, agentDir);
+    console.log(`  ✓ ${entry.defaultName} (${entry.type})`);
+  }
+
+  // Collect any new env vars needed.
+  const newEnvVars = selected.flatMap((e) => e.envVars ?? []);
+  if (newEnvVars.length > 0) {
+    console.log();
+    console.log("Add these to your .env:");
+    for (const v of newEnvVars) {
+      console.log(`  ${v}=`);
+    }
+  }
+
+  console.log();
+  console.log(`Restart to apply: auggy restart ${name}`);
+}

package/src/cli/commands/chat.ts

@@ -0,0 +1,207 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync, createWriteStream, createReadStream } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import packageJson from "../../../package.json" with { type: "json" };
+
+const DEFAULT_PORT = 8090;
+const RELEASE_REPO = "looselyorganized/augment-1";
+
+// Resolve the chat package directory relative to THIS module's location.
+// Uses import.meta.url so it works under both source-tree Bun runs and
+// future ESM-published builds.
+//
+// TODO(npm-packaging): when this CLI is published to npm, the chat/ package
+// won't be a sibling of src/cli/commands/. Two paths:
+//   a) Bundle chat/dist/ as a static asset in the published CLI tarball
+//      and point at the asset path here.
+//   b) Publish @auggy/chat as a separate npm package and use
+//      `require.resolve("@auggy/chat/server")` (after also exposing server.js
+//      as a package "exports" entry).
+// For now, the source-tree relative resolution is the only supported path.
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const CHAT_PACKAGE_DIR = resolve(MODULE_DIR, "../../../chat");
+
+export function chatCommand(): Command {
+  const cmd = new Command("chat")
+    .description("Launch the Auggy operator chat surface (Local GUI)")
+    .option("-p, --port <port>", "GUI server port", String(DEFAULT_PORT))
+    .option("--no-open", "Don't auto-open the browser")
+    .option("--rebuild", "Rebuild the GUI dist from source (requires Bun + Vite in chat/)")
+    .action(async (opts: { port: string; open: boolean; rebuild: boolean }) => {
+      const port = Number(opts.port);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        console.error(`Invalid --port value: ${opts.port}`);
+        process.exit(1);
+      }
+
+      const guiPackageDir = CHAT_PACKAGE_DIR;
+      const localDistDir = join(guiPackageDir, "dist");
+      const version = packageJson.version;
+      const cacheDistDir = join(homedir(), ".auggy", "chat", version, "dist");
+
+      // Lazy-load the chat server so a missing chat/ package (e.g. from an npm
+      // install that omits the chat/ directory) surfaces as a recoverable error
+      // instead of crashing the whole auggy CLI at module-load time.
+      let createGuiServer: typeof import("../../../chat/server").createGuiServer;
+      try {
+        ({ createGuiServer } = await import("../../../chat/server"));
+      } catch (err) {
+        console.error(
+          `[auggy chat] chat package not available: ${(err as Error).message}\n` +
+            `\n` +
+            `Recovery options:\n` +
+            `  • If you are running from source: cd ${guiPackageDir} && bun install\n` +
+            `  • If auggy was installed via npm and chat/ is missing, this is a\n` +
+            `    packaging bug — please file an issue.`,
+        );
+        process.exit(1);
+      }
+
+      let distDir: string;
+      try {
+        if (opts.rebuild) {
+          console.log("[auggy chat] Rebuilding chat/dist via Vite...");
+          await runVite(guiPackageDir);
+        }
+        distDir = await resolveDistDir({
+          localDistDir,
+          cacheDistDir,
+          version,
+        });
+      } catch (err) {
+        console.error(
+          `[auggy chat] chat dist not found or failed to resolve: ${(err as Error).message}\n` +
+            `\n` +
+            `Recovery options:\n` +
+            `  • If you are running from source: cd ${guiPackageDir} && bun install && bun run build\n` +
+            `  • Or pass --rebuild to do that automatically: auggy chat --rebuild\n` +
+            `  • If auggy was installed via npm and chat/ is missing, this is a\n` +
+            `    packaging bug — please file an issue.`,
+        );
+        process.exit(1);
+      }
+
+      let server: Awaited<ReturnType<typeof createGuiServer>>;
+      try {
+        server = createGuiServer({ port, staticDir: distDir });
+      } catch (err) {
+        console.error(
+          `[auggy chat] Failed to start server on port ${port}: ${(err as Error).message}\n` +
+            `Try a different port: auggy chat --port ${port + 1}`,
+        );
+        process.exit(1);
+      }
+
+      const url = `http://localhost:${port}`;
+      console.log(`[auggy chat] Local GUI ready at ${url}`);
+      console.log("[auggy chat] Ctrl-C to stop.");
+
+      if (opts.open) openBrowser(url);
+
+      const shutdown = (signal: string) => {
+        console.log(`\n[auggy chat] Received ${signal}, shutting down...`);
+        try {
+          server.stop();
+        } catch {
+          /* swallow */
+        }
+        process.exit(0);
+      };
+      process.on("SIGINT", () => shutdown("SIGINT"));
+      process.on("SIGTERM", () => shutdown("SIGTERM"));
+    });
+
+  return cmd;
+}
+
+async function resolveDistDir(opts: {
+  localDistDir: string;
+  cacheDistDir: string;
+  version: string;
+}): Promise<string> {
+  if (existsSync(join(opts.localDistDir, "index.html"))) return opts.localDistDir;
+  if (existsSync(join(opts.cacheDistDir, "index.html"))) return opts.cacheDistDir;
+
+  console.log(
+    `[auggy chat] No cached dist for version ${opts.version}; downloading from GitHub release...`,
+  );
+  await downloadAndCache(opts.version, opts.cacheDistDir);
+  if (!existsSync(join(opts.cacheDistDir, "index.html"))) {
+    throw new Error("download succeeded but dist/index.html not found after extraction");
+  }
+  return opts.cacheDistDir;
+}
+
+async function downloadAndCache(version: string, cacheDistDir: string): Promise<void> {
+  const tag = `v${version}`;
+  const tarballUrl = `https://github.com/${RELEASE_REPO}/releases/download/${tag}/chat-dist-${tag}.tar.gz`;
+  const checksumUrl = `${tarballUrl}.sha256`;
+
+  const cacheRoot = join(cacheDistDir, "..");
+  mkdirSync(cacheRoot, { recursive: true });
+
+  const tarballPath = join(cacheRoot, "dist.tar.gz");
+  const tarRes = await fetch(tarballUrl);
+  if (!tarRes.ok || !tarRes.body) {
+    throw new Error(`Download failed: ${tarRes.status} ${tarRes.statusText} from ${tarballUrl}`);
+  }
+  await pipeline(tarRes.body as unknown as NodeJS.ReadableStream, createWriteStream(tarballPath));
+
+  const checksumRes = await fetch(checksumUrl);
+  if (!checksumRes.ok) {
+    throw new Error(`Failed to fetch checksum: ${checksumRes.status} ${checksumRes.statusText}`);
+  }
+  const checksumLine = await checksumRes.text();
+  const expectedSha = checksumLine.split(/\s+/)[0];
+  const actualSha = await sha256File(tarballPath);
+  if (expectedSha !== actualSha) {
+    throw new Error(`Checksum mismatch: expected ${expectedSha}, got ${actualSha}`);
+  }
+
+  await runTar(tarballPath, cacheRoot);
+}
+
+function sha256File(path: string): Promise<string> {
+  return new Promise((resolveP, rejectP) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(path);
+    stream.on("data", (chunk: Buffer | string) => hash.update(chunk));
+    stream.on("end", () => resolveP(hash.digest("hex")));
+    stream.on("error", rejectP);
+  });
+}
+
+function runTar(tarballPath: string, destDir: string): Promise<void> {
+  return new Promise((resolveP, rejectP) => {
+    const child = spawn("tar", ["-xzf", tarballPath, "-C", destDir], {
+      stdio: "inherit",
+    });
+    child.on("exit", (code) => (code === 0 ? resolveP() : rejectP(new Error(`tar exit ${code}`))));
+    child.on("error", rejectP);
+  });
+}
+
+function runVite(cwd: string): Promise<void> {
+  return new Promise((resolveP, rejectP) => {
+    const child = spawn("bun", ["run", "build"], { cwd, stdio: "inherit" });
+    child.on("exit", (code) =>
+      code === 0 ? resolveP() : rejectP(new Error(`Vite build exit ${code}`)),
+    );
+    child.on("error", rejectP);
+  });
+}
+
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+  try {
+    spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    /* best-effort */
+  }
+}