@kaiba-cloud/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,32 +1,93 @@
 # @kaiba-cloud/cli
 
-Build and deploy your apps to Kaiba from CI or a terminal.
+The Kaiba platform from a terminal, a CI job, or an agent.
 
-## Auth
+```bash
+npm install -g @kaiba-cloud/cli
+kaiba login
+```
+
+## Why a CLI
+
+Two things a hosted tool cannot do, and this can.
+
+**It waits.** `kaiba sessions run --agent <id> --wait` blocks until the agent run
+is done, however long that takes, and puts the outcome in its exit code. There is
+no default timeout, because a client that gives up at an arbitrary minute mark
+turns one job into a guessing game about how long to allow.
+
+**It keeps your credential out of a model's context.** The token lives in your OS
+keychain. There is no flag to pass one, so it never reaches a shell history, a
+process table, or an agent transcript.
+
+## Logging in
+
+```bash
+kaiba login       # prints a code; approve it in a browser
+kaiba whoami      # which credential, from where, which organisation
+kaiba orgs        # every organisation this login reaches
+kaiba org use acme
+```
+
+Login uses the OAuth device flow, so it works over SSH, in a container and in a
+sandbox — anywhere without a browser to open. One login covers every organisation
+you belong to, and the platform's own permissions decide each request.
+
+For CI, set `KAIBA_API_TOKEN` to a `kaiba_deploy_` token instead. That credential
+reaches the `build`, `deploy`, `registry-login` and `status` commands only.
+
+## For agents
+
+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                 # top-level commands, one line each
+kaiba describe env             # one group
+kaiba schema sessions run      # one command's full schema
+```
+
+Both need no credential and make no network call.
 
-The CLI authenticates with a **scoped deploy token** — a `kaiba_deploy_` token an
-org admin mints in the Kaiba console (Environments → Deploy tokens). A deploy
-token grants only `build` and/or `deploy`. It is NOT an org admin key. Store it
-as a CI secret and pass it as `KAIBA_API_TOKEN`.
+Output is JSON whenever stdout is not a terminal. Errors go to stderr with a
+machine-readable `code`, a `hint`, and often an exact `nextCommand` to run.
 
-The hub URL defaults to `https://cloud.kaiba.ai`; override it with `KAIBA_HUB_URL`
-or `--hub-url`.
+Exit codes: **0** success, **1** failed, **2** auth, **3** validation (nothing
+happened), **4** confirmation required (nothing happened), **5** writes landed but
+something needs a human.
 
-## CLI
+A destructive command without `--confirm` exits 4, changes nothing, and prints
+what it would do plus a `confirmCommand` to re-run. That replaces an interactive
+prompt, which an agent can neither see nor answer.
+
+Install the agent skill so an assistant knows all of this:
 
 ```bash
-kaiba build  --repo <url> --branch <ref> --image <name> [--tag <sha>] [--deploy-service <svc>]
-kaiba deploy --service <name> --image <ref>
-kaiba status
+kaiba skill install          # into ./.claude/skills
+kaiba skill install --global # into ~/.claude/skills
+kaiba skill                  # just print it
 ```
 
-- `build` starts a git-mode build on your cluster and streams status until it
-  succeeds or fails. It builds a **pushed** git ref. Add `--deploy-service` to
-  roll the resulting image to that service in one step.
-- `deploy` retargets one compose service to an image and waits for it to run.
-- `status` prints each service and its live state.
+## Commands
+
+Run `kaiba describe` for the current list. In outline:
 
