@cloudhal/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,175 @@
+import { buildEval, describeJudgeRow, describeRun, judgeCheckCommand } from "../commands/ai.js";
+import {
+  analyticsExport,
+  analyticsRollup,
+  analyticsSeed,
+  analyticsStatus,
+  describeStatus,
+} from "../commands/analytics.js";
+import {
+  describeRelease,
+  describeSchedulesStatus,
+  describeTick,
+  schedulesList,
+  schedulesRunDue,
+  schedulesStatus,
+} from "../commands/schedules.js";
+import {                                  remoteFlags, subcommands } from "./types.js";
+
+/** `cloudhal analytics`, `schedules`, `ai`: running the deployed (or local) site. */
+
+const number = (v                    ) => (v === undefined ? undefined : Number(v));
+
+const analyticsStatusCommand             = async (_rest, values, { projectDir }) => {
+  const s = await analyticsStatus({ projectDir, ...remoteFlags(values) });
+  for (const line of describeStatus(s)) console.log(line);
+  return 0;
+};
+
+const analyticsRollupCommand             = async (_rest, values, { projectDir }) => {
+  const days = number(values.days);
+  const r = await analyticsRollup({
+    projectDir,
+    ...remoteFlags(values),
+    ...(days !== undefined ? { days } : {}),
+    ...(values.redo ? { redo: true } : {}),
+    log: (l) => console.log(l),
+  });
+  console.log(
+    `${r.done} day(s) rolled up, ${r.pending} pending${r.failed.length ? `, ${r.failed.length} failed` : ""}${r.pruned ? `; ${r.pruned} old raw event(s) pruned` : ""}`,
+  );
+  for (const f of r.failed) console.log(`  ${f.day}: ${f.error}`);
+  return r.failed.length ? 1 : 0;
+};
+
+const analyticsSeedCommand             = async (_rest, values, { projectDir }) => {
+  if (values.remote) throw new Error("seed writes demo data to the local SQLite only");
+  const days = number(values.days);
+  const views = number(values.views);
+  await analyticsSeed({
+    projectDir,
+    ...(days !== undefined ? { days } : {}),
+    ...(views !== undefined ? { views } : {}),
+    log: (l) => console.log(l),
+  });
+  return 0;
+};
+
+const analyticsExportCommand             = async (_rest, values, { projectDir }) => {
+  const csv = await analyticsExport({
+    projectDir,
+    ...remoteFlags(values),
+    ...(values.from ? { from: values.from } : {}),
+    ...(values.to ? { to: values.to } : {}),
+    ...(values.out ? { out: values.out } : {}),
+  });
+  if (values.out) console.log(`wrote ${values.out}`);
+  else process.stdout.write(csv);
+  return 0;
+};
+
+const schedulesStatusCommand             = async (_rest, values, { projectDir }) => {
+  const s = await schedulesStatus({ projectDir, ...remoteFlags(values) });
+  for (const line of describeSchedulesStatus(s)) console.log(line);
+  return 0;
+};
+
+const schedulesListCommand             = async (_rest, values, { projectDir }) => {
+  const limit = values.limit === undefined ? undefined : Number(values.limit);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200))
+    throw new Error("--limit must be 1–200");
+  const list = await schedulesList({
+    projectDir,
+    ...remoteFlags(values),
+    ...(limit ? { limit } : {}),
+  });
+  if (list.length === 0) console.log("no releases");
+  for (const r of list) console.log(describeRelease(r));
+  return 0;
+};
+
+const schedulesRunDueCommand             = async (_rest, values, { projectDir }) => {
+  const r = await schedulesRunDue({ projectDir, ...remoteFlags(values) });
+  console.log(describeTick(r));
+  return r.failed > 0 ? 1 : 0;
+};
+
+// RFC-0021 21c: is the design judge worth using? It scores the reference pages.
+const judgeCheck             = async (_rest, values, { projectDir }) => {
+  const result = await judgeCheckCommand({
+    projectDir,
+    ...remoteFlags(values),
+    ...(values.judge ? { judge: values.judge } : {}),
+    onRow: (r) => console.log(describeJudgeRow(r)),
+  });
+  console.log(`\n${result.table}`);
+  console.log(
+    result.ordered
+      ? "\nThe judge ranks the references in order."
+      : "\nThe judge does not rank the references in order: do not compare models with it.",
+  );
+  return result.ordered ? 0 : 1;
+};
+
+const split = (v                    ) =>
+  v
+    ? v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : undefined;
+
+/** RFC-0021 21c: the design pass (--look and --judge imply it). */
+function designPass(values           )                                                       {
+  if (!(values.design || values.look || values.judge)) return {};
+  return {
+    design: {
+      ...(values.look ? { look: true } : {}),
+      ...(values.judge ? { judge: values.judge === "none" ? false : values.judge } : {}),
+    },
+  };
+}
+
+const buildEvalCommand             = async (_rest, values, { projectDir }) => {
+  const models = split(values.models);
+  const briefs = split(values.briefs);
+  const report = await buildEval({
+    projectDir,
+    ...remoteFlags(values),
+    ...(models ? { models } : {}),
+    ...(briefs ? { briefs } : {}),
+    ...designPass(values),
+    onRun: (r) => console.log(describeRun(r)),
+  });
+  console.log(`\n${report.table}`);
+  if (values.out) {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(values.out, `${JSON.stringify(report, null, 2)}\n`);
+    console.log(`\nwrote ${values.out}`);
+  }
+  return 0;
+};
+
+export const OPS_COMMANDS = {
+  analytics: subcommands(
+    {
+      status: analyticsStatusCommand,
+      rollup: analyticsRollupCommand,
+      seed: analyticsSeedCommand,
+      export: analyticsExportCommand,
+    },
+    "usage: cloudhal analytics status|rollup|seed|export",
+  ),
+  schedules: subcommands(
+    {
+      status: schedulesStatusCommand,
+      list: schedulesListCommand,
+      "run-due": schedulesRunDueCommand,
+    },
+    "usage: cloudhal schedules status|list|run-due [--remote]",
+  ),
+  ai: subcommands(
+    { "judge-check": judgeCheck, "build-eval": buildEvalCommand },
+    "usage: cloudhal ai build-eval [--remote] [--models a,b] [--briefs x,y] | cloudhal ai judge-check [--remote] [--judge <model>]",
+  ),
+}                                     ;

