khotan-data 0.1.0 → 0.2.0

package/dist/cli.js

@@ -5,6 +5,7 @@ import path2 from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import prompts2 from 'prompts';
+import crypto from 'crypto';
 
 // src/cli/config-template.ts
 function configTemplate(outputDir) {
@@ -152,6 +153,11 @@ var COMPONENTS = {
         outputFile: "wires/wire.ts",
         outputBase: "outputDir"
       },
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
       {
         templatePath: path2.resolve(__dirname$1, "templates", "wire-panel.tsx"),
         outputFile: "wire.tsx",
@@ -168,6 +174,23 @@ var COMPONENTS = {
       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",
@@ -185,6 +208,11 @@ var COMPONENTS = {
       ]
     },
     files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
       {
         templatePath: path2.resolve(__dirname$1, "templates", "hub.tsx"),
         outputFile: "hub.tsx",
@@ -210,6 +238,11 @@ var COMPONENTS = {
       shadcnComponents: ["card", "table", "badge", "button"]
     },
     files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
       {
         templatePath: path2.resolve(__dirname$1, "templates", "logs.tsx"),
         outputFile: "logs.tsx",
@@ -231,6 +264,30 @@ var 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", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
+      {
+        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",
@@ -240,6 +297,11 @@ var COMPONENTS = {
       shadcnComponents: ["card", "badge", "button", "input", "label"]
     },
     files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
       {
         templatePath: path2.resolve(__dirname$1, "templates", "plug-debugger.tsx"),
         outputFile: "plug-debugger.tsx",
@@ -462,6 +524,22 @@ var BLOCKS = {
       }
     ]
   },
+  "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",
@@ -471,6 +549,11 @@ var BLOCKS = {
       shadcnComponents: ["card", "badge"]
     },
     files: [
+      {
+        templatePath: path2.resolve(__dirname$1, "templates", "api-state.tsx"),
+        outputFile: "api-state.tsx",
+        outputBase: "components"
+      },
       {
         templatePath: path2.resolve(
           __dirname$1,
@@ -1722,13 +1805,13 @@ function diffSchemas(expected, actual, basePath = "$") {
   }
   return diffObjectSchema(expected, actual, basePath);
 }
-function diffTypedNode(expected, actual, path14) {
+function diffTypedNode(expected, actual, path16) {
   const expectedType = expected["_type"];
   if (expectedType === "array") {
     if (actual.type !== "array") {
       return [
         {
-          path: path14,
+          path: path16,
           issue: "type_mismatch",
           note: `expected array, got ${actual.type}`
         }
@@ -1736,13 +1819,13 @@ function diffTypedNode(expected, actual, path14) {
     }
     const itemSchema = expected["items"];
     if (!itemSchema || !actual.items) return [];
-    return diffSchemas(itemSchema, actual.items, `${path14}[]`);
+    return diffSchemas(itemSchema, actual.items, `${path16}[]`);
   }
   const normalizedExpected = normalizeType(expectedType);
   if (normalizedExpected !== actual.type && actual.type !== "null") {
     return [
       {
-        path: path14,
+        path: path16,
         issue: "type_mismatch",
         note: `expected ${expectedType}, got ${actual.type}`
       }
@@ -1750,11 +1833,11 @@ function diffTypedNode(expected, actual, path14) {
   }
   return [];
 }
-function diffObjectSchema(expected, actual, path14) {
+function diffObjectSchema(expected, actual, path16) {
   if (actual.type !== "object") {
     return [
       {
-        path: path14,
+        path: path16,
         issue: "type_mismatch",
         note: `expected object, got ${actual.type}`
       }
@@ -1763,7 +1846,7 @@ function diffObjectSchema(expected, actual, path14) {
   const mismatches = [];
   const actualProps = actual.properties;
   for (const [key, typeDesc] of Object.entries(expected)) {
-    const childPath = path14 === "$" ? `$.${key}` : `${path14}.${key}`;
+    const childPath = path16 === "$" ? `$.${key}` : `${path16}.${key}`;
     const typeStr = typeof typeDesc === "string" ? typeDesc : null;
     const isOptional = typeStr?.endsWith("?") ?? false;
     if (!(key in actualProps)) {
@@ -1801,7 +1884,7 @@ function diffObjectSchema(expected, actual, path14) {
   }
   for (const key of Object.keys(actualProps)) {
     if (!(key in expected)) {
-      const childPath = path14 === "$" ? `$.${key}` : `${path14}.${key}`;
+      const childPath = path16 === "$" ? `$.${key}` : `${path16}.${key}`;
       mismatches.push({ path: childPath, issue: "extra" });
     }
   }
@@ -1822,6 +1905,48 @@ function normalizeType(typeStr) {
       return lower;
   }
 }
+var CLI_TOKEN_SCHEME = "KhotanCLI";
+function readSecretFromEnvFile(filePath) {
+  try {
+    const content = fs4.readFileSync(filePath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const match = /^KHOTAN_SECRET\s*=\s*["']?(.*?)["']?\s*$/.exec(trimmed);
+      if (match) return match[1] ?? null;
+    }
+  } catch {
+  }
+  return null;
+}
+function resolveKhotanSecret(cwd = process.cwd()) {
+  const fromEnv = process.env["KHOTAN_SECRET"]?.trim();
+  if (fromEnv) return fromEnv;
+  return readSecretFromEnvFile(path2.join(cwd, ".env.local")) ?? readSecretFromEnvFile(path2.join(cwd, ".env")) ?? null;
+}
+function cliAuthHeader() {
+  const secret = resolveKhotanSecret();
+  if (!secret) return null;
+  const timestamp = String(Date.now());
+  const sig = crypto.createHmac("sha256", secret).update(`khotan-cli:${timestamp}`).digest("hex");
+  return `${CLI_TOKEN_SCHEME} ${timestamp}.${sig}`;
+}
+function cliFetch(url, init) {
+  const auth = cliAuthHeader();
+  if (!auth) {
+    return init === void 0 ? fetch(url) : fetch(url, init);
+  }
+  const headers = {
+    ...init?.headers ?? {},
+    Authorization: auth
+  };
+  return fetch(url, { ...init, headers });
+}
+function unauthorizedHint() {
+  return resolveKhotanSecret() ? "Unauthorized. The dev server rejected the CLI token \u2014 confirm KHOTAN_SECRET matches the value the server is running with." : "Unauthorized. Set KHOTAN_SECRET in your environment (or .env.local) so the CLI can authenticate against your authorize() hook.";
+}
+
+// src/cli/commands/plug-vars.ts
 function output(obj) {
   process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
 }
@@ -1859,13 +1984,14 @@ function resolvePort(portFlag) {
 async function checkConnectivity(baseUrl) {
   let res;
   try {
-    res = await fetch(`${baseUrl}/plugs`);
+    res = await cliFetch(`${baseUrl}/plugs`);
   } catch {
     fail(
       "connect_failed",
       `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
     );
   }
+  if (res.status === 401) fail("unauthorized", unauthorizedHint());
   if (!res.ok) {
     fail(
       "api_unavailable",
@@ -1879,11 +2005,11 @@ var varsCommand = new Command("vars").description("View and manage plug variable
     const baseUrl = `http://localhost:${port}${opts.basePath}`;
     await checkConnectivity(baseUrl);
     if (opts.list) {
-      const plugsRes = await fetch(`${baseUrl}/plugs`);
+      const plugsRes = await cliFetch(`${baseUrl}/plugs`);
       const plugs = await plugsRes.json();
       const variables = await Promise.all(
         plugs.map(async (plug) => {
-          const res = await fetch(`${baseUrl}/variables/${plug.name}`);
+          const res = await cliFetch(`${baseUrl}/variables/${plug.name}`);
           if (res.status === 404) {
             return {
               plugName: plug.name,
@@ -1912,7 +2038,7 @@ var varsCommand = new Command("vars").description("View and manage plug variable
     }
     const resolvedAction = action ?? "show";
     if (resolvedAction === "show") {
-      const res = await fetch(`${baseUrl}/variables/${plugName}`);
+      const res = await cliFetch(`${baseUrl}/variables/${plugName}`);
       if (res.status === 404) {
         fail("plug_not_found", `Plug "${plugName}" not found.`);
       }
@@ -1939,7 +2065,7 @@ var varsCommand = new Command("vars").description("View and manage plug variable
       } catch {
         fail("invalid_json", "Could not parse --json as JSON.");
       }
-      const res = await fetch(`${baseUrl}/variables/${plugName}`, {
+      const res = await cliFetch(`${baseUrl}/variables/${plugName}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(payload)
@@ -1955,7 +2081,7 @@ var varsCommand = new Command("vars").description("View and manage plug variable
       return;
     }
     if (resolvedAction === "clear") {
-      const res = await fetch(`${baseUrl}/variables/${plugName}`, {
+      const res = await cliFetch(`${baseUrl}/variables/${plugName}`, {
         method: "DELETE"
       });
       if (!res.ok && res.status !== 204) {
@@ -2023,7 +2149,7 @@ function tryParseJson(value) {
 async function checkConnectivity2(baseUrl) {
   let res;
   try {
-    res = await fetch(`${baseUrl}/debug`);
+    res = await cliFetch(`${baseUrl}/debug`);
   } catch {
     fail2(
       "connect_failed",
@@ -2046,7 +2172,8 @@ var plugCommand = new Command("plug").alias("probe").description(
     if (opts.list) {
       await checkConnectivity2(baseUrl);
       try {
-        const res = await fetch(`${baseUrl}/plugs`);
+        const res = await cliFetch(`${baseUrl}/plugs`);
+        if (res.status === 401) fail2("unauthorized", unauthorizedHint());
         const data = await res.json();
         const raw = Array.isArray(data) ? data : data.plugs ?? [];
         const plugs = raw.map((p) => ({
@@ -2070,7 +2197,7 @@ var plugCommand = new Command("plug").alias("probe").description(
     await checkConnectivity2(baseUrl);
     if (opts.info) {
       try {
-        const res = await fetch(`${baseUrl}/debug/${plugName}`);
+        const res = await cliFetch(`${baseUrl}/debug/${plugName}`);
         if (res.status === 404) {
           fail2(
             "plug_not_found",
@@ -2089,7 +2216,7 @@ var plugCommand = new Command("plug").alias("probe").description(
     let allEndpoints = null;
     if (opts.endpoint) {
       try {
-        const res = await fetch(`${baseUrl}/debug/${plugName}`);
+        const res = await cliFetch(`${baseUrl}/debug/${plugName}`);
         if (res.status === 404) {
           fail2(
             "plug_not_found",
@@ -2153,7 +2280,7 @@ var plugCommand = new Command("plug").alias("probe").description(
     if (extraHeaders) debugPayload["headers"] = extraHeaders;
     let debugRes;
     try {
-      debugRes = await fetch(`${baseUrl}/debug/${plugName}`, {
+      debugRes = await cliFetch(`${baseUrl}/debug/${plugName}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(debugPayload)
@@ -2200,7 +2327,7 @@ var plugCommand = new Command("plug").alias("probe").description(
       } else {
         if (!allEndpoints) {
           try {
-            const metaRes = await fetch(`${baseUrl}/debug/${plugName}`);
+            const metaRes = await cliFetch(`${baseUrl}/debug/${plugName}`);
             const metaData = await metaRes.json();
             allEndpoints = metaData.endpoints ?? null;
           } catch {
@@ -2275,13 +2402,14 @@ function resolveWebhookOrigin(originFlag) {
 async function checkConnectivity3(baseUrl) {
   let res;
   try {
-    res = await fetch(`${baseUrl}/plugs`);
+    res = await cliFetch(`${baseUrl}/plugs`);
   } catch {
     fail3(
       "connect_failed",
       `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
     );
   }
+  if (res.status === 401) fail3("unauthorized", unauthorizedHint());
   if (!res.ok) {
     fail3(
       "api_unavailable",
@@ -2303,11 +2431,11 @@ var wireCommand = new Command("wire").description(
     const baseUrl = `http://localhost:${port}${opts.basePath}`;
     await checkConnectivity3(baseUrl);
     if (opts.list) {
-      const plugsRes = await fetch(`${baseUrl}/plugs`);
+      const plugsRes = await cliFetch(`${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 res = await cliFetch(`${baseUrl}/wires/${plug.name}`);
           const data = await res.json();
           return {
             plugName: plug.name,
@@ -2328,7 +2456,7 @@ var wireCommand = new Command("wire").description(
     }
     const resolvedAction = opts.info ? "info" : action ?? "info";
     if (resolvedAction === "info") {
-      const res = await fetch(`${baseUrl}/wires/${plugName}`);
+      const res = await cliFetch(`${baseUrl}/wires/${plugName}`);
       if (res.status === 404) {
         fail3("plug_not_found", `Plug "${plugName}" not found.`);
       }
@@ -2343,7 +2471,7 @@ var wireCommand = new Command("wire").description(
     }
     if (resolvedAction === "connect") {
       const callbackUrl = opts.callbackUrl ?? `${resolveWebhookOrigin(opts.webhookOrigin)}/api/khotan/webhook/${plugName}`;
-      const res = await fetch(`${baseUrl}/wires/${plugName}`, {
+      const res = await cliFetch(`${baseUrl}/wires/${plugName}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ callbackUrl })
@@ -2367,7 +2495,7 @@ var wireCommand = new Command("wire").description(
     if (resolvedAction === "disconnect") {
       let wireId = opts.wireId;
       if (!wireId) {
-        const currentRes = await fetch(`${baseUrl}/wires/${plugName}`);
+        const currentRes = await cliFetch(`${baseUrl}/wires/${plugName}`);
         const current = await currentRes.json();
         wireId = current.wire?.id;
       }
@@ -2377,7 +2505,7 @@ var wireCommand = new Command("wire").description(
           `No active wire found for "${plugName}". Use --wire-id to override.`
         );
       }
-      const res = await fetch(`${baseUrl}/wires/${plugName}`, {
+      const res = await cliFetch(`${baseUrl}/wires/${plugName}`, {
         method: "DELETE",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ wireId })
@@ -2435,9 +2563,10 @@ function resolveBaseUrl(opts) {
   return `http://localhost:${resolvePort4(opts.port)}${opts.basePath}`;
 }
 async function fetchJson(url, init) {
-  const res = await fetch(url, init);
+  const res = await cliFetch(url, init);
   const data = await res.json().catch(() => ({}));
   if (!res.ok) {
+    if (res.status === 401) fail4("unauthorized", unauthorizedHint());
     fail4(
       "request_failed",
       data.error ?? `Request to ${url} failed with status ${res.status}`
@@ -2446,20 +2575,22 @@ async function fetchJson(url, init) {
   return data;
 }
 async function checkConnectivity4(baseUrl) {
+  let res;
   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.`
-      );
-    }
+    res = await cliFetch(`${baseUrl}/flows`);
   } catch {
     fail4(
       "connect_failed",
       `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
     );
   }
+  if (res.status === 401) fail4("unauthorized", unauthorizedHint());
+  if (!res.ok) {
+    fail4(
+      "api_unavailable",
+      `Could not reach Khotan flows API at ${baseUrl}. Check your base path and dev server.`
+    );
+  }
 }
 function parseJsonOption(value, label) {
   if (!value) return void 0;
@@ -2571,6 +2702,244 @@ withApiOptions(
   );
   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 cliFetch(url, init);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    if (res.status === 401) fail5("unauthorized", unauthorizedHint());
+    fail5(
+      "request_failed",
+      data.error ?? `Request to ${url} failed with status ${res.status}`
+    );
+  }
+  return data;
+}
+async function checkConnectivity5(baseUrl) {
+  let res;
+  try {
+    res = await cliFetch(`${baseUrl}/flows`);
+  } catch {
+    fail5(
+      "connect_failed",
+      `Could not connect to dev server at ${baseUrl.replace("http://", "")}. Is it running?`
+    );
+  }
+  if (res.status === 401) fail5("unauthorized", unauthorizedHint());
+  if (!res.ok) {
+    fail5(
+      "api_unavailable",
+      `Could not reach Khotan flows API at ${baseUrl}. Check your base path and dev server.`
+    );
+  }
+}
+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 cliFetch(
+    `${baseUrl}/mappings/${encodeURIComponent(mappingId)}`,
+    {
+      method: "DELETE"
+    }
+  );
+  if (!res.ok) {
+    if (res.status === 401) fail5("unauthorized", unauthorizedHint());
+    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();
@@ -2582,4 +2951,5 @@ program.addCommand(migrateCommand);
 program.addCommand(plugCommand);
 program.addCommand(wireCommand);
 program.addCommand(flowsCommand);
+program.addCommand(mappingsCommand);
 program.parse();