@cloudhal/cli 0.0.0-stage → 0.1.0

package/dist/src/index.js

@@ -0,0 +1,82 @@
+export {
+                           
+  analyticsExport,
+  analyticsRollup,
+  analyticsSeed,
+  analyticsStatus,
+  describeStatus,
+                        
+  localAnalytics,
+                        
+  runLocalRollups,
+                      
+} from "./commands/analytics.js";
+export {                    build,                  dev } from "./commands/astro.js";
+export {
+                          
+                                
+                                
+                            
+                            
+  commentsExportCli,
+  commentsImportCli,
+  commentsStatusCli,
+  describeCommentsStatus,
+} from "./commands/comments.js";
+export { runLocalCommentsJob, startLocalCommentsJob } from "./commands/comments-local.js";
+export {
+                     
+                    
+  deploy,
+  loadOrCreateSecrets,
+  readDeployState,
+} from "./commands/deploy.js";
+export { findWorkspaceRoot,                                    init } from "./commands/init.js";
+export {
+  describeMediaImport,
+                             
+  mediaGc,
+  mediaImportUrls,
+  mediaVerify,
+                    
+} from "./commands/media.js";
+export { describeMigration,                          migrateTags } from "./commands/migrate.js";
+export {
+                            
+                           
+  transferOwner,
+} from "./commands/owner.js";
+export {
+  automationsEnabled,
+                      
+                             
+  runLocalTick,
+  startLocalScheduler,
+} from "./commands/scheduler-local.js";
+export {
+  describeSchedulesStatus,
+                           
+                             
+  schedulesList,
+  schedulesRunDue,
+  schedulesStatus,
+} from "./commands/schedules.js";
+export { resolveBuildSnapshot,                       snapshot } from "./commands/snapshot.js";
+export {                     studio } from "./commands/studio.js";
+export { pullSite, pushSite,                  } from "./commands/sync.js";
+export {
+                       
+  CONFIG_FILE,
+                      
+  commentsAvailable,
+                     
+  readProjectConfig,
+  writeProjectConfig,
+} from "./config.js";
+export {
+  BUILD_DEPENDENCIES,
+  detectPackageManager,
+  nextSteps,
+                      
+  pnpmWorkspaceYaml,
+} from "./project-setup.js";

package/dist/src/project-setup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a new project needs besides the starter's files so the first install and the first run
+ * work with npm, pnpm, yarn and bun (ADR-0013): which install scripts to allow, and the next
+ * steps to print in the package manager the person used.
+ */
+/**
+ * Dependencies whose install scripts must run (native builds and binaries): pnpm 12 refuses the
+ * install without `allowBuilds` for them, bun skips them without `trustedDependencies`. The
+ * monorepo's own pnpm-workspace.yaml allows the same ones.
+ */
+export declare const BUILD_DEPENDENCIES: readonly ["better-sqlite3", "esbuild", "workerd"];
+/** pnpm settings for a project outside a workspace: settings only, no `packages`. */
+export declare function pnpmWorkspaceYaml(): string;
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+/** The package manager that started this process (`npm create`, `pnpm dlx`, `bunx` …); npm otherwise. */
+export declare function detectPackageManager(userAgent?: string | undefined): PackageManager;
+/**
+ * The commands to run after `init`. `cloudhal` itself is a project dependency, not on PATH, so
+ * every step goes through the project's npm scripts.
+ */
+export declare function nextSteps(dir: string, pm: PackageManager): string[];

package/dist/src/project-setup.js

