@wardby/cli 0.4.1 → 0.5.0

package/dist/quickstart/coding.d.ts

@@ -0,0 +1,66 @@
+import type { CodingProvider } from "../coding/provider.js";
+import type { DeclaredService } from "../coding/services/declaration.js";
+import { type CodingSeedInput, type CodingSeedResult } from "./coding-seed.js";
+import { type QuickstartPaths, type QuickstartState } from "./config.js";
+import { type StarterService } from "./starter-services.js";
+export declare const CODING_PROXY_CONTAINER = "wardby-coding-proxy";
+export declare const CODING_COMPOSE_FILE = "deploy/local/docker-compose.quickstart-coding.yml";
+export interface CommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export type RunCommand = (command: string, args: string[], options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    inherit?: boolean;
+}) => CommandResult;
+export interface CodingPrompts {
+    line(question: string, fallback?: string): Promise<string>;
+    yesNo(question: string, defaultYes: boolean): Promise<boolean>;
+    secret(question: string): Promise<string>;
+}
+export interface CodingDeps {
+    run: RunCommand;
+    prompts: CodingPrompts;
+    log: (line: string) => void;
+    cwd: string;
+    /** The process environment: provider keys and image overrides. */
+    env: NodeJS.ProcessEnv;
+    packageRoot: string;
+    seed: (input: Omit<CodingSeedInput, "ownerId">) => Promise<CodingSeedResult>;
+    /** The catalog image for each declared service; `image` is undefined when the catalog has no such entry. */
+    catalogImages: (services: DeclaredService[]) => Promise<Array<{
+        service: DeclaredService;
+        image?: string;
+    }>>;
+}
+export interface CodingStepOptions {
+    nonInteractive: boolean;
+    /** true = --coding, false = --no-coding, undefined = ask (interactive) or skip (non-interactive). */
+    coding?: boolean;
+    trust: string[];
+    provider?: CodingProvider;
+    /** --starter-services; undefined = ask (interactive) or none (non-interactive). */
+    starterServices?: StarterService[];
+}
+export interface CodingStepResult {
+    roots: string[];
+    provider: CodingProvider;
+    repository?: string;
+    seed?: CodingSeedResult;
+}
+/** The top level of the git work tree containing `cwd`, realpath'd; null outside one. */
+export declare function defaultTrustedFolder(cwd: string): string | null;
+export declare function codingEnvUpdates(input: {
+    roots: string[];
+    provider: string;
+    /** The Codex worker; absent for claude-code, which doesn't need one. */
+    workerImage?: string;
+    runtimeImage: string;
+    claudeWorkerImage?: string;
+    claudeToolRunnerImage?: string;
+}): Record<string, string>;
+/** The compose files for a quickstart project; the coding file only once its runtime image is configured. */
+export declare function quickstartComposeFiles(packageRoot: string, env: Record<string, string | undefined>): string[];
+export declare function codingStep(paths: QuickstartPaths, state: QuickstartState, opts: CodingStepOptions, deps: CodingDeps): Promise<CodingStepResult | null>;

package/dist/quickstart/coding.js

