@cloudhal/cli 0.0.0-stage → 0.1.1

package/dist/src/cli.d.ts

@@ -0,0 +1,174 @@
+import type { CliCommand } from "./cli/types.js";
+/** Every flag any command takes; `CliValues` (cli/types.ts) is inferred from it. */
+export declare const OPTIONS: {
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+    };
+    readonly name: {
+        readonly type: "string";
+    };
+    readonly starter: {
+        readonly type: "string";
+    };
+    readonly port: {
+        readonly type: "string";
+    };
+    readonly host: {
+        readonly type: "boolean";
+    };
+    readonly label: {
+        readonly type: "string";
+    };
+    readonly publish: {
+        readonly type: "boolean";
+    };
+    readonly snapshot: {
+        readonly type: "string";
+    };
+    readonly "no-auth": {
+        readonly type: "boolean";
+    };
+    readonly scopes: {
+        readonly type: "string";
+    };
+    readonly skills: {
+        readonly type: "string";
+    };
+    readonly "preview-url": {
+        readonly type: "string";
+    };
+    readonly mode: {
+        readonly type: "string";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+    };
+    readonly replace: {
+        readonly type: "boolean";
+    };
+    readonly "admin-url": {
+        readonly type: "string";
+    };
+    readonly studio: {
+        readonly type: "string";
+    };
+    readonly revert: {
+        readonly type: "string";
+    };
+    readonly to: {
+        readonly type: "string";
+    };
+    readonly "include-markdown": {
+        readonly type: "boolean";
+    };
+    readonly "allow-host": {
+        readonly type: "string";
+        readonly multiple: true;
+    };
+    readonly remote: {
+        readonly type: "boolean";
+    };
+    readonly all: {
+        readonly type: "boolean";
+    };
+    readonly redo: {
+        readonly type: "boolean";
+    };
+    readonly days: {
+        readonly type: "string";
+    };
+    readonly views: {
+        readonly type: "string";
+    };
+    readonly from: {
+        readonly type: "string";
+    };
+    readonly out: {
+        readonly type: "string";
+    };
+    readonly jurisdiction: {
+        readonly type: "string";
+    };
+    readonly in: {
+        readonly type: "string";
+    };
+    readonly file: {
+        readonly type: "string";
+    };
+    readonly "with-personal-data": {
+        readonly type: "boolean";
+    };
+    readonly scheduler: {
+        readonly type: "string";
+    };
+    readonly plan: {
+        readonly type: "string";
+    };
+    readonly "force-downgrade": {
+        readonly type: "boolean";
+    };
+    readonly "no-build-studio": {
+        readonly type: "boolean";
+    };
+    readonly "cancel-schedules": {
+        readonly type: "boolean";
+    };
+    readonly limit: {
+        readonly type: "string";
+    };
+    readonly models: {
+        readonly type: "string";
+    };
+    readonly briefs: {
+        readonly type: "string";
+    };
+    readonly design: {
+        readonly type: "boolean";
+    };
+    readonly look: {
+        readonly type: "boolean";
+    };
+    readonly judge: {
+        readonly type: "string";
+    };
+    readonly format: {
+        readonly type: "string";
+    };
+    readonly width: {
+        readonly type: "string";
+    };
+    readonly scheme: {
+        readonly type: "string";
+    };
+    readonly motion: {
+        readonly type: "string";
+    };
+    readonly frames: {
+        readonly type: "string";
+    };
+    readonly base: {
+        readonly type: "string";
+    };
+    readonly path: {
+        readonly type: "string";
+    };
+    readonly slug: {
+        readonly type: "string";
+    };
+    readonly locale: {
+        readonly type: "string";
+    };
+    readonly project: {
+        readonly type: "string";
+    };
+    readonly theme: {
+        readonly type: "string";
+    };
+    readonly confirm: {
+        readonly type: "string";
+    };
+};
+/** `cloudhal <command>` → its handler. */
+export declare const COMMANDS: Record<string, CliCommand>;
+export declare function main(argv: string[]): Promise<number>;

package/dist/src/cli.js

