@cloudhal/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,98 @@
+/** `cloudhal deploy` options and result. */
+import type { SchedulerTicker, SchedulesDeployment, WorkersPlan, workerNames } from "../../cloudflare/config.js";
+import type { WranglerRunner } from "../../cloudflare/wrangler.js";
+import type { StudioBuilder } from "../../studio-build.js";
+import type { Jurisdiction } from "./state.js";
+export interface DeployOptions {
+    readonly projectDir: string;
+    /** Base name for Workers and resources (default: the site slug). */
+    readonly name?: string;
+    readonly studioDir?: string;
+    readonly dryRun?: boolean;
+    readonly log?: (line: string) => void;
+    /** Injected in tests. */
+    readonly wrangler?: WranglerRunner;
+    readonly fetch?: typeof fetch;
+    /** How long to wait for a freshly deployed admin Worker to answer. Default 2 minutes. */
+    readonly healthTimeoutMs?: number;
+    /**
+     * Asks a yes/no question in a terminal (the analytics upgrade prompt). Absent: non-interactive,
+     * so a project without an `analytics` key keeps analytics off.
+     */
+    readonly prompt?: (question: string) => Promise<boolean>;
+    /** The project's wrangler version (tests); read from its `package.json` otherwise. */
+    readonly wranglerVersion?: string;
+    /**
+     * `--jurisdiction eu`: create the D1 database in the EU jurisdiction (RFC-0007 D7). Only used
+     * when this deploy creates the database; a jurisdiction cannot be changed later.
+     */
+    readonly jurisdiction?: Jurisdiction;
+    /**
+     * Asks where a new D1 database should live (a terminal). Absent: non-interactive, so a new
+     * database gets the automatic location unless `jurisdiction` says otherwise.
+     */
+    readonly askJurisdiction?: () => Promise<Jurisdiction>;
+    /**
+     * `--scheduler cron|alarm`: the ticker to deploy with (RFC-0008 §8.3). Default: what the last
+     * deploy used, else `cron`; a refused cron trigger always falls back to `alarm`.
+     */
+    readonly scheduler?: SchedulerTicker;
+    /**
+     * `--force-downgrade`: deploy code with a lower schedules level than the deployment's even while
+     * releases are open or gates are set (RFC-0008 Compatibility). Holds and gates stop working.
+     */
+    readonly forceDowngrade?: boolean;
+    /**
+     * `--plan free|paid`: the account's Workers plan, which sizes each scheduler tick (RFC-0008 §8.2,
+     * `CLOUDHAL_TICK_BUDGET`). Default: `cloudhal.json` `schedules.plan`, else what the last deploy
+     * used, else `free`. Remembered in `state.json`.
+     */
+    readonly plan?: WorkersPlan;
+    /**
+     * `--no-build-studio` (`false`): never run the Studio build. Running from the monorepo, a missing
+     * `apps/studio/dist` or one older than the Studio sources then fails the deploy instead of being
+     * rebuilt. A published install ships Studio prebuilt and is never checked.
+     */
+    readonly buildStudio?: boolean;
+    /** Injected in tests: runs the Studio build. */
+    readonly studioBuilder?: StudioBuilder;
+}
+export interface DeployResult {
+    dryRun: boolean;
+    names: ReturnType<typeof workerNames>;
+    siteConfig: string;
+    adminConfig: string;
+    siteUrl?: string | undefined;
+    adminUrl?: string | undefined;
+    pushed?: boolean;
+    /** First deploy only: open it to create the owner account. */
+    setupUrl?: string;
+    /** Custom domains from cloudhal.json, routed by this deploy. */
+    customSiteUrl?: string;
+    customStudioUrl?: string;
+    /** What drives the scheduler (RFC-0008 §8.3): the minute cron trigger, or the clock's alarm. */
+    scheduler: SchedulerTicker;
+    /** The tick budget and the automations switch as deployed (RFC-0008 §8.2, §11.6). */
+    schedules: SchedulesDeployment;
+    /** Site analytics as deployed (RFC-0006 §11). */
+    analytics: {
+        enabled: boolean;
+        dataset?: string;
+        /** The cron trigger is in place (false: the scheduler runs on the Durable Object alarm). */
+        cron?: boolean;
+        /** The site's cache was purged because analytics switched on or off. */
+        purged?: boolean;
+    };
+    /** Reader comments as deployed (RFC-0007 §15.4); off per site until turned on in Studio. */
+    comments: {
+        available: boolean;
+        /** The cron trigger is in place (false: the scheduler runs on the Durable Object alarm). */
+        cron?: boolean;
+        /** The `COMMENTS_RL` Rate Limiting binding was added. */
+        rateLimit?: boolean;
+        /** The site's cache was purged because availability changed. */
+        purged?: boolean;
+    };
+    /** Set when this deploy created the D1 database: where it lives (RFC-0007 D7). */
+    databaseCreated?: Jurisdiction;
+}

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

