@cloudhal/cli 0.1.0 → 0.2.0

package/README.md

@@ -161,6 +161,8 @@ Locally, `cloudhal studio` reads the project's SQLite (`analytics_events`), roll
 
 `cloudhal deploy` uses **your** wrangler login (`npx wrangler login`, or `CLOUDFLARE_API_TOKEN`); Cloudhal never reads those credentials. It creates the D1 database and R2 bucket if needed (with a lifecycle rule that expires the snapshot bundles under `bundles/` after 30 days, RFC-0010), generates the deployment secrets once into `.cloudhal/deploy/secrets.json` (0600 — keep it out of git), builds and deploys the **site Worker** (Astro on demand, edge-cached) and the **admin Worker** (Studio, API, auth, MCP), and on the first deploy pushes your local site.
 
+**From Git (Workers Builds).** With `WORKERS_CI=1`, which Cloudflare sets in [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/), `cloudhal deploy` works from a fresh clone. It takes the names from the committed `wrangler.jsonc`, seeds the starter site when the checkout has none, keeps the secrets on the Workers and does not print the setup link. This is what the Deploy to Cloudflare button runs: see [docs/guides/deploy-button.md](../../docs/guides/deploy-button.md).
+
 **Custom domain.** `cloudhal domain set news.example.com --studio studio.example.com` records the hostnames in `cloudhal.json`; the next `cloudhal deploy` routes them to the Workers as [Cloudflare Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) (the zone must be in the same Cloudflare account — Cloudflare creates the DNS record and certificate) and makes the site's one its primary hostname, so preview links use it (canonical URLs in the starter are not rendered yet). The workers.dev addresses keep working. `cloudhal domain remove` and a deploy undo it.
 
 **Email (RFC-0011).** Add `"mail": { "from": "studio@example.com", "fromName": "Example Studio" }` to `cloudhal.json` and the next `cloudhal deploy` gives the admin Worker a [Cloudflare Email Service](https://developers.cloudflare.com/email-service/) `send_email` binding locked to that address. Invites can then be emailed, and staff can reset a forgotten password from the sign-in screen. Onboard the address's domain in Email Service first. Sending to any recipient needs Workers Paid (3,000 emails a month included); on Free, Email Service delivers only to verified destination addresses of your account. Locally, `cloudhal studio` prints these emails in the terminal instead of sending them.

package/dist/assets/skills/site-design/references/page-recipes.md

@@ -6,7 +6,7 @@ Starting points, not templates: adapt them to the site's rules and real content.
 1. **Hero:** `Band` (surface `gradient`, `mesh`, `inverse` or `brand`, width `full`, spacing `xl`) → `Heading` level 1 (the promise, ≤ 8 words) → `Text` size `l` (one sentence) → `Row` with one primary and one secondary `Button`.
 2. **Features:** plain section → `Heading` level 2 → `Grid` (columns 3 or 4) of `Card`s with a short `Heading` level 3 and one sentence each.
 3. **Proof:** `Band` surface `muted` or `dots` → `Grid` of `Stat`s, or `Columns 2-1` with a `Quote` / `testimonial` next to an `Image`.
-4. **Pricing:** `Tabs` (monthly / yearly) or a `Toggle` bound to data and `Text` bound with `formatCurrency`; one `Card` per real plan.
+4. **Pricing:** `Tabs` (monthly / yearly) or a `Toggle` with a `label` (shown above it) bound to data and `Text` bound with `formatCurrency`; one `Card` per real plan. A price with no currency symbol is `formatNumber` with `digits` 2 and `minDigits` 2 (9.60, not 9.6).
 5. **Questions:** `faq` block or `Accordion` of `Disclosure`s (the real questions, as many as there are).
 6. **Call to action:** `Band` surface `brand` or `accent` (anchor `start`) → `Heading` level 2 → one primary `Button`.
 
@@ -30,5 +30,5 @@ Compute, don't promise: a result is a function call over the inputs, never text
 - **Calculator** (calories, loan, savings, price × seats): a `Card` holding a `Heading`, the inputs (`NumberField` with `unit`, `min`, `max`; `RadioGroup` `variant: buttons` for two to four choices; `Checkbox` for yes/no), two or three to a `Grid` row, then the result as a `Stat` right below. Start every number input as `""` in `data`; bind each input's `value` with `{path}`; write the result as one formula with `calculate` and `vars` (each input's path, or a `choose` for a choice), and show it with `formatNumber` or `formatCurrency`. Calories: `(10*w + 6.25*h - 5*a + s) * f` with `s` and `f` from `choose`; a loan payment: `p * r / (1 - (1 + r)^(-12*y))` with `r` the yearly percent ÷ 1200.
 - **Keypad calculator:** a `Text` bound to `/display`, a `Grid` of `Button`s with `append` (digits and operators), `C` as `set` "" and `=` as `set` with `calculate` over `/display`.
 - **Chart:** a `Chart` bound to rows in `data` (`x` the label field, `series` the number fields), titled with what it shows, with a `caption` naming the source. Bar to compare, line over time, donut for parts of a whole.
