khotan-data 0.0.1 → 0.1.1

package/dist/cli.js

@@ -0,0 +1,2869 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs4 from 'fs';
+import path2 from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import prompts2 from 'prompts';
+
+// src/cli/config-template.ts
+function configTemplate(outputDir) {
+  return `export default {
+  outputDir: "${outputDir}",
+  components: [],
+};
+`;
+}
+var PM_INFO = {
+  bun: { name: "bun", installCmd: "bun add", devFlag: "-d" },
+  pnpm: { name: "pnpm", installCmd: "pnpm add", devFlag: "-D" },
+  yarn: { name: "yarn", installCmd: "yarn add", devFlag: "-D" },
+  npm: { name: "npm", installCmd: "npm install", devFlag: "--save-dev" }
+};
+var LOCKFILE_PRIORITY = [
+  { file: "bun.lock", pm: "bun" },
+  { file: "pnpm-lock.yaml", pm: "pnpm" },
+  { file: "yarn.lock", pm: "yarn" },
+  { file: "package-lock.json", pm: "npm" }
+];
+function detectPackageManager(cwd) {
+  for (const { file, pm } of LOCKFILE_PRIORITY) {
+    if (fs4.existsSync(path2.join(cwd, file))) {
+      return PM_INFO[pm];
+    }
+  }
+  return PM_INFO.npm;
+}
+function checkNpmPackages(cwd, packages) {
+  const pkgPath = path2.join(cwd, "package.json");
+  if (!fs4.existsSync(pkgPath)) {
+    return packages;
+  }
+  try {
+    const pkgJson = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+    const allDeps = {
+      ...pkgJson.dependencies,
+      ...pkgJson.devDependencies
+    };
+    return packages.filter((pkg) => !(pkg in allDeps));
+  } catch {
+    return packages;
+  }
+}
+function checkShadcnComponents(cwd, components) {
+  const componentsJsonPath = path2.join(cwd, "components.json");
+  let uiDir = null;
+  if (fs4.existsSync(componentsJsonPath)) {
+    try {
+      const config = JSON.parse(
+        fs4.readFileSync(componentsJsonPath, "utf-8")
+      );
+      const aliasPath = config.aliases?.components;
+      if (aliasPath) {
+        const resolved = aliasPath.replace(/^@\//, "src/").replace(/^~\//, "");
+        uiDir = path2.join(cwd, resolved, "ui");
+      }
+    } catch {
+    }
+  }
+  if (!uiDir) {
+    const srcUi = path2.join(cwd, "src", "components", "ui");
+    const rootUi = path2.join(cwd, "components", "ui");
+    if (fs4.existsSync(srcUi)) {
+      uiDir = srcUi;
+    } else if (fs4.existsSync(rootUi)) {
+      uiDir = rootUi;
+    } else {
+      return components;
+    }
+  }
+  return components.filter((name) => {
+    const filePath = path2.join(uiDir, `${name}.tsx`);
+    return !fs4.existsSync(filePath);
+  });
+}
+function installPackages(cwd, packages, opts) {
+  if (packages.length === 0) {
+    return { success: true };
+  }
+  const pm = detectPackageManager(cwd);
+  const devFlag = opts?.devDependency ? ` ${pm.devFlag}` : "";
+  const cmd = `${pm.installCmd} ${packages.join(" ")}${devFlag}`;
+  try {
+    execSync(cmd, { cwd, stdio: "pipe", encoding: "utf-8" });
+    return { success: true };
+  } catch (err) {
+    const e = err;
+    return {
+      success: false,
+      error: e.stderr ?? e.stdout ?? "Install command failed"
+    };
+  }
+}
+function installShadcnComponents(cwd, components) {
+  if (components.length === 0) {
+    return { success: true };
+  }
+  const cmd = `npx shadcn@latest add ${components.join(" ")} --yes`;
+  try {
+    execSync(cmd, { cwd, stdio: "pipe", encoding: "utf-8" });
+    return { success: true };
+  } catch (err) {
+    const e = err;
+    return {
+      success: false,
+      error: e.stderr ?? e.stdout ?? "shadcn install failed"
+    };
+  }
+}
+var __dirname$1 = path2.dirname(fileURLToPath(import.meta.url));
+var COMPONENTS = {
+  plug: {
+    name: "plug",
+    description: "Self-contained fetch wrapper with auth, retry, and pagination",
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "plug.ts"),
+        outputFile: "plugs/plug.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "plug.example.ts"),
+        outputFile: "plugs/plug.example.ts",
+        outputBase: "outputDir"
+      }
+    ],
+    dependencies: {
+      npmPackages: ["zod"]
+    }
+  },
+  wire: {
+    name: "wire",
+    description: "Webhook subscription lifecycle management using Plug for HTTP",
+    requires: ["plug", "schema"],
+    requiresShadcn: true,
+    dependencies: {
+      npmPackages: ["drizzle-orm"],
+      shadcnComponents: ["card", "badge", "button"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "wire.ts"),
+        outputFile: "wires/wire.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "wire-panel.tsx"),
+        outputFile: "wire.tsx",
+        outputBase: "components"
+      }
+    ]
+  },
+  schema: {
+    name: "schema",
+    description: "Drizzle table definitions for khotan plugs, flows, and runs",
+    templatePath: path2.resolve(__dirname$1, "templates", "schema.ts"),
+    outputFile: "khotan.ts",
+    dependencies: {
+      npmPackages: ["drizzle-orm"]
+    }
+  },
+  cache: {
+    name: "cache",
+    description: "First-class durable cache definitions for khotan sync workloads",
+    requires: ["schema"],
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "cache.ts"),
+        outputFile: "caches/cache.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "cache.example.ts"),
+        outputFile: "caches/cache.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  hub: {
+    name: "hub",
+    description: "Dashboard UI for managing plugs and flows",
+    requiresShadcn: true,
+    dependencies: {
+      npmPackages: ["drizzle-orm"],
+      shadcnComponents: [
+        "card",
+        "badge",
+        "table",
+        "switch",
+        "button",
+        "input",
+        "label"
+      ]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "hub.tsx"),
+        outputFile: "hub.tsx",
+        outputBase: "components"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "wire-panel.tsx"),
+        outputFile: "wire.tsx",
+        outputBase: "components"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "var-panel.tsx"),
+        outputFile: "var-panel.tsx",
+        outputBase: "components"
+      }
+    ]
+  },
+  logs: {
+    name: "logs",
+    description: "Paginated UI tables for runs and webhook events",
+    requiresShadcn: true,
+    dependencies: {
+      shadcnComponents: ["card", "table", "badge", "button"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "logs.tsx"),
+        outputFile: "logs.tsx",
+        outputBase: "components"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "runs-table.tsx"),
+        outputFile: "runs-table.tsx",
+        outputBase: "components"
+      },
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "webhook-events-table.tsx"
+        ),
+        outputFile: "webhook-events-table.tsx",
+        outputBase: "components"
+      }
+    ]
+  },
+  "mapping-browser": {
+    name: "mapping-browser",
+    description: "Searchable mappings browser for listing, creating, editing, and deleting resource mappings",
+    requiresShadcn: true,
+    dependencies: {
+      shadcnComponents: ["card", "table", "button", "input", "label"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "mapping-browser.tsx"
+        ),
+        outputFile: "mapping-browser.tsx",
+        outputBase: "components"
+      }
+    ]
+  },
+  "plug-debugger": {
+    name: "plug-debugger",
+    description: "Dev-only debug panel for testing plug requests interactively",
+    requiresShadcn: true,
+    requires: ["plug"],
+    dependencies: {
+      shadcnComponents: ["card", "badge", "button", "input", "label"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "plug-debugger.tsx"),
+        outputFile: "plug-debugger.tsx",
+        outputBase: "components"
+      }
+    ]
+  },
+  catch: {
+    name: "catch",
+    description: "Durable webhook event processing via Vercel Workflow",
+    requires: ["wire"],
+    requiresWorkflowIntegration: true,
+    dependencies: {
+      npmPackages: ["workflow"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "catch.ts"),
+        outputFile: "webhooks/catch.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "catch.example.ts"),
+        outputFile: "webhooks/catch.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  pass: {
+    name: "pass",
+    description: "Durable webhook event forwarding to another service via Vercel Workflow",
+    requires: ["wire", "plug"],
+    requiresWorkflowIntegration: true,
+    dependencies: {
+      npmPackages: ["workflow"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "pass.ts"),
+        outputFile: "webhooks/pass.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "pass.example.ts"),
+        outputFile: "webhooks/pass.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  inflow: {
+    name: "inflow",
+    description: "Durable flow for pulling data from a plug into your app via Vercel Workflow",
+    requires: ["plug", "schema"],
+    requiresWorkflowIntegration: true,
+    dependencies: {
+      npmPackages: ["workflow"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "inflow.ts"),
+        outputFile: "flows/inflow.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "inflow.example.ts"),
+        outputFile: "flows/inflow.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  outflow: {
+    name: "outflow",
+    description: "Durable flow for pushing app data out through a plug via Vercel Workflow",
+    requires: ["plug", "schema"],
+    requiresWorkflowIntegration: true,
+    dependencies: {
+      npmPackages: ["workflow"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "outflow.ts"),
+        outputFile: "flows/outflow.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "outflow.example.ts"
+        ),
+        outputFile: "flows/outflow.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  relay: {
+    name: "relay",
+    description: "Durable flow for moving data between plugs via Vercel Workflow",
+    requires: ["plug", "schema"],
+    requiresWorkflowIntegration: true,
+    dependencies: {
+      npmPackages: ["workflow"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "relay.ts"),
+        outputFile: "flows/relay.ts",
+        outputBase: "outputDir"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "relay.example.ts"),
+        outputFile: "flows/relay.example.ts",
+        outputBase: "outputDir"
+      }
+    ]
+  },
+  "agent-skill": {
+    name: "agent-skill",
+    description: "Agent skill that teaches AI agents to use khotan plug for API debugging",
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "agent-skill.md"),
+        outputFile: "khotan-probe",
+        outputBase: "agentSkills"
+      }
+    ]
+  },
+  "skill-setup": {
+    name: "skill-setup",
+    description: "Agent skill for setting up khotan-data in a Next.js project",
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "skill-setup.md"),
+        outputFile: "khotan-setup",
+        outputBase: "agentSkills"
+      }
+    ]
+  },
+  "skill-plug": {
+    name: "skill-plug",
+    description: "Agent skill for creating and configuring khotan Plugs (API clients)",
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "skill-plug.md"),
+        outputFile: "khotan-plug",
+        outputBase: "agentSkills"
+      }
+    ]
+  },
+  "skill-dashboard": {
+    name: "skill-dashboard",
+    description: "Agent skill for setting up the Hub dashboard and Plug Debugger UI",
+    files: [
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "skill-dashboard.md"
+        ),
+        outputFile: "khotan-dashboard",
+        outputBase: "agentSkills"
+      }
+    ]
+  },
+  "skill-webhook": {
+    name: "skill-webhook",
+    description: "Agent skill for webhook subscriptions with Wires, Catch, and Pass",
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "skill-webhook.md"),
+        outputFile: "khotan-webhook",
+        outputBase: "agentSkills"
+      }
+    ]
+  }
+};
+var BLOCKS = {
+  "config-page-1": {
+    name: "config-page-1",
+    description: "Page route at /config that renders the KhotanHub dashboard",
+    requires: ["hub"],
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "config-page.tsx"),
+        outputFile: "config/page.tsx",
+        outputBase: "appRoot"
+      }
+    ]
+  },
+  "debug-page-1": {
+    name: "debug-page-1",
+    description: "Debug routes at /debug (plug list) and /debug/[plugName] (debugger)",
+    requires: ["plug-debugger"],
+    files: [
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "debug-index-page.tsx"
+        ),
+        outputFile: "debug/page.tsx",
+        outputBase: "appRoot"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "debug-page.tsx"),
+        outputFile: "debug/[plugName]/page.tsx",
+        outputBase: "appRoot"
+      }
+    ]
+  },
+  "logs-page-1": {
+    name: "logs-page-1",
+    description: "Page route at /logs that renders recent runs and webhook events",
+    requires: ["logs"],
+    files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "logs-page.tsx"),
+        outputFile: "logs/page.tsx",
+        outputBase: "appRoot"
+      }
+    ]
+  },
+  "mappings-page-1": {
+    name: "mappings-page-1",
+    description: "Page route at /mappings that renders the reusable Khotan mappings browser",
+    requires: ["mapping-browser"],
+    files: [
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "mappings-page.tsx"
+        ),
+        outputFile: "mappings/page.tsx",
+        outputBase: "appRoot"
+      }
+    ]
+  },
+  graph: {
+    name: "graph",
+    description: "Standalone topology graph page at /graph with filtering and run-state overlays",
+    requiresShadcn: true,
+    dependencies: {
+      npmPackages: ["@xyflow/react"],
+      shadcnComponents: ["card", "badge"]
+    },
+    files: [
+      {
+        templatePath: path2.resolve(
+          __dirname$1,
+          "templates",
+          "topology-canvas.tsx"
+        ),
+        outputFile: "topology-canvas.tsx",
+        outputBase: "components"
+      },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "graph-page.tsx"),
+        outputFile: "graph/page.tsx",
+        outputBase: "appRoot"
+      }
+    ]
+  }
+};
+function getComponent(name) {
+  return COMPONENTS[name];
+}
+function getEntry(name) {
+  const comp = COMPONENTS[name];
+  if (comp) return { entry: comp, kind: "component" };
+  const block = BLOCKS[name];
+  if (block) return { entry: block, kind: "block" };
+  return void 0;
+}
+function listComponents() {
+  return Object.values(COMPONENTS);
+}
+function listBlocks() {
+  return Object.values(BLOCKS);
+}
+function isMultiFile(entry) {
+  return Array.isArray(entry.files) && entry.files.length > 0;
+}
+var AGENT_TARGETS = [
+  {
+    agent: "cursor",
+    skillPath: (name) => `.cursor/skills/${name}/SKILL.md`
+  },
+  {
+    agent: "claude",
+    skillPath: (name) => `.claude/skills/${name}/SKILL.md`
+  },
+  {
+    agent: "codex",
+    skillPath: (name) => `.agents/skills/${name}/SKILL.md`
+  },
+  {
+    agent: "copilot",
+    skillPath: (name) => `.github/skills/${name}/SKILL.md`
+  },
+  {
+    agent: "kiro",
+    skillPath: (name) => `.kiro/skills/${name}/SKILL.md`
+  },
+  {
+    agent: "roo",
+    skillPath: (name) => `.roo/rules/${name}/SKILL.md`
+  }
+];
+var AGENT_MARKERS = {
+  cursor: ".cursor",
+  claude: ".claude",
+  codex: ".agents",
+  copilot: ".github",
+  kiro: ".kiro",
+  roo: ".roo"
+};
+function detectAgents(cwd) {
+  const detected = AGENT_TARGETS.filter((t) => {
+    const marker = AGENT_MARKERS[t.agent];
+    return marker && fs4.existsSync(path2.join(cwd, marker));
+  });
+  if (detected.length > 0) return detected;
+  return AGENT_TARGETS.filter(
+    (t) => t.agent === "cursor" || t.agent === "claude"
+  );
+}
+function installSkills(cwd, skills, agentsTemplatePath) {
+  const targets = detectAgents(cwd);
+  const result = {
+    created: [],
+    skipped: [],
+    agents: targets.map((t) => t.agent)
+  };
+  for (const target of targets) {
+    for (const skill of skills) {
+      const relPath = target.skillPath(skill.name);
+      const absPath = path2.resolve(cwd, relPath);
+      if (fs4.existsSync(absPath)) {
+        result.skipped.push(relPath);
+        continue;
+      }
+      fs4.mkdirSync(path2.dirname(absPath), { recursive: true });
+      const content = fs4.readFileSync(skill.templatePath, "utf-8");
+      fs4.writeFileSync(absPath, content, "utf-8");
+      result.created.push(relPath);
+    }
+  }
+  const agentsPath = path2.resolve(cwd, "AGENTS.md");
+  if (!fs4.existsSync(agentsPath)) {
+    const content = fs4.readFileSync(agentsTemplatePath, "utf-8");
+    const resolved = resolveAgentsMdPaths(content, targets);
+    fs4.writeFileSync(agentsPath, resolved, "utf-8");
+    result.created.push("AGENTS.md");
+  } else {
+    result.skipped.push("AGENTS.md");
+  }
+  return result;
+}
+function resolveAgentsMdPaths(content, targets) {
+  if (targets.length === 0) return content;
+  const primary = targets[0];
+  return content.replace(
+    /skills\/(khotan-[\w-]+)\/SKILL\.md/g,
+    (_match, name) => primary.skillPath(name)
+  );
+}
+
+// src/cli/commands/init.ts
+var __dirname2 = path2.dirname(fileURLToPath(import.meta.url));
+function resolveOutputDir(projectRoot) {
+  if (fs4.existsSync(path2.join(projectRoot, "src", "app"))) {
+    return "src/khotan";
+  }
+  if (fs4.existsSync(path2.join(projectRoot, "app"))) {
+    return "khotan";
+  }
+  return "src/khotan";
+}
+function hasSrcLayout(cwd) {
+  return fs4.existsSync(path2.join(cwd, "src", "app"));
+}
+var DRIZZLE_PACKAGES = ["drizzle-orm", "postgres"];
+var DRIZZLE_DEV_PACKAGES = ["drizzle-kit"];
+var SHADCN_COMPONENTS = ["card", "badge", "table", "switch"];
+function scaffoldCoreFiles(cwd, outputDir) {
+  const created = [];
+  const khotanConfigTemplatePath = path2.resolve(
+    __dirname2,
+    "templates",
+    "khotan-config.ts"
+  );
+  const routeTemplatePath = path2.resolve(
+    __dirname2,
+    "templates",
+    "khotan-route.ts"
+  );
+  const khotanTsPath = path2.join(path2.resolve(cwd, outputDir), "khotan.ts");
+  if (!fs4.existsSync(khotanTsPath)) {
+    fs4.mkdirSync(path2.dirname(khotanTsPath), { recursive: true });
+    fs4.copyFileSync(khotanConfigTemplatePath, khotanTsPath);
+    created.push(path2.relative(cwd, khotanTsPath));
+  } else {
+    console.log(
+      `\u2713 ${path2.relative(cwd, khotanTsPath)} already exists, skipping`
+    );
+  }
+  const routeDir = path2.resolve(
+    cwd,
+    hasSrcLayout(cwd) ? "src/app/api/khotan/[...all]" : "app/api/khotan/[...all]"
+  );
+  const routePath = path2.join(routeDir, "route.ts");
+  if (!fs4.existsSync(routePath)) {
+    fs4.mkdirSync(routeDir, { recursive: true });
+    fs4.copyFileSync(routeTemplatePath, routePath);
+    created.push(path2.relative(cwd, routePath));
+  } else {
+    console.log(`\u2713 ${path2.relative(cwd, routePath)} already exists, skipping`);
+  }
+  return created;
+}
+async function runFullSetup(cwd) {
+  const results = [];
+  const pm = detectPackageManager(cwd);
+  console.log(`Detected package manager: ${pm.name}
+`);
+  const missingDrizzle = checkNpmPackages(cwd, DRIZZLE_PACKAGES);
+  const missingDrizzleDev = checkNpmPackages(cwd, DRIZZLE_DEV_PACKAGES);
+  if (missingDrizzle.length > 0) {
+    console.log(`Installing ${missingDrizzle.join(", ")}...`);
+    const result = installPackages(cwd, missingDrizzle);
+    if (result.success) {
+      console.log(`\u2713 Installed ${missingDrizzle.join(", ")}`);
+      results.push({ name: "Install drizzle packages", status: "success" });
+    } else {
+      console.error(`\u2717 Failed: ${result.error ?? "unknown error"}`);
+      results.push({
+        name: "Install drizzle packages",
+        status: "failed",
+        error: result.error
+      });
+    }
+  } else {
+    console.log("\u2713 Drizzle packages already installed, skipping");
+    results.push({ name: "Install drizzle packages", status: "skipped" });
+  }
+  if (missingDrizzleDev.length > 0) {
+    console.log(`Installing ${missingDrizzleDev.join(", ")} (dev)...`);
+    const result = installPackages(cwd, missingDrizzleDev, {
+      devDependency: true
+    });
+    if (result.success) {
+      console.log(
+        `\u2713 Installed ${missingDrizzleDev.join(", ")} as dev dependencies`
+      );
+      results.push({ name: "Install drizzle-kit", status: "success" });
+    } else {
+      console.error(`\u2717 Failed: ${result.error ?? "unknown error"}`);
+      results.push({
+        name: "Install drizzle-kit",
+        status: "failed",
+        error: result.error
+      });
+    }
+  } else {
+    console.log("\u2713 drizzle-kit already installed, skipping");
+    results.push({ name: "Install drizzle-kit", status: "skipped" });
+  }
+  const componentsJsonPath = path2.join(cwd, "components.json");
+  if (!fs4.existsSync(componentsJsonPath)) {
+    console.log("\nInitializing shadcn/ui...");
+    try {
+      execSync("npx shadcn@latest init --defaults --yes", {
+        cwd,
+        stdio: "pipe",
+        encoding: "utf-8"
+      });
+      console.log("\u2713 Initialized shadcn/ui");
+      results.push({ name: "Initialize shadcn", status: "success" });
+    } catch (err) {
+      const e = err;
+      const error = e.stderr ?? e.stdout ?? "shadcn init failed";
+      console.error(`\u2717 Failed to initialize shadcn: ${error}`);
+      results.push({ name: "Initialize shadcn", status: "failed", error });
+    }
+  } else {
+    console.log("\n\u2713 shadcn/ui already configured, skipping init");
+    results.push({ name: "Initialize shadcn", status: "skipped" });
+  }
+  const missingShadcn = checkShadcnComponents(cwd, SHADCN_COMPONENTS);
+  if (missingShadcn.length > 0) {
+    console.log(
+      `
+Installing shadcn components: ${missingShadcn.join(", ")}...`
+    );
+    const result = installShadcnComponents(cwd, missingShadcn);
+    if (result.success) {
+      console.log(`\u2713 Installed shadcn components: ${missingShadcn.join(", ")}`);
+      results.push({ name: "Install shadcn components", status: "success" });
+    } else {
+      console.error(`\u2717 Failed: ${result.error ?? "unknown error"}`);
+      results.push({
+        name: "Install shadcn components",
+        status: "failed",
+        error: result.error
+      });
+    }
+  } else {
+    console.log("\n\u2713 All required shadcn components already present, skipping");
+    results.push({ name: "Install shadcn components", status: "skipped" });
+  }
+  const configPath = path2.resolve(cwd, "khotan.config.ts");
+  const outputDir = resolveOutputDir(cwd);
+  if (!fs4.existsSync(configPath)) {
+    fs4.writeFileSync(configPath, configTemplate(outputDir), "utf-8");
+    console.log(`
+\u2713 Created khotan.config.ts (outputDir: ${outputDir})`);
+    results.push({ name: "Create khotan.config.ts", status: "success" });
+  } else {
+    console.log("\n\u2713 khotan.config.ts already exists, skipping");
+    results.push({ name: "Create khotan.config.ts", status: "skipped" });
+  }
+  const coreFiles = scaffoldCoreFiles(cwd, outputDir);
+  if (coreFiles.length > 0) {
+    results.push({
+      name: `Scaffold ${coreFiles.join(", ")}`,
+      status: "success"
+    });
+  } else {
+    results.push({ name: "Scaffold core files", status: "skipped" });
+  }
+  results.push(ensureKhotanDataInstalled(cwd));
+  return results;
+}
+function ensureKhotanDataInstalled(cwd) {
+  const missing = checkNpmPackages(cwd, ["khotan-data"]);
+  if (missing.length === 0) {
+    console.log("\u2713 khotan-data already installed, skipping");
+    return { name: "Install khotan-data", status: "skipped" };
+  }
+  console.log("Installing khotan-data...");
+  const result = installPackages(cwd, ["khotan-data"]);
+  if (result.success) {
+    console.log("\u2713 Installed khotan-data");
+    return { name: "Install khotan-data", status: "success" };
+  }
+  console.error(
+    `\u2717 Failed to install khotan-data: ${result.error ?? "unknown error"}`
+  );
+  return { name: "Install khotan-data", status: "failed", error: result.error };
+}
+async function runInit(cwd) {
+  const configPath = path2.resolve(cwd, "khotan.config.ts");
+  const outputDir = resolveOutputDir(cwd);
+  if (!fs4.existsSync(configPath)) {
+    fs4.writeFileSync(configPath, configTemplate(outputDir), "utf-8");
+    console.log(`\u2713 Created khotan.config.ts (outputDir: ${outputDir})`);
+  }
+  scaffoldCoreFiles(cwd, outputDir);
+  ensureKhotanDataInstalled(cwd);
+  return fs4.existsSync(configPath);
+}
+var SKILL_COMPONENTS = [
+  "skill-setup",
+  "skill-plug",
+  "skill-dashboard",
+  "skill-webhook",
+  "agent-skill"
+];
+function scaffoldAgentSkills(cwd) {
+  const skills = [];
+  for (const name of SKILL_COMPONENTS) {
+    const entry = getComponent(name);
+    if (!entry || !isMultiFile(entry)) continue;
+    for (const file of entry.files) {
+      if (file.outputBase === "agentSkills") {
+        skills.push({ name: file.outputFile, templatePath: file.templatePath });
+      }
+    }
+  }
+  if (skills.length === 0) return 0;
+  const agentsTemplatePath = path2.resolve(__dirname2, "templates", "agents.md");
+  const result = installSkills(cwd, skills, agentsTemplatePath);
+  if (result.created.length > 0) {
+    console.log(`  Agents detected: ${result.agents.join(", ")}`);
+    for (const f of result.created) {
+      console.log(`  \u2713 Created ${f}`);
+    }
+  }
+  return result.created.length;
+}
+var initCommand = new Command("init").description("Initialize khotan in your project").option(
+  "--full",
+  "Full project setup: install drizzle, shadcn, and configure everything"
+).option("-y, --yes", "Auto-accept all prompts").action(async (opts) => {
+  const cwd = process.cwd();
+  if (opts.full) {
+    console.log("Running full khotan setup...\n");
+    const results = await runFullSetup(cwd);
+    const succeeded = results.filter((r) => r.status === "success");
+    const skipped = results.filter((r) => r.status === "skipped");
+    const failed = results.filter((r) => r.status === "failed");
+    console.log("\n\u2500\u2500 Setup Summary \u2500\u2500");
+    for (const r of succeeded) {
+      console.log(`  \u2713 ${r.name}`);
+    }
+    for (const r of skipped) {
+      console.log(`  \u2298 ${r.name} (already done)`);
+    }
+    for (const r of failed) {
+      console.log(`  \u2717 ${r.name}: ${r.error ?? "unknown error"}`);
+    }
+    if (failed.length > 0) {
+      console.log(
+        `
+${String(failed.length)} step(s) failed. You may need to run them manually.`
+      );
+    } else {
+      console.log("\nAll done! Your project is ready for khotan.");
+    }
+    return;
+  }
+  const configPath = path2.resolve(cwd, "khotan.config.ts");
+  const outputDir = resolveOutputDir(cwd);
+  if (fs4.existsSync(configPath)) {
+    console.log(`\u2713 khotan.config.ts already exists, skipping`);
+  } else {
+    fs4.writeFileSync(configPath, configTemplate(outputDir), "utf-8");
+    console.log(`\u2713 Created khotan.config.ts (outputDir: ${outputDir})`);
+  }
+  const coreFiles = scaffoldCoreFiles(cwd, outputDir);
+  ensureKhotanDataInstalled(cwd);
+  let installSkills2 = opts.yes ?? false;
+  if (!installSkills2 && process.stdin.isTTY) {
+    const response = await prompts2({
+      type: "confirm",
+      name: "install",
+      message: "Install agent skills for AI-assisted development? (Y/n)",
+      initial: true
+    });
+    installSkills2 = response.install === true;
+  }
+  if (installSkills2) {
+    const count = scaffoldAgentSkills(cwd);
+    if (count > 0) {
+      console.log(`\u2713 Installed ${String(count)} agent skills`);
+    }
+  }
+  const allFiles = [
+    ...fs4.existsSync(configPath) && coreFiles.length === 0 ? [] : ["khotan.config.ts"],
+    ...coreFiles
+  ];
+  if (allFiles.length > 0 || coreFiles.length > 0) {
+    console.log("\nNext steps:");
+    console.log("  1. Update the db import in your khotan config file");
+    console.log("  2. Run `npx khotan add plug` to add the HTTP client");
+    console.log("  3. Run `npx khotan migrate` to create database tables");
+  }
+});
+function readDrizzleConfig(projectRoot) {
+  const configPath = path2.join(projectRoot, "drizzle.config.ts");
+  if (!fs4.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    return { content: fs4.readFileSync(configPath, "utf-8"), configPath };
+  } catch {
+    return null;
+  }
+}
+function parseSchemaValue(content) {
+  const schemaMatch = /schema:\s*["'`]([^"'`]+)["'`]/.exec(content);
+  return schemaMatch?.[1] ?? null;
+}
+function resolveDrizzleSchemaDir(projectRoot) {
+  const config = readDrizzleConfig(projectRoot);
+  if (!config) return null;
+  const schemaValue = parseSchemaValue(config.content);
+  if (!schemaValue) return null;
+  const normalized = schemaValue.replace(/^\.\//, "");
+  if (normalized.includes("*")) {
+    return normalized.replace(/\/\*.*$/, "");
+  }
+  if (/\.\w+$/.test(normalized)) {
+    return path2.dirname(normalized);
+  }
+  return normalized;
+}
+function detectSingleFileSchema(projectRoot) {
+  const config = readDrizzleConfig(projectRoot);
+  if (!config) return null;
+  const schemaValue = parseSchemaValue(config.content);
+  if (!schemaValue) return null;
+  const normalized = schemaValue.replace(/^\.\//, "");
+  if (normalized.includes("*")) return null;
+  if (!/\.\w+$/.test(normalized)) return null;
+  const dir = path2.dirname(normalized);
+  const prefix = schemaValue.startsWith("./") ? "./" : "";
+  return {
+    configPath: config.configPath,
+    currentValue: schemaValue,
+    globValue: `${prefix}${dir}/*`
+  };
+}
+function updateDrizzleConfigSchema(configPath, oldValue, newValue) {
+  const content = fs4.readFileSync(configPath, "utf-8");
+  const updated = content.replace(
+    new RegExp(
+      `(schema:\\s*)(["'\`])${oldValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\2`
+    ),
+    `$1$2${newValue}$2`
+  );
+  fs4.writeFileSync(configPath, updated, "utf-8");
+}
+function findNextConfigPath(cwd) {
+  const candidates = [
+    "next.config.ts",
+    "next.config.mts",
+    "next.config.js",
+    "next.config.mjs"
+  ];
+  for (const candidate of candidates) {
+    const fullPath = path2.join(cwd, candidate);
+    if (fs4.existsSync(fullPath)) return fullPath;
+  }
+  return path2.join(cwd, "next.config.ts");
+}
+function ensureWorkflowImport(source) {
+  if (source.includes(`from "workflow/next"`) || source.includes(`from 'workflow/next'`)) {
+    return source;
+  }
+  const nextImportPattern = /import\s+type\s+\{\s*NextConfig\s*\}\s+from\s+["']next["'];?\n?/;
+  if (nextImportPattern.test(source)) {
+    return source.replace(
+      nextImportPattern,
+      (match) => `${match}import { withWorkflow } from "workflow/next";
+`
+    );
+  }
+  return `import { withWorkflow } from "workflow/next";
+${source}`;
+}
+function wrapDefaultExport(source) {
+  if (source.includes("export default withWorkflow(")) {
+    return source;
+  }
+  const namedExportPattern = /export\s+default\s+([A-Za-z_$][\w$]*)\s*;?/;
+  if (namedExportPattern.test(source)) {
+    return source.replace(
+      namedExportPattern,
+      "export default withWorkflow($1);"
+    );
+  }
+  const objectExportPattern = /export\s+default\s+(\{[\s\S]*\})\s*;?/m;
+  if (objectExportPattern.test(source)) {
+    return source.replace(
+      objectExportPattern,
+      "export default withWorkflow($1);"
+    );
+  }
+  return null;
+}
+function ensureWorkflowNextConfig(cwd) {
+  const configPath = findNextConfigPath(cwd);
+  if (!fs4.existsSync(configPath)) {
+    fs4.writeFileSync(
+      configPath,
+      [
+        'import type { NextConfig } from "next";',
+        'import { withWorkflow } from "workflow/next";',
+        "",
+        "const nextConfig: NextConfig = {};",
+        "",
+        "export default withWorkflow(nextConfig);",
+        ""
+      ].join("\n"),
+      "utf-8"
+    );
+    return { status: "created", path: configPath };
+  }
+  const original = fs4.readFileSync(configPath, "utf-8");
+  const withImport = ensureWorkflowImport(original);
+  const wrapped = wrapDefaultExport(withImport);
+  if (!wrapped) {
+    return { status: "unsupported", path: configPath };
+  }
+  if (wrapped === original) {
+    return { status: "skipped", path: configPath };
+  }
+  fs4.writeFileSync(configPath, wrapped, "utf-8");
+  return { status: "updated", path: configPath };
+}
+
+// src/cli/commands/add.ts
+async function loadConfig() {
+  const configPath = path2.resolve(process.cwd(), "khotan.config.ts");
+  if (!fs4.existsSync(configPath)) {
+    return null;
+  }
+  const content = fs4.readFileSync(configPath, "utf-8");
+  const outputDirMatch = /outputDir:\s*["']([^"']+)["']/.exec(content);
+  return {
+    outputDir: outputDirMatch?.[1] ?? "src/lib/khotan"
+  };
+}
+function hasSrcLayout2(cwd) {
+  return fs4.existsSync(path2.join(cwd, "src", "app"));
+}
+function resolveOutputBase(file, cwd, outputDir) {
+  switch (file.outputBase) {
+    case "components":
+      return path2.resolve(
+        cwd,
+        hasSrcLayout2(cwd) ? "src/components/khotan" : "components/khotan"
+      );
+    case "app":
+      return path2.resolve(
+        cwd,
+        hasSrcLayout2(cwd) ? "src/app/api/khotan/[...all]" : "app/api/khotan/[...all]"
+      );
+    case "appRoot":
+      return path2.resolve(cwd, hasSrcLayout2(cwd) ? "src/app" : "app");
+    case "projectRoot":
+      return path2.resolve(cwd);
+    case "outputDir":
+    default:
+      return path2.resolve(cwd, outputDir);
+  }
+}
+function isScaffolded(entry, cwd, outputDir) {
+  if (isMultiFile(entry)) {
+    return entry.files.some((f) => {
+      const base = resolveOutputBase(f, cwd, outputDir);
+      return fs4.existsSync(path2.join(base, f.outputFile));
+    });
+  }
+  if (entry.outputFile) {
+    return fs4.existsSync(path2.join(cwd, outputDir, entry.outputFile));
+  }
+  return false;
+}
+async function scaffoldFile(templatePath, outputPath, force) {
+  if (fs4.existsSync(outputPath) && !force) {
+    const response = await prompts2({
+      type: "confirm",
+      name: "overwrite",
+      message: `${path2.basename(outputPath)} already exists at ${outputPath}. Overwrite?`,
+      initial: false
+    });
+    if (!response.overwrite) {
+      return false;
+    }
+  }
+  fs4.mkdirSync(path2.dirname(outputPath), { recursive: true });
+  const content = fs4.readFileSync(templatePath, "utf-8");
+  fs4.writeFileSync(outputPath, content, "utf-8");
+  return true;
+}
+async function checkAndInstallDeps(cwd, deps, autoYes) {
+  const allPackages = [
+    ...deps.npmPackages ?? [],
+    ...deps.npmDevPackages ?? []
+  ];
+  const missingPkgs = allPackages.length > 0 ? checkNpmPackages(cwd, allPackages) : [];
+  const missingShadcn = deps.shadcnComponents ? checkShadcnComponents(cwd, deps.shadcnComponents) : [];
+  if (missingPkgs.length === 0 && missingShadcn.length === 0) {
+    return;
+  }
+  if (missingPkgs.length > 0) {
+    console.log(`
+Missing npm packages: ${missingPkgs.join(", ")}`);
+  }
+  if (missingShadcn.length > 0) {
+    console.log(`Missing shadcn components: ${missingShadcn.join(", ")}`);
+  }
+  let shouldInstall = autoYes;
+  if (!shouldInstall && process.stdin.isTTY) {
+    const response = await prompts2({
+      type: "confirm",
+      name: "install",
+      message: "Install missing dependencies?",
+      initial: true
+    });
+    shouldInstall = response.install === true;
+  }
+  if (!shouldInstall) {
+    console.warn(
+      "\u26A0 Skipping dependency install. The component may not work without them."
+    );
+    return;
+  }
+  if (missingPkgs.length > 0) {
+    const regularPkgs = missingPkgs.filter(
+      (p) => !(deps.npmDevPackages ?? []).includes(p)
+    );
+    const devPkgs = missingPkgs.filter(
+      (p) => (deps.npmDevPackages ?? []).includes(p)
+    );
+    if (regularPkgs.length > 0) {
+      console.log(`Installing ${regularPkgs.join(", ")}...`);
+      const result = installPackages(cwd, regularPkgs);
+      if (result.success) {
+        console.log(`\u2713 Installed ${regularPkgs.join(", ")}`);
+      } else {
+        console.error(
+          `\u2717 Failed to install packages: ${result.error ?? "unknown error"}`
+        );
+      }
+    }
+    if (devPkgs.length > 0) {
+      console.log(`Installing ${devPkgs.join(", ")} (dev)...`);
+      const result = installPackages(cwd, devPkgs, { devDependency: true });
+      if (result.success) {
+        console.log(`\u2713 Installed ${devPkgs.join(", ")} as dev dependencies`);
+      } else {
+        console.error(
+          `\u2717 Failed to install dev packages: ${result.error ?? "unknown error"}`
+        );
+      }
+    }
+  }
+  if (missingShadcn.length > 0) {
+    console.log(`Installing shadcn components: ${missingShadcn.join(", ")}...`);
+    const result = installShadcnComponents(cwd, missingShadcn);
+    if (result.success) {
+      console.log(`\u2713 Installed shadcn components: ${missingShadcn.join(", ")}`);
+    } else {
+      console.error(
+        `\u2717 Failed to install shadcn components: ${result.error ?? "unknown error"}`
+      );
+    }
+  }
+}
+var addCommand = new Command("add").description("Add a component or block to your project").argument(
+  "<name>",
+  "Component or block to add (e.g., plug, inflow, outflow, relay, schema, hub, config-page-1)"
+).option("-f, --force", "Overwrite existing files without prompting").option("-y, --yes", "Auto-accept all install prompts").option("--without-ui", "Skip UI component scaffolding").action(
+  async (componentName, opts) => {
+    let config = await loadConfig();
+    if (!config) {
+      console.log("No khotan.config.ts found. Running init...\n");
+      const initOk = await runInit(process.cwd());
+      if (!initOk) {
+        console.error("\u2717 Init failed. Cannot proceed with add.");
+        process.exit(1);
+      }
+      config = await loadConfig();
+      if (!config) {
+        console.error("\u2717 Could not read config after init.");
+        process.exit(1);
+      }
+      console.log("");
+    }
+    const cwd = process.cwd();
+    scaffoldCoreFiles(cwd, config.outputDir);
+    const result = getEntry(componentName);
+    if (!result) {
+      const components = listComponents().map((c) => c.name).join(", ");
+      const blocks = listBlocks().map((b) => b.name).join(", ");
+      console.error(`\u2717 Unknown name "${componentName}".`);
+      console.error(`  Components: ${components}`);
+      console.error(`  Blocks:     ${blocks}`);
+      process.exit(1);
+    }
+    const { entry: component, kind } = result;
+    if (component.requires && component.requires.length > 0) {
+      for (const reqName of component.requires) {
+        const reqResult = getEntry(reqName);
+        if (!reqResult) continue;
+        const req = reqResult.entry;
+        if (!isScaffolded(req, cwd, config.outputDir)) {
+          let shouldAdd = opts.yes ?? false;
+          if (!shouldAdd && process.stdin.isTTY) {
+            const response = await prompts2({
+              type: "confirm",
+              name: "add",
+              message: `"${componentName}" requires the "${reqName}" component. Add it now?`,
+              initial: true
+            });
+            shouldAdd = response.add === true;
+          } else if (!shouldAdd) {
+            shouldAdd = true;
+          }
+          if (shouldAdd) {
+            console.log(`
+Adding required component: ${reqName}...`);
+            const { execSync: execSync4 } = await import('child_process');
+            execSync4(
+              `node ${process.argv[1] ?? ""} add ${reqName}${opts.force ? " --force" : ""}${opts.yes ? " --yes" : ""}`,
+              { cwd, stdio: "inherit" }
+            );
+            console.log("");
+          } else {
+            console.warn(
+              `\u26A0 Skipping "${reqName}". The ${kind} may not work without it.`
+            );
+          }
+        }
+      }
+    }
+    if (component.dependencies) {
+      const deps = { ...component.dependencies };
+      if (opts.withoutUi) {
+        delete deps.shadcnComponents;
+      }
+      await checkAndInstallDeps(cwd, deps, opts.yes ?? false);
+    }
+    if (component.requiresShadcn && !opts.withoutUi) {
+      const shadcnConfig = path2.join(cwd, "components.json");
+      if (!fs4.existsSync(shadcnConfig)) {
+        console.warn(
+          "\u26A0 shadcn/ui is required for the Hub component but components.json was not found."
+        );
+        console.warn(
+          "  Run `npx shadcn-ui@latest init` first, then re-run this command.\n"
+        );
+      }
+    }
+    if (isMultiFile(component)) {
+      const hasAgentSkills = component.files.some(
+        (f) => f.outputBase === "agentSkills"
+      );
+      if (hasAgentSkills) {
+        const skills = component.files.filter((f) => f.outputBase === "agentSkills").map((f) => ({ name: f.outputFile, templatePath: f.templatePath }));
+        const agentsTemplatePath = path2.resolve(
+          path2.dirname(component.files[0].templatePath),
+          "agents.md"
+        );
+        const result2 = installSkills(cwd, skills, agentsTemplatePath);
+        if (result2.created.length > 0) {
+          console.log(
+            `
+\u2713 Installed to ${result2.agents.join(", ")} (${String(result2.created.length)} files):`
+          );
+          for (const f of result2.created) {
+            console.log(`  ${f}`);
+          }
+        }
+        if (result2.skipped.length > 0 && result2.created.length === 0) {
+          console.log("\n\u2713 All skill files already exist, skipping");
+        }
+        return;
+      }
+      const createdFiles = [];
+      let filesToScaffold = component.files;
+      if (opts.withoutUi) {
+        filesToScaffold = filesToScaffold.filter(
+          (f) => !f.outputFile.endsWith(".tsx")
+        );
+      }
+      for (const file of filesToScaffold) {
+        if (file.outputBase === "appRoot") {
+          const baseDir = resolveOutputBase(file, cwd, config.outputDir);
+          const outputPath2 = path2.join(baseDir, file.outputFile);
+          const routeDir = path2.dirname(outputPath2);
+          const pageExtensions = [
+            "page.tsx",
+            "page.ts",
+            "page.jsx",
+            "page.js"
+          ];
+          const existing = pageExtensions.find(
+            (ext) => fs4.existsSync(path2.join(routeDir, ext))
+          );
+          if (existing && existing !== path2.basename(file.outputFile)) {
+            const relRoute = path2.relative(
+              cwd,
+              path2.join(routeDir, existing)
+            );
+            console.warn(
+              `
+\u26A0 Route collision: ${relRoute} already exists at this path.`
+            );
+            console.warn(
+              `  Adding "${component.name}" will create a conflicting route file.
+`
+            );
+          }
+        }
+      }
+      for (const file of filesToScaffold) {
+        const baseDir = resolveOutputBase(file, cwd, config.outputDir);
+        const outputPath2 = path2.join(baseDir, file.outputFile);
+        const created2 = await scaffoldFile(
+          file.templatePath,
+          outputPath2,
+          opts.force ?? false
+        );
+        if (created2) {
+          createdFiles.push(path2.relative(cwd, outputPath2));
+        }
+      }
+      if (createdFiles.length > 0) {
+        console.log(`
+\u2713 Created ${String(createdFiles.length)} files:`);
+        for (const f of createdFiles) {
+          console.log(`  ${f}`);
+        }
+      }
+      if (component.requiresWorkflowIntegration) {
+        const workflowConfig = ensureWorkflowNextConfig(cwd);
+        const relPath = path2.relative(cwd, workflowConfig.path);
+        if (workflowConfig.status === "created") {
+          console.log(`\u2713 Created ${relPath} with Workflow integration`);
+        } else if (workflowConfig.status === "updated") {
+          console.log(`\u2713 Updated ${relPath} with Workflow integration`);
+        } else if (workflowConfig.status === "skipped") {
+          console.log(`\u2713 ${relPath} already has Workflow integration`);
+        } else {
+          console.warn(
+            `\u26A0 Could not automatically update ${relPath} for Workflow integration. Wrap its default export with withWorkflow() from "workflow/next".`
+          );
+        }
+      }
+      if (componentName === "hub") {
+        console.log("\nNext steps:");
+        console.log(
+          "  1. Render <KhotanHub /> on a page, or `npx khotan add config-page-1` for a ready-made /config route"
+        );
+      }
+      return;
+    }
+    if (!component.templatePath || !component.outputFile) {
+      console.error(
+        `\u2717 ${kind === "block" ? "Block" : "Component"} "${componentName}" has no template.`
+      );
+      process.exit(1);
+    }
+    let outputDir = path2.resolve(cwd, config.outputDir);
+    let schemaDir = null;
+    if (componentName === "schema") {
+      schemaDir = resolveDrizzleSchemaDir(cwd);
+      if (schemaDir) {
+        outputDir = path2.resolve(cwd, schemaDir);
+        console.log(`\u2713 Detected Drizzle schema directory: ${schemaDir}`);
+      } else if (process.stdin.isTTY) {
+        const response = await prompts2(
+          {
+            type: "text",
+            name: "schemaPath",
+            message: "Where should the schema file be placed?",
+            initial: config.outputDir
+          },
+          {
+            onCancel: () => {
+            }
+          }
+        );
+        const schemaPath = response.schemaPath;
+        if (schemaPath) {
+          outputDir = path2.resolve(cwd, schemaPath);
+        }
+      }
+    }
+    const outputPath = path2.join(outputDir, component.outputFile);
+    const created = await scaffoldFile(
+      component.templatePath,
+      outputPath,
+      opts.force ?? false
+    );
+    if (!created) {
+      console.log("Cancelled.");
+      return;
+    }
+    console.log(`\u2713 Created ${path2.relative(cwd, outputPath)}`);
+    if (component.requiresWorkflowIntegration) {
+      const workflowConfig = ensureWorkflowNextConfig(cwd);
+      const relPath = path2.relative(cwd, workflowConfig.path);
+      if (workflowConfig.status === "created") {
+        console.log(`\u2713 Created ${relPath} with Workflow integration`);
+      } else if (workflowConfig.status === "updated") {
+        console.log(`\u2713 Updated ${relPath} with Workflow integration`);
+      } else if (workflowConfig.status === "skipped") {
+        console.log(`\u2713 ${relPath} already has Workflow integration`);
+      } else {
+        console.warn(
+          `\u26A0 Could not automatically update ${relPath} for Workflow integration. Wrap its default export with withWorkflow() from "workflow/next".`
+        );
+      }
+    }
+    if (componentName === "schema") {
+      const autoYes = opts.yes ?? false;
+      const singleFile = detectSingleFileSchema(cwd);
+      if (singleFile) {
+        const relConfig = path2.relative(cwd, singleFile.configPath);
+        console.log(
+          `
+\u26A0 ${relConfig} points to a single file ("${singleFile.currentValue}").`
+        );
+        console.log(
+          `  Drizzle Kit won't pick up khotan.ts unless the schema is a glob.`
+        );
+        let shouldUpdate = autoYes;
+        if (!shouldUpdate && process.stdin.isTTY) {
+          const response = await prompts2({
+            type: "confirm",
+            name: "update",
+            message: `Update schema to "${singleFile.globValue}" so Drizzle Kit picks up all files?`,
+            initial: true
+          });
+          shouldUpdate = response.update === true;
+        }
+        if (shouldUpdate) {
+          updateDrizzleConfigSchema(
+            singleFile.configPath,
+            singleFile.currentValue,
+            singleFile.globValue
+          );
+          console.log(
+            `\u2713 Updated ${relConfig}: schema \u2192 "${singleFile.globValue}"`
+          );
+        } else {
+          console.log(
+            `  Skipped. Update the schema value manually or Drizzle Kit won't see the khotan tables.`
+          );
+        }
+      }
+      const barrelPath = path2.join(outputDir, "index.ts");
+      if (fs4.existsSync(barrelPath)) {
+        const barrelContent = fs4.readFileSync(barrelPath, "utf-8");
+        const relBarrel = path2.relative(cwd, barrelPath);
+        if (barrelContent.includes("./khotan")) {
+          console.log(`\u2713 ${relBarrel} already re-exports khotan`);
+        } else {
+          let shouldUpdate = autoYes;
+          if (!shouldUpdate && process.stdin.isTTY) {
+            const response = await prompts2({
+              type: "confirm",
+              name: "update",
+              message: `Add \`export * from "./khotan"\` to ${relBarrel}?`,
+              initial: true
+            });
+            shouldUpdate = response.update === true;
+          }
+          if (shouldUpdate) {
+            const separator = barrelContent.endsWith("\n") ? "" : "\n";
+            fs4.appendFileSync(
+              barrelPath,
+              `${separator}export * from "./khotan";
+`
+            );
+            console.log(`\u2713 Updated ${relBarrel} with khotan re-export`);
+          } else {
+            console.log(`  Skipped. Add this to ${relBarrel} manually:
+`);
+            console.log(`    export * from "./khotan";`);
+          }
+        }
+      } else {
+        const relDir = path2.relative(cwd, outputDir);
+        const importBase = relDir.replace(/^src\//, "@/");
+        console.log(
+          `
+Add this re-export to your Drizzle schema barrel file:
+`
+        );
+        console.log(`  export * from "${importBase}/khotan";`);
+      }
+    } else {
+      const importBase = config.outputDir.replace(/^src\//, "@/");
+      if (componentName === "wire") {
+        console.log(`
+Usage:
+`);
+        console.log(`  import { wire } from "${importBase}/wire";`);
+        console.log(`  import { myPlug } from "${importBase}/plugs/plug";`);
+        console.log(`  import { db } from "@/db";
+`);
+        console.log(`  const myWire = wire({`);
+        console.log(`    plug: myPlug,`);
+        console.log(`    db,`);
+        console.log(`    subscribe: {`);
+        console.log(`      path: "/webhooks",`);
+        console.log(
+          `      buildBody: (callbackUrl) => ({ url: callbackUrl, events: ["*"] }),`
+        );
+        console.log(`      parseId: (res) => (res as { id: string }).id,`);
+        console.log(`    },`);
+        console.log(`    unsubscribe: {`);
+        console.log(`      path: (remoteId) => \`/webhooks/\${remoteId}\`,`);
+        console.log(`    },`);
+        console.log(`  });`);
+      } else {
+        console.log(`
+Usage:
+`);
+        console.log(
+          `  import { plug, bearer } from "${importBase}/plugs/${component.name}";`
+        );
+        console.log(`
+  const api = plug({`);
+        console.log(`    baseUrl: "https://api.example.com",`);
+        console.log(`    auth: bearer(process.env.API_TOKEN!),`);
+        console.log(`  });`);
+      }
+    }
+  }
+);
+function loadOutputDir() {
+  const configPath = path2.resolve(process.cwd(), "khotan.config.ts");
+  if (!fs4.existsSync(configPath)) return "src/lib/khotan";
+  const content = fs4.readFileSync(configPath, "utf-8");
+  const match = /outputDir:\s*["']([^"']+)["']/.exec(content);
+  return match?.[1] ?? "src/lib/khotan";
+}
+function runGenerate(cwd) {
+  const schema = getComponent("schema");
+  if (!schema || isMultiFile(schema) || !schema.templatePath || !schema.outputFile) {
+    console.error("\u2717 Could not find schema component in registry.");
+    return false;
+  }
+  let outputDir = loadOutputDir();
+  const schemaDir = resolveDrizzleSchemaDir(cwd);
+  if (schemaDir) {
+    outputDir = schemaDir;
+    console.log(`\u2713 Detected Drizzle schema directory: ${schemaDir}`);
+  }
+  const absOutputDir = path2.resolve(cwd, outputDir);
+  const outputPath = path2.join(absOutputDir, schema.outputFile);
+  fs4.mkdirSync(path2.dirname(outputPath), { recursive: true });
+  const content = fs4.readFileSync(schema.templatePath, "utf-8");
+  fs4.writeFileSync(outputPath, content, "utf-8");
+  console.log(`\u2713 Created ${path2.relative(cwd, outputPath)}`);
+  const singleFile = detectSingleFileSchema(cwd);
+  if (singleFile) {
+    const relConfig = path2.relative(cwd, singleFile.configPath);
+    updateDrizzleConfigSchema(
+      singleFile.configPath,
+      singleFile.currentValue,
+      singleFile.globValue
+    );
+    console.log(`\u2713 Updated ${relConfig}: schema \u2192 "${singleFile.globValue}"`);
+  }
+  const barrelPath = path2.join(absOutputDir, "index.ts");
+  if (fs4.existsSync(barrelPath)) {
+    const barrelContent = fs4.readFileSync(barrelPath, "utf-8");
+    const relBarrel = path2.relative(cwd, barrelPath);
+    if (barrelContent.includes("./khotan")) {
+      console.log(`\u2713 ${relBarrel} already re-exports khotan`);
+    } else {
+      const separator = barrelContent.endsWith("\n") ? "" : "\n";
+      fs4.appendFileSync(barrelPath, `${separator}export * from "./khotan";
+`);
+      console.log(`\u2713 Updated ${relBarrel} with khotan re-export`);
+    }
+  }
+  return true;
+}
+var generateCommand = new Command("generate").description(
+  "Generate the Khotan schema file and wire it into your Drizzle config"
+).action(async () => {
+  const cwd = process.cwd();
+  const configPath = path2.resolve(cwd, "khotan.config.ts");
+  if (!fs4.existsSync(configPath)) {
+    console.log("No khotan.config.ts found. Running init...\n");
+    const initOk = await runInit(cwd);
+    if (!initOk) {
+      console.error("\u2717 Init failed. Cannot proceed.");
+      process.exit(1);
+    }
+    console.log("");
+  }
+  const ok = runGenerate(cwd);
+  if (!ok) process.exit(1);
+});
+function isSchemaScaffolded(cwd) {
+  const schemaDir = resolveDrizzleSchemaDir(cwd);
+  if (!schemaDir) return false;
+  return fs4.existsSync(path2.join(cwd, schemaDir, "khotan.ts"));
+}
+var migrateCommand = new Command("migrate").description(
+  "Generate a migration and apply it (or --push to skip migration files)"
+).option("--push", "Push schema directly without generating migration files").action(async (opts) => {
+  const cwd = process.cwd();
+  const configPath = path2.resolve(cwd, "khotan.config.ts");
+  if (!fs4.existsSync(configPath)) {
+    console.log("No khotan.config.ts found. Running init...\n");
+    const initOk = await runInit(cwd);
+    if (!initOk) {
+      console.error("\u2717 Init failed. Cannot proceed.");
+      process.exit(1);
+    }
+    console.log("");
+  }
+  if (!isSchemaScaffolded(cwd)) {
+    console.log("Schema not found. Running generate...\n");
+    const ok = runGenerate(cwd);
+    if (!ok) {
+      console.error("\u2717 Generate failed. Cannot proceed.");
+      process.exit(1);
+    }
+    console.log("");
+  } else {
+    console.log("\u2713 Schema already generated");
+  }
+  const pm = detectPackageManager(cwd);
+  const runner = pm.name === "npm" ? "npx" : pm.name;
+  if (opts.push) {
+    console.log("Pushing schema directly to database...\n");
+    try {
+      execSync(`${runner} drizzle-kit push`, {
+        cwd,
+        stdio: "inherit"
+      });
+      console.log("\n\u2713 Schema pushed to database");
+    } catch {
+      console.error("\n\u2717 drizzle-kit push failed.");
+      console.error(
+        "  Make sure DATABASE_URL is set and drizzle-kit is installed."
+      );
+      process.exit(1);
+    }
+  } else {
+    console.log("Generating migration...\n");
+    try {
+      execSync(`${runner} drizzle-kit generate`, {
+        cwd,
+        stdio: "inherit"
+      });
+      console.log("\n\u2713 Migration file generated");
+    } catch {
+      console.error("\n\u2717 drizzle-kit generate failed.");
+      process.exit(1);
+    }
+    console.log("\nApplying migration...\n");
+    try {
+      execSync(`${runner} drizzle-kit migrate`, {
+        cwd,
+        stdio: "inherit"
+      });
+      console.log("\n\u2713 Migration applied successfully");
+    } catch {
+      console.error("\n\u2717 drizzle-kit migrate failed.");
+      console.error(
+        "  Make sure DATABASE_URL is set and drizzle-kit is installed."
+      );
+      process.exit(1);
+    }
+  }
+});
+
+// src/cli/compare.ts
+function inferShape(value) {
+  if (value === null || value === void 0) {
+    return { type: "null" };
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return { type: "array", items: null };
+    }
+    const merged = mergeShapes(value.map(inferShape));
+    return { type: "array", items: merged };
+  }
+  switch (typeof value) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "object": {
+      const properties = {};
+      for (const [k, v] of Object.entries(value)) {
+        properties[k] = inferShape(v);
+      }
+      return { type: "object", properties };
+    }
+    default:
+      return { type: "string" };
+  }
+}
+function mergeShapes(shapes) {
+  if (shapes.length === 0) return { type: "null" };
+  if (shapes.length === 1) return shapes[0];
+  const objectShapes = shapes.filter(
+    (s) => s.type === "object"
+  );
+  if (objectShapes.length === shapes.length) {
+    const merged = {};
+    for (const shape of objectShapes) {
+      for (const [key, node] of Object.entries(shape.properties)) {
+        if (!merged[key]) {
+          merged[key] = node;
+        } else if (merged[key].type === "object" && node.type === "object") {
+          merged[key] = mergeShapes([merged[key], node]);
+        }
+      }
+    }
+    return { type: "object", properties: merged };
+  }
+  return shapes[0];
+}
+function diffSchemas(expected, actual, basePath = "$") {
+  if ("_type" in expected) {
+    return diffTypedNode(expected, actual, basePath);
+  }
+  return diffObjectSchema(expected, actual, basePath);
+}
+function diffTypedNode(expected, actual, path15) {
+  const expectedType = expected["_type"];
+  if (expectedType === "array") {
+    if (actual.type !== "array") {
+      return [
+        {
+          path: path15,
+          issue: "type_mismatch",
+          note: `expected array, got ${actual.type}`
+        }
+      ];
+    }
+    const itemSchema = expected["items"];
+    if (!itemSchema || !actual.items) return [];
+    return diffSchemas(itemSchema, actual.items, `${path15}[]`);
+  }
+  const normalizedExpected = normalizeType(expectedType);
+  if (normalizedExpected !== actual.type && actual.type !== "null") {
+    return [
+      {
+        path: path15,
+        issue: "type_mismatch",
+        note: `expected ${expectedType}, got ${actual.type}`
+      }
+    ];
+  }
+  return [];
+}
+function diffObjectSchema(expected, actual, path15) {
+  if (actual.type !== "object") {
+    return [
+      {
+        path: path15,
+        issue: "type_mismatch",
+        note: `expected object, got ${actual.type}`
+      }
+    ];
+  }
+  const mismatches = [];
+  const actualProps = actual.properties;
+  for (const [key, typeDesc] of Object.entries(expected)) {
+    const childPath = path15 === "$" ? `$.${key}` : `${path15}.${key}`;
+    const typeStr = typeof typeDesc === "string" ? typeDesc : null;
+    const isOptional = typeStr?.endsWith("?") ?? false;
+    if (!(key in actualProps)) {
+      if (!isOptional) {
+        mismatches.push({ path: childPath, issue: "missing" });
+      }
+      continue;
+    }
+    const actualChild = actualProps[key];
+    if (typeStr !== null) {
+      const baseType = typeStr.replace(/\?$/, "").replace(/ \| null$/, "");
+      if (baseType === "" || baseType === "unknown") ; else if (baseType.endsWith("[]")) {
+        if (actualChild.type !== "array") {
+          mismatches.push({
+            path: childPath,
+            issue: "type_mismatch",
+            note: `expected ${baseType}, got ${actualChild.type}`
+          });
+        }
+      } else if (baseType === "object" && actualChild.type === "object") ; else {
+        const normalizedBase = normalizeType(baseType);
+        if (normalizedBase !== actualChild.type && actualChild.type !== "null") {
+          mismatches.push({
+            path: childPath,
+            issue: "type_mismatch",
+            note: `expected ${baseType}, got ${actualChild.type}`
+          });
+        }
+      }
+    } else if (typeof typeDesc === "object" && typeDesc !== null) {
+      mismatches.push(
+        ...diffSchemas(typeDesc, actualChild, childPath)
+      );
+    }
+  }
+  for (const key of Object.keys(actualProps)) {
+    if (!(key in expected)) {
+      const childPath = path15 === "$" ? `$.${key}` : `${path15}.${key}`;
+      mismatches.push({ path: childPath, issue: "extra" });
+    }
+  }
+  return mismatches;
+}
+function normalizeType(typeStr) {
+  const lower = typeStr.toLowerCase();
+  switch (lower) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "null":
+      return lower;
+    case "integer":
+    case "bigint":
+      return "number";
+    default:
+      return lower;
+  }
+}
+function output(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+function fail(error, hint) {
+  output({ ok: false, error, hint });
+  process.exit(1);
+}
+function parseEnvFile(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    const values = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const match = /^([A-Z0-9_]+)\s*=\s*["']?(.*?)["']?$/.exec(trimmed);
+      if (match) values[match[1]] = match[2];
+    }
+    return values;
+  } catch {
+    return {};
+  }
+}
+function parsePortFromEnvFile(filePath) {
+  const env = parseEnvFile(filePath);
+  const raw = env["PORT"];
+  if (!raw) return null;
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function resolvePort(portFlag) {
+  if (portFlag) return parseInt(portFlag, 10);
+  const cwd = process.cwd();
+  return parsePortFromEnvFile(path2.join(cwd, ".env.local")) ?? parsePortFromEnvFile(path2.join(cwd, ".env")) ?? 3e3;
+}
+async function checkConnectivity(baseUrl) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/plugs`);
+  } catch {
+    fail(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+  if (!res.ok) {
+    fail(
+      "api_unavailable",
+      `Could not reach Khotan API at ${baseUrl}. Check your base path and dev server.`
+    );
+  }
+}
+var varsCommand = new Command("vars").description("View and manage plug variables via the running Khotan API").argument("[plugName]", "Name of the plug whose variables you want to manage").argument("[action]", "Action: show | set | clear").option("--port <port>", "Dev server port").option("--base-path <path>", "API base path", "/api/khotan").option("--list", "List all plugs and their variable state").option("--json <json>", "Variable payload for set (JSON object)").action(
+  async (plugName, action, opts) => {
+    const port = resolvePort(opts.port);
+    const baseUrl = `http://localhost:${port}${opts.basePath}`;
+    await checkConnectivity(baseUrl);
+    if (opts.list) {
+      const plugsRes = await fetch(`${baseUrl}/plugs`);
+      const plugs = await plugsRes.json();
+      const variables = await Promise.all(
+        plugs.map(async (plug) => {
+          const res = await fetch(`${baseUrl}/variables/${plug.name}`);
+          if (res.status === 404) {
+            return {
+              plugName: plug.name,
+              configured: false,
+              fields: [],
+              values: {}
+            };
+          }
+          const data = await res.json();
+          return {
+            plugName: plug.name,
+            configured: data.configured ?? false,
+            fields: data.fields ?? [],
+            values: data.values ?? {}
+          };
+        })
+      );
+      output({ ok: true, variables });
+      return;
+    }
+    if (!plugName) {
+      fail(
+        "missing_plug",
+        "Usage: khotan plug vars <plugName> [show|set|clear] or khotan plug vars --list"
+      );
+    }
+    const resolvedAction = action ?? "show";
+    if (resolvedAction === "show") {
+      const res = await fetch(`${baseUrl}/variables/${plugName}`);
+      if (res.status === 404) {
+        fail("plug_not_found", `Plug "${plugName}" not found.`);
+      }
+      const data = await res.json();
+      output({
+        ok: true,
+        plugName,
+        configured: data.configured ?? false,
+        fields: data.fields ?? [],
+        values: data.values ?? {}
+      });
+      return;
+    }
+    if (resolvedAction === "set") {
+      if (!opts.json) {
+        fail(
+          "missing_json",
+          `Provide --json with a JSON object. Example: khotan plug vars myPlug set --json '{"apiKey":"..."}'`
+        );
+      }
+      let payload;
+      try {
+        payload = JSON.parse(opts.json);
+      } catch {
+        fail("invalid_json", "Could not parse --json as JSON.");
+      }
+      const res = await fetch(`${baseUrl}/variables/${plugName}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        fail(
+          "set_failed",
+          data.error ?? `Failed to set variables for "${plugName}"`
+        );
+      }
+      output({ ok: true, action: "set", plugName });
+      return;
+    }
+    if (resolvedAction === "clear") {
+      const res = await fetch(`${baseUrl}/variables/${plugName}`, {
+        method: "DELETE"
+      });
+      if (!res.ok && res.status !== 204) {
+        const data = await res.json().catch(() => ({}));
+        fail(
+          "clear_failed",
+          data.error ?? `Failed to clear variables for "${plugName}"`
+        );
+      }
+      output({ ok: true, action: "clear", plugName });
+      return;
+    }
+    fail(
+      "invalid_action",
+      `Unknown action "${resolvedAction}". Use show, set, clear, or --list.`
+    );
+  }
+);
+
+// src/cli/commands/probe.ts
+function output2(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+function fail2(error, hint) {
+  output2({ ok: false, error, hint });
+  process.exit(1);
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes}b`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}kb`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}mb`;
+}
+function parsePortFromEnvFile2(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || !trimmed) continue;
+      const match = /^PORT\s*=\s*["']?(\d+)["']?/.exec(trimmed);
+      if (match) return parseInt(match[1], 10);
+    }
+  } catch {
+  }
+  return null;
+}
+function resolvePort2(portFlag) {
+  if (portFlag) return parseInt(portFlag, 10);
+  const cwd = process.cwd();
+  const fromLocal = parsePortFromEnvFile2(path2.join(cwd, ".env.local"));
+  if (fromLocal) return fromLocal;
+  const fromEnv = parsePortFromEnvFile2(path2.join(cwd, ".env"));
+  if (fromEnv) return fromEnv;
+  return 3e3;
+}
+function tryParseJson(value) {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  return value;
+}
+async function checkConnectivity2(baseUrl) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/debug`);
+  } catch {
+    fail2(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+  if (res.status === 404) {
+    fail2(
+      "debug_disabled",
+      "Debug mode is not enabled. Set KHOTAN_DEBUG=1 in your environment and restart."
+    );
+  }
+}
+var plugCommand = new Command("plug").alias("probe").description(
+  "Inspect and test plugs via the running dev server's debug route"
+).argument("[plugName]", "Name of the plug to probe").argument("[method]", "HTTP method (GET, POST, PUT, DELETE, PATCH)").argument("[path]", "Request path (e.g. /products)").option("--port <port>", "Dev server port").option("--base-path <path>", "API base path", "/api/khotan").option("--list", "List all registered plugs").option("--info", "Show plug metadata and endpoints").option("--endpoint <name>", "Fire request using a named endpoint").option("--compare", "Compare response against declared schema").option("--body <json>", "Request body (JSON string)").option("--params <json>", "Query params (JSON string)").option("--headers <json>", "Extra headers (JSON string)").action(
+  async (plugName, method, reqPath, opts) => {
+    const port = resolvePort2(opts.port);
+    const baseUrl = `http://localhost:${port}${opts.basePath}`;
+    if (opts.list) {
+      await checkConnectivity2(baseUrl);
+      try {
+        const res = await fetch(`${baseUrl}/plugs`);
+        const data = await res.json();
+        const raw = Array.isArray(data) ? data : data.plugs ?? [];
+        const plugs = raw.map((p) => ({
+          name: p.name,
+          baseUrl: p.baseUrl,
+          authType: p.authType,
+          varsConfigured: p.varsConfigured ?? false
+        }));
+        output2({ ok: true, plugs });
+      } catch (e) {
+        fail2("fetch_failed", `Failed to fetch plug list: ${String(e)}`);
+      }
+      return;
+    }
+    if (!plugName) {
+      fail2(
+        "missing_plug",
+        "Usage: khotan plug <plugName> [METHOD] [path] [flags]. Use --list to see available plugs."
+      );
+    }
+    await checkConnectivity2(baseUrl);
+    if (opts.info) {
+      try {
+        const res = await fetch(`${baseUrl}/debug/${plugName}`);
+        if (res.status === 404) {
+          fail2(
+            "plug_not_found",
+            `Plug "${plugName}" not found. Use --list to see available plugs.`
+          );
+        }
+        const data = await res.json();
+        output2({ ok: true, plug: data });
+      } catch (e) {
+        fail2("fetch_failed", `Failed to fetch plug info: ${String(e)}`);
+      }
+      return;
+    }
+    let resolvedMethod = method?.toUpperCase();
+    let resolvedPath = reqPath;
+    let allEndpoints = null;
+    if (opts.endpoint) {
+      try {
+        const res = await fetch(`${baseUrl}/debug/${plugName}`);
+        if (res.status === 404) {
+          fail2(
+            "plug_not_found",
+            `Plug "${plugName}" not found. Use --list to see available plugs.`
+          );
+        }
+        const data = await res.json();
+        allEndpoints = data.endpoints ?? null;
+        if (!allEndpoints?.[opts.endpoint]) {
+          fail2(
+            "endpoint_not_found",
+            `Endpoint "${opts.endpoint}" not found on plug "${plugName}". Use --info to see available endpoints.`
+          );
+        }
+        const endpointMeta = allEndpoints[opts.endpoint];
+        resolvedMethod = endpointMeta["method"].toUpperCase();
+        resolvedPath = endpointMeta["path"];
+      } catch (e) {
+        if (e.code === "ECONNREFUSED") {
+          fail2("connect_failed", `Could not connect to dev server.`);
+        }
+        throw e;
+      }
+    }
+    if (!resolvedMethod || !resolvedPath) {
+      fail2(
+        "missing_args",
+        "Provide METHOD and path, or use --endpoint <name>. Example: khotan plug myPlug GET /items"
+      );
+    }
+    let body = void 0;
+    if (opts.body) {
+      try {
+        body = JSON.parse(opts.body);
+      } catch {
+        fail2("invalid_json", "Could not parse --body as JSON.");
+      }
+    }
+    let params;
+    if (opts.params) {
+      try {
+        params = JSON.parse(opts.params);
+      } catch {
+        fail2("invalid_json", "Could not parse --params as JSON.");
+      }
+    }
+    let extraHeaders;
+    if (opts.headers) {
+      try {
+        extraHeaders = JSON.parse(opts.headers);
+      } catch {
+        fail2("invalid_json", "Could not parse --headers as JSON.");
+      }
+    }
+    const debugPayload = {
+      method: resolvedMethod,
+      path: resolvedPath
+    };
+    if (body !== void 0) debugPayload["body"] = body;
+    if (params) debugPayload["params"] = params;
+    if (extraHeaders) debugPayload["headers"] = extraHeaders;
+    let debugRes;
+    try {
+      debugRes = await fetch(`${baseUrl}/debug/${plugName}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(debugPayload)
+      });
+    } catch (e) {
+      fail2("request_failed", `Failed to fire request: ${String(e)}`);
+    }
+    const debugData = await debugRes.json();
+    const rawBody = tryParseJson(debugData["body"]);
+    const responseBodyStr = JSON.stringify(rawBody);
+    const size = formatSize(new TextEncoder().encode(responseBodyStr).length);
+    const debugEndpoint = debugData["endpoint"];
+    const matchedEndpointName = debugEndpoint?.name ?? opts.endpoint ?? null;
+    const responseStatus = debugData["status"] ?? debugRes.status;
+    const isError = responseStatus >= 400;
+    const result = {
+      ok: true,
+      request: {
+        method: resolvedMethod,
+        path: resolvedPath,
+        params: params ?? null,
+        body: body ?? null
+      },
+      response: {
+        status: responseStatus,
+        statusText: debugData["statusText"] ?? debugRes.statusText,
+        timing: debugData["timing"] ?? null,
+        size,
+        headers: debugData["headers"] ?? null,
+        body: rawBody
+      },
+      matchedEndpoint: matchedEndpointName
+    };
+    if (isError && debugData["error"]) {
+      result["response"]["error"] = debugData["error"];
+    }
+    if (opts.compare) {
+      if (!matchedEndpointName) {
+        result["comparison"] = null;
+        result["comparisonNote"] = "No typed endpoint matched this request. Define endpoints on your plug to enable comparison.";
+      } else if (isError) {
+        result["comparison"] = null;
+        result["comparisonNote"] = `Response status ${responseStatus} \u2014 comparison skipped (schemas describe success responses).`;
+      } else {
+        if (!allEndpoints) {
+          try {
+            const metaRes = await fetch(`${baseUrl}/debug/${plugName}`);
+            const metaData = await metaRes.json();
+            allEndpoints = metaData.endpoints ?? null;
+          } catch {
+          }
+        }
+        const ep = allEndpoints?.[matchedEndpointName];
+        const responses = ep?.["responses"];
+        const responseSchema = responses?.["200"] ?? null;
+        if (!responseSchema) {
+          result["comparison"] = null;
+          result["comparisonNote"] = "No response schema defined for this endpoint";
+        } else {
+          const actualShape = inferShape(rawBody);
+          const mismatches = diffSchemas(responseSchema, actualShape);
+          result["comparison"] = {
+            match: mismatches.length === 0,
+            expected: responseSchema,
+            actual: actualShape,
+            mismatches
+          };
+        }
+      }
+    }
+    output2(result);
+  }
+);
+plugCommand.addCommand(varsCommand);
+function output3(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+function fail3(error, hint) {
+  output3({ ok: false, error, hint });
+  process.exit(1);
+}
+function parseEnvFile2(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    const values = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const match = /^([A-Z0-9_]+)\s*=\s*["']?(.*?)["']?$/.exec(trimmed);
+      if (match) values[match[1]] = match[2];
+    }
+    return values;
+  } catch {
+    return {};
+  }
+}
+function parsePortFromEnvFile3(filePath) {
+  const env = parseEnvFile2(filePath);
+  const raw = env["PORT"];
+  if (!raw) return null;
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function resolvePort3(portFlag) {
+  if (portFlag) return parseInt(portFlag, 10);
+  const cwd = process.cwd();
+  return parsePortFromEnvFile3(path2.join(cwd, ".env.local")) ?? parsePortFromEnvFile3(path2.join(cwd, ".env")) ?? 3e3;
+}
+function resolveWebhookOrigin(originFlag) {
+  if (originFlag) return originFlag.replace(/\/$/, "");
+  const cwd = process.cwd();
+  const env = {
+    ...parseEnvFile2(path2.join(cwd, ".env")),
+    ...parseEnvFile2(path2.join(cwd, ".env.local"))
+  };
+  const origin = env["KHOTAN_WEBHOOK_URL"] ?? env["NGROK_URL"] ?? env["NEXT_PUBLIC_APP_URL"] ?? `http://localhost:${resolvePort3(void 0)}`;
+  return origin.replace(/\/$/, "");
+}
+async function checkConnectivity3(baseUrl) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/plugs`);
+  } catch {
+    fail3(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+  if (!res.ok) {
+    fail3(
+      "api_unavailable",
+      `Could not reach Khotan API at ${baseUrl}. Check your base path and dev server.`
+    );
+  }
+}
+var wireCommand = new Command("wire").description(
+  "Inspect, connect, and disconnect wires via the running Khotan API"
+).argument("[plugName]", "Name of the plug whose wire you want to manage").argument("[action]", "Action: info | connect | disconnect").option("--port <port>", "Dev server port").option("--base-path <path>", "API base path", "/api/khotan").option(
+  "--list",
+  "List configured plugs and whether they currently have a wire"
+).option("--info", "Show current wire state for the plug").option("--callback-url <url>", "Explicit callback URL to register").option("--webhook-origin <url>", "Origin used to build default callback URL").option(
+  "--wire-id <id>",
+  "Explicit wire ID for disconnect (otherwise current wire is used)"
+).action(
+  async (plugName, action, opts) => {
+    const port = resolvePort3(opts.port);
+    const baseUrl = `http://localhost:${port}${opts.basePath}`;
+    await checkConnectivity3(baseUrl);
+    if (opts.list) {
+      const plugsRes = await fetch(`${baseUrl}/plugs`);
+      const plugs = await plugsRes.json();
+      const wires = await Promise.all(
+        plugs.map(async (plug) => {
+          const res = await fetch(`${baseUrl}/wires/${plug.name}`);
+          const data = await res.json();
+          return {
+            plugName: plug.name,
+            configured: data.configured ?? false,
+            connected: data.wire?.status === "active",
+            wire: data.wire ?? null
+          };
+        })
+      );
+      output3({ ok: true, wires });
+      return;
+    }
+    if (!plugName) {
+      fail3(
+        "missing_plug",
+        "Usage: khotan wire <plugName> [info|connect|disconnect] or khotan wire --list"
+      );
+    }
+    const resolvedAction = opts.info ? "info" : action ?? "info";
+    if (resolvedAction === "info") {
+      const res = await fetch(`${baseUrl}/wires/${plugName}`);
+      if (res.status === 404) {
+        fail3("plug_not_found", `Plug "${plugName}" not found.`);
+      }
+      const data = await res.json();
+      output3({
+        ok: true,
+        plugName,
+        configured: data.configured ?? false,
+        wire: data.wire ?? null
+      });
+      return;
+    }
+    if (resolvedAction === "connect") {
+      const callbackUrl = opts.callbackUrl ?? `${resolveWebhookOrigin(opts.webhookOrigin)}/api/khotan/webhook/${plugName}`;
+      const res = await fetch(`${baseUrl}/wires/${plugName}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ callbackUrl })
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        fail3(
+          "connect_failed",
+          data.error ?? `Failed to connect wire for "${plugName}"`
+        );
+      }
+      output3({
+        ok: true,
+        action: "connect",
+        plugName,
+        callbackUrl,
+        wire: data.wire ?? null
+      });
+      return;
+    }
+    if (resolvedAction === "disconnect") {
+      let wireId = opts.wireId;
+      if (!wireId) {
+        const currentRes = await fetch(`${baseUrl}/wires/${plugName}`);
+        const current = await currentRes.json();
+        wireId = current.wire?.id;
+      }
+      if (!wireId) {
+        fail3(
+          "missing_wire",
+          `No active wire found for "${plugName}". Use --wire-id to override.`
+        );
+      }
+      const res = await fetch(`${baseUrl}/wires/${plugName}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ wireId })
+      });
+      if (!res.ok && res.status !== 204) {
+        const data = await res.json();
+        fail3(
+          "disconnect_failed",
+          data.error ?? `Failed to disconnect wire "${wireId}"`
+        );
+      }
+      output3({ ok: true, action: "disconnect", plugName, wireId });
+      return;
+    }
+    fail3(
+      "invalid_action",
+      `Unknown action "${resolvedAction}". Use info, connect, disconnect, or --list.`
+    );
+  }
+);
+function output4(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+function fail4(error, hint) {
+  output4({ ok: false, error, hint });
+  process.exit(1);
+}
+function parseEnvFile3(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    const values = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const match = /^([A-Z0-9_]+)\s*=\s*["']?(.*?)["']?$/.exec(trimmed);
+      if (match) values[match[1]] = match[2];
+    }
+    return values;
+  } catch {
+    return {};
+  }
+}
+function parsePortFromEnvFile4(filePath) {
+  const raw = parseEnvFile3(filePath)["PORT"];
+  if (!raw) return null;
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function resolvePort4(portFlag) {
+  if (portFlag) return parseInt(portFlag, 10);
+  const cwd = process.cwd();
+  return parsePortFromEnvFile4(path2.join(cwd, ".env.local")) ?? parsePortFromEnvFile4(path2.join(cwd, ".env")) ?? 3e3;
+}
+function resolveBaseUrl(opts) {
+  return `http://localhost:${resolvePort4(opts.port)}${opts.basePath}`;
+}
+async function fetchJson(url, init) {
+  const res = await fetch(url, init);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    fail4(
+      "request_failed",
+      data.error ?? `Request to ${url} failed with status ${res.status}`
+    );
+  }
+  return data;
+}
+async function checkConnectivity4(baseUrl) {
+  try {
+    const res = await fetch(`${baseUrl}/flows`);
+    if (!res.ok) {
+      fail4(
+        "api_unavailable",
+        `Could not reach Khotan flows API at ${baseUrl}. Check your base path and dev server.`
+      );
+    }
+  } catch {
+    fail4(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+}
+function parseJsonOption(value, label) {
+  if (!value) return void 0;
+  try {
+    return JSON.parse(value);
+  } catch {
+    fail4("invalid_json", `${label} must be valid JSON.`);
+  }
+}
+async function listFlows(baseUrl) {
+  const data = await fetchJson(
+    `${baseUrl}/flows`
+  );
+  return Array.isArray(data) ? data : data.flows ?? [];
+}
+function resolveFlow(flows, flowNameOrId, plugName) {
+  const byId = flows.find((flow) => flow.id === flowNameOrId);
+  if (byId) {
+    if (plugName && byId.plugName !== plugName) {
+      fail4(
+        "flow_not_found",
+        `Flow ID "${flowNameOrId}" is not registered on plug "${plugName}".`
+      );
+    }
+    return byId;
+  }
+  const matches = flows.filter(
+    (flow) => flow.name === flowNameOrId && (!plugName || flow.plugName === plugName)
+  );
+  if (matches.length === 0) {
+    const suffix = plugName ? ` on plug "${plugName}"` : "";
+    fail4("flow_not_found", `Flow "${flowNameOrId}"${suffix} not found.`);
+  }
+  if (matches.length > 1) {
+    const plugs = matches.map((flow) => flow.plugName).filter(Boolean).join(", ");
+    fail4(
+      "ambiguous_flow",
+      `Flow "${flowNameOrId}" is registered on multiple plugs (${plugs}). Pass --plug <plugName>.`
+    );
+  }
+  return matches[0];
+}
+function withApiOptions(command) {
+  return command.option("--port <port>", "Dev server port").option("--base-path <path>", "API base path", "/api/khotan");
+}
+var flowsCommand = new Command("flows").alias("flow").description("List, trigger, and inspect flows via the running Khotan API");
+withApiOptions(
+  flowsCommand.command("list").description("List registered flows").option("--plug <plugName>", "Only show flows for one plug")
+).action(async (opts) => {
+  const baseUrl = resolveBaseUrl(opts);
+  await checkConnectivity4(baseUrl);
+  const flows = (await listFlows(baseUrl)).filter(
+    (flow) => !opts.plug || flow.plugName === opts.plug
+  );
+  output4({ ok: true, flows });
+});
+withApiOptions(
+  flowsCommand.command("info").description("Show one flow by name or ID").argument("<flowNameOrId>", "Flow name or ID").option("--plug <plugName>", "Disambiguate by plug name")
+).action(async (flowNameOrId, opts) => {
+  const baseUrl = resolveBaseUrl(opts);
+  await checkConnectivity4(baseUrl);
+  const flow = resolveFlow(await listFlows(baseUrl), flowNameOrId, opts.plug);
+  output4({ ok: true, flow });
+});
+withApiOptions(
+  flowsCommand.command("trigger").description("Start a tracked flow run").argument("<flowNameOrId>", "Flow name or ID").option("--plug <plugName>", "Disambiguate by plug name").option(
+    "--run-type <type>",
+    "Run type: full, delta, backfill, reconcile, dry-run",
+    "full"
+  ).option("--body <json>", "JSON body passed to the flow context")
+).action(
+  async (flowNameOrId, opts) => {
+    const baseUrl = resolveBaseUrl(opts);
+    await checkConnectivity4(baseUrl);
+    const flow = resolveFlow(await listFlows(baseUrl), flowNameOrId, opts.plug);
+    const requestBody = { runType: opts.runType };
+    const body = parseJsonOption(opts.body, "--body");
+    if (body !== void 0) requestBody["body"] = body;
+    const run = await fetchJson(
+      `${baseUrl}/flows/${encodeURIComponent(flow.id)}/runs`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(requestBody)
+      }
+    );
+    output4({ ok: true, action: "trigger", flow, run });
+  }
+);
+withApiOptions(
+  flowsCommand.command("runs").description("List runs for one flow").argument("<flowNameOrId>", "Flow name or ID").option("--plug <plugName>", "Disambiguate by plug name")
+).action(async (flowNameOrId, opts) => {
+  const baseUrl = resolveBaseUrl(opts);
+  await checkConnectivity4(baseUrl);
+  const flow = resolveFlow(await listFlows(baseUrl), flowNameOrId, opts.plug);
+  const runs = await fetchJson(
+    `${baseUrl}/flows/${encodeURIComponent(flow.id)}/runs`
+  );
+  output4({ ok: true, flow, runs });
+});
+withApiOptions(
+  flowsCommand.command("cancel").description("Cancel a running Workflow-backed Khotan run").argument("<runId>", "Khotan run ID")
+).action(async (runId, opts) => {
+  const baseUrl = resolveBaseUrl(opts);
+  await checkConnectivity4(baseUrl);
+  const run = await fetchJson(
+    `${baseUrl}/runs/${encodeURIComponent(runId)}/cancel`,
+    { method: "POST" }
+  );
+  output4({ ok: true, action: "cancel", run });
+});
+function output5(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+function fail5(error, hint) {
+  output5({ ok: false, error, hint });
+  process.exit(1);
+}
+function parseEnvFile4(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    const values = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const match = /^([A-Z0-9_]+)\s*=\s*["']?(.*?)["']?$/.exec(trimmed);
+      if (match) values[match[1]] = match[2];
+    }
+    return values;
+  } catch {
+    return {};
+  }
+}
+function parsePortFromEnvFile5(filePath) {
+  const raw = parseEnvFile4(filePath)["PORT"];
+  if (!raw) return null;
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function resolvePort5(portFlag) {
+  if (portFlag) return parseInt(portFlag, 10);
+  const cwd = process.cwd();
+  return parsePortFromEnvFile5(path2.join(cwd, ".env.local")) ?? parsePortFromEnvFile5(path2.join(cwd, ".env")) ?? 3e3;
+}
+function resolveBaseUrl2(opts) {
+  return `http://localhost:${resolvePort5(opts.port)}${opts.basePath}`;
+}
+async function fetchJson2(url, init) {
+  const res = await fetch(url, init);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    fail5(
+      "request_failed",
+      data.error ?? `Request to ${url} failed with status ${res.status}`
+    );
+  }
+  return data;
+}
+async function checkConnectivity5(baseUrl) {
+  try {
+    const res = await fetch(`${baseUrl}/flows`);
+    if (!res.ok) {
+      fail5(
+        "api_unavailable",
+        `Could not reach Khotan flows API at ${baseUrl}. Check your base path and dev server.`
+      );
+    }
+  } catch {
+    fail5(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+}
+function parseJsonObjectOption(value, label) {
+  if (!value) return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      fail5("invalid_json", `${label} must be a JSON object.`);
+    }
+    return parsed;
+  } catch {
+    fail5("invalid_json", `${label} must be valid JSON.`);
+  }
+}
+function withApiOptions2(command) {
+  return command.option("--port <port>", "Dev server port").option("--base-path <path>", "API base path", "/api/khotan");
+}
+async function listResources(baseUrl) {
+  return fetchJson2(`${baseUrl}/resources`);
+}
+async function resolveResource(baseUrl, resourceNameOrId) {
+  const resources = await listResources(baseUrl);
+  const match = resources.find(
+    (resource) => resource.id === resourceNameOrId || resource.name === resourceNameOrId
+  );
+  if (!match) {
+    fail5(
+      "resource_not_found",
+      `Resource "${resourceNameOrId}" is not registered in the running Khotan config.`
+    );
+  }
+  return match;
+}
+var mappingsCommand = new Command("mappings").description("List, lookup, and mutate mappings via the running Khotan API");
+withApiOptions2(
+  mappingsCommand.command("list").description("List mappings for one resource").argument("<resource>", "Resource name or ID").option("--limit <limit>", "Page size", "20").option("--offset <offset>", "Page offset", "0").option("--search <term>", "Search connectValue, refs, and metadata")
+).action(
+  async (resourceNameOrId, opts) => {
+    const baseUrl = resolveBaseUrl2(opts);
+    await checkConnectivity5(baseUrl);
+    const resource = await resolveResource(baseUrl, resourceNameOrId);
+    const limit = Math.max(parseInt(opts.limit, 10) || 20, 1);
+    const offset = Math.max(parseInt(opts.offset, 10) || 0, 0);
+    const url = new URL(
+      `${baseUrl}/resources/${encodeURIComponent(resource.id)}/mappings`
+    );
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("offset", String(offset));
+    if (opts.search) {
+      url.searchParams.set("search", opts.search);
+    }
+    const data = await fetchJson2(url.toString());
+    output5({
+      ok: true,
+      resource,
+      items: data.items,
+      page: data.page
+    });
+  }
+);
+withApiOptions2(
+  mappingsCommand.command("lookup").description("Lookup a mapping by connect value or plug ref").argument("<resource>", "Resource name or ID").option("--connect-value <value>", "Lookup by canonical connect value").option("--plug <plugName>", "Lookup by plug name").option("--ref <ref>", "Lookup by plug ref")
+).action(
+  async (resourceNameOrId, opts) => {
+    const usingConnectValue = typeof opts.connectValue === "string";
+    const usingPlugRef = typeof opts.plug === "string" || typeof opts.ref === "string";
+    if (!usingConnectValue && !usingPlugRef) {
+      fail5(
+        "validation_error",
+        "Pass either --connect-value <value> or --plug <plugName> with --ref <ref>."
+      );
+    }
+    if (usingConnectValue && usingPlugRef) {
+      fail5(
+        "validation_error",
+        "Choose one lookup mode: either --connect-value or --plug with --ref."
+      );
+    }
+    if (opts.plug && !opts.ref || !opts.plug && opts.ref) {
+      fail5(
+        "validation_error",
+        "Plug-ref lookup requires both --plug <plugName> and --ref <ref>."
+      );
+    }
+    const baseUrl = resolveBaseUrl2(opts);
+    await checkConnectivity5(baseUrl);
+    const resource = await resolveResource(baseUrl, resourceNameOrId);
+    const payload = usingConnectValue ? {
+      resourceId: resource.id,
+      connectValue: opts.connectValue
+    } : {
+      resourceId: resource.id,
+      plugName: opts.plug,
+      ref: opts.ref
+    };
+    const mapping = await fetchJson2(
+      `${baseUrl}/mappings/lookup`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      }
+    );
+    output5({ ok: true, resource, mapping });
+  }
+);
+withApiOptions2(
+  mappingsCommand.command("upsert").description("Create or update one mapping by canonical connect value").argument("<resource>", "Resource name or ID").requiredOption("--connect-value <value>", "Canonical connect value").requiredOption("--refs <json>", "JSON object of refs keyed by plug name").option("--metadata <json>", "Optional JSON object of contextual metadata")
+).action(
+  async (resourceNameOrId, opts) => {
+    const baseUrl = resolveBaseUrl2(opts);
+    await checkConnectivity5(baseUrl);
+    const resource = await resolveResource(baseUrl, resourceNameOrId);
+    const refs = parseJsonObjectOption(opts.refs, "--refs");
+    const metadata = parseJsonObjectOption(opts.metadata, "--metadata");
+    const mapping = await fetchJson2(`${baseUrl}/mappings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        resourceId: resource.id,
+        connectValue: opts.connectValue,
+        refs,
+        metadata
+      })
+    });
+    output5({ ok: true, action: "upsert", resource, mapping });
+  }
+);
+withApiOptions2(
+  mappingsCommand.command("update").description("Update one mapping by row ID").argument("<mappingId>", "Mapping row ID").requiredOption("--resource <resource>", "Resource name or ID").requiredOption("--connect-value <value>", "Canonical connect value").requiredOption("--refs <json>", "JSON object of refs keyed by plug name").option("--metadata <json>", "Optional JSON object of contextual metadata")
+).action(
+  async (mappingId, opts) => {
+    const baseUrl = resolveBaseUrl2(opts);
+    await checkConnectivity5(baseUrl);
+    const resource = await resolveResource(baseUrl, opts.resource);
+    const refs = parseJsonObjectOption(opts.refs, "--refs");
+    const metadata = parseJsonObjectOption(opts.metadata, "--metadata");
+    const mapping = await fetchJson2(
+      `${baseUrl}/mappings/${encodeURIComponent(mappingId)}`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          resourceId: resource.id,
+          connectValue: opts.connectValue,
+          refs,
+          metadata
+        })
+      }
+    );
+    output5({ ok: true, action: "update", resource, mapping });
+  }
+);
+withApiOptions2(
+  mappingsCommand.command("delete").description("Delete one mapping by row ID").argument("<mappingId>", "Mapping row ID")
+).action(async (mappingId, opts) => {
+  const baseUrl = resolveBaseUrl2(opts);
+  await checkConnectivity5(baseUrl);
+  const res = await fetch(`${baseUrl}/mappings/${encodeURIComponent(mappingId)}`, {
+    method: "DELETE"
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    fail5(
+      "request_failed",
+      data.error ?? `Delete request failed for mapping "${mappingId}" with status ${res.status}.`
+    );
+  }
+  output5({ ok: true, action: "delete", id: mappingId });
+});
+
+// src/cli/index.ts
+var program = new Command();
+program.name("khotan").description("Scaffold data components into your project").version("0.0.1");
+program.addCommand(initCommand);
+program.addCommand(addCommand);
+program.addCommand(generateCommand);
+program.addCommand(migrateCommand);
+program.addCommand(plugCommand);
+program.addCommand(wireCommand);
+program.addCommand(flowsCommand);
+program.addCommand(mappingsCommand);
+program.parse();