@khotan/cli 0.3.0 → 0.4.0

package/README.md

@@ -43,6 +43,17 @@ It writes an MCP config wired to `khotan mcp serve` (credentials referenced by
 MCP config merges into an existing one, preserving any other servers. Authenticate
 separately with `khotan auth set-key` or environment variables — never commit a key.
 
+`init` also installs catalog-derived agent **skills** for using the CLI into
+`.cursor/skills/`, `.agents/skills/`, and `.claude/skills/` (regardless of
+`--client`): an overview `khotan` skill plus one per command domain
+(`khotan-apps`, `khotan-databases`, …). The skills are generated from the same
+capability catalog that drives the commands, MCP tools, and `khotan help`, so
+they can never drift. They are **managed assets**: every `khotan init` run
+regenerates them in place (no `--force` needed), so re-running `init` is how a
+workspace picks up new CLI commands — like the `databases branches` group. Your
+hand-authored rule/guide and any MCP edits stay non-destructive (preserved
+unless `--force`).
+
 ## Authentication & profiles
 
 The CLI authenticates with an organization-scoped **API key**. Credentials are

package/dist/khotan.js

@@ -19,7 +19,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // ../khotan-core/src/version.ts
-var CATALOG_SCHEMA_VERSION = 1, CATALOG_VERSION = "2026-06-18", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.3.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
+var CATALOG_SCHEMA_VERSION = 1, CATALOG_VERSION = "2026-06-18", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.4.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
 var init_version = __esm(() => {
   SUPPORTED_CATALOG_SCHEMA_VERSIONS = [
     CATALOG_SCHEMA_VERSION
@@ -2040,155 +2040,9 @@ async function downloadFile(deps, options) {
 init_io();
 import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname2, join as join2, relative } from "node:path";
-var MCP_SERVER_KEY = "khotan";
-function mcpServerEntry() {
-  return {
-    command: "khotan",
-    args: ["mcp", "serve"],
-    env: {
-      KHOTAN_API_URL: "<your-khotan-api-url>",
-      KHOTAN_API_KEY: "<your-khotan-api-key>"
-    }
-  };
-}
-var GUIDE_BODY = `This workspace is wired to Khotan through the \`khotan\` CLI and its MCP server.
-Use them to inspect and configure apps, pipelines, databases, files, folders, and
-context documents through the Khotan \`/api/v1\` surface.
-
-## Authentication (do this once — never commit secrets)
-
-Khotan reads an organization-scoped API key from a stored profile or the
-environment:
-
-- Profile (recommended): \`khotan auth set-key --api-url <url> --api-key <key>\`
-  stores the key in an owner-only file outside the repository.
-- Environment: export \`KHOTAN_API_URL\` and \`KHOTAN_API_KEY\` in your shell or
-  agent sandbox.
-
-Never put an API key in a file committed to the repository. The generated MCP
-config contains only placeholders.
-
-## CLI surface
-
-- \`khotan apps list|get|create|delete|redeploy\` and \`khotan apps env …\`
-- \`khotan pipelines …\`, \`khotan databases …\`
-- \`khotan files list|upload|download|…\`, \`khotan folders …\`
-- \`khotan context list|get|create|update|delete\`
-- Add \`--json\` to any command for machine-readable output.
-
-Run \`khotan help\` or \`khotan <command> --help\` for the full, catalog-derived
-surface.
-
-## Safety
-
-- Destructive commands (deletes, env unset) require confirmation; pass \`--yes\`
-  only when you intend it.
-- Secret values (env reveal, database connection strings, credential rotation)
-  are only available through explicit commands and are never printed in lists.
-
-## MCP
-
-\`khotan mcp serve\` exposes the same operations as MCP tools and durable reads as
-MCP resources, reusing your stored profile or environment credentials.
-`;
-var CURSOR_RULES = `---
-description: Use the Khotan CLI and MCP tools to configure and operate this workspace's Khotan resources
-alwaysApply: false
----
-
-# Khotan
-
-${GUIDE_BODY}`;
-var GENERIC_GUIDE = `# Khotan agent guide
-
-${GUIDE_BODY}`;
-function toRelative(cwd, absolutePath) {
-  return relative(cwd, absolutePath) || absolutePath;
-}
-function writeTextAsset(ctx, absolutePath, content) {
-  const path = toRelative(ctx.cwd, absolutePath);
-  const existed = existsSync(absolutePath);
-  if (existed && !ctx.force) {
-    ctx.results.push({ path, action: "skipped" });
-    return;
-  }
-  mkdirSync2(dirname2(absolutePath), { recursive: true });
-  writeFileSync2(absolutePath, content);
-  ctx.results.push({ path, action: existed ? "forced" : "created" });
-}
-function writeMcpConfig(ctx, absolutePath) {
-  const path = toRelative(ctx.cwd, absolutePath);
-  let config = {};
-  const existed = existsSync(absolutePath);
-  if (existed) {
-    try {
-      config = JSON.parse(readFileSync2(absolutePath, "utf8"));
-    } catch {
-      ctx.results.push({ path, action: "skipped" });
-      return;
-    }
-  }
-  if (!config.mcpServers || typeof config.mcpServers !== "object") {
-    config.mcpServers = {};
-  }
-  const servers = config.mcpServers;
-  const hasKhotan = Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_KEY);
-  if (hasKhotan && !ctx.force) {
-    ctx.results.push({ path, action: "skipped" });
-    return;
-  }
-  servers[MCP_SERVER_KEY] = mcpServerEntry();
-  mkdirSync2(dirname2(absolutePath), { recursive: true });
-  writeFileSync2(absolutePath, `${JSON.stringify(config, null, 2)}
-`);
-  ctx.results.push({
-    path,
-    action: existed ? hasKhotan ? "forced" : "updated" : "created"
-  });
-}
-function runInit(options) {
-  const { io, cwd, client, force, json } = options;
-  const ctx = { cwd, force, results: [] };
-  if (client === "cursor") {
-    writeMcpConfig(ctx, join2(cwd, ".cursor", "mcp.json"));
-    writeTextAsset(ctx, join2(cwd, ".cursor", "rules", "khotan.mdc"), CURSOR_RULES);
-  } else {
-    writeMcpConfig(ctx, join2(cwd, "mcp.json"));
-    writeTextAsset(ctx, join2(cwd, "khotan-agents.md"), GENERIC_GUIDE);
-  }
-  if (json) {
-    io.out(`${JSON.stringify({ client, actions: ctx.results }, null, 2)}
-`);
-    return 0;
-  }
-  errLine(io, `Khotan workspace integration (${client}):`);
-  for (const result of ctx.results) {
-    errLine(io, `  ${result.action.padEnd(8)} ${result.path}`);
-  }
-  errLine(io);
-  errLine(io, "Next steps:");
-  errLine(io, "  1. Authenticate: khotan auth set-key --api-url <url> --api-key <key>");
-  errLine(io, "  2. Open this workspace in your agent and ask it to configure Khotan.");
-  return 0;
-}
 
-// src/cli/confirm.ts
+// src/cli/skills.ts
 init_src();
-init_io();
-async function ensureConfirmed(options) {
-  const { io, yes, summary } = options;
-  if (yes) {
-    return;
-  }
-  if (!io.isTty) {
-    throw new KhotanConfirmationRequiredError(`${summary} This is a destructive action; re-run with --yes to confirm in a non-interactive session.`);
-  }
-  errLine(io, summary);
-  const answer = (await io.prompt("Type 'yes' to confirm: ")).trim().toLowerCase();
-  if (answer !== "yes" && answer !== "y") {
-    throw new KhotanConfirmationRequiredError("Aborted; no changes were made.");
-  }
-}
 
 // src/cli/help.ts
 init_src();
@@ -2397,6 +2251,356 @@ function printCommandHelp(io, capability) {
   }
 }
 
+// src/cli/skills.ts
+var AUTH_LOGIN_CAPABILITY_ID = "api-keys.create-from-credentials";
+var OVERVIEW_DOMAINS = new Set([
+  "identity",
+  "api-keys"
+]);
+var DOMAIN_TITLES2 = {
+  apps: "Apps",
+  pipelines: "Pipelines",
+  databases: "Databases",
+  files: "Files",
+  folders: "Folders",
+  context: "Context documents"
+};
+var DOMAIN_LABELS = {
+  apps: "apps",
+  pipelines: "pipelines",
+  databases: "databases and database branches",
+  files: "files",
+  folders: "folders",
+  context: "context documents"
+};
+function domainTitle(domain) {
+  return DOMAIN_TITLES2[domain] ?? domain;
+}
+function domainLabel(domain) {
+  return DOMAIN_LABELS[domain] ?? domain;
+}
+function yamlQuote(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function frontmatter(name, description) {
+  return ["---", `name: ${name}`, `description: ${yamlQuote(description)}`, "---"].join(`
+`);
+}
+function stamp() {
+  return `<!-- generated from khotan catalog v${CATALOG_VERSION} (adapter ${KHOTAN_ADAPTER_VERSION}); do not edit by hand -->`;
+}
+function operationsForDomain(domain) {
+  return listCapabilities().filter(isOperationCapability).filter((capability) => capability.domain === domain).filter((capability) => capability.id !== AUTH_LOGIN_CAPABILITY_ID).sort((a, b) => a.cli.command.join(" ").localeCompare(b.cli.command.join(" ")));
+}
+function resourcesForDomain(domain) {
+  return listCapabilities().filter(isResourceCapability).filter((capability) => capability.domain === domain).sort((a, b) => a.id.localeCompare(b.id));
+}
+function fieldLine(field) {
+  const label = field.location === "path" ? `<${field.name}>` : `--${fieldFlag(field)}`;
+  const notes = [
+    field.required ? "required" : "optional",
+    field.location,
+    field.secret ? "secret" : null
+  ].filter(Boolean).join(", ");
+  return `- \`${label}\` — ${field.description ?? ""} (${notes})`;
+}
+function renderOperation(capability) {
+  const command = capability.cli.command.join(" ");
+  const lines = [
+    `### khotan ${command}`,
+    "",
+    `Usage: \`${commandUsage(capability)}\``,
+    "",
+    capability.description
+  ];
+  if (capability.input.length > 0) {
+    lines.push("", "Arguments & options:");
+    for (const field of capability.input) {
+      lines.push(fieldLine(field));
+    }
+  }
+  if (requiresConfirmation(capability.safety)) {
+    lines.push("", "Safety: destructive — prompts for confirmation in a terminal and refuses in non-interactive sessions unless you pass `--yes`.");
+  } else if (isSecret(capability.safety)) {
+    lines.push("", "Safety: secret — returns credential-bearing values; never shown in list/table output and never exposed as an MCP resource.");
+  }
+  lines.push("", `MCP tool: \`${capability.mcp.tool.name}\``);
+  if (capability.cli.examples && capability.cli.examples.length > 0) {
+    lines.push("", "Examples:");
+    for (const example of capability.cli.examples) {
+      lines.push(`- \`${example}\``);
+    }
+  }
+  return lines.join(`
+`);
+}
+function fileTransferSection() {
+  return [
+    "## Local file transfer (presigned)",
+    "",
+    "These commands move bytes between your machine and object storage using presigned URLs. They are CLI-only helpers (not catalog operations) that wrap the upload/download-url operations:",
+    "",
+    "- `khotan files upload <localPath> [--name <n>] [--folder-id <id>] [--folder-path <p>] [--content-type <t>]` — upload a local file.",
+    "- `khotan files download <fileId> --output <path>` — download a file to a local path."
+  ].join(`
+`);
+}
+function renderDomainSkill(domain) {
+  const operations = operationsForDomain(domain);
+  const resources = resourcesForDomain(domain);
+  const label = domainLabel(domain);
+  const commandTails = operations.map((capability) => capability.cli.command.slice(1).join(" ")).filter((tail) => tail.length > 0);
+  const description = `Use the khotan CLI and MCP server to work with Khotan ${label} — commands ${commandTails.join(", ")}. Use when a user wants to inspect or operate Khotan ${label} via the khotan CLI or its MCP tools.`;
+  const sections = [
+    frontmatter(`khotan-${domain}`, description),
+    "",
+    `# Khotan ${domainTitle(domain)}`,
+    "",
+    `Use the \`khotan\` CLI (and its MCP server) to operate Khotan ${label}. Every command also exists as an MCP tool. Add \`--json\` for machine-readable output; results go to stdout, diagnostics to stderr.`,
+    "",
+    "## Commands",
+    "",
+    operations.map(renderOperation).join(`
+
+`)
+  ];
+  if (domain === "files") {
+    sections.push("", fileTransferSection());
+  }
+  if (resources.length > 0) {
+    sections.push("", "## Resources", "");
+    for (const resource of resources) {
+      sections.push(`- \`${resource.mcp.resource.uriTemplate}\` — ${resource.mcp.resource.description}`);
+    }
+  }
+  sections.push("", stamp(), "");
+  return { name: `khotan-${domain}`, content: sections.join(`
+`) };
+}
+function overviewSkill() {
+  const domains = listDomains().filter((domain) => !OVERVIEW_DOMAINS.has(domain));
+  const description = "Use the khotan CLI and MCP server to operate this workspace's Khotan resources — authenticate, choose profiles, control output, and run apps, pipelines, databases, files, folders, and context commands. Use when setting up khotan auth or deciding which khotan command or domain skill to use.";
+  const indexLines = domains.map((domain) => `- \`khotan-${domain}\` — ${domainLabel(domain)}.`);
+  const content = [
+    frontmatter("khotan", description),
+    "",
+    "# Khotan",
+    "",
+    "This workspace is wired to Khotan through the `khotan` CLI and its MCP server. Both are thin adapters over the Khotan `/api/v1` surface and expose the same operations: the CLI for humans, MCP tools for agents.",
+    "",
+    "## Authentication (do this once — never commit secrets)",
+    "",
+    "Khotan reads an organization-scoped API key from a stored profile or the environment:",
+    "",
+    "- Profile (recommended): `khotan auth set-key --api-url <url> --api-key <key>` stores the key in an owner-only file outside the repository.",
+    "- Exchange credentials: `khotan login --api-url <url> --email <email> --password <pw> --organization-id <org>` mints and stores a key (CLI-only; never exposed as an MCP tool).",
+    "- Switch profiles: `khotan auth use <profile>`; list them with `khotan auth list` (keys are never printed).",
+    "- Environment overrides (CI/agents): `KHOTAN_API_URL`, `KHOTAN_API_KEY`, `KHOTAN_PROFILE` take precedence over stored profiles.",
+    "- Verify with `khotan whoami`.",
+    "",
+    "Never put an API key in a file committed to the repository. Generated MCP config contains only placeholders.",
+    "",
+    "## Output modes",
+    "",
+    "- Human-readable tables/detail by default; add `--json` for API-shaped JSON.",
+    "- Results go to stdout; prompts, progress, and diagnostics go to stderr, so `khotan ... --json | jq` stays clean.",
+    "",
+    "## Safety model",
+    "",
+    "Each capability has a safety class:",
+    "",
+    "- `read` — safe; freely listable.",
+    "- `write` — mutating; summarized before running.",
+    "- `destructive` — deletes/irreversible; prompts for confirmation and refuses non-interactively unless you pass `--yes`.",
+    "- `secret` — returns credential-bearing values (env reveal, connection strings, credential rotation); explicit-only and never printed in lists or exposed as MCP resources.",
+    "",
+    "## MCP server",
+    "",
+    "`khotan mcp serve` starts a stdio MCP server reusing your stored profile or environment credentials. Operations are exposed as tools (e.g. `khotan_apps_create`); durable read data is exposed as URI-addressed resources. stdout carries JSON-RPC only; logs go to stderr.",
+    "",
+    "## Command skills",
+    "",
+    "Per-domain skills cover the full, catalog-derived command surface:",
+    "",
+    ...indexLines,
+    "",
+    "Run `khotan help` or `khotan <command> --help` for the authoritative usage.",
+    "",
+    stamp(),
+    ""
+  ].join(`
+`);
+  return { name: "khotan", content };
+}
+function generateSkills() {
+  const domains = listDomains().filter((domain) => !OVERVIEW_DOMAINS.has(domain));
+  return [overviewSkill(), ...domains.map(renderDomainSkill)];
+}
+
+// src/cli/commands/init.ts
+var MCP_SERVER_KEY = "khotan";
+var SKILL_BASES = [".cursor", ".agents", ".claude"];
+function mcpServerEntry() {
+  return {
+    command: "khotan",
+    args: ["mcp", "serve"],
+    env: {
+      KHOTAN_API_URL: "<your-khotan-api-url>",
+      KHOTAN_API_KEY: "<your-khotan-api-key>"
+    }
+  };
+}
+var GUIDE_BODY = `This workspace is wired to Khotan through the \`khotan\` CLI and its MCP server.
+Use them to inspect and configure apps, pipelines, databases, files, folders, and
+context documents through the Khotan \`/api/v1\` surface.
+
+## Authentication (do this once — never commit secrets)
+
+Khotan reads an organization-scoped API key from a stored profile or the
+environment:
+
+- Profile (recommended): \`khotan auth set-key --api-url <url> --api-key <key>\`
+  stores the key in an owner-only file outside the repository.
+- Environment: export \`KHOTAN_API_URL\` and \`KHOTAN_API_KEY\` in your shell or
+  agent sandbox.
+
+Never put an API key in a file committed to the repository. The generated MCP
+config contains only placeholders.
+
+## CLI surface
+
+- \`khotan apps list|get|create|delete|redeploy\` and \`khotan apps env …\`
+- \`khotan pipelines …\`, \`khotan databases …\`
+- \`khotan files list|upload|download|…\`, \`khotan folders …\`
+- \`khotan context list|get|create|update|delete\`
+- Add \`--json\` to any command for machine-readable output.
+
+Run \`khotan help\` or \`khotan <command> --help\` for the full, catalog-derived
+surface.
+
+## Safety
+
+- Destructive commands (deletes, env unset) require confirmation; pass \`--yes\`
+  only when you intend it.
+- Secret values (env reveal, database connection strings, credential rotation)
+  are only available through explicit commands and are never printed in lists.
+
+## MCP
+
+\`khotan mcp serve\` exposes the same operations as MCP tools and durable reads as
+MCP resources, reusing your stored profile or environment credentials.
+`;
+var CURSOR_RULES = `---
+description: Use the Khotan CLI and MCP tools to configure and operate this workspace's Khotan resources
+alwaysApply: false
+---
+
+# Khotan
+
+${GUIDE_BODY}`;
+var GENERIC_GUIDE = `# Khotan agent guide
+
+${GUIDE_BODY}`;
+function toRelative(cwd, absolutePath) {
+  return relative(cwd, absolutePath) || absolutePath;
+}
+function writeTextAsset(ctx, absolutePath, content) {
+  const path = toRelative(ctx.cwd, absolutePath);
+  const existed = existsSync(absolutePath);
+  if (existed && !ctx.force) {
+    ctx.results.push({ path, action: "skipped" });
+    return;
+  }
+  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  writeFileSync2(absolutePath, content);
+  ctx.results.push({ path, action: existed ? "forced" : "created" });
+}
+function writeManagedAsset(ctx, absolutePath, content) {
+  const path = toRelative(ctx.cwd, absolutePath);
+  const existed = existsSync(absolutePath);
+  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  writeFileSync2(absolutePath, content);
+  ctx.results.push({ path, action: existed ? "updated" : "created" });
+}
+function writeMcpConfig(ctx, absolutePath) {
+  const path = toRelative(ctx.cwd, absolutePath);
+  let config = {};
+  const existed = existsSync(absolutePath);
+  if (existed) {
+    try {
+      config = JSON.parse(readFileSync2(absolutePath, "utf8"));
+    } catch {
+      ctx.results.push({ path, action: "skipped" });
+      return;
+    }
+  }
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+  const servers = config.mcpServers;
+  const hasKhotan = Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_KEY);
+  if (hasKhotan && !ctx.force) {
+    ctx.results.push({ path, action: "skipped" });
+    return;
+  }
+  servers[MCP_SERVER_KEY] = mcpServerEntry();
+  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  writeFileSync2(absolutePath, `${JSON.stringify(config, null, 2)}
+`);
+  ctx.results.push({
+    path,
+    action: existed ? hasKhotan ? "forced" : "updated" : "created"
+  });
+}
+function runInit(options) {
+  const { io, cwd, client, force, json } = options;
+  const ctx = { cwd, force, results: [] };
+  if (client === "cursor") {
+    writeMcpConfig(ctx, join2(cwd, ".cursor", "mcp.json"));
+    writeTextAsset(ctx, join2(cwd, ".cursor", "rules", "khotan.mdc"), CURSOR_RULES);
+  } else {
+    writeMcpConfig(ctx, join2(cwd, "mcp.json"));
+    writeTextAsset(ctx, join2(cwd, "khotan-agents.md"), GENERIC_GUIDE);
+  }
+  for (const skill of generateSkills()) {
+    for (const base of SKILL_BASES) {
+      writeManagedAsset(ctx, join2(cwd, base, "skills", skill.name, "SKILL.md"), skill.content);
+    }
+  }
+  if (json) {
+    io.out(`${JSON.stringify({ client, actions: ctx.results }, null, 2)}
+`);
+    return 0;
+  }
+  errLine(io, `Khotan workspace integration (${client}):`);
+  for (const result of ctx.results) {
+    errLine(io, `  ${result.action.padEnd(8)} ${result.path}`);
+  }
+  errLine(io);
+  errLine(io, "Next steps:");
+  errLine(io, "  1. Authenticate: khotan auth set-key --api-url <url> --api-key <key>");
+  errLine(io, "  2. Open this workspace in your agent and ask it to configure Khotan.");
+  return 0;
+}
+
+// src/cli/confirm.ts
+init_src();
+init_io();
+async function ensureConfirmed(options) {
+  const { io, yes, summary } = options;
+  if (yes) {
+    return;
+  }
+  if (!io.isTty) {
+    throw new KhotanConfirmationRequiredError(`${summary} This is a destructive action; re-run with --yes to confirm in a non-interactive session.`);
+  }
+  errLine(io, summary);
+  const answer = (await io.prompt("Type 'yes' to confirm: ")).trim().toLowerCase();
+  if (answer !== "yes" && answer !== "y") {
+    throw new KhotanConfirmationRequiredError("Aborted; no changes were made.");
+  }
+}
+
 // src/cli/run.ts
 init_io();
 init_session();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khotan/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Khotan CLI and MCP server: human- and agent-facing adapters over the Khotan /api/v1 surface.",
   "license": "SEE LICENSE IN LICENSE.md",