cf-orbs 0.1.0 → 0.2.1

package/README.md

@@ -35,7 +35,7 @@ When Amp pauses an orb, cf-orbs saves the disk as a snapshot and stops the conta
 | You need | Check |
 | --- | --- |
 | Node 22 or later (wrangler 4 needs it) | `node --version` |
-| Docker, running. wrangler builds the orb image on your machine | `docker info` |
+| Docker, running. wrangler builds the orb image on your machine (not for the [Workers Builds path](#install-without-docker-workers-builds-preview)) | `docker info` |
 | A Cloudflare account on **Workers Paid** ($5/month; Containers need it) | Dashboard → Workers & Pages → Plans |
 | wrangler logged in to that account | `npx wrangler login`, then `npx wrangler whoami` |
 | An Amp provider token (`aop_live_…`) | Amp → Settings → Orbs → Add Provider. Note the provider name you type there |
@@ -95,6 +95,38 @@ node cli/bin/cf-orbs.js init ../my-orbs --provider-name <name>   # asks for the
 
 Then use `node <repo>/cli/bin/cf-orbs.js` wherever this README says `cf-orbs`, with `--dir ../my-orbs` or from inside that directory.
 
+### Install without Docker (Workers Builds, preview)
+
+No Docker on your machine? `init --no-deploy` makes a git repo and the Worker with its secrets, but does not deploy. You push the repo to GitHub or GitLab and connect it in the Cloudflare dashboard. Workers Builds then builds both images in your account and deploys on each push. Measured: first build 10.6 min, upgrade 5.6 min, plus 2-4 min in the queue.
+
+```sh
+npx cf-orbs init --no-deploy --provider-name <name from Amp> --token-file <file>
+```
+
+It prints the dashboard settings to use. Full procedure and caveats: [docs/install-workers-builds.md](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md). This is a preview: the default install above (local Docker) and all defaults do not change.
+
+### What init validates
+
+Before the deploy, `init` stops with one `Failed: … — fix: …` line when:
+
+- Node is older than 22.
+- Docker does not answer `docker info` (not checked with `--no-deploy`).
+- wrangler is not logged in, sees no account, or sees several and you gave no `--account-id` (or an id that `wrangler whoami` does not list).
+- There is no Amp token, or it is empty or has spaces (a token without `aop_live_` gives a warning). With `--no-deploy` the token is optional.
+- `cf-orbs.config.jsonc` is not valid: unknown keys, sizes out of range, a bad name or image key.
+- An extra image key has no `image/<key>.Dockerfile`.
+- The account has no workers.dev subdomain and you gave no `--subdomain` (in a terminal, `init` asks for one).
+- `wrangler containers list` fails with a clear plan or login error (Workers Paid is needed). Any other error is a warning.
+
+After the deploy, `init` checks that `/v1/health` answers, that `/v1/status` accepts the control token, that at least one prewarm instance starts from the new image (self-test; skipped when `prewarm` is 0, and with `--no-deploy` until a build has run), and that the provider runs for 15 s with no token rejection and no second provider on the token.
+
+`cf-orbs doctor` also checks the project files, in every mode:
+
+- `image/Dockerfile` (and each extra image key) and the provider image use `FROM <image>@sha256:<digest>`.
+- `debugExec` is `false` (WARN when `true`).
+- No `aop_live_` token and no control token value is in a file that git tracks (SKIP outside a git repo).
+- `--no-deploy` projects only: `.gitignore` keeps out `.cf-orbs/control-token` and `.cf-orbs/state.json`, and `package.json` pins the wrangler version that cf-orbs uses.
+
 ## What you get
 
 - Orbs that run on your Cloudflare account. The repo checkout, build output and saved disks stay there.
@@ -149,7 +181,7 @@ Example: 120 awake hours a month at 20% CPU costs about $27.50 a month in total
 
 | Command | Does |
 | --- | --- |
-| `cf-orbs init [dir]` | Scaffold, deploy and check a provider. Flags: `--provider cloudflare\|external`, `--token-file`, `--account-id`, `--provider-name`, `--subdomain`, `--vcpu <1\|2\|3\|4>` |
+| `cf-orbs init [dir]` | Scaffold, deploy and check a provider. Flags: `--provider cloudflare\|external`, `--token-file`, `--account-id`, `--provider-name`, `--subdomain`, `--vcpu <1\|2\|3\|4>`, `--name <worker>`, `--no-deploy` (preview: [Workers Builds](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md), no Docker) |
 | `cf-orbs status [orb]` | Install status (provider, awake orbs, snapshots), or one orb |
 | `cf-orbs logs <orb>` | Redacted bootstrap log of one orb. `--lines N` (default 200) |
 | `cf-orbs logs --provider` | Redacted provider log (last 20 lines) |
@@ -240,11 +272,11 @@ To report a vulnerability, see [SECURITY.md](https://github.com/meirdick/cf-orbs
 
 ## Status and known gaps
 
-v0.1. The control plane, dispatch program, provider host and CLI are built and unit tested. On 2026-10-30 a real Amp thread ran end to end on a fresh install: spawn from the image, setup, pause with a project snapshot, wake from the snapshot in 2.3 s, first answer 41 s after the message.
+v0.2.1. The control plane, dispatch program, provider host and CLI are built and unit tested. On 2026-10-30 a real Amp thread ran end to end on a fresh install: spawn from the image, setup, pause with a project snapshot, wake from the snapshot in 2.3 s, first answer 41 s after the message.
 
 Known gaps:
 
-- `init` has no orb self-test yet, and no Workers Paid check before the first deploy (a Free account finds out from the deploy error).
+- The plan check before the first deploy is best effort: it asks wrangler to list Containers and stops only on a clear plan or login error. Any other error is a warning, and a Free account may still find out from the deploy error.
 - Paused orbs restore after an image rebuild. A restored disk keeps its old content; new image content reaches only orbs started from the image.
 - Orb lost mid-turn: Amp spawns the orb again and the agent runs the failed tool call again. The disk is kept; running processes and shell state are lost.
 - Not tested yet: the provider's memory on `lite` over 24 h, restore after the source image is deleted from the registry, the Desktop pane, and Docker inside an orb. Snapshot storage has no published price (beta).
@@ -263,6 +295,7 @@ Method, results and costs: [docs/benchmarks.md](https://github.com/meirdick/cf-o
 | Doc | Covers |
 | --- | --- |
 | [AGENTS.md](https://github.com/meirdick/cf-orbs/blob/main/AGENTS.md) | Install guide for an AI agent at a terminal |
+| [Install without Docker](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md) | Preview: Workers Builds builds and deploys from a git repo |
 | [Provider host](https://github.com/meirdick/cf-orbs/blob/main/provider/README.md) | Cloudflare-hosted vs external provider, token rotation |
 | [Orb image](https://github.com/meirdick/cf-orbs/blob/main/image/README.md) | The pinned image, toolchains, why snapshots are tied to it |
 | [Dispatch](https://github.com/meirdick/cf-orbs/blob/main/dispatch/README.md) | The program Amp runs per job, and its protocol |

package/dist/commands/deploy.js

@@ -12,7 +12,8 @@ import { deployWithRetry, lastErrorLine, makeWrangler } from "../wrangler.js";
 export async function deployProject(ctx, input) {
     const { ui, paths } = ctx;
     const { config, state } = input;
-    await materialize(paths, { templates: ctx.templates });
+    const git = state.mode === "git";
+    await materialize(paths, { templates: ctx.templates, git });
     const missing = missingDockerfiles(paths, config);
     if (missing.length > 0) {
         throw new CliError(`image Dockerfile missing: ${missing.join(", ")}`, "create it, or remove its key from images in cf-orbs.config.jsonc");
@@ -38,7 +39,8 @@ export async function deployProject(ctx, input) {
         ...state,
         url,
         workerName: config.name,
-        mode: config.providerHost,
+        // git mode stays git mode: Workers Builds still deploys from the repo
+        mode: git ? "git" : config.providerHost,
         deployedAt: new Date(ctx.now()).toISOString(),
         cliVersion: await cliVersion(),
     });

package/dist/commands/doctor.js

@@ -1,9 +1,11 @@
-// cf-orbs doctor: PASS/FAIL per check with a one-line fix, plus INFO hints that never fail. Read-only: never starts a provider or an orb.
+// cf-orbs doctor: PASS/FAIL per check with a one-line fix, plus INFO hints and WARN lines that never fail.
+// Read-only: never starts a provider or an orb.
 import { existsSync } from "node:fs";
 import { collectImageKeys, expectOk, providerInfo } from "../api.js";
 import { CONFIG_FILE, loadConfig, orbImageKeys } from "../config.js";
 import { connect } from "../connect.js";
 import { CliError, toFailedLine } from "../errors.js";
+import { fileChecks } from "../file-checks.js";
 import { fileMode, readState } from "../project.js";
 import { classifyDeployFailure, lastErrorLine, makeWrangler } from "../wrangler.js";
 import { AMP_CACHE_HINT } from "./snapshots.js";
@@ -77,6 +79,10 @@ export async function runDoctor(ctx) {
     }
     else
         checks.push(pass("control token", "present, mode 600"));
+    checks.push(...(await fileChecks(ctx.run, ctx.paths, config, {
+        git: state.mode === "git",
+        templates: ctx.templates,
+    })));
     const name = config?.name ?? state.workerName ?? "cf-orbs";
     const w = makeWrangler(ctx.run, { accountId: state.accountId });
     const d = await w.run(["deployments", "list", "--json", "--name", name], { timeoutMs: 60_000 });
@@ -106,20 +112,24 @@ export async function runDoctor(ctx) {
         checks.push(failed("health", e));
     }
     let status;
+    // git mode: Workers Builds deploys, so the fix is the build, not cf-orbs deploy
+    const apiFailed = (n, e) => state.mode === "git" && e instanceof CliError
+        ? failed(n, new CliError(e.cause_, `wait for the Workers Builds build to finish (Workers & Pages → ${name} → Deployments), or open its build log`))
+        : failed(n, e);
     if (api) {
         try {
             expectOk(await api.get("/v1/health"), "health");
             checks.push(pass("health", `${api.url}/v1/health ok`));
         }
         catch (e) {
-            checks.push(failed("health", e));
+            checks.push(apiFailed("health", e));
         }
         try {
             status = expectOk(await api.get("/v1/status"), "status");
             checks.push(pass("status", "/v1/status ok (control token accepted)"));
         }
         catch (e) {
-            checks.push(failed("status", e));
+            checks.push(apiFailed("status", e));
         }
     }
     // Names only: wrangler secret list never returns values.

package/dist/commands/init.js

@@ -1,18 +1,24 @@
 // cf-orbs init [dir]: zero to a live provider. plan() is pure (options + probes → steps); runInit() executes.
 // Re-runnable: reuses the control token, keeps the Amp token secret when none is given, keeps user files.
+// --no-deploy (git mode): no Docker, no deploy. Scaffold a repo for Workers Builds, create the Worker with its
+// secrets, print the dashboard steps. Workers Builds then builds the images and deploys on each push.
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { expectOk, makeApi, providerInfo } from "../api.js";
 import { flagBool, flagString } from "../args.js";
 import { CONFIG_FILE, findTopLevelValue, instanceForVcpu, loadConfig, setTopLevelJsonc, } from "../config.js";
 import { CliError, registerSecret } from "../errors.js";
+import { filesWithSecrets, gitTrackedFiles } from "../file-checks.js";
 import { dockerOk, nodeMajor, whoami } from "../probes.js";
-import { generateToken, materialize, readControlToken, readState, writeControlToken, writeState, } from "../project.js";
+import { cliVersion, GIT_DEPLOY_COMMAND, generateToken, gitPackageJson, materialize, missingDockerfiles, readControlToken, readState, withSecretsFile, writeControlToken, writeState, writeWranglerConfig, } from "../project.js";
 import { checkSubdomain, registerSubdomain, suggestSubdomain, wranglerBearer } from "../subdomain.js";
 import { ask, askHidden } from "../ui.js";
-import { makeWrangler } from "../wrangler.js";
+import { classifyDeployFailure, deployFailureError, lastErrorLine, makeWrangler, WRANGLER_PIN, } from "../wrangler.js";
 import { deployProject, startPrewarm } from "./deploy.js";
 export const PROVIDER_WAIT_MS = 90_000;
+/** How long init waits for the prewarm instances (a first start on a cold host pulls the image). */
+export const SELFTEST_WAIT_MS = 180_000;
 /** Provider must stay up this long with no reject, no second-provider line and no restart. */
 export const PROVIDER_STABLE_MS = 15_000;
 const CRON_PERIOD_MS = 5 * 60_000;
@@ -29,7 +35,13 @@ export function plan(o, p) {
             error: new CliError(`Node ${p.nodeVersion} is too old; cf-orbs needs Node 22 or later`, "install Node 22+ (https://nodejs.org) and rerun"),
         });
     }
-    if (!p.docker) {
+    if (o.noDeploy && o.mode === "external") {
+        fails.push({
+            kind: "fail",
+            error: new CliError("--no-deploy supports only --provider cloudflare", "drop --provider external, or run cf-orbs init --provider external without --no-deploy"),
+        });
+    }
+    if (!p.docker && !o.noDeploy) {
         fails.push({
             kind: "fail",
             error: new CliError("Docker is not running (wrangler builds the orb image locally)", "start Docker Desktop or the docker daemon, check `docker info`, then rerun"),
@@ -80,7 +92,17 @@ export function plan(o, p) {
         }
     }
     let ampSource;
-    if (o.mode === "cloudflare") {
+    const hadProvider = p.prevMode === "cloudflare" || p.prevMode === "git";
+    if (o.noDeploy) {
+        // the Amp token is optional here: set it now or later, the Worker starts the provider once it has one
+        if (o.tokenFile)
+            ampSource = "file";
+        else if (p.envToken)
+            ampSource = "env";
+        else if (interactive)
+            ampSource = "prompt";
+    }
+    else if (o.mode === "cloudflare") {
         if (o.tokenFile)
             ampSource = "file";
         else if (p.envToken)
@@ -88,7 +110,7 @@ export function plan(o, p) {
         else if (interactive)
             ampSource = "prompt";
         // Keep only a secret that exists: external mode deletes it from the Worker.
-        else if (p.deployed && p.prevMode === "cloudflare")
+        else if (p.deployed && hadProvider)
             ampSource = "keep";
         else if (p.deployed) {
             fails.push({
@@ -105,15 +127,24 @@ export function plan(o, p) {
     }
     if (fails.length > 0)
         return fails;
-    const steps = [account, { kind: "scaffold", mode: o.mode }];
+    const steps = [
+        account,
+        { kind: "plan-check" },
+        { kind: "scaffold", mode: o.mode, git: Boolean(o.noDeploy) },
+    ];
     steps.push({ kind: "control-token", action: p.hasControlToken ? "reuse" : "generate" });
     if (ampSource)
         steps.push({ kind: "amp-token", source: ampSource });
+    if (o.noDeploy) {
+        steps.push({ kind: "subdomain" }, { kind: "git-files" }, { kind: "git-secrets" }, { kind: "selftest" }, { kind: "git-next" });
+        steps.push({ kind: "done", command: helloCommand(o.providerName) });
+        return steps;
+    }
     const secrets = ["CONTROL_TOKEN"];
     // "prompt" may still end as keep (Enter on a re-run); the executor drops the secret then.
     if (ampSource && ampSource !== "keep")
         secrets.push("AMP_ORB_PROVIDER_TOKEN");
-    steps.push({ kind: "subdomain" }, { kind: "deploy", secrets }, { kind: "health" }, { kind: "status" });
+    steps.push({ kind: "subdomain" }, { kind: "deploy", secrets }, { kind: "health" }, { kind: "status" }, { kind: "selftest" });
     if (o.mode === "cloudflare") {
         steps.push({ kind: "start-provider" }, { kind: "wait-provider", timeoutMs: PROVIDER_WAIT_MS });
     }
@@ -122,9 +153,10 @@ export function plan(o, p) {
     steps.push({ kind: "done", command: helloCommand(o.providerName) });
     return steps;
 }
-export async function gatherProbes(ctx) {
+/** noDeploy: git mode needs no Docker, so the probe is skipped. */
+export async function gatherProbes(ctx, o = {}) {
     const [docker, who, ct, state] = await Promise.all([
-        dockerOk(ctx.run),
+        o.noDeploy ? false : dockerOk(ctx.run),
         whoami(ctx.run),
         readControlToken(ctx.paths),
         readState(ctx.paths),
@@ -150,6 +182,41 @@ function checkAmpToken(ctx, t) {
     registerSecret(t);
     return t;
 }
+function warmLast(body) {
+    const b = (body && typeof body === "object" ? body : {});
+    return (b.last && typeof b.last === "object" ? b.last : {});
+}
+/** One finished prewarm run: ok > 0 passes, ok = 0 fails init. */
+function reportSelftest(ui, view) {
+    const count = Number(view.count) || 0;
+    const ok = Number(view.ok) || 0;
+    const ms = Array.isArray(view.msPerInstance) ? view.msPerInstance : [];
+    if (ok === 0) {
+        const jobs = Array.isArray(view.jobs) ? view.jobs : [];
+        const why = jobs.find((j) => typeof j.error === "string")?.error;
+        throw new CliError(`orb self-test failed: no instance started from the new image${why ? ` (${String(why)})` : ""}`, "run cf-orbs logs --provider and cf-orbs status, check the image build, then run cf-orbs deploy");
+    }
+    const t = ms.length > 0 ? ` in ${ms.map((m) => `${(m / 1000).toFixed(0)} s`).join(" and ")}` : "";
+    if (ok < count)
+        ui.warn(`self-test: only ${ok} of ${count} instances started${t}`);
+    else
+        ui.step(`self-test: orb image starts (${ok} of ${count} ready${t})`);
+}
+/** --no-deploy: the last prewarm run of an already built Worker, or undefined. Never throws. */
+async function lastPrewarm(url, token, ctx) {
+    if (!url || !token)
+        return undefined;
+    try {
+        const r = await makeApi(url, token, ctx.fetch).get("/v1/warm");
+        if (r.status !== 200)
+            return undefined;
+        const last = warmLast(r.body);
+        return typeof last.at === "string" ? last : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function runInit(ctx, o, steps) {
     const { ui, paths } = ctx;
     let state = await readState(paths);
@@ -165,6 +232,11 @@ export async function runInit(ctx, o, steps) {
     let providerStartedByCron = false;
     let accountName;
     let providerName = o.providerName;
+    let prewarmStarted = -1;
+    let prewarmAt = 0;
+    let subdomain;
+    let repoExisted = false;
+    let git;
     // Show every failed precondition in one run, not one per rerun.
     const fails = steps.filter((s) => s.kind === "fail");
     for (const f of fails.slice(0, -1))
@@ -197,6 +269,7 @@ export async function runInit(ctx, o, steps) {
                     break; // unknown auth type: wrangler deploy reports a missing subdomain itself
                 const c = await checkSubdomain(ctx.fetch, accountId, bearer);
                 if (c.kind === "has") {
+                    subdomain = c.subdomain;
                     ui.step(`workers.dev subdomain: ${c.subdomain}`);
                     break;
                 }
@@ -211,6 +284,7 @@ export async function runInit(ctx, o, steps) {
                     name = (await ask(`This account has no workers.dev subdomain. Name for it [${def}]: `)) || def;
                 }
                 await registerSubdomain(ctx.fetch, accountId, bearer, name);
+                subdomain = name;
                 ui.step(`workers.dev subdomain: registered ${name}.workers.dev`);
                 break;
             }
@@ -218,6 +292,7 @@ export async function runInit(ctx, o, steps) {
                 const r = await materialize(paths, {
                     templates: ctx.templates,
                     configOverrides: { providerHost: s.mode },
+                    git: s.git,
                 });
                 if (r.wroteConfig)
                     ui.step(`scaffold: wrote ${CONFIG_FILE}`);
@@ -231,6 +306,11 @@ export async function runInit(ctx, o, steps) {
                     config = await loadConfig(paths.config);
                     ui.step(`scaffold: providerHost set to ${s.mode}`);
                 }
+                if (o.name !== undefined && config.name !== o.name) {
+                    await writeFile(paths.config, setTopLevelJsonc(await readFile(paths.config, "utf8"), "name", o.name));
+                    config = await loadConfig(paths.config);
+                    ui.step(`scaffold: name set to ${o.name}`);
+                }
                 // --vcpu overwrites "instance"; without it a re-run keeps what the config has
                 if (o.vcpu !== undefined && !sameInstance(config.instance, instanceForVcpu(o.vcpu))) {
                     const t = await readFile(paths.config, "utf8");
@@ -238,7 +318,13 @@ export async function runInit(ctx, o, steps) {
                     config = await loadConfig(paths.config);
                     ui.step(`scaffold: instance set to ${o.vcpu} vCPU, ${o.vcpu * 3} GiB, 20 GB disk`);
                 }
-                state = { ...state, accountId, providerName: o.providerName, mode: s.mode, workerName: config.name };
+                state = {
+                    ...state,
+                    accountId,
+                    providerName: o.providerName,
+                    mode: s.git ? "git" : s.mode,
+                    workerName: config.name,
+                };
                 await writeState(paths, state);
                 break;
             }
@@ -263,9 +349,16 @@ export async function runInit(ctx, o, steps) {
                 }
                 else if (s.source === "prompt") {
                     // Keep only a secret that exists: external mode deleted it from the Worker.
-                    const keep = Boolean(state.url) && prevMode === "cloudflare";
-                    const t = await askHidden(`Amp provider token (aop_live_…, not shown)${keep ? "; Enter keeps the current one" : ""}: `);
-                    if (t === "" && keep)
+                    const keep = Boolean(state.url) && (prevMode === "cloudflare" || prevMode === "git");
+                    const enter = o.noDeploy
+                        ? "; Enter skips (set it later)"
+                        : keep
+                            ? "; Enter keeps the current one"
+                            : "";
+                    const t = await askHidden(`Amp provider token (aop_live_…, not shown)${enter}: `);
+                    if (t === "" && o.noDeploy)
+                        ui.step("amp token: not given; set it later (see the steps below)");
+                    else if (t === "" && keep)
                         ui.step("amp token: keeping the current Worker secret");
                     else
                         ampToken = checkAmpToken(ctx, t);
@@ -320,8 +413,69 @@ export async function runInit(ctx, o, steps) {
                 lastStatus = expectOk(await api.get("/v1/status"), "status check");
                 ui.step("health: /v1/status ok (control token accepted)");
                 if (config)
-                    await startPrewarm(ctx, api, config);
+                    prewarmStarted = (await startPrewarm(ctx, api, config)).started;
+                prewarmAt = ctx.now();
                 break;
+            case "selftest": {
+                if (o.noDeploy) {
+                    // Workers Builds deploys later, so this run started no prewarm. Report an earlier run if the
+                    // Worker has one (a rerun after a build); else skip.
+                    const last = await lastPrewarm(url, controlToken, ctx);
+                    if (last && Number(last.pending) === 0 && Number(last.count) > 0) {
+                        // an old failed run does not fail init: the next build may fix the image
+                        if (Number(last.ok) > 0)
+                            reportSelftest(ui, last);
+                        else
+                            ui.warn("self-test: the last prewarm run started no instance; check the build, then cf-orbs status");
+                    }
+                    else
+                        ui.step("self-test: skipped (Workers Builds deploys later; after the first build, cf-orbs status shows the prewarm result)");
+                    break;
+                }
+                // The prewarm run starts throwaway orbs from the new image. If one becomes ready, the image,
+                // the registry and the container runtime work. No Amp thread and no debug route needed.
+                if (prewarmStarted === 0) {
+                    ui.step('self-test: skipped (no prewarm instance was started; set "prewarm" above 0 to enable)');
+                    break;
+                }
+                const until = ctx.now() + SELFTEST_WAIT_MS;
+                let view = {};
+                for (;;) {
+                    const r = await api.get("/v1/warm");
+                    const last = warmLast(r.body);
+                    // Ignore the result of an earlier run.
+                    if (typeof last.at === "string" && Date.parse(last.at) >= prewarmAt - 10_000) {
+                        view = last;
+                        if (Number(last.pending) === 0)
+                            break;
+                    }
+                    if (ctx.now() >= until)
+                        break;
+                    await ctx.sleep(3_000);
+                }
+                if (Number(view.count) > 0 && Number(view.pending) === 0)
+                    reportSelftest(ui, view);
+                else
+                    ui.warn("self-test: still running after 3 min; the first start on a new host pulls the image. Check cf-orbs status");
+                break;
+            }
+            case "plan-check": {
+                // Before the image build: a Free account fails here in seconds, not after a 1.8 GB push.
+                // Best effort: only a clear plan or login error stops init; any other error is a warning.
+                const r = await makeWrangler(ctx.run, { accountId }).run(["containers", "list", "--json"], {
+                    timeoutMs: 60_000,
+                });
+                if (r.code === 0) {
+                    ui.step("plan: Containers are available on this account");
+                    break;
+                }
+                const out = `${r.stdout}\n${r.stderr}`;
+                const kind = classifyDeployFailure(out);
+                if (kind === "paid" || kind === "auth")
+                    throw deployFailureError(kind, out);
+                ui.warn(`plan check skipped (wrangler containers list failed: ${lastErrorLine(out)})`);
+                break;
+            }
             case "start-provider": {
                 const r = await api.post("/v1/provider/start");
                 if (r.status === 404 || r.status === 405) {
@@ -365,6 +519,52 @@ export async function runInit(ctx, o, steps) {
                 }
                 break;
             }
+            case "git-files": {
+                if (!config)
+                    throw new Error("init plan bug: git-files before scaffold");
+                const missing = missingDockerfiles(paths, config);
+                if (missing.length > 0)
+                    throw new CliError(`image Dockerfile missing: ${missing.join(", ")}`, "create it, or remove its key from images in cf-orbs.config.jsonc");
+                await writeWranglerConfig(paths, config, accountId);
+                ui.step("git: wrote .cf-orbs/wrangler.jsonc (Workers Builds deploys with it)");
+                if (!existsSync(paths.packageJson)) {
+                    await writeFile(paths.packageJson, gitPackageJson(config.name, WRANGLER_PIN));
+                    ui.step(`git: wrote package.json (wrangler ${WRANGLER_PIN} for Workers Builds)`);
+                }
+                await writeLockfile(ctx);
+                repoExisted = await gitCommitNew(ctx, ampToken);
+                break;
+            }
+            case "git-secrets": {
+                if (!config || !controlToken)
+                    throw new Error("init plan bug: git-secrets before scaffold");
+                const secrets = { CONTROL_TOKEN: controlToken };
+                if (ampToken)
+                    secrets.AMP_ORB_PROVIDER_TOKEN = ampToken;
+                await putSecrets(ctx, config.name, accountId, secrets);
+                url = subdomain ? `https://${config.name}.${subdomain}.workers.dev` : state.url;
+                if (!url)
+                    ui.warn("Failed: could not read the account's workers.dev subdomain, so state.json has no URL — fix: after the first build, pass --url https://<name>.<subdomain>.workers.dev to status and doctor");
+                state = {
+                    ...state,
+                    url,
+                    accountId,
+                    mode: "git",
+                    workerName: config.name,
+                    cliVersion: await cliVersion(),
+                };
+                await writeState(paths, state);
+                break;
+            }
+            case "git-next":
+                git = gitNext({
+                    worker: config?.name ?? "cf-orbs",
+                    repoExisted,
+                    ampTokenGiven: Boolean(ampToken),
+                });
+                for (const l of git.lines)
+                    ui.out(l);
+                break;
             case "print-external-env":
                 ui.out("External provider mode. On an always-on host with the amp CLI, run:");
                 ui.out("  export AMP_ORB_PROVIDER_TOKEN=<your aop_live_ token>");
@@ -379,7 +579,123 @@ export async function runInit(ctx, o, steps) {
                 break;
         }
     }
-    return { url, command, providerName };
+    return { url, command, providerName, ...(git ? { git } : {}) };
+}
+/** Workers Builds settings for the dashboard (Settings → Builds → Connect), as tested on 2026-11-02. */
+export const GIT_PATH_FILTERS = ["image/**", ".cf-orbs/**", "cf-orbs.config.jsonc", "package*.json"];
+/** The next steps init --no-deploy prints. Pure. */
+export function gitNext(o) {
+    const settings = {
+        worker: o.worker,
+        branch: "main",
+        buildCommand: "",
+        deployCommand: GIT_DEPLOY_COMMAND,
+        rootDirectory: "/",
+        previews: false,
+        apiToken: "default build token",
+        buildWatchPaths: GIT_PATH_FILTERS,
+    };
+    const push = o.repoExisted
+        ? [
+            "1. Commit these files, then push the repo to GitHub or GitLab:",
+            "     git add -A && git commit -m 'cf-orbs init'",
+            "     git push",
+        ]
+        : [
+            "1. Make an empty repo on GitHub or GitLab. Push this directory to it:",
+            "     git remote add origin <repo URL>",
+            "     git push -u origin main",
+        ];
+    const lines = [
+        "",
+        "Next steps. Workers Builds builds the images in your Cloudflare account; this machine needs no Docker.",
+        ...push,
+        `2. Connect the repo: Cloudflare dashboard → Workers & Pages → ${o.worker} → Settings → Builds → Connect.`,
+        "     Repository:         the repo from step 1",
+        `     Branch:             ${settings.branch}${o.repoExisted ? " (the branch you push)" : ""}`,
+        "     Build command:      (leave empty)",
+        `     Deploy command:     ${settings.deployCommand}`,
+        `     Root directory:     ${settings.rootDirectory}`,
+        "     Previews (builds for non-production branches): off",
+        "     API token:          the default build token",
+        `     Build watch paths:  include ${settings.buildWatchPaths.join(", ")}`,
+        "   If no build starts, push a commit. Measured: first build 10.6 min, plus 2-4 min in the queue.",
+        "3. After the first build: cf-orbs status",
+        "   The 5-min cron starts the provider. The first spawn on each host pulls the image (40-50 s).",
+        ...(o.ampTokenGiven
+            ? []
+            : [
+                "4. No Amp token given. If the Worker has none yet, set it with:",
+                "     cf-orbs init --no-deploy --token-file <file>   (no build needed)",
+            ]),
+        "Upgrades: edit image/Dockerfile or cf-orbs.config.jsonc (or cf-orbs upgrade --digest sha256:<hex> --no-deploy), commit, push.",
+        "Docs: https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md",
+        "Then try it (spends Amp credits):",
+    ];
+    return { settings, lines };
+}
+/** package-lock.json for npm clean-install in Workers Builds. A failure is one warning. */
+async function writeLockfile(ctx) {
+    const { paths, ui } = ctx;
+    if (existsSync(join(paths.dir, "package-lock.json")))
+        return;
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    const r = await ctx.run(npm, ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], {
+        cwd: paths.dir,
+        timeoutMs: 180_000,
+    });
+    if (r.code === 0)
+        ui.step("git: wrote package-lock.json");
+    else
+        ui.warn(`Failed: could not write package-lock.json (${lastErrorLine(`${r.stdout}\n${r.stderr}`)}) — fix: run npm install --package-lock-only in ${paths.dir}, then commit it`);
+}
+/**
+ * git init + first commit when dir is in no git work tree. Returns true when a repo was there already.
+ * Checks the staged files for tokens before the commit.
+ */
+async function gitCommitNew(ctx, ampToken) {
+    const { paths, ui } = ctx;
+    const g = (args) => ctx.run("git", ["-C", paths.dir, ...args], { timeoutMs: 60_000 });
+    if ((await g(["rev-parse", "--is-inside-work-tree"])).code === 0) {
+        ui.step("git: this directory is in a git repo already; commit and push the changes yourself");
+        return true;
+    }
+    const init = await g(["init", "-b", "main"]);
+    if (init.code !== 0) {
+        ui.warn(`Failed: git init did not run (${lastErrorLine(`${init.stdout}\n${init.stderr}`)}) — fix: install git, then run git init -b main && git add -A && git commit -m 'cf-orbs init' in ${paths.dir}`);
+        return false;
+    }
+    await g(["add", "-A"]);
+    const ct = await readControlToken(paths);
+    const staged = (await gitTrackedFiles(ctx.run, paths.dir)) ?? [];
+    const hits = await filesWithSecrets(paths.dir, staged, [
+        ...(ct ? [ct] : []),
+        ...(ampToken ? [ampToken] : []),
+    ]);
+    if (hits.length > 0) {
+        await g(["reset", "-q"]);
+        throw new CliError(`a token is in file(s) staged for the first commit: ${hits.join(", ")}`, "remove the token from those files (or add them to .gitignore), then rerun cf-orbs init --no-deploy");
+    }
+    const c = await g(["commit", "-q", "-m", "cf-orbs init (Workers Builds)"]);
+    if (c.code === 0)
+        ui.step(`git: made a repo on branch main with a first commit (${staged.length} files)`);
+    else
+        ui.warn(`Failed: git commit did not run (${lastErrorLine(`${c.stdout}\n${c.stderr}`)}) — fix: set git config user.name and user.email, then git commit -m 'cf-orbs init' in ${paths.dir}`);
+    return false;
+}
+/** wrangler secret bulk from a 0600 temp file. Creates the Worker (a placeholder) when it does not exist. */
+async function putSecrets(ctx, name, accountId, secrets) {
+    const w = makeWrangler(ctx.run, { configPath: ctx.paths.wrangler, accountId });
+    const r = await withSecretsFile(secrets, (file) => w.run(["secret", "bulk", file], { env: { CI: "1" }, timeoutMs: 120_000 }));
+    const out = `${r.stdout}\n${r.stderr}`;
+    if (r.code !== 0 || /Secrets failed to upload|No content found/i.test(out)) {
+        throw classifyDeployFailure(out) === "auth"
+            ? new CliError("wrangler is not logged in or the token lacks permissions", "run npx wrangler login, then rerun")
+            : new CliError(`wrangler secret bulk failed: ${lastErrorLine(out)}`, "check npx wrangler whoami, then rerun cf-orbs init --no-deploy");
+    }
+    if (/Creating new Worker/i.test(out))
+        ctx.ui.step(`worker: created ${name} (a placeholder until the first build)`);
+    ctx.ui.step(`secrets: set ${Object.keys(secrets).join(" and ")} on Worker ${name}`);
 }
 /**
  * Read the provider log tail from /v1/status. Only lines since the last container start count.
@@ -425,16 +741,22 @@ export function parseVcpuFlag(v) {
         throw new CliError(`--vcpu must be 1, 2, 3 or 4, got ${JSON.stringify(v)}`, "pass --vcpu 4 (default, 12 GiB) or --vcpu 2 (6 GiB, about half the cost)");
     return Number(v);
 }
+const WORKER_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
 export function initOptions(ctx, existing) {
     const modeFlag = flagString(ctx.args, "provider");
     if (modeFlag !== undefined && modeFlag !== "cloudflare" && modeFlag !== "external") {
         throw new CliError(`--provider must be cloudflare or external, got ${modeFlag}`, "pass --provider cloudflare (default) or --provider external");
     }
+    const name = flagString(ctx.args, "name");
+    if (name !== undefined && !WORKER_NAME_RE.test(name))
+        throw new CliError(`--name ${JSON.stringify(name)} is not a valid Worker name (a-z, 0-9, -; max 63)`, "pass --name cf-orbs or another lowercase name");
     const explicitName = flagString(ctx.args, "provider-name") ?? ctx.env.AMP_ORB_PROVIDER_NAME ?? existing?.providerName;
     return {
         providerNameExplicit: explicitName !== undefined,
         subdomain: flagString(ctx.args, "subdomain") ?? ctx.env.CF_ORBS_SUBDOMAIN ?? undefined,
         vcpu: parseVcpuFlag(flagString(ctx.args, "vcpu")),
+        name,
+        noDeploy: flagBool(ctx.args, "no-deploy"),
         mode: modeFlag ?? existing?.providerHost ?? "cloudflare",
         nonInteractive: flagBool(ctx.args, "non-interactive") || Boolean(ctx.env.CI),
         tokenFile: flagString(ctx.args, "token-file"),
@@ -455,11 +777,23 @@ export async function initCommand(ctx) {
     }
     existing.providerName = (await readState(paths)).providerName;
     const o = initOptions(ctx, existing);
-    ui.step(`cf-orbs init in ${paths.dir} (provider host: ${o.mode})`);
-    const probes = await gatherProbes(ctx);
+    ui.step(`cf-orbs init in ${paths.dir} (provider host: ${o.mode}${o.noDeploy ? "; --no-deploy: Workers Builds deploys" : ""})`);
+    const probes = await gatherProbes(ctx, o);
     const steps = plan(o, probes);
     const r = await runInit(ctx, o, steps);
-    ui.result({ ok: true, url: r.url, mode: o.mode, providerName: r.providerName, next: r.command });
+    if (r.git)
+        ui.result({
+            ok: true,
+            mode: "git",
+            providerHost: o.mode,
+            url: r.url,
+            providerName: r.providerName,
+            settings: r.git.settings,
+            steps: r.git.lines.filter((l) => l !== ""),
+            next: r.command,
+        });
+    else
+        ui.result({ ok: true, url: r.url, mode: o.mode, providerName: r.providerName, next: r.command });
     if (r.command)
         ui.out(r.command);
     return 0;

package/dist/commands/upgrade.js

@@ -8,7 +8,7 @@ import { makeApi } from "../api.js";
 import { flagBool, flagString } from "../args.js";
 import { AMP_DEFAULT_IMAGE_REPO, CONFIG_FILE, loadConfig, parseConfigText, setTopLevelJsonc, } from "../config.js";
 import { CliError } from "../errors.js";
-import { readState, requireControlToken } from "../project.js";
+import { materialize, readState, requireControlToken, writeWranglerConfig } from "../project.js";
 import { deployProject, restartProviderAfterDeploy, startPrewarm } from "./deploy.js";
 import { AMP_CACHE_STEPS } from "./snapshots.js";
 const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
@@ -73,7 +73,16 @@ export async function upgradeCommand(ctx) {
     ui.warn("paused orbs may not restore after upgrade (their snapshots name image key orb, which is now the new image); push or commit their work first");
     ui.warn("awake orbs keep the old Worker code until they pause; keep the old key until their snapshots expire (30 days)");
     if (flagBool(ctx.args, "no-deploy")) {
-        ui.out("Run cf-orbs deploy to build and push the new image.");
+        const state = await readState(paths);
+        if (state.mode === "git") {
+            // Workers Builds deploys the committed wrangler.jsonc, so write it now with the new images entry
+            await materialize(paths, { templates: ctx.templates, git: true });
+            await writeWranglerConfig(paths, await loadConfig(paths.config), state.accountId);
+            ui.step("upgrade: wrote .cf-orbs/wrangler.jsonc");
+        }
+        ui.out(state.mode === "git"
+            ? "Commit and push: Workers Builds builds and deploys the new image."
+            : "Run cf-orbs deploy to build and push the new image.");
         for (const l of AMP_CACHE_STEPS)
             ui.out(l);
         ui.result({ ok: true, changed: true, deployed: false, oldKey: p.oldKey, nextSteps: AMP_CACHE_STEPS });

package/dist/file-checks.js

@@ -0,0 +1,194 @@
+// Checks on the project files: image pins, debugExec, secrets in tracked files, git mode files.
+// Used by doctor (all modes) and by init --no-deploy before its first commit. Read-only.
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_FILE } from "./config.js";
+import { CliError, toFailedLine } from "./errors.js";
+import { readControlToken, templatesDir } from "./project.js";
+import { WRANGLER_PIN } from "./wrangler.js";
+const pass = (name, detail) => ({ name, status: "PASS", detail });
+const failed = (name, e) => ({ name, status: "FAIL", detail: toFailedLine(e) });
+const skip = (name, detail) => ({ name, status: "SKIP", detail });
+const DIGEST_REF = /@sha256:[0-9a-f]{64}$/;
+/** Base image refs in a Dockerfile that have no @sha256 digest. Earlier stage names and scratch are fine. */
+export function unpinnedFroms(dockerfile) {
+    const stages = new Set(["scratch"]);
+    const out = [];
+    for (const line of dockerfile.split(/\r?\n/)) {
+        const m = /^\s*FROM\s+(.+)$/i.exec(line);
+        if (!m)
+            continue;
+        const words = m[1].trim().split(/\s+/);
+        const ref = words.find((w) => !w.startsWith("--"));
+        if (!ref)
+            continue;
+        const known = stages.has(ref.toLowerCase());
+        const as = words.findIndex((w) => w.toLowerCase() === "as");
+        if (as !== -1 && words[as + 1])
+            stages.add(words[as + 1].toLowerCase());
+        if (!known && !DIGEST_REF.test(ref))
+            out.push(ref);
+    }
+    return out;
+}
+/** "<repo>@sha256:0123456789ab" for a PASS line. */
+function shortRefs(dockerfile) {
+    const refs = [...dockerfile.matchAll(/^\s*FROM\s+(?:--\S+\s+)*(\S+)/gim)].map((m) => m[1].replace(/@sha256:([0-9a-f]{12})[0-9a-f]{52}$/, "@sha256:$1…"));
+    return refs.join(", ");
+}
+async function pinCheck(name, file, label, fix) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return failed(name, new CliError(`${label} not found`, "run cf-orbs init in this directory"));
+    }
+    const bad = unpinnedFroms(text);
+    if (bad.length > 0)
+        return failed(name, new CliError(`${label} FROM ${bad.join(", ")} has no @sha256 digest`, fix));
+    return pass(name, `${label} FROM ${shortRefs(text)} (by digest)`);
+}
+/** image/Dockerfile and the Dockerfile of every extra image key: each FROM is pinned by digest. */
+export async function orbImagePinCheck(p, c) {
+    const keys = [...new Set(Object.values(c?.images ?? {}))];
+    const files = [
+        ["image/Dockerfile", p.imageDockerfile],
+        ...keys.map((k) => [`image/${k}.Dockerfile`, join(p.imageDir, `${k}.Dockerfile`)]),
+    ];
+    const fix = "pin the base image as <image>@sha256:<digest> (for the Amp image: cf-orbs upgrade --digest sha256:<hex>)";
+    let first;
+    let extra = 0;
+    for (const [label, file] of files) {
+        if (label !== "image/Dockerfile" && !existsSync(file))
+            continue; // deploy reports a missing one
+        const c1 = await pinCheck("orb image pin", file, label, fix);
+        if (c1.status === "FAIL")
+            return c1;
+        if (first)
+            extra++;
+        first ??= c1;
+    }
+    return extra > 0 && first
+        ? { ...first, detail: `${first.detail}; ${extra} extra image key(s) pinned too` }
+        : first;
+}
+/** The provider image cf-orbs builds: the project copy (.cf-orbs/provider) if there is one, else the template. */
+export async function providerImagePinCheck(p, templates = templatesDir()) {
+    const copy = join(p.stateDir, "provider", "Dockerfile");
+    const tpl = join(templates, "provider", "Dockerfile");
+    // In a source checkout the templates are synced at build time; before that, read the source file.
+    const src = join(templates, "..", "..", "provider", "Dockerfile");
+    const [file, label] = existsSync(copy)
+        ? [copy, ".cf-orbs/provider/Dockerfile"]
+        : [existsSync(tpl) || !existsSync(src) ? tpl : src, "provider/Dockerfile (CLI template)"];
+    return pinCheck("provider image pin", file, label, "reinstall cf-orbs (the provider image is a CLI template), then cf-orbs deploy");
+}
+/** debugExec lets the control token run commands in orbs. WARN, never FAIL: the substrate bench needs it. */
+export function debugExecCheck(c, git) {
+    if (!c)
+        return skip("debugExec", "needs a valid config");
+    if (!c.debugExec)
+        return pass("debugExec", "false (the control token cannot run commands in orbs)");
+    const then = git ? "commit and push" : "run cf-orbs deploy";
+    return {
+        name: "debugExec",
+        status: "WARN",
+        detail: toFailedLine(new CliError("debugExec is true: whoever has the control token can run any command in any orb", `set "debugExec": false in ${CONFIG_FILE}, then ${then} (keep it on only for the substrate bench)`)),
+    };
+}
+const AOP_TOKEN = /aop_live_[A-Za-z0-9_-]{8,}/;
+const MAX_SCAN_BYTES = 10_000_000;
+/**
+ * Files (relative to dir) that hold an Amp provider token or one of the given secret values.
+ * Never returns the values. Skips files over 10 MB.
+ */
+export async function filesWithSecrets(dir, files, values) {
+    const hits = [];
+    const vals = values.filter((v) => v.length >= 8);
+    for (const f of files) {
+        const path = join(dir, f);
+        try {
+            if ((await stat(path)).size > MAX_SCAN_BYTES)
+                continue;
+            const text = await readFile(path, "latin1");
+            if (AOP_TOKEN.test(text) || vals.some((v) => text.includes(v)))
+                hits.push(f);
+        }
+        catch { }
+    }
+    return hits;
+}
+/** `git ls-files` of dir, or undefined when dir is not in a git work tree (or git is missing). */
+export async function gitTrackedFiles(run, dir) {
+    const r = await run("git", ["-C", dir, "ls-files", "-z"], { timeoutMs: 30_000 });
+    if (r.code !== 0)
+        return undefined;
+    return r.stdout.split("\0").filter(Boolean);
+}
+/** No aop_live_ token and no control token value in a file git tracks. SKIP outside a git work tree. */
+export async function trackedSecretsCheck(run, p, extra = []) {
+    const name = "secrets in git";
+    const files = await gitTrackedFiles(run, p.dir);
+    if (!files)
+        return skip(name, "not a git repository");
+    const ct = await readControlToken(p);
+    const hits = await filesWithSecrets(p.dir, files, [...(ct ? [ct] : []), ...extra]);
+    if (hits.length === 0)
+        return pass(name, `${files.length} tracked file(s), no aop_live_ or control token`);
+    return failed(name, new CliError(`a token is in tracked file(s): ${hits.slice(0, 5).join(", ")}${hits.length > 5 ? ", …" : ""}`, "git rm --cached those files (or remove the token), make a new token, and purge it from history if you pushed"));
+}
+/** Git mode: .cf-orbs/control-token and .cf-orbs/state.json are ignored and not tracked. */
+export async function gitignoreCheck(run, p) {
+    const name = "gitignore";
+    const paths = [".cf-orbs/control-token", ".cf-orbs/state.json"];
+    const notIgnored = [];
+    for (const f of paths) {
+        // exit 0: ignored; 1: not ignored or tracked; 128: no repo. Fall back to the .gitignore lines then.
+        const r = await run("git", ["-C", p.dir, "check-ignore", "-q", f], { timeoutMs: 30_000 });
+        if (r.code === 0)
+            continue;
+        if (r.code === 1) {
+            notIgnored.push(f);
+            continue;
+        }
+        let lines = [];
+        try {
+            lines = (await readFile(p.gitignore, "utf8")).split(/\r?\n/).map((l) => l.trim());
+        }
+        catch { }
+        if (!lines.includes(f))
+            notIgnored.push(f);
+    }
+    if (notIgnored.length === 0)
+        return pass(name, `${paths.join(" and ")} are ignored`);
+    return failed(name, new CliError(`${notIgnored.join(" and ")} not ignored by git (or tracked)`, `add ${notIgnored.join(" and ")} to .gitignore and run git rm --cached on any that git tracks`));
+}
+/** Git mode: package.json pins the wrangler version the CLI uses (Workers Builds installs that one). */
+export async function wranglerPinCheck(p) {
+    const name = "wrangler pin";
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(p.packageJson, "utf8"));
+    }
+    catch {
+        return failed(name, new CliError("package.json is missing or not valid JSON", "rerun cf-orbs init --no-deploy (it writes one)"));
+    }
+    const v = pkg.devDependencies?.wrangler ?? pkg.dependencies?.wrangler;
+    if (v === WRANGLER_PIN)
+        return pass(name, `package.json pins wrangler ${v}, same as cf-orbs`);
+    return failed(name, new CliError(`package.json ${v ? `pins wrangler ${v}` : "has no wrangler dependency"}; cf-orbs uses ${WRANGLER_PIN}`, `set devDependencies.wrangler to "${WRANGLER_PIN}", run npm install, commit and push`));
+}
+/** All file checks for doctor, in output order. git: state.mode is "git". */
+export async function fileChecks(run, p, c, o) {
+    const out = [
+        await orbImagePinCheck(p, c),
+        await providerImagePinCheck(p, o.templates),
+        debugExecCheck(c, o.git),
+        await trackedSecretsCheck(run, p),
+    ];
+    if (o.git)
+        out.push(await gitignoreCheck(run, p), await wranglerPinCheck(p));
+    return out;
+}

package/dist/index.js

@@ -33,6 +33,9 @@ export const COMMANDS = {
             "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (default cf-orbs)",
             "--subdomain <name>               workers.dev subdomain to register if the account has none",
             "--vcpu <1|2|3|4>                 orb size: N vCPU, N x 3 GiB, 20 GB disk (default 4; 2 is cheaper)",
+            "--name <name>                    Worker name (default cf-orbs; a second install needs another)",
+            "--no-deploy                      preview: no Docker, no deploy. Make a git repo for Workers Builds,",
+            "                                 create the Worker and its secrets, print the dashboard steps",
         ],
         flags: {
             provider: { type: "string" },
@@ -41,6 +44,8 @@ export const COMMANDS = {
             "provider-name": { type: "string" },
             subdomain: { type: "string" },
             vcpu: { type: "string" },
+            name: { type: "string" },
+            "no-deploy": { type: "boolean" },
         },
         dirPositional: true,
         run: initCommand,

package/dist/project.js

@@ -6,6 +6,8 @@
 //   cf-orbs.config.jsonc     user config (source of truth)
 //   image/Dockerfile         orb image, user-editable; upgrade bumps its digest; image/<key>.Dockerfile for extra keys
 //   .gitignore               generated; keeps .cf-orbs/ (and its control-token) out of git
+//                            (git mode: only control-token and state.json; Workers Builds needs the rest)
+//   package.json             git mode only: pins wrangler for Workers Builds
 //   .cf-orbs/
 //     wrangler.jsonc         generated
 //     worker/src/**          copied from templates on every deploy
@@ -35,6 +37,7 @@ export function projectPaths(dir) {
         state: join(s, "state.json"),
         controlToken: join(s, "control-token"),
         gitignore: join(d, ".gitignore"),
+        packageJson: join(d, "package.json"),
     };
 }
 /** cli/templates, resolved from this file (works from src/ under vitest and from dist/ when installed). */
@@ -105,15 +108,31 @@ export const GITIGNORE_LINES = [
     ".wrangler/",
     "node_modules/",
 ];
+/** Git mode (init --no-deploy): the generated files are committed, so only these stay out of git. */
+export const GIT_MODE_GITIGNORE_LINES = [
+    ".cf-orbs/control-token",
+    ".cf-orbs/state.json",
+    ".wrangler/",
+    "node_modules/",
+];
+/** Lines of the local layout that hide the generated files. Git mode removes them. */
+const LOCAL_ONLY_LINES = new Set([".cf-orbs/*", "!.cf-orbs/state.json"]);
 /** Add the cf-orbs lines to <dir>/.gitignore, keeping existing lines. */
-export async function ensureGitignore(p) {
+export async function ensureGitignore(p, git = false) {
     let cur = "";
     try {
         cur = await readFile(p.gitignore, "utf8");
     }
     catch { }
+    if (git && cur.split(/\r?\n/).some((l) => LOCAL_ONLY_LINES.has(l.trim()))) {
+        cur = cur
+            .split(/(?<=\n)/)
+            .filter((l) => !LOCAL_ONLY_LINES.has(l.trim()))
+            .join("");
+        await writeFile(p.gitignore, cur);
+    }
     const have = new Set(cur.split(/\r?\n/).map((l) => l.trim()));
-    const add = GITIGNORE_LINES.filter((l) => !have.has(l));
+    const add = (git ? GIT_MODE_GITIGNORE_LINES : GITIGNORE_LINES).filter((l) => !have.has(l));
     if (add.length === 0)
         return;
     const sep = cur === "" || cur.endsWith("\n") ? "" : "\n";
@@ -155,7 +174,7 @@ export async function materialize(p, opts = {}) {
         await writeFile(p.config, text);
         wroteConfig = true;
     }
-    await ensureGitignore(p);
+    await ensureGitignore(p, opts.git);
     return { wroteConfig, wroteDockerfile };
 }
 /** The files the provider image is built from, relative to .cf-orbs/ (its build context). */
@@ -213,3 +232,15 @@ export async function cliVersion() {
         return "0.0.0";
     }
 }
+/** Git mode deploy command: Workers Builds runs it in the repo root. */
+export const GIT_DEPLOY_COMMAND = "npx wrangler deploy --config .cf-orbs/wrangler.jsonc";
+/** Root package.json for git mode: Workers Builds installs the wrangler version it names. */
+export function gitPackageJson(name, wrangler) {
+    const pkg = {
+        name,
+        private: true,
+        scripts: { deploy: "wrangler deploy --config .cf-orbs/wrangler.jsonc" },
+        devDependencies: { wrangler },
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}

package/dist/wrangler-template.js

@@ -40,6 +40,9 @@ export function buildWranglerConfig(c, o = {}) {
         main: "worker/src/index.ts",
         compatibility_date: COMPATIBILITY_DATE,
         compatibility_flags: ["nodejs_compat"],
+        // explicit, so wrangler does not warn: the control plane is on workers.dev; preview URLs are not used
+        workers_dev: true,
+        preview_urls: false,
         observability: { enabled: true },
         containers: [
             orbContainer,

package/dist/wrangler.js

@@ -37,6 +37,8 @@ export const runProcess = (cmd, args, o = {}) => new Promise((resolve) => {
         resolve({ code: code ?? 1, stdout, stderr });
     });
 });
+/** The wrangler version the CLI depends on (cli/package.json). Git mode pins the same version in package.json. */
+export const WRANGLER_PIN = "4.156.0";
 /** [command, ...prefix args] that runs the pinned wrangler. Prefers the CLI's own dependency over npx. */
 export function wranglerCommand() {
     try {
@@ -46,7 +48,7 @@ export function wranglerCommand() {
             return [process.execPath, [bin]];
     }
     catch { }
-    return [process.platform === "win32" ? "npx.cmd" : "npx", ["--yes", "wrangler@4.156.0"]];
+    return [process.platform === "win32" ? "npx.cmd" : "npx", ["--yes", `wrangler@${WRANGLER_PIN}`]];
 }
 export function makeWrangler(run = runProcess, base = {}) {
     const [cmd, prefix] = wranglerCommand();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "cf-orbs",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Run Amp orbs on Cloudflare Containers: self-hosted orb provider, one command to install.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "cf-orbs": "./bin/cf-orbs.js"
+    "cf-orbs": "bin/cf-orbs.js"
   },
   "files": [
     "bin",