@cloudhal/cli 0.0.0-stage → 0.1.0

package/dist/src/commands/site.js

@@ -0,0 +1,151 @@
+/**
+ * `cloudhal site list | create | delete` (RFC-0034 §2–3): the sites of one installation — on the
+ * project's SQLite, or with `--remote` on the deployment (deployment token: `/api/admin/sites`).
+ * The project's own site (`cloudhal.json` `siteId`) is never deleted from here: its site Worker
+ * serves it.
+ */
+import path from "node:path";
+import { createEdition, deleteSiteData, listHosts, seedStarterSite } from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+import { brief, deployment,                  } from "./sync.js";
+
+                                                     
+                                                            
+                            
+ 
+
+                          
+                      
+                        
+                        
+                             
+                                 
+                         
+                                    
+                                        
+ 
+
+/** What an edition copied and what it left out. */
+                                 
+                         
+                         
+                                                                                  
+ 
+
+                                  
+                        
+                        
+                           
+                              
+                          
+                                                               
+                         
+ 
+
+async function remote   (options                , p        , init              = {})             {
+  const { adminUrl, token, fetch: f } = await deployment(options);
+  const res = await f(new URL(p, adminUrl), {
+    ...init,
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+  const text = await res.text();
+  if (res.status === 404 && p === "/api/admin/sites")
+    throw new Error("the deployment has no site management yet (deploy this version first)");
+  if (!res.ok) throw new Error(`the deployment answered ${res.status}: ${brief(text)}`);
+  return JSON.parse(text)     ;
+}
+
+async function withLocal   (
+  projectDir        ,
+  fn                                                               ,
+)             {
+  const cfg = await readProjectConfig(projectDir);
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  try {
+    return await fn(local);
+  } finally {
+    await local.close();
+  }
+}
+
+/** `cloudhal site list`. */
+export async function listSites(options                )                     {
+  if (options.remote)
+    return (await remote                      (options, "/api/admin/sites")).sites;
+  return withLocal(options.projectDir, async (l) => {
+    const hosts = await listHosts(l.sql);
+    return (await l.store.listSites()).map((s) => {
+      const held = hosts.filter((h) => h.siteId === s.id).map((h) => h.host);
+      return {
+        id: s.id,
+        name: s.name,
+        slug: s.slug,
+        projectId: s.projectId,
+        defaultLocale: s.defaultLocale,
+        theme: s.theme.name,
+        hosts: held,
+        conflicts: s.domains.map((d) => d.hostname).filter((h) => !held.includes(h)),
+      };
+    });
+  });
+}
+
+/** `cloudhal site create`: a new site in this installation, seeded like `cloudhal init`. */
+export async function createSite(
+  options                ,
+  input                 ,
+)                                                                       {
+  if (options.remote) {
+    const r = await remote                                                                       (
+      options,
+      "/api/admin/sites",
+      { method: "POST", body: JSON.stringify(input) },
+    );
+    return { ...r.site, ...(r.edition ? { edition: r.edition } : {}) };
+  }
+  return withLocal(options.projectDir, async (l) => {
+    if ((await l.store.listSites()).some((s) => s.slug === input.slug))
+      throw new Error(`a site with the slug ${input.slug} exists`);
+    if (input.from) {
+      const r = await createEdition(l.store, {
+        fromSiteId: input.from,
+        name: input.name,
+        slug: input.slug,
+        locale: input.locale ?? "en",
+      });
+      return { id: r.site.id, projectId: r.site.projectId, edition: r };
+    }
+    const site = await seedStarterSite(l.store, input);
+    return { id: site.id, projectId: site.projectId };
+  });
+}
+
+/** `cloudhal site delete <siteId> --confirm <slug>`. */
+export async function deleteSite(
+  options                ,
+  siteId        ,
+  confirm        ,
+)                                             {
+  const cfg = await readProjectConfig(options.projectDir);
+  if (siteId === cfg.siteId)
+    throw new Error(
+      `${siteId} is this project's site (cloudhal.json); its site Worker serves it, so it is not deleted from here`,
+    );
+  if (options.remote)
+    return remote(options, `/api/admin/sites/${encodeURIComponent(siteId)}`, {
+      method: "DELETE",
+      body: JSON.stringify({ confirm }),
+    });
+  return withLocal(options.projectDir, async (l) => {
+    const site = await l.store.getSite(siteId);
+    if (!site) throw new Error(`no site ${siteId}`);
+    if (confirm !== site.slug)
+      throw new Error(`confirm with the site's slug (${site.slug}) to delete it`);
+    return deleteSiteData(l, siteId);
+  });
+}

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

@@ -0,0 +1,10 @@
+import type { Snapshot } from "@cloudhal/core-contracts";
+export interface SnapshotOptions {
+    readonly projectDir: string;
+    readonly label?: string;
+    readonly publish?: boolean;
+}
+/** Creates a snapshot of the live site (and optionally publishes it). */
+export declare function snapshot(options: SnapshotOptions): Promise<Snapshot>;
+/** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
+export declare function resolveBuildSnapshot(projectDir: string): Promise<Snapshot>;

package/dist/src/commands/snapshot.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+                                                         
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+
+                                  
+                              
+                          
+                             
+ 
+
+/** Creates a snapshot of the live site (and optionally publishes it). */
+export async function snapshot(options                 )                    {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    const snap = await local.store.createSnapshot(cfg.siteId, {
+      actor: { kind: "human", id: "user_localcli0001", name: "cloudhal CLI" },
+      reason: options.publish ? "publish" : "manual",
+      ...(options.label ? { label: options.label } : {}),
+    });
+    if (options.publish) {
+      const site = await local.store.getSite(cfg.siteId);
+      if (!site) throw new Error(`site ${cfg.siteId} not found`);
+      await local.store.publish(site, snap.id);
+    }
+    return snap;
+  } finally {
+    await local.close();
+  }
+}
+
+/** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
+export async function resolveBuildSnapshot(projectDir        )                    {
+  const cfg = await readProjectConfig(projectDir);
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  try {
+    const site = await local.store.getSite(cfg.siteId);
+    if (!site) throw new Error(`site ${cfg.siteId} not found`);
+    if (site.publishedSnapshotId) {
+      const s = await local.store.getSnapshot(site.publishedSnapshotId);
+      if (s) return s;
+    }
+    const latest = await local.store.latestSnapshot(cfg.siteId);
+    if (latest) return latest;
+  } finally {
+    await local.close();
+  }
+  return snapshot({ projectDir, label: "build" });
+}

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

@@ -0,0 +1,29 @@
+import { restTransport } from "@cloudhal/api";
+export interface StudioOptions {
+    readonly projectDir: string;
+    readonly port?: number;
+    /** Directory of a built Studio (`apps/studio/dist`). Defaults to the monorepo build when present. */
+    readonly studioDist?: string;
+    /** Skip authentication (local scripts only). */
+    readonly noAuth?: boolean;
+    /** Where printed mail goes (tests); default stdout (RFC-0011). */
+    readonly mailOut?: (text: string) => void;
+    /** `false` skips the scheduler's Node ticker (tests). */
+    readonly scheduler?: boolean;
+    /** @deprecated the comments job runs on the scheduler's tick; `false` skips the ticker. */
+    readonly commentsJob?: boolean;
+}
+/** Paths the API owns; never answered with the Studio SPA. */
+export declare function isApiPath(pathname: string): boolean;
+/**
+ * Runs the Cloudhal API (and, when built, the Studio UI) for the project on Node.
+ * Authentication is wired by `createAuthFor()` from `@cloudhal/api/auth` when available.
+ */
+export declare function studio(options: StudioOptions): Promise<{
+    url: string;
+    stop(): Promise<void>;
+}>;
+/** Workers AI over REST from `CLOUDFLARE_ACCOUNT_ID` and `CLOUDHAL_AI_TOKEN` (RFC-0016 §1). */
+export declare function localAiTransport(env?: Record<string, string | undefined>): {
+    transport?: ReturnType<typeof restTransport>;
+};