-- **Comparison:** a `Table` bound to rows, the first column naming the row, numbers aligned `end` with a `format`.
+- **Comparison:** a `Table` bound to rows, the first column naming the row, numbers aligned `end` with a `format`. With more than four columns, mark the ones a phone reader can skip `hideOnPhone: true`, so each phone card keeps three or four lines. To say which option wins, give a `Text` a `visible` that compares the computed values: `{"lt": [{"call": "calculate", …}, {"call": "calculate", …}]}`; no sign tricks with `clamp` and `choose`.
 Check with `render_page`: no `input-label`, `chart-empty` or `overflow-x`, and the result shows a number with the sample values.

package/dist/assets/starters/blog/package.json

@@ -14,18 +14,18 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@cloudhal/astro-renderer": "0.1.0",
-    "@cloudhal/core-ts": "0.1.0",
+    "@cloudhal/astro-renderer": "0.2.0",
+    "@cloudhal/core-ts": "0.2.0",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "7.3.6",
     "better-sqlite3": "13.0.3",
     "tailwindcss": "^4.3.3",
     "@astrojs/cloudflare": "14.3.4",
-    "@cloudhal/cli": "0.1.0"
+    "@cloudhal/cli": "0.2.0"
   },
   "devDependencies": {
     "wrangler": "^4.148.0",
-    "@cloudhal/cloudflare": "0.1.0"
+    "@cloudhal/cloudflare": "0.2.0"
   },
   "trustedDependencies": [
     "better-sqlite3",

package/dist/assets/starters/blog/src/styles/features/live-surfaces.css

@@ -216,6 +216,9 @@ button.ch-button--secondary {
     @apply text-left font-medium text-zinc-600;
     content: attr(data-label);
   }
+  .ch-table td[data-phone="hide"] {
+    @apply hidden;
+  }
   .ch-table tr[data-highlight="yes"] td:first-child {
     box-shadow: none;
   }

package/dist/src/cli/commands-remote.js

@@ -53,6 +53,7 @@ const deployCommand             = async (_rest, values, { projectDir }) => {
     );
   if (r.setupUrl)
     console.log(`\nLocal site pushed. Create the owner account (once) at:\n  ${r.setupUrl}`);
+  if (r.setupInstructions) console.log(`\nStarter site pushed. ${r.setupInstructions}`);
   return 0;
 };
 

package/dist/src/commands/deploy/attach.js

