@cloudhal/cli 0.0.0-stage → 0.1.0

package/dist/src/cloudflare/wrangler.js

@@ -0,0 +1,133 @@
+/**
+ * Thin wrapper around the `wrangler` CLI (there is no supported JS deploy API). Credentials are
+ * wrangler's own — `wrangler login` or `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` in the
+ * environment; Cloudhal never reads or stores them.
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+
+                                 
+               
+                 
+                 
+                                                                    
+                                     
+ 
+
+                              
+                 
+                                            
+                             
+
+export function resolveWranglerBin(projectDir        )         {
+  const require = createRequire(path.join(projectDir, "package.json"));
+  return path.join(path.dirname(require.resolve("wrangler/package.json")), "bin/wrangler.js");
+}
+
+/** The version of the project's installed wrangler (`package.json`), or undefined. */
+export async function installedWranglerVersion(projectDir        )                              {
+  try {
+    const require = createRequire(path.join(projectDir, "package.json"));
+    const pkg = JSON.parse(await readFile(require.resolve("wrangler/package.json"), "utf8"))     
+                        
+     ;
+    return typeof pkg.version === "string" ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `a >= b` for `major.minor.patch` versions (pre-release suffixes ignored). */
+export function versionAtLeast(a        , b        )          {
+  const parse = (v        ) =>
+    v
+      .split(/[.+-]/)
+      .slice(0, 3)
+      .map((x) => Number.parseInt(x, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
+  }
+  return true;
+}
+
+/** Wrangler accepts the `analytics` (Analytics SQL) config key from this version (RFC-0006 §11). */
+export const WRANGLER_FOR_ANALYTICS = "4.145.0";
+
+/** Whether a failed deploy was refused for the account's cron-trigger limit (Free: 5). */
+export function isCronLimitError(output        )          {
+  return /cron/i.test(output) && /(limit|exceed|maximum|too many|quota)/i.test(output);
+}
+
+export function wranglerRunner(
+  projectDir        ,
+  log                         = () => {},
+)                 {
+  const bin = resolveWranglerBin(projectDir);
+  return async (args, { cwd, quiet }) => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "cloudhal-wrangler-"));
+    const outputFile = path.join(dir, "output.ndjson");
+    const { VITEST: _v, NODE_ENV: _n, ...env } = process.env;
+    try {
+      const result = await new Promise                                                  (
+        (resolve) => {
+          const child = spawn(process.execPath, [bin, ...args], {
+            cwd,
+            env: { ...env, WRANGLER_OUTPUT_FILE_PATH: outputFile, WRANGLER_SEND_METRICS: "false" },
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          let stdout = "";
+          let stderr = "";
+          child.stdout.on("data", (c        ) => {
+            stdout += c.toString();
+            if (!quiet) for (const l of c.toString().split("\n")) if (l.trim()) log(`  ${l}`);
+          });
+          child.stderr.on("data", (c        ) => {
+            stderr += c.toString();
+          });
+          child.once("exit", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+        },
+      );
+      let records                            = [];
+      try {
+        records = (await readFile(outputFile, "utf8"))
+          .split("\n")
+          .filter(Boolean)
+          .map((l) => JSON.parse(l)                           );
+      } catch {
+        // no structured output
+      }
+      return { ...result, records };
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+export class WranglerError extends Error {
+                    name = "WranglerError";
+}
+
+export async function must(
+  run                ,
+  args          ,
+  cwd        ,
+)                          {
+  const r = await run(args, { cwd });
+  if (r.code !== 0)
+    throw new WranglerError(
+      `wrangler ${args.join(" ")} failed:\n${(r.stderr || r.stdout).slice(-3000)}`,
+    );
+  return r;
+}
+
+/** URLs of a deployed Worker from wrangler's structured output. */
+export function deployedUrls(records                           )           {
+  return records
+    .filter((r) => r.type === "deploy")
+    .flatMap((r) => (Array.isArray(r.targets) ? (r.targets            ) : []))
+    .map((t) => (t.startsWith("http") ? t : `https://${t}`));
+}

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

@@ -0,0 +1,39 @@
+import { type BuildEvalRun, type BuildEvalSummary, type JudgeCheckRow } from "@cloudhal/api";
+import { type SyncOptions } from "./sync.js";
+export interface BuildEvalOptions extends SyncOptions {
+    readonly remote?: boolean;
+    readonly models?: readonly string[];
+    readonly briefs?: readonly string[];
+    /** RFC-0021 21c: render each result (checks, the judge's score; `look`: the model sees it first). */
+    readonly design?: {
+        readonly judge?: string | false;
+        readonly look?: boolean;
+    } | undefined;
+    /** Each run as it finishes. */
+    readonly onRun?: (run: BuildEvalRun) => void;
+    readonly env?: Record<string, string | undefined>;
+}
+export interface BuildEvalReport {
+    readonly where: "local" | "remote";
+    readonly runs: BuildEvalRun[];
+    readonly summary: BuildEvalSummary[];
+    readonly table: string;
+}
+export declare function buildEval(options: BuildEvalOptions): Promise<BuildEvalReport>;
+export declare function describeRun(r: BuildEvalRun): string;
+export interface JudgeCheckOptions extends SyncOptions {
+    readonly remote?: boolean;
+    /** The judge model (default Llama 4 Scout). */
+    readonly judge?: string | undefined;
+    readonly onRow?: (row: JudgeCheckRow) => void;
+    readonly env?: Record<string, string | undefined>;
+}
+/**
+ * `cloudhal ai judge-check` (RFC-0021 21c): the judge scores the reference pages (empty, bare,
+ * plain, strong); it is worth using when it ranks them in that order.
+ */
+export declare function judgeCheckCommand(options: JudgeCheckOptions): Promise<{
+    ordered: boolean;
+    table: string;
+}>;
+export declare function describeJudgeRow(r: JudgeCheckRow): string;

package/dist/src/commands/ai.js

@@ -0,0 +1,264 @@
+/**
+ * `cloudhal ai build-eval` (RFC-0020 open question 7): the Build model eval. The same briefs go
+ * through Build chat's turn on each model, in memory (nothing is stored), and the summary ranks
+ * the models by finished turns, accepted steps and speed. Locally it reaches Workers AI over REST
+ * (`CLOUDFLARE_ACCOUNT_ID`, `CLOUDHAL_AI_TOKEN`); with `--remote` it runs on the deployment's AI
+ * binding (deployment token). Every run is a real model call on the account.
+ */
+import path from "node:path";
+import {
+  ALL_EVAL_BRIEFS,
+  BUILD_EVAL_BRIEFS,
+  BUILD_EVAL_MODELS,
+                    
+                        
+  buildEvalTable,
+                     
+  judgeCheck,
+  judgeCheckTable,
+  runBuildEvalOnce,
+  summariseBuildEval,
+} from "@cloudhal/api";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { createCatalog } from "@cloudhal/core-ts/surfaces";
+import { readProjectConfig } from "../config.js";
+import { localRender } from "../render-chrome.js";
+import { localAiTransport } from "./studio.js";
+import { brief as briefText, deployment,                  } from "./sync.js";
+
+                                                       
+                            
+                                      
+                                      
+                                                                                                       
+                                                                                             
+                                 
+                                               
+                                                    
+ 
+
+                                  
+                                     
+                                
+                                       
+                         
+ 
+
+export async function buildEval(options                  )                           {
+  const models = options.models?.length ? options.models : BUILD_EVAL_MODELS;
+  // RFC-0022 §6: `--briefs` may name tool briefs too (calories, loan, chart, compare).
+  const briefs = options.briefs?.length
+    ? ALL_EVAL_BRIEFS.filter((b) => options.briefs?.includes(b.id))
+    : [...BUILD_EVAL_BRIEFS];
+  if (briefs.length === 0)
+    throw new Error(`--briefs: choose from ${ALL_EVAL_BRIEFS.map((b) => b.id).join(", ")}`);
+  if (options.remote) {
+    const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+    const runs                 = [];
+    // One request per run: a dropped connection loses that run only, and it is recorded as one.
+    for (const model of models)
+      for (const brief of briefs) {
+        const one = await remoteRuns(
+          f,
+          new URL(`/api/admin/sites/${cfg.siteId}/ai/build-eval`, adminUrl),
+          token,
+          model,
+          brief.id,
+          options.design,
+        ).catch((e         )                 => [
+          {
+            model,
+            brief: brief.id,
+            finished: false,
+            steps: 0,
+            refused: 0,
+            samples: [],
+            repairs: 0,
+            rounds: 0,
+            components: 0,
+            totalMs: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            error: e instanceof Error ? e.message.slice(0, 200) : "failed",
+          },
+        ]);
+        for (const run of one) {
+          runs.push(run);
+          options.onRun?.(run);
+        }
+      }
+    const summary = summariseBuildEval(runs);
+    return { where: "remote", runs, summary, table: buildEvalTable(summary) };
+  }
+  const { transport } = localAiTransport(options.env ?? process.env);
+  if (!transport)
+    throw new Error(
+      "set CLOUDFLARE_ACCOUNT_ID and CLOUDHAL_AI_TOKEN to reach Workers AI, or use --remote",
+    );
+  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 catalog = createCatalog({ name: site.theme.name, blocks: local.store.blocks });
+    // RFC-0021 21c: the local Chrome renders each result.
+    const render = options.design ? localRender(options.env ?? process.env) : undefined;
+    if (options.design && !render)
+      throw new Error("--design needs a local Chrome (set CHROME_PATH), or use --remote");
+    const design =
+      options.design && render
+        ? { ...options.design, renderer: render.renderer, site, blocks: local.store.blocks }
+        : undefined;
+    const runs                 = [];
+    for (const model of models)
+      for (const brief of briefs) {
+        const run = await runBuildEvalOnce({
+          transport,
+          model,
+          brief,
+          catalog,
+          siteId: site.id,
+          ...(design ? { design } : {}),
+        });
+        runs.push(run);
+        options.onRun?.(run);
+      }
+    const summary = summariseBuildEval(runs);
+    return { where: "local", runs, summary, table: buildEvalTable(summary) };
+  } finally {
+    await local.close();
+  }
+}
+
+/** One remote run (NDJSON: start, progress lines, the run, then a summary of one). */
+async function remoteRuns(
+  f              ,
+  url     ,
+  token        ,
+  model        ,
+  brief        ,
+  design                             ,
+)                          {
+  const res = await f(url, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify({ models: [model], briefs: [brief], ...(design ? { design } : {}) }),
+  });
+  if (!res.ok || !res.body) {
+    const text = await res.text();
+    if (res.status === 404 && !text.includes("site not found"))
+      throw new Error("the deployment has no build eval yet (deploy this version first)");
+    throw new Error(`the deployment answered ${res.status}: ${briefText(text)}`);
+  }
+  const runs                 = [];
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+    let nl = buffer.indexOf("\n");
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line) {
+        const msg = JSON.parse(line)                                        ;
+        if (msg.type === "run" && msg.run) runs.push(msg.run);
+      }
+      nl = buffer.indexOf("\n");
+    }
+    if (done) break;
+  }
+  if (runs.length === 0) throw new Error("the deployment ended the stream before the run");
+  return runs;
+}
+
+/** What the model saw when it looked, and what it did. */
+function lookText(l                                                          )         {
+  const saw = `looked (${l.images ? `${l.images} screenshots` : "checks only"}${l.failed.length ? `, failed ${l.failed.join(", ")}` : ", nothing failed"})`;
+  if (!l.round) return `${saw}, no extra round`;
+  return `${saw}, ${l.steps ? `fixed with ${l.steps} step(s)` : "kept the page"}`;
+}
+
+export function describeRun(r              )         {
+  const time = `${(r.totalMs / 1000).toFixed(1)} s`;
+  const d = r.design;
+  const design = d
+    ? `\n    design: ${d.score !== undefined ? `score ${d.score}` : "no score"}, ${d.failed.length ? `failed ${d.failed.join(", ")}` : "all checks passed"}${d.look ? `, ${lookText(d.look)}` : ""}${d.tool ? `, tool: ${d.tool.results - d.tool.empty}/${d.tool.results} results show with ${d.tool.inputs} sample inputs` : ""}${d.note ? ` — ${d.note}` : ""}${d.error ? ` (${d.error})` : ""}`
+    : "";
+  return `${r.model} · ${r.brief}: ${r.finished ? "finished" : "not finished"}, ${r.steps} step(s), ${r.refused} refused, ${r.repairs} repair(s), ${r.rounds} round(s), ${time}${r.error ? ` (${r.error})` : ""}${r.used?.length ? `\n    used: ${r.used.join(", ")}` : ""}${r.samples?.[0] ? `\n    e.g. ${r.samples[0]}` : ""}${design}`;
+}
+
+                                                        
+                            
+                                                 
+                                      
+                                                
+                                                    
+ 
+
+/**
+ * `cloudhal ai judge-check` (RFC-0021 21c): the judge scores the reference pages (empty, bare,
+ * plain, strong); it is worth using when it ranks them in that order.
+ */
+export async function judgeCheckCommand(
+  options                   ,
+)                                               {
+  if (options.remote) {
+    const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+    const res = await f(new URL(`/api/admin/sites/${cfg.siteId}/ai/judge-check`, adminUrl), {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(options.judge ? { judge: options.judge } : {}),
+    });
+    if (!res.ok || !res.body) {
+      const text = await res.text();
+      if (res.status === 404 && !text.includes("site not found"))
+        throw new Error("the deployment has no judge check yet (deploy this version first)");
+      throw new Error(`the deployment answered ${res.status}: ${briefText(text)}`);
+    }
+    let result                                                 ;
+    for (const line of (await res.text()).split("\n")) {
+      if (!line.trim()) continue;
+      const msg = JSON.parse(line)     
+                     
+                            
+                          
+                       
+       ;
+      if (msg.type === "row" && msg.row) options.onRow?.(msg.row);
+      if (msg.type === "result") result = { ordered: Boolean(msg.ordered), table: msg.table ?? "" };
+    }
+    if (!result) throw new Error("the deployment ended the stream before the result");
+    return result;
+  }
+  const env = options.env ?? process.env;
+  const { transport } = localAiTransport(env);
+  if (!transport)
+    throw new Error(
+      "set CLOUDFLARE_ACCOUNT_ID and CLOUDHAL_AI_TOKEN to reach Workers AI, or use --remote",
+    );
+  const render = localRender(env);
+  if (!render)
+    throw new Error("the judge check needs a local Chrome (set CHROME_PATH), or use --remote");
+  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 r = await judgeCheck({
+      transport,
+      renderer: render.renderer,
+      site,
+      judge: options.judge,
+      onRow: options.onRow,
+    });
+    return { ordered: r.ordered, table: judgeCheckTable(r.rows) };
+  } finally {
+    await local.close();
+  }
+}
+
+export function describeJudgeRow(r               )         {
+  return `${r.id}: ${r.score ?? "no score"} (expected ${r.expected[0]}–${r.expected[1]}${r.inRange ? "" : ", out of range"})${r.error ? ` — ${r.error}` : ""}${r.problems?.length ? `\n    ${r.problems.join("\n    ")}` : ""}`;
+}

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