package/dist/src/cli/commands-remote.d.ts

@@ -0,0 +1,8 @@
+import type { CliCommand } from "./types.js";
+export declare const REMOTE_COMMANDS: {
+    deploy: CliCommand;
+    domain: CliCommand;
+    push: CliCommand;
+    pull: CliCommand;
+    owner: CliCommand;
+};

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

@@ -0,0 +1,131 @@
+import { deploy } from "../commands/deploy.js";
+import {                    domain } from "../commands/domain.js";
+import { transferOwner } from "../commands/owner.js";
+import { pullSite, pushSite } from "../commands/sync.js";
+import { askJurisdiction, askYesNo } from "./prompts.js";
+                                                        
+
+/** `cloudhal deploy`, `domain`, `push`, `pull`, `owner`: the site on Cloudflare. */
+
+function deployFlags(values           )   
+                          
+                                       
+                                    
+  {
+  const where = values.jurisdiction;
+  if (where !== undefined && where !== "eu")
+    throw new Error(`--jurisdiction must be eu (got "${where}")`);
+  const ticker = values.scheduler;
+  if (ticker !== undefined && ticker !== "cron" && ticker !== "alarm")
+    throw new Error(`--scheduler must be cron or alarm (got "${ticker}")`);
+  const plan = values.plan;
+  if (plan !== undefined && plan !== "free" && plan !== "paid")
+    throw new Error(`--plan must be free or paid (got "${plan}")`);
+  return { where, ticker, plan };
+}
+
+const deployCommand             = async (_rest, values, { projectDir }) => {
+  const { where, ticker, plan } = deployFlags(values);
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  const r = await deploy({
+    projectDir,
+    ...(values.name ? { name: values.name } : {}),
+    ...(values["dry-run"] ? { dryRun: true } : {}),
+    ...(where ? { jurisdiction: where } : {}),
+    ...(ticker ? { scheduler: ticker } : {}),
+    ...(plan ? { plan } : {}),
+    ...(values["force-downgrade"] ? { forceDowngrade: true } : {}),
+    ...(values["no-build-studio"] ? { buildStudio: false } : {}),
+    log: (l) => console.log(l),
+    // The analytics and data-location questions need a person at a terminal.
+    ...(tty ? { prompt: askYesNo, askJurisdiction } : {}),
+  });
+  if (r.dryRun) {
+    console.log(`\nDry run OK. Workers: ${r.names.site}, ${r.names.admin}. Nothing was deployed.`);
+    return 0;
+  }
+  console.log(
+    `\nSite:   ${r.siteUrl ?? "(see wrangler output)"}\nStudio: ${r.adminUrl ?? "(see wrangler output)"}`,
+  );
+  if (r.customSiteUrl || r.customStudioUrl)
+    console.log(
+      `Custom: ${[r.customSiteUrl, r.customStudioUrl].filter(Boolean).join(" · ")} (DNS and certificate can take a few minutes)`,
+    );
+  if (r.setupUrl)
+    console.log(`\nLocal site pushed. Create the owner account (once) at:\n  ${r.setupUrl}`);
+  return 0;
+};
+
+function changeDomain(rest          , values           , projectDir        ) {
+  const [action, arg] = rest;
+  if (action === "set") {
+    if (!arg && !values.studio)
+      throw new Error("usage: cloudhal domain set <hostname> [--studio <hostname>]");
+    return domain({
+      projectDir,
+      set: {
+        ...(arg ? { site: arg } : {}),
+        ...(values.studio ? { studio: values.studio } : {}),
+      },
+    });
+  }
+  if (action === "remove") {
+    const which = arg ?? "all";
+    if (!["site", "studio", "all"].includes(which))
+      throw new Error("usage: cloudhal domain remove [site|studio|all]");
+    return domain({
+      projectDir,
+      remove: which === "all" ? ["site", "studio"] : [which                ],
+    });
+  }
+  if (action === undefined) return domain({ projectDir });
+  throw new Error(`unknown domain action "${action}" (set, remove)`);
+}
+
+const domainCommand             = async (rest, values, { projectDir }) => {
+  const result = await changeDomain(rest, values, projectDir);
+  console.log(
+    result
+      ? `site:   ${result.site ? `https://${result.site}` : "(workers.dev)"}\nstudio: ${result.studio ? `https://${result.studio}` : "(workers.dev)"}`
+      : "no custom domains; the Workers answer on workers.dev",
+  );
+  if (rest[0])
+    console.log("run `cloudhal deploy` to apply (the zone must be in your Cloudflare account)");
+  return 0;
+};
+
+/** `cloudhal push` and `cloudhal pull` take the same flags. */
+function syncCommand(run                                   )             {
+  return async (_rest, values, { projectDir }) => {
+    const opts = {
+      projectDir,
+      ...(values.replace ? { replace: true } : {}),
+      ...(values["cancel-schedules"] ? { cancelSchedules: true } : {}),
+      ...(values["admin-url"] ? { adminUrl: values["admin-url"] } : {}),
+      log: (l        ) => console.log(l),
+    };
+    await run(opts);
+    return 0;
+  };
+}
+
+const ownerCommand             = async (rest, values, { projectDir }) => {
+  const [action] = rest;
+  if (action !== "transfer" || !values.to)
+    throw new Error("usage: cloudhal owner transfer --to <email> [--admin-url <url>]");
+  await transferOwner({
+    projectDir,
+    to: values.to,
+    ...(values["admin-url"] ? { adminUrl: values["admin-url"] } : {}),
+    log: (l) => console.log(l),
+  });
+  return 0;
+};
+
+export const REMOTE_COMMANDS = {
+  deploy: deployCommand,
+  domain: domainCommand,
+  push: syncCommand(pushSite),
+  pull: syncCommand(pullSite),
+  owner: ownerCommand,
+}                                     ;

