cf-orbs 0.2.2 → 0.2.4

package/README.md

@@ -70,7 +70,7 @@ What `init` does:
 amp -ox "hello from cf-orbs" --orb-provider <name>
 ```
 
-The name after `--orb-provider` must match the provider name in Amp Settings. In the Amp app, pick the provider under **Self-Hosted** when you start a thread.
+The name after `--orb-provider` must match the provider name in Amp Settings. The default name is `cloudflare`. A saved name from an earlier `init` wins. In the Amp app, pick the provider under **Self-Hosted** when you start a thread.
 
 `init` is safe to run again. It keeps the control token, and it keeps the Amp token secret unless you give a new one.
 
@@ -120,6 +120,7 @@ Before the deploy, `init` stops with one `Failed: … — fix: …` line when:
 - 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.
+- The folder has no saved deployment and a Worker of the same name already exists in the account. `init` stops before it makes a control token, sets a secret or deploys, so it cannot overwrite a Worker that another folder made. Pass `--adopt` to take it over: a new control token replaces the old one, and this folder's config and `image/` are deployed. A rerun in the folder that made the Worker is not checked. If the check cannot run, it 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.
 
@@ -184,7 +185,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>`, `--name <worker>`, `--no-deploy` (preview: [Workers Builds](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md), no Docker) |
+| `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), `--adopt` (take over an existing Worker of the same name; see Back up) |
 | `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) |
@@ -225,6 +226,10 @@ After `cf-orbs deploy`, an orb that is awake keeps the old Worker code until it
 
 `cf-orbs deploy` then starts `prewarm` throwaway instances in the background (`prewarm: started 2 instances in the background`); `cf-orbs status` shows how fast they were ready.
 
