@khotan/cli 0.8.0 → 0.10.0

package/README.md

@@ -142,9 +142,11 @@ documented surface and the executable surface cannot drift. Run `khotan help` or
 | App env   | `apps env list <id>`, `apps env set <id> <KEY> --value V`, `apps env reveal <id> <KEY>`, `apps env unset <id> <KEY>`, `apps env bulk-set <id> --var A=1 --var B=2` |
 | Pipelines | same shape as apps under `pipelines …` |
 | Databases | `databases list`, `databases create --name db`, `databases connection <id>`, `databases rotate-credentials <id>`, `databases delete <id>` |
-| Files     | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files update <id> --name new.txt`, `files delete <id>` |
+| Files     | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files download-url <id>`, `files preview-url <id>`, `files update <id> --name new.txt`, `files delete <id>` |
 | Folders   | `folders list`, `folders create --name docs`, `folders rename <id> --name new`, `folders delete <id>` |
-| Context   | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...'`, `context update <slug> --expected-revision 3 --content '...'`, `context delete <slug>` |
+| Context   | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...' --folder-id <id>`, `context update <slug> --expected-revision 3 --content '...' --folder-id <id>`, `context delete <slug>` |
+| Context folders | `context folders list`, `context folders create --name docs --parent-id <id>`, `context folders update <id> --name new --parent-id <id>`, `context folders delete <id> --recursive` |
+| Context revisions | `context revisions list <slug>`, `context revisions get <slug> <revision>`, `context revisions restore <slug> <revision>` |
 
 ### Output modes
 