-## GitHub Action
+| Group | What it does |
+|---|---|
+| `login`, `logout`, `whoami`, `orgs`, `org use` | Authentication and organisation selection |
+| `agents` | Your organisation's agents. Kaiba's own system agents are not included. |
+| `sessions` | Start an agent run, wait for it, stream it, stop it |
+| `artifacts` | Upload, fetch, list and delete artifacts |
+| `env` | Dev environments: compose, vars, logs, exec, query, jobs, volumes |
+| `campus` | Deploy skills, agents and blueprints from a repo |
+| `workflows` | Trigger workflows as `*.trigger.json` in git; run one from a node |
+| `build`, `deploy`, `registry-login`, `status` | CI, on a deploy token |
+| `describe`, `schema`, `skill`, `update` | Introspection and maintenance |
+
+## Building and deploying from CI
+
+The Action wraps the same binary. It carries the deploy-token commands only,
+because a personal credential has no business in a shared workflow.
 
 ```yaml
 jobs:
@@ -34,37 +95,49 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - id: kaiba
+        uses: ai-kaiba/kaiba-action@v1
+        with:
+          command: registry-login
+          api-token: ${{ secrets.KAIBA_API_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: ${{ steps.kaiba.outputs.registry-url }}/web:${{ github.sha }}
       - uses: ai-kaiba/kaiba-action@v1
         with:
-          command: build
-          repo: ${{ github.server_url }}/${{ github.repository }}
-          branch: ${{ github.sha }}
-          image: web
-          tag: ${{ github.sha }}
-          service: web          # chains a deploy after the build
+          command: deploy
+          service: web
+          image: ${{ steps.kaiba.outputs.registry-url }}/web:${{ github.sha }}
           api-token: ${{ secrets.KAIBA_API_TOKEN }}
 ```
 
-## Publishing (maintainers)
-
-Published manually — no CI token to rotate. From the repo root:
+Or have Kaiba do the build:
 
 ```bash
-# 1. bump "version" in packages/kaiba-cli/package.json
-# 2. build + publish (publish runs the build via prepublishOnly)
-cd packages/kaiba-cli
-npm login            # once per machine; prompts for 2FA
-npm publish          # access:public is set in package.json; prompts for an OTP
+kaiba build --repo <url> --branch <ref> --image web --deploy-service web
 ```
 
-Notes:
-- `npm publish` uses your interactive npm login, so no long-lived token is stored.
-- npm refuses to republish an existing version — always bump first.
-- The published tarball contains only `dist/`, `action.yml`, and this README.
+`build` builds a **pushed** git ref on your own cluster and streams status until
+it succeeds or fails.
 
-The composite Action runs the compiled CLI, so `dist/` must be built. `npm publish`
-builds it automatically via `prepublishOnly`; to build without publishing:
+## Updating
 
 ```bash
-pnpm --filter @kaiba-cloud/cli build
+kaiba update --check   # changes nothing; safe anywhere
+kaiba update
 ```
+
+The CLI notices a newer version from headers the hub already sends, so it costs no
+extra request. It never checks or updates in CI, when output is machine-readable,
+or under `--quiet` or `--non-interactive`: a pipeline must not get a different
+binary mid-run.
+
+## Publishing (maintainers)
+
+Bump `version` in `package.json`, then push a matching `cli-v<version>` tag. The
+`Release CLI` workflow tests, builds, verifies the tarball and publishes with
+provenance. It refuses a version that is already on the registry, and a tag that
+disagrees with `package.json`.
+
+`npm publish` by hand still works and is the break-glass path.

package/action.yml

@@ -6,7 +6,7 @@ branding:
 
 inputs:
   command:
-    description: 'build | deploy | status'
+    description: 'build | deploy | registry-login | status'
     required: true
   api-token:
     description: 'A scoped Kaiba deploy token (store it as a secret).'
@@ -14,6 +14,10 @@ inputs:
   hub-url:
     description: 'Kaiba hub URL. Defaults to https://cloud.kaiba.ai.'
     required: false
+  cli-version:
+    description: 'npm version range for the CLI. Defaults to the major of the ref you pinned this action to.'
+    required: false
+    default: ''
   # build inputs
   repo:
     description: 'Git repository URL to build (build).'
@@ -40,11 +44,20 @@ inputs:
   service:
     description: 'Compose service name to retarget (deploy, or build with chained deploy).'
     required: false
