@catalyst-cloud/cli 0.14.10 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.15.0
+
+- Installation and onboarding share a plan and progress display. Browser approvals stay in the same flow, and resumed runs recheck saved choices against current access.
+- Linear permission updates open an explicit review page. Opening that page does not change the connection.
+- Onboarding can choose an existing Linear team or create one when the connected person has permission. Missing permission names the action needed to continue.
+- Onboarding can configure this machine as a Catalyst runner. It checks Docker, image compatibility, enrollment, capacity and team admission, and reports prerequisites that still need attention.
+- Headless and JSON runs avoid interactive prompts and report missing inputs. Readiness reports distinguish completed setup from evidence of a first ticket running.
+- The CLI uses SDK 0.14.1, which accepts the current cloud contract while refusing unknown write routes.
+
 ## 0.14.10
 
 - `catalyst onboard` refreshes its sign-in when it starts and between steps. A run started a while after signing in no longer asks for the browser sign-in again, and a long run of approvals no longer stops with "Renew your login".

package/README.md

@@ -126,6 +126,47 @@ catalyst ready --onboarding --json
 
 The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
 
+### Headless setup (CI, image builds, agent VMs)
+
+`catalyst onboard --headless` (or `CATALYST_ONBOARD_HEADLESS=1`) is for a machine with no person at it. It assumes every browser approval already happened: the person's key exists, and Linear and GitHub are connected for the workspace and the person. It never prompts, never opens a browser and never starts the device sign-in. Every input comes from a flag, an environment variable or a file:
+
+| Input | Flag | Environment |
+|--|--|--|
+| Personal key (Settings → API keys) | `--key-file <path>` | `CATALYST_CLOUD_TOKEN`, or `CATALYST_CLOUD_TOKEN_FILE` |
+| Linear team | `--team <ID or key>` | `CATALYST_ONBOARD_TEAM` |
+| Repositories | `--repo <owner/name>`, repeatable | `CATALYST_ONBOARD_REPOS` (comma or space separated) |
+| Coding account | `--coding-account <slot>` (`catalyst accounts` lists them) | `CATALYST_ONBOARD_CODING_ACCOUNT` |
+| Runner opt-in | `--runner yes\|no` | `CATALYST_ONBOARD_RUNNER` |
+| Cloud | `--base-url <url>` | `CATALYST_CLOUD_BASE_URL` |
+
+A flag wins over its variable. A machine that already has a saved login needs no key. The key is never accepted on the command line: `--key` under `--headless` exits 12, because other processes can read argv. A key file must be a regular file, owned by this user or root, that other users cannot write. A key for another person than the machine's saved login or setup record exits 12 and leaves the saved login as it was. With `--dry-run`, nothing is saved and no network call is made. The steps run without the key in their environment. The key is saved in the login config (mode 0600), the same as `catalyst login --key`, and it never appears in the output, the log or the receipt. In an image build, run setup when the container starts, or remove `~/.config/catalyst-cloud/customer.json` in the same step, so the key does not stay in a layer.
+
+Before any network call, the run checks that every input is present. Each missing input is named with its flag and variable, and the run exits 11 at once. A browser approval that does not exist yet is never started. Its step waits with a named reason, and the item's `url` is the page that fixes it:
+
+| Step | Reason | Page |
+|--|--|--|
+| Linear for the workspace | `linear_workspace_grant_missing` | Settings → Connections |
+| GitHub App for the workspace | `github_app_grant_missing` | Settings → Connections |
+| The person's Linear | `linear_personal_grant_missing` | Settings → Connected accounts |
+| The person's GitHub | `github_personal_grant_missing` | Settings → Connected accounts |
+
+With `--runner yes`, setup starts the self-hosted runner and verifies enrollment, advertised capacity and team admission. This needs Docker with Compose, pinned host images and an organization key file (`CATALYST_RUNNER_ORG_KEY_FILE`). When images, a key or admission are missing, exit 11 names that gate. A failed setup step exits 10. Use `--runner no` to skip the machine's runner. Unlike the interactive optional runner step, an explicitly requested headless runner must finish before exit 0.
+
+With `--json`, stdout carries exactly one document: the onboarding receipt plus a `headless` block (`schema: "catalyst-onboard-headless/1"`). The block holds the resolved `inputs` (the key appears only as its source: `env`, `file` or `saved`), and lists of items under `missing`, `refused`, `failed`, `deferred` and `warnings`. Each item has `id`, `kind` (`input`, `grant` or `step`), `reason` and a one-line `text`, plus `flag`, `env` and `url` where they apply. Everything else goes to stderr.
+
+| Exit | Meaning |
+|--|--|
+| 0 | Ready for work. Optional steps can still be listed under `deferred`. A `--dry-run` exits 0 for a plan; its verdict stays `not-ready`. |
+| 10 | A step failed. See `failed`. |
+| 11 | Something is missing: an input, a browser approval or a step that waits. See `missing`. |
+| 12 | Refused: a key on the command line, a key file other users can write or own, a host key instead of a personal key, a key for another person than the saved login, a malformed runner choice or an unknown option. See `refused`. |
+
+```sh
+# CI or an agent VM: the key comes from the secret store as an environment variable.
+CATALYST_CLOUD_TOKEN="$CATALYST_KEY" catalyst onboard --headless --json \
+  --team ENG --repo acme/api --coding-account claude-one --runner no
+```
+
 Local sync is optional. Include it in the plan with `--local-sync` when you need local SQL or sustained local reads. A resume keeps that choice. Readiness distinguishes failed checks from missing evidence and reports observed project work separately from unfinished setup.
 
 ## Requirements