@@ -173,6 +175,17 @@ khotan files upload ./report.pdf --folder-path /reports/2026
 khotan files download file_123 --output ./report.pdf
 ```
 
+To hand a file to a browser instead of saving it locally, mint a short-lived
+presigned URL and load it directly (no API key on the URL; expires in ~5 minutes):
+
+```bash
+khotan files preview-url file_123     # inline disposition, images and PDFs only
+khotan files download-url file_123    # attachment disposition, any file type
+```
+
+See [Serving file attachments](../../docs/files-api-attachments.md) for the full
+preview/download flow and the receiver wiring guidance.
+
 ## MCP server
 
 `khotan mcp serve` starts a local stdio MCP server that reuses the same profile,

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-28", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.7.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
+var CATALOG_SCHEMA_VERSION = 1, CATALOG_VERSION = "2026-07-01", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.10.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
 var init_version = __esm(() => {
   SUPPORTED_CATALOG_SCHEMA_VERSIONS = [
     CATALOG_SCHEMA_VERSION
@@ -906,6 +906,19 @@ var init_catalog = __esm(() => {
       cli: { command: ["files", "download-url"], summary: "Get a file download URL", defaultOutput: "detail" },
       mcp: { tool: { name: "khotan_files_download", title: "Get a file download URL", description: "Return a short-lived presigned GET URL for a ready file." } }
     },
+    {
+      id: "files.preview",
+      kind: "operation",
+      domain: "files",
+      safety: "read",
+      auth: true,
+      title: "Get a file preview URL",
+      description: "Return a short-lived presigned inline GET URL for a ready, preview-eligible file (images and PDFs).",
+      input: [idField("fileId", "The file id.")],
+      http: { method: "GET", path: "/api/v1/files/{fileId}/preview", operationId: "getFilePreviewUrl" },
+      cli: { command: ["files", "preview-url"], summary: "Get a file preview URL", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_files_preview", title: "Get a file preview URL", description: "Return a short-lived presigned inline GET URL for a ready, preview-eligible file (images and PDFs)." } }
+    },
     {
       id: "files.resource",
       kind: "resource",
@@ -1063,7 +1076,8 @@ var init_catalog = __esm(() => {
         { name: "content", location: "body", type: "string", required: true, description: "Canonical markdown content." },
         { name: "slug", location: "body", type: "string", description: "Optional slug; derived from the title when omitted." },
         { name: "description", location: "body", type: "string", description: "One-line purpose statement." },
-        { name: "tags", location: "body", type: "string[]", description: "Flat tag list." }
+        { name: "tags", location: "body", type: "string[]", description: "Flat tag list." },
+        { name: "folderId", location: "body", type: "string", description: "Folder placement; omit for the organization root." }
       ],
       http: { method: "POST", path: "/api/v1/context", operationId: "createContextDocument", bodyMode: "json" },
       cli: { command: ["context", "create"], summary: "Create a context document", defaultOutput: "detail" },
@@ -1085,6 +1099,7 @@ var init_catalog = __esm(() => {
         { name: "content", location: "body", type: "string", description: "New markdown content." },
         { name: "description", location: "body", type: "string", description: "New description (null clears it)." },
         { name: "tags", location: "body", type: "string[]", description: "New tag list." },
+        { name: "folderId", location: "body", type: "string", description: "Move the document to this folder; omit to leave unchanged. (Sending null to move to the root is not reachable via CLI flags.)" },
         { name: "changeSummary", location: "body", type: "string", description: "Optional revision-history note." }
       ],
       http: { method: "PATCH", path: "/api/v1/context/{slug}", operationId: "updateContextDocument", bodyMode: "json" },
@@ -1104,6 +1119,113 @@ var init_catalog = __esm(() => {
       cli: { command: ["context", "delete"], summary: "Delete a context document" },
       mcp: { tool: { name: "khotan_context_delete", title: "Delete a context document", description: "Soft-delete a context document. Requires confirmation." } }
     },
+    {
+      id: "context.folders.list",
+      kind: "operation",
+      domain: "context",
+      safety: "read",
+      auth: true,
+      title: "List context folders",
+      description: "List the organization's context folders as a flat list, each carrying parentId, path, depth, and its direct active-document count.",
+      input: [],
+      http: { method: "GET", path: "/api/v1/context/folders", operationId: "listContextFolders" },
+      cli: { command: ["context", "folders", "list"], summary: "List context folders", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_context_folders_list", title: "List context folders", description: "List context folders as a flat list with parentId, path, depth, and document count." } }
+    },
+    {
+      id: "context.folders.create",
+      kind: "operation",
+      domain: "context",
+      safety: "write",
+      auth: true,
+      title: "Create a context folder",
+      description: "Create a folder under an optional parent (omit parentId for the organization root).",
+      input: [
+        { name: "name", location: "body", type: "string", required: true, description: "The folder name; must be unique among active siblings." },
+        { name: "parentId", location: "body", type: "string", description: "Parent folder id; omit for the organization root." }
+      ],
+      http: { method: "POST", path: "/api/v1/context/folders", operationId: "createContextFolder", bodyMode: "json" },
+      cli: { command: ["context", "folders", "create"], summary: "Create a context folder", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_context_folders_create", title: "Create a context folder", description: "Create a context folder under an optional parent." } }
+    },
+    {
+      id: "context.folders.update",
+      kind: "operation",
+      domain: "context",
+      safety: "write",
+      auth: true,
+      title: "Rename or move a context folder",
+      description: "Rename a folder (name) and/or move it under a new parent (parentId).",
+      input: [
+        idField("id", "The folder id."),
+        { name: "name", location: "body", type: "string", description: "New folder name." },
+        { name: "parentId", location: "body", type: "string", description: "New parent folder id. (Sending null to move to the root is not reachable via CLI flags.)" }
+      ],
+      http: { method: "PATCH", path: "/api/v1/context/folders/{id}", operationId: "updateContextFolder", bodyMode: "json" },
+      cli: { command: ["context", "folders", "update"], summary: "Rename or move a context folder", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_context_folders_update", title: "Rename or move a context folder", description: "Rename a context folder and/or move it under a new parent (parentId null moves it to the root)." } }
+    },
+    {
+      id: "context.folders.delete",
+      kind: "operation",
+      domain: "context",
+      safety: "destructive",
+      auth: true,
+      title: "Delete a context folder",
+      description: "Soft-delete a folder. A non-empty folder requires --recursive, which also soft-deletes its subfolders and documents.",
+      input: [
+        idField("id", "The folder id."),
+        { name: "recursive", location: "query", type: "boolean", default: false, description: "Delete a non-empty folder and all of its contents." }
+      ],
+      http: { method: "DELETE", path: "/api/v1/context/folders/{id}", operationId: "deleteContextFolder" },
+      cli: { command: ["context", "folders", "delete"], summary: "Delete a context folder" },
+      mcp: { tool: { name: "khotan_context_folders_delete", title: "Delete a context folder", description: "Soft-delete a context folder. Pass recursive=true to delete a non-empty folder and its contents. Requires confirmation." } }
+    },
+    {
+      id: "context.revisions.list",
+      kind: "operation",
+      domain: "context",
+      safety: "read",
+      auth: true,
+      title: "List a context document's revisions",
+      description: "List a document's revision history, newest first (metadata only, never snapshot content).",
+      input: [idField("slug", "The document slug.")],
+      http: { method: "GET", path: "/api/v1/context/{slug}/revisions", operationId: "listContextDocumentRevisions" },
+      cli: { command: ["context", "revisions", "list"], summary: "List a document's revisions", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_context_revisions_list", title: "List document revisions", description: "List a context document's revision history, newest first (metadata only)." } }
+    },
+    {
+      id: "context.revisions.get",
+      kind: "operation",
+      domain: "context",
+      safety: "read",
+      auth: true,
+      title: "Get a context document revision",
+      description: "Get a single captured revision including its markdown snapshot.",
+      input: [
+        idField("slug", "The document slug."),
+        { name: "revision", location: "path", type: "number", required: true, description: "The revision number." }
+      ],
+      http: { method: "GET", path: "/api/v1/context/{slug}/revisions/{revision}", operationId: "getContextDocumentRevision" },
+      cli: { command: ["context", "revisions", "get"], summary: "Get a document revision", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_context_revisions_get", title: "Get a document revision", description: "Get a single context document revision including its markdown snapshot." } }
+    },
+    {
+      id: "context.revisions.restore",
+      kind: "operation",
+      domain: "context",
+      safety: "write",
+      auth: true,
+      title: "Restore a context document revision",
+      description: "Restore a document to an earlier revision by writing a new forward revision matching that snapshot (history is never rewritten).",
+      input: [
+        idField("slug", "The document slug."),
+        { name: "revision", location: "path", type: "number", required: true, description: "The revision number to restore." }
+      ],
+      http: { method: "POST", path: "/api/v1/context/{slug}/revisions/{revision}/restore", operationId: "restoreContextDocumentRevision" },
+      cli: { command: ["context", "revisions", "restore"], summary: "Restore a document revision", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_context_revisions_restore", title: "Restore a document revision", description: "Restore a context document to an earlier revision by writing a new forward revision." } }
+    },
     {
       id: "context.resource",
       kind: "resource",
@@ -2315,6 +2437,17 @@ function singleArrayProperty(record) {
   }
   return;
 }
+function singleObjectProperty(record) {
+  const keys = Object.keys(record);
+  if (keys.length !== 1) {
+    return;
+  }
+  const value = record[keys[0]];
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return;
+}
 function renderResult(io, result, options) {
   if (options.json) {
     outLine(io, JSON.stringify(result, null, 2));
@@ -2341,7 +2474,7 @@ function renderResult(io, result, options) {
       renderTable(io, list);
       return;
     }
-    renderDetail(io, record);
+    renderDetail(io, singleObjectProperty(record) ?? record);
     return;
   }
   outLine(io, scalar(result));

package/package.json

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