@backcap/cli 0.1.1

package/dist/index.mjs

@@ -0,0 +1,1340 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from 'citty';
+import { readPackageJSON } from 'pkg-types';
+import { Result } from '@backcap/shared/result';
+import { stat, readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { join, normalize, relative, dirname, resolve } from 'pathe';
+import { configSchema } from '@backcap/shared/schemas/config';
+import * as clack from '@clack/prompts';
+import { createConsola } from 'consola';
+import { ofetch, FetchError } from 'ofetch';
+import { registrySchema } from '@backcap/shared/schemas/registry';
+import { registryItemSchema } from '@backcap/shared/schemas/registry-item';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+var __defProp$3 = Object.defineProperty;
+var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$3 = (obj, key, value) => {
+  __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class ConfigError extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    __publicField$3(this, "code");
+    __publicField$3(this, "cause");
+    this.name = "ConfigError";
+    this.code = code;
+    this.cause = cause;
+  }
+}
+class ValidationError extends ConfigError {
+  constructor(zodError) {
+    const formatted = zodError.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n");
+    super(
+      `Config validation failed:
+${formatted}`,
+      "VALIDATION_ERROR",
+      zodError
+    );
+    this.name = "ValidationError";
+  }
+}
+class DetectionError extends Error {
+  constructor(field) {
+    super(`Could not auto-detect ${field}`);
+    __publicField$3(this, "field");
+    this.name = "DetectionError";
+    this.field = field;
+  }
+}
+
+const FRAMEWORK_MAP = [
+  { pkg: "next", id: "nextjs" },
+  { pkg: "@nestjs/core", id: "nestjs" },
+  { pkg: "fastify", id: "fastify" },
+  { pkg: "hono", id: "hono" },
+  { pkg: "express", id: "express" }
+];
+async function detectFramework(cwd) {
+  try {
+    const pkg = await readPackageJSON(cwd);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    for (const { pkg: name, id } of FRAMEWORK_MAP) {
+      if (name in deps) {
+        return Result.ok(id);
+      }
+    }
+  } catch {
+  }
+  return Result.fail(new DetectionError("framework"));
+}
+
+const LOCKFILE_MAP = [
+  { file: "bun.lockb", id: "bun" },
+  { file: "pnpm-lock.yaml", id: "pnpm" },
+  { file: "yarn.lock", id: "yarn" },
+  { file: "package-lock.json", id: "npm" }
+];
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectPackageManager(cwd) {
+  for (const { file, id } of LOCKFILE_MAP) {
+    if (await fileExists(join(cwd, file))) {
+      return Result.ok(id);
+    }
+  }
+  return Result.fail(new DetectionError("packageManager"));
+}
+
+async function configExists(cwd) {
+  try {
+    await stat(join(cwd, "backcap.json"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadConfig(cwd) {
+  try {
+    const raw = await readFile(join(cwd, "backcap.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    const result = configSchema.safeParse(parsed);
+    if (!result.success) {
+      return Result.fail(new ValidationError(result.error));
+    }
+    return Result.ok(result.data);
+  } catch (err) {
+    return Result.fail(
+      new ConfigError(
+        `Failed to load backcap.json: ${err instanceof Error ? err.message : String(err)}`,
+        "LOAD_ERROR",
+        err
+      )
+    );
+  }
+}
+function normalizePaths(config) {
+  return {
+    ...config,
+    paths: {
+      capabilities: normalize(config.paths.capabilities),
+      adapters: normalize(config.paths.adapters),
+      bridges: normalize(config.paths.bridges),
+      skills: normalize(config.paths.skills),
+      shared: normalize(config.paths.shared)
+    }
+  };
+}
+async function writeConfig(config, cwd) {
+  try {
+    const normalized = normalizePaths(config);
+    const content = JSON.stringify(normalized, null, 2) + "\n";
+    await writeFile(join(cwd, "backcap.json"), content, "utf-8");
+    return Result.ok(void 0);
+  } catch (err) {
+    return Result.fail(
+      new ConfigError(
+        `Failed to write backcap.json: ${err instanceof Error ? err.message : String(err)}`,
+        "WRITE_ERROR",
+        err
+      )
+    );
+  }
+}
+
+function buildDefaultConfig(framework, pm) {
+  return {
+    framework,
+    packageManager: pm,
+    paths: {
+      capabilities: "src/capabilities",
+      adapters: "src/adapters",
+      bridges: "src/bridges",
+      skills: ".claude/skills",
+      shared: "src/shared"
+    },
+    installed: { capabilities: [], bridges: [] }
+  };
+}
+
+function intro() {
+  clack.intro("backcap init");
+}
+function outro(msg) {
+  clack.outro(msg);
+}
+function fail(msg) {
+  clack.cancel(msg);
+  process.exit(1);
+}
+async function promptFramework() {
+  const value = await clack.select({
+    message: "Which framework are you using?",
+    options: [
+      { value: "nextjs", label: "Next.js" },
+      { value: "express", label: "Express" },
+      { value: "fastify", label: "Fastify" },
+      { value: "nestjs", label: "NestJS" },
+      { value: "hono", label: "Hono" }
+    ]
+  });
+  if (clack.isCancel(value)) {
+    process.exit(0);
+  }
+  return value;
+}
+async function promptPackageManager() {
+  const value = await clack.select({
+    message: "Which package manager are you using?",
+    options: [
+      { value: "npm", label: "npm" },
+      { value: "pnpm", label: "pnpm" },
+      { value: "yarn", label: "yarn" },
+      { value: "bun", label: "bun" }
+    ]
+  });
+  if (clack.isCancel(value)) {
+    process.exit(0);
+  }
+  return value;
+}
+async function promptOverwriteConfirm(existingConfig) {
+  const value = await clack.confirm({
+    message: `A backcap.json already exists (framework: ${existingConfig.framework}, packageManager: ${existingConfig.packageManager}). Overwrite?`
+  });
+  if (clack.isCancel(value)) {
+    process.exit(0);
+  }
+  return value;
+}
+
+const log = createConsola({
+  fancy: true,
+  defaults: {
+    tag: "backcap"
+  }
+});
+
+const init = defineCommand({
+  meta: {
+    name: "init",
+    description: "Initialize a Backcap project in the current directory"
+  },
+  async run() {
+    const cwd = process.cwd();
+    intro();
+    const frameworkResult = await detectFramework(cwd);
+    let framework = frameworkResult.isOk() ? frameworkResult.unwrap() : await promptFramework();
+    if (frameworkResult.isOk()) {
+      log.info(`Detected framework: ${framework}`);
+    }
+    const pmResult = await detectPackageManager(cwd);
+    let pm = pmResult.isOk() ? pmResult.unwrap() : await promptPackageManager();
+    if (pmResult.isOk()) {
+      log.info(`Detected package manager: ${pm}`);
+    }
+    if (await configExists(cwd)) {
+      const existingResult = await loadConfig(cwd);
+      if (existingResult.isOk()) {
+        const shouldOverwrite = await promptOverwriteConfirm(
+          existingResult.unwrap()
+        );
+        if (!shouldOverwrite) {
+          outro("Kept existing backcap.json unchanged.");
+          return;
+        }
+      }
+    }
+    const config = buildDefaultConfig(framework, pm);
+    const writeResult = await writeConfig(config, cwd);
+    if (writeResult.isFail()) {
+      fail(writeResult.unwrapError().message);
+      return;
+    }
+    outro("backcap.json created successfully!");
+  }
+});
+
+class RegistryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RegistryError";
+  }
+}
+
+const FALLBACK_URL = "https://raw.githubusercontent.com/backcap/registry/main/dist/registry.json";
+async function fetchRegistry(primaryUrl) {
+  let data;
+  try {
+    data = await ofetch(primaryUrl, { timeout: 1e3 });
+  } catch (e) {
+    if (e instanceof FetchError) {
+      log.warn("Primary registry unavailable. Using fallback.");
+      try {
+        data = await ofetch(FALLBACK_URL, { timeout: 3e3 });
+      } catch {
+        throw new RegistryError(
+          `Unable to reach registry. Check your internet connection or try again later.
+  Primary: ${primaryUrl}
+  Fallback: ${FALLBACK_URL}`
+        );
+      }
+    } else {
+      throw e;
+    }
+  }
+  const result = registrySchema.safeParse(data);
+  if (!result.success) {
+    throw new RegistryError(
+      "Registry response is invalid. This may indicate a version mismatch. Try updating: npx backcap@latest list"
+    );
+  }
+  return result.data;
+}
+
+function pad(str, len) {
+  return str.length >= len ? str.slice(0, len) : str + " ".repeat(len - str.length);
+}
+function truncate(str, maxLen) {
+  return str.length > maxLen ? str.slice(0, maxLen - 3) + "..." : str;
+}
+function renderCapabilityTable(items, installed) {
+  const capabilities = items.filter((i) => i.type === "capability");
+  const COL = { name: 20, version: 10, description: 50, installed: 12 };
+  const header = pad("Name", COL.name) + pad("Version", COL.version) + pad("Description", COL.description) + pad("Installed", COL.installed);
+  const separator = "-".repeat(COL.name + COL.version + COL.description + COL.installed);
+  const rows = capabilities.map((cap) => {
+    const installedMark = installed.has(cap.name) ? "\u2713" : "\u2014";
+    const version = cap.version ?? "\u2014";
+    return pad(cap.name, COL.name) + pad(version, COL.version) + pad(truncate(cap.description, COL.description - 2), COL.description) + installedMark;
+  });
+  const footer = `
+${capabilities.length} capabilities available`;
+  return [header, separator, ...rows, footer].join("\n") + "\n";
+}
+
+const DEFAULT_REGISTRY_URL$2 = "https://backcap.dev/registry.json";
+const list = defineCommand({
+  meta: {
+    name: "list",
+    description: "Browse available capabilities from the registry"
+  },
+  async run() {
+    const cwd = process.cwd();
+    let installed = /* @__PURE__ */ new Set();
+    let registryUrl = DEFAULT_REGISTRY_URL$2;
+    if (await configExists(cwd)) {
+      const configResult = await loadConfig(cwd);
+      if (configResult.isOk()) {
+        const config = configResult.unwrap();
+        const caps = config.installed?.capabilities ?? [];
+        installed = new Set(caps.map((c) => c.name));
+      }
+    } else {
+      log.info("Run `backcap init` to configure your project.");
+    }
+    log.start("Fetching registry...");
+    try {
+      const registry = await fetchRegistry(registryUrl);
+      const items = registry.items ?? [];
+      log.success("Registry loaded");
+      const table = renderCapabilityTable(items, installed);
+      process.stdout.write(table);
+    } catch (e) {
+      log.error(e.message);
+      process.exit(1);
+    }
+  }
+});
+
+const KNOWN_ADAPTERS = [
+  { npmPackage: "@prisma/client", adapterSuffix: "prisma", category: "persistence" },
+  { npmPackage: "express", adapterSuffix: "express", category: "http" },
+  { npmPackage: "fastify", adapterSuffix: "fastify", category: "http" },
+  { npmPackage: "@nestjs/core", adapterSuffix: "nestjs", category: "http" },
+  { npmPackage: "hono", adapterSuffix: "hono", category: "http" }
+];
+async function detectAdapters(cwd, capabilityName) {
+  try {
+    const pkg = await readPackageJSON(cwd);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return KNOWN_ADAPTERS.map((mapping) => ({
+      name: `${capabilityName}-${mapping.adapterSuffix}`,
+      category: mapping.category,
+      detected: mapping.npmPackage in deps
+    })).filter((a) => a.detected);
+  } catch {
+    return [];
+  }
+}
+
+function detectPM(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml")))
+    return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock")))
+    return "yarn";
+  if (existsSync(join(cwd, "bun.lockb")))
+    return "bun";
+  return "npm";
+}
+function buildInstallCommand(pm, deps, dev = false) {
+  const installCmd = { npm: "install", pnpm: "add", yarn: "add", bun: "add" }[pm];
+  const devFlag = { npm: "--save-dev", pnpm: "-D", yarn: "--dev", bun: "-d" }[pm];
+  return [pm, installCmd, ...dev ? [devFlag] : [], ...deps];
+}
+
+function resolveSharedPath(fileDest, capabilityRoot) {
+  const sharedDir = join(capabilityRoot, "shared");
+  return relative(dirname(fileDest), sharedDir);
+}
+function applyTemplateMarkers(content, markers) {
+  return Object.entries(markers).reduce(
+    (acc, [key, value]) => acc.replaceAll(`{{${key}}}`, value),
+    content
+  );
+}
+
+async function writeCapabilityFiles(files, options) {
+  const writtenPaths = [];
+  for (const file of files) {
+    const destPath = normalize(join(options.capabilityRoot, file.path));
+    const dir = dirname(destPath);
+    await mkdir(dir, { recursive: true });
+    const sharedPath = resolveSharedPath(destPath, options.capabilityRoot);
+    const fileMarkers = { ...options.markers, shared_path: sharedPath };
+    const content = applyTemplateMarkers(file.content, fileMarkers);
+    await writeFile(destPath, content, "utf-8");
+    writtenPaths.push(destPath);
+  }
+  return writtenPaths;
+}
+
+async function installDeps(pm, deps, cwd, dev = false) {
+  if (deps.length === 0)
+    return;
+  const [cmd, ...args] = buildInstallCommand(pm, deps, dev);
+  if (!cmd)
+    return;
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: "pipe" });
+    child.on("close", (code) => {
+      if (code === 0)
+        resolve();
+      else
+        reject(new Error(`${cmd} exited with code ${code}`));
+    });
+    child.on("error", reject);
+  });
+}
+
+function ensureInstalled(config) {
+  if (!config.installed || typeof config.installed !== "object" || Array.isArray(config.installed)) {
+    config.installed = { capabilities: [], bridges: [] };
+  }
+  const installed = config.installed;
+  if (!Array.isArray(installed.capabilities)) {
+    installed.capabilities = [];
+  }
+  if (!Array.isArray(installed.bridges)) {
+    installed.bridges = [];
+  }
+  return installed;
+}
+async function updateConfigCapability(cwd, entry) {
+  const configPath = join(cwd, "backcap.json");
+  const { readFile } = await import('node:fs/promises');
+  const raw = await readFile(configPath, "utf-8");
+  const config = JSON.parse(raw);
+  const installed = ensureInstalled(config);
+  const capEntry = {
+    name: entry.name,
+    version: entry.version,
+    adapters: entry.adapters
+  };
+  if (entry.partial) {
+    capEntry.partial = true;
+  }
+  installed.capabilities.push(capEntry);
+  const tmpPath = configPath + ".tmp";
+  await writeFile(tmpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  await rename(tmpPath, configPath);
+}
+async function updateConfigBridge(cwd, entry) {
+  const configPath = join(cwd, "backcap.json");
+  const { readFile } = await import('node:fs/promises');
+  const raw = await readFile(configPath, "utf-8");
+  const config = JSON.parse(raw);
+  const installed = ensureInstalled(config);
+  installed.bridges.push({ name: entry.name, version: entry.version });
+  const tmpPath = configPath + ".tmp";
+  await writeFile(tmpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  await rename(tmpPath, configPath);
+}
+
+var __defProp$2 = Object.defineProperty;
+var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$2 = (obj, key, value) => {
+  __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class ConflictDetectionError extends Error {
+  constructor(message, filePath, suggestion, cause) {
+    super(message);
+    __publicField$2(this, "filePath");
+    __publicField$2(this, "suggestion");
+    __publicField$2(this, "cause");
+    this.name = "ConflictDetectionError";
+    this.filePath = filePath;
+    this.suggestion = suggestion;
+    this.cause = cause;
+  }
+}
+
+async function detectConflicts(targetDir, incomingFiles) {
+  const resolvedTarget = resolve(targetDir);
+  const files = [];
+  for (const incoming of incomingFiles) {
+    const filePath = resolve(join(resolvedTarget, incoming.relativePath));
+    const rel = relative(resolvedTarget, filePath);
+    if (rel.startsWith("..") || rel.startsWith("/")) {
+      throw new ConflictDetectionError(
+        `Path traversal detected: "${incoming.relativePath}" resolves outside target directory`,
+        incoming.relativePath,
+        "Ensure all file paths in the capability are relative and do not contain '..' segments."
+      );
+    }
+    try {
+      const existingContent = await readFile(filePath, "utf-8");
+      if (existingContent === incoming.content) {
+        files.push({
+          relativePath: incoming.relativePath,
+          status: "identical",
+          existingContent,
+          incomingContent: incoming.content
+        });
+      } else {
+        files.push({
+          relativePath: incoming.relativePath,
+          status: "modified",
+          existingContent,
+          incomingContent: incoming.content
+        });
+      }
+    } catch (err) {
+      const error = err;
+      if (error.code === "ENOENT") {
+        files.push({
+          relativePath: incoming.relativePath,
+          status: "new",
+          incomingContent: incoming.content
+        });
+      } else if (error.code === "EACCES") {
+        throw new ConflictDetectionError(
+          `Permission denied reading "${incoming.relativePath}"`,
+          incoming.relativePath,
+          "Check file permissions or run the command with appropriate privileges.",
+          error
+        );
+      } else {
+        throw new ConflictDetectionError(
+          `Failed to read "${incoming.relativePath}": ${error.message}`,
+          incoming.relativePath,
+          "Check that the file is accessible and the disk is not full.",
+          error
+        );
+      }
+    }
+  }
+  const hasConflicts = files.some((f) => f.status === "modified");
+  return { hasConflicts, files };
+}
+
+const MAX_DIFF_LINES = 50;
+function groupByStatus(files) {
+  const newFiles = [];
+  const modifiedFiles = [];
+  const identicalFiles = [];
+  for (const file of files) {
+    if (file.status === "new")
+      newFiles.push(file);
+    else if (file.status === "modified")
+      modifiedFiles.push(file);
+    else
+      identicalFiles.push(file);
+  }
+  return { newFiles, modifiedFiles, identicalFiles };
+}
+function computeLineDiff(existing, incoming) {
+  const existingLines = existing.split("\n");
+  const incomingLines = incoming.split("\n");
+  const lines = [];
+  const maxLen = Math.max(existingLines.length, incomingLines.length);
+  for (let i = 0; i < maxLen; i++) {
+    const existLine = i < existingLines.length ? existingLines[i] : void 0;
+    const incomLine = i < incomingLines.length ? incomingLines[i] : void 0;
+    if (existLine === incomLine)
+      continue;
+    if (existLine !== void 0 && incomLine !== void 0) {
+      lines.push(`- ${existLine}`);
+      lines.push(`+ ${incomLine}`);
+    } else if (existLine !== void 0) {
+      lines.push(`- ${existLine}`);
+    } else if (incomLine !== void 0) {
+      lines.push(`+ ${incomLine}`);
+    }
+  }
+  return lines;
+}
+function renderConflictSummary(report) {
+  const { newFiles, modifiedFiles, identicalFiles } = groupByStatus(report.files);
+  const sections = [];
+  if (newFiles.length > 0) {
+    sections.push(
+      `New files (${newFiles.length}):
+${newFiles.map((f) => `  + ${f.relativePath}`).join("\n")}`
+    );
+  }
+  if (modifiedFiles.length > 0) {
+    sections.push(
+      `Modified files (${modifiedFiles.length}):
+${modifiedFiles.map((f) => `  ~ ${f.relativePath}`).join("\n")}`
+    );
+  }
+  if (identicalFiles.length > 0) {
+    sections.push(
+      `Identical files (${identicalFiles.length}):
+${identicalFiles.map((f) => `  = ${f.relativePath}`).join("\n")}`
+    );
+  }
+  clack.note(sections.join("\n\n"), "Conflict Report");
+}
+function renderDetailedDiffs(report) {
+  const modifiedFiles = report.files.filter((f) => f.status === "modified");
+  for (const file of modifiedFiles) {
+    if (!file.existingContent)
+      continue;
+    const diffLines = computeLineDiff(file.existingContent, file.incomingContent);
+    const truncated = diffLines.length > MAX_DIFF_LINES;
+    const displayed = truncated ? diffLines.slice(0, MAX_DIFF_LINES) : diffLines;
+    let body = displayed.join("\n");
+    if (truncated) {
+      body += `
+...${diffLines.length - MAX_DIFF_LINES} more lines`;
+    }
+    clack.note(body, file.relativePath);
+  }
+}
+
+class InstallCancelledError extends Error {
+  constructor() {
+    super("Installation cancelled by user.");
+    this.name = "InstallCancelledError";
+  }
+}
+async function selectiveInstall(report, skillFiles) {
+  const options = report.files.map((file) => {
+    const isSkill = skillFiles.has(file.relativePath);
+    const statusLabel = file.status === "new" ? "new" : file.status === "modified" ? "modified" : "identical";
+    return {
+      value: file.relativePath,
+      label: `${file.relativePath} (${statusLabel})`,
+      hint: isSkill ? "always installed" : void 0
+    };
+  });
+  const initialValues = report.files.filter((f) => f.status !== "modified").map((f) => f.relativePath);
+  for (const skillPath of skillFiles) {
+    if (!initialValues.includes(skillPath)) {
+      initialValues.push(skillPath);
+    }
+  }
+  const selected = await clack.multiselect({
+    message: "Select files to install:",
+    options,
+    initialValues
+  });
+  if (clack.isCancel(selected)) {
+    throw new InstallCancelledError();
+  }
+  const selectedSet = new Set(selected);
+  for (const skillPath of skillFiles) {
+    selectedSet.add(skillPath);
+  }
+  const installed = [];
+  const skipped = [];
+  const alwaysInstalled = [];
+  for (const file of report.files) {
+    if (skillFiles.has(file.relativePath)) {
+      alwaysInstalled.push(file.relativePath);
+    } else if (selectedSet.has(file.relativePath)) {
+      installed.push(file.relativePath);
+    } else {
+      skipped.push(file.relativePath);
+    }
+  }
+  return { installed, skipped, alwaysInstalled };
+}
+
+function resolveSkillFiles(capabilityJson) {
+  const skillFiles = /* @__PURE__ */ new Set();
+  if (capabilityJson.skills) {
+    for (const skillPath of capabilityJson.skills) {
+      skillFiles.add(skillPath);
+    }
+  }
+  if (capabilityJson.files) {
+    for (const file of capabilityJson.files) {
+      const filename = file.path.split("/").pop() ?? "";
+      if (filename.toLowerCase() === "skill.md") {
+        skillFiles.add(file.path);
+      }
+    }
+  }
+  return skillFiles;
+}
+
+async function installSkill(options) {
+  const { skillsPath, capabilityName, skillFiles, coreSkillFiles, templateValues, onConflict } = options;
+  await installCoreSkillIfAbsent(skillsPath, coreSkillFiles, templateValues);
+  if (skillFiles.length === 0)
+    return;
+  const skillDirName = `backcap-${capabilityName}`;
+  const skillDir = join(skillsPath, skillDirName);
+  const existing = await skillDirExists(skillDir);
+  if (existing && onConflict) {
+    const action = await onConflict(skillDirName);
+    if (action === "skip")
+      return;
+    if (action === "merge") {
+      await mergeSkillDir(skillDir, skillFiles, templateValues);
+      return;
+    }
+  }
+  await writeSkillFiles(skillDir, skillFiles, templateValues);
+}
+async function skillDirExists(dir) {
+  try {
+    const s = await stat(dir);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function mergeSkillDir(skillDir, files, templateValues) {
+  for (const file of files) {
+    const destPath = join(skillDir, file.path);
+    const content = applyTemplateMarkers(file.content, templateValues);
+    try {
+      const existing = await readFile(destPath, "utf-8");
+      const merged = mergeSkillFiles(existing, content);
+      if (merged !== existing) {
+        await writeFile(destPath, merged, "utf-8");
+      }
+    } catch {
+      const dir = dirname(destPath);
+      await mkdir(dir, { recursive: true });
+      await writeFile(destPath, content, "utf-8");
+    }
+  }
+}
+async function installCoreSkillIfAbsent(skillsPath, coreFiles, templateValues) {
+  if (coreFiles.length === 0)
+    return;
+  const coreSkillPath = join(skillsPath, "backcap-core", "SKILL.md");
+  try {
+    await readFile(coreSkillPath, "utf-8");
+    return;
+  } catch {
+  }
+  const coreDir = join(skillsPath, "backcap-core");
+  await writeSkillFiles(coreDir, coreFiles, templateValues);
+}
+async function writeSkillFiles(targetDir, files, templateValues) {
+  for (const file of files) {
+    const destPath = join(targetDir, file.path);
+    const dir = dirname(destPath);
+    await mkdir(dir, { recursive: true });
+    const content = applyTemplateMarkers(file.content, templateValues);
+    await writeFile(destPath, content, "utf-8");
+  }
+}
+function extractSkillFiles(files) {
+  return files.filter((f) => f.type === "skill" || f.path.startsWith("skills/")).filter((f) => typeof f.content === "string").map((f) => ({
+    path: f.path.replace(/^skills\//, ""),
+    content: f.content
+  }));
+}
+function resolveSkillsPath(config) {
+  return config.paths.skills ?? ".claude/skills";
+}
+function mergeSkillFiles(existing, incoming) {
+  const existingSections = parseSections(existing);
+  const incomingSections = parseSections(incoming);
+  const existingNames = new Set(existingSections.map((s) => s.name));
+  const newSections = incomingSections.filter((s) => !existingNames.has(s.name));
+  if (newSections.length === 0)
+    return existing;
+  return existing.trimEnd() + "\n\n" + newSections.map((s) => s.content).join("\n\n") + "\n";
+}
+function parseSections(content) {
+  const sections = [];
+  const lines = content.split("\n");
+  let currentName = "";
+  let currentLines = [];
+  for (const line of lines) {
+    const match = line.match(/^## (.+)$/);
+    if (match) {
+      if (currentName) {
+        sections.push({ name: currentName, content: currentLines.join("\n") });
+      }
+      currentName = match[1].trim();
+      currentLines = [line];
+    } else if (currentName) {
+      currentLines.push(line);
+    }
+  }
+  if (currentName) {
+    sections.push({ name: currentName, content: currentLines.join("\n") });
+  }
+  return sections;
+}
+
+function reportInstallResult(result) {
+  const sections = [];
+  if (result.installed.length > 0) {
+    sections.push(
+      `Installed (${result.installed.length}):
+${result.installed.map((f) => `  + ${f}`).join("\n")}`
+    );
+  }
+  if (result.alwaysInstalled.length > 0) {
+    sections.push(
+      `Always installed (${result.alwaysInstalled.length}):
+${result.alwaysInstalled.map((f) => `  * ${f}`).join("\n")}`
+    );
+  }
+  if (result.skipped.length > 0) {
+    sections.push(
+      `Skipped (${result.skipped.length}):
+${result.skipped.map((f) => `  - ${f}`).join("\n")}`
+    );
+  }
+  clack.note(sections.join("\n\n"), "Install Summary");
+  const totalWritten = result.installed.length + result.alwaysInstalled.length;
+  clack.outro(`${totalWritten} files installed, ${result.skipped.length} skipped`);
+}
+
+async function promptAdapterSelection(available, detected) {
+  const value = await clack.multiselect({
+    message: "Which adapters do you want to install? (detected from package.json)",
+    options: available.map((a) => ({
+      value: a.name,
+      label: `${a.name} (${a.category})`
+    })),
+    initialValues: detected
+  });
+  if (clack.isCancel(value)) {
+    clack.cancel("Installation cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+async function promptInstallConfirm(capabilityName) {
+  const value = await clack.confirm({
+    message: `Install ${capabilityName} with the above configuration?`
+  });
+  if (clack.isCancel(value)) {
+    clack.cancel("Installation cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+async function promptConflictResolution() {
+  const value = await clack.select({
+    message: "Conflicts detected. How would you like to proceed?",
+    options: [
+      { value: "compare_and_continue", label: "Compare and continue (overwrite all)" },
+      { value: "selective", label: "Select files individually" },
+      { value: "different_path", label: "Choose a different path" },
+      { value: "abort", label: "Abort installation" }
+    ]
+  });
+  if (clack.isCancel(value)) {
+    clack.cancel("Installation cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+async function promptSkillConflict(skillName) {
+  const value = await clack.select({
+    message: `Skill "${skillName}" already exists. How would you like to proceed?`,
+    options: [
+      { value: "merge", label: "Merge (add missing sections)" },
+      { value: "overwrite", label: "Overwrite existing skill" },
+      { value: "skip", label: "Skip skill installation" }
+    ]
+  });
+  if (clack.isCancel(value)) {
+    clack.cancel("Installation cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+async function promptNewPath() {
+  const value = await clack.text({
+    message: "Enter a new target path for the capability:",
+    validate: (input) => {
+      if (!input || input.trim().length === 0) {
+        return "Path cannot be empty";
+      }
+    }
+  });
+  if (clack.isCancel(value)) {
+    clack.cancel("Installation cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => {
+  __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class FileWriteError extends Error {
+  constructor(message, filePath, suggestion, cause) {
+    super(message);
+    __publicField$1(this, "filePath");
+    __publicField$1(this, "suggestion");
+    __publicField$1(this, "cause");
+    this.name = "FileWriteError";
+    this.filePath = filePath;
+    this.suggestion = suggestion;
+    this.cause = cause;
+  }
+}
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class MissingDependencyError extends Error {
+  constructor(missingCapabilities) {
+    super(`Required capabilities not installed: ${missingCapabilities.join(", ")}`);
+    __publicField(this, "missingCapabilities");
+    __publicField(this, "suggestion");
+    this.name = "MissingDependencyError";
+    this.missingCapabilities = missingCapabilities;
+    this.suggestion = `Run: ${missingCapabilities.map((c) => `backcap add ${c}`).join(" && ")}`;
+  }
+}
+
+const DEFAULT_REGISTRY_URL$1 = "https://backcap.dev";
+const add = defineCommand({
+  meta: {
+    name: "add",
+    description: "Install a capability or bridge from the registry"
+  },
+  args: {
+    capability: {
+      type: "positional",
+      required: true,
+      description: "Capability or bridge name to install"
+    }
+  },
+  async run({ args }) {
+    const cwd = process.cwd();
+    const itemName = args.capability;
+    intro();
+    if (!await configExists(cwd)) {
+      fail("No backcap.json found. Run `backcap init` first.");
+      return;
+    }
+    const configResult = await loadConfig(cwd);
+    if (configResult.isFail()) {
+      fail(configResult.unwrapError().message);
+      return;
+    }
+    const config = configResult.unwrap();
+    log.info(`Fetching ${itemName}...`);
+    let itemData;
+    let fetchedFromBridges = false;
+    try {
+      itemData = await ofetch(`${DEFAULT_REGISTRY_URL$1}/dist/${itemName}.json`, {
+        timeout: 5e3
+      });
+    } catch {
+      try {
+        itemData = await ofetch(`${DEFAULT_REGISTRY_URL$1}/dist/bridges/${itemName}.json`, {
+          timeout: 5e3
+        });
+        fetchedFromBridges = true;
+      } catch {
+        fail(`Could not fetch "${itemName}" from registry.`);
+        return;
+      }
+    }
+    const parsed = registryItemSchema.safeParse(itemData);
+    if (!parsed.success) {
+      fail("Invalid data received from registry.");
+      return;
+    }
+    const item = parsed.data;
+    const itemVersion = item.version;
+    const itemType = item.type;
+    if (itemType === "bridge" || fetchedFromBridges) {
+      await installBridge(cwd, config, item, itemVersion);
+      return;
+    }
+    const capabilityName = itemName;
+    const skillFiles = resolveSkillFiles(item);
+    const availableAdapters = await detectAdapters(cwd, capabilityName);
+    let selectedAdapters = [];
+    if (availableAdapters.length > 0) {
+      selectedAdapters = await promptAdapterSelection(
+        availableAdapters.map((a) => ({ name: a.name, category: a.category })),
+        availableAdapters.filter((a) => a.detected).map((a) => a.name)
+      );
+    }
+    const files = item.files;
+    const filesToWrite = files.filter((f) => typeof f.content === "string");
+    const markers = {
+      capabilities_path: config.paths.capabilities,
+      adapters_path: config.paths.adapters,
+      bridges_path: config.paths.bridges,
+      skills_path: config.paths.skills
+    };
+    let capRoot = normalize(join(cwd, config.paths.capabilities, capabilityName));
+    const incomingFiles = filesToWrite.map((f) => ({
+      relativePath: f.path,
+      content: f.content
+    }));
+    let useSelectiveInstall = false;
+    let resolved = false;
+    while (!resolved) {
+      let report;
+      try {
+        report = await detectConflicts(capRoot, incomingFiles);
+      } catch (err) {
+        if (err instanceof ConflictDetectionError) {
+          fail(`Conflict detection failed for ${err.filePath}: ${err.message}
+${err.suggestion}`);
+          return;
+        }
+        throw err;
+      }
+      if (report.files.every((f) => f.status === "identical")) {
+        log.info("All files are identical. No changes needed.");
+        outro("Nothing to update.");
+        return;
+      }
+      if (!report.hasConflicts) {
+        resolved = true;
+        break;
+      }
+      renderConflictSummary(report);
+      const action = await promptConflictResolution();
+      if (action === "abort") {
+        outro("Installation cancelled. No files were written.");
+        return;
+      }
+      if (action === "different_path") {
+        const newPath = await promptNewPath();
+        capRoot = normalize(join(cwd, newPath, capabilityName));
+        continue;
+      }
+      if (action === "selective") {
+        try {
+          const installResult = await selectiveInstall(report, skillFiles);
+          const selectedPaths = /* @__PURE__ */ new Set([...installResult.installed, ...installResult.alwaysInstalled]);
+          const selectedFiles = filesToWrite.filter((f) => selectedPaths.has(f.path));
+          await writeCapabilityFiles(selectedFiles, { capabilityRoot: capRoot, markers });
+          reportInstallResult(installResult);
+          useSelectiveInstall = true;
+          resolved = true;
+          const version = itemVersion ?? "1.0.0";
+          await updateConfigCapability(cwd, {
+            name: capabilityName,
+            version,
+            adapters: selectedAdapters,
+            partial: installResult.skipped.length > 0
+          });
+        } catch (err) {
+          if (err instanceof InstallCancelledError) {
+            outro("Installation cancelled. No files were written.");
+            return;
+          }
+          if (err instanceof FileWriteError) {
+            fail(`File write failed for ${err.filePath}: ${err.message}
+${err.suggestion}`);
+            return;
+          }
+          throw err;
+        }
+        break;
+      }
+      renderDetailedDiffs(report);
+      resolved = true;
+    }
+    if (!useSelectiveInstall) {
+      const confirmed = await promptInstallConfirm(capabilityName);
+      if (!confirmed) {
+        outro("Installation cancelled.");
+        return;
+      }
+      await writeCapabilityFiles(filesToWrite, { capabilityRoot: capRoot, markers });
+      log.success(`Capability files written to ${capRoot}`);
+      const version = itemVersion ?? "1.0.0";
+      await updateConfigCapability(cwd, {
+        name: capabilityName,
+        version,
+        adapters: selectedAdapters
+      });
+    }
+    for (const adapterName of selectedAdapters) {
+      log.info(`Fetching adapter ${adapterName}...`);
+      try {
+        const adapterData = await ofetch(`${DEFAULT_REGISTRY_URL$1}/dist/${adapterName}.json`, {
+          timeout: 5e3
+        });
+        const adapterParsed = registryItemSchema.safeParse(adapterData);
+        if (!adapterParsed.success) {
+          log.warn(`Invalid adapter data for "${adapterName}", skipping.`);
+          continue;
+        }
+        const adapterItem = adapterParsed.data;
+        const adapterFiles = adapterItem.files.filter((f) => typeof f.content === "string");
+        const adapterType = adapterName.replace(`${capabilityName}-`, "");
+        const category = adapterType === "prisma" ? "persistence" : "http";
+        const adapterRoot = normalize(join(cwd, config.paths.adapters, category, adapterType, capabilityName));
+        await writeCapabilityFiles(adapterFiles, { capabilityRoot: adapterRoot, markers });
+        log.success(`Adapter files written to ${adapterRoot}`);
+      } catch {
+        log.warn(`Could not fetch adapter "${adapterName}", skipping.`);
+      }
+    }
+    const skillsPath = normalize(join(cwd, resolveSkillsPath(config)));
+    const capSkillFiles = extractSkillFiles(files);
+    if (capSkillFiles.length > 0) {
+      let coreSkillFiles = [];
+      try {
+        const coreData = await ofetch(`${DEFAULT_REGISTRY_URL$1}/dist/skills/backcap-core.json`, {
+          timeout: 5e3
+        });
+        const coreParsed = registryItemSchema.safeParse(coreData);
+        if (coreParsed.success) {
+          coreSkillFiles = extractSkillFiles(
+            coreParsed.data.files
+          );
+        }
+      } catch {
+      }
+      await installSkill({
+        skillsPath,
+        capabilityName,
+        skillFiles: capSkillFiles,
+        coreSkillFiles,
+        templateValues: markers,
+        onConflict: promptSkillConflict
+      });
+      log.success(`Skill installed to ${skillsPath}/backcap-${capabilityName}/`);
+    }
+    const pm = detectPM(cwd);
+    const npmDeps = item.dependencies ? Object.keys(item.dependencies) : [];
+    const devDeps = item.peerDependencies ? Object.keys(item.peerDependencies) : [];
+    if (npmDeps.length > 0) {
+      log.info(`Installing dependencies: ${npmDeps.join(", ")}`);
+      await installDeps(pm, npmDeps, cwd);
+    }
+    if (devDeps.length > 0) {
+      log.info(`Installing dev dependencies: ${devDeps.join(", ")}`);
+      await installDeps(pm, devDeps, cwd, true);
+    }
+    if (!useSelectiveInstall) {
+      const version = itemVersion ?? "1.0.0";
+      const lines = [
+        `${capabilityName} v${version} installed successfully!`,
+        "",
+        `  Capability: ${capRoot}`
+      ];
+      if (selectedAdapters.length > 0) {
+        lines.push(`  Adapters:   ${selectedAdapters.join(", ")}`);
+      }
+      lines.push("", "  Next steps:");
+      lines.push(`  1. Review the installed files in ${config.paths.capabilities}/${capabilityName}/`);
+      lines.push("  2. Run the test suite to verify: npx vitest run");
+      lines.push("  3. Check available bridges: backcap bridges");
+      outro(lines.join("\n"));
+    }
+  }
+});
+async function installBridge(cwd, config, item, itemVersion) {
+  const bridgeName = item.name;
+  const version = itemVersion ?? "0.1.0";
+  const installedBridgeNames = new Set(config.installed.bridges.map((b) => b.name));
+  if (installedBridgeNames.has(bridgeName)) {
+    log.info(`Bridge "${bridgeName}" is already installed.`);
+    outro("Nothing to update.");
+    return;
+  }
+  const requiredDeps = Array.isArray(item.dependencies) ? item.dependencies : item.dependencies ? Object.keys(item.dependencies) : [];
+  if (requiredDeps.length > 0) {
+    const installedCapNames = new Set(config.installed.capabilities.map((c) => c.name));
+    const missing = requiredDeps.filter((dep) => !installedCapNames.has(dep));
+    if (missing.length > 0) {
+      const err = new MissingDependencyError(missing);
+      fail(`${err.message}
+${err.suggestion}`);
+      return;
+    }
+  }
+  const files = item.files;
+  const filesToWrite = files.filter((f) => typeof f.content === "string");
+  const markers = {
+    capabilities_path: config.paths.capabilities,
+    adapters_path: config.paths.adapters,
+    bridges_path: config.paths.bridges,
+    skills_path: config.paths.skills
+  };
+  const bridgeRoot = normalize(join(cwd, config.paths.bridges, bridgeName));
+  const incomingFiles = filesToWrite.map((f) => ({
+    relativePath: f.path,
+    content: f.content
+  }));
+  try {
+    const report = await detectConflicts(bridgeRoot, incomingFiles);
+    if (report.files.every((f) => f.status === "identical")) {
+      log.info("All bridge files are identical. No changes needed.");
+      outro("Nothing to update.");
+      return;
+    }
+    if (report.hasConflicts) {
+      renderConflictSummary(report);
+      const action = await promptConflictResolution();
+      if (action === "abort") {
+        outro("Installation cancelled. No files were written.");
+        return;
+      }
+      if (action === "compare_and_continue") {
+        renderDetailedDiffs(report);
+      }
+      if (action === "different_path") {
+        outro("Bridge installation cancelled.");
+        return;
+      }
+    }
+  } catch (err) {
+    if (err instanceof ConflictDetectionError) {
+      fail(`Conflict detection failed for ${err.filePath}: ${err.message}
+${err.suggestion}`);
+      return;
+    }
+    throw err;
+  }
+  const confirmed = await promptInstallConfirm(bridgeName);
+  if (!confirmed) {
+    outro("Installation cancelled.");
+    return;
+  }
+  await writeCapabilityFiles(filesToWrite, { capabilityRoot: bridgeRoot, markers });
+  log.success(`Bridge files written to ${bridgeRoot}`);
+  await updateConfigBridge(cwd, { name: bridgeName, version });
+  const lines = [
+    `Bridge ${bridgeName} v${version} installed successfully!`,
+    "",
+    `  Bridge: ${bridgeRoot}`,
+    `  Connects: ${requiredDeps.join(" + ")}`,
+    "",
+    "  Next steps:",
+    `  1. Review the bridge files in ${config.paths.bridges}/${bridgeName}/`,
+    "  2. Wire the bridge in your application entry point",
+    "  3. Run the test suite: npx vitest run"
+  ];
+  outro(lines.join("\n"));
+}
+
+const DEFAULT_REGISTRY_URL = "https://backcap.dev";
+const bridges = defineCommand({
+  meta: {
+    name: "bridges",
+    description: "List available bridges between installed capabilities"
+  },
+  async run() {
+    const cwd = process.cwd();
+    clack.intro("backcap bridges");
+    if (!await configExists(cwd)) {
+      fail("No backcap.json found. Run `backcap init` first.");
+      return;
+    }
+    const configResult = await loadConfig(cwd);
+    if (configResult.isFail()) {
+      fail(configResult.unwrapError().message);
+      return;
+    }
+    const config = configResult.unwrap();
+    const installedCaps = config.installed?.capabilities ?? [];
+    const installedCapNames = new Set(installedCaps.map((c) => c.name));
+    if (installedCapNames.size === 0) {
+      clack.log.info("No capabilities installed yet. Run `backcap add <capability>` to get started.");
+      clack.outro("No bridges available.");
+      return;
+    }
+    let catalog;
+    try {
+      catalog = await ofetch(`${DEFAULT_REGISTRY_URL}/dist/bridges/index.json`, {
+        timeout: 5e3
+      });
+    } catch {
+      fail("Could not fetch bridge catalog from registry.");
+      return;
+    }
+    const compatible = catalog.bridges.filter(
+      (b) => b.dependencies.every((dep) => installedCapNames.has(dep))
+    );
+    if (compatible.length === 0) {
+      clack.log.info("No compatible bridges found for your installed capabilities.");
+      clack.outro("Install more capabilities to unlock bridges.");
+      return;
+    }
+    const installedBridges = new Set(
+      (config.installed?.bridges ?? []).map((b) => b.name)
+    );
+    const lines = compatible.map((b) => {
+      const status = installedBridges.has(b.name) ? "installed" : "available";
+      return `  ${b.name} \u2014 ${b.description}
+    Dependencies: ${b.dependencies.join(", ")} | Status: ${status}`;
+    });
+    clack.note(lines.join("\n\n"), "Available Bridges");
+    const availableCount = compatible.filter((b) => !installedBridges.has(b.name)).length;
+    if (availableCount > 0) {
+      clack.log.info(`Run \`backcap add <bridge-name>\` to install a bridge.`);
+    }
+    clack.outro(`${compatible.length} bridge(s) found.`);
+  }
+});
+
+const main = defineCommand({
+  meta: {
+    name: "backcap",
+    version: "0.0.1",
+    description: "Backcap \u2014 capability registry CLI"
+  },
+  subCommands: {
+    init,
+    list,
+    add,
+    bridges
+  }
+});
+
+runMain(main);