+  output:
+    description: 'Output format: text | json | ndjson. Use json to parse the result with jq.'
+    required: false
+
+outputs:
+  registry-url:
+    description: 'The registry push prefix (set by the registry-login command). Append /<image>:<tag>.'
+    value: ${{ steps.run.outputs.registry-url }}
 
 runs:
   using: 'composite'
   steps:
     - name: Run kaiba
+      id: run
       shell: bash
       # Every input reaches bash ONLY through the environment — never interpolated
       # into the script body. Interpolating `${{ inputs.* }}` into `run:` would let
@@ -53,7 +66,6 @@ runs:
       env:
         KAIBA_API_TOKEN: ${{ inputs.api-token }}
         KAIBA_HUB_URL: ${{ inputs.hub-url }}
-        ACTION_PATH: ${{ github.action_path }}
         IN_COMMAND: ${{ inputs.command }}
         IN_REPO: ${{ inputs.repo }}
         IN_BRANCH: ${{ inputs.branch }}
@@ -63,6 +75,16 @@ runs:
         IN_CONTEXT: ${{ inputs.context }}
         IN_GIT_TOKEN: ${{ inputs.git-token }}
         IN_SERVICE: ${{ inputs.service }}
+        IN_OUTPUT: ${{ inputs.output }}
+        CLI_VERSION: ${{ inputs.cli-version }}
+        # The ref the CALLER pinned — `v1` for `uses: ai-kaiba/kaiba-cli@v1`.
+        # The CLI major is read from it, so this file never needs editing when a
+        # new major ships: tagging `v2` in this repository is the whole release.
+        ACTION_REF: ${{ github.action_ref }}
+        # A workflow pins its CLI version through the `uses:` ref, so the CLI must
+        # not change it underneath. `CI` is set on every runner and would be enough
+        # on its own; this states the intent rather than relying on it.
+        KAIBA_DISABLE_AUTO_UPDATE: '1'
       run: |
         set -euo pipefail
         add() { [ -n "${2:-}" ] && ARGS+=("--$1" "$2") || true; }
@@ -82,7 +104,39 @@ runs:
             add service "$IN_SERVICE"
             add image "$IN_IMAGE"
             ;;
+          registry-login) ;;
           status) ;;
+          # Deploy-token commands only, on purpose. The user commands
+          # (env, campus, sessions, workflows) authenticate a PERSON, and a
+          # personal credential has no business in a shared workflow.
           *) echo "Unknown command: $IN_COMMAND" >&2; exit 1 ;;
         esac
-        node "$ACTION_PATH/dist/cli.js" "$IN_COMMAND" ${ARGS[@]+"${ARGS[@]}"}
+        add output "$IN_OUTPUT"
+        # Fetched from npm rather than vendored beside this file.
+        #
+        # A vendored `dist/cli.js` has to be re-pushed to this repository on
+        # every CLI release, which is how the copy here came to lag the source.
+        # npm already holds the published build, so the action carries no code
+        # at all and cannot drift from it.
+        #
+        # Which CLI to run, in order: an explicit `cli-version` input, else the
+        # major of the ref the caller pinned, else `latest`.
+        #
+        # Reading it from the ref is what lets this file stay fixed forever:
+        # `@v1` resolves to `1` (the newest 1.x, so fixes arrive on their own),
+        # `@v2` to `2`, and shipping a new major is just a new tag here.
+        #
+        # A ref that is not `vN` — a branch, or a commit SHA someone pinned for
+        # reproducibility — carries no version, so `latest` stands in rather than
+        # guessing a major that may not exist.
+        VERSION="$CLI_VERSION"
+        if [ -z "$VERSION" ]; then
+          case "$ACTION_REF" in
+            v[0-9]*) VERSION="${ACTION_REF#v}"; VERSION="${VERSION%%.*}" ;;
+            *)       VERSION='latest' ;;
+          esac
+        fi
+
+        echo "Using @kaiba-cloud/cli@${VERSION}"
+        # `-y` because a runner is non-interactive.
+        npx -y "@kaiba-cloud/cli@${VERSION}" "$IN_COMMAND" ${ARGS[@]+"${ARGS[@]}"}