@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.6

package/bin/chunks/chunk-B5I45LFD.js

@@ -0,0 +1,619 @@
+import {
+  cancelSite,
+  deploySite,
+  importFeedback,
+  previewSite,
+  refineAmend,
+  refinePrepare,
+  refineSite,
+  refineVerify,
+  resumeSite,
+  runDoctor,
+  shareSite,
+  synthesizeSite
+} from "./chunk-42IXFXUD.js";
+import {
+  verifySite
+} from "./chunk-VH7PM7KJ.js";
+import {
+  upgradeSite
+} from "./chunk-7VLBEAFW.js";
+import {
+  createSite
+} from "./chunk-4DM5TTLG.js";
+import {
+  explainStage
+} from "./chunk-CBEJZO4L.js";
+import {
+  runSite,
+  statusSite,
+  workflowArgvFromFlags
+} from "./chunk-FYN4T4SV.js";
+import {
+  EXIT_CODES
+} from "./chunk-JCRGE6AL.js";
+import {
+  siteInputsFromFlags
+} from "./chunk-3CTBXY5K.js";
+import {
+  buildVerified
+} from "./chunk-E5Y46VBX.js";
+import {
+  approvedOrigin,
+  inspectForms,
+  safeId,
+  validateFormConfig
+} from "./chunk-4GZCAWWK.js";
+import {
+  findHarnessRoot
+} from "./chunk-HNORQ74T.js";
+import {
+  files
+} from "./chunk-T6PE4KN4.js";
+
+// src/cli/index.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// src/cli/events.ts
+var EventStream = class {
+  mode;
+  events = [];
+  constructor(mode = "text") {
+    this.mode = mode;
+  }
+  getMode() {
+    return this.mode;
+  }
+  emit(event) {
+    const fullEvent = {
+      ...event,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.events.push(fullEvent);
+    if (this.mode === "events") {
+      process.stdout.write(JSON.stringify(fullEvent) + "\n");
+    } else if (this.mode === "text") {
+      if (event.type === "error") {
+        console.error(typeof event.data === "string" ? event.data : JSON.stringify(event.data));
+      } else if (event.type === "log" && typeof event.data === "string") {
+        console.log(event.data);
+      }
+    }
+  }
+  log(message) {
+    this.emit({ type: "log", data: message });
+  }
+  error(message) {
+    this.emit({ type: "error", data: message });
+  }
+  status(status) {
+    this.emit({ type: "status", data: status });
+  }
+  finish(result) {
+    this.emit({ type: "result", data: result });
+    if (this.mode === "json") {
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    } else if (this.mode === "text") {
+      if (!result.ok && result.error) {
+        console.error(`Error: ${result.error}`);
+      }
+      if (result.summary) {
+        console.log(result.summary);
+      }
+    }
+  }
+};
+function determineOutputMode(flags) {
+  if (flags.json && flags.events) {
+    const err = new Error("--json and --events flags are mutually exclusive");
+    err.exitCode = EXIT_CODES.CONFIG_OR_CLI_ERROR;
+    throw err;
+  }
+  if (flags.json) return "json";
+  if (flags.events) return "events";
+  return "text";
+}
+
+// src/cli/forms.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+// src/forms/cloudflare.ts
+async function cloudflareRequest(access, path, method = "GET", body) {
+  const response = await fetch(`https://api.cloudflare.com/client/v4${path}`, { method, headers: { authorization: `Bearer ${access.token}`, "content-type": "application/json" }, signal: AbortSignal.timeout(15e3), ...body === void 0 ? {} : { body: JSON.stringify(body) } });
+  const result = await response.json();
+  if (!response.ok || !result.success) throw new Error(`Cloudflare ${method} ${path}: HTTP ${response.status}; codes ${(result.errors || []).map((e) => e.code).join(",")}. Check scoped token permissions.`);
+  return result.result;
+}
+async function listWidgets(access) {
+  const result = [];
+  for (let page = 1; page <= 20; page++) {
+    const rows = await cloudflareRequest(access, `/accounts/${access.account}/challenges/widgets?page=${page}&per_page=100`);
+    result.push(...rows.map((w) => ({ sitekey: w.sitekey, name: w.name, domains: w.domains })));
+    if (rows.length < 100) return result;
+  }
+  throw new Error("Widget pagination limit reached");
+}
+function allocateWidget(widgets, hostnames) {
+  const hosts = [...new Set(hostnames)].sort();
+  if (!hosts.length || hosts.length > 10 || hosts.some((h) => h.includes("*") || h.includes("/") || !h)) throw new Error("One to ten exact widget hostnames required");
+  const managed = widgets.filter((w) => /^vitris-forms-pool-\d+$/.test(w.name));
+  const existing = managed.find((w) => hosts.every((h) => w.domains.includes(h))) || managed.find((w) => (/* @__PURE__ */ new Set([...w.domains, ...hosts])).size <= 10);
+  if (existing) return { widget: existing, name: existing.name, domains: [.../* @__PURE__ */ new Set([...existing.domains, ...hosts])].sort() };
+  if (widgets.length >= 20) throw new Error("Free Turnstile widget capacity exhausted (20/account, 10 hostnames/widget). Arrange Enterprise limits or release reviewed unused capacity.");
+  let n = 1;
+  while (widgets.some((w) => w.name === `vitris-forms-pool-${n}`)) n++;
+  return { name: `vitris-forms-pool-${n}`, domains: hosts };
+}
+async function reconcileWidget(access, hostnames, apply) {
+  try {
+    await cloudflareRequest(access, "/user/tokens/verify");
+  } catch {
+    await cloudflareRequest(access, `/accounts/${access.account}/tokens/verify`);
+  }
+  const plan = allocateWidget(await listWidgets(access), hostnames);
+  if (!apply) return { sitekey: plan.widget?.sitekey, plan };
+  let widget;
+  if (!plan.widget) widget = await cloudflareRequest(access, `/accounts/${access.account}/challenges/widgets`, "POST", { name: plan.name, domains: plan.domains, mode: "managed", bot_fight_mode: false, clearance_level: "no_clearance" });
+  else if (JSON.stringify([...plan.widget.domains].sort()) !== JSON.stringify(plan.domains)) widget = await cloudflareRequest(access, `/accounts/${access.account}/challenges/widgets/${plan.widget.sitekey}`, "PUT", { name: plan.name, domains: plan.domains, mode: "managed", bot_fight_mode: false, clearance_level: "no_clearance" });
+  else widget = plan.widget;
+  return { sitekey: widget.sitekey, secretRef: `pool_${widget.sitekey}`, plan };
+}
+function validateSecretMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.entries(value).some(([key, secret]) => !safeId(key) || typeof secret !== "string" || !secret || secret.length > 200)) throw new Error("Expected complete Turnstile secret map with named nonempty string values");
+  return { ...value };
+}
+async function provisionWidgetSecrets(access, worker, existing) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(worker)) throw new Error("Invalid Worker name");
+  const secrets = validateSecretMap(existing);
+  const managed = (await listWidgets(access)).filter((w) => /^vitris-forms-pool-\d+$/.test(w.name));
+  for (const w of managed) {
+    const details = await cloudflareRequest(access, `/accounts/${access.account}/challenges/widgets/${w.sitekey}`);
+    if (!details.secret) throw new Error("Turnstile secret unavailable");
+    secrets[`pool_${w.sitekey}`] = details.secret;
+  }
+  await cloudflareRequest(access, `/accounts/${access.account}/workers/scripts/${worker}/secrets`, "PUT", { name: "FORMS_TURNSTILE_SECRETS", type: "secret_text", text: JSON.stringify(secrets) });
+}
+
+// src/cli/forms.ts
+async function formsCommand(command, opts) {
+  try {
+    const root = resolve(opts.site || "."), launchPath = join(root, "launch.json");
+    const launch = existsSync(launchPath) ? JSON.parse(readFileSync(launchPath, "utf8")) : {};
+    const backend = opts.backendOrigin || launch.backendOrigin, tenant = opts.tenant;
+    const backendRequest = async (method, body) => {
+      const adminToken = process.env.VITRIS_FORMS_SETUP_TOKEN;
+      if (!backend || !safeId(tenant) || !adminToken) throw new Error("Provide --tenant, --backend-origin and VITRIS_FORMS_SETUP_TOKEN (scoped to this tenant)");
+      approvedOrigin(backend);
+      const response = await fetch(`${backend}/api/forms/${tenant}`, { method, headers: { authorization: `Bearer ${adminToken}`, "content-type": "application/json" }, ...body ? { body: JSON.stringify(body) } : {}, signal: AbortSignal.timeout(15e3) });
+      const data = await response.json();
+      if (!response.ok) throw new Error(`Forms backend HTTP ${response.status}: ${JSON.stringify(data)}`);
+      return data;
+    };
+    if (command === "status") return { ok: true, exitCode: 0, data: await backendRequest("GET"), summary: "Server-side form readiness and notification status retrieved" };
+    if (!["inspect", "setup"].includes(command)) throw new Error("Use vitris forms inspect|setup|status");
+    await buildVerified(root);
+    const inventory = files(join(root, "dist")).filter((f) => f.endsWith(".html") && !f.endsWith("404.html")).flatMap((file) => {
+      const rel = file.slice(join(root, "dist").length + 1).replaceAll("\\", "/");
+      const pagePath = rel === "index.html" ? "/" : "/" + rel.replace(/\/index\.html$/, "").replace(/\.html$/, "");
+      return inspectForms(readFileSync(file, "utf8")).map((form) => ({ pagePath, ...form }));
+    });
+    if (command === "inspect") return { ok: true, exitCode: 0, data: { inventory }, summary: "Contact-form inventory (unsupported and unrelated forms included)" };
+    if (!safeId(tenant) || !backend) throw new Error("Setup requires --tenant and --backend-origin");
+    approvedOrigin(backend);
+    const origins = opts.origins || [];
+    origins.forEach(approvedOrigin);
+    const eligible = inventory.filter((f) => f.eligible);
+    if (!eligible.length || eligible.some((f) => f.unsupported.length)) throw new Error("No supported contact forms. Run forms inspect and adapt unsupported controls.");
+    if (opts.mode === "live") throw new Error("Setup prepares disabled/test forms only. Live activation requires the reviewed tenant-scoped configuration API and server readiness.");
+    const supplied = opts.config ? JSON.parse(readFileSync(resolve(opts.config), "utf8")) : void 0;
+    const apply = !!opts.apply && !opts.dryRun;
+    let sitekey = opts.testKeys ? "1x00000000000000000000AA" : "pending", secretRef = opts.testKeys ? "test" : "pending";
+    let widgetPlan;
+    let cloudAccess;
+    let existingSecrets;
+    if (opts.cloudflare) {
+      const access = { account: process.env.CLOUDFLARE_ACCOUNT_ID || "", token: process.env.CLOUDFLARE_API_TOKEN || "" };
+      if (!access.account || !access.token) throw new Error("Cloudflare account/token required");
+      if (apply && (!opts.worker || !process.env.FORMS_TURNSTILE_SECRETS)) throw new Error("For secret reconciliation provide --worker and FORMS_TURNSTILE_SECRETS containing the current complete map ({} for a new isolated Worker)");
+      if (apply) existingSecrets = validateSecretMap(JSON.parse(process.env.FORMS_TURNSTILE_SECRETS));
+      const result = await reconcileWidget(access, origins.map((o) => new URL(o).hostname), false);
+      widgetPlan = result.plan;
+      cloudAccess = access;
+      sitekey = result.sitekey || sitekey;
+      secretRef = result.secretRef || (result.sitekey ? `pool_${result.sitekey}` : secretRef);
+    }
+    const forms = [], publicForms = [];
+    for (const f of eligible) {
+      const explicit = supplied?.forms.find((c) => c.pagePath === f.pagePath && (c.index ?? 0) === f.index);
+      const prior = launch.forms?.find((c) => c.pagePath === f.pagePath && (c.index ?? 0) === f.index);
+      const id = explicit?.id || prior?.id || `${tenant.slice(0, 40)}_${(f.pagePath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_|_$/g, "") || "root").slice(0, 20)}_${createHash("sha256").update(f.pagePath).digest("hex").slice(0, 8)}_${f.index}`;
+      const config = validateFormConfig(explicit || { id, mode: opts.mode || "disabled", origins, fields: f.fields, recipients: opts.recipients || [], turnstile: { sitekey, secretRef, action: opts.testKeys ? "test" : "contact" } });
+      if (config.mode === "live") throw new Error("Setup cannot activate live forms");
+      const actual = new Set(f.fields.map((field) => field.name));
+      if (actual.size !== config.fields.length || config.fields.some((field) => !actual.has(field.name))) throw new Error("Configured schema must include every captured field");
+      if (config.fields.some((field) => {
+        const authored = f.fields.find((a) => a.name === field.name);
+        return field.type !== authored.type || authored.required && !field.required || authored.options?.some((o) => !field.options?.includes(o));
+      })) throw new Error("Configured schema must preserve control types, required fields and authored choices");
+      forms.push(config);
+      publicForms.push({ id: config.id, pagePath: f.pagePath, index: f.index, sitekey: config.turnstile.sitekey, action: config.turnstile.action });
+    }
+    const plan = { tenant, backendOrigin: backend, forms, publicForms, widgetPlan, requirements: ["Tenant-scoped setup token", "Turnstile secrets on backend", "FORMS_ABUSE_SECRET", ...opts.testKeys ? ["Dummy keys require a controlled hostname/action verification fixture; use a real widget in test mode for manual end-to-end acceptance"] : [], "For live: approved recipients, authenticated Vitris sender and FORMS_EMAIL binding"] };
+    mkdirSync(join(root, "artifacts/forms"), { recursive: true });
+    writeFileSync(join(root, "artifacts/forms/setup-plan.json"), JSON.stringify(plan, null, 2) + "\n");
+    if (apply) {
+      if (cloudAccess) {
+        await backendRequest("GET");
+        const widget = await reconcileWidget(cloudAccess, origins.map((o) => new URL(o).hostname), true);
+        await provisionWidgetSecrets(cloudAccess, opts.worker, existingSecrets);
+        sitekey = widget.sitekey;
+        secretRef = widget.secretRef;
+        for (const form of forms) {
+          form.turnstile.sitekey = sitekey;
+          form.turnstile.secretRef = secretRef;
+        }
+        for (const binding of publicForms) binding.sitekey = sitekey;
+        plan.widgetPlan = widget.plan;
+        writeFileSync(join(root, "artifacts/forms/setup-plan.json"), JSON.stringify(plan, null, 2) + "\n");
+      }
+      if (sitekey === "pending" && !supplied) throw new Error("Provide --test-keys, --cloudflare, or explicit --forms-config");
+      await backendRequest("POST", { tenant: { slug: launch.slug || tenant, name: launch.name || tenant }, forms });
+      writeFileSync(launchPath, JSON.stringify({ ...launch, backendOrigin: backend, forms: publicForms }, null, 2) + "\n");
+      await buildVerified(root);
+      return { ok: true, exitCode: 0, data: { ...plan, status: await backendRequest("GET") }, summary: "Registered forms and connected frontend; review status before live activation" };
+    }
+    return { ok: true, exitCode: 0, data: plan, summary: "Prepared setup plan; use --apply to reconcile isolated/test resources" };
+  } catch (error) {
+    return { ok: false, exitCode: EXIT_CODES.CONFIG_OR_CLI_ERROR, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// src/cli/index.ts
+function parseArgs(args) {
+  const command = [];
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (key.includes("=")) {
+        const [k, ...v] = key.split("=");
+        flags[k] = v.join("=");
+      } else {
+        const next = args[i + 1];
+        if (next !== void 0 && !next.startsWith("-")) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg.slice(1);
+      const next = args[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      command.push(arg);
+    }
+    i++;
+  }
+  return { command, flags };
+}
+function resolvePrecedence(flags, siteRoot) {
+  const merged = {};
+  if (siteRoot && existsSync2(resolve2(siteRoot, "launch.json"))) {
+    try {
+      const launch = JSON.parse(readFileSync2(resolve2(siteRoot, "launch.json"), "utf8"));
+      if (typeof launch.ownerEmail === "string") merged.owner = launch.ownerEmail;
+      if (typeof launch.slug === "string") merged.slug = launch.slug;
+      if (typeof launch.name === "string") merged.name = launch.name;
+    } catch {
+    }
+  }
+  if (flags.config && typeof flags.config === "string") {
+    try {
+      const configPath = resolve2(flags.config);
+      if (existsSync2(configPath)) {
+        const cfg = JSON.parse(readFileSync2(configPath, "utf8"));
+        for (const [k, v] of Object.entries(cfg)) {
+          if (typeof v === "string" || typeof v === "boolean") merged[k] = v;
+        }
+      }
+    } catch {
+    }
+  }
+  if (process.env.VITRIS_SITE) merged.site = process.env.VITRIS_SITE;
+  if (process.env.VITRIS_ADAPTER) merged.adapter = process.env.VITRIS_ADAPTER;
+  if (process.env.VITRIS_MODEL) merged.model = process.env.VITRIS_MODEL;
+  if (process.env.CLOUDFLARE_API_TOKEN) merged.cloudflareApiToken = process.env.CLOUDFLARE_API_TOKEN;
+  if (process.env.CLOUDFLARE_ACCOUNT_ID) merged.cloudflareAccountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  for (const [k, v] of Object.entries(flags)) {
+    merged[k] = v;
+  }
+  return merged;
+}
+async function runCli(argv) {
+  const { command, flags } = parseArgs(argv);
+  let outputMode;
+  try {
+    outputMode = determineOutputMode({
+      json: !!flags.json,
+      events: !!flags.events
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return EXIT_CODES.CONFIG_OR_CLI_ERROR;
+  }
+  const stream = new EventStream(outputMode);
+  if (flags.version || flags.v) {
+    stream.log(`@tryvitris/website-harness v${JSON.parse(readFileSync2(resolve2(findHarnessRoot(), "package.json"), "utf8")).version}`);
+    return EXIT_CODES.SUCCESS;
+  }
+  if (flags.help || flags.h || command.length === 0) {
+    const help = `Vitris \uFFFD agent harness for building and verifying websites
+
+Usage: vitris <command> [options]
+
+Commands:
+  forms inspect|setup|status            Inventory, provision, and check contact forms
+  doctor                                Check environment, dependencies, and site health
+  site create --dir DIR --slug SLUG    Scaffold a new customer site repo (--from URL or --blank)
+  run                                   Execute single-variant, --creative, or 5-variant run
+  refine --request "..."                Refine an existing site with classified scope
+  refine prepare --request "..."        Analyze impact, capture baseline, and stage a refinement
+  refine amend --request-id ID --scope direction,business --reason "..."   Expand classification, retaining baseline
+  refine verify [--request-id ID]       Verify refinement impact across facts, links, slots, and layout
+  status [--run ID]                     Check current execution and lock status
+  resume [--run ID]                     Resume an interrupted workflow or design run
+  cancel [--run ID]                     Gracefully cancel an active run PID and release locks
+  feedback import --file FILE           Import structured comparison feedback for a design run
+  synthesize [--feedback FILE]          Synthesize candidate directions into final representative
+  verify                                Verify compilation and evaluate all quality gates
+  preview [--port PORT]                 Serve local verified dist preview
+  deploy [--provider cloudflare]        Deploy site to Cloudflare Pages with smoke verification
+  cloudflare [doctor|whoami|login]      Cloudflare credentials and permissions diagnostics
+  share [--run ID]                      Start local preview or design comparison review share
+  knowledge explain --stage STAGE       Show the knowledge that stage would load. No model call.
+
+Options:
+  --mode redesign|preserve               New site workflow (default: redesign)
+  --harness SPEC                        Starter dependency version, tarball, or file: path
+  --template ID                         Catalog template ID, name, or hosted URL; continue automatically
+  --template-release RELEASE            Optional template revision
+  --content TEXT                        Additional business content or instructions
+  --content-file FILE                   UTF-8 content file (instead of --content)
+  --backend-origin URL                  Backend origin for a new site
+  --site DIR                            Site directory path (default: current directory)
+  --json                                Output single structured JSON result at completion
+  --events                              Stream newline-delimited JSON (NDJSON) events
+  --dry-run                             Validate inputs and environment without making changes
+`;
+    stream.log(help);
+    return EXIT_CODES.SUCCESS;
+  }
+  const siteRoot = typeof flags.site === "string" ? flags.site : void 0;
+  const opts = resolvePrecedence(flags, siteRoot);
+  const dryRun = !!flags["dry-run"] || !!flags.dryRun;
+  const abortController = new AbortController();
+  const onSig = () => {
+    abortController.abort();
+  };
+  process.on("SIGINT", onSig);
+  process.on("SIGTERM", onSig);
+  const primary = command[0];
+  const secondary = command[1];
+  let result;
+  try {
+    if (primary === "forms") {
+      const list = (name) => typeof opts[name] === "string" ? opts[name].split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+      result = await formsCommand(secondary || "status", { site: siteRoot, tenant: typeof opts.tenant === "string" ? opts.tenant : void 0, backendOrigin: typeof opts["backend-origin"] === "string" ? opts["backend-origin"] : void 0, origins: list("origins"), recipients: list("recipients"), mode: typeof opts.mode === "string" ? opts.mode : void 0, apply: !!opts.apply, testKeys: !!opts["test-keys"], cloudflare: !!opts.cloudflare, worker: typeof opts.worker === "string" ? opts.worker : void 0, config: typeof opts["forms-config"] === "string" ? opts["forms-config"] : void 0, dryRun });
+    } else if (primary === "doctor") {
+      result = await runDoctor({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        provider: typeof opts.provider === "string" ? opts.provider : void 0,
+        dryRun
+      });
+    } else if (primary === "site" && secondary === "create") {
+      result = await createSite({
+        ...siteInputsFromFlags(opts),
+        dir: typeof opts.dir === "string" ? opts.dir : "",
+        slug: typeof opts.slug === "string" ? opts.slug : "",
+        name: typeof opts.name === "string" ? opts.name : void 0,
+        from: typeof opts.from === "string" ? opts.from : void 0,
+        mode: opts.mode,
+        blank: !!opts.blank,
+        owner: typeof opts.owner === "string" ? opts.owner : void 0,
+        backendOrigin: typeof opts["backend-origin"] === "string" ? opts["backend-origin"] : typeof opts["kernel-origin"] === "string" ? opts["kernel-origin"] : void 0,
+        harnessSpec: typeof opts.harness === "string" ? opts.harness : typeof opts.kernel === "string" ? opts.kernel : void 0,
+        force: !!opts.force,
+        dryRun
+      });
+    } else if (primary === "run") {
+      result = await runSite({
+        ...siteInputsFromFlags(opts),
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        variants: opts.variants !== void 0 ? String(opts.variants) : void 0,
+        creativeProfile: !!opts.creative,
+        adapter: typeof opts.adapter === "string" ? opts.adapter : void 0,
+        model: typeof opts.model === "string" ? opts.model : void 0,
+        theme: typeof opts.theme === "string" ? opts.theme : void 0,
+        themeScope: opts["theme-scope"] === "all" ? "all" : opts["theme-scope"] === "one" ? "one" : void 0,
+        restartFrom: typeof opts["restart-from"] === "string" ? opts["restart-from"] : void 0,
+        reason: typeof opts.reason === "string" ? opts.reason : void 0,
+        dryRun,
+        signal: abortController.signal,
+        onLog: (line) => stream.log(line),
+        workflowArgv: workflowArgvFromFlags(opts)
+      });
+    } else if (primary === "refine") {
+      if (secondary === "prepare") {
+        result = await refinePrepare({
+          site: typeof opts.site === "string" ? opts.site : void 0,
+          request: typeof opts.request === "string" ? opts.request : "",
+          scope: typeof opts.scope === "string" ? opts.scope : void 0,
+          requestId: typeof opts["request-id"] === "string" ? opts["request-id"] : typeof opts.requestId === "string" ? opts.requestId : void 0,
+          planFile: typeof opts.plan === "string" ? opts.plan : void 0,
+          dryRun
+        });
+      } else if (secondary === "amend") {
+        result = await refineAmend({ site: typeof opts.site === "string" ? opts.site : void 0, requestId: typeof opts["request-id"] === "string" ? opts["request-id"] : "", scope: typeof opts.scope === "string" ? opts.scope : "", reason: typeof opts.reason === "string" ? opts.reason : "", dryRun });
+      } else if (secondary === "verify") {
+        result = await refineVerify({
+          site: typeof opts.site === "string" ? opts.site : void 0,
+          requestId: typeof opts["request-id"] === "string" ? opts["request-id"] : typeof opts.requestId === "string" ? opts.requestId : void 0,
+          dryRun
+        });
+      } else {
+        result = await refineSite({
+          site: typeof opts.site === "string" ? opts.site : void 0,
+          request: typeof opts.request === "string" ? opts.request : "",
+          scope: typeof opts.scope === "string" ? opts.scope : void 0,
+          evidence: typeof opts.evidence === "string" ? opts.evidence : void 0,
+          dryRun,
+          signal: abortController.signal,
+          onLog: (line) => stream.log(line),
+          workflowArgv: workflowArgvFromFlags(opts)
+        });
+      }
+    } else if (primary === "upgrade") {
+      result = upgradeSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        target: typeof opts.target === "string" ? opts.target : void 0,
+        to: typeof opts.to === "string" ? opts.to : void 0,
+        apply: !!opts.apply,
+        rollback: !!opts.rollback,
+        recover: !!opts.recover
+      });
+    } else if (primary === "status") {
+      result = await statusSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0
+      });
+    } else if (primary === "resume") {
+      result = await resumeSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0,
+        dryRun,
+        signal: abortController.signal,
+        onLog: (line) => stream.log(line),
+        workflowArgv: workflowArgvFromFlags(opts)
+      });
+    } else if (primary === "cancel") {
+      result = await cancelSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0,
+        dryRun
+      });
+    } else if (primary === "feedback" && secondary === "import") {
+      result = await importFeedback({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0,
+        file: typeof opts.file === "string" ? opts.file : "",
+        dryRun
+      });
+    } else if (primary === "synthesize") {
+      result = await synthesizeSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0,
+        feedback: typeof opts.feedback === "string" ? opts.feedback : void 0,
+        dryRun,
+        onLog: (line) => stream.log(line)
+      });
+    } else if (primary === "verify") {
+      result = await verifySite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        remoteUrl: typeof opts.remote === "string" ? opts.remote : void 0,
+        dryRun
+      });
+    } else if (primary === "preview") {
+      result = await previewSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        port: opts.port ? Number(opts.port) : void 0,
+        dryRun,
+        wait: !dryRun && !flags["no-wait"],
+        signal: abortController.signal,
+        onLog: (line) => stream.log(line)
+      });
+    } else if (primary === "deploy") {
+      result = await deploySite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        provider: "cloudflare",
+        environment: opts.environment === "production" ? "production" : "preview",
+        branch: typeof opts.branch === "string" ? opts.branch : void 0,
+        dryRun,
+        signal: abortController.signal,
+        onLog: (line) => stream.log(line)
+      });
+    } else if (primary === "cloudflare") {
+      const sub = secondary || "doctor";
+      if (sub === "doctor") {
+        result = await runDoctor({ provider: "cloudflare", operation: "pages" });
+      } else if (sub === "whoami") {
+        const probe = spawnSync(process.platform === "win32" ? "npx.cmd" : "npx", ["wrangler", "whoami"], { encoding: "utf8" });
+        result = {
+          ok: probe.status === 0,
+          exitCode: probe.status === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.CONFIG_OR_CLI_ERROR,
+          summary: probe.stdout || probe.stderr
+        };
+      } else if (sub === "login") {
+        const probe = spawnSync(process.platform === "win32" ? "npx.cmd" : "npx", ["wrangler", "login"], { stdio: "inherit" });
+        result = {
+          ok: probe.status === 0,
+          exitCode: probe.status === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR,
+          summary: probe.status === 0 ? "Wrangler login completed" : "Wrangler login failed"
+        };
+      } else {
+        result = {
+          ok: false,
+          exitCode: EXIT_CODES.CONFIG_OR_CLI_ERROR,
+          error: `Unknown cloudflare subcommand: ${sub}. Supported: doctor, whoami, login`
+        };
+      }
+    } else if (primary === "knowledge" && secondary === "explain") {
+      const explained = explainStage(resolve2(typeof opts.site === "string" ? opts.site : "."), typeof opts.stage === "string" ? opts.stage : "direction");
+      result = { ok: true, exitCode: EXIT_CODES.SUCCESS, summary: explained.text, data: explained };
+    } else if (primary === "share") {
+      result = await shareSite({
+        site: typeof opts.site === "string" ? opts.site : void 0,
+        runId: typeof opts.run === "string" ? opts.run : void 0,
+        port: opts.port ? Number(opts.port) : void 0,
+        dryRun,
+        tunnel: !!flags.tunnel || !!flags["quick-tunnel"],
+        wait: !dryRun && !flags["no-wait"],
+        signal: abortController.signal,
+        onLog: (line) => stream.log(line)
+      });
+    } else {
+      result = {
+        ok: false,
+        exitCode: EXIT_CODES.CONFIG_OR_CLI_ERROR,
+        error: `Unknown command: ${command.join(" ")}. Run 'vitris --help' for usage.`
+      };
+    }
+  } catch (err) {
+    result = {
+      ok: false,
+      exitCode: err.exitCode || EXIT_CODES.GENERIC_ERROR,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  } finally {
+    process.off("SIGINT", onSig);
+    process.off("SIGTERM", onSig);
+  }
+  stream.finish(result);
+  return result.exitCode;
+}
+
+export {
+  runCli
+};