package/dist/src/commands/studio.js

@@ -0,0 +1,172 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { ApprovalStore, AuditLog, loadSkills } from "@cloudhal/agent-runtime";
+import { AiStore, createApi, restTransport } from "@cloudhal/api";
+import { serveNode } from "@cloudhal/api/node";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { nodeTransport } from "@cloudhal/core-ts/media-node";
+import { SqlScheduleStore } from "@cloudhal/schedules/sql";
+import { assetDir } from "../assets.js";
+import { loadBlockRegistry, loadThemeDesign, loadThemeSettings } from "../blocks.js";
+import { readProjectConfig } from "../config.js";
+import { localRender } from "../render-chrome.js";
+import { localAnalytics, startLocalRollups } from "./analytics.js";
+import { localComments } from "./comments-local.js";
+import { terminalMailSender } from "./mail-local.js";
+import { resolveSkillsDir } from "./mcp.js";
+import { automationsEnabled, startLocalScheduler } from "./scheduler-local.js";
+
+                                
+                              
+                         
+                                                                                                       
+                               
+                                                  
+                            
+                                                                    
+                                            
+                                                           
+                               
+                                                                                             
+                                 
+ 
+
+async function exists(p        )                   {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Paths the API owns; never answered with the Studio SPA. */
+export function isApiPath(pathname        )          {
+  return pathname === "/api" || pathname.startsWith("/api/");
+}
+
+/**
+ * Runs the Cloudhal API (and, when built, the Studio UI) for the project on Node.
+ * Authentication is wired by `createAuthFor()` from `@cloudhal/api/auth` when available.
+ */
+export async function studio(
+  options               ,
+)                                                  {
+  const cfg = await readProjectConfig(options.projectDir);
+  // The theme's block types (RFC-0015 §6) join the built-ins, and its design settings
+  // (RFC-0017 §1) check `Site.theme.config`: validated, offered, listed.
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir), {
+    blocks: await loadBlockRegistry(options.projectDir),
+    themeSettings: await loadThemeSettings(options.projectDir),
+    themeDesign: await loadThemeDesign(options.projectDir),
+  });
+  const studioDist = options.studioDist ?? (await assetDir("studio")) ?? "";
+  const serveStudio = await exists(path.join(studioDist, "index.html"));
+
+  const skillsDir = await resolveSkillsDir(options.projectDir);
+  // Site analytics on the project's SQLite (RFC-0006 L3): read through SqlAnalytics, daily totals
+  // rolled up hourly (and raw events pruned) while Studio runs.
+  const analytics = localAnalytics(local.sql, cfg);
+  const stopRollups = analytics.feature().enabled
+    ? startLocalRollups(analytics, local, cfg.analytics)
+    : () => {};
+  // RFC-0007 §12: the comment routes on the project's SQLite.
+  const comments = await localComments(local.sql, local.dataDir);
+  // RFC-0008 §8.4: the scheduler's Node ticker (releases, automations, and the hourly comments
+  // job behind its watermark) while Studio runs, with a catch-up tick now.
+  const ticker =
+    options.scheduler === false || options.commentsJob === false
+      ? undefined
+      : startLocalScheduler({
+          sql: local.sql,
+          blobs: local.blobs,
+          graph: local.store,
+          // RFC-0008 §11.1: the broken-link sweep's 404 rows
+          ...(analytics.feature().enabled ? { analytics } : {}),
+        });
+  let deps                                  = {
+    store: local.store,
+    analytics,
+    comments,
+    ...(ticker ? { scheduler: ticker } : {}),
+    // RFC-0008 §13: the schedule routes, tools and notifications on the project's SQLite.
+    schedules: {
+      store: new SqlScheduleStore(local.sql),
+      maxNewBodies: Number.POSITIVE_INFINITY,
+      // §11.6: `CLOUDHAL_AUTOMATIONS=off` refuses automation keys and stops occurrences.
+      automationsEnabled: automationsEnabled(),
+    },
+    requireAuth: !options.noAuth,
+    // RFC-0011: invites and reset links are printed here instead of sent.
+    ...(cfg.mail ? { mail: terminalMailSender(cfg.mail, options.mailOut) } : {}),
+    // RFC-0016: Workers AI over REST when the environment has an account id and a token (never
+    // stored); the settings are kept either way.
+    ai: { store: new AiStore(local.sql), ...localAiTransport() },
+    // The Studio dev server (vite, :5173) proxies /api here during Studio development.
+    trustedOrigins: [
+      "http://localhost:5173",
+      ...(process.env.CLOUDHAL_TRUSTED_ORIGINS?.split(",") ?? []),
+    ],
+    // Without auth anyone who can reach the port could write; answer localhost names only.
+    ...(options.noAuth ? { allowedHosts: ["localhost", "127.0.0.1", "[::1]"] } : {}),
+    mcp: {
+      stateKey: crypto.getRandomValues(new Uint8Array(32)),
+      audit: new AuditLog(local.sql),
+      approvals: new ApprovalStore(local.sql),
+      skills: skillsDir ? await loadSkills(skillsDir) : [],
+      media: { fetchTransport: nodeTransport() },
+      // RFC-0021 §4: render_page with the local Chrome, when there is one.
+      render: localRender(),
+    },
+  };
+  if (!options.noAuth) {
+    const { createAuthFor } = await import("@cloudhal/api/auth/node");
+    const auth = await createAuthFor({
+      dataDir: local.dataDir,
+      baseURL: `http://localhost:${options.port ?? 8787}`,
+      // Better Auth checks Origin on browser POSTs itself; the Studio dev server must pass too.
+      trustedOrigins: deps.trustedOrigins ?? [],
+    });
+    deps = {
+      ...deps,
+      resolveActor: auth.resolveActor,
+      resolvePrincipal: auth.resolvePrincipal,
+      authHandler: auth.handler,
+      agentKeys: auth.agentKeys,
+      staff: auth.staff,
+      signUp: auth.signUp,
+    };
+  }
+  const app = createApi(deps);
+
+  if (serveStudio) {
+    const { serveStatic } = await import("@hono/node-server/serve-static");
+    const root = path.relative(process.cwd(), studioDist) || ".";
+    app.use("/assets/*", serveStatic({ root }));
+    // The SPA fallback is for Studio's own routes only: an /api path the API did not answer (a
+    // route that is not mounted, e.g. agent keys without auth) falls through to the API's JSON 404
+    // rather than receiving index.html with a 200.
+    const spa = serveStatic({ root, path: "index.html" });
+    app.get("*", (c, next) => (isApiPath(c.req.path) ? next() : spa(c, next)));
+  }
+
+  const { server, port } = await serveNode(app, { port: options.port ?? 8787 });
+  return {
+    url: `http://localhost:${port}/`,
+    stop: async () => {
+      stopRollups();
+      ticker?.stop();
+      await new Promise      ((resolve) => server.close(() => resolve()));
+      await local.close();
+    },
+  };
+}
+
+/** Workers AI over REST from `CLOUDFLARE_ACCOUNT_ID` and `CLOUDHAL_AI_TOKEN` (RFC-0016 §1). */
+export function localAiTransport(env                                     = process.env)   
+                                               
+  {
+  const accountId = env.CLOUDFLARE_ACCOUNT_ID?.trim();
+  const token = env.CLOUDHAL_AI_TOKEN?.trim();
+  return accountId && token ? { transport: restTransport({ accountId, token }) } : {};
+}

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

