@cloudhal/cli 0.0.0-stage → 0.1.1

package/dist/src/commands/media.js

@@ -0,0 +1,182 @@
+/**
+ * `cloudhal media …` (RFC-0004): local media maintenance.
+ *
+ * - `import-urls [--dry-run] [--include-markdown] [--allow-host <h>]… | --revert <id>` copies images
+ *   that pages, entries and terms link by URL into the media library. https URLs go through the
+ *   SSRF-safe fetcher (resolved, checked and pinned on Node); site paths (`/images/x.jpg`) are read
+ *   from the project's `public/` directory and must stay inside it; `http:` and anything else is
+ *   skipped and reported. Revertible; nothing goes live until someone publishes.
+ * - `verify [assetId]` recomputes the SHA-256 of stored blobs; for an external file it streams the
+ *   URL (no size cap, this host only) and records a computed checksum.
+ * - `gc [--dry-run]` collects unreferenced content older than 24 hours.
+ */
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import {
+  importMediaUrls,
+                    
+                         
+                         
+  revertMediaImport,
+} from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import {                      MEDIA_LIMITS, MEDIA_TYPES, safeFetch } from "@cloudhal/core-ts/media";
+import { nodeTransport } from "@cloudhal/core-ts/media-node";
+import { readProjectConfig } from "../config.js";
+
+const PERSON = { kind: "human"         , id: "user_localcli001", name: "cloudhal media" };
+
+                                        
+                              
+                            
+                                     
+                           
+                                                                                                     
+                                          
+                                                                                       
+                                      
+ 
+
+/**
+ * A site path read from `public/`, confined to it: the resolved real path must stay inside the
+ * directory (no `..`, no symlink out of it).
+ */
+async function readPublic(projectDir        , sitePath        )                        {
+  const clean = decodeURIComponent(sitePath.split(/[?#]/)[0] ?? "");
+  if (!clean.startsWith("/") || clean.includes("\0") || clean.includes("\\"))
+    return { skip: "not a site path" };
+  const root = await realpath(path.join(projectDir, "public")).catch(() => undefined);
+  if (!root) return { skip: "the project has no public/ directory" };
+  const file = path.resolve(root, `.${clean}`);
+  const real = await realpath(file).catch(() => undefined);
+  if (!real?.startsWith(`${root}${path.sep}`))
+    return { skip: "not found in public/ (or outside it)" };
+  return { bytes: new Uint8Array(await readFile(real)) };
+}
+
+export async function mediaImportUrls(
+  options                       ,
+)                                                 {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    if (options.revert)
+      return await revertMediaImport(local.store, cfg.siteId, options.revert, { actor: PERSON });
+    const site = await local.store.getSite(cfg.siteId);
+    const siteHosts = (site?.metadata?.["cloudhal.media.allowHosts"] ?? "")
+      .split(/[\s,]+/)
+      .filter(Boolean);
+    const allowHosts = [...(options.allowHosts ?? []), ...siteHosts];
+    const transport = options.transport ?? nodeTransport();
+    return await importMediaUrls(local.store, cfg.siteId, {
+      actor: PERSON,
+      ...(options.dryRun ? { dryRun: true } : {}),
+      ...(options.includeMarkdown ? { includeMarkdown: true } : {}),
+      load: async (from) => {
+        if (from.startsWith("/") && !from.startsWith("//"))
+          return readPublic(options.projectDir, from);
+        if (!from.startsWith("https://"))
+          return { skip: "only https URLs and site paths are imported" };
+        const res = await safeFetch(from, {
+          transport,
+          maxBytes: MEDIA_LIMITS.fetchAsset,
+          accept: Object.keys(MEDIA_TYPES).filter((t) => t.startsWith("image/")),
+          ...(allowHosts.length ? { allowHosts } : {}),
+          blockedHosts: (site?.domains ?? []).map((d) => d.hostname),
+        });
+        return { bytes: res.bytes, contentType: res.contentType };
+      },
+    });
+  } finally {
+    await local.close();
+  }
+}
+
+                               
+                           
+                        
+                                                            
+ 
+
+export async function mediaVerify(options   
+                     
+                   
+                             
+ )                        {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    const store = local.store;
+    const assets = options.assetId
+      ? [await store.getAsset(options.assetId)].filter((a) => a?.siteId === cfg.siteId)
+      : (await store.listAssets(cfg.siteId, { limit: 200 })).assets;
+    if (options.assetId && assets.length === 0)
+      throw new Error(`asset ${options.assetId} not found`);
+    const ok           = [];
+    const problems                           = [];
+    for (const asset of assets) {
+      if (!asset) continue;
+      if (asset.storage.kind === "blob") {
+        const r = await store.verifyMediaBlob(cfg.siteId, asset.sha256);
+        if (r === "ok") ok.push(asset.id);
+        else
+          problems.push({
+            assetId: asset.id,
+            problem: r === "missing" ? "bytes missing" : "SHA-256 mismatch",
+          });
+        continue;
+      }
+      // External: only when asked for by id (it downloads the whole file).
+      if (!options.assetId) continue;
+      const hash = createHash("sha256");
+      const res = await safeFetch(asset.storage.url, {
+        transport: options.transport ?? nodeTransport(),
+        maxBytes: Number.MAX_SAFE_INTEGER,
+        accept: [],
+        totalTimeoutMs: 6 * 60 * 60 * 1000,
+        onChunk: (c) => hash.update(c),
+      });
+      const sha256 = hash.digest("hex");
+      await store.verifyExternalAsset(asset, { sha256, bytes: res.size });
+      if (sha256 === asset.sha256) ok.push(asset.id);
+      else
+        problems.push({
+          assetId: asset.id,
+          problem: `declared ${asset.sha256}, computed ${sha256} (recorded)`,
+        });
+    }
+    return { checked: ok.length + problems.length, ok, problems };
+  } finally {
+    await local.close();
+  }
+}
+
+export async function mediaGc(options                                          ) {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    return await local.store.collectMediaGarbage(cfg.siteId, {
+      ...(options.dryRun ? { dryRun: true } : {}),
+    });
+  } finally {
+    await local.close();
+  }
+}
+
+/** Human-readable lines for a run. */
+export function describeMediaImport(r                                       )           {
+  if ("restored" in r)
+    return [
+      `reverted ${r.migrationId}: ${r.restored} node(s) restored, ${r.assetsDeleted} asset(s) deleted`,
+      ...(r.edited.length ? [`left alone (edited since): ${r.edited.join(", ")}`] : []),
+    ];
+  return [
+    r.dryRun
+      ? `dry run: ${r.sources.length} source(s) in ${r.nodes} node(s)`
+      : `imported ${r.assets.length} file(s) into ${r.nodes} node(s); migration id ${r.migrationId}`,
+    ...r.sources.map((s) => `  ${s}`),
+    ...r.skipped.map((s) => `skipped ${s.from}: ${s.reason}`),
+    ...(r.dryRun ? [] : ["nothing is live until you publish; undo with --revert <migration id>"]),
+  ];
+}

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