@@ -0,0 +1,430 @@
+/**
+ * The quickstart's optional coding step: trust local folders, start the coding
+ * proxy, and seed a coding agent (`local-builder`) and a review agent
+ * (`local-reviewer`) against a local git repository — no GitHub App needed.
+ *
+ * Every Docker/Compose call, prompt, and database write goes through
+ * CodingDeps so tests never touch the Docker daemon. The only write into the
+ * user's repository is the opt-in starter `.wardby/services.yaml`, made with
+ * git plumbing onto its own branch (starter-services.ts).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { delimiter, join, resolve, sep } from "node:path";
+import { dockerCodingPreflight } from "../coding/docker-preflight.js";
+import { cleanGitEnv } from "../coding/local-git.js";
+import { LOCAL_REPO_PREFIX, loadLocalRepoRoots, resolveLocalRepository } from "../coding/local-repo.js";
+import { BUILDER_AGENT, REVIEWER_AGENT } from "./coding-seed.js";
+import { defaultModel, readQuickstartEnv, writeQuickstartEnv, } from "./config.js";
+import { CodingSkip, prepareImages } from "./coding-images.js";
+import { STARTER_SERVICES_BRANCH, commitStarterServices, inspectDeclaredServices, repoDefaultBranch, starterDeclaredServices, starterServicesYaml, } from "./starter-services.js";
+export const CODING_PROXY_CONTAINER = "wardby-coding-proxy";
+export const CODING_COMPOSE_FILE = "deploy/local/docker-compose.quickstart-coding.yml";
+const BASE_COMPOSE_FILE = "deploy/local/docker-compose.yml";
+const PROVIDER_KEYS = {
+    codex: "OPENAI_API_KEY",
+    "claude-code": "ANTHROPIC_API_KEY",
+};
+const PROVIDER_LABELS = { codex: "Codex", "claude-code": "Claude Code" };
+/** The top level of the git work tree containing `cwd`, realpath'd; null outside one. */
+export function defaultTrustedFolder(cwd) {
+    const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8", env: cleanGitEnv() });
+    const top = result.status === 0 ? result.stdout.trim() : "";
+    if (!top)
+        return null;
+    try {
+        return realpathSync(top);
+    }
+    catch {
+        return null;
+    }
+}
+export function codingEnvUpdates(input) {
+    const updates = {
+        LOCAL_REPO_ROOTS: input.roots.join(delimiter),
+        JOB_LAUNCHER: "docker",
+        WARDBY_RUNTIME_IMAGE: input.runtimeImage,
+        CODING_PROXY_CONTAINER,
+    };
+    if (input.provider !== "claude-code" && input.workerImage)
+        updates.CODING_WORKER_IMAGE = input.workerImage;
+    if (input.provider === "claude-code" && input.claudeWorkerImage && input.claudeToolRunnerImage) {
+        updates.CODING_CLAUDE_WORKER_IMAGE = input.claudeWorkerImage;
+        updates.CODING_CLAUDE_TOOL_RUNNER_IMAGE = input.claudeToolRunnerImage;
+    }
+    return updates;
+}
+/** The compose files for a quickstart project; the coding file only once its runtime image is configured. */
+export function quickstartComposeFiles(packageRoot, env) {
+    const files = [join(packageRoot, BASE_COMPOSE_FILE)];
+    if (env.WARDBY_RUNTIME_IMAGE)
+        files.push(join(packageRoot, CODING_COMPOSE_FILE));
+    return files;
+}
+function realFolder(path) {
+    let real;
+    try {
+        real = realpathSync(resolve(path));
+    }
+    catch {
+        throw new CodingSkip(`${path} does not exist`);
+    }
+    if (!statSync(real).isDirectory())
+        throw new CodingSkip(`${path} is not a folder`);
+    return real;
+}
+async function isRepositoryTop(path, roots) {
+    try {
+        await resolveLocalRepository(`${LOCAL_REPO_PREFIX}${path}`, roots);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function chooseRoots(opts, existing, deps) {
+    const roots = [...existing];
+    const add = (path) => {
+        const real = realFolder(path);
+        if (!roots.includes(real))
+            roots.push(real);
+    };
+    for (const path of opts.trust)
+        add(path);
+    if (opts.nonInteractive) {
+        if (roots.length === 0)
+            throw new CodingSkip("pass --trust <dir> to choose the folders coding agents may use");
+        return roots;
+    }
+    if (existing.length > 0) {
+        deps.log("Trusted folders:");
+        existing.forEach((root, index) => deps.log(`  [${index + 1}] ${root}`));
+        const remove = await deps.prompts.line("Remove any? Numbers separated by commas (blank = keep all): ", "");
+        const drop = new Set(remove.split(",").map((part) => Number(part.trim()) - 1));
+        for (const index of [...drop].sort((a, b) => b - a)) {
+            if (Number.isInteger(index) && index >= 0 && index < existing.length)
+                roots.splice(roots.indexOf(existing[index]), 1);
+        }
+    }
+    const suggested = defaultTrustedFolder(deps.cwd);
+    if (suggested && !roots.includes(suggested) && (await deps.prompts.yesNo(`Trust ${suggested}?`, true))) {
+        roots.push(suggested);
+    }
+    for (;;) {
+        const answer = await deps.prompts.line("Add another trusted folder (blank = done): ", "");
+        if (!answer)
+            break;
+        try {
+            add(answer);
+        }
+        catch (error) {
+            deps.log(`! ${error.message}`);
+        }
+    }
+    if (roots.length === 0)
+        throw new CodingSkip("no folder was trusted");
+    return roots;
+}
+async function chooseProvider(opts, config, deps) {
+    const hasKey = (provider) => Boolean(deps.env[PROVIDER_KEYS[provider]] || config[PROVIDER_KEYS[provider]]);
+    let provider = opts.provider;
+    if (!provider) {
+        const available = ["codex", "claude-code"].filter(hasKey);
+        if (available.length === 1 || (opts.nonInteractive && available.length > 0))
+            provider = available[0];
+        else if (opts.nonInteractive)
+            throw new CodingSkip("set OPENAI_API_KEY (Codex) or ANTHROPIC_API_KEY (Claude Code)");
+        else {
+            const answer = (await deps.prompts.line("Coding agent: [1] Codex, [2] Claude Code [1] ", "1")).toLowerCase();
+            if (answer === "1" || answer === "codex")
+                provider = "codex";
+            else if (answer === "2" || answer === "claude-code" || answer === "claude")
+                provider = "claude-code";
+            else
+                throw new CodingSkip(`unknown coding agent "${answer}"`);
+        }
+    }
+    const keyName = PROVIDER_KEYS[provider];
+    if (!hasKey(provider)) {
+        if (opts.nonInteractive)
+            throw new CodingSkip(`${keyName} is required for ${PROVIDER_LABELS[provider]}`);
+        const key = await deps.prompts.secret(`${keyName}: `);
+        if (!key)
+            throw new CodingSkip(`${keyName} cannot be empty`);
+        config[keyName] = key;
+    }
+    else if (!config[keyName] && deps.env[keyName]) {
+        // The coding proxy container reads the key from the quickstart env file.
+        config[keyName] = deps.env[keyName];
+    }
+    return provider;
+}
+function startProxy(paths, state, deps) {
+    const env = readQuickstartEnv(paths);
+    const files = quickstartComposeFiles(deps.packageRoot, env).flatMap((file) => ["--file", file]);
+    const args = ["compose", "--project-name", state.composeProject, "--env-file", paths.envFile, ...files];
+    const result = deps.run("docker", [...args, "up", "--detach", "--wait", "--wait-timeout", "90", "coding-proxy"], {
+        cwd: paths.projectDir,
+        env: { ...deps.env, ...env, WARDBY_PROJECT_DIR: paths.projectDir },
+    });
+    if (result.status !== 0) {
+        throw new CodingSkip(`the coding proxy did not start: ${(result.stderr || result.stdout).trim().split("\n")[0]}`);
+    }
+}
+/** Git repositories among the trusted folders: a folder that is one, else its direct (non-hidden) children. */
+async function findRepositories(scan, roots) {
+    const found = [];
+    const add = (path) => {
+        if (!found.includes(path))
+            found.push(path);
+    };
+    for (const root of scan) {
+        if (await isRepositoryTop(root, roots)) {
+            add(root);
+            continue;
+        }
+        let names;
+        try {
+            names = readdirSync(root, { withFileTypes: true })
+                .filter((entry) => !entry.name.startsWith(".") && (entry.isDirectory() || entry.isSymbolicLink()))
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            let real;
+            try {
+                real = realpathSync(join(root, name));
+                if (!statSync(real).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // A symlink out of the trusted folder is not a candidate; resolveLocalRepository checks the roots.
+            if (real !== root && !real.startsWith(root.endsWith(sep) ? root : root + sep))
+                continue;
+            // Cheap pre-check (a .git directory or file) before spawning git.
+            if (!existsSync(join(real, ".git")))
+                continue;
+            if (await isRepositoryTop(real, roots))
+                add(real);
+        }
+    }
+    return found;
+}
+async function chooseRepository(roots, opts, deps) {
+    // Folders passed with --trust on this run take precedence over the saved ones.
+    const thisRun = [];
+    for (const path of opts.trust) {
+        try {
+            thisRun.push(realpathSync(resolve(path)));
+        }
+        catch {
+            // chooseRoots already rejected a missing folder.
+        }
+    }
+    let found = await findRepositories(thisRun, roots);
+    if (found.length === 0)
+        found = await findRepositories(roots, roots);
+    if (found.length === 1)
+        return found[0];
+    if (found.length > 1) {
+        if (opts.nonInteractive) {
+            deps.log(`Found ${found.length} git repositories in the trusted folders; using ${found[0]}:`);
+            for (const repo of found)
+                deps.log(`  ${repo}`);
+            deps.log("  To use another, re-run quickstart with --trust <repo>.");
+            return found[0];
+        }
+        deps.log("Git repositories found in the trusted folders:");
+        found.forEach((repo, index) => deps.log(`  [${index + 1}] ${repo}`));
+        for (;;) {
+            const answer = await deps.prompts.line(`Which repository should the agents use? [1-${found.length}] `, "1");
+            const index = Number(answer.trim()) - 1;
+            if (Number.isInteger(index) && index >= 0 && index < found.length)
+                return found[index];
+            deps.log(`! Enter a number from 1 to ${found.length}.`);
+        }
+    }
+    if (opts.nonInteractive)
+        return null;
+    for (;;) {
+        const answer = await deps.prompts.line("Git repository for the agents (inside a trusted folder; blank = skip): ", "");
+        if (!answer)
+            return null;
+        try {
+            return (await resolveLocalRepository(`${LOCAL_REPO_PREFIX}${resolve(answer)}`, roots)).path;
+        }
+        catch (error) {
+            deps.log(`! ${error.message}`);
+        }
+    }
+}
+async function chooseStarter(branch, opts, deps) {
+    if (opts.starterServices !== undefined)
+        return opts.starterServices;
+    if (opts.nonInteractive)
+        return [];
+    const answer = (await deps.prompts.line(`No .wardby/services.yaml on ${branch}. Create a starter on a new branch ${STARTER_SERVICES_BRANCH}? [p]ostgres, [r]edis, [b]oth, [n]one [n] `, "n")).toLowerCase();
+    if (answer === "p" || answer === "postgres")
+        return ["postgres"];
+    if (answer === "r" || answer === "redis")
+        return ["redis"];
+    if (answer === "b" || answer === "both")
+        return ["postgres", "redis"];
+    return [];
+}
+async function pullServiceImages(services, deps) {
+    if (services.length === 0)
+        return;
+    for (const { service, image } of await deps.catalogImages(services)) {
+        const label = `${service.name} ${service.version}`;
+        if (!image)
+            deps.log(`! ${label} is not in the service catalog; runs that declare it will be refused.`);
+        else if (deps.run("docker", ["pull", image], { inherit: true }).status !== 0) {
+            deps.log(`! Could not pull the ${label} image (${image}); a run will pull it when it starts.`);
+        }
+    }
+}
+/** Reads (or offers to create) the repository's services.yaml; returns the service names the builder may start. */
+async function prepareServices(repo, roots, branch, baseSha, opts, deps) {
+    // Read at the exact commit a starter would be built on, so the two cannot disagree.
+    const declared = await inspectDeclaredServices(repo, roots, baseSha);
+    if (declared.kind === "invalid") {
+        deps.log(`! .wardby/services.yaml on ${branch} is invalid: ${declared.reason}`);
+        deps.log("  Coding runs on that branch will be refused until it is fixed (see docs/coding-services.md).");
+        return [];
+    }
+    if (declared.kind === "valid") {
+        const list = declared.services.map((service) => `${service.name} ${service.version}`).join(", ");
+        deps.log(`✓ .wardby/services.yaml on ${branch} declares: ${list || "no services"}`);
+        await pullServiceImages(declared.services, deps);
+        return declared.services.map((service) => service.name);
+    }
+    const choices = await chooseStarter(branch, opts, deps);
+    if (choices.length === 0) {
+        deps.log(`No .wardby/services.yaml on ${branch}; add one to start databases next to runs (docs/coding-services.md).`);
+        return [];
+    }
+    const result = await commitStarterServices({
+        dir: repo,
+        baseSha,
+        content: starterServicesYaml(choices),
+        confirmReplace: async (existing) => {
+            if (opts.nonInteractive)
+                return false;
+            return await deps.prompts.yesNo(`Branch ${STARTER_SERVICES_BRANCH} already exists (at ${existing.slice(0, 12)}). Replace it?`, false);
+        },
+    });
+    if (result.status === "refused") {
+        deps.log(`! Did not write the starter file: ${result.reason}`);
+        return [];
+    }
+    if (result.status === "kept") {
+        deps.log(`! Branch ${STARTER_SERVICES_BRANCH} already exists; left it unchanged.`);
+    }
+    else {
+        deps.log(`✓ Committed a starter .wardby/services.yaml on branch ${STARTER_SERVICES_BRANCH} (your checkout is unchanged).`);
+    }
+    deps.log(`  Merge ${STARTER_SERVICES_BRANCH} into ${branch}, or point ${BUILDER_AGENT} at it:`);
+    deps.log(`  update_agent with codingProfile.baseRef = "${STARTER_SERVICES_BRANCH}"`);
+    const services = starterDeclaredServices(choices);
+    await pullServiceImages(services, deps);
+    return services.map((service) => service.name);
+}
+function seedLines(seed, repository) {
+    const lines = [];
+    for (const [name, outcome] of [
+        [BUILDER_AGENT, seed.builder],
+        [REVIEWER_AGENT, seed.reviewer],
+    ]) {
+        if (outcome.status === "skipped")
+            lines.push(`! ${name}: ${outcome.reason}`);
+        else
+            lines.push(`✓ ${name} ${outcome.status} for ${repository}`);
+    }
+    if (seed.builder.status !== "skipped" && seed.reviewer.status !== "skipped") {
+        lines.push("", "Try them from your MCP client (or ask your assistant to make these calls):", `  trigger_agent {"agentId": "${seed.builder.id}", "task": "Add a short CONTRIBUTING.md"}`, "  The run pushes a branch wardby/run-<run id> into your repository (get_run shows it). Review it with:", `  trigger_agent {"agentId": "${seed.reviewer.id}", "review": {"branch": "wardby/run-<run id>"}}`);
+    }
+    return lines;
+}
+export async function codingStep(paths, state, opts, deps) {
+    if (opts.coding === false)
+        return null;
+    if (opts.coding === undefined) {
+        if (opts.nonInteractive)
+            return null;
+        if (!(await deps.prompts.yesNo("Set up coding + review agents against a local git repo?", false)))
+            return null;
+    }
+    try {
+        const config = readQuickstartEnv(paths);
+        const existing = loadLocalRepoRoots({ LOCAL_REPO_ROOTS: config.LOCAL_REPO_ROOTS });
+        for (const missing of existing.missing)
+            deps.log(`! Dropping trusted folder ${missing}: it no longer exists.`);
+        const roots = await chooseRoots(opts, existing.roots, deps);
+        const provider = await chooseProvider(opts, config, deps);
+        const images = prepareImages(provider, config, deps);
+        const next = {
+            ...config,
+            ...codingEnvUpdates({
+                roots,
+                provider,
+                workerImage: images.worker,
+                runtimeImage: images.runtime,
+                claudeWorkerImage: images.claudeWorker,
+                claudeToolRunnerImage: images.claudeToolRunner,
+            }),
+        };
+        // An earlier quickstart run, or a manual setting, may have pointed CODING_WORKER_IMAGE at the Claude
+        // worker; that would start the wrong driver for a Codex run. A real Codex worker from a Codex run stays.
+        const staleClaude = [config.CODING_CLAUDE_WORKER_IMAGE, images.claudeWorker].filter(Boolean);
+        if (provider === "claude-code" && staleClaude.includes(next.CODING_WORKER_IMAGE))
+            delete next.CODING_WORKER_IMAGE;
+        writeQuickstartEnv(paths, next);
+        deps.log(`✓ Trusted folders: ${roots.join(", ")}`);
+        startProxy(paths, state, deps);
+        deps.log(`✓ Coding proxy is running (${CODING_PROXY_CONTAINER})`);
+        const preflight = await dockerCodingPreflight({
+            workerImage: images.worker,
+            claudeWorkerImage: images.claudeWorker,
+            claudeToolRunnerImage: images.claudeToolRunner,
+            proxyContainer: CODING_PROXY_CONTAINER,
+        }, async (image) => deps.run("docker", ["image", "inspect", image]).status === 0);
+        if (preflight)
+            throw new CodingSkip(`coding preflight failed: ${preflight}`);
+        deps.log("✓ Coding preflight passed");
+        const repo = await chooseRepository(roots, opts, deps);
+        if (!repo) {
+            deps.log("No git repository was found in or directly under the trusted folders; the agents were not created.");
+            return { roots, provider };
+        }
+        const base = await repoDefaultBranch(repo);
+        if (!base) {
+            deps.log(`! ${repo} has no checked-out branch with commits; the agents were not created.`);
+            return { roots, provider };
+        }
+        const services = await prepareServices(repo, roots, base.branch, base.sha, opts, deps);
+        const repository = `${LOCAL_REPO_PREFIX}${repo}`;
+        const seed = await deps.seed({
+            provider,
+            builderModel: defaultModel(provider === "codex" ? "openai" : "anthropic"),
+            reviewerModel: state.model,
+            repository,
+            baseRef: base.branch,
+            services,
+        });
+        for (const line of seedLines(seed, repository))
+            deps.log(line);
+        return { roots, provider, repository, seed };
+    }
+    catch (error) {
+        if (!(error instanceof CodingSkip))
+            throw error;
+        deps.log(`! Skipped the coding step: ${error.message}.`);
+        return null;
+    }
+}

package/dist/quickstart/images.d.ts

@@ -0,0 +1,19 @@
+export interface QuickstartImages {
+    runtime: string;
+    worker: string;
+    /** Claude Code's worker and tool runner; absent when this source does not provide them. */
+    claudeWorker?: string;
+    claudeToolRunner?: string;
+    source: "env" | "package" | "build";
+}
+/**
+ * Where the coding step gets its runtime and worker images: explicit env
+ * overrides, the digest-pinned refs written at release time, or a local build
+ * from a source checkout.
+ */
+export declare function resolveQuickstartImages(opts: {
+    env: NodeJS.ProcessEnv;
+    packageRoot: string;
+}): QuickstartImages | {
+    unavailable: string;
+};

package/dist/quickstart/images.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { imageVariable } from "../config/providers.js";
+const DIGEST_REF = /@sha256:[0-9a-f]{64}$/;
+function readPackageImages(packageRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageRoot, "dist", "quickstart-images.json"), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const { runtime, worker, claudeWorker, claudeToolRunner } = parsed;
+        if (typeof runtime !== "string" || typeof worker !== "string")
+            return undefined;
+        // An image is never resolved by tag: a tag can be repointed after release.
+        if (!DIGEST_REF.test(runtime) || !DIGEST_REF.test(worker))
+            return undefined;
+        // The Claude Code images are optional, but both or neither, and pinned when present.
+        if (claudeWorker === undefined && claudeToolRunner === undefined)
+            return { runtime, worker };
+        if (typeof claudeWorker !== "string" || typeof claudeToolRunner !== "string")
+            return undefined;
+        if (!DIGEST_REF.test(claudeWorker) || !DIGEST_REF.test(claudeToolRunner))
+            return undefined;
+        return { runtime, worker, claudeWorker, claudeToolRunner };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Where the coding step gets its runtime and worker images: explicit env
+ * overrides, the digest-pinned refs written at release time, or a local build
+ * from a source checkout.
+ */
+export function resolveQuickstartImages(opts) {
+    const { env, packageRoot } = opts;
+    // The Claude pair resolves on its own: both env vars together beat the package pair, and one
+    // image is never taken from the environment and the other from the package.
+    // Blank is unset, as the server reads it (imageVariable).
+    const runtimeImage = imageVariable(env.WARDBY_RUNTIME_IMAGE);
+    const workerImage = imageVariable(env.CODING_WORKER_IMAGE);
+    const claudeWorker = imageVariable(env.CODING_CLAUDE_WORKER_IMAGE);
+    const claudeToolRunner = imageVariable(env.CODING_CLAUDE_TOOL_RUNNER_IMAGE);
+    const envClaude = claudeWorker && claudeToolRunner ? { claudeWorker, claudeToolRunner } : {};
+    if (runtimeImage && workerImage) {
+        return { runtime: runtimeImage, worker: workerImage, ...envClaude, source: "env" };
+    }
+    const pinned = readPackageImages(packageRoot);
+    if (pinned)
+        return { ...pinned, ...envClaude, source: "package" };
+    if (existsSync(join(packageRoot, "deploy", "Dockerfile")) &&
+        existsSync(join(packageRoot, "src", "coding-worker", "Dockerfile"))) {
+        return {
+            runtime: "wardby-runtime:local",
+            worker: "wardby-coding-worker:local",
+            claudeWorker: "wardby-claude-coding-worker:local",
+            claudeToolRunner: "wardby-claude-tool-runner:local",
+            source: "build",
+        };
+    }
+    return {
+        unavailable: "This version of @wardby/cli was published without coding images. Upgrade @wardby/cli, or run quickstart from a clone of the wardby repository.",
+    };
+}