@scenar/cli 0.1.20 → 0.2.0

package/src/pack/run-pack.ts

@@ -0,0 +1,163 @@
+import { resolve, join, basename } from "node:path";
+import { stat, mkdir, writeFile, rm, readdir, copyFile, access } from "node:fs/promises";
+import { detectRenderExport } from "../render/detect-render-export.js";
+import { resolveProvidersPath } from "../render/resolve-providers.js";
+import { generateEmbedEntry, generateEmbedHtml } from "./generate-embed-entry.js";
+import { runViteBuild } from "./build.js";
+import {
+  buildPackManifest,
+  writePackManifest,
+  writeScenarioJson,
+  verifyManifestFilesExist,
+  type PackManifest,
+} from "./pack-manifest.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+
+/** Generator version stamped into scenario.json (kept in sync with the CLI). */
+const PACK_GENERATOR_VERSION = "0.0.1";
+
+/** Options for {@link runPack}. Paths may be relative; they are resolved here. */
+export interface RunPackOptions {
+  /** Path to a scenario directory (must contain steps.ts + a renderStep export). */
+  readonly scenarioDir: string;
+  /** Output directory for the bundle (default: ./<scenario-id>-bundle). */
+  readonly outDir?: string;
+  /** Canonical viewport width in px (default: {@link DEFAULT_VIEWPORT}.width). */
+  readonly width?: number;
+  /** Shell/container height in px (default: {@link DEFAULT_VIEWPORT}.height). */
+  readonly shellHeight?: number;
+  /** Keep the generated entry directory for debugging (default: false). */
+  readonly keepTemp?: boolean;
+  /** Progress sink for mid-operation messages. */
+  readonly onLog?: (message: string) => void;
+}
+
+/** The outcome of a successful pack. */
+export interface PackResult {
+  readonly scenarioId: string;
+  readonly outDir: string;
+  readonly renderFilePath: string;
+  readonly providersPath: string | null;
+  readonly hasNarration: boolean;
+  readonly manifest: PackManifest;
+  readonly totalBytes: number;
+}
+
+/**
+ * Bundle a scenario directory into a self-contained, hosted embed — the pure
+ * orchestration behind `scenar pack`, with no process/exit coupling so both the
+ * CLI command and the MCP server can call it. Throws on any failure (invalid
+ * directory, bundler error, allowlist violation); the caller formats it.
+ */
+export async function runPack(options: RunPackOptions): Promise<PackResult> {
+  const onLog = options.onLog ?? (() => {});
+  const scenarioDir = resolve(options.scenarioDir);
+
+  const info = await stat(scenarioDir).catch(() => null);
+  if (!info) {
+    throw new Error(`${options.scenarioDir} does not exist.`);
+  }
+  if (!info.isDirectory()) {
+    throw new Error(
+      `${options.scenarioDir} is not a directory. ` +
+        "The pack command requires a scenario directory (with steps.ts).",
+    );
+  }
+
+  const scenarioId = basename(scenarioDir);
+  const outDir = options.outDir ? resolve(options.outDir) : resolve(`./${scenarioId}-bundle`);
+  const width = options.width ?? DEFAULT_VIEWPORT.width;
+  const shellHeight = options.shellHeight ?? DEFAULT_VIEWPORT.height;
+
+  // The entry must live inside the scenario directory so the bundler's
+  // node_modules resolution walks up into the consumer project.
+  const tempDir = join(scenarioDir, ".scenar-pack");
+
+  try {
+    const renderFilePath = await detectRenderExport(scenarioDir);
+    const providersPath = await resolveProvidersPath(scenarioDir);
+    const hasNarration = await fileExists(join(scenarioDir, "narration", "manifest.json"));
+
+    onLog(`Scenario:  ${scenarioId}`);
+    onLog(`Render:    ${renderFilePath}`);
+    onLog(`Providers: ${providersPath ?? "none"}`);
+    onLog(`Narration: ${hasNarration ? "yes (manifest found)" : "none"}`);
+    onLog(`Output:    ${outDir}`);
+
+    // 1. Generate the browser entry + index.html into the temp dir.
+    const entrySource = generateEmbedEntry({
+      scenarioDir,
+      renderFilePath,
+      scenarioId,
+      hasNarration,
+      providersPath,
+      canonicalWidth: width,
+      shellHeight,
+    });
+    await mkdir(tempDir, { recursive: true });
+    const entryFileName = "entry.tsx";
+    const entryHtmlPath = join(tempDir, "index.html");
+    await writeFile(join(tempDir, entryFileName), entrySource, "utf-8");
+    await writeFile(entryHtmlPath, generateEmbedHtml(scenarioId, entryFileName), "utf-8");
+
+    // 2. Build the static bundle with Vite.
+    onLog("Bundling embed with Vite...");
+    await runViteBuild({ root: tempDir, outDir, entryHtmlPath });
+
+    // 3. Copy the narration manifest + audio. The embed fetches
+    //    ./narration/manifest.json at runtime and resolves each clip's
+    //    relative src against it, so both must ship in the bundle.
+    if (hasNarration) {
+      await copyNarration(scenarioDir, outDir);
+    }
+
+    // 4. Write the required scenario.json descriptor, recording the canonical
+    //    viewport baked into the bundle so `deploy`/`serve`/`publish` can derive
+    //    a correctly-proportioned embed snippet (DD-004).
+    await writeScenarioJson(outDir, scenarioId, PACK_GENERATOR_VERSION, {
+      width,
+      height: shellHeight,
+    });
+
+    // 5. Compute + write the deploy-facing pack manifest (validates the bundle
+    //    against the backend allowlist; throws on any violation).
+    const manifest = await buildPackManifest(outDir, scenarioId);
+    await verifyManifestFilesExist(outDir, manifest);
+    await writePackManifest(outDir, manifest);
+
+    const totalBytes = manifest.files.reduce((sum, f) => sum + f.sizeBytes, 0);
+    return { scenarioId, outDir, renderFilePath, providersPath, hasNarration, manifest, totalBytes };
+  } finally {
+    if (!options.keepTemp) {
+      await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+/**
+ * Copy the narration manifest and every *.mp3 from <scenarioDir>/narration into
+ * <outDir>/narration. The manifest is the runtime index the embed fetches; the
+ * mp3s are the clips it references by relative src.
+ */
+async function copyNarration(scenarioDir: string, outDir: string): Promise<void> {
+  const srcDir = join(scenarioDir, "narration");
+  const destDir = join(outDir, "narration");
+  await mkdir(destDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const name = entry.name.toLowerCase();
+    if (name === "manifest.json" || name.endsWith(".mp3")) {
+      await copyFile(join(srcDir, entry.name), join(destDir, entry.name));
+    }
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/publish/github.d.ts

@@ -0,0 +1,11 @@
+import type { PublishFlowDeps } from "./publish-flow.js";
+/**
+ * The production {@link PublishFlowDeps} backed by the `gh` CLI and `git`. The
+ * `log` sink is supplied by the command; everything here shells out.
+ *
+ * Auth uses `gh` throughout: API calls go through `gh api`, and the git push
+ * borrows gh's credential helper (`gh auth git-credential`) for that one command
+ * only — so no token is ever placed on the command line or written to config.
+ */
+export declare function createGithubPublisher(): Omit<PublishFlowDeps, "log">;
+//# sourceMappingURL=github.d.ts.map

package/src/publish/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../src/publish/github.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAuCzD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,CAoKpE"}

package/src/publish/github.js

@@ -0,0 +1,197 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, mkdir, rm, cp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/** Run a command, capturing output. Never rejects on a non-zero exit code. */
+function run(file, args, cwd) {
+    return new Promise((resolvePromise) => {
+        execFile(file, args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+            const code = error && typeof error.code === "number"
+                ? error.code
+                : error
+                    ? 1
+                    : 0;
+            resolvePromise({ code, stdout: stdout.toString(), stderr: stderr.toString() });
+        });
+    });
+}
+/** Commit identity for the published snapshot (Pages ignores authorship). */
+const COMMIT_USER = "scenar-cli";
+const COMMIT_EMAIL = "scenar-cli@users.noreply.github.com";
+/**
+ * The branch GitHub Pages currently serves for owner/repo, or null if Pages is
+ * not enabled (the GET 404s, so `gh` exits non-zero). The authoritative state
+ * check that {@link createGithubPublisher}'s enablePages relies on.
+ */
+async function getPagesBranch(owner, repo) {
+    const result = await run("gh", ["api", `repos/${owner}/${repo}/pages`, "--jq", ".source.branch"]);
+    if (result.code !== 0)
+        return null;
+    const branch = result.stdout.trim();
+    return branch.length > 0 ? branch : null;
+}
+/**
+ * The production {@link PublishFlowDeps} backed by the `gh` CLI and `git`. The
+ * `log` sink is supplied by the command; everything here shells out.
+ *
+ * Auth uses `gh` throughout: API calls go through `gh api`, and the git push
+ * borrows gh's credential helper (`gh auth git-credential`) for that one command
+ * only — so no token is ever placed on the command line or written to config.
+ */
+export function createGithubPublisher() {
+    return {
+        async ensureToolsAvailable() {
+            const git = await run("git", ["--version"]);
+            if (git.code !== 0) {
+                throw new Error("git is not installed or not on PATH. Install git and retry.");
+            }
+            const gh = await run("gh", ["--version"]);
+            if (gh.code !== 0) {
+                throw new Error("the GitHub CLI (gh) is not installed. Install it from https://cli.github.com and retry.");
+            }
+            const auth = await run("gh", ["auth", "status"]);
+            if (auth.code !== 0) {
+                throw new Error("not authenticated with GitHub. Run `gh auth login` and retry.");
+            }
+        },
+        async resolveOwner(explicitOrg) {
+            if (explicitOrg)
+                return explicitOrg;
+            const result = await run("gh", ["api", "user", "--jq", ".login"]);
+            const login = result.stdout.trim();
+            if (result.code !== 0 || login.length === 0) {
+                throw new Error(`could not resolve your GitHub username via gh (${result.stderr.trim() || "no output"}).`);
+            }
+            return login;
+        },
+        async repoExists(owner, repo) {
+            const result = await run("gh", ["repo", "view", `${owner}/${repo}`, "--json", "name"]);
+            return result.code === 0;
+        },
+        async createRepo(owner, repo, opts) {
+            const visibility = opts.private ? "--private" : "--public";
+            const result = await run("gh", [
+                "repo",
+                "create",
+                `${owner}/${repo}`,
+                visibility,
+                "--description",
+                opts.description,
+            ]);
+            if (result.code !== 0) {
+                throw new Error(`failed to create ${owner}/${repo}: ${result.stderr.trim() || "unknown error"}`);
+            }
+        },
+        async pushBundleToPages({ bundleDir, owner, repo, path, message }) {
+            const workDir = await mkdtemp(join(tmpdir(), "scenar-publish-"));
+            // Borrow gh's credential helper for network git ops only; no token on argv.
+            const cred = ["-c", "credential.helper=!gh auth git-credential"];
+            const git = async (args) => {
+                const result = await run("git", args, workDir);
+                if (result.code !== 0) {
+                    throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || "unknown error"}`);
+                }
+                return result;
+            };
+            try {
+                // Stage in a throwaway repo so the user's bundle dir is never turned into
+                // a git repo.
+                const remote = `https://github.com/${owner}/${repo}.git`;
+                await git(["init", "-q"]);
+                await git(["remote", "add", "origin", remote]);
+                // Subdir publishes build on the existing branch so sibling tours survive;
+                // root publishes replace the whole branch (dedicated single-tour repo).
+                let basedOnExisting = false;
+                if (path) {
+                    const fetched = await run("git", [...cred, "fetch", "-q", "--depth=1", "origin", "gh-pages"], workDir);
+                    if (fetched.code === 0) {
+                        await git(["checkout", "-q", "-B", "gh-pages", "FETCH_HEAD"]);
+                        basedOnExisting = true;
+                    }
+                    else {
+                        await git(["checkout", "-q", "-b", "gh-pages"]);
+                    }
+                }
+                else {
+                    await git(["checkout", "-q", "-B", "gh-pages"]);
+                }
+                // Replace only the target subfolder (or the whole tree at root). The
+                // root .nojekyll makes Pages serve files verbatim (no Jekyll processing
+                // of underscore-prefixed paths, etc.).
+                const targetDir = path ? join(workDir, path) : workDir;
+                if (path) {
+                    await rm(targetDir, { recursive: true, force: true });
+                    await mkdir(dirname(targetDir), { recursive: true });
+                }
+                await cp(bundleDir, targetDir, { recursive: true });
+                await writeFile(join(workDir, ".nojekyll"), "", "utf-8");
+                await git(["add", "-A"]);
+                // Republishing identical content is a no-op — nothing to commit or push.
+                const status = await git(["status", "--porcelain"]);
+                if (status.stdout.trim().length === 0)
+                    return;
+                await git([
+                    "-c", `user.name=${COMMIT_USER}`,
+                    "-c", `user.email=${COMMIT_EMAIL}`,
+                    "commit", "-q", "-m", message,
+                ]);
+                // Fast-forward push when built on the fetched head; otherwise force
+                // (creating or replacing the branch wholesale).
+                const pushArgs = basedOnExisting
+                    ? [...cred, "push", "-q", "origin", "gh-pages"]
+                    : [...cred, "push", "-q", "-f", "origin", "gh-pages"];
+                const pushed = await run("git", pushArgs, workDir);
+                if (pushed.code !== 0) {
+                    throw new Error(`git push failed: ${pushed.stderr.trim() || "unknown error"}`);
+                }
+            }
+            finally {
+                await rm(workDir, { recursive: true, force: true }).catch(() => { });
+            }
+        },
+        async enablePages(owner, repo) {
+            // Verify state rather than trust POST's exit code. The Pages create
+            // endpoint can return an async 202 with an empty body, which makes
+            // `gh api` exit non-zero ("unexpected end of JSON input") even though the
+            // site was enabled. GET is the authoritative check and is naturally
+            // idempotent for re-publishes.
+            const current = await getPagesBranch(owner, repo);
+            if (current === "gh-pages")
+                return; // already pointed at our branch
+            if (current !== null) {
+                // Enabled, but from a different branch — repoint it.
+                const put = await run("gh", [
+                    "api",
+                    "-X",
+                    "PUT",
+                    `repos/${owner}/${repo}/pages`,
+                    "-f",
+                    "source[branch]=gh-pages",
+                    "-f",
+                    "source[path]=/",
+                ]);
+                if (put.code !== 0) {
+                    throw new Error(`failed to repoint GitHub Pages to gh-pages: ${put.stderr.trim() || "unknown error"}`);
+                }
+                return;
+            }
+            // Not enabled yet — create it, then confirm via GET (ignore the create's
+            // noisy exit/parse behaviour and rely on the observed state).
+            const post = await run("gh", [
+                "api",
+                "-X",
+                "POST",
+                `repos/${owner}/${repo}/pages`,
+                "-f",
+                "source[branch]=gh-pages",
+                "-f",
+                "source[path]=/",
+            ]);
+            const after = await getPagesBranch(owner, repo);
+            if (after !== null)
+                return;
+            throw new Error(`failed to enable GitHub Pages: ${post.stderr.trim() || "unknown error"}`);
+        },
+    };
+}
+//# sourceMappingURL=github.js.map

package/src/publish/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../../src/publish/github.ts"],"names":[],"mappings":"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"}

package/src/publish/github.ts

@@ -0,0 +1,216 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, mkdir, rm, cp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { PublishFlowDeps } from "./publish-flow.js";
+
+/** Result of running a child process without throwing on a non-zero exit. */
+interface RunResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Run a command, capturing output. Never rejects on a non-zero exit code. */
+function run(file: string, args: string[], cwd?: string): Promise<RunResult> {
+  return new Promise<RunResult>((resolvePromise) => {
+    execFile(file, args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      const code = error && typeof (error as { code?: unknown }).code === "number"
+        ? (error as { code: number }).code
+        : error
+          ? 1
+          : 0;
+      resolvePromise({ code, stdout: stdout.toString(), stderr: stderr.toString() });
+    });
+  });
+}
+
+/** Commit identity for the published snapshot (Pages ignores authorship). */
+const COMMIT_USER = "scenar-cli";
+const COMMIT_EMAIL = "scenar-cli@users.noreply.github.com";
+
+/**
+ * The branch GitHub Pages currently serves for owner/repo, or null if Pages is
+ * not enabled (the GET 404s, so `gh` exits non-zero). The authoritative state
+ * check that {@link createGithubPublisher}'s enablePages relies on.
+ */
+async function getPagesBranch(owner: string, repo: string): Promise<string | null> {
+  const result = await run("gh", ["api", `repos/${owner}/${repo}/pages`, "--jq", ".source.branch"]);
+  if (result.code !== 0) return null;
+  const branch = result.stdout.trim();
+  return branch.length > 0 ? branch : null;
+}
+
+/**
+ * The production {@link PublishFlowDeps} backed by the `gh` CLI and `git`. The
+ * `log` sink is supplied by the command; everything here shells out.
+ *
+ * Auth uses `gh` throughout: API calls go through `gh api`, and the git push
+ * borrows gh's credential helper (`gh auth git-credential`) for that one command
+ * only — so no token is ever placed on the command line or written to config.
+ */
+export function createGithubPublisher(): Omit<PublishFlowDeps, "log"> {
+  return {
+    async ensureToolsAvailable() {
+      const git = await run("git", ["--version"]);
+      if (git.code !== 0) {
+        throw new Error("git is not installed or not on PATH. Install git and retry.");
+      }
+      const gh = await run("gh", ["--version"]);
+      if (gh.code !== 0) {
+        throw new Error(
+          "the GitHub CLI (gh) is not installed. Install it from https://cli.github.com and retry.",
+        );
+      }
+      const auth = await run("gh", ["auth", "status"]);
+      if (auth.code !== 0) {
+        throw new Error("not authenticated with GitHub. Run `gh auth login` and retry.");
+      }
+    },
+
+    async resolveOwner(explicitOrg) {
+      if (explicitOrg) return explicitOrg;
+      const result = await run("gh", ["api", "user", "--jq", ".login"]);
+      const login = result.stdout.trim();
+      if (result.code !== 0 || login.length === 0) {
+        throw new Error(
+          `could not resolve your GitHub username via gh (${result.stderr.trim() || "no output"}).`,
+        );
+      }
+      return login;
+    },
+
+    async repoExists(owner, repo) {
+      const result = await run("gh", ["repo", "view", `${owner}/${repo}`, "--json", "name"]);
+      return result.code === 0;
+    },
+
+    async createRepo(owner, repo, opts) {
+      const visibility = opts.private ? "--private" : "--public";
+      const result = await run("gh", [
+        "repo",
+        "create",
+        `${owner}/${repo}`,
+        visibility,
+        "--description",
+        opts.description,
+      ]);
+      if (result.code !== 0) {
+        throw new Error(`failed to create ${owner}/${repo}: ${result.stderr.trim() || "unknown error"}`);
+      }
+    },
+
+    async pushBundleToPages({ bundleDir, owner, repo, path, message }) {
+      const workDir = await mkdtemp(join(tmpdir(), "scenar-publish-"));
+      // Borrow gh's credential helper for network git ops only; no token on argv.
+      const cred = ["-c", "credential.helper=!gh auth git-credential"];
+      const git = async (args: string[]) => {
+        const result = await run("git", args, workDir);
+        if (result.code !== 0) {
+          throw new Error(`git ${args.join(" ")} failed: ${result.stderr.trim() || "unknown error"}`);
+        }
+        return result;
+      };
+      try {
+        // Stage in a throwaway repo so the user's bundle dir is never turned into
+        // a git repo.
+        const remote = `https://github.com/${owner}/${repo}.git`;
+        await git(["init", "-q"]);
+        await git(["remote", "add", "origin", remote]);
+
+        // Subdir publishes build on the existing branch so sibling tours survive;
+        // root publishes replace the whole branch (dedicated single-tour repo).
+        let basedOnExisting = false;
+        if (path) {
+          const fetched = await run("git", [...cred, "fetch", "-q", "--depth=1", "origin", "gh-pages"], workDir);
+          if (fetched.code === 0) {
+            await git(["checkout", "-q", "-B", "gh-pages", "FETCH_HEAD"]);
+            basedOnExisting = true;
+          } else {
+            await git(["checkout", "-q", "-b", "gh-pages"]);
+          }
+        } else {
+          await git(["checkout", "-q", "-B", "gh-pages"]);
+        }
+
+        // Replace only the target subfolder (or the whole tree at root). The
+        // root .nojekyll makes Pages serve files verbatim (no Jekyll processing
+        // of underscore-prefixed paths, etc.).
+        const targetDir = path ? join(workDir, path) : workDir;
+        if (path) {
+          await rm(targetDir, { recursive: true, force: true });
+          await mkdir(dirname(targetDir), { recursive: true });
+        }
+        await cp(bundleDir, targetDir, { recursive: true });
+        await writeFile(join(workDir, ".nojekyll"), "", "utf-8");
+
+        await git(["add", "-A"]);
+
+        // Republishing identical content is a no-op — nothing to commit or push.
+        const status = await git(["status", "--porcelain"]);
+        if (status.stdout.trim().length === 0) return;
+
+        await git([
+          "-c", `user.name=${COMMIT_USER}`,
+          "-c", `user.email=${COMMIT_EMAIL}`,
+          "commit", "-q", "-m", message,
+        ]);
+
+        // Fast-forward push when built on the fetched head; otherwise force
+        // (creating or replacing the branch wholesale).
+        const pushArgs = basedOnExisting
+          ? [...cred, "push", "-q", "origin", "gh-pages"]
+          : [...cred, "push", "-q", "-f", "origin", "gh-pages"];
+        const pushed = await run("git", pushArgs, workDir);
+        if (pushed.code !== 0) {
+          throw new Error(`git push failed: ${pushed.stderr.trim() || "unknown error"}`);
+        }
+      } finally {
+        await rm(workDir, { recursive: true, force: true }).catch(() => {});
+      }
+    },
+
+    async enablePages(owner, repo) {
+      // Verify state rather than trust POST's exit code. The Pages create
+      // endpoint can return an async 202 with an empty body, which makes
+      // `gh api` exit non-zero ("unexpected end of JSON input") even though the
+      // site was enabled. GET is the authoritative check and is naturally
+      // idempotent for re-publishes.
+      const current = await getPagesBranch(owner, repo);
+      if (current === "gh-pages") return; // already pointed at our branch
+      if (current !== null) {
+        // Enabled, but from a different branch — repoint it.
+        const put = await run("gh", [
+          "api",
+          "-X",
+          "PUT",
+          `repos/${owner}/${repo}/pages`,
+          "-f",
+          "source[branch]=gh-pages",
+          "-f",
+          "source[path]=/",
+        ]);
+        if (put.code !== 0) {
+          throw new Error(`failed to repoint GitHub Pages to gh-pages: ${put.stderr.trim() || "unknown error"}`);
+        }
+        return;
+      }
+
+      // Not enabled yet — create it, then confirm via GET (ignore the create's
+      // noisy exit/parse behaviour and rely on the observed state).
+      const post = await run("gh", [
+        "api",
+        "-X",
+        "POST",
+        `repos/${owner}/${repo}/pages`,
+        "-f",
+        "source[branch]=gh-pages",
+        "-f",
+        "source[path]=/",
+      ]);
+      const after = await getPagesBranch(owner, repo);
+      if (after !== null) return;
+      throw new Error(`failed to enable GitHub Pages: ${post.stderr.trim() || "unknown error"}`);
+    },
+  };
+}