package/dist/src/cli/commands-site.d.ts

@@ -0,0 +1,4 @@
+import { type CliCommand } from "./types.js";
+export declare const SITE_COMMANDS: {
+    site: CliCommand;
+};

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

@@ -0,0 +1,52 @@
+/** `cloudhal site list | create | delete` (RFC-0034 §2–3). */
+import { createSite, deleteSite, listSites } from "../commands/site.js";
+import {                  remoteFlags, subcommands } from "./types.js";
+
+const USAGE =
+  "usage: cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>] | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]";
+
+const list             = async (_rest, values, { projectDir }) => {
+  const sites = await listSites({ projectDir, ...remoteFlags(values) });
+  for (const s of sites) {
+    console.log(`${s.id}  ${s.slug}  ${s.defaultLocale}  ${s.theme}  ${s.name}`);
+    if (s.hosts.length > 0) console.log(`  hosts: ${s.hosts.join(", ")}`);
+    if (s.conflicts.length > 0)
+      console.log(`  not served (another site holds it): ${s.conflicts.join(", ")}`);
+  }
+  return 0;
+};
+
+const create             = async (_rest, values, { projectDir }) => {
+  if (!values.name || !values.slug) throw new Error(USAGE);
+  const site = await createSite(
+    { projectDir, ...remoteFlags(values) },
+    {
+      name: values.name,
+      slug: values.slug,
+      ...(values.locale ? { locale: values.locale } : {}),
+      ...(values.project ? { projectId: values.project } : {}),
+      ...(values.theme ? { theme: values.theme } : {}),
+      ...(values.from ? { from: values.from } : {}),
+    },
+  );
+  console.log(`created ${site.id} in project ${site.projectId} (nothing is published)`);
+  if (site.edition) {
+    console.log(
+      `  edition: ${site.edition.pages} page(s) and ${site.edition.menus} menu(s) copied as drafts`,
+    );
+    for (const s of site.edition.skipped) console.log(`  left out ${s.what}: ${s.reason}`);
+  }
+  return 0;
+};
+
+const remove             = async (rest, values, { projectDir }) => {
+  const [siteId] = rest;
+  if (!siteId || !values.confirm) throw new Error(USAGE);
+  const r = await deleteSite({ projectDir, ...remoteFlags(values) }, siteId, values.confirm);
+  console.log(`deleted ${siteId}: ${r.rows} rows, ${r.objects} stored files`);
+  return 0;
+};
+
+export const SITE_COMMANDS = {
+  site: subcommands({ list, create, delete: remove }, USAGE),
+}                                     ;

