@kaiba-cloud/cli 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaiba-cloud/cli",
-  "version": "0.1.0",
-  "description": "Kaiba CLI — build and deploy your apps from CI or a terminal.",
+  "version": "0.2.1",
+  "description": "Kaiba CLI \u2014 build and deploy your apps from CI or a terminal.",
   "type": "module",
   "license": "UNLICENSED",
   "bin": {
@@ -10,19 +10,26 @@
   "files": [
     "dist",
     "action.yml",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "tsc -p tsconfig.json",
-    "check-types": "tsc --noEmit"
+    "build": "node scripts/build.mjs",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "node scripts/build.mjs && node scripts/verify-tarball.mjs"
   },
   "devDependencies": {
+    "@ai-agents/redis-protocol": "workspace:*",
+    "@kaiba/sdk": "workspace:*",
     "@types/node": "^20.19.43",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "esbuild": "^0.25.0",
+    "vitest": "^4.1.10",
+    "tsx": "^4.19.2"
   },
   "engines": {
     "node": ">=18"

package/skills/kaiba-cli/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: kaiba-cli
+description: Use when working with the Kaiba platform from a shell — dispatching a managed agent and waiting for its result, deploying campus skills, agents or blueprints, operating a dev environment, uploading or fetching artifacts, running workflows, or diagnosing a `kaiba` command that failed. Prefer this over the Kaiba MCP tools for anything that has to wait.
+---
+
+# The Kaiba CLI
+
+`kaiba` reaches the Kaiba platform as **you**, not as an organisation key. One
+login covers every organisation you belong to, and the platform's own permissions
+decide each request.
+
+## First moves
+
+Never guess a flag. The CLI describes itself, and the description is generated
+from the same declarations that parse your arguments, so it cannot be out of date:
+
+```bash
+kaiba describe                            # the top-level commands, one line each
+kaiba describe campus agents              # one group's commands
+kaiba schema campus agents sessions run   # one command's full schema
+```
+
+`describe` and `schema` need no credential and make no network call. They are
+safe to run first, before you know whether you are logged in.
+
+## The shape of the tree
+
+Two trees, and everything sits in one of them.
+
+```
+campus agents      the agent definitions   list get create update delete sync
+campus agents sessions   the runs of one   run list get result history logs message stop close delete
+campus skills      what an agent loads     list get sync
+campus blueprints  a skill plus a scaffold list get sync
+campus artifacts   the files agents make   list get upload replace download delete tags
+campus workflows   graphs that dispatch    list get pull push run runs status cancel delete
+
+env                the dev environment     status services logs exec query deploy compose vars …
+```
+
+`login`, `logout`, `whoami`, `orgs` and `org` sit outside both, and so do the
+four CI commands, which take a different credential.
+
+## The output contract
+
+Output is **JSON whenever stdout is not a terminal**, so a pipe, a CI job or an
+agent gets machine-readable output with no flag. Add `--output json` to force it,
+or `--output ndjson` for a stream.
+
+**Exit codes:**
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. Under `--wait`, the agent run also succeeded. |
+| 1 | The CLI or the hub failed. State may be partly changed. |
+| 2 | Auth: no credential, the wrong one, or refused. |
+| 3 | Validation. Refused **before** anything happened. |
+| 4 | Confirmation required. Nothing changed. |
+| 5 | Every write landed, and something a human must fix remains. |
+
+Branch on the exit code first. For the sub-case, read `error.code` — it is a
+closed, documented set.
+
+Errors go to **stderr** and carry a `hint`, and often a `nextCommand`. **When
+`nextCommand` is present, run it.** It is exact and already quoted.
+
+```json
+{"ok":false,"command":"agents.get",
+ "error":{"code":"not-found","message":"Managed agent not found.",
+          "hint":"List the agents in this organisation.",
+          "nextCommand":"kaiba campus agents list --output json","exitCode":1}}
+```
+
+**NDJSON streams:** read lines, ignore a `type` you do not recognise, stop at
+`type:"result"`, then read the exit code. That one sentence is the whole contract.
+
+## Credentials
+
+```bash
+kaiba login       # prints a code, you approve it in a browser, done
+kaiba whoami      # which credential, from where, which organisation
+```
+
+`login` uses a device code, so it works over SSH, in a container and in a sandbox
+— anywhere without a browser. The credential is stored in your OS keychain where
+one is available, and `whoami` always tells you which store was used.
+
+**Never pass a token as a flag.** There is no flag for one. A token on a command
+line reaches your shell history, the process table, and an agent's transcript. For
+CI, set `KAIBA_API_TOKEN`.
+
+There are two credential classes and they are not interchangeable. `kaiba login`
+gives you a **user** credential for everything under `campus` and `env`. `build`,
+`deploy`, `registry-login` and `status` are the **CI** commands and want a `kaiba_deploy_` token in
+`KAIBA_API_TOKEN`. Present the wrong one and the CLI exits 2 and names the command
+that wants the other.
+
+## Choosing an organisation
+
+One rule: `--org` beats `KAIBA_ORG_ID`, which beats the stored default, which is
+used only when you belong to exactly one organisation.
+
+If none of those resolves and you belong to several, the CLI **refuses** rather
+than picking. Every command reports `data.org.resolvedFrom`, so which source won
+is never a guess.
+
+```bash
+kaiba orgs                 # list them
+kaiba org use acme         # set a default once
+```
+
+## Recipe: run an agent and get its answer
+
+This is what the CLI is for. An MCP tool call cannot block for twenty minutes;
+this can.
+
+```bash
+kaiba campus agents sessions run --agent ag-123 --message-file task.md --wait
+```
+
+**There is no timeout.** It waits until the run is done, however long that takes,
+and heartbeats every minute so you can see it is alive. Read the exit code:
+
+- **0** — the agent finished and succeeded. The answer is in `data.result`.
+- **1** with `error.code: "agent-failed"` — it ran and failed. Read the transcript:
+  `kaiba campus agents sessions history <id>`.
+- **1** with `error.code: "timeout"` — only possible if you passed `--timeout`.
+  `data.sessionId` comes back, so **resume rather than starting again**:
+  `kaiba campus agents sessions result <id> --wait`.
+
+To start work and collect it later, drop `--wait`: you get a `sessionId`
+immediately.
+
+## Recipe: watch a run as it happens
+
+```bash
+kaiba campus agents sessions run --agent ag-123 --message "check the build" --follow --wait --output ndjson
+```
+
+`--follow` narrates, `--wait` decides. With both, the exit code comes from the
+result, never from the stream — a terminated session with no result is a failure.
+A dropped connection resumes from the last event with nothing lost or repeated.
+
+## Recipe: deploy campus artifacts
+
+**Always dry-run first.**
+
+```bash
+kaiba campus skills sync --dry-run    # read the plan
+kaiba campus skills sync              # then do it
+```
+
+`--scope system` targets the platform registry and is update-only: it never
+creates. If a sync refuses because an artifact was promoted to system scope, that
+is the cross-scope guard doing its job — do not work around it, use `--scope system`.
+
+## Recipe: workflows as files in git
+
+```bash
+kaiba campus workflows pull                              # graphs to *.trigger.json
+kaiba campus workflows push --dry-run                    # preview
+kaiba campus workflows push                              # deploy
+kaiba campus workflows run wf-1 --node dispatch --wait    # run from ONE node
+```
+
+`push` never arms or disarms anything. Deploying a graph and turning it on are two
+decisions, and the file's `enabled` key is reported against the live state rather
+than applied.
+
+## Recipe: operate a dev environment
+
+Every `devEnv*` MCP tool has a command here:
+
+| MCP tool | Command |
+|---|---|
+| `devEnvConnect`, `devEnvServiceStatus` | `kaiba env status` |
+| `devEnvGetCompose` / `devEnvSetCompose` | `kaiba env compose get` / `set` |
+| `devEnvSetVars` | `kaiba env vars set` |
+| `devEnvDeploy` | `kaiba env deploy` |
+| `devEnvServiceLogs` | `kaiba env logs --service X` |
+| `devEnvExec` | `kaiba env exec --service X -- <cmd>` |
+| `devEnvQuery` | `kaiba env query --service X --engine postgres --sql "..."` |
+| `devEnvRestartService` | `kaiba env restart --service X` |
+| `devEnvResetVolume` / `devEnvResizeVolume` | `kaiba env volume reset` / `resize` |
+| `devEnvRunJob` / `devEnvListJobs` | `kaiba env jobs run` / `list` |
+
+`env exec` is one shot and returns captured output. **Its exit code is the remote
+command's**, labelled `exitCodeSource: "remote"` — the one place the exit code is
+not from the table above.
+
+## Recipe: artifacts
+
+```bash
+kaiba campus artifacts upload --file report.md --title "Q3 report" --tags finance
+kaiba campus artifacts download art-1 --output-file report.md
+```
+
+Upload is a two-step presigned PUT and the CLI handles both steps. If it reports
+`error.code: "transport"`, the row exists with no bytes — run the
+`kaiba campus artifacts replace` command it gives you.
+
+## Destructive commands
+
+There is no interactive prompt, because you cannot answer one. Instead a
+destructive command **exits 4 and changes nothing**, printing what it would do:
+
+```json
+{"ok":false,"command":"env.volume.reset",
+ "error":{"code":"confirmation-required","exitCode":4},
+ "confirmation":{
+   "changes":[{"action":"delete","resource":"volume","target":"db",
+               "detail":"Every byte in db's volume is lost. This cannot be undone."}],
+   "confirmCommand":"kaiba env volume reset --service db --confirm --output json"}}
+```
+
+**Show `confirmation.changes` to your human. If they approve, run
+`confirmation.confirmCommand` verbatim.** Do not reconstruct it and do not add
+`--confirm` yourself to a command they have not seen.
+
+## What introspection cannot tell you
+
+- **Prefer this CLI over the Kaiba MCP tools for anything that waits.** An MCP
+  call cannot block and has no cursor to resume from.
+- **A managed-agent pod has no `kaiba` binary.** Inside a pod, use the MCP tools.
+  This CLI is for a developer machine, a CI runner, or an agent with a shell.
+- **Always `--dry-run` a campus sync first.**
+- **Never put a token on a command line.**
+
+## When something fails
+
+| Symptom | What it means |
+|---|---|
+| exit 2, `no-credential` | Run `kaiba login`. |
+| exit 2, `wrong-credential-class` | You have the CI token and want the user one, or the reverse. The error names the right command. |
+| exit 3, no organisation | Pass `--org`, or run `kaiba org use <id>` once. |
+| exit 3, `invalid-input` with a `codePoint` | A value contains a control character. It is refused, not cleaned, because cleaning would change what you named. |
+| exit 3, `cli-too-old` | The platform needs a newer CLI. The hint carries the upgrade command. |
+| exit 4 | Nothing happened. See the confirmation section above. |
+| exit 5 | Every write landed. Something still needs a human — read `data`. |

package/dist/client.js

@@ -1,52 +0,0 @@
-/**
- * HTTP client for the Kaiba CI surface (`/ci/*` on the hub). Authenticates with
- * a scoped deploy token via `x-api-key`. Uses only the Node 18+ global `fetch`,
- * so the CLI ships with no runtime dependencies.
- */
-export class KaibaApiError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
-        this.name = 'KaibaApiError';
-    }
-}
-export class KaibaClient {
-    base;
-    token;
-    constructor(opts) {
-        this.base = opts.hubUrl.replace(/\/$/, '');
-        this.token = opts.token;
-    }
-    async request(method, path, body) {
-        const res = await fetch(`${this.base}${path}`, {
-            method,
-            headers: {
-                'x-api-key': this.token,
-                ...(body ? { 'content-type': 'application/json' } : {}),
-            },
-            ...(body ? { body: JSON.stringify(body) } : {}),
-        });
-        const text = await res.text();
-        const data = text ? JSON.parse(text) : {};
-        if (!res.ok) {
-            throw new KaibaApiError(res.status, data.error ?? `${res.status} ${res.statusText}`);
-        }
-        return data;
-    }
-    startBuild(req) {
-        return this.request('POST', '/ci/builds', req);
-    }
-    getBuild(buildId, clusterId) {
-        return this.request('GET', `/ci/builds/${encodeURIComponent(buildId)}?clusterId=${encodeURIComponent(clusterId)}`);
-    }
-    getBuildLogs(buildId, clusterId) {
-        return this.request('GET', `/ci/builds/${encodeURIComponent(buildId)}/logs?clusterId=${encodeURIComponent(clusterId)}`);
-    }
-    deploy(service, image) {
-        return this.request('POST', '/ci/deploy', { service, image });
-    }
-    status() {
-        return this.request('GET', '/ci/status');
-    }
-}