@khotan/cli 0.1.1 → 0.3.0

package/README.md

@@ -179,6 +179,17 @@ Example MCP client configuration:
 operation (method, path, operationId) using a snapshot of the OpenAPI document at
 [`packages/khotan-core/src/catalog/__fixtures__/openapi.snapshot.json`](../khotan-core/src/catalog/__fixtures__/openapi.snapshot.json).
 
+Because that snapshot is committed, the catalog can validate green against a
+stale contract. Guard against it by regenerating the live operation index
+in-process and diffing it against the snapshot (no running server needed):
+
+```bash
+bun run khotan:snapshot:check   # exit 1 on any added/removed/renamed operation
+```
+
+Wire this into CI (it only needs build-minimum env) so a route added, removed,
+or renamed without updating the snapshot fails the build.
+
 Regenerate the snapshot when the API surface changes:
 
 ```bash

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-13", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.1.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
+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 init_version = __esm(() => {
   SUPPORTED_CATALOG_SCHEMA_VERSIONS = [
     CATALOG_SCHEMA_VERSION
@@ -444,6 +444,128 @@ var init_catalog = __esm(() => {
           mimeType: "application/json"
         }
       }
+    },
+    {
+      id: "databases.branches.list",
+      kind: "operation",
+      domain: "databases",
+      safety: "read",
+      auth: true,
+      title: "List database branches",
+      description: "List a database's branches (no credentials).",
+      input: [idField("databaseId", "The database id.")],
+      http: { method: "GET", path: "/api/v1/databases/{databaseId}/branches", operationId: "listDatabaseBranches" },
+      cli: { command: ["databases", "branches", "list"], summary: "List database branches", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_databases_branches_list", title: "List database branches", description: "List a database's branches (no credentials)." } }
+    },
+    {
+      id: "databases.branches.get",
+      kind: "operation",
+      domain: "databases",
+      safety: "read",
+      auth: true,
+      title: "Get a database branch",
+      description: "Get one branch by id (no credentials).",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      http: { method: "GET", path: "/api/v1/databases/{databaseId}/branches/{branchId}", operationId: "getDatabaseBranch" },
+      cli: { command: ["databases", "branches", "get"], summary: "Get a database branch", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_databases_branches_get", title: "Get a database branch", description: "Get one branch by id (no credentials)." } }
+    },
+    {
+      id: "databases.branches.create",
+      kind: "operation",
+      domain: "databases",
+      safety: "write",
+      auth: true,
+      title: "Create a database branch",
+      description: "Branch a ready database, optionally from a parent branch (nested branching).",
+      input: [
+        idField("databaseId", "The database id."),
+        { name: "name", location: "body", type: "string", required: true, description: "The branch name." },
+        { name: "initSource", location: "body", type: "string", required: true, description: "parent-data (copy schema + data) or schema-only (blank)." },
+        { name: "parentBranchId", location: "body", type: "string", description: "Branch to create from; omit to branch from the database root." },
+        { name: "parentTimestamp", location: "body", type: "string", description: "Point-in-time (ISO 8601) for parent-data branches." },
+        { name: "expiresAt", location: "body", type: "string", description: "Explicit expiration (ISO 8601); omit for the ephemeral default." },
+        { name: "noExpiry", location: "body", type: "boolean", description: "Create a non-expiring branch; mutually exclusive with expiresAt." }
+      ],
+      http: { method: "POST", path: "/api/v1/databases/{databaseId}/branches", operationId: "createDatabaseBranch", bodyMode: "json" },
+      cli: { command: ["databases", "branches", "create"], summary: "Create a database branch", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_databases_branches_create", title: "Create a database branch", description: "Branch a ready database, optionally from a parent branch (nested branching)." } }
+    },
+    {
+      id: "databases.branches.delete",
+      kind: "operation",
+      domain: "databases",
+      safety: "destructive",
+      auth: true,
+      title: "Delete a database branch",
+      description: "Permanently delete a branch. Delete its child branches first.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      http: { method: "DELETE", path: "/api/v1/databases/{databaseId}/branches/{branchId}", operationId: "deleteDatabaseBranch" },
+      cli: { command: ["databases", "branches", "delete"], summary: "Delete a database branch" },
+      mcp: { tool: { name: "khotan_databases_branches_delete", title: "Delete a database branch", description: "Permanently delete a branch. Requires confirmation; delete child branches first." } }
+    },
+    {
+      id: "databases.branches.connection",
+      kind: "operation",
+      domain: "databases",
+      safety: "secret",
+      auth: true,
+      title: "Get a branch connection (secret)",
+      description: "Retrieve a branch connection URI. Secret-bearing; explicit-only.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      http: { method: "GET", path: "/api/v1/databases/{databaseId}/branches/{branchId}/connection", operationId: "getDatabaseBranchConnection" },
+      cli: { command: ["databases", "branches", "connection"], summary: "Get a branch connection URI (secret)", defaultOutput: "raw" },
+      mcp: { tool: { name: "khotan_databases_branches_connection", title: "Get a branch connection URI (secret)", description: "Retrieve a branch connection URI. Secret-bearing — returns a credential." } }
+    },
+    {
+      id: "databases.branches.rotate-credentials",
+      kind: "operation",
+      domain: "databases",
+      safety: "secret",
+      auth: true,
+      title: "Rotate branch credentials (secret)",
+      description: "Rotate a branch's credentials and return the new connection. Secret-bearing.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      http: { method: "POST", path: "/api/v1/databases/{databaseId}/branches/{branchId}/rotate-credentials", operationId: "rotateDatabaseBranchCredentials", bodyMode: "none" },
+      cli: { command: ["databases", "branches", "rotate-credentials"], summary: "Rotate branch credentials (secret)", defaultOutput: "raw" },
+      mcp: { tool: { name: "khotan_databases_branches_rotate_credentials", title: "Rotate branch credentials (secret)", description: "Rotate a branch's credentials and return the new connection. Secret-bearing." } }
+    },
+    {
+      id: "databases.branches.resource",
+      kind: "resource",
+      domain: "databases",
+      safety: "read",
+      auth: true,
+      title: "Branch summary",
+      description: "Credential-free branch summary addressed by database and branch id.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      readsVia: "databases.branches.get",
+      http: { method: "GET", path: "/api/v1/databases/{databaseId}/branches/{branchId}", operationId: "getDatabaseBranch" },
+      mcp: {
+        resource: {
+          uriTemplate: "khotan://databases/{databaseId}/branches/{branchId}",
+          name: "database-branch-summary",
+          title: "Branch summary",
+          description: "Credential-free branch summary as JSON.",
+          mimeType: "application/json"
+        }
+      }
     }
   ];
   fileCapabilities = [
@@ -654,6 +776,23 @@ var init_catalog = __esm(() => {
       cli: { command: ["context", "list"], summary: "List context documents", defaultOutput: "table" },
       mcp: { tool: { name: "khotan_context_list", title: "List context documents", description: "List the context document manifest (metadata only)." } }
     },
+    {
+      id: "context.search",
+      kind: "operation",
+      domain: "context",
+      safety: "read",
+      auth: true,
+      title: "Search context documents",
+      description: "Hybrid semantic + full-text search; returns ranked passages with their source slug.",
+      input: [
+        { name: "q", location: "query", type: "string", required: true, description: "Natural-language search query." },
+        { name: "k", location: "query", type: "number", default: 10, description: "Maximum number of snippets to return (1-50)." },
+        { name: "kind", location: "query", type: "string", description: "Filter by kind: instructions, knowledge, or record." }
+      ],
+      http: { method: "GET", path: "/api/v1/context/search", operationId: "searchContextDocuments" },
+      cli: { command: ["context", "search"], summary: "Search context documents", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_context_search", title: "Search context documents", description: "Hybrid semantic + full-text search over context documents; returns ranked passages, each with its source slug." } }
+    },
     {
       id: "context.get",
       kind: "operation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khotan/cli",
-  "version": "0.1.1",
+  "version": "0.3.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",