package/dist/src/cli/help.d.ts

@@ -0,0 +1,2 @@
+/** `cloudhal --help`; every command it names has an entry in `COMMANDS` (cli.ts). */
+export declare const HELP = "cloudhal \u2014 agent-native sites\n\nUsage:\n  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store\n  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)\n  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)\n  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot\n  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)\n  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]\n                                                          MCP server over stdio for this project\n  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]\n                  [--force-downgrade] [--no-build-studio]\n                                                          site + admin Workers on Cloudflare (uses wrangler login);\n                                                          --jurisdiction eu keeps a newly created D1 database\n                                                          in the EU (cannot be changed later); --scheduler picks\n                                                          the minute cron trigger or the Durable Object alarm;\n                                                          --plan sizes scheduler ticks for the account's Workers\n                                                          plan (default free; remembered);\n                                                          --force-downgrade deploys older schedules code over\n                                                          open releases and time gates; from the monorepo a\n                                                          stale apps/studio/dist is rebuilt first\n                                                          (--no-build-studio: fail instead)\n  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]\n                                                          custom domains for the next deploy\n  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]\n                                                          local site \u2192 deployment (refused while releases are\n                                                          open unless --cancel-schedules cancels them)\n  cloudhal pull [--replace] [--admin-url <url>]           deployment \u2192 local site\n  cloudhal owner transfer --to <email> [--admin-url <url>]\n                                                          make a member the deployment's Owner\n                                                          (lockout recovery; uses the deployment token)\n  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]\n                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]\n                                                          the installation's sites (RFC-0034): one Studio,\n                                                          many isolated sites; nothing is published\n  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]\n                                                          move entry tags into tag terms (RFC-0002);\n                                                          resumable; --revert <id> undoes a run\n  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]\u2026 | --revert <id>\n                                                          copy linked images into the media library\n                                                          (RFC-0004); revertible\n  cloudhal media verify [<assetId>]                       recompute media checksums\n  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)\n  cloudhal media placeholders [--remote] [--all] [--dry-run]\n                                                          draw missing image placeholders in local Chrome\n  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget\n  cloudhal analytics rollup [--days <n>] [--remote] [--redo]\n                                                          compute daily totals (--remote backfills the\n                                                          deployment from WAE, up to 92 days)\n  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only\n  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]\n                                                          daily totals as CSV (default: 30 days)\n  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges\n  cloudhal comments export [--remote] [--with-personal-data --out <file>]\n                                                          comments as JSON lines (stdout or --out)\n  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun\n  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages\n  cloudhal schedules list [--remote] [--limit <n>]        the site's releases\n  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from\n                                                          the system's cron every minute)\n  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]\n                        [--design] [--look] [--judge <model>|none]\n                                                          compare models on Build chat's turn, in memory\n                                                          (real model calls; RFC-0020 open question 7);\n                                                          --design renders each result: failed checks and\n                                                          a vision model's score (RFC-0021 21c); --look lets\n                                                          the model see its render first, as Build chat does\n  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty \u2192 strong) with the\n                                                          design judge; fails when it does not rank them\n  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]\n                        [--frames <n>] [--base <url>] [--out <dir>]\n                                                          screenshots and render_page's checks for a page\n                                                          (of cloudhal dev by default; RFC-0024)\n  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets\n  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file\n                                                          (Figma, Style Dictionary; RFC-0023)\n  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON\n                                                          (RFC-0025)\n  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot\n                                                          (publishing keeps it current; for restored backups)\n  cloudhal --help\n";