@@ -0,0 +1,106 @@
+/** `cloudhal deploy` options and result. */
+
+             
+                  
+                      
+              
+              
+                                    
+                                                                   
+                                                           
+                                               
+
+                                
+                              
+                                                                      
+                         
+                              
+                            
+                                        
+                           
+                                     
+                                
+                                                                                           
+                                    
+     
+                                                                                                  
+                                                                 
+     
+                                                           
+                                                                                        
+                                    
+     
+                                                                                                
+                                                                                   
+     
+                                       
+     
+                                                                                             
+                                                                               
+     
+                                                         
+     
+                                                                                                
+                                                                                   
+     
+                                       
+     
+                                                                                                   
+                                                                                               
+     
+                                    
+     
+                                                                                                    
+                                                                                                  
+                                                   
+     
+                              
+     
+                                                                                                    
+                                                                                                   
+                                                                             
+     
+                                 
+                                                  
+                                         
+ 
+
+                               
+                  
+                                        
+                     
+                      
+                               
+                                
+                   
+                                                                
+                    
+                                                                  
+                         
+                           
+                                                                                                  
+                             
+                                                                                       
+                                 
+                                                   
+              
+                     
+                     
+                                                                                                
+                   
+                                                                            
+                     
+    
+                                                                                              
+             
+                       
+                                                                                                
+                   
+                                                             
+                        
+                                                                    
+                     
+    
+                                                                                    
+                                 
+ 

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

