@cloudhal/cli 0.0.0-stage → 0.1.0

package/dist/src/commands/scheduler-local.js

@@ -0,0 +1,237 @@
+/**
+ * The scheduler on Node (RFC-0008 §8.4): `cloudhal dev`, `cloudhal studio` and `cloudhal mcp` run
+ * the same `runDue` as the admin Worker, on a timer of at most 60 s — re-armed after every tick at
+ * `min(nextWakeAt − now, 60 s)` (1 s while there is more), moved earlier by pokes, `unref`'d — with
+ * a catch-up tick at start, so releases and occurrences missed while the process was down follow
+ * the missed-run rules (within the hour: run; later: `missed`). Several processes on one SQLite
+ * file are safe: every effect is claimed with a lease.
+ *
+ * It replaces the hourly interval of `startLocalCommentsJob`: the comments job (and the schedules
+ * retention) are system jobs behind watermarks on the tick. There is no edge cache, so releases
+ * purge nothing (`none`).
+ *
+ * `CLOUDHAL_AUTOMATIONS=off` in the process environment is the deployment's kill switch here too
+ * (§11.6): automations stop (no occurrences, no windows, automation keys refused); releases and
+ * gates go on.
+ */
+import { releaseApprovalCheck } from "@cloudhal/api";
+import { SqlCommentStore } from "@cloudhal/comments/sql";
+                                                        
+import {
+                     
+                         
+  notFoundFromAnalytics,
+} from "@cloudhal/core-ts/automations";
+import {
+  runScheduledTick,
+                        
+                  
+                   
+} from "@cloudhal/core-ts/releases";
+import { dailyAt, hourlyAt,                           TICK_BUDGETS } from "@cloudhal/schedules";
+import { SqlScheduleStore } from "@cloudhal/schedules/sql";
+                                                              
+import { runLocalCommentsJob } from "./comments-local.js";
+
+/** The longest the Node timer sleeps (§8.4). */
+export const NODE_TICK_MAX_MS = 60_000;
+
+/**
+ * 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 function automationsEnabled(
+  env                                               = process.env,
+) {
+  return env.CLOUDHAL_AUTOMATIONS?.trim().toLowerCase() !== "off";
+}
+
+                                        
+                          
+                            
+                                 
+                                                                       
+                              
+                                        
+                                  
+                            
+                                  
+                                                                                    
+                                                     
+     
+                                                                                          
+                                                                                                    
+     
+                                           
+                                                                       
+                                       
+                                                                                             
+                                             
+ 
+
+/** What the Node ticker adds for the built-in jobs (§11.1): local analytics and the local renderer. */
+export function localBuiltinInputs(o                       )                {
+  const origin = o.siteOrigin;
+  return {
+    ...(o.analytics ? { notFound: notFoundFromAnalytics(o.analytics) } : {}),
+    ...(origin
+      ? {
+          fetchDocument: async ({ siteId, path }                                  ) => {
+            if (o.siteId && o.siteId !== siteId) return undefined;
+            const res = await fetch(new URL(path, origin));
+            const contentType = res.headers.get("content-type");
+            return {
+              status: res.status,
+              ...(contentType ? { contentType } : {}),
+              body: await res.text(),
+            };
+          },
+        }
+      : {}),
+  };
+}
+
+/** The deployment's periodic jobs on Node: the comments job and the schedules retention. */
+export function localSystemJobs(
+  sql           ,
+  graph                ,
+  o                                                    ,
+)                        {
+  const jobs                        = [
+    {
+      name: "schedules.retention",
+      cost: 3,
+      next: dailyAt(3, 27),
+      async run({ now }) {
+        const r = await new SqlScheduleStore(sql).applyRetention(now.toISOString());
+        if (r.runs + r.releases > 0)
+          o.log(`schedules retention: ${r.runs} run(s), ${r.releases} release(s) deleted`);
+      },
+    },
+  ];
+  if (o.comments)
+    jobs.push({
+      name: "comments.hourly",
+      cost: 20,
+      next: hourlyAt(17),
+      async run({ now }) {
+        const r = await runLocalCommentsJob(graph, new SqlCommentStore(sql), now);
+        o.log(
+          `comments hourly: ${r.sites} site(s), ${r.retained} row(s) past retention${r.more ? " (more next run)" : ""}, ${r.closed} thread(s) closed`,
+        );
+      },
+    });
+  return jobs;
+}
+
+/** One tick on the project's SQLite (the Node timer, `cloudhal schedules run-due`). */
+export function runLocalTick(
+  o                                                             ,
+)                      {
+  const log = o.log ?? (() => {});
+  return runScheduledTick({
+    sql: o.sql,
+    blobs: o.blobs,
+    now: o.at ?? (o.now ?? (() => new Date()))(),
+    trigger: o.trigger,
+    wake: "computed",
+    // no platform limit on Node; the same bounded steps
+    budget: TICK_BUDGETS.paid,
+    log,
+    systemJobs: ({ counted }) =>
+      localSystemJobs(counted, o.graph, { comments: o.comments !== false, log }),
+    // RFC-0008 §10.6: the approver may still approve it, an auto release's key still holds.
+    checkApproval: releaseApprovalCheck({ sql: o.sql, graph: o.graph }),
+    // RFC-0008 §11.1: the built-in jobs (their notifications are derived from the runs).
+    builtinInputs: () => localBuiltinInputs(o),
+    // §11.6: `CLOUDHAL_AUTOMATIONS=off` stops automations; releases go on.
+    automationsEnabled: o.automations ?? automationsEnabled(),
+  });
+}
+
+                                                          
+                                                                  
+                                  
+                                               
+                               
+               
+ 
+
+/** Starts the Node ticker (catch-up now, then at most every 60 s). */
+export function startLocalScheduler(o                       )                 {
+  const log = o.log ?? ((l        ) => process.stderr.write(`${l}\n`));
+  const clock = o.now ?? (() => new Date());
+  const max = o.maxIntervalMs ?? NODE_TICK_MAX_MS;
+  let timer                                           ;
+  let at                    ;
+  let running                                             ;
+  let again = false;
+  let stopped = false;
+
+  const arm = (when        ) => {
+    if (stopped) return;
+    const now = clock().getTime();
+    const target = Math.max(now + 1_000, Math.min(when, now + max));
+    if (timer && at !== undefined && at <= target) return;
+    if (timer) clearTimeout(timer);
+    at = target;
+    timer = setTimeout(() => {
+      timer = undefined;
+      at = undefined;
+      void tick("node");
+    }, target - now);
+    timer.unref?.();
+  };
+
+  const tick = async (trigger             )                                  => {
+    if (running) {
+      again = true;
+      return running;
+    }
+    running = (async () => {
+      let report                        ;
+      try {
+        report = await runLocalTick({ ...o, log, trigger, at: clock() });
+      } catch (e) {
+        log(`schedules tick (${trigger}) failed: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      const now = clock().getTime();
+      const next = !report
+        ? now + max
+        : report.more
+          ? now + 1_000
+          : report.nextWakeAt
+            ? Date.parse(report.nextWakeAt)
+            : now + max;
+      arm(next);
+      return report;
+    })();
+    try {
+      return await running;
+    } finally {
+      running = undefined;
+      if (again && !stopped) {
+        again = false;
+        arm(clock().getTime());
+      }
+    }
+  };
+
+  const started = tick("node").then(() => {});
+  return {
+    mode: "node",
+    started,
+    async poke(when        ) {
+      const t = Date.parse(when);
+      arm(Number.isFinite(t) ? t : clock().getTime());
+    },
+    runDue: (trigger) =>
+      tick(trigger).then((r) => r ?? { ran: 0, late: 0, failed: 1, more: false }),
+    nextAt: () => at,
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+}

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

@@ -0,0 +1,32 @@
+import { type ReleaseSummary, type SchedulerHealthReport, type TickReport } from "@cloudhal/core-ts/releases";
+import { type SyncOptions } from "./sync.js";
+export interface SchedulesCliOptions extends SyncOptions {
+    /** Talk to the deployment (deployment token) instead of the local SQLite. */
+    readonly remote?: boolean;
+    /** Clock (tests). */
+    readonly now?: () => Date;
+}
+export interface SchedulesStatusReport {
+    readonly where: "local" | "remote";
+    readonly engine: {
+        readonly schedulesLevel: number;
+    };
+    readonly scheduler: SchedulerHealthReport;
+    readonly sites: readonly {
+        readonly siteId: string;
+        readonly name?: string;
+        readonly openReleases: readonly ReleaseSummary[];
+        readonly gatedNodes: number;
+    }[];
+}
+/** `cloudhal schedules status`. */
+export declare function schedulesStatus(options: SchedulesCliOptions): Promise<SchedulesStatusReport>;
+export declare function describeSchedulesStatus(s: SchedulesStatusReport): string[];
+export declare function describeRelease(r: ReleaseSummary): string;
+/** `cloudhal schedules list`: the site's releases, open first by time, then recent ones. */
+export declare function schedulesList(options: SchedulesCliOptions & {
+    limit?: number;
+}): Promise<ReleaseSummary[]>;
+/** `cloudhal schedules run-due`: one tick now (`manual`), locally or on the deployment. */
+export declare function schedulesRunDue(options: SchedulesCliOptions): Promise<TickReport>;
+export declare function describeTick(r: TickReport): string;

package/dist/src/commands/schedules.js

@@ -0,0 +1,170 @@
+/**
+ * `cloudhal schedules status | list | run-due` (RFC-0008 §16): the scheduler's health, the open
+ * releases and gated pages of the project's site, and a tick on demand — on the project's SQLite,
+ * or with `--remote` on the deployment (deployment token: `/api/admin/schedules/*`). Self-hosters
+ * without a long-running process run `cloudhal schedules run-due` from the system's cron every
+ * minute (§8.4).
+ */
+import path from "node:path";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import {
+  gatedNodeCount,
+  ReleaseService,
+                      
+  releaseSummary,
+  SCHEDULES_ENGINE_LEVEL,
+                             
+  schedulerHealthReport,
+                  
+} from "@cloudhal/core-ts/releases";
+import { readProjectConfig } from "../config.js";
+import { runLocalTick } from "./scheduler-local.js";
+import { brief, deployment,                  } from "./sync.js";
+
+                                                          
+                                                                               
+                            
+                       
+                            
+ 
+
+                                        
+                                     
+                                                       
+                                            
+                            
+                            
+                           
+                                                     
+                                
+      
+ 
+
+async function remoteJson   (
+  options                     ,
+  p        ,
+  init              = {},
+)                                                                           {
+  const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+  const res = await f(new URL(p.replace(":siteId", cfg.siteId), adminUrl), {
+    ...init,
+    headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
+  });
+  const text = await res.text();
+  if (res.status === 404 && p.startsWith("/api/admin/schedules"))
+    throw new Error(
+      "the deployment does not run schedules yet (deploy this version with `cloudhal deploy` first)",
+    );
+  if (!res.ok) throw new Error(`the deployment answered ${res.status}: ${brief(text)}`);
+  return { cfg, body: 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, cfg.siteId);
+  } finally {
+    await local.close();
+  }
+}
+
+/** `cloudhal schedules status`. */
+export async function schedulesStatus(
+  options                     ,
+)                                 {
+  if (options.remote) {
+    const { body } = await remoteJson                                      (
+      options,
+      "/api/admin/schedules/status",
+    );
+    return { ...body, where: "remote" };
+  }
+  const now = (options.now ?? (() => new Date()))();
+  return withLocal(options.projectDir, async (local) => {
+    const releases = new ReleaseService({ graph: local.store });
+    const sites = [];
+    for (const site of await local.store.listSites())
+      sites.push({
+        siteId: site.id,
+        name: site.name,
+        openReleases: (await releases.openReleases(site.id)).map(releaseSummary),
+        gatedNodes: await gatedNodeCount(local.sql, site.id, now),
+      });
+    return {
+      where: "local"         ,
+      engine: { schedulesLevel: SCHEDULES_ENGINE_LEVEL },
+      scheduler: await schedulerHealthReport(local.sql, { now, mode: "node" }),
+      sites,
+    };
+  });
+}
+
+const HEALTH_WORDS                                                 = {
+  running: "running",
+  late: "late (work is due and the last tick is over two minutes behind)",
+  stopped: "stopped (no tick for over ten minutes)",
+  unknown: "never ticked",
+};
+
+export function describeSchedulesStatus(s                       )           {
+  const h = s.scheduler;
+  const lines = [
+    `scheduler (${s.where}, ${h.mode}): ${HEALTH_WORDS[h.state]}${h.lastTickAt ? `; last tick ${h.lastTickAt}${h.lastTrigger ? ` (${h.lastTrigger})` : ""}` : ""}${h.nextWakeAt ? `; next by ${h.nextWakeAt}` : ""}`,
+    ...(h.nextDueAt ? [`next due: ${h.nextDueAt}`] : []),
+    `schedules level: ${s.engine.schedulesLevel}`,
+  ];
+  for (const site of s.sites) {
+    lines.push(
+      `${site.name ?? site.siteId} (${site.siteId}): ${site.openReleases.length} open release(s), ${site.gatedNodes} gated page(s)/entr(ies)`,
+    );
+    for (const r of site.openReleases) lines.push(`  ${describeRelease(r)}`);
+  }
+  return lines;
+}
+
+export function describeRelease(r                )         {
+  return `${r.id}  ${r.state.padEnd(17)} ${r.executeAt ?? "(no time)".padEnd(24)}  ${r.items} item(s)${r.title ? `  ${r.title}` : ""}`;
+}
+
+/** `cloudhal schedules list`: the site's releases, open first by time, then recent ones. */
+export async function schedulesList(
+  options                                          ,
+)                            {
+  const limit = options.limit ?? 50;
+  if (options.remote) {
+    const { body } = await remoteJson                                (
+      options,
+      `/api/admin/sites/:siteId/schedules/releases?limit=${limit}`,
+    );
+    return body.releases;
+  }
+  return withLocal(options.projectDir, async (local, siteId) =>
+    (await new ReleaseService({ graph: local.store }).list(siteId, { limit })).map(releaseSummary),
+  );
+}
+
+/** `cloudhal schedules run-due`: one tick now (`manual`), locally or on the deployment. */
+export async function schedulesRunDue(options                     )                      {
+  if (options.remote)
+    return (
+      await remoteJson            (options, "/api/admin/schedules/run-due", { method: "POST" })
+    ).body;
+  return withLocal(options.projectDir, (local) =>
+    runLocalTick({
+      sql: local.sql,
+      blobs: local.blobs,
+      graph: local.store,
+      trigger: "manual",
+      ...(options.now ? { now: options.now } : {}),
+      log: (l) => process.stderr.write(`${l}\n`),
+    }),
+  );
+}
+
+export function describeTick(r            )         {
+  return `tick: ${r.ran} ran, ${r.late} late, ${r.failed} failed${r.more ? ", more is due (run again)" : ""}${r.nextWakeAt ? `; next due ${r.nextWakeAt}` : ""}`;
+}

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

@@ -0,0 +1,14 @@
+import { type SyncOptions } from "./sync.js";
+export interface SearchCliOptions extends SyncOptions {
+    readonly remote?: boolean;
+}
+export interface ReindexReport {
+    readonly where: "local" | "remote";
+    readonly published: string | null;
+    readonly index: {
+        readonly snapshotId: string;
+        readonly entries: number;
+    } | null;
+}
+export declare function searchReindex(options: SearchCliOptions): Promise<ReindexReport>;
+export declare function describeReindex(r: ReindexReport): string;

package/dist/src/commands/search.js

@@ -0,0 +1,53 @@
+/**
+ * `cloudhal search reindex` (RFC-0019 §3): rebuilds the site's search index from its live snapshot,
+ * on the project's SQLite or with `--remote` on the deployment (deployment token). Publishing keeps
+ * the index current on its own; this is for restored backups (`wrangler d1 export` skips virtual
+ * tables) and for sites published before search existed.
+ */
+import path from "node:path";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+import { brief, deployment,                  } from "./sync.js";
+
+                                                       
+                            
+ 
+
+                                
+                                     
+                                    
+                                                                                   
+ 
+
+export async function searchReindex(options                  )                         {
+  if (options.remote) {
+    const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+    const res = await f(new URL(`/api/admin/sites/${cfg.siteId}/search/reindex`, adminUrl), {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const text = await res.text();
+    if (res.status === 404 && !text.includes("site not found"))
+      throw new Error(
+        "the deployment has no search yet (deploy this version with `cloudhal deploy` first)",
+      );
+    if (!res.ok) throw new Error(`the deployment answered ${res.status}: ${brief(text)}`);
+    return { where: "remote", ...(JSON.parse(text)                                ) };
+  }
+  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`);
+    await local.store.refreshSearch(cfg.siteId, { full: true });
+    const index = await local.store.searchStatus(cfg.siteId);
+    return { where: "local", published: site.publishedSnapshotId ?? null, index: index ?? null };
+  } finally {
+    await local.close();
+  }
+}
+
+export function describeReindex(r               )         {
+  if (!r.published) return `${r.where}: the site has not been published yet; nothing to index`;
+  return `${r.where}: indexed ${r.index?.entries ?? 0} item(s) from ${r.published}`;
+}

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

@@ -0,0 +1,46 @@
+import { type SyncOptions } from "./sync.js";
+export interface SiteCliOptions extends SyncOptions {
+    /** Talk to the deployment instead of the local SQLite. */
+    readonly remote?: boolean;
+}
+export interface SiteRow {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly projectId: string;
+    readonly defaultLocale: string;
+    readonly theme: string;
+    readonly hosts: readonly string[];
+    readonly conflicts: readonly string[];
+}
+/** What an edition copied and what it left out. */
+export interface EditionSummary {
+    readonly pages: number;
+    readonly menus: number;
+    readonly skipped: readonly {
+        readonly what: string;
+        readonly reason: string;
+    }[];
+}
+export interface CreateSiteInput {
+    readonly name: string;
+    readonly slug: string;
+    readonly locale?: string;
+    readonly projectId?: string;
+    readonly theme?: string;
+    /** RFC-0034 §6: start as a language edition of this site. */
+    readonly from?: string;
+}
+/** `cloudhal site list`. */
+export declare function listSites(options: SiteCliOptions): Promise<SiteRow[]>;
+/** `cloudhal site create`: a new site in this installation, seeded like `cloudhal init`. */
+export declare function createSite(options: SiteCliOptions, input: CreateSiteInput): Promise<{
+    id: string;
+    projectId: string;
+    edition?: EditionSummary;
+}>;
+/** `cloudhal site delete <siteId> --confirm <slug>`. */
+export declare function deleteSite(options: SiteCliOptions, siteId: string, confirm: string): Promise<{
+    rows: number;
+    objects: number;
+}>;