@@ -52,7 +52,8 @@ async function installationOf(projectDir        , folder        ) {
 export async function deployAttached(options               )                        {
   const own = await readProjectConfig(options.projectDir);
   const inst = await installationOf(options.projectDir, own.installation          );
-  const loaded = await loadDeploy({ ...options, name: inst.state.name });
+  // the installation lives in another local project, never in a Workers Builds checkout
+  const loaded = await loadDeploy({ ...options, name: inst.state.name, workersBuilds: false });
   const base = { ...loaded.base, siteName: `${inst.state.name}-site-${loaded.site.slug}` };
   const previous = {
     ...(loaded.previous ?? inst.state),

package/dist/src/commands/deploy/context.d.ts

@@ -18,4 +18,6 @@ export interface DeployContext {
     readonly previous: DeployState | undefined;
     readonly base: DeploymentNames;
     readonly names: ReturnType<typeof workerNames>;
+    /** Running in Cloudflare Workers Builds (`workers-builds.ts`). */
+    readonly workersBuilds: boolean;
 }

package/dist/src/commands/deploy/context.js

@@ -19,4 +19,6 @@
                                              
                                  
                                                  
+                                                                    
+                                  
  

package/dist/src/commands/deploy/options.d.ts

@@ -56,6 +56,12 @@ export interface DeployOptions {
     readonly buildStudio?: boolean;
     /** Injected in tests: runs the Studio build. */
     readonly studioBuilder?: StudioBuilder;
+    /**
+     * Deploying from Cloudflare Workers Builds (the Deploy to Cloudflare button): names from the
+     * committed `wrangler.jsonc`, the starter seeded when missing, secrets kept on the Workers.
+     * Default: `WORKERS_CI=1` in the environment.
+     */
+    readonly workersBuilds?: boolean;
 }
 export interface DeployResult {
     dryRun: boolean;
@@ -67,6 +73,8 @@ export interface DeployResult {
     pushed?: boolean;
     /** First deploy only: open it to create the owner account. */
     setupUrl?: string;
+    /** First deploy from Workers Builds: how to create the owner account (no link is printed). */
+    setupInstructions?: string;
     /** Custom domains from cloudhal.json, routed by this deploy. */
     customSiteUrl?: string;
     customStudioUrl?: string;

package/dist/src/commands/deploy/options.js

@@ -63,6 +63,12 @@
                                  
                                                   
                                          
+     
+                                                                                               
+                                                                                              
+                                                
+     
+                                   
  
 
                                
@@ -75,6 +81,8 @@
                    
                                                                 
                     
+                                                                                                
+                             
                                                                   
                          
                            

package/dist/src/commands/deploy/prepare.js

@@ -63,6 +63,7 @@ import {
   rateLimitDeployment,
 } from "./settings.js";
 import { deployDir, exists,                    readDeployState } from "./state.js";
+import { committedNames, inWorkersBuilds, seedIfMissing } from "./workers-builds.js";
 
 export function checkOptions(options               )       {
   if (options.jurisdiction !== undefined && !["auto", "eu"].includes(options.jurisdiction))
@@ -80,16 +81,22 @@ export async function loadDeploy(options               )
   const dir = deployDir(options.projectDir, cfg.dataDir);
   await mkdir(dir, { recursive: true });
   const run = options.wrangler ?? wranglerRunner(options.projectDir, log);
+  // Workers Builds: the button's names, and the starter site in a checkout that has none
+  const workersBuilds = inWorkersBuilds(options.workersBuilds);
+  const committed = workersBuilds
+    ? await committedNames(siteConfigPath(options.projectDir))
+    : undefined;
+  if (committed) await seedIfMissing(options.projectDir, cfg, committed.name, log);
 
   const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
   const site = await local.store.getSite(cfg.siteId);
   await local.close();
   if (!site) throw new Error(`site ${cfg.siteId} not found in the local store`);
   const previous = await readDeployState(options.projectDir, cfg.dataDir);
-  const name = options.name ?? previous?.name ?? site.slug;
+  const name = options.name ?? committed?.name ?? previous?.name ?? site.slug;
   // RFC-0029 §3: the search provider's instance and bucket, bound by both Workers.
   const search = searchDeploymentOf(cfg.search, name);
-  const base                  = { name, ...(search ? { search } : {}) };
+  const base                  = { ...committed, name, ...(search ? { search } : {}) };
   if (search)
     log(
       `search: Cloudflare AI Search instance ${search.instance} over R2 bucket ${search.bucket} (the instance must exist, read that bucket and declare the text metadata fields locale and kind); ${search.monthlyLimit} semantic searches a month for the deployment (Cloudflare includes 1,000 per account), then FTS5 alone until the month ends`,
@@ -97,7 +104,7 @@ export async function loadDeploy(options               )
   const names = workerNames(base);
   // 0. analytics: decided before anything is generated; the wrangler version gates the configs
   const decided = await decideAnalytics(options, cfg, site.name, log);
-  return { options, log, cfg: decided, dir, run, site, previous, base, names };
+  return { options, log, cfg: decided, dir, run, site, previous, base, names, workersBuilds };
 }
 
 /** 0. analytics bindings (wrangler ≥ 4.145); 0b. reader comments (RFC-0007 §15.4). */
@@ -159,8 +166,11 @@ export async function provision(
   ctx               ,
 )                                                                                   {
   const { options, names, log, base } = ctx;
+  // Workers Builds: the database the button provisioned (its token may not read D1)
+  const known = ctx.workersBuilds ? base.databaseId : undefined;
   const existing = await readExistingIds(siteConfigPath(options.projectDir));
-  let databaseId = existing.databaseId;
+  // (a placeholder id in the committed file is no id: never carried into the config)
+  let databaseId = ctx.workersBuilds ? known : existing.databaseId;
   let databaseCreated                          ;
   if (!options.dryRun) {
     const r = await ensureResources(ctx.run, {
@@ -168,6 +178,7 @@ export async function provision(
       names,
       log,
       where: jurisdictionChooser(options, log),
+      ...(known ? { databaseId: known } : {}),
     });
     databaseId = r.databaseId;
     databaseCreated = r.created;

package/dist/src/commands/deploy/resources.d.ts

@@ -2,12 +2,14 @@
 import type { workerNames } from "../../cloudflare/config.js";
 import type { WranglerRunner } from "../../cloudflare/wrangler.js";
 import type { Jurisdiction } from "./state.js";
-export declare function ensureResources(run: WranglerRunner, { cwd, names, log, where, }: {
+export declare function ensureResources(run: WranglerRunner, { cwd, names, log, where, databaseId: known, }: {
     cwd: string;
     names: ReturnType<typeof workerNames>;
     log: (l: string) => void;
     /** Asked only when the database is created: where it lives. */
     where: () => Promise<Jurisdiction>;
+    /** A database already provisioned (Workers Builds): no D1 call at all. */
+    databaseId?: string;
 }): Promise<{
     databaseId: string;
     created?: Jurisdiction;

package/dist/src/commands/deploy/resources.js

@@ -12,12 +12,15 @@ export async function ensureResources(
     names,
     log,
     where,
+    databaseId: known,
   }   
                 
                                           
                              
                                                                    
                                        
+                                                                              
+                        
    ,
 )                                                          {
   const info = async () => {
@@ -29,7 +32,7 @@ export async function ensureResources(
       return undefined;
     }
   };
-  let databaseId = await info();
+  let databaseId = known ?? (await info());
   let made                          ;
   if (!databaseId) {
     made = await where();

package/dist/src/commands/deploy/ship.d.ts

@@ -9,7 +9,9 @@ type PreparedAdmin = Awaited<ReturnType<typeof prepareAdminWorker>>;
  * the SchedulerClock alarm ticks instead.
  */
 export declare function shipWorkers(ctx: DeployContext, input: {
-    secrets: DeploySecrets;
+    /** What this deploy sets on each Worker (the site Worker's share of the admin Worker's). */
+    siteSecrets: Partial<DeploySecrets>;
+    adminSecrets: Partial<DeploySecrets>;
     admin: PreparedAdmin;
     prepareAdmin: (ticker: SchedulerTicker) => Promise<PreparedAdmin>;
     scheduler: SchedulerTicker;

package/dist/src/commands/deploy/ship.js

@@ -28,7 +28,9 @@ import { CRON_REFUSED_MESSAGE } from "./schedules-guard.js";
 export async function shipWorkers(
   ctx               ,
   input   
-                           
+                                                                                                
+                                        
+                                         
                          
                                                                       
                                
@@ -39,29 +41,27 @@ export async function shipWorkers(
                              
    {
   const { options, run, names, log, dir } = ctx;
-  const { secrets, admin } = input;
+  const { admin } = input;
   let scheduler = input.scheduler;
-  // Secrets go to wrangler through files that exist only while it runs (0600, then removed).
+  // Secrets go to wrangler through files that exist only while it runs (0600, then removed); a
+  // Worker keeps every secret a deploy does not set.
   const siteSecretsFile = path.join(dir, "site-secrets.json");
   const adminSecretsFile = path.join(dir, "admin-secrets.json");
-  const writeSecret = async (file        , value        ) => {
+  const secretsArgs = async (file        , value        ) => {
+    if (Object.keys(value).length === 0) return [];
     await writeFile(file, JSON.stringify(value), { mode: 0o600 });
     await chmod(file, 0o600);
+    return ["--secrets-file", file];
   };
   let siteDeploy                                  ;
   let adminDeploy                                  ;
   try {
-    await writeSecret(siteSecretsFile, {
-      CLOUDHAL_PREVIEW_SECRET: secrets.CLOUDHAL_PREVIEW_SECRET,
-      CLOUDHAL_PURGE_TOKEN: secrets.CLOUDHAL_PURGE_TOKEN,
-      // RFC-0007: the same value as the admin Worker's (proof of work, emails, stored secrets)
-      CLOUDHAL_COMMENTS_KEY: secrets.CLOUDHAL_COMMENTS_KEY,
-    });
-    await writeSecret(adminSecretsFile, secrets);
+    const siteArgs = await secretsArgs(siteSecretsFile, input.siteSecrets);
+    const adminSecrets = await secretsArgs(adminSecretsFile, input.adminSecrets);
     log(`deploying ${names.site}`);
-    siteDeploy = await must(run, ["deploy", "--secrets-file", siteSecretsFile], options.projectDir);
+    siteDeploy = await must(run, ["deploy", ...siteArgs], options.projectDir);
     log(`deploying ${names.admin}`);
-    const adminArgs = ["deploy", "-c", admin.configPath, "--secrets-file", adminSecretsFile];
+    const adminArgs = ["deploy", "-c", admin.configPath, ...adminSecrets];
     adminDeploy = await run(adminArgs, { cwd: admin.dir });
     if (
       adminDeploy.code !== 0 &&

package/dist/src/commands/deploy/state.d.ts

@@ -1,6 +1,8 @@
 import type { SchedulerTicker, WorkersPlan } from "../../cloudflare/config.js";
 export declare const SECRET_KEYS: readonly ["BETTER_AUTH_SECRET", "MCP_STATE_KEY", "CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN", "CLOUDHAL_DEPLOY_TOKEN", "CLOUDHAL_SETUP_TOKEN", "CLOUDHAL_COMMENTS_KEY"];
 export type DeploySecrets = Record<(typeof SECRET_KEYS)[number], string>;
+/** The secrets the site Worker has too, with the same values as the admin Worker's. */
+export declare const SITE_SECRET_KEYS: readonly ["CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN", "CLOUDHAL_COMMENTS_KEY"];
 export interface DeployState {
     name: string;
     adminUrl?: string;

package/dist/src/commands/deploy/state.js

@@ -14,6 +14,12 @@ export const SECRET_KEYS = [
   "CLOUDHAL_COMMENTS_KEY",
 ]         ;
                                                                          
+/** The secrets the site Worker has too, with the same values as the admin Worker's. */
+export const SITE_SECRET_KEYS = [
+  "CLOUDHAL_PREVIEW_SECRET",
+  "CLOUDHAL_PURGE_TOKEN",
+  "CLOUDHAL_COMMENTS_KEY",
+]                                                           ;
 
                               
                

package/dist/src/commands/deploy/workers-builds.d.ts

@@ -0,0 +1,30 @@
+import type { DeploymentNames, workerNames } from "../../cloudflare/config.js";
+import type { WranglerRunner } from "../../cloudflare/wrangler.js";
+import type { ProjectConfig } from "../../config.js";
+import { type DeploySecrets } from "./state.js";
+/** Whether this deploy runs in Workers Builds (`WORKERS_CI=1`, set by Cloudflare). */
+export declare const inWorkersBuilds: (flag: boolean | undefined) => boolean;
+/** The committed `wrangler.jsonc`'s names, read before this deploy rewrites it. */
+export declare function committedNames(file: string): Promise<Omit<DeploymentNames, "search">>;
+/** Seeds the starter site under `cloudhal.json`'s `siteId` when this checkout has none. */
+export declare function seedIfMissing(projectDir: string, cfg: ProjectConfig, name: string, log: (line: string) => void): Promise<void>;
+export interface BuildsSecrets {
+    /** What this deploy sets on each Worker; everything else the Workers keep. */
+    readonly site: Partial<DeploySecrets>;
+    readonly admin: Partial<DeploySecrets>;
+    /** Every value this deploy knows (always the new deployment token). */
+    readonly known: Partial<DeploySecrets> & {
+        CLOUDHAL_DEPLOY_TOKEN: string;
+    };
+}
+/**
+ * The secrets to set: the missing ones and a new deployment token, written to the checkout's
+ * `secrets.json` (0600, gone with the build) for `cloudhal push`.
+ */
+export declare function buildsSecrets(run: WranglerRunner, input: {
+    cwd: string;
+    dir: string;
+    names: ReturnType<typeof workerNames>;
+}): Promise<BuildsSecrets>;
+/** What the owner does once, instead of a printed setup link. */
+export declare function setupInstructions(adminUrl: string, adminWorker: string): string;

package/dist/src/commands/deploy/workers-builds.js

@@ -0,0 +1,146 @@
+/**
+ * `cloudhal deploy` inside Cloudflare Workers Builds (`WORKERS_CI=1`), which the Deploy to
+ * Cloudflare button sets up (docs/guides/deploy-button.md). Every build starts from a fresh clone:
+ * no local store, no `secrets.json`, no `state.json`. So:
+ *
+ * - names: the committed `wrangler.jsonc` is the button's — the Worker it connected (which
+ *   Workers Builds requires the config to name) and the D1 database and R2 bucket it provisioned,
+ *   possibly renamed by the person who clicked. The deployment takes those names; the admin Worker
+ *   is `<base>-admin`, where `<base>` is the site Worker's name without `-site`.
+ * - the site: when the local store lacks `cloudhal.json`'s `siteId`, the starter site is seeded
+ *   under that id. Only the first deploy pushes it; afterwards the deployment is the source of
+ *   truth, as always.
+ * - secrets: they live only on the Workers. A secret either Worker already has is kept (wrangler
+ *   keeps every secret a deploy does not set); a missing one is generated and set. The secrets
+ *   both Workers share are set together, so they never differ. The deployment token, which only
+ *   this deploy uses, is new on every build.
+ * - the setup link is never printed (build logs are kept): the owner sets their own setup token
+ *   on the admin Worker and opens the link themselves.
+ */
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+                                                                               
+                                                                   
+                                                     
+import { seedProjectSite } from "../../seed-site.js";
+import {                     randomSecret, SECRET_KEYS, SITE_SECRET_KEYS } from "./state.js";
+
+/** Whether this deploy runs in Workers Builds (`WORKERS_CI=1`, set by Cloudflare). */
+export const inWorkersBuilds = (flag                     )          =>
+  flag ?? process.env.WORKERS_CI === "1";
+
+/** A placeholder D1 id a template commits before the button provisions the real database. */
+const PLACEHOLDER_ID = /^0{8}-0{4}-0{4}-0{4}-0{12}$/;
+
+/** The committed `wrangler.jsonc`'s names, read before this deploy rewrites it. */
+export async function committedNames(file        )                                           {
+  let cfg   
+                  
+                                                                                        
+                                                              
+   ;
+  try {
+    cfg = JSON.parse((await readFile(file, "utf8")).replace(/^\s*\/\/.*$/gm, ""));
+  } catch {
+    throw new Error(
+      `Workers Builds: ${path.basename(file)} is missing or not JSON; it must name the site Worker, its D1 database and R2 bucket (docs/guides/deploy-button.md)`,
+    );
+  }
+  if (!cfg.name) throw new Error(`Workers Builds: ${path.basename(file)} has no "name"`);
+  const db = cfg.d1_databases?.find((d) => d.binding === "DB");
+  const bucket = cfg.r2_buckets?.find((b) => b.binding === "BLOBS");
+  const base = cfg.name.replace(/-site$/, "") || cfg.name;
+  return {
+    name: base,
+    ...(cfg.name !== `${base}-site` ? { siteName: cfg.name } : {}),
+    ...(db?.database_name ? { databaseName: db.database_name } : {}),
+    ...(db?.database_id && !PLACEHOLDER_ID.test(db.database_id)
+      ? { databaseId: db.database_id }
+      : {}),
+    ...(bucket?.bucket_name ? { bucketName: bucket.bucket_name } : {}),
+  };
+}
+
+/** Seeds the starter site under `cloudhal.json`'s `siteId` when this checkout has none. */
+export async function seedIfMissing(
+  projectDir        ,
+  cfg               ,
+  name        ,
+  log                        ,
+)                {
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  const site = await local.store.getSite(cfg.siteId);
+  await local.close();
+  if (site) return;
+  await seedProjectSite(projectDir, { dataDir: cfg.dataDir, name, slug: name, siteId: cfg.siteId });
+  log(
+    `Workers Builds: seeded the starter site ${cfg.siteId}; it is pushed only if the deployment does not have it yet`,
+  );
+}
+
+async function secretNames(run                , worker        , cwd        )                       {
+  const r = await run(["secret", "list", "--name", worker, "--format", "json"], {
+    cwd,
+    quiet: true,
+  });
+  if (r.code !== 0) {
+    // A Worker that does not exist yet has no secrets; any other failure must stop the deploy,
+    // or the secrets would be replaced and what they encrypt lost.
+    if (/not found|10007/i.test(r.stderr + r.stdout)) return new Set();
+    throw new Error(
+      `Workers Builds: could not list the secrets of ${worker}:\n${(r.stderr || r.stdout).slice(-2000)}`,
+    );
+  }
+  try {
+    return new Set((JSON.parse(r.stdout)                      ).map((s) => s.name));
+  } catch {
+    throw new Error(`Workers Builds: could not read the secret list of ${worker}`);
+  }
+}
+
+                                
+                                                                                
+                                        
+                                         
+                                                                         
+                                                                             
+ 
+
+/**
+ * The secrets to set: the missing ones and a new deployment token, written to the checkout's
+ * `secrets.json` (0600, gone with the build) for `cloudhal push`.
+ */
+export async function buildsSecrets(
+  run                ,
+  input                                                                     ,
+)                         {
+  const site = await secretNames(run, input.names.site, input.cwd);
+  const admin = await secretNames(run, input.names.admin, input.cwd);
+  const shared                    = SITE_SECRET_KEYS;
+  const known                                                             = {
+    CLOUDHAL_DEPLOY_TOKEN: randomSecret(),
+  };
+  for (const key of SECRET_KEYS) {
+    const missing = shared.includes(key) ? !site.has(key) || !admin.has(key) : !admin.has(key);
+    if (missing && !known[key]) known[key] = randomSecret();
+  }
+  const pick = (keys                   ) =>
+    Object.fromEntries(Object.entries(known).filter(([k]) => keys.includes(k)));
+  const file = path.join(input.dir, "secrets.json");
+  await writeFile(file, `${JSON.stringify(known, null, 2)}\n`, { mode: 0o600 });
+  await chmod(file, 0o600);
+  return { site: pick(shared), admin: known, known };
+}
+
+/** What the owner does once, instead of a printed setup link. */
+export function setupInstructions(adminUrl        , adminWorker        )         {
+  const login = `${adminUrl.replace(/\/$/, "")}/login#setup=`;
+  return [
+    "Create the owner account (once). The setup link is not printed, because build logs are kept:",
+    `  1. Cloudflare dashboard › Workers & Pages › ${adminWorker} › Settings › Variables and Secrets:`,
+    "     edit CLOUDHAL_SETUP_TOKEN and set a random value of your own (32 characters or more),",
+    `     or run \`npx wrangler secret put CLOUDHAL_SETUP_TOKEN --name ${adminWorker}\``,
+    `  2. open ${login}<that value>`,
+  ].join("\n");
+}

package/dist/src/commands/deploy.d.ts

@@ -39,6 +39,9 @@
  *      `apps/studio/src`, `apps/studio/index.html` or `packages/ui/src`, the deploy runs
  *      `pnpm --filter @cloudhal/studio build` first; `--no-build-studio` fails instead. A published
  *      install ships Studio prebuilt and is never checked.
+ *  13. Workers Builds (`WORKERS_CI=1`, the Deploy to Cloudflare button): names from the committed
+ *      `wrangler.jsonc`, the starter seeded when the checkout has none, secrets kept on the Workers
+ *      and no setup link printed (`deploy/workers-builds.ts`, docs/guides/deploy-button.md).
  *
  * `--dry-run` runs everything up to wrangler's own `--dry-run` (bundles, configs) and skips
  * provisioning, deployment and push — no Cloudflare account needed.

package/dist/src/commands/deploy.js

@@ -39,6 +39,9 @@
  *      `apps/studio/src`, `apps/studio/index.html` or `packages/ui/src`, the deploy runs
  *      `pnpm --filter @cloudhal/studio build` first; `--no-build-studio` fails instead. A published
  *      install ships Studio prebuilt and is never checked.
+ *  13. Workers Builds (`WORKERS_CI=1`, the Deploy to Cloudflare button): names from the committed
+ *      `wrangler.jsonc`, the starter seeded when the checkout has none, secrets kept on the Workers
+ *      and no setup link printed (`deploy/workers-builds.ts`, docs/guides/deploy-button.md).
  *
  * `--dry-run` runs everything up to wrangler's own `--dry-run` (bundles, configs) and skips
  * provisioning, deployment and push — no Cloudflare account needed.
@@ -64,7 +67,8 @@ import { downgradeGuard } from "./deploy/schedules-guard.js";
 import { attachedWorkers } from "./deploy/served-sites.js";
 import { commentsResult } from "./deploy/settings.js";
 import { afterDeploy, purgeIfSwitched, shipWorkers } from "./deploy/ship.js";
-import { loadOrCreateSecrets, writeDeployState } from "./deploy/state.js";
+import { loadOrCreateSecrets, SITE_SECRET_KEYS, writeDeployState } from "./deploy/state.js";
+import { buildsSecrets, setupInstructions } from "./deploy/workers-builds.js";
 import { resolveSkillsDir } from "./mcp.js";
 
                                                                        
@@ -90,6 +94,15 @@ export {
   SECRET_KEYS,
 } from "./deploy/state.js";
 
+/** What this deploy sets on each Worker, and the values it knows (all of them, outside Workers Builds). */
+async function deploySecrets(ctx                                        ) {
+  if (ctx.workersBuilds && !ctx.options.dryRun)
+    return buildsSecrets(ctx.run, { cwd: ctx.options.projectDir, dir: ctx.dir, names: ctx.names });
+  const all = await loadOrCreateSecrets(ctx.dir);
+  const site = Object.fromEntries(SITE_SECRET_KEYS.map((k) => [k, all[k]]));
+  return { site, admin: all, known: all };
+}
+
 export async function deploy(options               )                        {
   checkOptions(options);
   // RFC-0034 §4: a site Worker that joins another installation deploys only itself.
@@ -99,10 +112,11 @@ export async function deploy(options               )                        {
   const { analytics, comments } = await analyticsAndComments(ctx);
   const studioDir = await studioDirFor(ctx);
   const { withIds, databaseCreated } = await provision(ctx);
-  // 2. secrets; 2b. RFC-0008: never deploy code that ignores holds and gates over open releases
-  const secrets = await loadOrCreateSecrets(ctx.dir);
-  if (!options.dryRun && previous?.adminUrl)
-    await downgradeGuard(options, previous.adminUrl, secrets.CLOUDHAL_DEPLOY_TOKEN, log);
+  // 2. secrets (Workers Builds: kept on the Workers); 2b. RFC-0008: never deploy code that
+  // ignores holds and gates over open releases
+  const secrets = await deploySecrets(ctx);
+  if (!options.dryRun && previous?.adminUrl && !ctx.workersBuilds)
+    await downgradeGuard(options, previous.adminUrl, secrets.known.CLOUDHAL_DEPLOY_TOKEN, log);
   const settings = await deploySettings(ctx);
   const { plan, schedules, observability } = settings;
   const site = await buildSite(ctx, { withIds, analytics, comments, observability });
@@ -163,7 +177,8 @@ export async function deploy(options               )                        {
   }
 
   const { siteUrl, adminUrl, scheduler } = await shipWorkers(ctx, {
-    secrets,
+    siteSecrets: secrets.site,
+    adminSecrets: secrets.admin,
     admin,
     prepareAdmin,
     scheduler: settings.scheduler,
@@ -184,18 +199,21 @@ export async function deploy(options               )                        {
     plan,
   });
   const pushed = await afterDeploy(ctx, { siteUrl, adminUrl });
-  const { purged, analyticsChanged, commentsChanged } = await purgeIfSwitched(ctx, {
-    siteUrl,
-    analytics,
-    comments,
-    purgeToken: secrets.CLOUDHAL_PURGE_TOKEN,
-  });
+  // Workers Builds knows no previous deploy, nor (after the first) the purge token: no purge
+  const purgeToken = secrets.known.CLOUDHAL_PURGE_TOKEN;
+  const { purged, analyticsChanged, commentsChanged } = purgeToken
+    ? await purgeIfSwitched(ctx, { siteUrl, analytics, comments, purgeToken })
+    : { purged: false, analyticsChanged: false, commentsChanged: false };
 
   // First deploy: the owner account can only be created through this one-time link.
+  const setupToken = secrets.known.CLOUDHAL_SETUP_TOKEN;
+  const first = pushed && adminUrl;
   const setupUrl =
-    pushed && adminUrl
-      ? `${adminUrl.replace(/\/$/, "")}/login#setup=${secrets.CLOUDHAL_SETUP_TOKEN}`
+    first && setupToken && !ctx.workersBuilds
+      ? `${adminUrl.replace(/\/$/, "")}/login#setup=${setupToken}`
       : undefined;
+  const instructions =
+    first && ctx.workersBuilds ? setupInstructions(adminUrl, names.admin) : undefined;
   return {
     dryRun: false,
     names,
@@ -205,6 +223,7 @@ export async function deploy(options               )                        {
     adminUrl,
     pushed,
     ...(setupUrl ? { setupUrl } : {}),
+    ...(instructions ? { setupInstructions: instructions } : {}),
     ...(cfg.domains?.site ? { customSiteUrl: `https://${cfg.domains.site}` } : {}),
     ...(cfg.domains?.studio ? { customStudioUrl: `https://${cfg.domains.studio}` } : {}),
     scheduler,

package/dist/src/commands/init.js

@@ -9,12 +9,10 @@ import {
   writeFile,
 } from "node:fs/promises";
 import path from "node:path";
-import { seedStarterSite } from "@cloudhal/core-ts";
-import { openLocalStore } from "@cloudhal/core-ts/local";
 import { assetDir, materializeDependencies, monorepoRoot, monorepoVersions } from "../assets.js";
-import { loadThemeSettings } from "../blocks.js";
 import { writeProjectConfig } from "../config.js";
 import { pnpmWorkspaceYaml } from "../project-setup.js";
+import { seedProjectSite } from "../seed-site.js";
 import { starterFilter } from "../starter-files.js";
 
                               
@@ -109,34 +107,16 @@ export async function init(options             )                      {
     await writeFile(path.join(projectDir, "pnpm-workspace.yaml"), pnpmWorkspaceYaml());
 
   const dataDir = ".cloudhal";
-  const local = await openLocalStore(path.join(projectDir, dataDir));
-  try {
-    const seeded = await seedStarterSite(local.store, { name, slug });
-    // RFC-0024 decision 4: new sites start with standard motion when the theme offers it; readers
-    // who ask for reduced motion still get less, and existing sites keep theirs.
-    const settings = await loadThemeSettings(projectDir);
-    const site =
-      settings && "motion" in settings.properties
-        ? await local.store.updateSite({
-            ...seeded,
-            theme: {
-              ...seeded.theme,
-              config: { ...(seeded.theme.config ?? {}), motion: "standard" },
-            },
-          })
-        : seeded;
-    // RFC-0006 owner decision 4: new projects record cookie-less analytics by default.
-    // RFC-0007 §15.4: reader comments are available to the deployment, but stay off for the site
-    // until someone turns them on in Studio (D4).
-    await writeProjectConfig(projectDir, {
-      siteId: site.id,
-      dataDir,
-      analytics: { enabled: true },
-      comments: { available: true },
-    });
-    log(`seeded site ${site.id} (${name}) in ${dataDir}/`);
-    return { projectDir, siteId: site.id, linked: repo !== undefined };
-  } finally {
-    await local.close();
-  }
+  const site = await seedProjectSite(projectDir, { dataDir, name, slug });
+  // RFC-0006 owner decision 4: new projects record cookie-less analytics by default.
+  // RFC-0007 §15.4: reader comments are available to the deployment, but stay off for the site
+  // until someone turns them on in Studio (D4).
+  await writeProjectConfig(projectDir, {
+    siteId: site.id,
+    dataDir,
+    analytics: { enabled: true },
+    comments: { available: true },
+  });
+  log(`seeded site ${site.id} (${name}) in ${dataDir}/`);
+  return { projectDir, siteId: site.id, linked: repo !== undefined };
 }

package/dist/src/render-chrome.js

@@ -90,7 +90,8 @@ export function chromeRenderer(
     );
     const endpoint = new Promise        ((resolve, reject) => {
       let err = "";
-      const timer = setTimeout(() => reject(new Error("Chrome did not start")), 10_000);
+      // A cold start on a busy CI runner can take well over 10 s; a warm one is under a second.
+      const timer = setTimeout(() => reject(new Error("Chrome did not start")), 30_000);
       child.stderr?.on("data", (chunk        ) => {
         err += chunk.toString();
         const m = /DevTools listening on (ws:\/\/\S+)/.exec(err);

package/dist/src/seed-site.d.ts

@@ -0,0 +1,7 @@
+import type { Site } from "@cloudhal/core-contracts";
+export declare function seedProjectSite(projectDir: string, input: {
+    dataDir: string;
+    name: string;
+    slug: string;
+    siteId?: string;
+}): Promise<Site>;

package/dist/src/seed-site.js

@@ -0,0 +1,34 @@
+/** The starter site a new project starts with (`cloudhal init`, and a deploy from Workers Builds). */
+import path from "node:path";
+                                                     
+import { seedStarterSite } from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { loadThemeSettings } from "./blocks.js";
+
+export async function seedProjectSite(
+  projectDir        ,
+  input                                                                  ,
+)                {
+  const local = await openLocalStore(path.join(projectDir, input.dataDir));
+  try {
+    const seeded = await seedStarterSite(local.store, {
+      name: input.name,
+      slug: input.slug,
+      ...(input.siteId ? { siteId: input.siteId } : {}),
+    });
+    // RFC-0024 decision 4: new sites start with standard motion when the theme offers it; readers
+    // who ask for reduced motion still get less, and existing sites keep theirs.
+    const settings = await loadThemeSettings(projectDir);
+    return settings && "motion" in settings.properties
+      ? await local.store.updateSite({
+          ...seeded,
+          theme: {
+            ...seeded.theme,
+            config: { ...(seeded.theme.config ?? {}), motion: "standard" },
+          },
+        })
+      : seeded;
+  } finally {
+    await local.close();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudhal/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "cloudhal — create, run and build Cloudhal sites locally",
   "license": "Apache-2.0",
   "homepage": "https://cloudhal.dev",
@@ -27,16 +27,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@cloudhal/agent-runtime": "0.1.0",
-    "@cloudhal/analytics": "0.1.0",
-    "@cloudhal/api": "0.1.0",
-    "@cloudhal/cloudflare": "0.1.0",
-    "@cloudhal/comments": "0.1.0",
-    "@cloudhal/core-contracts": "0.1.0",
-    "@cloudhal/core-ts": "0.1.0",
-    "@cloudhal/mcp-server": "0.1.0",
-    "@cloudhal/schedules": "0.1.0",
-    "@cloudhal/storage": "0.1.0",
+    "@cloudhal/agent-runtime": "0.2.0",
+    "@cloudhal/analytics": "0.2.0",
+    "@cloudhal/api": "0.2.0",
+    "@cloudhal/cloudflare": "0.2.0",
+    "@cloudhal/comments": "0.2.0",
+    "@cloudhal/core-contracts": "0.2.0",
+    "@cloudhal/core-ts": "0.2.0",
+    "@cloudhal/mcp-server": "0.2.0",
+    "@cloudhal/schedules": "0.2.0",
+    "@cloudhal/storage": "0.2.0",
     "@hono/node-server": "^2.1.4",
     "better-sqlite3": "13.0.3"
   },