@cloudhal/cli 0.0.0-stage → 0.1.1

package/dist/src/commands/analytics.js

@@ -0,0 +1,347 @@
+/**
+ * `cloudhal analytics status|rollup|seed|export` (RFC-0006 §11) and the local analytics of
+ * `cloudhal studio` and `cloudhal mcp` (L3): raw events in the project's SQLite
+ * (`analytics_events`, written by `cloudhal dev` with `analytics.dev` and by Node self-hosts),
+ * read through `SqlAnalytics`, rolled up by the same `runRollups` as the admin Worker's cron.
+ * `--remote` talks to the deployment's admin Worker with the deployment token.
+ */
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import {                demoEvents, MAX_LIVE_DAYS } from "@cloudhal/analytics";
+import {
+  AnalyticsService,
+                       
+  rangeFromParams,
+} from "@cloudhal/analytics/service";
+import { SqlAnalytics } from "@cloudhal/analytics/sql";
+                                                        
+import {                  openLocalStore } from "@cloudhal/core-ts/local";
+                                                   
+import {
+                       
+  analyticsDefaultsOf,
+  analyticsEnabled,
+                     
+  readProjectConfig,
+} from "../config.js";
+import { brief, deployment,                  } from "./sync.js";
+
+/** Default days of raw events kept in SQLite (`analytics.rawRetentionDays`). */
+export const RAW_RETENTION_DAYS = 90;
+const DAY_MS = 86_400_000;
+
+/**
+ * The project's local analytics: SQLite as both store and reader. `enabled` follows cloudhal.json
+ * (Studio shows "not running" otherwise); `operator` forces the defaults on for CLI work on the
+ * local data (seed, rollup) whatever the deployment default says.
+ */
+export function localAnalytics(
+  sql           ,
+  cfg                                  ,
+  options                                           = {},
+)                   {
+  const defaults = analyticsDefaultsOf(cfg);
+  const on = analyticsEnabled(cfg);
+  return new AnalyticsService({
+    sql,
+    store: on || options.operator ? "sql" : "none",
+    live: new SqlAnalytics(sql),
+    defaults: {
+      enabled: options.operator ? true : defaults.enabled,
+      uniqueVisitors: defaults.uniqueVisitors,
+      vitalsOneIn: defaults.vitalsOneIn     ,
+    },
+    ...(options.now ? { now: options.now } : {}),
+    onError: (message, error) =>
+      process.stderr.write(`analytics: ${message}: ${(error         )?.message ?? error}\n`),
+  });
+}
+
+/**
+ * The local job (`cloudhal studio`, hourly): roll up finished days of every site, then prune raw
+ * events older than `rawRetentionDays`.
+ */
+export async function runLocalRollups(
+  service                  ,
+  store                ,
+  sql           ,
+  analytics                             ,
+  options                                            = {},
+) {
+  const siteIds = (await store.listSites()).map((s) => s.id);
+  const lookback = options.lookbackDays ?? 7;
+  const report = await service.rollup({
+    siteIds,
+    lookbackDays: lookback,
+    maxSiteDays: lookback * Math.max(1, siteIds.length),
+    ...(options.redo ? { redo: true } : {}),
+  });
+  const days = analytics?.rawRetentionDays ?? RAW_RETENTION_DAYS;
+  const pruned = await new SqlAnalytics(sql).prune(
+    new Date(service.now().getTime() - days * DAY_MS),
+  );
+  return { ...report, pruned };
+}
+
+/** Starts the hourly local job; returns a stop function. Errors are logged, never thrown. */
+export function startLocalRollups(
+  service                  ,
+  local            ,
+  analytics                             ,
+  log                         = (l) => process.stderr.write(`${l}\n`),
+)             {
+  const tick = () => {
+    runLocalRollups(service, local.store, local.sql, analytics).catch((e) =>
+      log(`analytics rollup failed: ${e instanceof Error ? e.message : String(e)}`),
+    );
+  };
+  tick();
+  const timer = setInterval(tick, 3_600_000);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+                                                          
+                                                                               
+                            
+ 
+
+async function withLocal   (
+  projectDir        ,
+  fn                                                                                         ,
+  now             ,
+)             {
+  const cfg = await readProjectConfig(projectDir);
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  try {
+    return await fn({
+      cfg,
+      local,
+      service: localAnalytics(local.sql, cfg, { operator: true, ...(now ? { now } : {}) }),
+    });
+  } finally {
+    await local.close();
+  }
+}
+
+async function remoteJson   (
+  options             ,
+  pathname        ,
+  init              ,
+)             {
+  const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+  const url = new URL(pathname.replace(":siteId", cfg.siteId), adminUrl);
+  const res = await f(url, {
+    ...init,
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+  });
+  const body = await res.text();
+  if (!res.ok) throw new Error(`${url.pathname} failed (${res.status}): ${brief(body)}`);
+  return (res.headers.get("content-type")?.startsWith("text/csv") ? body : JSON.parse(body))     ;
+}
+
+                                                      
+                                           
+                           
+ 
+
+/** `cloudhal analytics status [--remote]`. */
+export async function analyticsStatus(options                     )                       {
+  if (options.remote)
+    return remoteJson             (options, "/api/admin/sites/:siteId/analytics/status");
+  return withLocal(options.projectDir, async ({ cfg, local }) => {
+    // the deployment's view, not the operator's: enabled follows cloudhal.json
+    const status = await localAnalytics(local.sql, cfg).status(cfg.siteId);
+    const row = await local.sql.get               (
+      "SELECT COUNT(*) AS n FROM analytics_events WHERE site_id = ?",
+      [cfg.siteId],
+    );
+    return { ...status, events: Number(row?.n ?? 0) };
+  });
+}
+
+export function describeStatus(s             )           {
+  const f = s.feature;
+  return [
+    `analytics: ${f.enabled ? "on" : "off"} for this deployment (store ${f.store}, reader ${f.reader}${f.rollups === "on-read" ? ", daily totals on read" : ""})`,
+    `site ${s.siteId}: ${s.settings.enabled ? "on" : "off"}${s.settings.stored ? "" : " (deployment default)"} · unique visitors ${s.settings.uniqueVisitors ? "on" : "off"} · vitals ${s.settings.vitalsOneIn ? `1 in ${s.settings.vitalsOneIn}` : "off"}`,
+    `daily totals through: ${s.lastRollup ? s.lastRollup.day : "none yet"}`,
+    ...(s.budget ? [`live queries today: ${s.budget.used} of ${s.budget.limit}`] : []),
+    ...(s.quota
+      ? [
+          `yesterday (${s.quota.day}): ${s.quota.pageviews} page views, about ${s.quota.requests} requests`,
+        ]
+      : []),
+    ...(s.events !== undefined ? [`raw events in SQLite: ${s.events}`] : []),
+  ];
+}
+
+                                                               
+                                                                              
+                         
+                                                              
+                          
+ 
+
+                                  
+                        
+                                                             
+                           
+                          
+                           
+ 
+
+/** `cloudhal analytics rollup [--days n] [--remote]`: backfill daily totals. */
+export async function analyticsRollup(options                  )                           {
+  const days = options.days ?? 7;
+  if (!Number.isInteger(days) || days < 1 || days > MAX_LIVE_DAYS)
+    throw new Error(`--days must be a whole number from 1 to ${MAX_LIVE_DAYS}`);
+  if (options.remote) {
+    if (options.redo) throw new Error("--redo works on the local data only");
+    // A few site-days per request (Worker limits); repeat while days are pending.
+    let done = 0;
+    let calls = 0;
+    const failed                                   = [];
+    let pending = 1;
+    while (pending > 0 && calls < days + 5) {
+      const r = await remoteJson  
+                                
+                                                 
+                        
+                       
+        (options, "/api/admin/sites/:siteId/analytics/rollup", {
+        method: "POST",
+        body: JSON.stringify({ days, maxSiteDays: 3 }),
+      });
+      calls++;
+      if (r.reader === "none")
+        throw new Error(
+          "the deployment records analytics but cannot read them (no Analytics SQL binding on this account yet); nothing to roll up",
+        );
+      done += r.done.length;
+      failed.push(...r.failed);
+      // failed days stay pending; stop rather than retry them forever
+      pending = r.failed.length > 0 && r.done.length === 0 ? 0 : r.pending;
+      options.log?.(`rolled up ${done} day(s), ${r.pending} pending`);
+    }
+    return { done, failed, pending, calls };
+  }
+  return withLocal(options.projectDir, async ({ cfg, local, service }) => {
+    const r = await runLocalRollups(service, local.store, local.sql, cfg.analytics, {
+      lookbackDays: days,
+      ...(options.redo ? { redo: true } : {}),
+    });
+    return { done: r.done.length, failed: r.failed, pending: r.pending, pruned: r.pruned };
+  });
+}
+
+                                 
+                              
+                                                        
+                         
+                                                  
+                          
+                            
+                                        
+ 
+
+/** The site's published pages, articles and public archives, most important first. */
+async function publishedNodes(store                , siteId        )                      {
+  const [pages, entries, terms, taxonomies] = await Promise.all([
+    store.listPages(siteId),
+    store.listContentEntries(siteId, { status: ["published"] }),
+    store.listTerms(siteId),
+    store.listTaxonomies(siteId),
+  ]);
+  const tax = new Map(taxonomies.map((t) => [t.id, t]));
+  const home = pages.filter((p) => p.status === "published" && p.path === "/");
+  return [
+    ...home.map((p) => ({
+      nodeId: p.id,
+      nodeKind: "page"         ,
+      path: p.path,
+      locale: p.locale,
+    })),
+    ...entries.map((e) => ({
+      nodeId: e.id,
+      nodeKind: "entry"         ,
+      path: `/${e.collection}/${e.slug}`,
+      locale: e.locale,
+    })),
+    ...pages
+      .filter((p) => p.status === "published" && p.path !== "/")
+      .map((p) => ({ nodeId: p.id, nodeKind: "page"         , path: p.path, locale: p.locale })),
+    ...terms.flatMap((t) => {
+      const x = tax.get(t.taxonomyId);
+      return x?.archive.enabled && t.status === "active" && t.visibility === "public"
+        ? [{ nodeId: t.id, nodeKind: "archive"         , path: `${x.archive.basePath}/${t.slug}` }]
+        : [];
+    }),
+  ];
+}
+
+/** `cloudhal analytics seed [--days 30]`: realistic demo data in the local SQLite only. */
+export async function analyticsSeed(
+  options                ,
+)                                                               {
+  const days = options.days ?? 30;
+  if (!Number.isInteger(days) || days < 1 || days > 365)
+    throw new Error("--days must be a whole number from 1 to 365");
+  return withLocal(
+    options.projectDir,
+    async ({ cfg, local, service }) => {
+      const nodes = await publishedNodes(local.store, cfg.siteId);
+      if (nodes.length === 0)
+        throw new Error(
+          "nothing is published yet: publish the site (cloudhal snapshot --publish) first",
+        );
+      const settings = await service.settings(cfg.siteId);
+      const events = demoEvents({
+        siteId: cfg.siteId,
+        nodes,
+        days,
+        now: service.now(),
+        ...(options.views !== undefined ? { viewsPerDay: options.views } : {}),
+        vitalsOneIn: settings.vitalsOneIn || 5,
+        uniqueVisitors: settings.uniqueVisitors,
+      });
+      await new SqlAnalytics(local.sql).insertMany(events);
+      const r = await runLocalRollups(service, local.store, local.sql, cfg.analytics, {
+        lookbackDays: Math.min(days, MAX_LIVE_DAYS),
+        redo: true,
+      });
+      options.log?.(
+        `seeded ${events.length} demo events over ${days} day(s) on ${nodes.length} node(s); ${r.done.length} day(s) rolled up`,
+      );
+      if (!analyticsEnabled(cfg))
+        options.log?.(
+          'analytics are off in cloudhal.json; set "analytics": { "enabled": true } to see them in cloudhal studio',
+        );
+      return { events: events.length, nodes: nodes.length, rolledUp: r.done.length };
+    },
+    options.now,
+  );
+}
+
+                                                               
+                         
+                       
+                                                         
+                        
+ 
+
+/** `cloudhal analytics export --from --to [--remote] [--out file]`: daily totals as CSV. */
+export async function analyticsExport(options                  )                  {
+  const params = { from: options.from, to: options.to };
+  const range = rangeFromParams(params);
+  const csv = options.remote
+    ? await remoteJson        (
+        options,
+        `/api/admin/sites/:siteId/analytics/export?from=${encodeURIComponent(range.from)}&to=${encodeURIComponent(range.to)}`,
+      )
+    : await withLocal(options.projectDir, ({ cfg, service }) =>
+        service.exportCsv(cfg.siteId, range),
+      );
+  if (options.out) await writeFile(path.resolve(options.projectDir, options.out), csv);
+  return csv;
+}

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

@@ -0,0 +1,22 @@
+export interface DevOptions {
+    readonly projectDir: string;
+    readonly port?: number;
+    readonly host?: boolean;
+    /** `false` skips the scheduler's Node ticker (RFC-0008 §8.4). */
+    readonly scheduler?: boolean;
+}
+/** Starts the Astro dev server for the project (live source, drafts visible). Returns a stop function. */
+export declare function dev(options: DevOptions): Promise<{
+    stop(): Promise<void>;
+    url: string | undefined;
+}>;
+export interface BuildOptions {
+    readonly projectDir: string;
+    /** Render this snapshot instead of the published/latest one. */
+    readonly snapshotId?: string;
+}
+/** Static build from a snapshot: published → latest → freshly created. */
+export declare function build(options: BuildOptions): Promise<{
+    snapshotId: string;
+    outDir: string;
+}>;

package/dist/src/commands/astro.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { readProjectConfig } from "../config.js";
+import { startLocalScheduler } from "./scheduler-local.js";
+import { resolveBuildSnapshot } from "./snapshot.js";
+
+                             
+                              
+                         
+                          
+                                                                   
+                               
+ 
+
+/** Starts the Astro dev server for the project (live source, drafts visible). Returns a stop function. */
+export async function dev(
+  options            ,
+)                                                              {
+  const cfg = await readProjectConfig(options.projectDir); // fail early with a clear message
+  process.env.CLOUDHAL_SOURCE = "live";
+  // Note: Astro skips its dev middleware entirely when `process.env.VITEST` is set, so a dev
+  // server cannot be started inside a Vitest worker; tests spawn the CLI as a child process.
+  const astro = await import("astro");
+  const server = await astro.dev({
+    root: path.resolve(options.projectDir),
+    mode: "development",
+    logLevel: "info",
+    server: {
+      ...(options.port !== undefined ? { port: options.port } : {}),
+      ...(options.host ? { host: true } : {}),
+    },
+  });
+  const addr = server.address;
+  const host = !addr
+    ? undefined
+    : addr.family === "IPv6"
+      ? addr.address === "::" || addr.address === "::1"
+        ? "localhost"
+        : `[${addr.address}]`
+      : addr.address;
+  const url = addr && host ? `http://${host}:${addr.port}/` : undefined;
+  // RFC-0008 §8.4: releases publish on time while the preview runs (its own connection to the
+  // project's SQLite; leases keep it safe beside Studio's and the MCP server's tickers).
+  const local =
+    options.scheduler === false
+      ? undefined
+      : await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  const ticker = local
+    ? startLocalScheduler({
+        sql: local.sql,
+        blobs: local.blobs,
+        graph: local.store,
+        // RFC-0008 §11.1: the feed check reads this dev server's feed and sitemap
+        ...(url ? { siteOrigin: url, siteId: cfg.siteId } : {}),
+      })
+    : undefined;
+  return {
+    stop: async () => {
+      ticker?.stop();
+      await server.stop();
+      await local?.close();
+    },
+    url,
+  };
+}
+
+                               
+                              
+                                                                  
+                               
+ 
+
+/** Static build from a snapshot: published → latest → freshly created. */
+export async function build(
+  options              ,
+)                                                  {
+  const snapshotId = options.snapshotId ?? (await resolveBuildSnapshot(options.projectDir)).id;
+  process.env.CLOUDHAL_SOURCE = `snapshot:${snapshotId}`;
+  const cfg = await readProjectConfig(options.projectDir);
+  const astro = await import("astro");
+  const root = path.resolve(options.projectDir);
+  // A static build has no request: without `site`, Astro's URLs (canonical links, the sitemap,
+  // feeds) say localhost. The site's own primary domain still wins (`siteOrigin`).
+  const site = cfg.domains?.site ? `https://${cfg.domains.site}` : undefined;
+  await astro.build({ root, logLevel: "info", ...(site ? { site } : {}) });
+  return { snapshotId, outDir: path.join(root, "dist") };
+}

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

@@ -0,0 +1,22 @@
+import { type ChromeFooter, type ChromeHeader } from "@cloudhal/core-ts/chrome";
+export interface ChromeOptions {
+    readonly projectDir: string;
+    /** `get`: a file to write (stdout otherwise); `set`: the file to read. */
+    readonly file?: string;
+}
+/** The chrome file: the site's header, footer and brand (logos as `asset:<id>`). */
+export interface ChromeFile {
+    header: ChromeHeader | Record<string, never>;
+    footer: ChromeFooter | Record<string, never>;
+    brand: Record<string, unknown>;
+}
+/**
+ * `cloudhal chrome get` (RFC-0025 §5): the site's header, footer and brand as JSON, the file
+ * `cloudhal chrome set` reads. Returns the JSON written.
+ */
+export declare function chromeGet(options: ChromeOptions): Promise<string>;
+/**
+ * `cloudhal chrome set --file <chrome.json>`: replaces the parts the file has (an empty part goes
+ * back to the default), with the checks Studio and agents get, and snapshots the site.
+ */
+export declare function chromeSet(options: ChromeOptions): Promise<ChromeFile>;

package/dist/src/commands/chrome.js

@@ -0,0 +1,90 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  applyChromeForm,
+  brandToForm,
+                    
+                    
+  chromeMenuKeys,
+  logoAsset,
+} from "@cloudhal/core-ts/chrome";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { loadThemeSettings } from "../blocks.js";
+import { readProjectConfig } from "../config.js";
+
+                                
+                              
+                                                                            
+                         
+ 
+
+/** The chrome file: the site's header, footer and brand (logos as `asset:<id>`). */
+                             
+                                               
+                                               
+                                 
+ 
+
+async function withSite   (
+  projectDir        ,
+  run                                                                                   ,
+)             {
+  const cfg = await readProjectConfig(projectDir);
+  const themeSettings = await loadThemeSettings(projectDir);
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir), { themeSettings });
+  try {
+    return await run(local, cfg.siteId);
+  } finally {
+    await local.close();
+  }
+}
+
+/**
+ * `cloudhal chrome get` (RFC-0025 §5): the site's header, footer and brand as JSON, the file
+ * `cloudhal chrome set` reads. Returns the JSON written.
+ */
+export async function chromeGet(options               )                  {
+  return withSite(options.projectDir, async ({ store }, siteId) => {
+    const site = await store.getSite(siteId);
+    if (!site) throw new Error(`site ${siteId} not found`);
+    const file             = {
+      header: site.chrome?.header ?? {},
+      footer: site.chrome?.footer ?? {},
+      brand: brandToForm(site.brand),
+    };
+    const json = `${JSON.stringify(file, null, 2)}\n`;
+    if (options.file) await writeFile(path.resolve(options.projectDir, options.file), json);
+    return json;
+  });
+}
+
+/**
+ * `cloudhal chrome set --file <chrome.json>`: replaces the parts the file has (an empty part goes
+ * back to the default), with the checks Studio and agents get, and snapshots the site.
+ */
+export async function chromeSet(options               )                      {
+  if (!options.file) throw new Error("usage: cloudhal chrome set --file <chrome.json>");
+  const input = JSON.parse(
+    await readFile(path.resolve(options.projectDir, options.file), "utf8"),
+  )                           ;
+  return withSite(options.projectDir, async ({ store }, siteId) => {
+    const site = await store.getSite(siteId);
+    if (!site) throw new Error(`site ${siteId} not found`);
+    const { site: next, issues } = await applyChromeForm(site, input, {
+      menus: chromeMenuKeys(await store.listMenus(site.id)),
+      resolve: async (assetId) => logoAsset(await store.getAsset(assetId), site),
+    });
+    if (issues.length > 0) throw new Error(issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
+    const saved = await store.updateSite(next);
+    await store.createSnapshot(siteId, {
+      actor: { kind: "human", id: "user_localcli0001", name: "cloudhal CLI" },
+      reason: "manual",
+      label: "cloudhal chrome set",
+    });
+    return {
+      header: saved.chrome?.header ?? {},
+      footer: saved.chrome?.footer ?? {},
+      brand: brandToForm(saved.brand),
+    };
+  });
+}

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

@@ -0,0 +1,40 @@
+import { type CommentKeys } from "@cloudhal/comments";
+import { SqlCommentStore } from "@cloudhal/comments/sql";
+import type { SiteGraphStore } from "@cloudhal/core-ts";
+import type { SqlDriver } from "@cloudhal/storage";
+/** The data directory's key file (`cloudhal dev` creates the same one). */
+export declare const LOCAL_KEY_FILE = "comments.key";
+/**
+ * The project's comments keys: `CLOUDHAL_COMMENTS_KEY`, else `<dataDir>/comments.key`; with
+ * `create`, a missing file is created (256 random bits, owner-only), as `cloudhal dev` does.
+ */
+export declare function localCommentsKeys(dataDir: string, o?: {
+    create?: boolean;
+    env?: Record<string, string | undefined>;
+}): Promise<CommentKeys | undefined>;
+export declare function localComments(sql: SqlDriver, dataDir: string, env?: Record<string, string | undefined>): Promise<{
+    store: SqlCommentStore;
+    keys?: CommentKeys;
+    onQueued: (siteId: string) => void;
+}>;
+/** Empties a site's (or every site's) comment purge queue: locally there is nothing to purge. */
+export declare function drainPurgeQueue(store: SqlCommentStore, siteId?: string): Promise<number>;
+/** One run of the local hourly job; returns what it did (for logs and tests). */
+export declare function runLocalCommentsJob(graph: SiteGraphStore, store: SqlCommentStore, now?: Date): Promise<{
+    sites: number;
+    retained: number;
+    deletedEntries: number;
+    closed: number;
+    salts: number;
+    purgeLog: number;
+    more: boolean;
+    drained: number;
+}>;
+/**
+ * Starts the hourly comments job on its own timer: once now, then every hour; errors are logged,
+ * never thrown. Returns a stop function.
+ *
+ * @deprecated `cloudhal studio`, `mcp` and `dev` run the job as the `comments.hourly` system job
+ * of the scheduler's Node ticker (RFC-0008 §8.4, `scheduler-local.ts`).
+ */
+export declare function startLocalCommentsJob(graph: SiteGraphStore, store: SqlCommentStore, log?: (line: string) => void, intervalMs?: number): () => void;