@@ -0,0 +1,55 @@
+/**
+ * The phases of `cloudhal deploy` before anything is uploaded: the project and its site, analytics
+ * and comments, the Studio build, Cloudflare resources, the scheduler and plan, the site Worker.
+ */
+import { type AnalyticsDeployment, type CommentsDeployment, type DeploymentNames, type ObservabilityDeployment, type SchedulerTicker, type SchedulesDeployment, type WorkersPlan } from "../../cloudflare/config.js";
+import type { DeployContext } from "./context.js";
+import type { DeployOptions } from "./options.js";
+import { type Jurisdiction } from "./state.js";
+export declare function checkOptions(options: DeployOptions): void;
+/** The project, its site, the last deploy, the names; analytics decided before anything is generated. */
+export declare function loadDeploy(options: DeployOptions): Promise<DeployContext>;
+/** 0. analytics bindings (wrangler ≥ 4.145); 0b. reader comments (RFC-0007 §15.4). */
+export declare function analyticsAndComments(ctx: DeployContext): Promise<{
+    analytics: AnalyticsDeployment | undefined;
+    comments: CommentsDeployment;
+}>;
+/**
+ * The built Studio. From the monorepo, `apps/studio/dist` is only as new as its last build: build
+ * it (or, with --no-build-studio, refuse) when it is missing or Studio sources changed since. A
+ * published install ships Studio prebuilt and is never checked.
+ */
+export declare function studioDirFor(ctx: DeployContext): Promise<string>;
+/** 1. resources: D1, R2, KV (skipped on a dry run); the database id goes into the configs. */
+export declare function provision(ctx: DeployContext): Promise<{
+    withIds: DeploymentNames;
+    databaseCreated: Jurisdiction | undefined;
+}>;
+export interface DeploySettings {
+    scheduler: SchedulerTicker;
+    plan: WorkersPlan;
+    schedules: SchedulesDeployment;
+    observability: ObservabilityDeployment;
+}
+/**
+ * 2c. the scheduler's ticker: asked for, else the last deploy's, else cron (RFC-0008 §8.3). A
+ * deployment last configured without a cron slot (`CLOUDHAL_*_CRON=off`) starts on the alarm.
+ * 2d. the tick budget and the automations switch (RFC-0008 §8.2, §11.6), and what this deploy
+ * turns on, said once.
+ */
+export declare function deploySettings(ctx: DeployContext): Promise<DeploySettings>;
+/**
+ * 3. the site Worker: its config, the theme's block types (RFC-0015 §6), design settings
+ * (RFC-0017 §1) and DESIGN.md (RFC-0021 §1) checked before anything is built, then the build.
+ */
+export declare function buildSite(ctx: DeployContext, input: {
+    withIds: DeploymentNames;
+    analytics: AnalyticsDeployment | undefined;
+    comments: CommentsDeployment;
+    observability: ObservabilityDeployment;
+}): Promise<{
+    siteConfig: string;
+    blockTypes: string | undefined;
+    themeSettings: string | undefined;
+    themeDesign: string | undefined;
+}>;

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

