@agentskit/cli 0.13.9 → 0.13.12

package/dist/bin.cjs

@@ -154,7 +154,7 @@ function createDemoAdapter(provider, model) {
           ].join(" ");
           for (const chunk of reply.match(/.{1,18}/g) ?? []) {
             if (cancelled) return;
-            await new Promise((resolve6) => setTimeout(resolve6, 35));
+            await new Promise((resolve7) => setTimeout(resolve7, 35));
             yield { type: "text", content: chunk };
           }
           yield { type: "done" };
@@ -4036,11 +4036,11 @@ function scaffoldAgent(schema) {
 }
 async function writeScaffold(files, outDir, opts = {}) {
   const { writeFile: writeFile5, mkdir: mkdir5, access } = await import('fs/promises');
-  const { dirname: dirname4, join: join8 } = await import('path');
+  const { dirname: dirname5, join: join11 } = await import('path');
   const written = [];
   for (const f of files) {
-    const full = join8(outDir, f.path);
-    await mkdir5(dirname4(full), { recursive: true });
+    const full = join11(outDir, f.path);
+    await mkdir5(dirname5(full), { recursive: true });
     if (!opts.overwrite) {
       try {
         await access(full);
@@ -4709,8 +4709,22 @@ async function defaultExists(path5) {
     return false;
   }
 }
+function assertInstallable(agent) {
+  if (agent.status === "draft" || agent.installable === false) {
+    throw new Error(
+      `"${agent.id}" is a catalog draft \u2014 not installable yet. Browse the roadmap at https://registry.agentskit.io/r/catalog.json`
+    );
+  }
+  if (agent.status === "alpha") {
+    console.warn(`[agentskit] "${agent.id}" is alpha \u2014 experimental; review before production use.`);
+  }
+  if (agent.status === "deprecated") {
+    throw new Error(`"${agent.id}" is deprecated and no longer installable from the registry.`);
+  }
+}
 async function addAgent(id, options = {}) {
   const agent = await fetchAgent(id, options);
+  assertInstallable(agent);
   const baseDir = options.outDir ?? "agents";
   const targetDir = path.join(baseDir, id);
   const exists = options.existsImpl ?? defaultExists;
@@ -4782,14 +4796,767 @@ async function diffAgent(id, options = {}) {
   }
   return { agent, targetDir, files };
 }
+function allDeps(pkg) {
+  if (!pkg) return {};
+  return { ...pkg.peerDependencies, ...pkg.devDependencies, ...pkg.dependencies };
+}
+function readJson(fs, path5) {
+  const raw = fs.readFile(path5);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function detectPackageManager(fs, root) {
+  if (fs.exists(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.exists(path.join(root, "bun.lockb")) || fs.exists(path.join(root, "bun.lock"))) return "bun";
+  if (fs.exists(path.join(root, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function detectUiBinding(deps) {
+  const has = (name) => name in deps;
+  if (has("react-native") || has("expo")) return "react-native";
+  if (has("@angular/core")) return "angular";
+  if (has("svelte")) return "svelte";
+  if (has("nuxt") || has("vue")) return "vue";
+  if (has("solid-js")) return "solid";
+  if (has("ink")) return "ink";
+  if (has("react")) return "react";
+  return "unknown";
+}
+function detectMetaFramework(fs, root, deps, uiBinding) {
+  const has = (name) => name in deps;
+  const hasPrefix = (prefix) => Object.keys(deps).some((d) => d.startsWith(prefix));
+  if (has("next")) {
+    if (fs.exists(path.join(root, "app")) || fs.exists(path.join(root, "src/app"))) return "next-app";
+    return "next-pages";
+  }
+  if (hasPrefix("@remix-run/")) return "remix";
+  if (has("@tanstack/react-start") || has("@tanstack/start")) return "tanstack-start";
+  if (has("@sveltejs/kit")) return "sveltekit";
+  if (has("nuxt")) return "nuxt";
+  if (has("astro")) return "astro";
+  if (uiBinding === "angular") {
+    return has("@angular/ssr") || has("@angular/platform-server") ? "angular-ssr" : "angular-spa";
+  }
+  if (has("expo")) return "expo";
+  if (has("react-scripts")) return "cra";
+  if (has("vite")) return "vite";
+  if (uiBinding === "ink") return "node";
+  if (uiBinding === "unknown") return "unknown";
+  return "none";
+}
+function detectImportAlias(fs, root) {
+  const tsconfig = readJson(
+    fs,
+    path.join(root, "tsconfig.json")
+  );
+  const paths = tsconfig?.compilerOptions?.paths;
+  if (!paths) return null;
+  for (const key of Object.keys(paths)) {
+    if (key.endsWith("/*")) return key.slice(0, -2);
+  }
+  return null;
+}
+var CSS_ENTRY_CANDIDATES = [
+  "app/globals.css",
+  "app/global.css",
+  "src/app/globals.css",
+  "src/index.css",
+  "src/styles/globals.css",
+  "styles/globals.css",
+  "src/app.css",
+  "src/styles.css"
+];
+function detectStyling(fs, root, deps) {
+  const tailwind = "tailwindcss" in deps || fs.exists(path.join(root, "tailwind.config.ts")) || fs.exists(path.join(root, "tailwind.config.js")) || fs.exists(path.join(root, "tailwind.config.cjs")) || fs.exists(path.join(root, "tailwind.config.mjs"));
+  let cssEntry = null;
+  for (const candidate of CSS_ENTRY_CANDIDATES) {
+    if (fs.exists(path.join(root, candidate))) {
+      cssEntry = candidate;
+      break;
+    }
+  }
+  return { mode: tailwind ? "tailwind-preset" : "data-attrs-only", cssEntry };
+}
+function detectMonorepo(fs, root) {
+  if (fs.exists(path.join(root, "pnpm-workspace.yaml"))) return { tool: "pnpm", root };
+  if (fs.exists(path.join(root, "turbo.json"))) return { tool: "turbo", root };
+  if (fs.exists(path.join(root, "nx.json"))) return { tool: "nx", root };
+  return null;
+}
+function scanProject(fs, root = ".") {
+  const pkg = readJson(fs, path.join(root, "package.json"));
+  const deps = allDeps(pkg);
+  const uiBinding = detectUiBinding(deps);
+  const metaFramework = detectMetaFramework(fs, root, deps, uiBinding);
+  const srcDir = fs.exists(path.join(root, "src")) ? "src" : null;
+  return {
+    uiBinding,
+    metaFramework,
+    packageManager: detectPackageManager(fs, root),
+    typescript: fs.exists(path.join(root, "tsconfig.json")),
+    srcDir,
+    importAlias: detectImportAlias(fs, root),
+    styling: detectStyling(fs, root, deps),
+    monorepo: detectMonorepo(fs, root)
+  };
+}
+var CONFIG_PATH = ".agentskit/components.json";
+var SCHEMA_URL = "https://raw.githubusercontent.com/AgentsKit-io/agentskit-registry/v1/schema/components.json";
+var DEFAULT_REGISTRY = "https://registry.agentskit.io";
+var SERVER_DIR_BY_META = {
+  "next-app": "app/api",
+  "next-pages": "pages/api",
+  remix: "app/routes",
+  "tanstack-start": "app/routes",
+  astro: "src/pages/api",
+  sveltekit: "src/routes/api",
+  nuxt: "server/api",
+  "angular-ssr": "src/server",
+  expo: "server",
+  vite: "server",
+  cra: "server",
+  "angular-spa": "server",
+  node: "server",
+  none: "server"
+};
+function joinPath(base, sub) {
+  return base ? `${base}/${sub}` : sub;
+}
+function buildConfig(scan) {
+  const uiBinding = scan.uiBinding === "unknown" ? "react" : scan.uiBinding;
+  const metaFramework = scan.metaFramework === "unknown" ? "none" : scan.metaFramework;
+  const srcBase = scan.srcDir ?? "";
+  const componentsPath = joinPath(srcBase, "components");
+  const libPath = joinPath(srcBase, "lib");
+  const rawServer = SERVER_DIR_BY_META[metaFramework];
+  const serverPath = srcBase && (metaFramework === "next-app" || metaFramework === "next-pages") && !rawServer.startsWith("src/") ? joinPath(srcBase, rawServer) : rawServer;
+  const alias = scan.importAlias;
+  return {
+    $schema: SCHEMA_URL,
+    schemaVersion: 1,
+    uiBinding,
+    metaFramework,
+    typescript: scan.typescript,
+    styling: {
+      mode: scan.styling.mode,
+      css: scan.styling.cssEntry ?? "app/globals.css",
+      tailwindConfig: null
+    },
+    aliases: {
+      // components + lib are import-aliased when the project has one; the server
+      // route is a framework-routed filesystem location, so it mirrors its path.
+      components: alias ? `${alias}/components` : `./${componentsPath}`,
+      lib: alias ? `${alias}/lib` : `./${libPath}`,
+      server: serverPath
+    },
+    paths: {
+      root: scan.monorepo?.root ?? ".",
+      components: componentsPath,
+      lib: libPath,
+      server: serverPath
+    },
+    registries: { default: DEFAULT_REGISTRY }
+  };
+}
+function serializeConfig(config) {
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+function parseConfig(raw) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object") return null;
+  const c = data;
+  if (typeof c.schemaVersion !== "number" || !c.uiBinding || !c.metaFramework || !c.registries) {
+    return null;
+  }
+  return c;
+}
+function readConfig(io, root = ".") {
+  const raw = io.read(path.join(root, CONFIG_PATH));
+  return raw == null ? null : parseConfig(raw);
+}
+function writeConfig(io, config, root = ".") {
+  const path5 = path.join(root, CONFIG_PATH);
+  io.write(path5, serializeConfig(config));
+  return path5;
+}
+function resolveConfig(io, scan, root = ".") {
+  const existing = readConfig(io, root);
+  if (existing) return { config: existing, fromDisk: true };
+  return { config: buildConfig(scan), fromDisk: false };
+}
+var IntegrityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+};
+function isSafeRegistryPath(rel) {
+  if (rel === "" || path.isAbsolute(rel)) return false;
+  const segments = rel.split(/[/\\]/);
+  for (const s of segments) {
+    if (s === "" || s === "." || s === "..") return false;
+  }
+  return true;
+}
+function assertContained(targetDir, rel) {
+  if (!isSafeRegistryPath(rel)) {
+    throw new IntegrityError(`unsafe registry path rejected: ${JSON.stringify(rel)}`);
+  }
+  const base = path.resolve(targetDir);
+  const dest = path.resolve(base, rel);
+  if (dest !== base && !dest.startsWith(base + path.sep)) {
+    throw new IntegrityError(`path escapes the target directory: ${JSON.stringify(rel)}`);
+  }
+  return dest;
+}
+function commitFiles(fs, targetDir, files, options = {}) {
+  const planned = files.map((f) => ({ dest: assertContained(targetDir, f.path), content: f.content, rel: f.path }));
+  if (!options.force) {
+    const conflicts = planned.filter((p) => fs.exists(p.dest)).map((p) => p.rel);
+    if (conflicts.length > 0) {
+      throw new IntegrityError(
+        `refusing to overwrite ${conflicts.length} existing file(s) (use --force): ${conflicts.join(", ")}`
+      );
+    }
+  }
+  const written = [];
+  try {
+    for (const p of planned) {
+      fs.write(p.dest, p.content);
+      written.push(p.dest);
+    }
+  } catch (err) {
+    for (const dest of written.reverse()) {
+      try {
+        fs.remove(dest);
+      } catch {
+      }
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new IntegrityError(`install failed and was rolled back (${written.length} file(s) removed): ${message}`);
+  }
+  return { written };
+}
+
+// src/components/fetch.ts
+var SUPPORTED_SCHEMA_VERSION = 1;
+var DEFAULT_REGISTRY2 = "https://registry.agentskit.io";
+function resolveIdentifier(identifier, config, options = {}) {
+  const registries = config?.registries ?? {};
+  if (/^https?:\/\//.test(identifier)) {
+    const m = identifier.match(/^(.*?)\/r\/([^/]+?)(?:\.json)?$/);
+    if (m) return { base: m[1], itemId: m[2] };
+    const url = new URL(identifier);
+    const id = url.pathname.split("/").filter(Boolean).pop()?.replace(/\.json$/, "") ?? identifier;
+    return { base: `${url.origin}`, itemId: id };
+  }
+  if (identifier.startsWith("@")) {
+    const slash = identifier.indexOf("/");
+    if (slash < 0) throw new IntegrityError(`invalid namespaced identifier: ${identifier}`);
+    const org = identifier.slice(1, slash);
+    const name = identifier.slice(slash + 1);
+    const base2 = registries[org];
+    if (!base2) throw new IntegrityError(`unknown registry namespace "@${org}" \u2014 add it to components.json registries`);
+    return { base: base2, itemId: name };
+  }
+  const base = options.registryBase ?? registries.default ?? DEFAULT_REGISTRY2;
+  return { base, itemId: identifier };
+}
+function resolveAuthHeader(base, config, env = {}) {
+  const map = config?.registryAuth;
+  if (!map) return {};
+  for (const [registryBase, envVar] of Object.entries(map)) {
+    if (base.startsWith(registryBase)) {
+      const token = env[envVar];
+      if (token) return { authorization: `Bearer ${token}` };
+    }
+  }
+  return {};
+}
+function sha256Hex(content) {
+  return crypto.createHash("sha256").update(content, "utf8").digest("hex");
+}
+function verifyChecksums(files) {
+  const bad = files.filter((f) => sha256Hex(f.content) !== f.sha256).map((f) => f.path);
+  if (bad.length > 0) {
+    throw new IntegrityError(`checksum mismatch \u2014 install aborted for ${bad.length} file(s): ${bad.join(", ")}`);
+  }
+}
+function manifestUrl(ref) {
+  return `${ref.base}/r/${ref.itemId}.json`;
+}
+function fileUrl(ref, path5) {
+  return `${ref.base}/r/${ref.itemId}/${path5}`;
+}
+async function getText2(fetchImpl, url, headers) {
+  const res = await fetchImpl(url, { headers });
+  if (!res.ok) throw new IntegrityError(`fetch failed (${res.status}) for ${url}`);
+  return res.text();
+}
+async function fetchManifest(identifier, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const ref = resolveIdentifier(identifier, options.config, options);
+  const headers = resolveAuthHeader(ref.base, options.config, options.env);
+  const raw = await getText2(fetchImpl, manifestUrl(ref), headers);
+  if (options.signatureVerifier) {
+    const sig = await getText2(fetchImpl, `${manifestUrl(ref)}.minisig`, headers);
+    const ok = await options.signatureVerifier(raw, sig);
+    if (!ok) throw new IntegrityError(`manifest signature verification failed for ${ref.itemId}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new IntegrityError(`manifest is not valid JSON for ${ref.itemId}`);
+  }
+  const component = parsed;
+  if (component?.kind !== "component") {
+    throw new IntegrityError(`"${ref.itemId}" is not a component (kind=${String(component?.kind)})`);
+  }
+  if (typeof component.schemaVersion !== "number" || component.schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+    throw new IntegrityError(
+      `"${ref.itemId}" needs a newer CLI (schemaVersion ${component.schemaVersion} > ${SUPPORTED_SCHEMA_VERSION})`
+    );
+  }
+  return { ref, component };
+}
+async function fetchPortFiles(ref, port, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const headers = resolveAuthHeader(ref.base, options.config, options.env);
+  const resolved = await Promise.all(
+    port.files.map(async (f) => {
+      const content = f.content ?? await getText2(fetchImpl, fileUrl(ref, f.path), headers);
+      return { path: f.path, content, sha256: f.sha256 };
+    })
+  );
+  verifyChecksums(resolved);
+  return resolved.map((f) => ({ path: f.path, content: f.content }));
+}
+
+// src/components/validate.ts
+var NO_NODE_SERVER = /* @__PURE__ */ new Set([
+  "expo",
+  "vite",
+  "cra",
+  "angular-spa",
+  "none"
+]);
+var SERVERLESS_CAPABLE = /* @__PURE__ */ new Set([
+  "next-app",
+  "next-pages",
+  "remix",
+  "tanstack-start",
+  "sveltekit",
+  "nuxt"
+]);
+function parseVersion(input2) {
+  const cleaned = input2.trim().replace(/^[v=]+/, "").split(/[-+]/)[0] ?? "";
+  const parts = cleaned.split(".");
+  if (parts.length === 0 || parts[0] === "") return null;
+  const nums = parts.map((p) => Number.parseInt(p, 10));
+  if (nums.some((n) => Number.isNaN(n))) return null;
+  return { major: nums[0] ?? 0, minor: nums[1] ?? 0, patch: nums[2] ?? 0 };
+}
+function cmp(a, b) {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+function satisfiesRange(version, range) {
+  const r = range.trim();
+  if (r === "" || r === "*" || r === "x" || r.startsWith("workspace:")) return true;
+  if (r.includes("||")) return r.split("||").some((part) => satisfiesRange(version, part));
+  const v = parseVersion(version);
+  if (!v) return true;
+  const m = r.match(/^(>=|<=|>|<|=|\^|~)?\s*(.+)$/);
+  if (!m) return true;
+  const op = m[1] ?? "=";
+  const target = parseVersion(m[2]);
+  if (!target) return true;
+  switch (op) {
+    case ">=":
+      return cmp(v, target) >= 0;
+    case ">":
+      return cmp(v, target) > 0;
+    case "<=":
+      return cmp(v, target) <= 0;
+    case "<":
+      return cmp(v, target) < 0;
+    case "^": {
+      if (cmp(v, target) < 0) return false;
+      if (target.major > 0) return v.major === target.major;
+      if (target.minor > 0) return v.major === 0 && v.minor === target.minor;
+      return v.major === 0 && v.minor === 0 && v.patch === target.patch;
+    }
+    case "~":
+      return v.major === target.major && v.minor === target.minor && cmp(v, target) >= 0;
+    default:
+      return cmp(v, target) === 0;
+  }
+}
+function validateInstall(input2) {
+  const { scan, component, installed = {} } = input2;
+  const issues = [];
+  const err = (code, message) => issues.push({ severity: "error", code, message });
+  const warn = (code, message) => issues.push({ severity: "warning", code, message });
+  const supported = Object.keys(component.ports);
+  if (scan.uiBinding === "unknown") {
+    err("framework-unknown", `Could not detect the UI framework. ${component.id} supports: ${supported.join(", ")}.`);
+    return { ok: false, issues };
+  }
+  const port = component.ports[scan.uiBinding];
+  if (!port) {
+    err(
+      "binding-unsupported",
+      `${component.id} has no "${scan.uiBinding}" port. Supported bindings: ${supported.join(", ")}.`
+    );
+    return { ok: false, issues };
+  }
+  const pairShipped = component.frameworks.some(
+    (t) => t.uiBinding === scan.uiBinding && (scan.metaFramework === "unknown" || t.metaFramework === scan.metaFramework)
+  );
+  if (scan.metaFramework !== "unknown" && !pairShipped) {
+    err(
+      "target-unsupported",
+      `${component.id} does not ship a ${scan.uiBinding} \xD7 ${scan.metaFramework} target.`
+    );
+  }
+  const peerRanges = { ...component.peerRanges, ...port.peerRanges };
+  for (const [name, range] of Object.entries(peerRanges)) {
+    const have = installed[name];
+    if (have == null) continue;
+    if (!satisfiesRange(have, range)) {
+      err("peer-mismatch", `${name}@${have} does not satisfy required ${range}.`);
+    }
+  }
+  const server = port.server;
+  if (server) {
+    const noServer = NO_NODE_SERVER.has(scan.metaFramework);
+    if (server.runtimeRequirement === "nodejs" && noServer && server.delivery === "bundled") {
+      err(
+        "runtime-unsatisfiable",
+        `${scan.metaFramework} has no Node server, but this port needs a bundled Node handler. Use a hosted endpoint instead.`
+      );
+    }
+    if (server.embeddingBackend === "onnx-node" && noServer) {
+      err(
+        "embedding-unsatisfiable",
+        `The onnx-node embedder needs a Node runtime; ${scan.metaFramework} can't run it. Use a BYO/api-remote embedder.`
+      );
+    }
+    if (noServer && server.delivery === "bundled") {
+      for (const e of component.env ?? []) {
+        if (e.scope === "server" && e.required) {
+          err("env-client-leak", `Server-only env "${e.name}" can't be bundled into a client-only ${scan.metaFramework} target.`);
+        }
+      }
+    }
+    if (server.rateLimitBackend === "memory" && SERVERLESS_CAPABLE.has(scan.metaFramework)) {
+      warn(
+        "ratelimit-memory",
+        `In-memory rate-limit is per-instance and ineffective on serverless ${scan.metaFramework}. Set UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN for a durable limiter.`
+      );
+    }
+  }
+  if (port.language === "ts" && !scan.typescript) {
+    err("language-ts-only", `${component.id}'s ${scan.uiBinding} port is TypeScript-only, but this is a JavaScript project.`);
+  }
+  if (port.stylingMode === "tailwind-preset" && scan.styling.mode !== "tailwind-preset") {
+    warn("styling-tailwind", `This port expects Tailwind, which wasn't detected. The component still renders via its --ak-* tokens; wire the preset manually.`);
+  }
+  return { ok: !issues.some((i) => i.severity === "error"), port, issues };
+}
+
+// src/components/marker.ts
+function assertUniquePaths(files) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    if (seen.has(f.path)) {
+      throw new IntegrityError(`duplicate file path in install marker: ${JSON.stringify(f.path)}`);
+    }
+    seen.add(f.path);
+  }
+}
+function sameKey(entry, id, installPath) {
+  return entry.id === id && entry.installPath === installPath;
+}
+function upsertInstalled(config, entry) {
+  const current = config.installed ?? [];
+  const idx = current.findIndex((e) => sameKey(e, entry.id, entry.installPath));
+  const installed = idx === -1 ? [...current, entry] : current.map((e, i) => i === idx ? entry : e);
+  return { ...config, installed };
+}
+function buildInstalledComponent(args) {
+  assertUniquePaths(args.files);
+  const files = {};
+  for (const f of args.files) {
+    files[f.path] = { sha: sha256Hex(f.content), installedAt: args.now };
+  }
+  return {
+    id: args.id,
+    kind: "component",
+    framework: args.framework,
+    installPath: args.installPath,
+    ref: args.ref,
+    version: args.version,
+    files
+  };
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = canonicalize(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function hashEntry(entry) {
+  return sha256Hex(canonicalJson(entry));
+}
+function appendAudit(prevEntries, entry) {
+  const prev = prevEntries.length > 0 ? prevEntries[prevEntries.length - 1] : void 0;
+  const prevEntryHash = prev ? hashEntry(prev) : "";
+  return { ...entry, prevEntryHash };
+}
+function serializeAuditLog(entries) {
+  if (entries.length === 0) return "";
+  return `${entries.map((e) => JSON.stringify(e)).join("\n")}
+`;
+}
+function parseAuditLog(raw) {
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      out.push(parsed);
+    }
+  }
+  return out;
+}
+
+// src/components/flow.ts
+var AUDIT_PATH = ".agentskit/install-log.jsonl";
+function installedVersions(scanFs, root) {
+  const raw = scanFs.readFile(path.join(root, "package.json"));
+  if (raw == null) return {};
+  try {
+    const pkg = JSON.parse(raw);
+    return { ...pkg.peerDependencies, ...pkg.devDependencies, ...pkg.dependencies };
+  } catch {
+    return {};
+  }
+}
+async function addComponent(options, deps) {
+  const root = options.root ?? ".";
+  const scan = scanProject(deps.scanFs, root);
+  const { config, fromDisk } = resolveConfig(deps.io, scan, root);
+  const { ref, component } = await fetchManifest(options.identifier, {
+    fetchImpl: deps.fetchImpl,
+    env: deps.env,
+    config,
+    registryBase: options.registryBase,
+    signatureVerifier: options.signatureVerifier
+  });
+  const validation = validateInstall({
+    scan,
+    component,
+    installed: installedVersions(deps.scanFs, root)
+  });
+  if (!validation.ok || !validation.port) {
+    const errors = validation.issues.filter((i) => i.severity === "error").map((i) => i.message);
+    throw new IntegrityError(`cannot install ${component.id}: ${errors.join("; ") || "no compatible port"}`);
+  }
+  const port = validation.port;
+  const files = await fetchPortFiles(ref, port, { fetchImpl: deps.fetchImpl, env: deps.env, config });
+  const installPath = options.outDir ?? port.defaultTarget;
+  const { written } = commitFiles(deps.writeFs, installPath, files, { force: options.force });
+  const framework = {
+    uiBinding: port.uiBinding,
+    metaFramework: scan.metaFramework === "unknown" ? config.metaFramework : scan.metaFramework
+  };
+  const now = deps.now();
+  const marker = buildInstalledComponent({
+    id: component.id,
+    framework,
+    installPath,
+    ref: ref.base,
+    version: component.version,
+    files,
+    now
+  });
+  writeConfig(deps.io, upsertInstalled(config, marker), root);
+  const auditPath = path.join(root, AUDIT_PATH);
+  const prev = parseAuditLog(deps.io.read(auditPath) ?? "");
+  const entry = appendAudit(prev, {
+    schemaVersion: 1,
+    eventType: "install",
+    id: component.id,
+    version: component.version,
+    ref: ref.base,
+    files: files.map((f) => ({ path: f.path, sha256: marker.files[f.path].sha })),
+    manifestSigRef: options.signatureVerifier ? `${ref.itemId}.minisig` : "",
+    timestamp: now
+  });
+  deps.io.write(auditPath, serializeAuditLog([...prev, entry]));
+  return {
+    id: component.id,
+    version: component.version,
+    installPath,
+    framework,
+    written,
+    packages: [...component.packages, ...port.packages ?? []],
+    env: component.env ?? [],
+    warnings: validation.issues.filter((i) => i.severity === "warning"),
+    configFromDisk: fromDisk
+  };
+}
+function nodeScanFs() {
+  return {
+    readFile(path5) {
+      try {
+        return fs.readFileSync(path5, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    exists(path5) {
+      return fs.existsSync(path5);
+    }
+  };
+}
+function nodeWriteFs() {
+  return {
+    exists(path5) {
+      return fs.existsSync(path5);
+    },
+    write(path5, content) {
+      fs.mkdirSync(path.dirname(path5), { recursive: true });
+      fs.writeFileSync(path5, content, "utf8");
+    },
+    remove(path5) {
+      fs.rmSync(path5, { force: true });
+    }
+  };
+}
+function nodeConfigIo() {
+  return {
+    read(path5) {
+      try {
+        return fs.readFileSync(path5, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    write(path5, content) {
+      fs.mkdirSync(path.dirname(path5), { recursive: true });
+      fs.writeFileSync(path5, content, "utf8");
+    }
+  };
+}
+var nodeFetch = async (url, init) => {
+  const res = await globalThis.fetch(url, { headers: init?.headers });
+  return {
+    ok: res.ok,
+    status: res.status,
+    text: () => res.text()
+  };
+};
+
+// src/commands/add-component.ts
+function isNotAComponent(err) {
+  return err instanceof IntegrityError && /fetch failed|is not a component/i.test(err.message);
+}
+function printReport(result) {
+  const { id, version, installPath, framework, written, packages, env, warnings, configFromDisk } = result;
+  const out = process.stdout;
+  out.write(`
+\u2713 Installed ${id}@${version} \u2192 ${installPath}/  (${framework.uiBinding} \xD7 ${framework.metaFramework})
+`);
+  out.write(`  wrote ${written.length} file${written.length === 1 ? "" : "s"}
+`);
+  if (packages.length > 0) {
+    out.write(`
+Install the packages it composes:
+  npm install ${packages.join(" ")}
+`);
+  }
+  const required = env.filter((e) => e.required);
+  if (required.length > 0) {
+    out.write(`
+Required environment:
+`);
+    for (const e of required) out.write(`  ${e.name} \u2014 ${e.description}
+`);
+  }
+  if (warnings.length > 0) {
+    out.write(`
+Warnings:
+`);
+    for (const w of warnings) out.write(`  \u26A0 ${w.message}
+`);
+  }
+  if (!configFromDisk) {
+    out.write(`
+Tip: run \`agentskit init\` to commit .agentskit/components.json and skip the scan next time.
+`);
+  }
+  out.write("\n");
+}
+async function tryComponentAdd(name, options) {
+  try {
+    const result = await addComponent(
+      { identifier: name, outDir: options.out, force: options.force === true, registryBase: options.registry },
+      {
+        scanFs: nodeScanFs(),
+        io: nodeConfigIo(),
+        writeFs: nodeWriteFs(),
+        fetchImpl: nodeFetch,
+        now: () => (/* @__PURE__ */ new Date()).toISOString(),
+        env: process.env
+      }
+    );
+    printReport(result);
+    return "installed";
+  } catch (err) {
+    if (isNotAComponent(err)) return "not-a-component";
+    throw err;
+  }
+}
 
 // src/commands/add.ts
 function registerAddCommand(program) {
-  program.command("add <agent>").description(
-    'Add a ready-made agent from the AgentsKit registry (registry.agentskit.io). Copies the agent source into your project \u2014 you own the code. With --run, also executes it. e.g. `agentskit add research` or `agentskit add legal-contract-reviewer --run "review this NDA\u2026" --provider ollama`.'
-  ).option("--out <dir>", "Directory to write the agent into (default: ./agents)").option("-f, --force", "Overwrite existing files").option("--run <task>", "Run the agent on this task right after adding it").option("--provider <provider>", "Provider for --run (openai, anthropic, gemini, ollama, demo)", "demo").option("--model <model>", "Model for --run").option("--api-key <key>", "API key for --run (else read from the provider env var)").action(
+  program.command("add <name>").description(
+    'Add a ready-made agent or UI component from the AgentsKit registry (registry.agentskit.io). Auto-detects which: a component is scanned/validated against your project and installed transactionally; an agent is copied into ./agents. You own the code. e.g. `agentskit add docs-chat` (component) or `agentskit add research --run "\u2026"` (agent).'
+  ).option("--out <dir>", "Directory to install into (component: the port dir; agent: ./agents)").option("-f, --force", "Overwrite existing files").option("--registry <url>", "Registry base URL override (component install)").option("--run <task>", "Run the agent on this task right after adding it").option("--provider <provider>", "Provider for --run (openai, anthropic, gemini, ollama, demo)", "demo").option("--model <model>", "Model for --run").option("--api-key <key>", "API key for --run (else read from the provider env var)").action(
     async (agent, options) => {
       try {
+        const outcome = await tryComponentAdd(agent, {
+          out: options.out,
+          force: options.force,
+          registry: options.registry
+        });
+        if (outcome === "installed") return;
         const result = await addAgent(agent, { outDir: options.out, force: options.force === true });
         process.stdout.write(`
 Added "${result.agent.title}" \u2192 ${result.targetDir}/