@@ -0,0 +1,50 @@
+/**
+ * What a new project needs besides the starter's files so the first install and the first run
+ * work with npm, pnpm, yarn and bun (ADR-0013): which install scripts to allow, and the next
+ * steps to print in the package manager the person used.
+ */
+
+/**
+ * Dependencies whose install scripts must run (native builds and binaries): pnpm 12 refuses the
+ * install without `allowBuilds` for them, bun skips them without `trustedDependencies`. The
+ * monorepo's own pnpm-workspace.yaml allows the same ones.
+ */
+export const BUILD_DEPENDENCIES = ["better-sqlite3", "esbuild", "workerd"]         ;
+
+/** pnpm settings for a project outside a workspace: settings only, no `packages`. */
+export function pnpmWorkspaceYaml()         {
+  return [
+    "# pnpm 12 runs install scripts only for packages allowed here.",
+    "allowBuilds:",
+    ...BUILD_DEPENDENCIES.map((name) => `  ${name}: true`),
+    "",
+  ].join("\n");
+}
+
+                                                             
+
+/** The package manager that started this process (`npm create`, `pnpm dlx`, `bunx` …); npm otherwise. */
+export function detectPackageManager(
+  userAgent                     = process.env.npm_config_user_agent,
+)                 {
+  const name = userAgent?.split("/")[0];
+  return name === "pnpm" || name === "yarn" || name === "bun" ? name : "npm";
+}
+
+/**
+ * The commands to run after `init`. `cloudhal` itself is a project dependency, not on PATH, so
+ * every step goes through the project's npm scripts.
+ */
+export function nextSteps(dir        , pm                )           {
+  const scripts                          = [
+    ["dev", "live preview with drafts, fully offline"],
+    ["studio", "Studio + API + MCP for this project"],
+    ["deploy", "put it on Cloudflare (uses your wrangler login)"],
+  ];
+  const width = Math.max(...scripts.map(([s]) => `${pm} run ${s}`.length)) + 3;
+  return [
+    `cd ${/\s/.test(dir) ? JSON.stringify(dir) : dir}`,
+    `${pm} install`,
+    ...scripts.map(([s, what]) => `${`${pm} run ${s}`.padEnd(width)}${what}`),
+  ];
+}

package/dist/src/render-chrome.d.ts

@@ -0,0 +1,9 @@
+import { type PageRenderer } from "@cloudhal/mcp-server/render";
+import type { RenderDeps } from "@cloudhal/mcp-server/tools";
+/** The Chrome to render with, if this machine has one. */
+export declare function findChrome(env?: NodeJS.ProcessEnv): string | undefined;
+/** `render_page`'s deps for `cloudhal studio` and `cloudhal mcp`, or undefined (no Chrome, or off). */
+export declare function localRender(env?: NodeJS.ProcessEnv): RenderDeps | undefined;
+export declare function chromeRenderer(executable: string, options?: {
+    idleMs?: number;
+}): PageRenderer;

package/dist/src/render-chrome.js

@@ -0,0 +1,140 @@
+/**
+ * `render_page` on Node (RFC-0021 §4): the local Chrome over its DevTools protocol, started on
+ * the first render and stopped after a minute without one. `CHROME_PATH` picks the executable;
+ * `CLOUDHAL_RENDER=off` turns rendering off. No browser library: Node 24 has WebSocket.
+ */
+import {                    spawn } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {                 cdpSession,                   } from "@cloudhal/mcp-server/render";
+                                                             
+
+const CANDIDATES = [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+  "/opt/pw-browsers/chromium",
+  "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+];
+
+/** The Chrome to render with, if this machine has one. */
+export function findChrome(env                    = process.env)                     {
+  if (env.CHROME_PATH) return existsSync(env.CHROME_PATH) ? env.CHROME_PATH : undefined;
+  return CANDIDATES.find((p) => existsSync(p));
+}
+
+/** `render_page`'s deps for `cloudhal studio` and `cloudhal mcp`, or undefined (no Chrome, or off). */
+export function localRender(env                    = process.env)                         {
+  if (env.CLOUDHAL_RENDER === "off") return undefined;
+  const executable = findChrome(env);
+  return executable ? { renderer: chromeRenderer(executable) } : undefined;
+}
+
+function nodeSocket(ws           )            {
+  return {
+    send: (m) => ws.send(m),
+    onMessage: (l) => ws.addEventListener("message", (e) => l(String(e.data))),
+    onClose: (l) => ws.addEventListener("close", () => l()),
+    close: () => ws.close(),
+  };
+}
+
+export function chromeRenderer(
+  executable        ,
+  options                      = {},
+)               {
+  let chrome                                                                               ;
+  let active = 0;
+  let idle                                           ;
+
+  const stop = () => {
+    if (!chrome) return;
+    const { process: child, dir } = chrome;
+    chrome = undefined;
+    child.kill();
+    // A Chrome still starting up can ignore SIGTERM and outlive this process: force it.
+    const force = setTimeout(() => child.kill("SIGKILL"), 2000);
+    force.unref?.();
+    child.once("exit", () => clearTimeout(force));
+    // Chrome's helpers can still be writing into the profile as the main process exits: retry,
+    // and never let a leftover temporary directory become an uncaught exception.
+    child.once("exit", () => {
+      try {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+      } catch {
+        // the OS cleans its temporary directory
+      }
+    });
+  };
+
+  const start = () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "cloudhal-render-"));
+    const child = spawn(
+      executable,
+      [
+        "--headless=new",
+        "--remote-debugging-port=0",
+        `--user-data-dir=${dir}`,
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--hide-scrollbars",
+        "--mute-audio",
+        "about:blank",
+      ],
+      { stdio: ["ignore", "ignore", "pipe"] },
+    );
+    const endpoint = new Promise        ((resolve, reject) => {
+      let err = "";
+      const timer = setTimeout(() => reject(new Error("Chrome did not start")), 10_000);
+      child.stderr?.on("data", (chunk        ) => {
+        err += chunk.toString();
+        const m = /DevTools listening on (ws:\/\/\S+)/.exec(err);
+        if (m) {
+          clearTimeout(timer);
+          resolve(m[1]          );
+        }
+      });
+      child.once("exit", () => {
+        clearTimeout(timer);
+        reject(new Error("Chrome exited"));
+        if (chrome?.process === child) chrome = undefined;
+      });
+    });
+    endpoint.catch(() => {});
+    chrome = { process: child, endpoint, dir };
+    process.once("exit", () => child.kill());
+    return chrome;
+  };
+
+  return {
+    async session() {
+      clearTimeout(idle);
+      const { endpoint } = chrome ?? start();
+      const ws = new WebSocket(await endpoint);
+      await new Promise      ((resolve, reject) => {
+        ws.addEventListener("open", () => resolve(), { once: true });
+        ws.addEventListener("error", () => reject(new Error("could not reach Chrome")), {
+          once: true,
+        });
+      });
+      active++;
+      const session = await cdpSession(nodeSocket(ws));
+      return {
+        open: session.open,
+        async close() {
+          await session.close();
+          active--;
+          if (active === 0) {
+            idle = setTimeout(stop, options.idleMs ?? 60_000);
+            idle.unref?.();
+          }
+        },
+      };
+    },
+  };
+}