@@ -0,0 +1,298 @@
+/**
+ * The phases of `cloudhal deploy` before anything is uploaded: the project and its site, analytics
+ * and comments, the Studio build, Cloudflare resources, the scheduler and plan, the site Worker.
+ */
+
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { datasetName } from "@cloudhal/analytics/wae";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { assetDir, monorepoRoot } from "../../assets.js";
+import {
+  blockTypesFile,
+  loadBlockRegistry,
+  loadThemeDesign,
+  loadThemeSettings,
+  themeSettingsFile,
+} from "../../blocks.js";
+import { buildSiteWorker } from "../../cloudflare/build.js";
+import {
+                           
+                          
+  DEFAULT_SCHEDULES_DEPLOYMENT,
+                       
+                               
+  readExistingIds,
+  readExistingVars,
+                       
+                           
+  siteConfigPath,
+  siteWorkerConfig,
+                   
+  workerNames,
+  writeWranglerConfig,
+} from "../../cloudflare/config.js";
+import { searchDeploymentOf } from "../../cloudflare/search.js";
+import {
+  installedWranglerVersion,
+  versionAtLeast,
+  WRANGLER_FOR_ANALYTICS,
+  wranglerRunner,
+} from "../../cloudflare/wrangler.js";
+import {
+  analyticsDefaultsOf,
+  analyticsEnabled,
+  commentsAvailable,
+  readProjectConfig,
+} from "../../config.js";
+import {
+  ensureStudioBuild,
+  MONOREPO_STUDIO_DIST,
+  STUDIO_BUILD_COMMAND,
+} from "../../studio-build.js";
+                                                  
+                                                  
+import { ensureResources } from "./resources.js";
+import { servedSites } from "./served-sites.js";
+import {
+  commentsRateLimitDeployment,
+  DEFAULT_QUERY_BUDGET,
+  decideAnalytics,
+  jurisdictionChooser,
+  observabilityOf,
+  rateLimitDeployment,
+} from "./settings.js";
+import { deployDir, exists,                    readDeployState } from "./state.js";
+
+export function checkOptions(options               )       {
+  if (options.jurisdiction !== undefined && !["auto", "eu"].includes(options.jurisdiction))
+    throw new Error(`--jurisdiction must be eu (got "${String(options.jurisdiction)}")`);
+  if (options.scheduler !== undefined && !["cron", "alarm"].includes(options.scheduler))
+    throw new Error(`--scheduler must be cron or alarm (got "${String(options.scheduler)}")`);
+  if (options.plan !== undefined && !["free", "paid"].includes(options.plan))
+    throw new Error(`--plan must be free or paid (got "${String(options.plan)}")`);
+}
+
+/** The project, its site, the last deploy, the names; analytics decided before anything is generated. */
+export async function loadDeploy(options               )                         {
+  const log = options.log ?? (() => {});
+  const cfg = await readProjectConfig(options.projectDir);
+  const dir = deployDir(options.projectDir, cfg.dataDir);
+  await mkdir(dir, { recursive: true });
+  const run = options.wrangler ?? wranglerRunner(options.projectDir, 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;
+  // 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 } : {}) };
+  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`,
+    );
+  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 };
+}
+
+/** 0. analytics bindings (wrangler ≥ 4.145); 0b. reader comments (RFC-0007 §15.4). */
+export async function analyticsAndComments(
+  ctx               ,
+)                                                                                        {
+  const { options, cfg, base, previous, log } = ctx;
+  let analytics                                 ;
+  if (analyticsEnabled(cfg)) {
+    const version = options.wranglerVersion ?? (await installedWranglerVersion(options.projectDir));
+    if (version && !versionAtLeast(version, WRANGLER_FOR_ANALYTICS))
+      throw new Error(
+        `Analytics needs wrangler 4.145 or newer (found ${version}). Run \`pnpm add -D wrangler@^4.148\`, or set \`analytics.enabled: false\` in cloudhal.json.`,
+      );
+    analytics = {
+      dataset: datasetName(base.name),
+      defaults: analyticsDefaultsOf(cfg),
+      budget: cfg.analytics?.queryBudget ?? DEFAULT_QUERY_BUDGET,
+      ...rateLimitDeployment(cfg, datasetName(base.name)),
+    };
+  }
+  // available by default, still off for every site
+  const comments                     = commentsAvailable(cfg)
+    ? { available: true, ...commentsRateLimitDeployment(cfg, base.name) }
+    : { available: false };
+  if (comments.available && previous?.comments !== "on")
+    log(
+      "comments: available on this deployment, and off for every site until someone turns them on in Studio (Site settings › Comments)",
+    );
+  return { analytics, comments };
+}
+
+/**
+ * The built Studio. From the monorepo, `apps/studio/dist` is only as new as its last build: build
+ * it (or, with --no-build-studio, refuse) when it is missing or Studio sources changed since. A
+ * published install ships Studio prebuilt and is never checked.
+ */
+export async function studioDirFor(ctx               )                  {
+  const { options, log } = ctx;
+  const repoRoot = await monorepoRoot();
+  const studioDir =
+    options.studioDir ??
+    (await assetDir("studio")) ??
+    (repoRoot ? path.join(repoRoot, MONOREPO_STUDIO_DIST) : "(no built Studio)");
+  await ensureStudioBuild({
+    studioDir,
+    repoRoot,
+    build: options.buildStudio !== false,
+    log,
+    ...(options.studioBuilder ? { builder: options.studioBuilder } : {}),
+  });
+  if (!(await exists(path.join(studioDir, "index.html"))))
+    throw new Error(`built Studio not found at ${studioDir} (run \`${STUDIO_BUILD_COMMAND}\`)`);
+  return studioDir;
+}
+
+/** 1. resources: D1, R2, KV (skipped on a dry run); the database id goes into the configs. */
+export async function provision(
+  ctx               ,
+)                                                                                   {
+  const { options, names, log, base } = ctx;
+  const existing = await readExistingIds(siteConfigPath(options.projectDir));
+  let databaseId = existing.databaseId;
+  let databaseCreated                          ;
+  if (!options.dryRun) {
+    const r = await ensureResources(ctx.run, {
+      cwd: options.projectDir,
+      names,
+      log,
+      where: jurisdictionChooser(options, log),
+    });
+    databaseId = r.databaseId;
+    databaseCreated = r.created;
+    if (!databaseCreated && options.jurisdiction === "eu")
+      log(
+        `D1 database ${names.database} already exists, so --jurisdiction changes nothing: a jurisdiction is chosen when the database is created and cannot be changed (to move, export the data, deploy under a new --name with --jurisdiction eu, and import)`,
+      );
+  }
+  return { withIds: { ...base, ...(databaseId ? { databaseId } : {}) }, databaseCreated };
+}
+
+                                 
+                             
+                    
+                                 
+                                         
+ 
+
+/**
+ * 2c. the scheduler's ticker: asked for, else the last deploy's, else cron (RFC-0008 §8.3). A
+ * deployment last configured without a cron slot (`CLOUDHAL_*_CRON=off`) starts on the alarm.
+ * 2d. the tick budget and the automations switch (RFC-0008 §8.2, §11.6), and what this deploy
+ * turns on, said once.
+ */
+export async function deploySettings(ctx               )                          {
+  const { options, cfg, previous, log } = ctx;
+  const legacy = await readExistingVars(path.join(ctx.dir, "admin", "wrangler.jsonc"));
+  const scheduler                  =
+    options.scheduler ??
+    previous?.scheduler ??
+    (legacy.CLOUDHAL_ANALYTICS_CRON === "off" || legacy.CLOUDHAL_COMMENTS_CRON === "off"
+      ? "alarm"
+      : "cron");
+  if (scheduler === "alarm" && !options.scheduler)
+    log(
+      "scheduler: Durable Object alarm (this account had no free cron slot); `cloudhal deploy --scheduler cron` tries the cron trigger again",
+    );
+  const plan              =
+    options.plan ?? cfg.schedules?.plan ?? previous?.plan ?? DEFAULT_SCHEDULES_DEPLOYMENT.plan;
+  const schedules                      = {
+    automations: cfg.schedules?.automations !== false,
+    plan,
+  };
+  if (plan === "free" && !options.plan && !cfg.schedules?.plan)
+    log(
+      "scheduler: Workers Free tick budget (40 statements, 1 release a tick). On Workers Paid, deploy once with `--plan paid` (remembered) or set `schedules.plan` in cloudhal.json",
+    );
+  // Workers Logs sampling and opt-in Traces for both Workers; Smart Placement for the admin Worker.
+  const observability                          = observabilityOf(cfg);
+  logFeatures(ctx, { plan, observability, schedules });
+  return { scheduler, plan, schedules, observability };
+}
+
+function logFeatures(
+  { cfg, log }               ,
+  { plan, observability, schedules }                                   ,
+)       {
+  if (observability.traces !== false)
+    log(
+      `observability: Workers Traces on for ${Math.round(observability.traces * 100)}% of requests (stored traces count toward Cloudflare Observability usage from 2026-12-01)`,
+    );
+  if (cfg.placement === "smart")
+    log(
+      "placement: Smart Placement on for the admin Worker; compare its request duration in the Workers dashboard before and after (docs/guides/cloudflare-hardening.md)",
+    );
+  // RFC-0011: email delivery through the Email Service binding, locked to `mail.from`.
+  if (cfg.mail)
+    log(
+      plan === "paid"
+        ? `mail: invites and reset links are sent from ${cfg.mail.from} (its domain must be onboarded to Cloudflare Email Service)`
+        : `mail: invites and reset links are sent from ${cfg.mail.from}. On Workers Free, Email Service delivers only to verified destination addresses of this account; any recipient needs Workers Paid`,
+    );
+  // RFC-0016: Workers AI for in-editor commands; each site's owner turns it on in Studio.
+  if (cfg.ai)
+    log(
+      "ai: Workers AI is bound to the admin Worker; turn AI on per site in Studio › Settings › AI (billed per use, 10,000 free neurons a day)",
+    );
+  // RFC-0021 §4: agents check pages with render_page in Browser Rendering.
+  log(
+    cfg.render === false
+      ? "render: off (cloudhal.json `render: false`); agents check pages with preview_page only"
+      : "render: Browser Rendering is bound for render_page (agents only, 10 a minute per key, 200 a day per site; browser time is billed past the plan's allowance; `render: false` in cloudhal.json turns it off)",
+  );
+  if (!schedules.automations)
+    log(
+      "automations: off for this deployment (cloudhal.json `schedules.automations`); releases and time gates go on",
+    );
+}
+
+/**
+ * 3. the site Worker: its config, the theme's block types (RFC-0015 §6), design settings
+ * (RFC-0017 §1) and DESIGN.md (RFC-0021 §1) checked before anything is built, then the build.
+ */
+export async function buildSite(
+  ctx               ,
+  input   
+                             
+                                               
+                                 
+                                           
+   ,
+) {
+  const { options, cfg, site, log } = ctx;
+  // RFC-0034 §4–5: the other sites this Worker serves, checked and with their routes.
+  const served = await servedSites(ctx);
+  await writeWranglerConfig(
+    siteConfigPath(options.projectDir),
+    siteWorkerConfig({
+      ...input.withIds,
+      siteId: cfg.siteId,
+      ...(served.siteIds ? { siteIds: served.siteIds } : {}),
+      ...(served.hosts.length > 0 ? { domains: served.hosts } : {}),
+      ...(cfg.domains?.site ? { domain: cfg.domains.site, siteHosts: [cfg.domains.site] } : {}),
+      ...(input.analytics ? { analytics: input.analytics } : {}),
+      comments: input.comments,
+      observability: input.observability,
+    }),
+    `Cloudhal site Worker for ${site.name}`,
+  );
+  await loadBlockRegistry(options.projectDir);
+  await loadThemeSettings(options.projectDir);
+  const blockTypes = await blockTypesFile(options.projectDir);
+  const themeSettings = await themeSettingsFile(options.projectDir);
+  const themeDesign = await loadThemeDesign(options.projectDir);
+  log("building the site Worker");
+  const siteConfig = await buildSiteWorker(options.projectDir, (l) => log(`  ${l}`));
+  return { siteConfig, blockTypes, themeSettings, themeDesign };
+}

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