package/dist/args.js

@@ -41,6 +41,7 @@ export const FLAG_TABLES = {
     },
     install: {},
     onboard: {
+        verbose: { value: false, help: "show granted permissions for connected steps in interactive setup" },
         team: {
             value: true,
             help: "explicitly select an existing Linear team by ID or unique key",
@@ -54,6 +55,15 @@ export const FLAG_TABLES = {
             value: false,
             help: "include the optional local sync setup in this plan",
         },
+        runner: {
+            value: false,
+            optionalValue: true,
+            help: "run Catalyst's work on this machine; with --headless, supply yes|no (or CATALYST_ONBOARD_RUNNER)",
+        },
+        "no-runner": {
+            value: false,
+            help: "do not run Catalyst's work on this machine, and do not ask",
+        },
         "resume-from": {
             value: true,
             help: "resume at a verified onboarding step",
@@ -64,6 +74,18 @@ export const FLAG_TABLES = {
             value: false,
             help: "print the plan without taking the lock or changing files",
         },
+        headless: {
+            value: false,
+            help: "never prompt or open a browser; every input by flag, env or file; exit 11 names what is missing (or CATALYST_ONBOARD_HEADLESS=1)",
+        },
+        "key-file": {
+            value: true,
+            help: "headless: read the personal key from this file (or CATALYST_CLOUD_TOKEN_FILE, or the key in CATALYST_CLOUD_TOKEN); never the key itself on the command line",
+        },
+        "coding-account": {
+            value: true,
+            help: "verify this coding-account slot (catalyst accounts lists them; or CATALYST_ONBOARD_CODING_ACCOUNT)",
+        },
     },
     status: {},
     notice: {},
@@ -435,8 +457,9 @@ export const FLAG_TABLES = {
     },
 };
 export const VERB_USAGE = {
+    setup: "setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--resume-from <step>] [--only <step>] [--local-sync] [--yes] [--dry-run] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",
@@ -512,7 +535,16 @@ export function parseArgs(argv) {
                     ? `unknown option for ${out.command}: --${name}`
                     : `unknown option: --${name}`);
             }
-            if (spec.value) {
+            if (spec.optionalValue) {
+                const next = argv[i + 1];
+                if (inlineValue !== undefined)
+                    out.flags[name] = inlineValue;
+                else if (next !== undefined && !next.startsWith("-"))
+                    out.flags[name] = argv[++i];
+                else
+                    out.flags[name] = true;
+            }
+            else if (spec.value) {
                 const v = inlineValue ?? requireValue(argv, ++i, `--${name}`);
                 if (spec.repeat) {
                     const prev = out.flags[name];

package/dist/capabilities.js

@@ -5,7 +5,8 @@ const agent = (method, name) => ({ method, path: `/api/v1/agent/${name}` });
  *  the person, the workspace, the project, the repository, then work. A new verb is a new row here
  *  in the same change, or `catalyst capabilities` lies to every guide that reads it. */
 export const CAPABILITIES = [
-    { verb: "onboard", does: "run and resume Catalyst setup with a saved step record", needs: "member", routes: [], since: "0.14.0", bootstrapHandoff: true },
+    { verb: "setup", does: "show install.sh's plan, progress and sign-in in this terminal, and ask its questions", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1 },
+    { verb: "onboard", does: "run and resume Catalyst setup with a saved step record", needs: "member", routes: [], since: "0.14.0", bootstrapHandoff: true, headless: true },
     { verb: "status", does: "say whether this machine is connected, as whom, and to which cloud", needs: "member", routes: [], since: "0.1.0" },
     { verb: "me", does: "read the person's seat, role and Linear identity", needs: "member", routes: [], since: "0.1.0" },
     { verb: "ready", does: "read the machine and the workspace's per-project readiness in one verdict", needs: "member", routes: [], since: "0.1.0" },

package/dist/cli-update-notice.js

@@ -0,0 +1,76 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { configDirFor, publishedCachePathFor } from "./config.js";
+import { latestPublishedVersion } from "./published.js";
+import { semverOlder } from "./semver.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RELEASE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+/** A notice never installs anything, shares setup's frame or writes machine-readable stdout. */
+export async function maybePrintPublishedUpdateNotice(ctx, options) {
+    if (!options.interactive ||
+        options.json ||
+        options.command === "setup" ||
+        options.command === "onboard")
+        return;
+    const directory = configDirFor(ctx.home);
+    const state = join(directory, "update-notice.json");
+    const published = publishedCachePathFor(ctx.home);
+    const now = ctx.now();
+    if (!Number.isFinite(now.getTime()))
+        return;
+    try {
+        // Optional metadata must not follow a user-created link or replace a special file.
+        for (const path of [
+            join(ctx.home, ".config"),
+            directory,
+            state,
+            published,
+            `${published}.tmp`,
+        ]) {
+            try {
+                const info = lstatSync(path);
+                if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()))
+                    return;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return;
+            }
+        }
+        try {
+            const previous = JSON.parse(readFileSync(state, "utf8"));
+            if (previous &&
+                typeof previous === "object" &&
+                "checkedAt" in previous &&
+                typeof previous.checkedAt === "string") {
+                const age = now.getTime() - Date.parse(previous.checkedAt);
+                if (age >= 0 && age < DAY_MS)
+                    return;
+            }
+        }
+        catch {
+            /* Missing or malformed optional metadata can be refreshed. */
+        }
+        mkdirSync(directory, { recursive: true });
+        const temporary = `${state}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify({ version: 1, checkedAt: now.toISOString() }) + "\n", { mode: 0o600, flag: "wx" });
+            renameSync(temporary, state);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+        // Record the attempt before the bounded lookup, including failures, so offline commands do
+        // not repeatedly contact npm. Reuse ready's anonymous request and version cache.
+        const reply = await latestPublishedVersion(ctx);
+        if (reply.latest &&
+            RELEASE.test(reply.latest) &&
+            semverOlder(options.version, reply.latest)) {
+            ctx.stderr(`Catalyst ${reply.latest} is out. Update with: npm install -g @catalyst-cloud/cli@latest`);
+        }
+    }
+    catch {
+        /* An optional update notice must never stop the requested command. */
+    }
+}