@@ -0,0 +1,16 @@
+import type { TagsMigrationResult, TagsRevertResult } from "@cloudhal/core-ts";
+export interface MigrateTagsOptions {
+    readonly projectDir: string;
+    /** Report what would change; write nothing. */
+    readonly dryRun?: boolean;
+    /** Undo the run with this migration id (the id of its `before tags-to-terms` snapshot). */
+    readonly revert?: string;
+}
+/**
+ * `cloudhal migrate tags-to-terms`: moves `ContentEntry.tags` into tag terms on the local site
+ * (RFC-0002). Resumable and idempotent; `--revert <id>` restores the tags of entries nobody edited
+ * since. Nothing goes live until a person publishes.
+ */
+export declare function migrateTags(options: MigrateTagsOptions): Promise<TagsMigrationResult | TagsRevertResult>;
+/** Human-readable summary lines for the terminal. */
+export declare function describeMigration(result: TagsMigrationResult | TagsRevertResult): string[];

package/dist/src/commands/migrate.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+                                                                               
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+
+                                     
+                              
+                                                 
+                            
+                                                                                             
+                           
+ 
+
+const CLI_ACTOR = { kind: "human", id: "user_localcli0001", name: "cloudhal CLI" }         ;
+
+/**
+ * `cloudhal migrate tags-to-terms`: moves `ContentEntry.tags` into tag terms on the local site
+ * (RFC-0002). Resumable and idempotent; `--revert <id>` restores the tags of entries nobody edited
+ * since. Nothing goes live until a person publishes.
+ */
+export async function migrateTags(
+  options                    ,
+)                                                  {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    if (options.revert !== undefined)
+      return await local.store.revertTagsToTerms(cfg.siteId, options.revert, { actor: CLI_ACTOR });
+    return await local.store.migrateTagsToTerms(cfg.siteId, CLI_ACTOR, {
+      ...(options.dryRun ? { dryRun: true } : {}),
+    });
+  } finally {
+    await local.close();
+  }
+}
+
+/** Human-readable summary lines for the terminal. */
+export function describeMigration(result                                        )           {
+  if ("restored" in result)
+    return [
+      `reverted ${result.migrationId}: ${result.restored} entries got their tags back`,
+      ...(result.edited.length
+        ? [`left untouched (edited since the migration): ${result.edited.join(", ")}`]
+        : []),
+      `deleted ${result.termsDeleted} unused terms${result.taxonomiesDeleted.length ? ` and the empty taxonomies ${result.taxonomiesDeleted.join(", ")}` : ""}`,
+      `snapshot ${result.snapshotId}`,
+    ];
+  if (result.upToDate) return ["nothing to migrate: no entry has tags and the taxonomies exist"];
+  const lines = [
+    `${result.dryRun ? "would migrate" : "migrated"} ${result.entries} entries: ${result.tags.length} distinct tags, ${result.termsCreated} new terms, ${result.termsReused} reused${result.resumed ? " (resumed)" : ""}`,
+  ];
+  if (result.taxonomiesCreated.length)
+    lines.push(
+      `${result.dryRun ? "would create" : "created"} taxonomies: ${result.taxonomiesCreated.join(", ")} (category not required on existing sites)`,
+    );
+  for (const s of result.skipped) lines.push(`skipped ${s.entryId}: ${s.reason}`);
+  if (!result.dryRun)
+    lines.push(
+      `migration id ${result.migrationId} (undo: cloudhal migrate tags-to-terms --revert ${result.migrationId})`,
+      "nothing is live yet: review the snapshot diff and publish",
+    );
+  return lines;
+}

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