@@ -0,0 +1,42 @@
+export interface SyncOptions {
+    readonly projectDir: string;
+    /** Overwrite diverged content on the receiving side. */
+    readonly replace?: boolean;
+    /**
+     * `cloudhal push --cancel-schedules` (RFC-0008 §16): cancel the deployment's open releases
+     * before replacing the graph their pins point into. Without it a push refuses while any exist.
+     */
+    readonly cancelSchedules?: boolean;
+    /** Admin Worker URL; default from `<dataDir>/deploy/state.json`. */
+    readonly adminUrl?: string;
+    readonly log?: (line: string) => void;
+    /** Injected in tests. */
+    readonly fetch?: typeof fetch;
+}
+/** Error bodies may be HTML pages (e.g. a not-yet-live workers.dev host); keep messages short. */
+export declare function brief(body: string): string;
+/** The deployment's admin Worker and its operator token (from `cloudhal deploy`'s state). */
+export declare function deployment(options: SyncOptions): Promise<{
+    cfg: import("../config.js").ProjectConfig;
+    adminUrl: string;
+    token: string;
+    fetch: typeof fetch;
+}>;
+export declare function pushSite(options: SyncOptions & {
+    ifAbsent?: boolean;
+}): Promise<{
+    pushed: boolean;
+    message: string;
+}>;
+/**
+ * Makes `hostname` the deployed site's primary domain (preview links, canonical URLs) and mirrors
+ * it in the local store. Used by `cloudhal deploy` once a custom domain is routed.
+ */
+export declare function setPrimaryDomain(options: SyncOptions & {
+    hostname: string;
+}): Promise<{
+    changed: boolean;
+}>;
+export declare function pullSite(options: SyncOptions): Promise<{
+    message: string;
+}>;