@@ -0,0 +1,95 @@
+import { parseArgs } from "node:util";
+import { CONTENT_COMMANDS } from "./cli/commands-content.js";
+import { LOCAL_COMMANDS } from "./cli/commands-local.js";
+import { OPS_COMMANDS } from "./cli/commands-ops.js";
+import { REMOTE_COMMANDS } from "./cli/commands-remote.js";
+import { SITE_COMMANDS } from "./cli/commands-site.js";
+import { HELP } from "./cli/help.js";
+                                                 
+
+/** Every flag any command takes; `CliValues` (cli/types.ts) is inferred from it. */
+export const OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  name: { type: "string" },
+  starter: { type: "string" },
+  port: { type: "string" },
+  host: { type: "boolean" },
+  label: { type: "string" },
+  publish: { type: "boolean" },
+  snapshot: { type: "string" },
+  "no-auth": { type: "boolean" },
+  scopes: { type: "string" },
+  skills: { type: "string" },
+  "preview-url": { type: "string" },
+  mode: { type: "string" },
+  "dry-run": { type: "boolean" },
+  replace: { type: "boolean" },
+  "admin-url": { type: "string" },
+  studio: { type: "string" },
+  revert: { type: "string" },
+  to: { type: "string" },
+  "include-markdown": { type: "boolean" },
+  "allow-host": { type: "string", multiple: true },
+  remote: { type: "boolean" },
+  all: { type: "boolean" },
+  redo: { type: "boolean" },
+  days: { type: "string" },
+  views: { type: "string" },
+  from: { type: "string" },
+  out: { type: "string" },
+  jurisdiction: { type: "string" },
+  in: { type: "string" },
+  file: { type: "string" },
+  "with-personal-data": { type: "boolean" },
+  scheduler: { type: "string" },
+  plan: { type: "string" },
+  "force-downgrade": { type: "boolean" },
+  "no-build-studio": { type: "boolean" },
+  "cancel-schedules": { type: "boolean" },
+  limit: { type: "string" },
+  models: { type: "string" },
+  briefs: { type: "string" },
+  design: { type: "boolean" },
+  look: { type: "boolean" },
+  judge: { type: "string" },
+  format: { type: "string" },
+  width: { type: "string" },
+  scheme: { type: "string" },
+  motion: { type: "string" },
+  frames: { type: "string" },
+  base: { type: "string" },
+  path: { type: "string" },
+  slug: { type: "string" },
+  locale: { type: "string" },
+  project: { type: "string" },
+  theme: { type: "string" },
+  confirm: { type: "string" },
+}         ;
+
+/** `cloudhal <command>` → its handler. */
+export const COMMANDS                             = {
+  ...LOCAL_COMMANDS,
+  ...REMOTE_COMMANDS,
+  ...CONTENT_COMMANDS,
+  ...OPS_COMMANDS,
+  ...SITE_COMMANDS,
+};
+
+export async function main(argv          )                  {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: OPTIONS,
+  });
+  const [command, ...rest] = positionals;
+  if (values.help || !command) {
+    process.stdout.write(HELP);
+    return command ? 0 : 1;
+  }
+  const run = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
+  if (!run) {
+    process.stderr.write(`unknown command "${command}"\n\n${HELP}`);
+    return 1;
+  }
+  return run(rest, values, { projectDir: process.cwd() });
+}

package/dist/src/cloudflare/admin.d.ts

