@cloudhal/cli 0.0.0-stage → 0.1.1

package/dist/src/commands/init.js

@@ -0,0 +1,142 @@
+import {
+  access,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { seedStarterSite } from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { assetDir, materializeDependencies, monorepoRoot, monorepoVersions } from "../assets.js";
+import { loadThemeSettings } from "../blocks.js";
+import { writeProjectConfig } from "../config.js";
+import { pnpmWorkspaceYaml } from "../project-setup.js";
+import { starterFilter } from "../starter-files.js";
+
+                              
+                       
+                         
+                            
+                                        
+ 
+
+async function exists(p        )                   {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Walks up from `dir` to find a pnpm workspace root (so copied starters keep `workspace:*` links). */
+export async function findWorkspaceRoot(dir        )                              {
+  let cur = path.resolve(dir);
+  for (;;) {
+    if (await exists(path.join(cur, "pnpm-workspace.yaml"))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return undefined;
+    cur = parent;
+  }
+}
+
+function slugify(s        )         {
+  return (
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 64) || "site"
+  );
+}
+
+                             
+                              
+                          
+     
+                                                                                                 
+                                                                        
+     
+                           
+ 
+
+export async function init(options             )                      {
+  const log = options.log ?? (() => {});
+  const projectDir = path.resolve(options.dir);
+  const starter = options.starter ?? "blog";
+  const startersDir = await assetDir("starters");
+  if (!startersDir) throw new Error("no starters found in this cloudhal installation");
+  const starterDir = path.join(startersDir, starter);
+  if (!(await exists(starterDir)))
+    throw new Error(`unknown starter "${starter}" (looked in ${startersDir})`);
+  if ((await exists(projectDir)) && (await readdir(projectDir)).length > 0) {
+    throw new Error(`${projectDir} is not empty`);
+  }
+  await mkdir(projectDir, { recursive: true });
+
+  await cp(starterDir, projectDir, { recursive: true, filter: await starterFilter(starterDir) });
+  // Published starters carry `_gitignore` (npm strips .gitignore from tarballs).
+  if (await exists(path.join(projectDir, "_gitignore")))
+    await rename(path.join(projectDir, "_gitignore"), path.join(projectDir, ".gitignore"));
+  log(`copied starter "${starter}"`);
+
+  const name = options.name ?? path.basename(projectDir);
+  const slug = slugify(name);
+  const pkgPath = path.join(projectDir, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"))                           ;
+  pkg.name = slug;
+  pkg.private = true;
+  // Inside the monorepo workspace the starter keeps workspace:/catalog: links. Published starters
+  // already carry real versions. From a source checkout, anywhere else, the packages are linked to
+  // that checkout: their version need not exist on npm yet.
+  const inWorkspace = (await findWorkspaceRoot(projectDir)) !== undefined;
+  const repo = inWorkspace ? undefined : await monorepoRoot();
+  const out = repo
+    ? materializeDependencies(pkg, await monorepoVersions(repo), {
+        // real paths, so the relative link survives symlinked folders (macOS /var → /private/var)
+        linkFrom: await realpath(projectDir),
+      })
+    : pkg;
+  await writeFile(pkgPath, `${JSON.stringify(out, null, 2)}\n`);
+  if (repo) log(`linked @cloudhal/* to ${repo} (install with pnpm)`);
+  // pnpm 12 fails the install unless the native builds are allowed (settings-only workspace file;
+  // inside the monorepo its own file already allows them).
+  if (!inWorkspace)
+    await writeFile(path.join(projectDir, "pnpm-workspace.yaml"), pnpmWorkspaceYaml());
+
+  const dataDir = ".cloudhal";
+  const local = await openLocalStore(path.join(projectDir, dataDir));
+  try {
+    const seeded = await seedStarterSite(local.store, { name, slug });
+    // RFC-0024 decision 4: new sites start with standard motion when the theme offers it; readers
+    // who ask for reduced motion still get less, and existing sites keep theirs.
+    const settings = await loadThemeSettings(projectDir);
+    const site =
+      settings && "motion" in settings.properties
+        ? await local.store.updateSite({
+            ...seeded,
+            theme: {
+              ...seeded.theme,
+              config: { ...(seeded.theme.config ?? {}), motion: "standard" },
+            },
+          })
+        : seeded;
+    // RFC-0006 owner decision 4: new projects record cookie-less analytics by default.
+    // RFC-0007 §15.4: reader comments are available to the deployment, but stay off for the site
+    // until someone turns them on in Studio (D4).
+    await writeProjectConfig(projectDir, {
+      siteId: site.id,
+      dataDir,
+      analytics: { enabled: true },
+      comments: { available: true },
+    });
+    log(`seeded site ${site.id} (${name}) in ${dataDir}/`);
+    return { projectDir, siteId: site.id, linked: repo !== undefined };
+  } finally {
+    await local.close();
+  }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * RFC-0011 offline: with `mail` in cloudhal.json, `cloudhal studio` prints every mail to the
+ * terminal instead of sending it, so invites and reset links can be tried without Email Service.
+ */
+import type { MailSender } from "@cloudhal/api";
+import type { MailConfig } from "../config.js";
+export declare function terminalMailSender(cfg: MailConfig, write?: (text: string) => void): MailSender;

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

@@ -0,0 +1,30 @@
+/**
+ * RFC-0011 offline: with `mail` in cloudhal.json, `cloudhal studio` prints every mail to the
+ * terminal instead of sending it, so invites and reset links can be tried without Email Service.
+ */
+                                                             
+                                               
+
+export function terminalMailSender(
+  cfg            ,
+  write                         = (text) => process.stdout.write(text),
+)             {
+  const from = cfg.fromName ? `${cfg.fromName} <${cfg.from}>` : cfg.from;
+  return {
+    id: "terminal",
+    async send(message             ) {
+      write(
+        [
+          "── mail (printed, not sent: cloudhal studio) ──",
+          `From: ${from}`,
+          `To: ${message.to}`,
+          `Subject: ${message.subject}`,
+          "",
+          message.text,
+          "──",
+          "",
+        ].join("\n"),
+      );
+    },
+  };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * `cloudhal mcp` — the project's MCP server over stdio, for local clients (Claude Code, Cursor, …).
+ * The caller is the local developer, so the default scopes are unrestricted; the approval gate
+ * (publish / rollback / delete) still applies and is answered inside the client.
+ */
+import { type AgentMode, type Scope } from "@cloudhal/agent-runtime";
+export interface McpOptions {
+    readonly projectDir: string;
+    /** Scopes granted to the client. Default: everything (`*`). */
+    readonly scopes?: readonly Scope[];
+    /** Directory of skills to expose as resources. Default: `<project>/skills`, else the bundled official skills. */
+    readonly skillsDir?: string;
+    /** Base URL of a running `cloudhal dev`, for preview links. */
+    readonly previewUrl?: string;
+    /** Agent mode (ADR-0015). Default `edits`; `bypass` is allowed here because this is local. */
+    readonly mode?: AgentMode;
+}
+/** Where the official skills live when running from the monorepo or an installed package. */
+export declare function resolveSkillsDir(projectDir: string): Promise<string | undefined>;
+export declare function mcp(options: McpOptions): Promise<{
+    stop(): Promise<void>;
+}>;

package/dist/src/commands/mcp.js

@@ -0,0 +1,113 @@
+/**
+ * `cloudhal mcp` — the project's MCP server over stdio, for local clients (Claude Code, Cursor, …).
+ * The caller is the local developer, so the default scopes are unrestricted; the approval gate
+ * (publish / rollback / delete) still applies and is answered inside the client.
+ */
+
+import { access } from "node:fs/promises";
+import path from "node:path";
+import {
+                 
+  AuditLog,
+  DEFAULT_AGENT_MODE,
+                   
+  loadSkills,
+             
+} from "@cloudhal/agent-runtime";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { nodeTransport } from "@cloudhal/core-ts/media-node";
+import { serveCloudhalStdio } from "@cloudhal/mcp-server/stdio";
+import { SqlScheduleStore } from "@cloudhal/schedules/sql";
+import { assetDir } from "../assets.js";
+import { loadBlockRegistry, loadThemeDesign, loadThemeSettings } from "../blocks.js";
+import { readProjectConfig } from "../config.js";
+import { localRender } from "../render-chrome.js";
+import { localAnalytics } from "./analytics.js";
+import { localComments } from "./comments-local.js";
+import { automationsEnabled, startLocalScheduler } from "./scheduler-local.js";
+
+                             
+                              
+                                                                 
+                                     
+                                                                                                                   
+                              
+                                                                 
+                               
+                                                                                                
+                            
+ 
+
+async function exists(p        )                   {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Where the official skills live when running from the monorepo or an installed package. */
+export async function resolveSkillsDir(projectDir        )                              {
+  const own = path.join(projectDir, "skills");
+  if (await exists(own)) return own;
+  return assetDir("skills");
+}
+
+export async function mcp(options            )                                     {
+  const cfg = await readProjectConfig(options.projectDir);
+  // The theme's block types (RFC-0015 §6) join the built-ins, and its design settings
+  // (RFC-0017 §1) check `Site.theme.config`: validated, offered, listed.
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir), {
+    blocks: await loadBlockRegistry(options.projectDir),
+    themeSettings: await loadThemeSettings(options.projectDir),
+    themeDesign: await loadThemeDesign(options.projectDir),
+  });
+  const skillsDir = options.skillsDir ?? (await resolveSkillsDir(options.projectDir));
+  const skills                = skillsDir ? await loadSkills(skillsDir) : [];
+  // The comment tools read and moderate the project's comments (RFC-0007 §11). The process owns
+  // the store while a client runs it, so it also runs the scheduler's Node ticker (RFC-0008 §8.4):
+  // releases, automations and the hourly comments job behind its watermark.
+  const comments = await localComments(local.sql, local.dataDir);
+  const ticker = startLocalScheduler({
+    sql: local.sql,
+    blobs: local.blobs,
+    graph: local.store,
+    log: (l) => process.stderr.write(`cloudhal mcp: ${l}\n`),
+  });
+  const handle = serveCloudhalStdio({
+    store: local.store,
+    principal: {
+      actor: { kind: "agent", id: "agent_localstdio", name: "local MCP client" },
+      scopes: [...(options.scopes ?? ["*"])],
+      mode: options.mode ?? DEFAULT_AGENT_MODE,
+      local: true,
+    },
+    audit: new AuditLog(local.sql),
+    skills,
+    previewBaseUrl: options.previewUrl,
+    // fetch_asset_url resolves, checks and pins every address on Node (RFC-0004 §5.7).
+    media: { fetchTransport: nodeTransport() },
+    // RFC-0021 §4: render_page with the local Chrome, when there is one.
+    render: localRender(),
+    // The analytics tools read the project's SQLite (RFC-0006 L3).
+    analytics: localAnalytics(local.sql, cfg),
+    comments,
+    // RFC-0008 §12: the schedule tools on the project's SQLite, poking this process's ticker.
+    schedules: {
+      store: new SqlScheduleStore(local.sql),
+      scheduler: ticker,
+      maxNewBodies: Number.POSITIVE_INFINITY,
+      // §11.6: `CLOUDHAL_AUTOMATIONS=off` refuses automation keys and stops occurrences.
+      automationsEnabled: automationsEnabled(),
+    },
+    onerror: (e) => process.stderr.write(`cloudhal mcp: ${e.message}\n`),
+  });
+  return {
+    stop: async () => {
+      ticker.stop();
+      await handle.close();
+      await local.close();
+    },
+  };
+}

package/dist/src/commands/media-placeholders.d.ts

@@ -0,0 +1,29 @@
+import type { Asset } from "@cloudhal/core-contracts";
+import { type PageRenderer } from "@cloudhal/mcp-server/render";
+import { type SyncOptions } from "./sync.js";
+export interface PlaceholdersCliOptions extends SyncOptions {
+    readonly remote?: boolean;
+    /** Redraw images that already have a colour. */
+    readonly all?: boolean;
+    readonly dryRun?: boolean;
+    /** Tests inject a renderer; default: the local Chrome. */
+    readonly renderer?: PageRenderer;
+}
+export interface Placeholder {
+    readonly lqip?: string;
+    readonly color?: string;
+}
+export interface PlaceholdersReport {
+    readonly where: "local" | "remote";
+    readonly candidates: number;
+    readonly drawn: number;
+    readonly failed: {
+        readonly id: string;
+        readonly reason: string;
+    }[];
+    readonly dryRun: boolean;
+}
+export declare function mediaPlaceholders(options: PlaceholdersCliOptions): Promise<PlaceholdersReport>;
+/** An image's fields with new placeholders: what the server measured and the focal point stay. */
+export declare function withPlaceholder(image: NonNullable<Asset["image"]>, p: Placeholder): NonNullable<Asset["image"]>;
+export declare function describePlaceholders(r: PlaceholdersReport): string;

package/dist/src/commands/media-placeholders.js

@@ -0,0 +1,239 @@
+/**
+ * `cloudhal media placeholders [--remote] [--all] [--dry-run]` (RFC-0028 §5): gives images their
+ * placeholder — a 24 px LQIP and the dominant colour — where nothing drew one: files that agents,
+ * imports or `cloudhal push` brought in (Studio draws them on upload). Workers cannot decode
+ * images and the deployment has no Images binding, so the drawing happens here, in the local
+ * Chrome (the one `render_page` uses), with the code Studio runs.
+ *
+ * Without `--remote` it works on the project's SQLite; with it, on the deployment through the
+ * admin API (deployment token). `--all` redraws images that already have a colour.
+ * Transparent images get their colour only: the renderer never paints their LQIP.
+ */
+import path from "node:path";
+                                                      
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import {
+  candidateOf,
+  dominantColor,
+  leanWebp,
+  needsPlaceholder,
+                            
+} from "@cloudhal/core-ts/media";
+import { bytesToBase64,                   } from "@cloudhal/mcp-server/render";
+import { readProjectConfig } from "../config.js";
+import { chromeRenderer, findChrome } from "../render-chrome.js";
+import { brief, deployment,                  } from "./sync.js";
+
+                                                             
+                            
+                                                  
+                         
+                            
+                                                            
+                                   
+ 
+
+                              
+                         
+                          
+ 
+
+                                     
+                                     
+                              
+                         
+                                                                      
+                           
+ 
+
+/** Larger files are skipped: the placeholder is not worth moving tens of megabytes. */
+const MAX_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Draws one image in the page at ≤ 24 px: the canvas's WebP and its pixels (for the colour).
+ * An `<img>` rather than `createImageBitmap`, so SVG draws too (at the asset's own size).
+ */
+const DRAW = (b64        , mediaType        , width        , height        ) => `(async () => {
+  const bytes = Uint8Array.from(atob(${JSON.stringify(b64)}), (c) => c.charCodeAt(0));
+  const url = URL.createObjectURL(new Blob([bytes], { type: ${JSON.stringify(mediaType)} }));
+  try {
+    const img = new Image();
+    img.src = url;
+    await img.decode();
+    const w = img.naturalWidth || ${width};
+    const h = img.naturalHeight || ${height};
+    const scale = 24 / Math.max(w, h);
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(w * scale));
+    canvas.height = Math.max(1, Math.round(h * scale));
+    const ctx = canvas.getContext("2d");
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+    return {
+      webp: canvas.toDataURL("image/webp", 0.5),
+      rgba: Array.from(ctx.getImageData(0, 0, canvas.width, canvas.height).data),
+    };
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+})()`;
+
+/** Where candidates come from and where placeholders go. */
+                  
+                                     
+                                                      
+                                                      
+                                                               
+                         
+ 
+
+export async function mediaPlaceholders(
+  options                        ,
+)                              {
+  const target = options.remote ? await remoteTarget(options) : await localTarget(options);
+  try {
+    const candidates = await target.list(options.all === true);
+    const failed                                   = [];
+    if (options.dryRun || candidates.length === 0)
+      return {
+        where: target.where,
+        candidates: candidates.length,
+        drawn: 0,
+        failed,
+        dryRun: !!options.dryRun,
+      };
+    const renderer = options.renderer ?? defaultRenderer();
+    const session = await renderer.session();
+    let drawn = 0;
+    try {
+      const tab = await session.open("about:blank", { width: 64, height: 64 });
+      for (const c of candidates) {
+        try {
+          const bytes = await target.bytes(c);
+          if (bytes.byteLength > MAX_BYTES) throw new Error("larger than 25 MB; skipped");
+          const out = await tab.evaluate                                  (
+            DRAW(bytesToBase64(bytes), c.mediaType, c.width, c.height),
+          );
+          const lqip = leanWebp(out.webp);
+          const color = dominantColor(out.rgba);
+          const placeholder              = {
+            ...(!c.alpha && /^data:image\/webp;base64,/.test(lqip) && lqip.length <= 3000
+              ? { lqip }
+              : {}),
+            ...(color ? { color } : {}),
+          };
+          if (!placeholder.color && !placeholder.lqip) throw new Error("nothing visible to draw");
+          await target.save(c, placeholder);
+          drawn++;
+        } catch (e) {
+          failed.push({ id: c.id, reason: e instanceof Error ? e.message : String(e) });
+        }
+      }
+      await tab.close();
+    } finally {
+      await session.close();
+    }
+    return { where: target.where, candidates: candidates.length, drawn, failed, dryRun: false };
+  } finally {
+    await target.close();
+  }
+}
+
+function defaultRenderer()               {
+  const chrome = findChrome();
+  if (!chrome)
+    throw new Error(
+      "placeholders are drawn in a local Chrome and none was found; install Chrome or set CHROME_PATH",
+    );
+  return chromeRenderer(chrome, { idleMs: 1000 });
+}
+
+async function localTarget(options                        )                  {
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  const { store } = local;
+  return {
+    where: "local",
+    async list(all) {
+      const out                         = [];
+      let cursor                    ;
+      do {
+        const page = await store.listAssets(cfg.siteId, {
+          kind: ["image"],
+          status: ["active", "retired"],
+          ...(cursor ? { cursor } : {}),
+        });
+        for (const a of page.assets) if (needsPlaceholder(a, all)) out.push(candidateOf(a));
+        cursor = page.nextCursor;
+      } while (cursor);
+      return out;
+    },
+    async bytes(c) {
+      const bytes = await store.readMediaBlob(cfg.siteId, c.sha256);
+      if (!bytes) throw new Error("its bytes are missing");
+      return bytes;
+    },
+    async save(c, p) {
+      const asset = await store.getAsset(c.id);
+      if (!asset?.image) throw new Error("it is gone");
+      await store.updateAsset({ ...asset, image: withPlaceholder(asset.image, p) });
+    },
+    close: () => local.close(),
+  };
+}
+
+async function remoteTarget(options                        )                  {
+  const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+  const auth = { authorization: `Bearer ${token}` };
+  const call = async (url        , init              = {}) => {
+    const res = await f(new URL(url, adminUrl), { ...init, headers: { ...auth, ...init.headers } });
+    if (
+      res.status === 404 &&
+      url.includes("placeholders") &&
+      !(await res.clone().text()).includes("not found:")
+    )
+      throw new Error(
+        "the deployment has no placeholder backfill yet (deploy this version with `cloudhal deploy` first)",
+      );
+    if (!res.ok)
+      throw new Error(`the deployment answered ${res.status}: ${brief(await res.text())}`);
+    return res;
+  };
+  const base = `/api/admin/sites/${cfg.siteId}`;
+  return {
+    where: "remote",
+    async list(all) {
+      const res = await call(`${base}/media-placeholders${all ? "?all=1" : ""}`);
+      return ((await res.json())                                      ).assets;
+    },
+    async bytes(c) {
+      const res = await call(`${base}/media/${c.sha256}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    async save(c, p) {
+      await call(`${base}/media-placeholders/${c.id}`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ rev: c.rev, ...p }),
+      });
+    },
+    close: async () => {},
+  };
+}
+
+/** An image's fields with new placeholders: what the server measured and the focal point stay. */
+export function withPlaceholder(
+  image                             ,
+  p             ,
+)                              {
+  const { lqip: _l, color: _c, ...kept } = image;
+  return { ...kept, ...(p.lqip ? { lqip: p.lqip } : {}), ...(p.color ? { color: p.color } : {}) };
+}
+
+export function describePlaceholders(r                    )         {
+  if (r.candidates === 0) return `${r.where}: every image has its placeholder`;
+  if (r.dryRun)
+    return `${r.where}: ${r.candidates} image(s) need a placeholder (dry run, nothing drawn)`;
+  const lines = [`${r.where}: drew ${r.drawn} of ${r.candidates} placeholder(s)`];
+  for (const f of r.failed) lines.push(`  ${f.id}: ${f.reason}`);
+  return lines.join("\n");
+}

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

@@ -0,0 +1,32 @@
+import { type MediaImportResult, type MediaRevertResult } from "@cloudhal/core-ts";
+import { type FetchTransport } from "@cloudhal/core-ts/media";
+export interface MediaImportCliOptions {
+    readonly projectDir: string;
+    readonly dryRun?: boolean;
+    readonly includeMarkdown?: boolean;
+    readonly revert?: string;
+    /** Hosts https sources may come from (`--allow-host`, repeatable); the site's list applies too. */
+    readonly allowHosts?: readonly string[];
+    /** Tests inject a transport (a fake origin); default: the pinning Node transport. */
+    readonly transport?: FetchTransport;
+}
+export declare function mediaImportUrls(options: MediaImportCliOptions): Promise<MediaImportResult | MediaRevertResult>;
+export interface VerifyResult {
+    readonly checked: number;
+    readonly ok: string[];
+    readonly problems: {
+        assetId: string;
+        problem: string;
+    }[];
+}
+export declare function mediaVerify(options: {
+    projectDir: string;
+    assetId?: string;
+    transport?: FetchTransport;
+}): Promise<VerifyResult>;
+export declare function mediaGc(options: {
+    projectDir: string;
+    dryRun?: boolean;
+}): Promise<import("@cloudhal/core-ts").GcResult>;
+/** Human-readable lines for a run. */
+export declare function describeMediaImport(r: MediaImportResult | MediaRevertResult): string[];