@khotan/cli 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# Khotan CLI & MCP server
+
+`@khotan/cli` is the first-party command-line interface and Model Context
+Protocol (MCP) server for the Khotan API. Both surfaces are thin adapters over
+the public `/api/v1` HTTP API, driven by the shared capability catalog in
+[`@khotan/core`](../khotan-core). They add nothing the API cannot do — they make
+the same operations ergonomic for humans (CLI) and agents (MCP).
+
+## Install & run
+
+The published CLI is a self-contained Node.js binary (no Bun required). Install
+or invoke it with standard npm tooling:
+
+```bash
+npx @khotan/cli --help     # zero-install
+npm i -g @khotan/cli       # global `khotan` binary
+# or: bun add -g @khotan/cli / pnpm add -g @khotan/cli
+khotan --help
+```
+
+From this repository (contributors), run it from source on Bun:
+
+```bash
+bun run khotan -- --help          # via the root script
+bun packages/khotan-cli/src/bin/khotan.ts --help   # directly
+```
+
+## Scaffold a workspace
+
+`khotan init` writes Khotan agent integration into the current directory so your
+own agents (Cursor, Devin, …) can drive setup. It is non-destructive and
+re-runnable, and never writes secrets.
+
+```bash
+khotan init                 # Cursor: .cursor/mcp.json + .cursor/rules/khotan.mdc
+khotan init --client generic   # root mcp.json + khotan-agents.md
+khotan init --force         # regenerate managed assets, overwriting edits
+khotan init --json          # machine-readable summary on stdout
+```
+
+It writes an MCP config wired to `khotan mcp serve` (credentials referenced by
+`KHOTAN_API_URL` / `KHOTAN_API_KEY`, placeholders only) plus agent guidance. The
+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.
+
+## Authentication & profiles
+
+The CLI authenticates with an organization-scoped **API key**. Credentials are
+stored in an owner-only file at `${XDG_CONFIG_HOME:-~/.config}/khotan/profiles.json`
+(`0600`, in a `0700` directory). You can keep several named profiles.
+
+### Store an existing API key
+
+Create a key in the dashboard, then:
+
+```bash
+khotan auth set-key --api-url https://app.example.com --api-key khk_live_...
+khotan whoami        # verifies the key via GET /api/v1/me
+```
+
+### Exchange credentials for a key
+
+```bash
+khotan login \
+  --api-url https://app.example.com \
+  --email you@example.com \
+  --password '••••••' \
+  --organization-id org_123
+```
+
+`login` calls `POST /api/v1/api-keys`, stores the minted key once, and verifies
+it. The key itself is never printed to stdout.
+
+### Profiles
+
+```bash
+khotan auth set-key --profile staging --api-url https://staging.example.com --api-key ...
+khotan auth use staging      # switch the active profile
+khotan auth list             # list profiles (never prints keys)
+khotan apps list --profile staging   # one-off override
+```
+
+### Environment variables (CI & agents)
+
+Environment variables take precedence over stored profile values, so no on-disk
+state is needed in CI or sandboxes:
+
+| Variable          | Purpose                                   |
+| ----------------- | ----------------------------------------- |
+| `KHOTAN_API_URL`  | API origin (e.g. `https://app.example.com`) |
+| `KHOTAN_API_KEY`  | Organization-scoped API key               |
+| `KHOTAN_PROFILE`  | Select a stored profile by name           |
+
+```bash
+export KHOTAN_API_URL=https://app.example.com
+export KHOTAN_API_KEY=khk_live_...
+khotan apps list --json | jq '.apps[].id'
+```
+
+## Command surface
+
+Commands are grouped by domain and derived from the capability catalog, so the
+documented surface and the executable surface cannot drift. Run `khotan help` or
+`khotan <command> --help` for details.
+
+| Domain    | Examples |
+| --------- | -------- |
+| Apps      | `apps list`, `apps get <id>`, `apps create --name web --env KEY=VALUE`, `apps delete <id>`, `apps redeploy <id>` |
+| 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>` |
+| 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>` |
+
+### Output modes
+
+- Human-readable tables/detail by default.
+- `--json` emits the API-shaped JSON to **stdout**.
+- Results go to **stdout**; diagnostics, prompts, and progress go to **stderr**,
+  so `khotan ... --json | jq` stays clean.
+
+### Safety
+
+Each capability has a safety class (`read`, `write`, `destructive`, `secret`):
+
+- **Destructive** commands (`delete`, `env unset`) prompt for confirmation in a
+  terminal and **refuse** in non-interactive sessions unless you pass `--yes`.
+- **Secret** values (`env reveal`, `databases connection`,
+  `databases rotate-credentials`) are only available via explicit commands and
+  are never included in list/table output.
+
+### File transfer
+
+Uploads and downloads move bytes directly between your machine and object
+storage using presigned URLs:
+
+```bash
+khotan files upload ./report.pdf --folder-path /reports/2026
+khotan files download file_123 --output ./report.pdf
+```
+
+## MCP server
+
+`khotan mcp serve` starts a local stdio MCP server that reuses the same profile,
+environment overrides, API client, and catalog as the CLI. It advertises
+**tools** (operations) and **resources** (URI-addressed read data) during
+initialization.
+
+- Operations become tools (e.g. `khotan_apps_create`). Destructive tools require
+  `{ "confirm": true }`; secret tools are labelled `[secret]`. The password-bearing
+  credential exchange is **not** exposed as a tool.
+- Durable read data is exposed as resource templates: `khotan://apps/{appId}`,
+  `khotan://pipelines/{pipelineId}`, `khotan://databases/{databaseId}`,
+  `khotan://files/{fileId}`, `khotan://context/{slug}`.
+- Secret-bearing values (env var values, connection URIs) are never resources.
+- stdout carries JSON-RPC only; all logs go to stderr.
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "khotan": {
+      "command": "khotan",
+      "args": ["mcp", "serve"],
+      "env": {
+        "KHOTAN_API_URL": "https://app.example.com",
+        "KHOTAN_API_KEY": "khk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Catalog ↔ OpenAPI consistency
+
+`@khotan/core` validates that every catalog operation maps to a real `/api/v1`
+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).
+
+Regenerate the snapshot when the API surface changes:
+
+```bash
+curl -s "$KHOTAN_API_URL/api/v1/openapi.json" \
+  | jq '{openapi, info, paths: (.paths | map_values(map_values({operationId})))}' \
+  > packages/khotan-core/src/catalog/__fixtures__/openapi.snapshot.json
+```
+
+## Development
+
+```bash
+bun run khotan:typecheck   # typecheck both packages
+bun run khotan:test        # run all Khotan tests
+bun run khotan -- <args>   # run the CLI from source
+bun run khotan:build       # bundle the publishable dist/khotan.js (Node target)
+```
+
+The build bundles `@khotan/core` into a single Node-executable ESM file at
+`packages/khotan-cli/dist/khotan.js`. `@khotan/core` stays a private workspace
+package; only the bundled `@khotan/cli` is published, so the published manifest
+has no `workspace:*` dependencies.
+
+## Release
+
+Versioning and publishing use [changesets](https://github.com/changesets/changesets):
+
+```bash
+bun run changeset          # author a changeset describing the change
+bun run release:version    # apply changesets: bump version + update changelog
+bun run release:publish    # build, then publish @khotan/cli to npm (public)
+```
+
+`prepublishOnly` rebuilds the bundle, so the published `bin` always matches
+source. Publishing requires the `@khotan` npm org and a publish token.