package/dist/src/cli/help.js

@@ -0,0 +1,83 @@
+/** `cloudhal --help`; every command it names has an entry in `COMMANDS` (cli.ts). */
+export const HELP = `cloudhal — agent-native sites
+
+Usage:
+  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store
+  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)
+  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)
+  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot
+  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)
+  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]
+                                                          MCP server over stdio for this project
+  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]
+                  [--force-downgrade] [--no-build-studio]
+                                                          site + admin Workers on Cloudflare (uses wrangler login);
+                                                          --jurisdiction eu keeps a newly created D1 database
+                                                          in the EU (cannot be changed later); --scheduler picks
+                                                          the minute cron trigger or the Durable Object alarm;
+                                                          --plan sizes scheduler ticks for the account's Workers
+                                                          plan (default free; remembered);
+                                                          --force-downgrade deploys older schedules code over
+                                                          open releases and time gates; from the monorepo a
+                                                          stale apps/studio/dist is rebuilt first
+                                                          (--no-build-studio: fail instead)
+  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]
+                                                          custom domains for the next deploy
+  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]
+                                                          local site → deployment (refused while releases are
+                                                          open unless --cancel-schedules cancels them)
+  cloudhal pull [--replace] [--admin-url <url>]           deployment → local site
+  cloudhal owner transfer --to <email> [--admin-url <url>]
+                                                          make a member the deployment's Owner
+                                                          (lockout recovery; uses the deployment token)
+  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]
+                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]
+                                                          the installation's sites (RFC-0034): one Studio,
+                                                          many isolated sites; nothing is published
+  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]
+                                                          move entry tags into tag terms (RFC-0002);
+                                                          resumable; --revert <id> undoes a run
+  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]… | --revert <id>
+                                                          copy linked images into the media library
+                                                          (RFC-0004); revertible
+  cloudhal media verify [<assetId>]                       recompute media checksums
+  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)
+  cloudhal media placeholders [--remote] [--all] [--dry-run]
+                                                          draw missing image placeholders in local Chrome
+  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget
+  cloudhal analytics rollup [--days <n>] [--remote] [--redo]
+                                                          compute daily totals (--remote backfills the
+                                                          deployment from WAE, up to 92 days)
+  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only
+  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]
+                                                          daily totals as CSV (default: 30 days)
+  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges
+  cloudhal comments export [--remote] [--with-personal-data --out <file>]
+                                                          comments as JSON lines (stdout or --out)
+  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun
+  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages
+  cloudhal schedules list [--remote] [--limit <n>]        the site's releases
+  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from
+                                                          the system's cron every minute)
+  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]
+                        [--design] [--look] [--judge <model>|none]
+                                                          compare models on Build chat's turn, in memory
+                                                          (real model calls; RFC-0020 open question 7);
+                                                          --design renders each result: failed checks and
+                                                          a vision model's score (RFC-0021 21c); --look lets
+                                                          the model see its render first, as Build chat does
+  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty → strong) with the
+                                                          design judge; fails when it does not rank them
+  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]
+                        [--frames <n>] [--base <url>] [--out <dir>]
+                                                          screenshots and render_page's checks for a page
+                                                          (of cloudhal dev by default; RFC-0024)
+  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets
+  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file
+                                                          (Figma, Style Dictionary; RFC-0023)
+  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON
+                                                          (RFC-0025)
+  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot
+                                                          (publishing keeps it current; for restored backups)
+  cloudhal --help
+`;

