@answerloops/agent-sdk 0.5.0 → 0.6.0

package/README.md

@@ -1,8 +1,32 @@
 # @answerloops/agent-sdk
 
-Typed Node/browser client for the [answerLoops Agent API](https://answerloops.com/docs/integrations/agent-api) — search the knowledge base, read the FAQ digest, list/create tickets, and generate grounded answers.
+Typed Node/browser client for the [answerLoops Agent API](https://answerloops.com/docs/integrations/agent-api) — search the knowledge base, read the FAQ digest, list/create tickets, and generate grounded answers. Also ships a CLI (`answerloops`) that bootstraps a self-hosted instance or installs the [Claude Code agent skills](https://answerloops.com/docs/integrations/agent-skills).
 
-## Install
+## Getting started
+
+Don't have a running answerLoops instance yet? Bootstrap one:
+
+```bash
+npx @answerloops/agent-sdk setup
+```
+
+Clones the repo if needed, checks Docker + git are present, generates
+`AUTH_SECRET`/`ENCRYPTION_KEY`, starts the published image via Docker
+Compose, and polls `/api/health` until it's actually up. It never invents a
+real credential — if `DATABASE_URL`, `AUTH_URL`, or the Google OAuth pair are
+missing, it tells you exactly what to add to `.env` and exits, rather than
+guessing.
+
+Already have a workspace (hosted or self-hosted) and just want an agent
+connected to it? Install the Claude Code skills instead:
+
+```bash
+npx @answerloops/agent-sdk skills answerloops-setup answerloops-operate
+```
+
+Writes both into `.claude/skills/` — install just one by naming it alone.
+
+Building against the API directly instead? Install the library:
 
 ```bash
 npm install @answerloops/agent-sdk

package/dist/cli/index.cjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/index.ts
+var import_node_util = require("util");
+
+// src/cli/setup.ts
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
+
+// src/cli/util.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(`\u2717 ${msg}`);
+  process.exit(1);
+}
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+function commandExists(cmd, args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(cmd, args, { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+function fileExists(path) {
+  return (0, import_node_fs.existsSync)(path);
+}
+
+// src/cli/prereqs.ts
+async function checkPrereqs() {
+  const missing = [];
+  if (!await commandExists("git", ["--version"])) {
+    missing.push("git \u2014 https://git-scm.com/downloads");
+  }
+  if (!await commandExists("docker", ["--version"])) {
+    missing.push("Docker \u2014 https://docs.docker.com/get-docker/");
+  } else if (!await commandExists("docker", ["compose", "version"])) {
+    missing.push("Docker Compose v2 \u2014 update Docker Desktop or install the compose plugin");
+  }
+  if (missing.length > 0) {
+    for (const m of missing) console.error(`\u2717 ${m}`);
+    fail("Missing prerequisites. Install the above, then re-run.");
+  }
+  log("\u2713 git and Docker (with Compose v2) found");
+}
+
+// src/cli/repo.ts
+var import_node_path = require("path");
+var REPO_URL = "https://github.com/answerLoops/answerLoops.git";
+var MARKER = "docker-compose.ghcr.yml";
+async function ensureRepo(targetDir) {
+  if (fileExists((0, import_node_path.join)(process.cwd(), MARKER))) {
+    return process.cwd();
+  }
+  if (fileExists((0, import_node_path.join)(targetDir, MARKER))) {
+    log(`\u2713 using existing checkout at ${targetDir}`);
+    return targetDir;
+  }
+  log(`Cloning ${REPO_URL} into ${targetDir}...`);
+  const code = await run("git", ["clone", REPO_URL, targetDir]);
+  if (code !== 0) fail(`git clone failed (exit ${code})`);
+  return targetDir;
+}
+
+// src/cli/env.ts
+var import_node_crypto = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var REQUIRED_VARS = ["DATABASE_URL", "AUTH_URL", "AUTH_GOOGLE_ID", "AUTH_GOOGLE_SECRET"];
+var HOW_TO_GET = {
+  DATABASE_URL: "a Postgres connection string you run and control, e.g. postgresql://user:pass@host:5432/db",
+  AUTH_URL: "the public URL this instance will be reachable at, e.g. http://localhost:3000",
+  AUTH_GOOGLE_ID: "a Google OAuth client ID \u2014 console.cloud.google.com, register callback {AUTH_URL}/api/auth/callback/google",
+  AUTH_GOOGLE_SECRET: "the matching Google OAuth client secret from the same client"
+};
+function parseEnvFile(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) return {};
+  const out = {};
+  for (const line of (0, import_node_fs2.readFileSync)(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+function genSecret() {
+  return (0, import_node_crypto.randomBytes)(32).toString("hex");
+}
+function ensureEnv(repoDir) {
+  const envPath = (0, import_node_path2.join)(repoDir, ".env");
+  const existing = parseEnvFile(envPath);
+  const toAppend = [];
+  for (const secretVar of ["AUTH_SECRET", "ENCRYPTION_KEY"]) {
+    if (!existing[secretVar] && !process.env[secretVar]) {
+      const value = genSecret();
+      toAppend.push(`${secretVar}=${value}`);
+      log(`\u2713 generated ${secretVar}`);
+    }
+  }
+  if (toAppend.length > 0) {
+    (0, import_node_fs2.appendFileSync)(envPath, ((0, import_node_fs2.existsSync)(envPath) ? "\n" : "") + toAppend.join("\n") + "\n");
+  } else if (!(0, import_node_fs2.existsSync)(envPath)) {
+    (0, import_node_fs2.writeFileSync)(envPath, "");
+  }
+  const missing = REQUIRED_VARS.filter((v) => !existing[v] && !process.env[v]);
+  if (missing.length > 0) {
+    console.error(`Missing required configuration in ${envPath}:`);
+    for (const v of missing) console.error(`  ${v} \u2014 ${HOW_TO_GET[v]}`);
+    console.error(
+      `
+Add these to ${envPath} (or export them before running this command), then re-run.`
+    );
+    fail("Required environment variables not set.");
+  }
+  log(`\u2713 ${envPath} has everything required`);
+}
+
+// src/cli/health.ts
+async function waitForHealth(url, timeoutSeconds = 120) {
+  const intervalMs = 3e3;
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  log(`Waiting for ${url} to become healthy (timeout ${timeoutSeconds}s)...`);
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        log(`\u2713 healthy`);
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  fail(
+    `${url} still unhealthy after ${timeoutSeconds}s. Check logs: docker compose -f docker-compose.ghcr.yml logs app -f`
+  );
+}
+
+// src/cli/skills.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var RAW_BASE = "https://raw.githubusercontent.com/answerLoops/answerLoops/main";
+var SKILLS = {
+  "answerloops-setup": ["skills/setup/SKILL.md"],
+  "answerloops-operate": ["skills/operate/SKILL.md"]
+};
+async function installSkills(names) {
+  for (const name of names) {
+    const files = SKILLS[name];
+    if (!files) fail(`Unknown skill "${name}". Known: ${Object.keys(SKILLS).join(", ")}`);
+    const destDir = (0, import_node_path3.join)(".claude", "skills", name);
+    (0, import_node_fs3.mkdirSync)(destDir, { recursive: true });
+    for (const relPath of files) {
+      const url = `${RAW_BASE}/${relPath}`;
+      const res = await fetch(url);
+      if (!res.ok) fail(`Could not fetch ${url} (${res.status})`);
+      const body = await res.text();
+      const destPath = (0, import_node_path3.join)(destDir, relPath.split("/").pop());
+      (0, import_node_fs3.writeFileSync)(destPath, body);
+    }
+    log(`\u2713 installed ${name} -> ${destDir}`);
+  }
+}
+
+// src/cli/setup.ts
+async function runSetup(opts) {
+  await checkPrereqs();
+  const repoDir = await ensureRepo(opts.targetDir);
+  ensureEnv(repoDir);
+  log("Starting the stack (docker compose -f docker-compose.ghcr.yml up -d)...");
+  const code = await run("docker", ["compose", "-f", "docker-compose.ghcr.yml", "up", "-d"], {
+    cwd: repoDir
+  });
+  if (code !== 0) fail(`docker compose up failed (exit ${code})`);
+  const authUrl = readAuthUrl(repoDir) ?? "http://localhost:3000";
+  await waitForHealth(`${authUrl.replace(/\/+$/, "")}/api/health`);
+  if (opts.withSkills) {
+    await installSkills(["answerloops-setup", "answerloops-operate"]);
+  }
+  log(`
+Your instance is live at ${authUrl}. Sign in with Google and complete onboarding.`);
+}
+function readAuthUrl(repoDir) {
+  try {
+    const text = (0, import_node_fs4.readFileSync)((0, import_node_path4.join)(repoDir, ".env"), "utf8");
+    const line = text.split("\n").find((l) => l.trim().startsWith("AUTH_URL="));
+    return line?.slice(line.indexOf("=") + 1).trim();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/cli/index.ts
+var USAGE = `Usage: answerloops <command> [options]
+
+Commands:
+  setup                Bootstrap a self-hosted answerLoops instance (Docker,
+                        the published image). Requires Docker + git.
+    --dir <path>          Directory to clone into if not already in a
+                           checkout (default: ./answerLoops)
+    --with-skills          Also install the Claude Code setup + operate
+                           skills into ./.claude/skills/
+
+  skills <name...>     Install one or more Claude Code skills into
+                        ./.claude/skills/. Names: answerloops-setup,
+                        answerloops-operate
+
+  help                 Show this message
+`;
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "setup": {
+      const { values } = (0, import_node_util.parseArgs)({
+        args: rest,
+        options: {
+          dir: { type: "string", default: "answerLoops" },
+          "with-skills": { type: "boolean", default: false }
+        }
+      });
+      await runSetup({ targetDir: values.dir, withSkills: values["with-skills"] });
+      break;
+    }
+    case "skills": {
+      if (rest.length === 0) {
+        console.error("Usage: answerloops skills <name...>");
+        process.exit(1);
+      }
+      await installSkills(rest);
+      break;
+    }
+    case "help":
+    case void 0:
+    case "--help":
+    case "-h":
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command "${command}"
+`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/cli/index.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { parseArgs } from "util";
+
+// src/cli/setup.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/cli/util.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(`\u2717 ${msg}`);
+  process.exit(1);
+}
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+function commandExists(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+function fileExists(path) {
+  return existsSync(path);
+}
+
+// src/cli/prereqs.ts
+async function checkPrereqs() {
+  const missing = [];
+  if (!await commandExists("git", ["--version"])) {
+    missing.push("git \u2014 https://git-scm.com/downloads");
+  }
+  if (!await commandExists("docker", ["--version"])) {
+    missing.push("Docker \u2014 https://docs.docker.com/get-docker/");
+  } else if (!await commandExists("docker", ["compose", "version"])) {
+    missing.push("Docker Compose v2 \u2014 update Docker Desktop or install the compose plugin");
+  }
+  if (missing.length > 0) {
+    for (const m of missing) console.error(`\u2717 ${m}`);
+    fail("Missing prerequisites. Install the above, then re-run.");
+  }
+  log("\u2713 git and Docker (with Compose v2) found");
+}
+
+// src/cli/repo.ts
+import { join } from "path";
+var REPO_URL = "https://github.com/answerLoops/answerLoops.git";
+var MARKER = "docker-compose.ghcr.yml";
+async function ensureRepo(targetDir) {
+  if (fileExists(join(process.cwd(), MARKER))) {
+    return process.cwd();
+  }
+  if (fileExists(join(targetDir, MARKER))) {
+    log(`\u2713 using existing checkout at ${targetDir}`);
+    return targetDir;
+  }
+  log(`Cloning ${REPO_URL} into ${targetDir}...`);
+  const code = await run("git", ["clone", REPO_URL, targetDir]);
+  if (code !== 0) fail(`git clone failed (exit ${code})`);
+  return targetDir;
+}
+
+// src/cli/env.ts
+import { randomBytes } from "crypto";
+import { existsSync as existsSync2, readFileSync, appendFileSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var REQUIRED_VARS = ["DATABASE_URL", "AUTH_URL", "AUTH_GOOGLE_ID", "AUTH_GOOGLE_SECRET"];
+var HOW_TO_GET = {
+  DATABASE_URL: "a Postgres connection string you run and control, e.g. postgresql://user:pass@host:5432/db",
+  AUTH_URL: "the public URL this instance will be reachable at, e.g. http://localhost:3000",
+  AUTH_GOOGLE_ID: "a Google OAuth client ID \u2014 console.cloud.google.com, register callback {AUTH_URL}/api/auth/callback/google",
+  AUTH_GOOGLE_SECRET: "the matching Google OAuth client secret from the same client"
+};
+function parseEnvFile(path) {
+  if (!existsSync2(path)) return {};
+  const out = {};
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+function genSecret() {
+  return randomBytes(32).toString("hex");
+}
+function ensureEnv(repoDir) {
+  const envPath = join2(repoDir, ".env");
+  const existing = parseEnvFile(envPath);
+  const toAppend = [];
+  for (const secretVar of ["AUTH_SECRET", "ENCRYPTION_KEY"]) {
+    if (!existing[secretVar] && !process.env[secretVar]) {
+      const value = genSecret();
+      toAppend.push(`${secretVar}=${value}`);
+      log(`\u2713 generated ${secretVar}`);
+    }
+  }
+  if (toAppend.length > 0) {
+    appendFileSync(envPath, (existsSync2(envPath) ? "\n" : "") + toAppend.join("\n") + "\n");
+  } else if (!existsSync2(envPath)) {
+    writeFileSync(envPath, "");
+  }
+  const missing = REQUIRED_VARS.filter((v) => !existing[v] && !process.env[v]);
+  if (missing.length > 0) {
+    console.error(`Missing required configuration in ${envPath}:`);
+    for (const v of missing) console.error(`  ${v} \u2014 ${HOW_TO_GET[v]}`);
+    console.error(
+      `
+Add these to ${envPath} (or export them before running this command), then re-run.`
+    );
+    fail("Required environment variables not set.");
+  }
+  log(`\u2713 ${envPath} has everything required`);
+}
+
+// src/cli/health.ts
+async function waitForHealth(url, timeoutSeconds = 120) {
+  const intervalMs = 3e3;
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  log(`Waiting for ${url} to become healthy (timeout ${timeoutSeconds}s)...`);
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        log(`\u2713 healthy`);
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  fail(
+    `${url} still unhealthy after ${timeoutSeconds}s. Check logs: docker compose -f docker-compose.ghcr.yml logs app -f`
+  );
+}
+
+// src/cli/skills.ts
+import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
+var RAW_BASE = "https://raw.githubusercontent.com/answerLoops/answerLoops/main";
+var SKILLS = {
+  "answerloops-setup": ["skills/setup/SKILL.md"],
+  "answerloops-operate": ["skills/operate/SKILL.md"]
+};
+async function installSkills(names) {
+  for (const name of names) {
+    const files = SKILLS[name];
+    if (!files) fail(`Unknown skill "${name}". Known: ${Object.keys(SKILLS).join(", ")}`);
+    const destDir = join3(".claude", "skills", name);
+    mkdirSync(destDir, { recursive: true });
+    for (const relPath of files) {
+      const url = `${RAW_BASE}/${relPath}`;
+      const res = await fetch(url);
+      if (!res.ok) fail(`Could not fetch ${url} (${res.status})`);
+      const body = await res.text();
+      const destPath = join3(destDir, relPath.split("/").pop());
+      writeFileSync2(destPath, body);
+    }
+    log(`\u2713 installed ${name} -> ${destDir}`);
+  }
+}
+
+// src/cli/setup.ts
+async function runSetup(opts) {
+  await checkPrereqs();
+  const repoDir = await ensureRepo(opts.targetDir);
+  ensureEnv(repoDir);
+  log("Starting the stack (docker compose -f docker-compose.ghcr.yml up -d)...");
+  const code = await run("docker", ["compose", "-f", "docker-compose.ghcr.yml", "up", "-d"], {
+    cwd: repoDir
+  });
+  if (code !== 0) fail(`docker compose up failed (exit ${code})`);
+  const authUrl = readAuthUrl(repoDir) ?? "http://localhost:3000";
+  await waitForHealth(`${authUrl.replace(/\/+$/, "")}/api/health`);
+  if (opts.withSkills) {
+    await installSkills(["answerloops-setup", "answerloops-operate"]);
+  }
+  log(`
+Your instance is live at ${authUrl}. Sign in with Google and complete onboarding.`);
+}
+function readAuthUrl(repoDir) {
+  try {
+    const text = readFileSync2(join4(repoDir, ".env"), "utf8");
+    const line = text.split("\n").find((l) => l.trim().startsWith("AUTH_URL="));
+    return line?.slice(line.indexOf("=") + 1).trim();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/cli/index.ts
+var USAGE = `Usage: answerloops <command> [options]
+
+Commands:
+  setup                Bootstrap a self-hosted answerLoops instance (Docker,
+                        the published image). Requires Docker + git.
+    --dir <path>          Directory to clone into if not already in a
+                           checkout (default: ./answerLoops)
+    --with-skills          Also install the Claude Code setup + operate
+                           skills into ./.claude/skills/
+
+  skills <name...>     Install one or more Claude Code skills into
+                        ./.claude/skills/. Names: answerloops-setup,
+                        answerloops-operate
+
+  help                 Show this message
+`;
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "setup": {
+      const { values } = parseArgs({
+        args: rest,
+        options: {
+          dir: { type: "string", default: "answerLoops" },
+          "with-skills": { type: "boolean", default: false }
+        }
+      });
+      await runSetup({ targetDir: values.dir, withSkills: values["with-skills"] });
+      break;
+    }
+    case "skills": {
+      if (rest.length === 0) {
+        console.error("Usage: answerloops skills <name...>");
+        process.exit(1);
+      }
+      await installSkills(rest);
+      break;
+    }
+    case "help":
+    case void 0:
+    case "--help":
+    case "-h":
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command "${command}"
+`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@answerloops/agent-sdk",
-  "version": "0.5.0",
-  "description": "Typed client for the answerLoops Agent API (knowledge base search, FAQ, tickets, grounded answers).",
+  "version": "0.6.0",
+  "description": "Typed client for the answerLoops Agent API (knowledge base search, FAQ, tickets, grounded answers) and a CLI to self-host answerLoops or install its Claude Code skills.",
   "license": "AGPL-3.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "answerloops": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,7 +41,7 @@
     "knowledge-base"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/cli/index.ts --format esm,cjs --dts --clean && chmod +x dist/cli/index.js",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {