ghostrail 0.5.0 → 0.6.1

package/README.md

@@ -19,14 +19,172 @@ A software factory is thin glue over three primitive layers: where work comes fr
 ## Quickstart
 
 ```bash
-npx ghostrail install         # CLI on your PATH + the /ghostrail agent skill
+npx ghostrail install         # CLI + skill, then offers to set up your credentials
 ghostrail init code-local     # or: content-loop
-ghostrail secrets-setup --write    # scaffold your credentials file, then fill it in
 ghostrail run                      # one tick: claim, isolate, run, gate, open PRs
 ghostrail respond                  # fold new human PR comments back into branches
-ghostrail board                    # watch runs at http://127.0.0.1:4369/
+ghostrail board                    # watch runs at http://127.0.0.1:5050/
 ```
 
+## Credentials
+
+Ghostrail reads its credentials from two dotenv-style files before every `run`,
+`watch`, `respond`, and `triage`:
+
+| File | Scope |
+| --- | --- |
+| `~/.config/ghostrail/secrets.env` | every factory on your account |
+| `.ghostrail.env` in the repo you point `-C` at | that one factory |
+
+Precedence is repo, then global, then the ambient environment, so a value in a
+file beats an exported variable of the same name. Nothing has to go in your
+shell profile.
+
+`ghostrail install` offers to create this file for you at the end of a fresh
+install. You can also do it any time:
+
+```bash
+ghostrail secrets-setup            # report what it would add, change nothing
+ghostrail secrets-setup --write    # create it (mode 600), then open your $EDITOR
+```
+
+It is append-only and safe to re-run: existing values are never rewritten, keys
+you added yourself are left alone, and a second run adds nothing. Run it again
+after upgrading and it tops the file up with placeholders for any credential a
+newer ghostrail has learned to read. Add `--no-edit` to skip the editor.
+
+Uncomment only the lines you need. Leave the rest commented, because an
+uncommented empty value overrides, and therefore blanks out, a working
+credential from your environment.
+
+### `LINEAR_API_KEY` (required)
+
+The tracker credential. Ghostrail acts as whoever owns this key: it reads
+eligible issues, assigns them, moves their state, comments, and creates
+sub-issues during `triage`.
+
+1. Go to [linear.app/settings/account/security](https://linear.app/settings/account/security)
+   (**Settings → Account → Security & access**).
+2. Under **Personal API keys**, click **New API key**.
+3. Name it something you will recognize later, like `ghostrail`.
+4. Grant **Write**. Read alone is not enough: ghostrail assigns issues, moves
+   them between states, and comments. You do not need **Admin**.
+5. Restrict it to the team your factory works in, if your workspace has several.
+6. Copy the key (it starts with `lin_api_`) into `LINEAR_API_KEY`.
+
+Linear shows the key once. If you lose it, delete that key and make a new one.
+
+### `GH_TOKEN` (required for a code factory)
+
+Used to clone the repo, push factory branches, open pull requests, label them,
+and read and post PR comments during `respond`. `GITHUB_TOKEN` is read as a
+fallback when `GH_TOKEN` is unset; set one, not both.
+
+**The simple option, a classic token.** Go to
+[github.com/settings/tokens](https://github.com/settings/tokens) → **Generate
+new token (classic)**, set an expiration (90 days is a reasonable default), and
+tick the single **`repo`** scope. That covers everything ghostrail does. Add
+**`workflow`** only if you expect the agent to edit files under
+`.github/workflows/`, since GitHub rejects those pushes otherwise.
+
+**The tighter option, a fine-grained token.** Go to
+[github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens)
+→ **Generate new token**, set an expiration, select **Only select
+repositories** and pick the repo your factory targets, then grant these
+repository permissions:
+
+| Permission | Access | Why |
+| --- | --- | --- |
+| Contents | Read and write | clone the repo, push the factory branch |
+| Pull requests | Read and write | open the PR, read its comments in `respond` |
+| Issues | Read and write | apply the `ghostrail` label, post PR comments |
+| Metadata | Read-only | mandatory, GitHub enables it for you |
+
+Issues is the surprising one. PR labels and PR comments both go through
+GitHub's issues API, so a token with only Pull requests write cannot label a PR
+or comment on it.
+
+One caveat before you choose fine-grained: `gh` has a
+[known issue](https://github.com/cli/cli/issues/9166) where some PR reads fail
+with `Resource not accessible by personal access token`, because the CLI asks
+for project-card fields no fine-grained permission covers. If `respond` fails
+that way, a classic `repo` token is the fix.
+
+For a repo owned by an organization, an org owner may need to approve the token
+before it works, and fine-grained tokens can be blocked by org policy entirely.
+
+### Agent auth: pick one rail
+
+Ghostrail runs Claude Code as the coding agent, and there are two ways to pay
+for it. `ANTHROPIC_API_KEY` **wins whenever both are set**, so if you mean to
+bill a subscription, leave the API key commented out and make sure it is not
+exported in your shell either.
+
+**`CLAUDE_CODE_OAUTH_TOKEN`, to bill a Pro or Max subscription.** Run:
+
+```bash
+claude setup-token
+```
+
+It opens the same browser authorization flow as `/login` and prints a one-year
+token to the terminal. It does not save it anywhere, so copy it straight into
+`CLAUDE_CODE_OAUTH_TOKEN`. Requires a Pro, Max, Team, or Enterprise plan.
+Confirm that automated use fits your plan's terms before running it unattended,
+and note that your plan's rolling limits are shared with your claude.ai usage.
+
+**`ANTHROPIC_API_KEY`, to bill metered API usage.** Go to
+[platform.claude.com](https://platform.claude.com) → **Settings → API keys** →
+**Create key**, and copy it into `ANTHROPIC_API_KEY`. Straightforward billing
+and no shared subscription limits, but every run costs tokens.
+
+### Keeping them safe
+
+`secrets-setup` writes the file mode `600` inside a `700` directory, so it is
+readable only by you. A few things worth knowing:
+
+- **Never commit one.** A repo-local `.ghostrail.env` belongs in `.gitignore`;
+  the scaffolded templates do not add that line for you.
+- **Ghostrail redacts values from its CLI output.** Run logs and the JSON a tick
+  prints replace any known credential value, and `secrets-setup` prints key
+  names only. The run store behind `ghostrail board` keeps metadata rather than
+  command output (gate step names, exit codes, PR links), so it has little to
+  leak, but it is not passed through the redactor. Treat redaction as a safety
+  net, not a reason to paste a key into a terminal.
+- **Rotate on the provider, not in the file.** Delete the old key at the source
+  so a leaked copy stops working, then paste the new one in.
+
+## The factory image
+
+Only the `container` backend needs one. Both scaffold templates default to
+`local-worktree`, which runs in a git worktree on your host with no image and no
+Docker, so a first setup usually needs nothing here.
+
+When you do switch to `kind = "container"`, build the toolchain image once per
+machine. The agent and the gate run *inside* the workspace, so the container
+needs node and pnpm for the gate, git and `gh` to publish, and the Claude CLI for
+the agent. The default `alpine:3` has none of them.
+
+```bash
+ghostrail image build                  # -> ghostrail-factory:local
+ghostrail image build --tag mine:v2    # or your own tag
+```
+
+The Dockerfile ships inside the npm package, so this needs no checkout. From a
+repo checkout, `scripts/build-factory-image.sh` does the same thing. `ghostrail
+install` offers to run the build for you, defaulting to no since most people
+start on `local-worktree`.
+
+Point the config at whatever you built:
+
+```toml
+[backend]
+kind  = "container"
+image = "ghostrail-factory:local"
+```
+
+No credentials are baked into the image. They are forwarded per run from your
+environment after the secrets files are applied.
+
 ## Drive it from your coding agent
 
 `ghostrail skill` installs a `/ghostrail` skill into whichever coding agents you

package/dist/board/port.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The board's default port.
+ *
+ * It was 4369 until TJ-1507, which is the IANA-registered port for EPMD, the
+ * Erlang Port Mapper Daemon. Any machine running RabbitMQ, CouchDB, or Elixir
+ * tooling already holds it, so the board failed to start through no fault of
+ * the user. 5050 is unassigned.
+ */
+export declare const DEFAULT_BOARD_PORT = 5050;
+/** How many ports to try before giving up, when the port was not named. */
+export declare const PORT_FALLBACK_ATTEMPTS = 20;
+/**
+ * The ports to try, in order: `start`, `start + 1`, and so on. Stops at the top
+ * of the port range rather than proposing invalid ports, so a start near the
+ * ceiling simply yields a shorter list. Pure.
+ */
+export declare function portCandidates(start: number, attempts: number): number[];
+/**
+ * True for a value that can actually be bound: a whole number in 1..65535.
+ * Guards the flag, so `--port -5` or `--port 99999` is rejected with a clear
+ * message rather than reaching `listen` and failing obscurely.
+ */
+export declare function isValidPort(value: number): boolean;
+/** True for the error a busy port produces, the only one worth retrying. */
+export declare function isAddressInUse(error: unknown): boolean;
+//# sourceMappingURL=port.d.ts.map

package/dist/board/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/board/port.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAKzC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAQxE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD"}

package/dist/board/port.js

@@ -0,0 +1,41 @@
+/**
+ * The board's default port.
+ *
+ * It was 4369 until TJ-1507, which is the IANA-registered port for EPMD, the
+ * Erlang Port Mapper Daemon. Any machine running RabbitMQ, CouchDB, or Elixir
+ * tooling already holds it, so the board failed to start through no fault of
+ * the user. 5050 is unassigned.
+ */
+export const DEFAULT_BOARD_PORT = 5050;
+/** How many ports to try before giving up, when the port was not named. */
+export const PORT_FALLBACK_ATTEMPTS = 20;
+/** The highest valid TCP port. */
+const MAX_PORT = 65535;
+/**
+ * The ports to try, in order: `start`, `start + 1`, and so on. Stops at the top
+ * of the port range rather than proposing invalid ports, so a start near the
+ * ceiling simply yields a shorter list. Pure.
+ */
+export function portCandidates(start, attempts) {
+    const ports = [];
+    for (let i = 0; i < attempts; i++) {
+        const port = start + i;
+        if (port > MAX_PORT)
+            break;
+        ports.push(port);
+    }
+    return ports;
+}
+/**
+ * True for a value that can actually be bound: a whole number in 1..65535.
+ * Guards the flag, so `--port -5` or `--port 99999` is rejected with a clear
+ * message rather than reaching `listen` and failing obscurely.
+ */
+export function isValidPort(value) {
+    return Number.isInteger(value) && value >= 1 && value <= MAX_PORT;
+}
+/** True for the error a busy port produces, the only one worth retrying. */
+export function isAddressInUse(error) {
+    return error?.code === "EADDRINUSE";
+}
+//# sourceMappingURL=port.js.map

package/dist/board/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/board/port.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,kCAAkC;AAClC,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,QAAgB;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC;QACvB,IAAI,IAAI,GAAG,QAAQ;YAAE,MAAM;QAC3B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,QAAQ,CAAC;AACpE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAQ,KAAmC,EAAE,IAAI,KAAK,YAAY,CAAC;AACrE,CAAC"}

package/dist/cli/commands.d.ts

@@ -1,4 +1,5 @@
 import type { Scope } from "../vendor/skilltend/paths.js";
+import { type Asker } from "./prompt.js";
 export interface CommandStreams {
     out: (text: string) => void;
     err: (text: string) => void;
@@ -39,6 +40,8 @@ interface BoardFlags {
     port: number;
     bind: string;
     token?: string;
+    /** True when --port/-p named the port, rather than it coming from the default. */
+    portExplicit: boolean;
 }
 /** Parse `board` flags: `--repo`, `--port`, `--bind`, `--token`. */
 export declare function parseBoardFlags(argv: readonly string[], defaults: BoardFlags): BoardFlags;
@@ -84,7 +87,16 @@ export declare function cmdSkill(argv: readonly string[], streams: CommandStream
  * Pins to the running version rather than `latest`, so `npx ghostrail@x.y.z
  * install` gives you exactly x.y.z.
  */
-export declare function cmdInstall(argv: readonly string[], streams: CommandStreams, env?: CommandEnv, cwd?: string): Promise<number>;
+export declare function cmdInstall(argv: readonly string[], streams: CommandStreams, env?: CommandEnv, cwd?: string, deps?: InstallDeps): Promise<number>;
+/**
+ * Offer the two setup steps `install` cannot infer: the factory image and the
+ * credentials file. An explicit flag decides; otherwise ask, but only on a TTY,
+ * so a Dockerfile or CI install never blocks on stdin.
+ *
+ * Failures here are reported and swallowed. A failed optional extra must not
+ * make a successful install look like a failed one.
+ */
+export declare function runInstallOffers(argv: readonly string[], streams: CommandStreams, env: CommandEnv, deps?: InstallDeps): Promise<void>;
 /**
  * `ghostrail self-update`: upgrade the CLI to the latest published version, then
  * install that version's skill.
@@ -101,6 +113,23 @@ export declare function cmdSelfUpdate(argv: readonly string[], streams: CommandS
  * the profile.
  */
 export declare function cmdClaudeSetup(argv: readonly string[], streams: CommandStreams, env?: CommandEnv): Promise<number>;
+/** Injectables so `image` and the install offers can be driven in tests. */
+export interface InstallDeps extends SecretsSetupDeps {
+    /** Runs docker; defaults to spawning it and streaming its output. */
+    runDocker?: (args: readonly string[]) => Promise<number>;
+    /** Overrides TTY detection for the prompts. */
+    isTty?: boolean;
+    /** Answers a yes/no prompt; defaults to reading the terminal. */
+    ask?: Asker;
+}
+/**
+ * `ghostrail image build`: build the factory toolchain image from the
+ * Dockerfile inside the installed package, so no repo checkout is needed.
+ *
+ * Only `build` is supported today; the noun is a subcommand so `image push` or
+ * `image check` can join it later without another top-level verb.
+ */
+export declare function cmdImage(argv: readonly string[], streams: CommandStreams, deps?: InstallDeps): Promise<number>;
 /** Injectables so the editor launch can be observed instead of performed. */
 export interface SecretsSetupDeps {
     launchEditor?: (command: readonly string[], path: string) => Promise<number>;

package/dist/cli/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands.js

@@ -1,15 +1,18 @@
+import { spawn } from "node:child_process";
 import { access, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { spawnCollect } from "../backend/proc.js";
+import { DEFAULT_BOARD_PORT, PORT_FALLBACK_ATTEMPTS, isAddressInUse, isValidPort, portCandidates, } from "../board/port.js";
 import { createBoardServer } from "../board/server.js";
 import { buildProposal, writeProfile } from "../claude-profile/index.js";
 import { parseDuration } from "../config/duration.js";
 import { parseMergedConfig } from "../config/load.js";
 import { STORE_DIR, buildLoopDeps, buildRespondDeps, buildTriageDeps, resolveRepoSlug, } from "../factory/build.js";
 import { GlobalStore, resolveGlobalDir } from "../global/store.js";
+import { DEFAULT_FACTORY_IMAGE, dockerBuildArgs, dockerDir, parseImageFlags, } from "../image/build.js";
 import { classify, hashContent, mergeManifest, readManifest, writeManifest, } from "../init/template.js";
 import { FileLock } from "../lock/file-lock.js";
 import { runTick } from "../loop/engine.js";
@@ -20,6 +23,7 @@ import { applySkillPlan, describePlan, pathCtx, planSkillInstall, uninstallSkill
 import { FileStore } from "../store/file-store.js";
 import { triageTick } from "../triage/engine.js";
 import { VERSION } from "../version.js";
+import { askOnTerminal, parseInstallOffers } from "./prompt.js";
 /**
  * Parse the flags shared by `run` and `respond`: `--config`/`-c <path>` and
  * `--repo`/`-C <path>`, starting from the given defaults. Unknown tokens are
@@ -268,8 +272,10 @@ export function parseBoardFlags(argv, defaults) {
             i++;
         }
         else if (arg === "--port" || arg === "-p") {
-            if (Number.isFinite(Number(next)))
+            if (isValidPort(Number(next))) {
                 flags.port = Number(next);
+                flags.portExplicit = true;
+            }
             i++;
         }
         else if (arg === "--bind") {
@@ -287,10 +293,16 @@ export function parseBoardFlags(argv, defaults) {
 export function cmdBoard(argv, streams, env = process.env, cwd = process.cwd()) {
     const flags = parseBoardFlags(argv, {
         repo: cwd,
-        port: 4369,
+        port: DEFAULT_BOARD_PORT,
         bind: "127.0.0.1",
+        portExplicit: false,
         ...(env.GHOSTRAIL_BOARD_TOKEN === undefined ? {} : { token: env.GHOSTRAIL_BOARD_TOKEN }),
     });
+    // A --port that failed validation leaves the default in place. Say so, rather
+    // than quietly serving somewhere the user did not ask for.
+    if (!flags.portExplicit && (argv.includes("--port") || argv.includes("-p"))) {
+        streams.err("ignoring --port: must be a whole number from 1 to 65535\n");
+    }
     const store = new FileStore(join(flags.repo, STORE_DIR));
     let server;
     try {
@@ -303,13 +315,40 @@ export function cmdBoard(argv, streams, env = process.env, cwd = process.cwd())
         streams.err(`${error instanceof Error ? error.message : String(error)}\n`);
         return Promise.resolve(1);
     }
+    const candidates = flags.portExplicit
+        ? [flags.port]
+        : portCandidates(flags.port, PORT_FALLBACK_ATTEMPTS);
     return new Promise((resolve) => {
+        let index = 0;
         server.on("error", (error) => {
-            streams.err(`board error: ${error.message}\n`);
+            // Only a busy port is worth retrying, and only when we chose the port
+            // ourselves. A port the user named is never moved silently, because
+            // something (a bookmark, a proxy) usually depends on that exact number.
+            const next = candidates[index + 1];
+            if (isAddressInUse(error) && next !== undefined) {
+                index++;
+                server.listen(next, flags.bind);
+                return;
+            }
+            if (isAddressInUse(error) && flags.portExplicit) {
+                streams.err(`board error: port ${flags.port} is already in use\n`);
+            }
+            else if (isAddressInUse(error)) {
+                const last = candidates[candidates.length - 1] ?? flags.port;
+                streams.err(`board error: no free port between ${flags.port} and ${last}\n`);
+            }
+            else {
+                streams.err(`board error: ${error.message}\n`);
+            }
             resolve(1);
         });
-        server.listen(flags.port, flags.bind, () => {
-            streams.out(`ghostrail board on http://${flags.bind}:${flags.port}/\n`);
+        const first = candidates[0] ?? flags.port;
+        server.listen(first, flags.bind, () => {
+            const bound = candidates[index] ?? first;
+            if (bound !== flags.port) {
+                streams.out(`port ${flags.port} was busy, using ${bound}\n`);
+            }
+            streams.out(`ghostrail board on http://${flags.bind}:${bound}/\n`);
         });
     });
 }
@@ -630,15 +669,53 @@ async function npmInstallGlobal(version) {
  * Pins to the running version rather than `latest`, so `npx ghostrail@x.y.z
  * install` gives you exactly x.y.z.
  */
-export async function cmdInstall(argv, streams, env = process.env, cwd = process.cwd()) {
+export async function cmdInstall(argv, streams, env = process.env, cwd = process.cwd(), deps = {}) {
     streams.out(`installing ghostrail@${VERSION} globally...\n`);
     const code = await npmInstallGlobal(VERSION);
     if (code !== 0) {
         streams.err(`global install failed (npm exited ${code}). Install it yourself with: npm install -g ghostrail\n`);
     }
     const skillCode = await cmdSkill(argv, streams, env, cwd);
+    await runInstallOffers(argv, streams, env, deps);
     return code === 0 ? skillCode : 1;
 }
+/**
+ * Offer the two setup steps `install` cannot infer: the factory image and the
+ * credentials file. An explicit flag decides; otherwise ask, but only on a TTY,
+ * so a Dockerfile or CI install never blocks on stdin.
+ *
+ * Failures here are reported and swallowed. A failed optional extra must not
+ * make a successful install look like a failed one.
+ */
+export async function runInstallOffers(argv, streams, env, deps = {}) {
+    const offers = parseInstallOffers(argv);
+    const interactive = deps.isTty ?? process.stdin.isTTY === true;
+    const ask = deps.ask ?? askOnTerminal;
+    const decide = async (stated, question, defaultYes) => {
+        if (stated !== undefined)
+            return stated;
+        if (!interactive)
+            return false;
+        return ask(question, defaultYes);
+    };
+    const wantsImage = await decide(offers.image, `\nBuild the factory container image (${DEFAULT_FACTORY_IMAGE})?\nOnly needed for [backend].kind = "container", and it takes a few minutes.`, false);
+    if (wantsImage) {
+        const code = await cmdImage(["build"], streams, deps);
+        if (code !== 0)
+            streams.err("image build failed; run `ghostrail image build` to retry\n");
+    }
+    const secretsPath = join(resolveGlobalDir({ GHOSTRAIL_HOME: env.GHOSTRAIL_HOME, XDG_CONFIG_HOME: env.XDG_CONFIG_HOME }, homedir()), GLOBAL_SECRETS_FILE);
+    const wantsSecrets = await decide(offers.secrets, `\nCreate your credentials (secrets) file at ${secretsPath}?`, true);
+    if (wantsSecrets) {
+        const code = await cmdSecretsSetup(["--write"], streams, env, {
+            ...(deps.isTty === undefined ? {} : { isTty: deps.isTty }),
+            ...(deps.launchEditor === undefined ? {} : { launchEditor: deps.launchEditor }),
+        });
+        if (code !== 0) {
+            streams.err("secrets setup failed; run `ghostrail secrets-setup --write` to retry\n");
+        }
+    }
+}
 /**
  * `ghostrail self-update`: upgrade the CLI to the latest published version, then
  * install that version's skill.
@@ -734,6 +811,41 @@ export async function cmdClaudeSetup(argv, streams, env = process.env) {
     }
     return 0;
 }
+/**
+ * `ghostrail image build`: build the factory toolchain image from the
+ * Dockerfile inside the installed package, so no repo checkout is needed.
+ *
+ * Only `build` is supported today; the noun is a subcommand so `image push` or
+ * `image check` can join it later without another top-level verb.
+ */
+export async function cmdImage(argv, streams, deps = {}) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "build") {
+        streams.err(`ghostrail image: unknown subcommand '${subcommand ?? ""}'\n\nUsage: ghostrail image build [--tag <tag>]\n`);
+        return 1;
+    }
+    const { tag } = parseImageFlags(rest);
+    const context = dockerDir();
+    const dockerfile = join(context, "factory.Dockerfile");
+    const args = dockerBuildArgs(dockerfile, context, tag);
+    streams.out(`building ${tag} from ${dockerfile}\n`);
+    const run = deps.runDocker ?? streamDocker;
+    const code = await run(args);
+    if (code === 0) {
+        streams.out(`built ${tag}\n`);
+        return 0;
+    }
+    streams.err(`docker exited ${code}. Is Docker installed and running? \`docker version\` should succeed.\n`);
+    return code;
+}
+/** Spawn docker inheriting the terminal, so a long build shows progress. */
+function streamDocker(args) {
+    return new Promise((resolve) => {
+        const child = spawn("docker", [...args], { stdio: "inherit" });
+        child.on("error", () => resolve(1));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
 /** Parse `secrets-setup` flags: `--write` and `--no-edit`. */
 function parseSecretsSetupFlags(argv) {
     return {