@@ -0,0 +1,29 @@
+import type { Page } from "@cloudhal/core-contracts";
+/** What one page asks to move (RFC-0024), counted from its surfaces without a browser. */
+export interface PageMotion {
+    path: string;
+    /** The page's own level, else the site's. */
+    level: string;
+    reveals: number;
+    hovers: number;
+    scroll: number;
+    splits: number;
+    loops: number;
+    ambient: number;
+    stories: number;
+    morphs: string[];
+    warnings: string[];
+}
+export interface MotionAudit {
+    level: string;
+    pageTransition: string;
+    pages: PageMotion[];
+}
+/** The budgets of RFC-0024 §2, as `render_page`'s motion-budget check counts them. */
+export declare function auditPage(page: Pick<Page, "path" | "sections" | "motion">, site: string): PageMotion;
+/** `cloudhal motion audit`: the motion every page of the local site asks for, and its budgets. */
+export declare function motionAudit(options: {
+    projectDir: string;
+    path?: string;
+}): Promise<MotionAudit>;
+export declare function describeMotionAudit(a: MotionAudit): string;

package/dist/src/commands/motion.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+                                                                                       
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+
+/** What one page asks to move (RFC-0024), counted from its surfaces without a browser. */
+                             
+               
+                                               
+                
+                  
+                 
+                 
+                 
+                
+                  
+                  
+                   
+                     
+ 
+
+                              
+                
+                         
+                      
+ 
+
+const isObj = (v         )                               =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The budgets of RFC-0024 §2, as `render_page`'s motion-budget check counts them. */
+export function auditPage(
+  page                                            ,
+  site        ,
+)             {
+  const all                     = page.sections
+    .filter((s)                      => s.kind === "surface")
+    .flatMap((s) => s.components);
+  const m = (c                  ) => (isObj(c.motion) ? c.motion : {});
+  const count = (f                                  ) => all.filter(f).length;
+  const out             = {
+    path: page.path,
+    level: page.motion ?? site,
+    reveals: count((c) => typeof m(c).reveal === "string"),
+    hovers: count((c) => typeof m(c).hover === "string"),
+    scroll: count((c) => typeof m(c).scroll === "string"),
+    splits: count((c) => String(m(c).reveal ?? "").startsWith("split-")),
+    loops: count(
+      (c) =>
+        typeof m(c).loop === "string" ||
+        c.component === "Marquee" ||
+        (c.component === "Heading" && isObj(c.props) && c.props.effect === "rotate-words"),
+    ),
+    ambient: count((c) => isObj(c.props) && isObj(c.props.ambient)),
+    stories: count((c) => c.component === "Scrolly"),
+    morphs: all.map((c) => m(c).morph).filter((k)              => typeof k === "string"),
+    warnings: [],
+  };
+  if (out.scroll > 6) out.warnings.push(`${out.scroll} scroll effects (keep to 6)`);
+  if (out.stories > 1) out.warnings.push(`${out.stories} scroll stories (keep to 1)`);
+  if (out.splits > 2) out.warnings.push(`${out.splits} split texts (keep to 2)`);
+  if (out.loops > 2) out.warnings.push(`${out.loops} things that loop (keep to 2)`);
+  if (out.ambient > 2) out.warnings.push(`${out.ambient} ambient backgrounds (keep to 2)`);
+  const dup = out.morphs.filter((k, i) => out.morphs.indexOf(k) !== i);
+  if (dup.length) out.warnings.push(`morph keys used twice: ${[...new Set(dup)].join(", ")}`);
+  if (out.level === "none" && out.reveals + out.scroll + out.loops + out.ambient > 0)
+    out.warnings.push("motion presets on a page whose level is none: nothing will move");
+  return out;
+}
+
+/** `cloudhal motion audit`: the motion every page of the local site asks for, and its budgets. */
+export async function motionAudit(options   
+                     
+                
+ )                       {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    const site = await local.store.getSite(cfg.siteId);
+    if (!site) throw new Error(`site ${cfg.siteId} not found`);
+    const config = site.theme.config ?? {};
+    const level = typeof config.motion === "string" ? config.motion : "none";
+    const pages = (await local.store.listPages(cfg.siteId))
+      .filter((p) => !options.path || p.path === options.path)
+      .sort((a, b) => a.path.localeCompare(b.path));
+    return {
+      level,
+      pageTransition: typeof config.pageTransition === "string" ? config.pageTransition : "none",
+      pages: pages.map((p) => auditPage(p, level)),
+    };
+  } finally {
+    await local.close();
+  }
+}
+
+export function describeMotionAudit(a             )         {
+  const lines = [`site motion: ${a.level}, page transition: ${a.pageTransition}`];
+  for (const p of a.pages) {
+    const parts = (
+      [
+        ["reveals", p.reveals],
+        ["hovers", p.hovers],
+        ["scroll", p.scroll],
+        ["splits", p.splits],
+        ["loops", p.loops],
+        ["ambient", p.ambient],
+        ["stories", p.stories],
+      ]         
+    )
+      .filter(([, n]) => n > 0)
+      .map(([k, n]) => `${k} ${n}`);
+    lines.push(
+      `${p.path}  (${p.level})  ${parts.length ? parts.join(", ") : "still"}${p.morphs.length ? `  morph: ${p.morphs.join(", ")}` : ""}`,
+    );
+    for (const w of p.warnings) lines.push(`  ! ${w}`);
+  }
+  return lines.join("\n");
+}

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