package/dist/src/cli/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Where a new D1 database should live (RFC-0007 D7), asked only when `cloudhal deploy` is about to
+ * create it. Enter keeps the automatic location.
+ */
+export declare function askJurisdiction(): Promise<"auto" | "eu">;
+/** A yes/no question at the terminal; Enter means yes. */
+export declare function askYesNo(question: string): Promise<boolean>;

package/dist/src/cli/prompts.js

@@ -0,0 +1,35 @@
+import { createInterface } from "node:readline/promises";
+
+/**
+ * Where a new D1 database should live (RFC-0007 D7), asked only when `cloudhal deploy` is about to
+ * create it. Enter keeps the automatic location.
+ */
+export async function askJurisdiction()                         {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;;) {
+      const answer = (
+        await rl.question(
+          "Where should the D1 database live?\n  1) Automatic: Cloudflare picks the location (default)\n  2) EU jurisdiction: the data stays inside the EU\nA location cannot be changed after the database is created. Choose [1/2]: ",
+        )
+      )
+        .trim()
+        .toLowerCase();
+      if (answer === "" || answer === "1" || answer === "automatic") return "auto";
+      if (answer === "2" || answer === "eu") return "eu";
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/** A yes/no question at the terminal; Enter means yes. */
+export async function askYesNo(question        )                   {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}

package/dist/src/cli/types.d.ts

@@ -0,0 +1,26 @@
+import type { parseArgs } from "node:util";
+import type { OPTIONS } from "../cli.js";
+/** The parsed flags, typed from `OPTIONS`. */
+export type CliValues = ReturnType<typeof parseArgs<{
+    args: string[];
+    allowPositionals: true;
+    options: typeof OPTIONS;
+}>>["values"];
+/** What every command handler gets besides its positionals and flags. */
+export type CliContext = {
+    projectDir: string;
+};
+/** One `cloudhal <command>`: `rest` is the positionals after the command; resolves to the exit code. */
+export type CliCommand = (rest: string[], values: CliValues, ctx: CliContext) => Promise<number>;
+/** Resolves when the process is asked to stop (Ctrl-C, SIGTERM). */
+export declare function untilSignal(also?: (resolve: () => void) => void): Promise<void>;
+/**
+ * A command whose first positional picks an action (`cloudhal media gc`); an unknown or missing
+ * action throws `usage`. The action gets the positionals after its name.
+ */
+export declare function subcommands(actions: Record<string, CliCommand>, usage: string): CliCommand;
+/** `--remote` and `--admin-url`, spread into the remote-capable commands' options. */
+export declare function remoteFlags(values: CliValues): {
+    remote?: boolean;
+    adminUrl?: string;
+};

package/dist/src/cli/types.js

@@ -0,0 +1,42 @@
+                                           
+                                         
+
+/** The parsed flags, typed from `OPTIONS`. */
+                                   
+                                                                                       
+            
+
+/** What every command handler gets besides its positionals and flags. */
+                                                
+
+/** One `cloudhal <command>`: `rest` is the positionals after the command; resolves to the exit code. */
+                                                                                                 
+
+/** Resolves when the process is asked to stop (Ctrl-C, SIGTERM). */
+export function untilSignal(also                                )                {
+  return new Promise      ((resolve) => {
+    for (const sig of ["SIGINT", "SIGTERM"]         ) process.once(sig, () => resolve());
+    also?.(resolve);
+  });
+}
+
+/**
+ * A command whose first positional picks an action (`cloudhal media gc`); an unknown or missing
+ * action throws `usage`. The action gets the positionals after its name.
+ */
+export function subcommands(actions                            , usage        )             {
+  return async (rest, values, ctx) => {
+    const [what, ...args] = rest;
+    const action = what !== undefined && Object.hasOwn(actions, what) ? actions[what] : undefined;
+    if (!action) throw new Error(usage);
+    return action(args, values, ctx);
+  };
+}
+
+/** `--remote` and `--admin-url`, spread into the remote-capable commands' options. */
+export function remoteFlags(values           ) {
+  return {
+    ...(values.remote ? { remote: true } : {}),
+    ...(values["admin-url"] ? { adminUrl: values["admin-url"] } : {}),
+  };
+}