/** * `cloudhal deploy` / `push` / `pull` orchestration. The real wrangler runs in `--dry-run` mode * (bundles both Workers, no account needed); the full flow uses a recording wrangler stand-in and * an in-process admin API so ordering, idempotency and the first-deploy push are checked. */ import { mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; import { createApi } from "@cloudhal/api"; import { SiteGraphStore } from "@cloudhal/core-ts"; import { openLocalStore } from "@cloudhal/core-ts/local"; import { ReleaseService } from "@cloudhal/core-ts/releases"; import { MemoryBlobStore } from "@cloudhal/storage"; import { BetterSqlite3Driver } from "@cloudhal/storage/sqlite"; import { afterAll, beforeAll, describe, expect, it } from "vitest"; import { rateLimitNamespaceId } from "../src/cloudflare/config.ts"; import type { WranglerRunner } from "../src/cloudflare/wrangler.ts"; import { domain } from "../src/commands/domain.ts"; import { deploy, init, pullSite, pushSite, readProjectConfig } from "../src/index.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); const STARTER_NODE_MODULES = path.resolve(here, "../../../starters/blog/node_modules"); const jsonc = async (file: string) => JSON.parse((await readFile(file, "utf8")).replace(/^\s*\/\/.*$/gm, "")) as Record< string, unknown >; describe("cloudhal deploy", () => { let tmp: string; let projectDir: string; let studioDir: string; beforeAll(async () => { tmp = await mkdtemp(path.join(os.tmpdir(), "cloudhal-deploycmd-")); projectDir = path.join(tmp, "site"); await init({ dir: projectDir, name: "Deploy Me" }); await symlink(STARTER_NODE_MODULES, path.join(projectDir, "node_modules"), "dir"); studioDir = path.join(tmp, "studio"); await mkdir(studioDir); await writeFile(path.join(studioDir, "index.html"), "Studio"); }); afterAll(async () => { await rm(tmp, { recursive: true, force: true }); }); it("--dry-run bundles both Workers with the real wrangler and generates configs and secrets", async () => { // RFC-0006 §5.5: `analytics.rateLimit` adds the beacon's Rate Limiting binding, which the // real wrangler must accept in its dry run. const cfgFile = path.join(projectDir, "cloudhal.json"); const initial = await readFile(cfgFile, "utf8"); const withLimit = JSON.parse(initial) as Record; // RFC-0007 §6.5: `comments.rateLimit` adds the submissions' binding next to it. expect(withLimit.comments).toEqual({ available: true }); await writeFile( cfgFile, JSON.stringify({ ...withLimit, analytics: { enabled: true, rateLimit: { limit: 60 } }, comments: { available: true, rateLimit: true }, }), ); const r = await deploy({ projectDir, studioDir, dryRun: true }); await writeFile(cfgFile, initial); expect(r.names).toEqual({ site: "deploy-me-site", admin: "deploy-me-admin", database: "deploy-me-db", bucket: "deploy-me-blobs", }); const cfg = await readProjectConfig(projectDir); const deployDir = path.join(projectDir, cfg.dataDir, "deploy"); expect((await stat(path.join(deployDir, "out/site/entry.mjs"))).isFile()).toBe(true); expect((await stat(path.join(deployDir, "out/admin/worker.js"))).isFile()).toBe(true); const site = await jsonc(path.join(projectDir, "wrangler.jsonc")); expect(site).toMatchObject({ name: "deploy-me-site", main: "@cloudhal/astro-renderer/cloudflare-entry", cache: { enabled: true }, // RFC-0006 §11: `cloudhal init` turns analytics on, so the Site Worker writes to WAE analytics_engine_datasets: [{ binding: "ANALYTICS", dataset: "deploy_me_events" }], vars: { CLOUDHAL_SITE_ID: cfg.siteId, CLOUDHAL_ANALYTICS: "on", CLOUDHAL_ANALYTICS_DEFAULTS: JSON.stringify({ enabled: true, uniqueVisitors: false, vitalsOneIn: 5, }), }, ratelimits: [ { name: "ANALYTICS_RL", namespace_id: rateLimitNamespaceId("deploy_me_events"), simple: { limit: 60, period: 60 }, }, { name: "COMMENTS_RL", namespace_id: rateLimitNamespaceId("deploy-me", "comments"), simple: { limit: 10, period: 60 }, }, ], }); expect(rateLimitNamespaceId("deploy_me_events")).toMatch(/^1\d{9}$/); expect(rateLimitNamespaceId("other_events")).not.toBe(rateLimitNamespaceId("deploy_me_events")); expect(rateLimitNamespaceId("deploy-me", "comments")).not.toBe( rateLimitNamespaceId("deploy-me"), ); expect(r.analytics).toEqual({ enabled: true, dataset: "deploy_me_events", cron: true }); expect(r.comments).toEqual({ available: true, cron: true, rateLimit: true }); // the comments key is a secret (`--secrets-file`), never a var in a generated config expect(JSON.stringify(site)).not.toContain("CLOUDHAL_COMMENTS_KEY"); const admin = await jsonc(r.adminConfig); expect(admin).toMatchObject({ name: "deploy-me-admin", compatibility_flags: ["nodejs_compat"], services: [{ binding: "SITE", service: "deploy-me-site" }], assets: { not_found_handling: "none", run_worker_first: ["/api/*", "/mcp", "/mcp/*", "/.well-known/*"], }, // …and the admin Worker reads it through the Analytics SQL binding, with the hourly job analytics: { binding: "ANALYTICS_SQL" }, vars: { CLOUDHAL_ANALYTICS_DATASET: "deploy_me_events", CLOUDHAL_ANALYTICS_BUDGET: "8000", CLOUDHAL_ANALYTICS_DEFAULTS: JSON.stringify({ enabled: true, uniqueVisitors: false, vitalsOneIn: 5, }), CLOUDHAL_COMMENTS_AVAILABLE: "true", CLOUDHAL_SCHEDULER: "cron", }, // RFC-0008 §8.2–§8.3: the scheduler's minute tick in the old slot, and the clock declared triggers: { crons: ["* * * * *"] }, durable_objects: { bindings: [ { name: "SCHEDULER_CLOCK", class_name: "SchedulerClock" }, { name: "BUILD_ROOMS", class_name: "BuildRoom" }, ], }, migrations: [ { tag: "v1", new_sqlite_classes: ["SchedulerClock"] }, { tag: "v2", new_sqlite_classes: ["BuildRoom"] }, ], }); expect(r.scheduler).toBe("cron"); // the generated entry exports the Durable Object class next to the Worker expect(await readFile(path.join(deployDir, "admin/worker.ts"), "utf8")).toContain( 'export { SchedulerClock } from "@cloudhal/cloudflare/admin";', ); expect(await readFile(path.join(deployDir, "admin/worker.ts"), "utf8")).toContain( 'export { BuildRoom } from "@cloudhal/cloudflare/admin";', ); expect(JSON.stringify(admin)).not.toContain("CLOUDHAL_COMMENTS_KEY"); const secretsFile = path.join(deployDir, "secrets.json"); expect((await stat(secretsFile)).mode & 0o777).toBe(0o600); const secrets = JSON.parse(await readFile(secretsFile, "utf8")) as Record; expect(Object.keys(secrets).sort()).toEqual([ "BETTER_AUTH_SECRET", "CLOUDHAL_COMMENTS_KEY", "CLOUDHAL_DEPLOY_TOKEN", "CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN", "CLOUDHAL_SETUP_TOKEN", "MCP_STATE_KEY", ]); for (const v of Object.values(secrets)) expect(v.length).toBeGreaterThanOrEqual(32); // stable across runs await deploy({ projectDir, studioDir, dryRun: true }); expect(JSON.parse(await readFile(secretsFile, "utf8"))).toEqual(secrets); // RFC-0008: the scheduler keeps its trigger whatever analytics and comments say. Wrangler // accepts both configs. await writeFile( cfgFile, JSON.stringify({ ...withLimit, analytics: { enabled: false }, domains: { site: "news.example.com" }, }), ); const commentsOnly = await deploy({ projectDir, studioDir, dryRun: true }); const siteC = await jsonc(path.join(projectDir, "wrangler.jsonc")); expect(siteC.vars).toEqual({ CLOUDHAL_SITE_ID: cfg.siteId, CLOUDHAL_SITE_HOSTS: "news.example.com", }); expect(siteC.ratelimits).toBeUndefined(); const adminC = await jsonc(commentsOnly.adminConfig); expect(adminC.analytics).toBeUndefined(); // RFC-0008 §8.2, §11.6: the tick budget and the automations switch are always written expect(adminC.vars).toEqual({ CLOUDHAL_SITE_ID: cfg.siteId, CLOUDHAL_COMMENTS_AVAILABLE: "true", CLOUDHAL_SCHEDULER: "cron", CLOUDHAL_TICK_BUDGET: "free", CLOUDHAL_AUTOMATIONS: "on", }); expect(commentsOnly.schedules).toEqual({ automations: true, plan: "free" }); expect(adminC.triggers).toEqual({ crons: ["* * * * *"] }); expect(commentsOnly.comments).toEqual({ available: true, cron: true }); await writeFile( cfgFile, JSON.stringify({ ...withLimit, analytics: { enabled: false }, comments: { available: false }, // the deployment's automations kill switch and a Workers Paid account (§8.2, §11.6) schedules: { automations: false, plan: "paid" }, }), ); const none = await deploy({ projectDir, studioDir, dryRun: true }); const adminN = await jsonc(none.adminConfig); expect(adminN.vars).toEqual({ CLOUDHAL_SITE_ID: cfg.siteId, CLOUDHAL_COMMENTS_AVAILABLE: "false", CLOUDHAL_SCHEDULER: "cron", CLOUDHAL_TICK_BUDGET: "paid", CLOUDHAL_AUTOMATIONS: "off", }); expect(none.schedules).toEqual({ automations: false, plan: "paid" }); expect(adminN.triggers).toEqual({ crons: ["* * * * *"] }); expect(none.comments).toEqual({ available: false }); await writeFile(cfgFile, initial); }); it("provisions, deploys site before admin, pushes once, and keeps the deployment as source of truth", async () => { // an in-process "deployed" admin API const sql = await BetterSqlite3Driver.open(":memory:"); const blobs = new MemoryBlobStore(); const remote = new SiteGraphStore({ sql, blobs }); await remote.init(); const cfg = await readProjectConfig(projectDir); const secrets = JSON.parse( await readFile(path.join(projectDir, cfg.dataDir, "deploy/secrets.json"), "utf8"), ) as Record; const app = createApi({ store: remote, admin: { deployToken: secrets.CLOUDHAL_DEPLOY_TOKEN as string, storage: { sql, blobs } }, }); const purges: string[] = []; const fakeFetch = (async (input: RequestInfo | URL, init?: RequestInit) => { const req = new Request(input, init); // the Site Worker's purge endpoint (analytics switched on: the script tag must appear) if (new URL(req.url).pathname === "/__cloudhal/purge") { purges.push(`${new URL(req.url).host} ${req.headers.get("authorization")}`); return new Response("ok"); } return app.fetch(req); }) as typeof fetch; const calls: string[] = []; const secretNames: string[][] = []; let databaseCreated = false; const lifecycleAdds: string[][] = []; const wrangler: WranglerRunner = async (args) => { calls.push(args.filter((a) => !a.includes("/")).join(" ")); if (args.includes("--secrets-file")) secretNames.push( Object.keys( JSON.parse( await readFile(args[args.indexOf("--secrets-file") + 1] as string, "utf8"), ) as Record, ).sort(), ); const ok = (stdout = "", records: Record[] = []) => ({ code: 0, stdout, stderr: "", records, }); if (args[0] === "d1" && args[1] === "info") return databaseCreated ? ok(JSON.stringify({ uuid: "11111111-2222-3333-4444-555555555555" })) : { code: 1, stdout: "", stderr: "not found", records: [] }; if (args[0] === "d1" && args[1] === "create") { databaseCreated = true; return ok(); } if (args[2] === "lifecycle" && args[3] === "list") return ok(lifecycleAdds.map((a) => `name: ${a[5]}\nprefix: ${a[6]}`).join("\n\n")); if (args[2] === "lifecycle" && args[3] === "add") lifecycleAdds.push(args); if (args[0] === "deploy" && args.includes("-c")) return ok("", [{ type: "deploy", targets: ["deploy-me-admin.acme.workers.dev"] }]); if (args[0] === "deploy") return ok("", [{ type: "deploy", targets: ["https://deploy-me-site.acme.workers.dev"] }]); return ok(); }; const lines: string[] = []; const first = await deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000, log: (l) => lines.push(l), }); expect(calls).toEqual([ "d1 info deploy-me-db --json", "d1 create deploy-me-db", "d1 info deploy-me-db --json", "r2 bucket create deploy-me-blobs", "r2 bucket lifecycle list deploy-me-blobs", "r2 bucket lifecycle add deploy-me-blobs cloudhal-bundles --expire-days 30 --force", "deploy --secrets-file", "deploy -c --secrets-file", ]); // RFC-0010: snapshot bundles expire after 30 days; node blobs are untouched expect(lifecycleAdds).toEqual([ [ "r2", "bucket", "lifecycle", "add", "deploy-me-blobs", "cloudhal-bundles", "bundles/", "--expire-days", "30", "--force", ], ]); expect(first).toMatchObject({ siteUrl: "https://deploy-me-site.acme.workers.dev", adminUrl: "https://deploy-me-admin.acme.workers.dev", pushed: true, }); // analytics went on with this deploy: one purge of the site's cache, with the purge token expect(first.analytics).toEqual({ enabled: true, dataset: "deploy_me_events", cron: true, purged: true, }); expect(purges).toEqual([ `deploy-me-site.acme.workers.dev Bearer ${secrets.CLOUDHAL_PURGE_TOKEN}`, ]); // RFC-0007: comments available (off per site), the key bound to both Workers, never printed; // a non-interactive first deploy creates the database in the automatic location and says how // to choose the EU jurisdiction instead. expect(first.comments).toEqual({ available: true, cron: true, purged: true }); expect(first.databaseCreated).toBe("auto"); expect(secretNames).toEqual([ ["CLOUDHAL_COMMENTS_KEY", "CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN"], [ "BETTER_AUTH_SECRET", "CLOUDHAL_COMMENTS_KEY", "CLOUDHAL_DEPLOY_TOKEN", "CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN", "CLOUDHAL_SETUP_TOKEN", "MCP_STATE_KEY", ], ]); const output = lines.join("\n"); expect(output).toMatch(/comments: available on this deployment, and off for every site/); expect(output).toMatch(/automatic location \(non-interactive\).*--jurisdiction eu/); expect(output).not.toContain(secrets.CLOUDHAL_COMMENTS_KEY as string); expect( JSON.parse(await readFile(path.join(projectDir, cfg.dataDir, "deploy/state.json"), "utf8")), ).toMatchObject({ comments: "on", jurisdiction: "auto", }); // the owner account can only be created through the one-time setup link expect(first.setupUrl).toBe( `https://deploy-me-admin.acme.workers.dev/login#setup=${secrets.CLOUDHAL_SETUP_TOKEN}`, ); // wrangler's secret files existed only during the deploy const leftovers = (await import("node:fs/promises")).readdir( path.join(projectDir, cfg.dataDir, "deploy"), ); expect((await leftovers).filter((f) => f.endsWith("-secrets.json"))).toEqual([]); const siteCfg = await jsonc(path.join(projectDir, "wrangler.jsonc")); expect((siteCfg.d1_databases as { database_id: string }[])[0]?.database_id).toBe( "11111111-2222-3333-4444-555555555555", ); // the deployment got the site, with its public hostname for preview links expect((await remote.getSite(cfg.siteId))?.domains).toEqual([ { hostname: "deploy-me-site.acme.workers.dev", primary: true }, ]); // an agent edits the deployment; a redeploy must not push over it const about = (await remote.listPages(cfg.siteId)).find((p) => p.path === "/about"); await remote.updatePage({ ...(about as NonNullable), title: "Edited in production", }); calls.length = 0; const second = await deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000, }); expect(second.pushed).toBe(false); expect(second.setupUrl).toBeUndefined(); // analytics stayed on, comments stayed available: no second purge expect(second.analytics.purged).toBe(false); expect(second.comments).toEqual({ available: true, cron: true }); expect(second.databaseCreated).toBeUndefined(); expect(purges).toHaveLength(1); expect(calls[0]).toBe("d1 info deploy-me-db --json"); expect(calls).not.toContain("d1 create deploy-me-db"); // the rule is there already: listed, not added twice expect(calls).toContain("r2 bucket lifecycle list deploy-me-blobs"); expect(lifecycleAdds).toHaveLength(1); expect((await remote.getPage(about?.id as string))?.title).toBe("Edited in production"); // push refuses to overwrite; pull brings production home; push --replace would win await expect(pushSite({ projectDir, fetch: fakeFetch })).rejects.toThrow(/diverged/); await pullSite({ projectDir, fetch: fakeFetch, replace: true }); const local = await openLocalStore(path.join(projectDir, cfg.dataDir)); expect((await local.store.getPage(about?.id as string))?.title).toBe("Edited in production"); await local.close(); const same = await pushSite({ projectDir, fetch: fakeFetch }); expect(same.message).toContain('"unchanged":true'); }); it("routes custom domains to both Workers and makes the site's one primary; removing restores workers.dev", async () => { const sql = await BetterSqlite3Driver.open(":memory:"); const blobs = new MemoryBlobStore(); const remote = new SiteGraphStore({ sql, blobs }); await remote.init(); const cfg = await readProjectConfig(projectDir); const secrets = JSON.parse( await readFile(path.join(projectDir, cfg.dataDir, "deploy/secrets.json"), "utf8"), ) as Record; const app = createApi({ store: remote, admin: { deployToken: secrets.CLOUDHAL_DEPLOY_TOKEN as string, storage: { sql, blobs } }, }); const fakeFetch = (async (input: RequestInfo | URL, init?: RequestInit) => app.fetch(new Request(input, init))) as typeof fetch; // The first `d1 info` fails as a transient API error would; `d1 create` then finds the // database already there, and the deploy reads its id again instead of stopping. let infoFailures = 1; const wrangler: WranglerRunner = async (args) => { const ok = (stdout = "", records: Record[] = []) => ({ code: 0, stdout, stderr: "", records, }); if (args[0] === "d1" && args[1] === "info" && infoFailures-- > 0) return { code: 1, stdout: "", stderr: "A request to the Cloudflare API failed", records: [], }; if (args[0] === "d1" && args[1] === "create") return { code: 1, stdout: "", stderr: "A database with that name already exists", records: [], }; if (args[0] === "d1" && args[1] === "info") return ok(JSON.stringify({ uuid: "11111111-2222-3333-4444-555555555555" })); if (args[0] === "deploy" && args.includes("-c")) return ok("", [{ type: "deploy", targets: ["deploy-me-admin.acme.workers.dev"] }]); if (args[0] === "deploy") return ok("", [{ type: "deploy", targets: ["https://deploy-me-site.acme.workers.dev"] }]); return ok(); }; const run = () => deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000 }); // the command validates and normalises what a person types await expect(domain({ projectDir, set: { site: "not a host" } })).rejects.toThrow( /not a hostname/, ); await expect(domain({ projectDir, set: { site: "x.acme.workers.dev" } })).rejects.toThrow( /workers\.dev/, ); await expect( domain({ projectDir, set: { site: "a.example.com", studio: "A.example.com" } }), ).rejects.toThrow(/different hostnames/); expect( await domain({ projectDir, set: { site: "https://News.Example.com/", studio: "studio.example.com" }, }), ).toEqual({ site: "news.example.com", studio: "studio.example.com" }); expect((await readProjectConfig(projectDir)).domains).toEqual({ site: "news.example.com", studio: "studio.example.com", }); // #48: the local site takes it as its primary domain before any deploy (`cloudhal build`) const before = await openLocalStore(path.join(projectDir, cfg.dataDir)); expect((await before.store.getSite(cfg.siteId))?.domains[0]).toEqual({ hostname: "news.example.com", primary: true, }); await before.close(); // #49: hosts that answer with a 301 to the site's domain await expect(domain({ projectDir, set: { redirects: ["news.example.com"] } })).rejects.toThrow( /cannot redirect/, ); expect( await domain({ projectDir, set: { redirects: ["WWW.news.example.com", "www.news.example.com"] }, }), ).toMatchObject({ redirects: ["www.news.example.com"] }); const r = await run(); expect(r).toMatchObject({ customSiteUrl: "https://news.example.com", customStudioUrl: "https://studio.example.com", }); const siteCfg = await jsonc(path.join(projectDir, "wrangler.jsonc")); expect(siteCfg.routes).toEqual([ { pattern: "news.example.com", custom_domain: true }, { pattern: "www.news.example.com", custom_domain: true }, ]); expect(siteCfg.vars).toMatchObject({ CLOUDHAL_REDIRECT_HOSTS: "www.news.example.com", CLOUDHAL_REDIRECT_TO: "news.example.com", }); const adminCfg = await jsonc(r.adminConfig); expect(adminCfg.routes).toEqual([{ pattern: "studio.example.com", custom_domain: true }]); // the custom domain is primary on the deployment and locally; workers.dev stays secondary const expected = [ { hostname: "news.example.com", primary: true }, { hostname: "deploy-me-site.acme.workers.dev", primary: false }, ]; expect((await remote.getSite(cfg.siteId))?.domains).toEqual(expected); const local = await openLocalStore(path.join(projectDir, cfg.dataDir)); expect((await local.store.getSite(cfg.siteId))?.domains).toEqual(expected); await local.close(); // removing it: no routes, and workers.dev is primary again expect(await domain({ projectDir, remove: ["site", "studio"] })).toBeUndefined(); expect((await readProjectConfig(projectDir)).domains).toBeUndefined(); const again = await run(); expect(again.customSiteUrl).toBeUndefined(); expect((await jsonc(path.join(projectDir, "wrangler.jsonc"))).routes).toBeUndefined(); expect((await remote.getSite(cfg.siteId))?.domains[0]).toEqual({ hostname: "deploy-me-site.acme.workers.dev", primary: true, }); }); it("analytics: existing projects are asked (non-interactive: off), wrangler is checked, the cron limit is survived", async () => { const sql = await BetterSqlite3Driver.open(":memory:"); const blobs = new MemoryBlobStore(); const remote = new SiteGraphStore({ sql, blobs }); await remote.init(); const cfg = await readProjectConfig(projectDir); const secrets = JSON.parse( await readFile(path.join(projectDir, cfg.dataDir, "deploy/secrets.json"), "utf8"), ) as Record; const app = createApi({ store: remote, admin: { deployToken: secrets.CLOUDHAL_DEPLOY_TOKEN as string, storage: { sql, blobs } }, }); const purges: string[] = []; const fakeFetch = (async (input: RequestInfo | URL, init?: RequestInit) => { const req = new Request(input, init); if (new URL(req.url).pathname === "/__cloudhal/purge") { purges.push(req.url); return new Response("ok"); } return app.fetch(req); }) as typeof fetch; let cronRefusals = 0; const adminDeploys: string[] = []; const wrangler: WranglerRunner = async (args) => { const ok = (stdout = "", records: Record[] = []) => ({ code: 0, stdout, stderr: "", records, }); if (args[0] === "d1" && args[1] === "info") return ok(JSON.stringify({ uuid: "11111111-2222-3333-4444-555555555555" })); if (args[0] === "deploy" && args.includes("-c")) { const config = await jsonc(args[args.indexOf("-c") + 1] as string); adminDeploys.push(JSON.stringify((config.triggers as { crons: string[] }).crons)); if (cronRefusals-- > 0 && (config.triggers as { crons: string[] }).crons.length > 0) return { code: 1, stdout: "", stderr: "✘ [ERROR] A request to the Cloudflare API failed: You have exceeded the limit of 5 cron triggers. [code: 10057]", records: [], }; return ok("", [{ type: "deploy", targets: ["deploy-me-admin.acme.workers.dev"] }]); } if (args[0] === "deploy") return ok("", [{ type: "deploy", targets: ["https://deploy-me-site.acme.workers.dev"] }]); return ok(); }; const lines: string[] = []; const run = (extra: Partial[0]> = {}) => deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000, log: (l) => lines.push(l), ...extra, }); // A project from before RFC-0006 has no `analytics` key; `media` (the starter's) survives. const file = path.join(projectDir, "cloudhal.json"); const raw = JSON.parse(await readFile(file, "utf8")) as Record; const { analytics: _a, ...old } = raw; await writeFile(file, JSON.stringify({ ...old, media: { transform: "none" } })); // Non-interactive: analytics stay off and the deploy says how to turn them on. The bindings, // vars and cron are gone, and the site cache is purged once so the script tag disappears. const off = await run(); expect(off.analytics).toEqual({ enabled: false, purged: true }); expect(lines.join("\n")).toMatch(/analytics: off\. Turn on cookie-less analytics/); const siteOff = await jsonc(path.join(projectDir, "wrangler.jsonc")); expect(siteOff.analytics_engine_datasets).toBeUndefined(); expect(siteOff.vars).toEqual({ CLOUDHAL_SITE_ID: cfg.siteId }); const adminOff = await jsonc(off.adminConfig); expect(adminOff.analytics).toBeUndefined(); // the scheduler keeps its minute trigger (RFC-0008 §8.2) expect(adminOff.vars).toEqual({ CLOUDHAL_SITE_ID: cfg.siteId, CLOUDHAL_COMMENTS_AVAILABLE: "true", CLOUDHAL_SCHEDULER: "cron", CLOUDHAL_TICK_BUDGET: "free", CLOUDHAL_AUTOMATIONS: "on", }); expect(lines.join("\n")).toMatch(/Workers Free tick budget .* `--plan paid` \(remembered\)/); expect(adminOff.triggers).toEqual({ crons: ["* * * * *"] }); expect(JSON.parse(await readFile(file, "utf8")).analytics).toBeUndefined(); expect(purges).toHaveLength(1); // Interactive: the question is asked once and the answer saved. An old wrangler stops the // deploy before anything is generated, with what to do. const asked: string[] = []; await expect( run({ prompt: async (q) => { asked.push(q); return true; }, wranglerVersion: "4.120.0", }), ).rejects.toThrow( "Analytics needs wrangler 4.145 or newer (found 4.120.0). Run `pnpm add -D wrangler@^4.148`, or set `analytics.enabled: false` in cloudhal.json.", ); expect(asked).toEqual(["Turn on cookie-less analytics for Deploy Me? (Y/n) "]); const saved = JSON.parse(await readFile(file, "utf8")) as Record; expect(saved.analytics).toEqual({ enabled: true }); expect(saved.media).toEqual({ transform: "none" }); // The account has no free cron slot: the admin Worker goes without the trigger, the // Durable Object clock ticks instead, and the deploy says so in the RFC's words (§16). cronRefusals = 1; adminDeploys.length = 0; const on = await run({ prompt: async () => false, wranglerVersion: "4.148.0" }); expect(adminDeploys).toEqual(['["* * * * *"]', "[]"]); expect(on.scheduler).toBe("alarm"); expect(on.analytics).toEqual({ enabled: true, dataset: "deploy_me_events", cron: false, purged: true, }); expect(lines).toContain( "Cloudflare refused the cron trigger: this account uses all its cron triggers (Workers Free allows 5). The scheduler runs on a Durable Object alarm instead.", ); expect(on.comments).toEqual({ available: true, cron: false }); const adminOn = await jsonc(on.adminConfig); expect(adminOn.triggers).toEqual({ crons: [] }); expect(adminOn.vars).toMatchObject({ CLOUDHAL_COMMENTS_AVAILABLE: "true", CLOUDHAL_SCHEDULER: "alarm", }); expect(adminOn.vars).not.toHaveProperty("CLOUDHAL_ANALYTICS_CRON"); expect(adminOn.vars).not.toHaveProperty("CLOUDHAL_COMMENTS_CRON"); expect(adminOn.durable_objects).toEqual({ bindings: [ { name: "SCHEDULER_CLOCK", class_name: "SchedulerClock" }, { name: "BUILD_ROOMS", class_name: "BuildRoom" }, ], }); expect(purges).toHaveLength(2); expect( JSON.parse(await readFile(path.join(projectDir, cfg.dataDir, "deploy/state.json"), "utf8")) .scheduler, ).toBe("alarm"); // The next deploy stays on the clock (no refused attempt), and says how to try cron again. adminDeploys.length = 0; lines.length = 0; const again = await run({ prompt: async () => false, wranglerVersion: "4.148.0" }); expect(again.scheduler).toBe("alarm"); expect(adminDeploys).toEqual(["[]"]); expect(lines.join("\n")).toMatch(/`cloudhal deploy --scheduler cron` tries the cron trigger/); // `--scheduler cron` tries the trigger again; the slot is free now. adminDeploys.length = 0; const back = await run({ prompt: async () => false, wranglerVersion: "4.148.0", scheduler: "cron", }); expect(back.scheduler).toBe("cron"); expect(adminDeploys).toEqual(['["* * * * *"]']); // RFC-0008 §8.2: `--plan paid` sizes ticks for Workers Paid and is remembered in state.json, // so the next deploy without the flag keeps it; `--plan free` goes back. const stateFile = path.join(projectDir, cfg.dataDir, "deploy/state.json"); const paid = await run({ prompt: async () => false, wranglerVersion: "4.148.0", plan: "paid" }); expect(paid.schedules).toEqual({ automations: true, plan: "paid" }); expect((await jsonc(paid.adminConfig)).vars).toMatchObject({ CLOUDHAL_TICK_BUDGET: "paid" }); expect(JSON.parse(await readFile(stateFile, "utf8")).plan).toBe("paid"); lines.length = 0; const kept = await run({ prompt: async () => false, wranglerVersion: "4.148.0" }); expect(kept.schedules.plan).toBe("paid"); expect((await jsonc(kept.adminConfig)).vars).toMatchObject({ CLOUDHAL_TICK_BUDGET: "paid", CLOUDHAL_AUTOMATIONS: "on", }); expect(lines.join("\n")).not.toMatch(/Workers Free tick budget/); const free = await run({ prompt: async () => false, wranglerVersion: "4.148.0", plan: "free" }); expect((await jsonc(free.adminConfig)).vars).toMatchObject({ CLOUDHAL_TICK_BUDGET: "free" }); expect(JSON.parse(await readFile(stateFile, "utf8")).plan).toBe("free"); await expect(run({ plan: "pro" as never })).rejects.toThrow("--plan must be free or paid"); }); it("comments and data location: --jurisdiction eu only when the database is created, availability switches purge once", async () => { const sql = await BetterSqlite3Driver.open(":memory:"); const blobs = new MemoryBlobStore(); const remote = new SiteGraphStore({ sql, blobs }); await remote.init(); const cfg = await readProjectConfig(projectDir); const secrets = JSON.parse( await readFile(path.join(projectDir, cfg.dataDir, "deploy/secrets.json"), "utf8"), ) as Record; const app = createApi({ store: remote, admin: { deployToken: secrets.CLOUDHAL_DEPLOY_TOKEN as string, storage: { sql, blobs } }, }); const purges: string[] = []; const fakeFetch = (async (input: RequestInfo | URL, init?: RequestInit) => { const req = new Request(input, init); if (new URL(req.url).pathname === "/__cloudhal/purge") { purges.push(req.url); return new Response("ok"); } return app.fetch(req); }) as typeof fetch; const created = new Set(); const calls: string[] = []; const wrangler: WranglerRunner = async (args) => { calls.push(args.filter((a) => !a.includes("/")).join(" ")); const ok = (stdout = "", records: Record[] = []) => ({ code: 0, stdout, stderr: "", records, }); if (args[0] === "d1" && args[1] === "info") return created.has(args[2] as string) ? ok(JSON.stringify({ uuid: "11111111-2222-3333-4444-555555555555" })) : { code: 1, stdout: "", stderr: "not found", records: [] }; if (args[0] === "d1" && args[1] === "create") { created.add(args[2] as string); return ok(); } // a token that may not manage lifecycle rules (RFC-0010): a warning, not a failed deploy if (args[2] === "lifecycle" && args[3] === "add") return { code: 1, stdout: "", stderr: "✘ Authentication error [code: 10000]\n", records: [], }; if (args[0] === "deploy" && args.includes("-c")) return ok("", [{ type: "deploy", targets: ["eu-news-admin.acme.workers.dev"] }]); if (args[0] === "deploy") return ok("", [{ type: "deploy", targets: ["https://eu-news-site.acme.workers.dev"] }]); return ok(); }; const lines: string[] = []; const run = (extra: Partial[0]> = {}) => deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000, log: (l) => lines.push(l), name: "eu-news", ...extra, }); await expect(run({ jurisdiction: "us" as never })).rejects.toThrow( '--jurisdiction must be eu (got "us")', ); // A new database: the flag wins over the question, and the database is created in the EU. const asked: string[] = []; const eu = await run({ jurisdiction: "eu", askJurisdiction: async () => { asked.push("asked"); return "auto"; }, }); expect(asked).toEqual([]); expect(calls).toContain("d1 create eu-news-db --jurisdiction eu"); expect(eu.databaseCreated).toBe("eu"); expect(lines.join("\n")).toMatch(/in the EU jurisdiction \(this cannot be changed later\)/); expect(lines.join("\n")).toMatch( /could not set the R2 lifecycle rule for bundles\/ \(✘ Authentication error \[code: 10000\]\)/, ); // The database exists: the flag changes nothing and says so; the question is never asked. calls.length = 0; lines.length = 0; const again = await run({ jurisdiction: "eu", askJurisdiction: async () => { asked.push("asked"); return "eu"; }, }); expect(again.databaseCreated).toBeUndefined(); expect(asked).toEqual([]); expect(calls.filter((c) => c.startsWith("d1 create"))).toEqual([]); expect(lines.join("\n")).toMatch(/already exists, so --jurisdiction changes nothing/); // Interactive, another deployment name: the question decides. Comments switched off for the // deployment: the admin Worker says so and the site cache is purged once (cached pages lose // the comments section). const file = path.join(projectDir, "cloudhal.json"); const raw = JSON.parse(await readFile(file, "utf8")) as Record; await writeFile(file, JSON.stringify({ ...raw, comments: { available: false } })); purges.length = 0; const off = await run({ name: "eu-news-two", askJurisdiction: async () => { asked.push("asked"); return "eu"; }, }); await writeFile(file, JSON.stringify(raw)); expect(asked).toEqual(["asked"]); expect(off.databaseCreated).toBe("eu"); expect(calls).toContain("d1 create eu-news-two-db --jurisdiction eu"); expect(off.comments).toEqual({ available: false, purged: true }); expect((await jsonc(off.adminConfig)).vars).toMatchObject({ CLOUDHAL_COMMENTS_AVAILABLE: "false", }); expect(purges).toHaveLength(1); }); it("schedules (RFC-0008 §16): legacy no-cron deployments start on the clock, the downgrade guard, the push guard", async () => { const sql = await BetterSqlite3Driver.open(":memory:"); const blobs = new MemoryBlobStore(); const remote = new SiteGraphStore({ sql, blobs }); await remote.init(); const cfg = await readProjectConfig(projectDir); const dir = path.join(projectDir, cfg.dataDir, "deploy"); const secrets = JSON.parse(await readFile(path.join(dir, "secrets.json"), "utf8")) as Record< string, string >; const app = createApi({ store: remote, admin: { deployToken: secrets.CLOUDHAL_DEPLOY_TOKEN as string, storage: { sql, blobs } }, }); let status: unknown; const fakeFetch = (async (input: RequestInfo | URL, init?: RequestInit) => { const req = new Request(input, init); const p = new URL(req.url).pathname; if (p === "/__cloudhal/purge") return new Response("ok"); if (p === "/api/admin/schedules/status" && status !== undefined) return Response.json(status); return app.fetch(req); }) as typeof fetch; const adminDeploys: string[] = []; const wrangler: WranglerRunner = async (args) => { const ok = (records: Record[] = []) => ({ code: 0, stdout: "", stderr: "", records, }); if (args[0] === "d1" && args[1] === "info") return { ...ok(), stdout: JSON.stringify({ uuid: "11111111-2222-3333-4444-555555555555" }), }; if (args[0] === "deploy" && args.includes("-c")) { const config = await jsonc(args[args.indexOf("-c") + 1] as string); adminDeploys.push(String((config.vars as Record).CLOUDHAL_SCHEDULER)); return ok([{ type: "deploy", targets: ["deploy-me-admin.acme.workers.dev"] }]); } if (args[0] === "deploy") return ok([{ type: "deploy", targets: ["https://deploy-me-site.acme.workers.dev"] }]); return ok(); }; const lines: string[] = []; const run = (extra: Partial[0]> = {}) => deploy({ projectDir, studioDir, wrangler, fetch: fakeFetch, healthTimeoutMs: 5000, name: "deploy-me", prompt: async () => false, wranglerVersion: "4.148.0", log: (l) => lines.push(l), ...extra, }); // A deployment configured before RFC-0008 without a cron slot (`CLOUDHAL_*_CRON=off`, no // scheduler in its state): read once as `alarm`, and the vars are not written again. const stateFile = path.join(dir, "state.json"); const state = JSON.parse(await readFile(stateFile, "utf8")) as Record; const { scheduler: _s, ...before } = state; await writeFile( stateFile, JSON.stringify({ ...before, adminUrl: "https://deploy-me-admin.acme.workers.dev" }), ); const adminFile = path.join(dir, "admin", "wrangler.jsonc"); const old = await jsonc(adminFile); await writeFile( adminFile, JSON.stringify({ ...old, vars: { CLOUDHAL_COMMENTS_AVAILABLE: "true", CLOUDHAL_COMMENTS_CRON: "off" }, }), ); const legacy = await run(); expect(legacy.scheduler).toBe("alarm"); expect(adminDeploys).toEqual(["alarm"]); expect((await jsonc(adminFile)).vars).not.toHaveProperty("CLOUDHAL_COMMENTS_CRON"); // The downgrade guard: a deployment running a higher schedules level with open releases or // gates refuses older code unless --force-downgrade; with nothing to protect it deploys. status = { engine: { schedulesLevel: 99 }, sites: [{ siteId: cfg.siteId, openReleases: [{ id: "rel_x" }], gatedNodes: 2 }], }; adminDeploys.length = 0; await expect(run({ scheduler: "cron" })).rejects.toThrow( /downgrade the deployment's schedules \(level 99 → 1\) while it has 1 open release\(s\) and 2 page\(s\)/, ); expect(adminDeploys).toEqual([]); lines.length = 0; await run({ scheduler: "cron", forceDowngrade: true }); expect(lines.join("\n")).toMatch( /--force-downgrade: deploying schedules level 1 over level 99/, ); status = { engine: { schedulesLevel: 99 }, sites: [{ siteId: cfg.siteId, openReleases: [], gatedNodes: 0 }], }; await expect(run({ scheduler: "cron" })).resolves.toMatchObject({ scheduler: "cron" }); status = undefined; // the in-process deployment answers itself (level 1): no guard // The push guard: open releases on the deployment refuse a push unless --cancel-schedules. await pushSite({ projectDir, fetch: fakeFetch, replace: true }); const entry = (await remote.listContentEntries(cfg.siteId))[0]; if (!entry) throw new Error("no entry"); await remote.updateContentEntry({ ...entry, title: "Scheduled retitle" }); const releases = new ReleaseService({ graph: remote }); const { release } = await releases.create({ siteId: cfg.siteId, set: [entry.id], createdBy: { kind: "human", id: "user_deployer01", name: "Op" }, when: { at: new Date(Date.now() + 3_600_000).toISOString() }, }); await expect(pushSite({ projectDir, fetch: fakeFetch, replace: true })).rejects.toThrow( new RegExp(`open releases[\\s\\S]*${release.id} draft[\\s\\S]*--cancel-schedules`), ); await pushSite({ projectDir, fetch: fakeFetch, replace: true, cancelSchedules: true }); expect((await releases.get(cfg.siteId, release.id)).release).toMatchObject({ state: "canceled", outcome: { kind: "canceled", by: { id: "sys_operator01" } }, }); }); });