@@ -0,0 +1,18 @@
+/**
+ * `cloudhal owner transfer --to <email>` — Owner lockout recovery (RFC-0005 §3, open question 7).
+ * The operator, who holds the deployment token and is already root for site data, makes an
+ * existing member the deployment's Owner; the current Owner becomes an Administrator. Audited as
+ * `member.transfer-ownership` with `via: "deploy-token"`.
+ */
+import { type SyncOptions } from "./sync.js";
+export interface OwnerTransferOptions extends SyncOptions {
+    /** Email of the member who becomes the Owner. */
+    readonly to: string;
+}
+export interface OwnerTransferResult {
+    from: string | null;
+    to: string;
+    name: string;
+    email: string;
+}
+export declare function transferOwner(options: OwnerTransferOptions): Promise<OwnerTransferResult>;

package/dist/src/commands/owner.js

@@ -0,0 +1,39 @@
+/**
+ * `cloudhal owner transfer --to <email>` — Owner lockout recovery (RFC-0005 §3, open question 7).
+ * The operator, who holds the deployment token and is already root for site data, makes an
+ * existing member the deployment's Owner; the current Owner becomes an Administrator. Audited as
+ * `member.transfer-ownership` with `via: "deploy-token"`.
+ */
+import { brief, deployment,                  } from "./sync.js";
+
+                                                           
+                                                   
+                      
+ 
+
+                                      
+                      
+             
+               
+                
+ 
+
+export async function transferOwner(options                      )                               {
+  const email = options.to.trim();
+  if (!email.includes("@")) throw new Error("usage: cloudhal owner transfer --to <email>");
+  const { adminUrl, token, fetch: f } = await deployment(options);
+  const res = await f(new URL("/api/admin/owner", adminUrl), {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  const body = await res.text();
+  if (res.status === 404)
+    throw new Error(
+      `no member with the email ${email} on this deployment (invite them first): ${brief(body)}`,
+    );
+  if (!res.ok) throw new Error(`owner transfer failed (${res.status}): ${brief(body)}`);
+  const result = JSON.parse(body)                       ;
+  options.log?.(`${result.name} <${result.email}> is now the Owner`);
+  return result;
+}

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

@@ -0,0 +1,26 @@
+import { type RenderCheck } from "@cloudhal/mcp-server/render";
+export interface RenderOptions {
+    readonly projectDir: string;
+    /** A path on the site (`/pricing`) or a full URL. */
+    readonly target: string;
+    /** Where a path is served; `cloudhal dev` by default. */
+    readonly base?: string;
+    readonly widths?: readonly number[];
+    readonly scheme?: string;
+    readonly motion?: string;
+    readonly frames?: number;
+    /** The folder for the screenshots, relative to the project. */
+    readonly out?: string;
+}
+export interface RenderReport {
+    url: string;
+    files: string[];
+    checks: RenderCheck[];
+}
+/**
+ * `cloudhal render` (RFC-0024 §8): `render_page`'s browser and checks from the command line, for a
+ * page of the running site (`cloudhal dev`) or any URL. Screenshots go to `.cloudhal/renders/`.
+ */
+export declare function render(options: RenderOptions): Promise<RenderReport>;
+/** The report as text: the screenshots, then each failed check with its examples. */
+export declare function describeRender(r: RenderReport): string;

package/dist/src/commands/render.js

@@ -0,0 +1,94 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  RENDER_MOTIONS,
+  RENDER_SCHEMES,
+  RENDER_WIDTHS,
+                   
+                    
+                    
+                   
+  renderPage,
+} from "@cloudhal/mcp-server/render";
+import { chromeRenderer, findChrome } from "../render-chrome.js";
+
+                                
+                              
+                                                       
+                          
+                                                           
+                         
+                                      
+                           
+                           
+                           
+                                                                 
+                        
+ 
+
+                               
+              
+                  
+                        
+ 
+
+/**
+ * `cloudhal render` (RFC-0024 §8): `render_page`'s browser and checks from the command line, for a
+ * page of the running site (`cloudhal dev`) or any URL. Screenshots go to `.cloudhal/renders/`.
+ */
+export async function render(options               )                        {
+  const chrome = findChrome();
+  if (!chrome) throw new Error("no Chrome found (set CHROME_PATH)");
+  const url = /^https?:\/\//.test(options.target)
+    ? options.target
+    : new URL(options.target, options.base ?? "http://localhost:4321").href;
+  const widths = (options.widths?.length ? options.widths : [1440, 390]).filter(
+    (w)                   => (RENDER_WIDTHS                     ).includes(w),
+  );
+  if (!widths.length) throw new Error(`--width: one or more of ${RENDER_WIDTHS.join(", ")}`);
+  const pick =                   (v                    , allowed              , name        ) => {
+    if (v === undefined) return undefined;
+    if (!(allowed                     ).includes(v))
+      throw new Error(`--${name}: one of ${allowed.join(", ")}`);
+    return v     ;
+  };
+  const scheme = pick              (options.scheme, RENDER_SCHEMES, "scheme");
+  const frames = options.frames ? Math.min(6, Math.max(1, Math.round(options.frames))) : 0;
+  const motion =
+    pick              (options.motion, RENDER_MOTIONS, "motion") ?? (frames ? "full" : "static");
+  const result = await renderPage(chromeRenderer(chrome), url, {
+    widths,
+    fullPage: true,
+    ...(scheme ? { scheme } : {}),
+    motion,
+    ...(frames ? { frames } : {}),
+    timeoutMs: 60_000,
+  });
+  const dir = path.resolve(options.projectDir, options.out ?? ".cloudhal/renders");
+  await mkdir(dir, { recursive: true });
+  const slug = new URL(url).pathname.replace(/^\/|\/$/g, "").replace(/[^a-z0-9]+/gi, "-") || "home";
+  const files           = [];
+  for (const shot of result.shots)
+    for (const [i, jpeg] of shot.images.entries()) {
+      const file = path.join(dir, `${slug}-${shot.width}-${i + 1}.jpg`);
+      await writeFile(file, jpeg);
+      files.push(path.relative(options.projectDir, file));
+    }
+  return { url, files, checks: result.checks };
+}
+
+/** The report as text: the screenshots, then each failed check with its examples. */
+export function describeRender(r              )         {
+  const failed = r.checks.filter((c) => !c.ok);
+  return [
+    `rendered ${r.url}`,
+    ...r.files.map((f) => `  ${f}`),
+    failed.length
+      ? `${failed.length} of ${r.checks.length} checks found problems:`
+      : `all ${r.checks.length} checks passed`,
+    ...failed.flatMap((c) => [
+      `✗ ${c.id}: ${c.count} at ${c.widths.join(", ")} px`,
+      ...c.examples.map((e) => `    ${e}`),
+    ]),
+  ].join("\n");
+}

package/dist/src/commands/scheduler-local.d.ts

@@ -0,0 +1,55 @@
+import type { SiteGraphStore } from "@cloudhal/core-ts";
+import { type BuiltinInputs, type NotFoundAnalytics } from "@cloudhal/core-ts/automations";
+import { type SchedulerControl, type TickReport, type TickTrigger } from "@cloudhal/core-ts/releases";
+import { type SystemJobDefinition } from "@cloudhal/schedules";
+import type { BlobStore, SqlDriver } from "@cloudhal/storage";
+/** The longest the Node timer sleeps (§8.4). */
+export declare const NODE_TICK_MAX_MS = 60000;
+/**
+ * The deployment's automations switch on Node (RFC-0008 §11.6): `CLOUDHAL_AUTOMATIONS=off` stops
+ * them, as on the admin Worker; anything else (or nothing) leaves them on.
+ */
+export declare function automationsEnabled(env?: Readonly<Record<string, string | undefined>>): boolean;
+export interface LocalSchedulerOptions {
+    readonly sql: SqlDriver;
+    readonly blobs: BlobStore;
+    readonly graph: SiteGraphStore;
+    /** Runs the comments job hourly (studio, mcp, dev). Default true. */
+    readonly comments?: boolean;
+    readonly log?: (line: string) => void;
+    /** Clock and timers (tests). */
+    readonly now?: () => Date;
+    readonly maxIntervalMs?: number;
+    /** The project's analytics (the broken-link sweep's 404 rows, RFC-0008 §11.1). */
+    readonly analytics?: NotFoundAnalytics | undefined;
+    /**
+     * Where the local renderer serves the site (`cloudhal dev`): the feed check fetches its
+     * `/rss.xml` and `/sitemap.xml` there. Absent (Studio, MCP): the feed check has nothing to fetch.
+     */
+    readonly siteOrigin?: string | undefined;
+    /** The site the local renderer serves (`cloudhal.json` `siteId`). */
+    readonly siteId?: string | undefined;
+    /** Automations run (§11.6). Default: `automationsEnabled()` of the process environment. */
+    readonly automations?: boolean | undefined;
+}
+/** What the Node ticker adds for the built-in jobs (§11.1): local analytics and the local renderer. */
+export declare function localBuiltinInputs(o: LocalSchedulerOptions): BuiltinInputs;
+/** The deployment's periodic jobs on Node: the comments job and the schedules retention. */
+export declare function localSystemJobs(sql: SqlDriver, graph: SiteGraphStore, o: {
+    comments: boolean;
+    log: (line: string) => void;
+}): SystemJobDefinition[];
+/** One tick on the project's SQLite (the Node timer, `cloudhal schedules run-due`). */
+export declare function runLocalTick(o: LocalSchedulerOptions & {
+    trigger: TickTrigger;
+    at?: Date;
+}): Promise<TickReport>;
+export interface LocalScheduler extends SchedulerControl {
+    /** Resolves once the catch-up tick at start has run (tests). */
+    readonly started: Promise<void>;
+    /** The next timer, as an instant (tests). */
+    nextAt(): number | undefined;
+    stop(): void;
+}
+/** Starts the Node ticker (catch-up now, then at most every 60 s). */
+export declare function startLocalScheduler(o: LocalSchedulerOptions): LocalScheduler;