package/dist/src/starter-files.d.ts

@@ -0,0 +1,4 @@
+/** Never copied, with or without git. */
+export declare const STARTER_SKIP: Set<string>;
+/** A `cp` filter for copying `dir`: keeps a path when it is, or leads to, a file worth copying. */
+export declare function starterFilter(dir: string): Promise<(src: string) => boolean>;

package/dist/src/starter-files.js

@@ -0,0 +1,51 @@
+/**
+ * Which files of a starter get copied (by `cloudhal init` and by the package build). Inside a git
+ * checkout only what git knows — tracked files and new ones it does not ignore — so local build
+ * output, test leftovers and other ignored files never reach a new project; elsewhere (a
+ * published CLI, no git) everything but the build directories.
+ */
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+/** Never copied, with or without git. */
+export const STARTER_SKIP = new Set([
+  "node_modules",
+  "dist",
+  ".astro",
+  ".cloudhal",
+  ".wrangler",
+  "wrangler.jsonc",
+  "cloudhal.json",
+]);
+
+/** The starter's files as git sees them, relative to `dir`; undefined outside a git checkout. */
+async function gitFiles(dir        )                                   {
+  try {
+    const { stdout } = await promisify(execFile)(
+      "git",
+      ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "."],
+      { cwd: dir, maxBuffer: 16 * 1024 * 1024 },
+    );
+    const files = stdout.split("\0").filter(Boolean);
+    return files.length > 0 ? new Set(files) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A `cp` filter for copying `dir`: keeps a path when it is, or leads to, a file worth copying. */
+export async function starterFilter(dir        )                                    {
+  const files = await gitFiles(dir);
+  const keep = new Set        ();
+  for (const file of files ?? []) {
+    const parts = file.split("/");
+    for (let i = 1; i <= parts.length; i++) keep.add(parts.slice(0, i).join("/"));
+  }
+  return (src) => {
+    if (STARTER_SKIP.has(path.basename(src))) return false;
+    if (!files) return true;
+    const rel = path.relative(dir, src).split(path.sep).join("/");
+    return rel === "" || keep.has(rel);
+  };
+}

package/dist/src/studio-build.d.ts

@@ -0,0 +1,43 @@
+/** The monorepo's Studio build, relative to the repo root. */
+export declare const MONOREPO_STUDIO_DIST = "apps/studio/dist";
+/** What a Studio build is made from, relative to the repo root (files or directories). */
+export declare const STUDIO_SOURCES: string[];
+export declare const STUDIO_BUILD_COMMAND = "pnpm --filter @cloudhal/studio build";
+/** The most recently modified file under `paths` (each a file or a directory), if any. */
+export declare function newestFile(paths: readonly string[]): Promise<{
+    file: string;
+    mtimeMs: number;
+} | undefined>;
+export type StudioBuildState = {
+    state: "current";
+} | {
+    state: "missing";
+}
+/** `newest` is the source file (relative to the repo root) edited after the build. */
+ | {
+    state: "stale";
+    newest: string;
+};
+/** Compares the monorepo's `apps/studio/dist/index.html` with the newest Studio source file. */
+export declare function studioBuildState(repoRoot: string): Promise<StudioBuildState>;
+export type StudioBuilder = (repoRoot: string, log: (line: string) => void) => Promise<void>;
+/** Runs `pnpm --filter @cloudhal/studio build` in the repo root. */
+export declare const pnpmStudioBuild: StudioBuilder;
+export interface EnsureStudioBuildOptions {
+    /** The Studio directory the deploy is about to upload. */
+    readonly studioDir: string;
+    /** The monorepo root when the CLI runs from source; undefined for a published install. */
+    readonly repoRoot: string | undefined;
+    /** `false` (`--no-build-studio`): never build; a missing or stale build fails the deploy. */
+    readonly build: boolean;
+    readonly log: (line: string) => void;
+    /** Injected in tests. */
+    readonly builder?: StudioBuilder;
+}
+/**
+ * When `studioDir` is the monorepo's `apps/studio/dist`, makes sure it is at least as new as the
+ * Studio sources: builds it when it is missing or older, or fails naming the command when building
+ * is switched off. Any other directory (a published install's shipped copy, an explicit one) is
+ * left alone. Returns whether it built.
+ */
+export declare function ensureStudioBuild(options: EnsureStudioBuildOptions): Promise<boolean>;

package/dist/src/studio-build.js

@@ -0,0 +1,138 @@
+/**
+ * Keeps `cloudhal deploy` from shipping a stale Studio when it runs from the monorepo, where the
+ * Studio is `apps/studio/dist` — a build nothing else keeps current. A published install ships
+ * Studio prebuilt in `dist/assets/studio` and is never checked.
+ */
+import { spawn } from "node:child_process";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** The monorepo's Studio build, relative to the repo root. */
+export const MONOREPO_STUDIO_DIST = "apps/studio/dist";
+
+/** What a Studio build is made from, relative to the repo root (files or directories). */
+export const STUDIO_SOURCES = ["apps/studio/src", "apps/studio/index.html", "packages/ui/src"];
+
+export const STUDIO_BUILD_COMMAND = "pnpm --filter @cloudhal/studio build";
+
+async function mtimeOf(p        )                              {
+  try {
+    return (await stat(p)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The most recently modified file under `paths` (each a file or a directory), if any. */
+export async function newestFile(
+  paths                   ,
+)                                                         {
+  let newest                                               ;
+  const visit = async (p        )                => {
+    let s                                  ;
+    try {
+      s = await stat(p);
+    } catch {
+      return;
+    }
+    if (s.isDirectory()) {
+      for (const name of await readdir(p)) await visit(path.join(p, name));
+    } else if (!newest || s.mtimeMs > newest.mtimeMs) newest = { file: p, mtimeMs: s.mtimeMs };
+  };
+  for (const p of paths) await visit(p);
+  return newest;
+}
+
+                              
+                        
+                        
+                                                                                        
+                                       
+
+/** Compares the monorepo's `apps/studio/dist/index.html` with the newest Studio source file. */
+export async function studioBuildState(repoRoot        )                            {
+  const built = await mtimeOf(path.join(repoRoot, MONOREPO_STUDIO_DIST, "index.html"));
+  if (built === undefined) return { state: "missing" };
+  const newest = await newestFile(STUDIO_SOURCES.map((p) => path.join(repoRoot, p)));
+  return newest && newest.mtimeMs > built
+    ? { state: "stale", newest: path.relative(repoRoot, newest.file) }
+    : { state: "current" };
+}
+
+                                                                                             
+
+/** Runs `pnpm --filter @cloudhal/studio build` in the repo root. */
+export const pnpmStudioBuild                = async (repoRoot, log) => {
+  const { VITEST: _v, NODE_ENV: _n, ...env } = process.env;
+  await new Promise      ((resolve, reject) => {
+    const child = spawn("pnpm", ["--filter", "@cloudhal/studio", "build"], {
+      cwd: repoRoot,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32",
+    });
+    let output = "";
+    const onData = (chunk        ) => {
+      output += chunk.toString();
+      for (const line of chunk.toString().split("\n")) if (line.trim()) log(`  ${line}`);
+    };
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    child.once("error", (err) =>
+      reject(new Error(`could not run \`${STUDIO_BUILD_COMMAND}\`: ${err.message}`)),
+    );
+    child.once("exit", (code) =>
+      code === 0
+        ? resolve()
+        : reject(
+            new Error(`\`${STUDIO_BUILD_COMMAND}\` failed (${code}):\n${output.slice(-4000)}`),
+          ),
+    );
+  });
+};
+
+                                           
+                                                            
+                             
+                                                                                            
+                                        
+                                                                                               
+                          
+                                       
+                           
+                                   
+ 
+
+/**
+ * When `studioDir` is the monorepo's `apps/studio/dist`, makes sure it is at least as new as the
+ * Studio sources: builds it when it is missing or older, or fails naming the command when building
+ * is switched off. Any other directory (a published install's shipped copy, an explicit one) is
+ * left alone. Returns whether it built.
+ */
+export async function ensureStudioBuild(options                          )                   {
+  const { repoRoot, log } = options;
+  if (!repoRoot) return false;
+  if (path.resolve(options.studioDir) !== path.resolve(repoRoot, MONOREPO_STUDIO_DIST))
+    return false;
+  const current = await studioBuildState(repoRoot);
+  if (current.state === "current") return false;
+  const why =
+    current.state === "missing"
+      ? `no Studio build at ${MONOREPO_STUDIO_DIST}`
+      : `the Studio build in ${MONOREPO_STUDIO_DIST} is older than ${current.newest}`;
+  if (!options.build)
+    throw new Error(
+      `${why}. Run \`${STUDIO_BUILD_COMMAND}\`, or deploy without --no-build-studio to build it.`,
+    );
+  log(`studio: ${why}; running \`${STUDIO_BUILD_COMMAND}\``);
+  await (options.builder ?? pnpmStudioBuild)(repoRoot, log);
+  const after = await studioBuildState(repoRoot);
+  if (after.state === "missing")
+    throw new Error(
+      `\`${STUDIO_BUILD_COMMAND}\` finished without ${MONOREPO_STUDIO_DIST}/index.html`,
+    );
+  // A source dated in the future (clock skew) stays newer than any build; say so, deploy anyway.
+  if (after.state === "stale")
+    log(`studio: built, but ${after.newest} is dated after the new build (clock skew?)`);
+  return true;
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@cloudhal/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "cloudhal — create, run and build Cloudhal sites locally",
+  "license": "Apache-2.0",
+  "homepage": "https://cloudhal.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudhal-dev/cloudhal.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/cloudhal-dev/cloudhal/issues"
+  },
+  "type": "module",
+  "bin": {
+    "cloudhal": "./dist/bin/cloudhal.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cloudhal/agent-runtime": "0.1.0",
+    "@cloudhal/analytics": "0.1.0",
+    "@cloudhal/api": "0.1.0",
+    "@cloudhal/cloudflare": "0.1.0",
+    "@cloudhal/comments": "0.1.0",
+    "@cloudhal/core-contracts": "0.1.0",
+    "@cloudhal/core-ts": "0.1.0",
+    "@cloudhal/mcp-server": "0.1.0",
+    "@cloudhal/schedules": "0.1.0",
+    "@cloudhal/storage": "0.1.0",
+    "@hono/node-server": "^2.1.4",
+    "better-sqlite3": "13.0.3"
+  },
+  "peerDependencies": {
+    "astro": "^7.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "astro": "^7.3.6",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3",
+    "@modelcontextprotocol/client": "2.3.1",
+    "wrangler": "4.148.0",
+    "@cloudflare/workers-types": "^5.20261007.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test"
+  }
 }