@@ -0,0 +1,54 @@
+import { type AnalyticsDeployment, type CommentsDeployment, type DeploymentNames, type MailDeployment, type ObservabilityDeployment, type SchedulerTicker, type SchedulesDeployment } from "./config.js";
+export interface PreparedAdmin {
+    dir: string;
+    configPath: string;
+}
+/**
+ * The admin Worker's entry: the prelude first (zod initialisation order; see the module), the
+ * skills as data, and the theme's block types (RFC-0015 §6) imported from the project so wrangler
+ * bundles them.
+ */
+export declare function adminEntry(blockTypes?: string, themeSettings?: string, themeDesign?: boolean): string;
+export declare function prepareAdminWorker(options: {
+    projectDir: string;
+    dataDir: string;
+    names: DeploymentNames;
+    /** The site the site Worker serves (`CLOUDHAL_SITE_ID`; the feed check fetches only its feed). */
+    siteId?: string | undefined;
+    /** RFC-0034 §4: the sites a multi-site site Worker serves. */
+    siteIds?: readonly string[] | undefined;
+    /** RFC-0034 §4: site Workers attached to this installation (`/api/admin/site-workers`). */
+    siteWorkers?: readonly {
+        name: string;
+        siteIds: readonly string[];
+    }[] | undefined;
+    /** Built Studio (`apps/studio/dist`). */
+    studioDir: string;
+    skillsDir?: string | undefined;
+    /** Custom domain for Studio (Cloudflare Custom Domain). */
+    domain?: string | undefined;
+    /** Site analytics: the Analytics SQL binding and vars (RFC-0006 §11). */
+    analytics?: AnalyticsDeployment | undefined;
+    /** Reader comments: the availability switch (RFC-0007 §15.3). */
+    comments?: CommentsDeployment | undefined;
+    /** The scheduler's ticker (RFC-0008 §8.3): the minute cron trigger (default) or the clock. */
+    scheduler?: SchedulerTicker | undefined;
+    /** The tick budget and the automations switch (RFC-0008 §8.2, §11.6). */
+    schedules?: SchedulesDeployment | undefined;
+    /** Email delivery (RFC-0011): the `send_email` binding and the sender vars. */
+    mail?: MailDeployment | undefined;
+    /** In-editor AI (RFC-0016): the Workers AI binding. */
+    ai?: boolean | undefined;
+    /** Browser Rendering for `render_page` (RFC-0021 §4). */
+    browser?: boolean | undefined;
+    /** The theme's `src/blocks.ts` (RFC-0015 §6), bundled into the Worker with it. */
+    blockTypes?: string | undefined;
+    /** The theme's `src/settings.ts` (RFC-0017 §1), bundled the same way. */
+    themeSettings?: string | undefined;
+    /** The theme's DESIGN.md text (RFC-0021 §1), written next to the entry. */
+    themeDesign?: string | undefined;
+    /** Logs sampling and opt-in traces. */
+    observability?: ObservabilityDeployment | undefined;
+    /** Smart Placement for the admin Worker. */
+    placement?: "smart" | undefined;
+}): Promise<PreparedAdmin>;

package/dist/src/cloudflare/admin.js