@@ -0,0 +1,94 @@
+import { AnalyticsService, type AnalyticsStatus } from "@cloudhal/analytics/service";
+import type { SiteGraphStore } from "@cloudhal/core-ts";
+import { type LocalStore } from "@cloudhal/core-ts/local";
+import type { SqlDriver } from "@cloudhal/storage";
+import { type AnalyticsConfig, type ProjectConfig } from "../config.js";
+import { type SyncOptions } from "./sync.js";
+/** Default days of raw events kept in SQLite (`analytics.rawRetentionDays`). */
+export declare const RAW_RETENTION_DAYS = 90;
+/**
+ * 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 declare function localAnalytics(sql: SqlDriver, cfg: Pick<ProjectConfig, "analytics">, options?: {
+    operator?: boolean;
+    now?: () => Date;
+}): AnalyticsService;
+/**
+ * The local job (`cloudhal studio`, hourly): roll up finished days of every site, then prune raw
+ * events older than `rawRetentionDays`.
+ */
+export declare function runLocalRollups(service: AnalyticsService, store: SiteGraphStore, sql: SqlDriver, analytics: AnalyticsConfig | undefined, options?: {
+    lookbackDays?: number;
+    redo?: boolean;
+}): Promise<{
+    saltsDeleted: number;
+    done: readonly {
+        siteId: string;
+        day: string;
+        rows: number;
+    }[];
+    failed: readonly {
+        siteId: string;
+        day: string;
+        error: string;
+    }[];
+    pending: number;
+    retained: number;
+    pruned: number;
+}>;
+/** Starts the hourly local job; returns a stop function. Errors are logged, never thrown. */
+export declare function startLocalRollups(service: AnalyticsService, local: LocalStore, analytics: AnalyticsConfig | undefined, log?: (line: string) => void): () => void;
+export interface AnalyticsCliOptions extends SyncOptions {
+    /** Talk to the deployment (deployment token) instead of the local SQLite. */
+    readonly remote?: boolean;
+}
+export interface LocalStatus extends AnalyticsStatus {
+    /** Raw events in SQLite (local only). */
+    readonly events?: number;
+}
+/** `cloudhal analytics status [--remote]`. */
+export declare function analyticsStatus(options: AnalyticsCliOptions): Promise<LocalStatus>;
+export declare function describeStatus(s: LocalStatus): string[];
+export interface RollupCliOptions extends AnalyticsCliOptions {
+    /** Days back from yesterday (default 7; at most 92, WAE keeps 3 months). */
+    readonly days?: number;
+    /** Local only: roll up days that are already done again. */
+    readonly redo?: boolean;
+}
+export interface RollupCliResult {
+    readonly done: number;
+    readonly failed: readonly {
+        day: string;
+        error: string;
+    }[];
+    readonly pending: number;
+    readonly calls?: number;
+    readonly pruned?: number;
+}
+/** `cloudhal analytics rollup [--days n] [--remote]`: backfill daily totals. */
+export declare function analyticsRollup(options: RollupCliOptions): Promise<RollupCliResult>;
+export interface SeedCliOptions {
+    readonly projectDir: string;
+    /** Days of demo traffic before today (default 30). */
+    readonly days?: number;
+    /** Average page views per day (default 120). */
+    readonly views?: number;
+    readonly now?: () => Date;
+    readonly log?: (line: string) => void;
+}
+/** `cloudhal analytics seed [--days 30]`: realistic demo data in the local SQLite only. */
+export declare function analyticsSeed(options: SeedCliOptions): Promise<{
+    events: number;
+    nodes: number;
+    rolledUp: number;
+}>;
+export interface ExportCliOptions extends AnalyticsCliOptions {
+    readonly from?: string;
+    readonly to?: string;
+    /** Write to this file instead of returning the CSV. */
+    readonly out?: string;
+}
+/** `cloudhal analytics export --from --to [--remote] [--out file]`: daily totals as CSV. */
+export declare function analyticsExport(options: ExportCliOptions): Promise<string>;