+### Back up
+
+Running orbs need nothing on your machine: the Worker, the orbs and the snapshots are in Cloudflare. Back up `cf-orbs.config.jsonc` and `image/` (a private git repo is enough; the `.gitignore` that `init` writes keeps the control token out). Keep the Amp provider token in a password manager if you want to restore without making a new one. The control token can be made again. To restore in a new folder, run `init --adopt`: without it, `init` stops because the Worker already exists. See [Back up and restore](https://cf-orbs-site.mdick85.workers.dev/docs/guides/back-up-and-restore/).
+
 ## Troubleshooting
 
 Run `cf-orbs doctor` first.
@@ -275,7 +280,7 @@ To report a vulnerability, see [SECURITY.md](https://github.com/meirdick/cf-orbs
 
 ## Status and known gaps
 
-v0.2.2. 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.4. 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:
 

package/dist/commands/init.js

@@ -14,7 +14,7 @@ import { dockerOk, nodeMajor, whoami } from "../probes.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 { classifyDeployFailure, deployFailureError, lastErrorLine, makeWrangler, WRANGLER_PIN, } from "../wrangler.js";
+import { classifyDeployFailure, deployFailureError, lastErrorLine, lookupWorker, 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). */
@@ -22,6 +22,8 @@ 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;
+/** One line at the end of a successful init, before the amp command. */
+export const BACKUP_LINE = "back up: cf-orbs.config.jsonc and image/. Guide: https://cf-orbs-site.mdick85.workers.dev/docs/guides/back-up-and-restore/";
 export function helloCommand(providerName) {
     return `amp -ox "hello from cf-orbs" --orb-provider ${providerName}`;
 }
@@ -132,6 +134,12 @@ export function plan(o, p) {
         { kind: "plan-check" },
         { kind: "scaffold", mode: o.mode, git: Boolean(o.noDeploy) },
     ];
+    // A folder with no saved deployment and no control token must not overwrite a Worker it did not create.
+    // A folder with a control token made the Worker before (a run that failed before it saved the URL) or holds a
+    // restored backup: it keeps the same token, so nothing is lost. Runs after scaffold (the Worker name is in the
+    // config then) and before the control token, the secrets and the deploy.
+    if (!p.deployed && !p.hasControlToken)
+        steps.push({ kind: "adopt-check", adopt: Boolean(o.adopt) });
     steps.push({ kind: "control-token", action: p.hasControlToken ? "reuse" : "generate" });
     if (ampSource)
         steps.push({ kind: "amp-token", source: ampSource });
@@ -328,6 +336,19 @@ export async function runInit(ctx, o, steps) {
                 await writeState(paths, state);
                 break;
             }
+            case "adopt-check": {
+                if (!config)
+                    throw new Error("init plan bug: adopt-check before scaffold");
+                const found = await lookupWorker(makeWrangler(ctx.run, { accountId }), config.name);
+                if (found.kind === "found") {
+                    if (!s.adopt)
+                        throw new CliError(`Worker ${config.name} already exists in this account and this folder did not create it`, "run init in the folder that made it, restore that folder (see Back up and restore), pass --name <new> for a second install, or pass --adopt to take it over");
+                    ui.warn(`adopt: taking over Worker ${config.name}; a new control token replaces the old one (the folder that made it loses CLI access); this folder's config and image/ are deployed`);
+                }
+                else if (found.kind === "unknown")
+                    ui.warn(`existing-Worker check could not run (${found.reason}); init goes on`);
+                break;
+            }
             case "control-token":
                 controlToken = s.action === "reuse" ? await readControlToken(paths) : undefined;
                 if (!controlToken) {
@@ -340,8 +361,7 @@ export async function runInit(ctx, o, steps) {
                 break;
             case "amp-token":
                 // No interactive name question here: say so if the name is a fallback, not given
-                if (s.source !== "prompt" &&
-                    (o.providerNameSource === "config" || o.providerNameSource === "default"))
+                if (s.source !== "prompt" && o.providerNameSource === "default")
                     ui.warn(`provider name ${providerName} was not given explicitly; it must match the name in Amp Settings → Orbs (pass --provider-name <name> if it differs)`);
                 if (s.source === "env")
                     ampToken = checkAmpToken(ctx, (ctx.env.AMP_ORB_PROVIDER_TOKEN ?? "").trim());
@@ -580,6 +600,7 @@ export async function runInit(ctx, o, steps) {
             case "done":
                 command = s.command === helloCommand(o.providerName) ? helloCommand(providerName) : s.command;
                 ui.step(`provider name ${providerName} must match the name in Amp Settings → Orbs`);
+                ui.out(BACKUP_LINE);
                 break;
         }
     }
@@ -745,6 +766,8 @@ 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);
 }
+/** Default Amp provider name when none is given. The Worker name default is separate: cf-orbs. */
+export const DEFAULT_PROVIDER_NAME = "cloudflare";
 const WORKER_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
 export function initOptions(ctx, existing) {
     const modeFlag = flagString(ctx.args, "provider");
@@ -761,6 +784,7 @@ export function initOptions(ctx, existing) {
         vcpu: parseVcpuFlag(flagString(ctx.args, "vcpu")),
         name,
         noDeploy: flagBool(ctx.args, "no-deploy"),
+        adopt: flagBool(ctx.args, "adopt"),
         mode: modeFlag ?? existing?.providerHost ?? "cloudflare",
         nonInteractive: flagBool(ctx.args, "non-interactive") || Boolean(ctx.env.CI),
         tokenFile: flagString(ctx.args, "token-file"),
@@ -768,17 +792,14 @@ export function initOptions(ctx, existing) {
         providerName: flagString(ctx.args, "provider-name") ??
             ctx.env.AMP_ORB_PROVIDER_NAME ??
             existing?.providerName ??
-            existing?.name ??
-            "cf-orbs",
+            DEFAULT_PROVIDER_NAME,
         providerNameSource: flagString(ctx.args, "provider-name") !== undefined
             ? "flag"
             : ctx.env.AMP_ORB_PROVIDER_NAME !== undefined
                 ? "env"
                 : existing?.providerName !== undefined
                     ? "saved"
-                    : existing?.name !== undefined
-                        ? "config"
-                        : "default",
+                    : "default",
     };
 }
 export async function initCommand(ctx) {

package/dist/index.js

@@ -30,12 +30,14 @@ export const COMMANDS = {
             "--provider cloudflare|external   where amp orb provider runs (default cloudflare)",
             "--token-file <file>              Amp provider token file (else AMP_ORB_PROVIDER_TOKEN, else prompt)",
             "--account-id <id>                Cloudflare account (else CLOUDFLARE_ACCOUNT_ID, else ask)",
-            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (else AMP_ORB_PROVIDER_NAME, saved name, config name, then cf-orbs)",
+            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (default cloudflare; AMP_ORB_PROVIDER_NAME or a saved name wins)",
             "--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",
+            "--adopt                          take over a Worker of the same name that this folder did not create;",
+            "                                 init stops without it. A new control token replaces the old one",
         ],
         flags: {
             provider: { type: "string" },
@@ -46,6 +48,7 @@ export const COMMANDS = {
             vcpu: { type: "string" },
             name: { type: "string" },
             "no-deploy": { type: "boolean" },
+            adopt: { type: "boolean" },
         },
         dirPositional: true,
         run: initCommand,

package/dist/wrangler.js

@@ -135,6 +135,27 @@ export function deployFailureError(kind, output) {
             return new CliError(`wrangler deploy failed: ${lastErrorLine(output)}`, "fix the error above, then rerun cf-orbs deploy");
     }
 }
+/**
+ * Does a Worker with this name exist in the account? Runs `wrangler deployments list --json --name <name>`.
+ * Verified with wrangler 4.156.0: an existing Worker exits 0 and prints a JSON array. A missing one exits 1,
+ * prints nothing on stdout and prints `This Worker does not exist on your account. [code: 10007]` on stderr.
+ * Any other result (auth, network, bad account id, odd output) is "unknown".
+ */
+export async function lookupWorker(w, name) {
+    const r = await w.run(["deployments", "list", "--json", "--name", name], { timeoutMs: 60_000 });
+    const out = `${r.stdout}\n${r.stderr}`;
+    if (r.code === 0) {
+        try {
+            if (Array.isArray(JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf("["))))))
+                return { kind: "found" };
+        }
+        catch { }
+        return { kind: "unknown", reason: "unreadable wrangler output" };
+    }
+    if (/\[code: 10007\]|This Worker does not exist/.test(out))
+        return { kind: "missing" };
+    return { kind: "unknown", reason: lastErrorLine(out) };
+}
 /** Last meaningful line of wrangler output, preferring the "✘ [ERROR]" line. */
 export function lastErrorLine(output) {
     const clean = output.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g"), "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cf-orbs",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Run Amp orbs on Cloudflare Containers: self-hosted orb provider, one command to install.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/worker/src/api.ts

@@ -18,7 +18,7 @@ import { type Env, orbDoName, PROVIDER_DO_NAME, REGISTRY_DO_NAME } from "./env";
 import { BENCH_ORB_RE, type BenchStartRequest, parseBenchStart } from "./orb/bench";
 import { restartProvider } from "./provider-restart";
 
-export const API_VERSION = "0.2.2";
+export const API_VERSION = "0.2.4";
 
 /** D2. Amp sends `amp-<thread id>`. Never starts with `_` or `.`, so it cannot look like an internal name. */
 export const ORB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;