package/dist/src/commands/sync.js

@@ -0,0 +1,211 @@
+/**
+ * `cloudhal push` / `cloudhal pull`: move the site between the local project and its Cloudflare
+ * deployment through the admin Worker (`/api/admin/sites/:id/bundle`, deployment token).
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  exportSite,
+  importSite,
+  mediaBlobKey,
+                  
+  withPrimaryDomain,
+} from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+
+                              
+                              
+                                                          
+                             
+     
+                                                                                             
+                                                                                                 
+     
+                                     
+                                                                      
+                             
+                                        
+                           
+                                
+ 
+
+/** Error bodies may be HTML pages (e.g. a not-yet-live workers.dev host); keep messages short. */
+export function brief(body        )         {
+  const text = body
+    .replace(/<style[\s\S]*?<\/style>|<svg[\s\S]*?<\/svg>|<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+}
+
+/** The deployment's admin Worker and its operator token (from `cloudhal deploy`'s state). */
+export async function deployment(options             ) {
+  const cfg = await readProjectConfig(options.projectDir);
+  const dir = path.join(options.projectDir, cfg.dataDir, "deploy");
+  let adminUrl = options.adminUrl;
+  if (!adminUrl) {
+    try {
+      adminUrl = (
+        JSON.parse(await readFile(path.join(dir, "state.json"), "utf8"))                         
+      ).adminUrl;
+    } catch {
+      // not deployed
+    }
+  }
+  if (!adminUrl)
+    throw new Error("no deployment found: run `cloudhal deploy` first (or pass --admin-url)");
+  const secrets = JSON.parse(await readFile(path.join(dir, "secrets.json"), "utf8"))     
+                                   
+   ;
+  if (!secrets.CLOUDHAL_DEPLOY_TOKEN)
+    throw new Error("deployment token missing in .cloudhal/deploy/secrets.json");
+  return { cfg, adminUrl, token: secrets.CLOUDHAL_DEPLOY_TOKEN, fetch: options.fetch ?? fetch };
+}
+
+async function target(options             ) {
+  const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+  const url = new URL(`/api/admin/sites/${cfg.siteId}/bundle`, adminUrl);
+  return { cfg, url, token, fetch: f };
+}
+
+export async function pushSite(
+  options                                      ,
+)                                                {
+  const log = options.log ?? (() => {});
+  const { cfg, url, token, fetch: f } = await target(options);
+  const auth = { authorization: `Bearer ${token}` };
+  if (options.ifAbsent) {
+    const probe = await f(url, { headers: auth });
+    if (probe.status === 200) {
+      log(
+        "the deployment already has this site; leaving it as the source of truth (use `cloudhal pull`)",
+      );
+      return { pushed: false, message: "already deployed" };
+    }
+  }
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  let bundle            ;
+  try {
+    bundle = await exportSite(local, cfg.siteId);
+    // Media bytes first (RFC-0004 §4.7): the deployment refuses a bundle whose media it lacks.
+    let uploaded = 0;
+    for (const m of bundle.media ?? []) {
+      const mediaUrl = new URL(`/api/admin/sites/${cfg.siteId}/media/${m.sha256}`, url);
+      const head = await f(mediaUrl, { method: "HEAD", headers: auth });
+      if (head.status === 200) continue;
+      const bytes = await local.blobs.get(mediaBlobKey(cfg.siteId, m.sha256));
+      if (!bytes)
+        throw new Error(`local media ${m.sha256} is missing; run \`cloudhal media verify\``);
+      const put = await f(mediaUrl, {
+        method: "PUT",
+        headers: { ...auth, "content-type": "application/octet-stream" },
+        body: bytes,
+      });
+      if (!put.ok)
+        throw new Error(`uploading media failed (${put.status}): ${brief(await put.text())}`);
+      uploaded++;
+    }
+    if (uploaded) log(`media: ${uploaded} file(s) uploaded`);
+  } finally {
+    await local.close();
+  }
+  url.searchParams.set("mode", options.replace ? "replace" : "bootstrap");
+  if (options.cancelSchedules) url.searchParams.set("cancelSchedules", "1");
+  const res = await f(url, {
+    method: "PUT",
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify(bundle),
+  });
+  const body = await res.text();
+  if (res.status === 409 && /"error":"schedules_(pending|running)"/.test(body)) {
+    const parsed = JSON.parse(body)     
+                    
+                      
+                                                                                                   
+     ;
+    const list = (parsed.details?.releases ?? [])
+      .map(
+        (r) =>
+          `  ${r.id} ${r.state}${r.executeAt ? ` at ${r.executeAt}` : ""}${r.title ? ` — ${r.title}` : ""}`,
+      )
+      .join("\n");
+    throw new Error(
+      parsed.error === "schedules_running"
+        ? `${parsed.message}`
+        : `the deployment has open releases; a push replaces the graph their pinned versions point into:\n${list}\nCancel them in Studio, or push with --cancel-schedules.`,
+    );
+  }
+  if (res.status === 409)
+    throw new Error(
+      `the deployment has diverged from your local copy: ${brief(body)}\nRun \`cloudhal pull\` first, or \`cloudhal push --replace\` to overwrite.`,
+    );
+  if (!res.ok) throw new Error(`push failed (${res.status}): ${brief(body)}`);
+  log(`pushed: ${body}`);
+  return { pushed: true, message: body };
+}
+
+/**
+ * Makes `hostname` the deployed site's primary domain (preview links, canonical URLs) and mirrors
+ * it in the local store. Used by `cloudhal deploy` once a custom domain is routed.
+ */
+export async function setPrimaryDomain(
+  options                                    ,
+)                                {
+  const { cfg, url, token, fetch: f } = await target(options);
+  const res = await f(new URL(`/api/admin/sites/${cfg.siteId}/domains`, url), {
+    method: "PUT",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify({ primary: options.hostname }),
+  });
+  const body = await res.text();
+  if (!res.ok) throw new Error(`setting the site's domain failed (${res.status}): ${brief(body)}`);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    const site = await local.store.getSite(cfg.siteId);
+    if (site && site.domains.find((d) => d.primary)?.hostname !== options.hostname)
+      await local.store.updateSite({
+        ...site,
+        domains: withPrimaryDomain(site.domains, options.hostname),
+      });
+  } finally {
+    await local.close();
+  }
+  return { changed: (JSON.parse(body)                         ).changed === true };
+}
+
+export async function pullSite(options             )                               {
+  const log = options.log ?? (() => {});
+  const { cfg, url, token, fetch: f } = await target(options);
+  const res = await f(url, { headers: { authorization: `Bearer ${token}` } });
+  if (!res.ok) throw new Error(`pull failed (${res.status}): ${brief(await res.text())}`);
+  const bundle = (await res.json())              ;
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    // Media bytes first (RFC-0004 §4.7), verified by SHA-256 as they land.
+    let downloaded = 0;
+    for (const m of bundle.media ?? []) {
+      const key = mediaBlobKey(cfg.siteId, m.sha256);
+      if (await local.blobs.head(key)) continue;
+      const got = await f(new URL(`/api/admin/sites/${cfg.siteId}/media/${m.sha256}`, url), {
+        headers: { authorization: `Bearer ${token}` },
+      });
+      if (!got.ok) throw new Error(`downloading media failed (${got.status})`);
+      await local.blobs.put(key, new Uint8Array(await got.arrayBuffer()), {
+        sha256: m.sha256,
+        contentType: m.mediaType,
+      });
+      downloaded++;
+    }
+    if (downloaded) log(`media: ${downloaded} file(s) downloaded`);
+    const result = await importSite(local, bundle, {
+      mode: options.replace ? "replace" : "bootstrap",
+      log,
+    });
+    const message = JSON.stringify(result);
+    log(`pulled: ${message}`);
+    return { message };
+  } finally {
+    await local.close();
+  }
+}

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

@@ -0,0 +1,12 @@
+export interface TokensExportOptions {
+    readonly projectDir: string;
+    readonly format?: string;
+    /** A file to write; stdout otherwise. */
+    readonly out?: string;
+}
+/**
+ * `cloudhal tokens export` (RFC-0023 §5): the site's design tokens, as the renderer expands them,
+ * in the W3C Design Tokens format (DTCG 2025.10), for Figma (Tokens Studio) and Style Dictionary.
+ * Returns the JSON written.
+ */
+export declare function tokensExport(options: TokensExportOptions): Promise<string>;