@@ -0,0 +1,156 @@
+/**
+ * Prepares the admin Worker for wrangler: `<project>/.cloudhal/deploy/admin/` gets an entry that
+ * bundles the project's skills, and a wrangler config pointing at the built Studio.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readSkillSources } from "@cloudhal/agent-runtime";
+import {
+                           
+  adminWorkerConfig,
+                          
+                       
+                      
+                               
+  readExistingIds,
+                       
+                           
+  writeWranglerConfig,
+} from "./config.js";
+
+                                
+              
+                     
+ 
+
+/**
+ * The admin Worker's entry: the prelude first (zod initialisation order; see the module), the
+ * skills as data, and the theme's block types (RFC-0015 §6) imported from the project so wrangler
+ * bundles them.
+ */
+export function adminEntry(
+  blockTypes         ,
+  themeSettings         ,
+  themeDesign = false,
+)         {
+  const rel = (p                    ) => (p && !p.startsWith(".") ? `./${p}` : p);
+  const blocksFrom = rel(blockTypes);
+  const settingsFrom = rel(themeSettings);
+  const options = [
+    "skills",
+    ...(blocksFrom ? ["blockTypes"] : []),
+    ...(settingsFrom ? ["themeSettings"] : []),
+    ...(themeDesign ? ["themeDesign"] : []),
+  ];
+  return [
+    "// Generated by `cloudhal deploy`.",
+    "// The prelude must stay first (zod initialisation order; see the module).",
+    'import "@cloudhal/cloudflare/workerd-prelude";',
+    'import { createAdminWorker } from "@cloudhal/cloudflare/admin";',
+    'import skills from "./skills.ts";',
+    ...(blocksFrom ? [`import { blockTypes } from ${JSON.stringify(blocksFrom)};`] : []),
+    ...(settingsFrom ? [`import { themeSettings } from ${JSON.stringify(settingsFrom)};`] : []),
+    // RFC-0021 §1: the theme's DESIGN.md, as text.
+    ...(themeDesign ? ['import themeDesign from "./theme-design.ts";'] : []),
+    "",
+    "// The scheduler's Durable Object clock (RFC-0008 §8.3), declared by every deploy.",
+    'export { SchedulerClock } from "@cloudhal/cloudflare/admin";',
+    "// Build rooms for Studio's Build view (RFC-0020 §6), declared by every deploy.",
+    'export { BuildRoom } from "@cloudhal/cloudflare/admin";',
+    "",
+    `export default createAdminWorker({ ${options.join(", ")} });`,
+    "",
+  ].join("\n");
+}
+
+export async function prepareAdminWorker(options   
+                     
+                  
+                         
+                                                                                                    
+                              
+                                                                
+                                          
+                                                                                             
+                                                                                    
+                                           
+                    
+                                 
+                                                             
+                              
+                                                                           
+                                              
+                                                                   
+                                            
+                                                                                                
+                                          
+                                                                           
+                                              
+                                                                                 
+                                    
+                                                         
+                           
+                                                           
+                                
+                                                                                    
+                                  
+                                                                           
+                                     
+                                                                             
+                                   
+                                         
+                                                      
+                                              
+                                  
+ )                         {
+  const dir = path.join(options.projectDir, options.dataDir, "deploy", "admin");
+  await mkdir(dir, { recursive: true });
+  const skills = options.skillsDir ? await readSkillSources(options.skillsDir) : [];
+  await writeFile(
+    path.join(dir, "skills.ts"),
+    `// Generated by \`cloudhal deploy\` from ${options.skillsDir ?? "(no skills)"}.\nexport default ${JSON.stringify(skills, null, 2)};\n`,
+  );
+  if (options.themeDesign)
+    await writeFile(
+      path.join(dir, "theme-design.ts"),
+      `// Generated by \`cloudhal deploy\` from the theme's src/DESIGN.md.\nexport default ${JSON.stringify(options.themeDesign)};\n`,
+    );
+  await writeFile(
+    path.join(dir, "worker.ts"),
+    adminEntry(
+      options.blockTypes
+        ? path.relative(dir, options.blockTypes).split(path.sep).join("/")
+        : undefined,
+      options.themeSettings
+        ? path.relative(dir, options.themeSettings).split(path.sep).join("/")
+        : undefined,
+      options.themeDesign !== undefined,
+    ),
+  );
+  const configPath = path.join(dir, "wrangler.jsonc");
+  const existing = await readExistingIds(configPath);
+  await writeWranglerConfig(
+    configPath,
+    adminWorkerConfig({
+      ...existing,
+      ...options.names,
+      ...(options.siteId ? { siteId: options.siteId } : {}),
+      ...(options.siteIds ? { siteIds: options.siteIds } : {}),
+      ...(options.siteWorkers?.length ? { siteWorkers: options.siteWorkers } : {}),
+      main: "./worker.ts",
+      studioDir: path.relative(dir, options.studioDir) || ".",
+      ...(options.domain ? { domain: options.domain } : {}),
+      ...(options.analytics ? { analytics: options.analytics } : {}),
+      ...(options.comments ? { comments: options.comments } : {}),
+      ...(options.scheduler ? { scheduler: options.scheduler } : {}),
+      ...(options.schedules ? { schedules: options.schedules } : {}),
+      ...(options.mail ? { mail: options.mail } : {}),
+      ...(options.ai ? { ai: true } : {}),
+      ...(options.browser ? { browser: true } : {}),
+      ...(options.observability ? { observability: options.observability } : {}),
+      ...(options.placement ? { placement: options.placement } : {}),
+    }),
+    "Cloudhal admin Worker (API, auth, MCP, Studio)",
+  );
+  return { dir, configPath };
+}

package/dist/src/cloudflare/build.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Builds the project's Site Worker (`CLOUDHAL_TARGET=cloudflare astro build`). Output:
+ * `dist/server/wrangler.json` (+ `entry.mjs`) and `dist/client` (static assets).
+ */
+export declare function buildSiteWorker(projectDir: string, log?: (line: string) => void): Promise<string>;

package/dist/src/cloudflare/build.js

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Builds the project's Site Worker (`CLOUDHAL_TARGET=cloudflare astro build`). Output:
+ * `dist/server/wrangler.json` (+ `entry.mjs`) and `dist/client` (static assets).
+ */
+export async function buildSiteWorker(
+  projectDir        ,
+  log                         = () => {},
+)                  {
+  const require = createRequire(path.join(projectDir, "package.json"));
+  const astroBin = path.join(path.dirname(require.resolve("astro/package.json")), "bin/astro.mjs");
+  const { VITEST: _v, NODE_ENV: _n, ...env } = process.env;
+  await new Promise      ((resolve, reject) => {
+    const child = spawn(process.execPath, [astroBin, "build"], {
+      cwd: projectDir,
+      env: { ...env, CLOUDHAL_TARGET: "cloudflare" },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    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("exit", (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`astro build failed (${code}):\n${output.slice(-4000)}`)),
+    );
+  });
+  return path.join(projectDir, "dist/server/wrangler.json");
+}