@@ -0,0 +1,26 @@
+/** Cloudflare resources a deploy needs (D1, R2, KV, the bundle lifecycle rule), the health wait and the cache purge. */
+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, }: {
+    cwd: string;
+    names: ReturnType<typeof workerNames>;
+    log: (l: string) => void;
+    /** Asked only when the database is created: where it lives. */
+    where: () => Promise<Jurisdiction>;
+}): Promise<{
+    databaseId: string;
+    created?: Jurisdiction;
+}>;
+/** The R2 lifecycle rule that expires snapshot bundles (RFC-0010 "Retention"). */
+export declare const BUNDLE_LIFECYCLE_RULE = "cloudhal-bundles";
+export declare const BUNDLE_LIFECYCLE_DAYS = 30;
+/**
+ * Expires `bundles/` after 30 days, once per bucket. Bundles are a cache the site Worker rewrites
+ * when one is missing, so a rule that cannot be read or set is a warning, never a failed deploy.
+ * `lifecycle add` appends without checking names, hence the list first.
+ */
+export declare function ensureBundleLifecycle(run: WranglerRunner, cwd: string, bucket: string, log: (l: string) => void): Promise<void>;
+export declare function waitForHealth(adminUrl: string, f: typeof fetch, log: (line: string) => void, timeoutMs: number): Promise<void>;
+/** Purges the site Worker's whole cache once (the script tag lives in cached HTML). */
+export declare function purgeSite(siteUrl: string, token: string, f: typeof fetch, log: (line: string) => void): Promise<boolean>;