@scenar/cli 0.1.20 → 0.2.1

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"}`);
+    },
+  };
+}

package/src/publish/publish-flow.d.ts

@@ -0,0 +1,110 @@
+/**
+ * GitHub Pages publishing — the OSS "permanent public URL" path of Phase 1.
+ *
+ * The flow is dependency-injected (mirroring deploy-flow.ts) so its ordering and
+ * payloads are unit-testable against fakes, with zero live GitHub calls in the
+ * test suite. The real `gh`/`git` implementations live in ./github.ts.
+ */
+/** Identity for the target GitHub repository + how to write to it. */
+export interface PublishOptions {
+    /** The packed bundle directory to publish. */
+    readonly bundleDir: string;
+    /** Target repository name (default: the scenario slug). */
+    readonly repo: string;
+    /**
+     * Subdirectory within the repo to publish into, normalized (no leading/
+     * trailing slashes). Empty string means the repo root — a dedicated,
+     * single-tour repo whose every publish replaces the whole branch. A non-empty
+     * path (e.g. `welcome-tour`) lets many tours coexist in one repo; publishing
+     * replaces only that subfolder and preserves its siblings.
+     */
+    readonly path: string;
+    /** Target owner (a GitHub org); omitted means the authenticated user. */
+    readonly org?: string;
+    /** Create the repo private rather than public (Pages needs Pro for private). */
+    readonly private: boolean;
+    /** Commit message for the published snapshot. */
+    readonly message: string;
+}
+/** The published location. */
+export interface PublishResult {
+    readonly owner: string;
+    readonly repo: string;
+    /** The subdirectory the embed was published into ("" for the repo root). */
+    readonly path: string;
+    /** The repository's web URL. */
+    readonly repoUrl: string;
+    /** The GitHub Pages URL the embed is served at (includes the path). */
+    readonly pagesUrl: string;
+    /** True when the repo was created by this run (vs. reused). */
+    readonly created: boolean;
+}
+/**
+ * The side-effecting operations the flow depends on, injected so the ordering
+ * can be tested without `gh`, `git`, or the network.
+ */
+export interface PublishFlowDeps {
+    /** Verify `gh` + `git` are installed and `gh` is authenticated; else throw. */
+    ensureToolsAvailable(): Promise<void>;
+    /** Resolve the target owner: the explicit org, or the authenticated user. */
+    resolveOwner(explicitOrg: string | undefined): Promise<string>;
+    /** Whether owner/repo already exists. */
+    repoExists(owner: string, repo: string): Promise<boolean>;
+    /** Create owner/repo (public unless private requested). */
+    createRepo(owner: string, repo: string, opts: {
+        private: boolean;
+        description: string;
+    }): Promise<void>;
+    /**
+     * Publish the bundle (plus a root .nojekyll) to the repo's gh-pages branch.
+     * An empty `path` replaces the whole branch (dedicated repo); a non-empty
+     * `path` updates only that subfolder, preserving sibling tours already on the
+     * branch.
+     */
+    pushBundleToPages(input: {
+        bundleDir: string;
+        owner: string;
+        repo: string;
+        path: string;
+        message: string;
+    }): Promise<void>;
+    /** Enable GitHub Pages from gh-pages (idempotent — a no-op if already on). */
+    enablePages(owner: string, repo: string): Promise<void>;
+    /** Progress sink (stderr in the command; captured in tests). */
+    log(message: string): void;
+}
+/**
+ * Validate a GitHub repository name. Returns an error message, or null if valid.
+ * The scenario slug (the default) is always valid; this guards an explicit
+ * `--repo` before any repo is touched.
+ */
+export declare function validateRepoName(repo: string): string | null;
+/**
+ * Normalize a publish path to a clean, slash-separated subpath with no leading,
+ * trailing, or doubled slashes. `/`, `.`, and empty all normalize to "" (root).
+ */
+export declare function normalizePath(path: string | undefined): string;
+/**
+ * Validate a (pre-normalized) publish subpath. Returns an error message, or null
+ * if valid. "" (root) is always valid; each segment must be a safe slug and
+ * never `..` (no directory traversal into the branch).
+ */
+export declare function validatePublishPath(path: string): string | null;
+/**
+ * The GitHub Pages URL for owner/repo, optionally under a subpath. A repository
+ * named exactly `<owner>.github.io` is the user/org site and serves at the apex;
+ * every other repo serves under its name as a path (which is why packed bundles
+ * use a relative base so they work from a subpath). A non-empty `path` appends a
+ * further subdirectory so many tours can share one repo.
+ */
+export declare function pagesUrl(owner: string, repo: string, path?: string): string;
+/** The repository's web URL. */
+export declare function repoUrl(owner: string, repo: string): string;
+/**
+ * Drive the publish: verify tooling, resolve the owner, ensure the repo exists,
+ * push the bundle to gh-pages, and enable Pages. Ordering is load-bearing — the
+ * repo must exist before the push, and the gh-pages branch must exist (from the
+ * push) before Pages can be pointed at it.
+ */
+export declare function runPublishFlow(deps: PublishFlowDeps, opts: PublishOptions): Promise<PublishResult>;
+//# sourceMappingURL=publish-flow.d.ts.map

package/src/publish/publish-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-flow.d.ts","sourceRoot":"","sources":["../../../src/publish/publish-flow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,6EAA6E;IAC7E,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,yCAAyC;IACzC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,2DAA2D;IAC3D,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxG;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,gEAAgE;IAChE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW5D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS/D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED,gCAAgC;AAChC,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,aAAa,CAAC,CAuCxB"}

package/src/publish/publish-flow.js

@@ -0,0 +1,117 @@
+/**
+ * GitHub Pages publishing — the OSS "permanent public URL" path of Phase 1.
+ *
+ * The flow is dependency-injected (mirroring deploy-flow.ts) so its ordering and
+ * payloads are unit-testable against fakes, with zero live GitHub calls in the
+ * test suite. The real `gh`/`git` implementations live in ./github.ts.
+ */
+/** A repo name's allowed characters (GitHub: alphanumerics, ., _, -). */
+const REPO_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+/** GitHub caps repository names at 100 characters. */
+const MAX_REPO_NAME_LENGTH = 100;
+/** Allowed characters for a single publish path segment. */
+const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+/**
+ * Validate a GitHub repository name. Returns an error message, or null if valid.
+ * The scenario slug (the default) is always valid; this guards an explicit
+ * `--repo` before any repo is touched.
+ */
+export function validateRepoName(repo) {
+    if (repo.length === 0 || repo.length > MAX_REPO_NAME_LENGTH) {
+        return `repo name must be 1-${MAX_REPO_NAME_LENGTH} characters`;
+    }
+    if (repo === "." || repo === "..") {
+        return `repo name must not be "." or ".."`;
+    }
+    if (!REPO_NAME_PATTERN.test(repo)) {
+        return `invalid repo name "${repo}"; allowed: letters, digits, ".", "_", "-"`;
+    }
+    return null;
+}
+/**
+ * Normalize a publish path to a clean, slash-separated subpath with no leading,
+ * trailing, or doubled slashes. `/`, `.`, and empty all normalize to "" (root).
+ */
+export function normalizePath(path) {
+    return (path ?? "")
+        .split("/")
+        .map((seg) => seg.trim())
+        .filter((seg) => seg.length > 0 && seg !== ".")
+        .join("/");
+}
+/**
+ * Validate a (pre-normalized) publish subpath. Returns an error message, or null
+ * if valid. "" (root) is always valid; each segment must be a safe slug and
+ * never `..` (no directory traversal into the branch).
+ */
+export function validatePublishPath(path) {
+    if (path.length === 0)
+        return null;
+    for (const seg of path.split("/")) {
+        if (seg === "..")
+            return `path must not contain ".."`;
+        if (!PATH_SEGMENT_PATTERN.test(seg)) {
+            return `invalid path segment "${seg}"; allowed: letters, digits, ".", "_", "-"`;
+        }
+    }
+    return null;
+}
+/**
+ * The GitHub Pages URL for owner/repo, optionally under a subpath. A repository
+ * named exactly `<owner>.github.io` is the user/org site and serves at the apex;
+ * every other repo serves under its name as a path (which is why packed bundles
+ * use a relative base so they work from a subpath). A non-empty `path` appends a
+ * further subdirectory so many tours can share one repo.
+ */
+export function pagesUrl(owner, repo, path) {
+    const host = `${owner.toLowerCase()}.github.io`;
+    const base = repo.toLowerCase() === host ? `https://${host}/` : `https://${host}/${repo}/`;
+    const clean = normalizePath(path);
+    return clean ? `${base}${clean}/` : base;
+}
+/** The repository's web URL. */
+export function repoUrl(owner, repo) {
+    return `https://github.com/${owner}/${repo}`;
+}
+/**
+ * Drive the publish: verify tooling, resolve the owner, ensure the repo exists,
+ * push the bundle to gh-pages, and enable Pages. Ordering is load-bearing — the
+ * repo must exist before the push, and the gh-pages branch must exist (from the
+ * push) before Pages can be pointed at it.
+ */
+export async function runPublishFlow(deps, opts) {
+    await deps.ensureToolsAvailable();
+    const owner = await deps.resolveOwner(opts.org);
+    const exists = await deps.repoExists(owner, opts.repo);
+    if (!exists) {
+        deps.log(`Creating ${opts.private ? "private" : "public"} repo ${owner}/${opts.repo}...`);
+        await deps.createRepo(owner, opts.repo, {
+            private: opts.private,
+            description: "Scenar embed — published with `scenar publish`.",
+        });
+    }
+    else {
+        deps.log(`Reusing existing repo ${owner}/${opts.repo}...`);
+    }
+    deps.log(opts.path
+        ? `Publishing into ${opts.repo}/${opts.path}/ on the gh-pages branch...`
+        : "Pushing bundle to the gh-pages branch...");
+    await deps.pushBundleToPages({
+        bundleDir: opts.bundleDir,
+        owner,
+        repo: opts.repo,
+        path: opts.path,
+        message: opts.message,
+    });
+    deps.log("Enabling GitHub Pages...");
+    await deps.enablePages(owner, opts.repo);
+    return {
+        owner,
+        repo: opts.repo,
+        path: opts.path,
+        repoUrl: repoUrl(owner, opts.repo),
+        pagesUrl: pagesUrl(owner, opts.repo, opts.path),
+        created: !exists,
+    };
+}
+//# sourceMappingURL=publish-flow.js.map

package/src/publish/publish-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-flow.js","sourceRoot":"","sources":["../../../src/publish/publish-flow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAE9C,sDAAsD;AACtD,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAsEjD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QAC5D,OAAO,uBAAuB,oBAAoB,aAAa,CAAC;IAClE,CAAC;IACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,mCAAmC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,OAAO,sBAAsB,IAAI,4CAA4C,CAAC;IAChF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAwB;IACpD,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;SAChB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SACxB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,KAAK,GAAG,CAAC;SAC9C,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,4BAA4B,CAAC;QACtD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO,yBAAyB,GAAG,4CAA4C,CAAC;QAClF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,IAAY,EAAE,IAAa;IACjE,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,YAAY,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,IAAI,IAAI,IAAI,GAAG,CAAC;IAC3F,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,IAAY;IACjD,OAAO,sBAAsB,KAAK,IAAI,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAqB,EACrB,IAAoB;IAEpB,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,SAAS,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC;QAC1F,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE;YACtC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,iDAAiD;SAC/D,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,GAAG,CAAC,yBAAyB,KAAK,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,CAAC,GAAG,CACN,IAAI,CAAC,IAAI;QACP,CAAC,CAAC,mBAAmB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,6BAA6B;QACxE,CAAC,CAAC,0CAA0C,CAC/C,CAAC;IACF,MAAM,IAAI,CAAC,iBAAiB,CAAC;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;IAEH,IAAI,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;IACrC,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAEzC,OAAO;QACL,KAAK;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;QAClC,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;QAC/C,OAAO,EAAE,CAAC,MAAM;KACjB,CAAC;AACJ,CAAC"}

package/src/publish/publish-flow.ts

@@ -0,0 +1,199 @@
+/**
+ * GitHub Pages publishing — the OSS "permanent public URL" path of Phase 1.
+ *
+ * The flow is dependency-injected (mirroring deploy-flow.ts) so its ordering and
+ * payloads are unit-testable against fakes, with zero live GitHub calls in the
+ * test suite. The real `gh`/`git` implementations live in ./github.ts.
+ */
+
+/** A repo name's allowed characters (GitHub: alphanumerics, ., _, -). */
+const REPO_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/** GitHub caps repository names at 100 characters. */
+const MAX_REPO_NAME_LENGTH = 100;
+
+/** Allowed characters for a single publish path segment. */
+const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/** Identity for the target GitHub repository + how to write to it. */
+export interface PublishOptions {
+  /** The packed bundle directory to publish. */
+  readonly bundleDir: string;
+  /** Target repository name (default: the scenario slug). */
+  readonly repo: string;
+  /**
+   * Subdirectory within the repo to publish into, normalized (no leading/
+   * trailing slashes). Empty string means the repo root — a dedicated,
+   * single-tour repo whose every publish replaces the whole branch. A non-empty
+   * path (e.g. `welcome-tour`) lets many tours coexist in one repo; publishing
+   * replaces only that subfolder and preserves its siblings.
+   */
+  readonly path: string;
+  /** Target owner (a GitHub org); omitted means the authenticated user. */
+  readonly org?: string;
+  /** Create the repo private rather than public (Pages needs Pro for private). */
+  readonly private: boolean;
+  /** Commit message for the published snapshot. */
+  readonly message: string;
+}
+
+/** The published location. */
+export interface PublishResult {
+  readonly owner: string;
+  readonly repo: string;
+  /** The subdirectory the embed was published into ("" for the repo root). */
+  readonly path: string;
+  /** The repository's web URL. */
+  readonly repoUrl: string;
+  /** The GitHub Pages URL the embed is served at (includes the path). */
+  readonly pagesUrl: string;
+  /** True when the repo was created by this run (vs. reused). */
+  readonly created: boolean;
+}
+
+/**
+ * The side-effecting operations the flow depends on, injected so the ordering
+ * can be tested without `gh`, `git`, or the network.
+ */
+export interface PublishFlowDeps {
+  /** Verify `gh` + `git` are installed and `gh` is authenticated; else throw. */
+  ensureToolsAvailable(): Promise<void>;
+  /** Resolve the target owner: the explicit org, or the authenticated user. */
+  resolveOwner(explicitOrg: string | undefined): Promise<string>;
+  /** Whether owner/repo already exists. */
+  repoExists(owner: string, repo: string): Promise<boolean>;
+  /** Create owner/repo (public unless private requested). */
+  createRepo(owner: string, repo: string, opts: { private: boolean; description: string }): Promise<void>;
+  /**
+   * Publish the bundle (plus a root .nojekyll) to the repo's gh-pages branch.
+   * An empty `path` replaces the whole branch (dedicated repo); a non-empty
+   * `path` updates only that subfolder, preserving sibling tours already on the
+   * branch.
+   */
+  pushBundleToPages(input: {
+    bundleDir: string;
+    owner: string;
+    repo: string;
+    path: string;
+    message: string;
+  }): Promise<void>;
+  /** Enable GitHub Pages from gh-pages (idempotent — a no-op if already on). */
+  enablePages(owner: string, repo: string): Promise<void>;
+  /** Progress sink (stderr in the command; captured in tests). */
+  log(message: string): void;
+}
+
+/**
+ * Validate a GitHub repository name. Returns an error message, or null if valid.
+ * The scenario slug (the default) is always valid; this guards an explicit
+ * `--repo` before any repo is touched.
+ */
+export function validateRepoName(repo: string): string | null {
+  if (repo.length === 0 || repo.length > MAX_REPO_NAME_LENGTH) {
+    return `repo name must be 1-${MAX_REPO_NAME_LENGTH} characters`;
+  }
+  if (repo === "." || repo === "..") {
+    return `repo name must not be "." or ".."`;
+  }
+  if (!REPO_NAME_PATTERN.test(repo)) {
+    return `invalid repo name "${repo}"; allowed: letters, digits, ".", "_", "-"`;
+  }
+  return null;
+}
+
+/**
+ * Normalize a publish path to a clean, slash-separated subpath with no leading,
+ * trailing, or doubled slashes. `/`, `.`, and empty all normalize to "" (root).
+ */
+export function normalizePath(path: string | undefined): string {
+  return (path ?? "")
+    .split("/")
+    .map((seg) => seg.trim())
+    .filter((seg) => seg.length > 0 && seg !== ".")
+    .join("/");
+}
+
+/**
+ * Validate a (pre-normalized) publish subpath. Returns an error message, or null
+ * if valid. "" (root) is always valid; each segment must be a safe slug and
+ * never `..` (no directory traversal into the branch).
+ */
+export function validatePublishPath(path: string): string | null {
+  if (path.length === 0) return null;
+  for (const seg of path.split("/")) {
+    if (seg === "..") return `path must not contain ".."`;
+    if (!PATH_SEGMENT_PATTERN.test(seg)) {
+      return `invalid path segment "${seg}"; allowed: letters, digits, ".", "_", "-"`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The GitHub Pages URL for owner/repo, optionally under a subpath. A repository
+ * named exactly `<owner>.github.io` is the user/org site and serves at the apex;
+ * every other repo serves under its name as a path (which is why packed bundles
+ * use a relative base so they work from a subpath). A non-empty `path` appends a
+ * further subdirectory so many tours can share one repo.
+ */
+export function pagesUrl(owner: string, repo: string, path?: string): string {
+  const host = `${owner.toLowerCase()}.github.io`;
+  const base = repo.toLowerCase() === host ? `https://${host}/` : `https://${host}/${repo}/`;
+  const clean = normalizePath(path);
+  return clean ? `${base}${clean}/` : base;
+}
+
+/** The repository's web URL. */
+export function repoUrl(owner: string, repo: string): string {
+  return `https://github.com/${owner}/${repo}`;
+}
+
+/**
+ * Drive the publish: verify tooling, resolve the owner, ensure the repo exists,
+ * push the bundle to gh-pages, and enable Pages. Ordering is load-bearing — the
+ * repo must exist before the push, and the gh-pages branch must exist (from the
+ * push) before Pages can be pointed at it.
+ */
+export async function runPublishFlow(
+  deps: PublishFlowDeps,
+  opts: PublishOptions,
+): Promise<PublishResult> {
+  await deps.ensureToolsAvailable();
+
+  const owner = await deps.resolveOwner(opts.org);
+  const exists = await deps.repoExists(owner, opts.repo);
+  if (!exists) {
+    deps.log(`Creating ${opts.private ? "private" : "public"} repo ${owner}/${opts.repo}...`);
+    await deps.createRepo(owner, opts.repo, {
+      private: opts.private,
+      description: "Scenar embed — published with `scenar publish`.",
+    });
+  } else {
+    deps.log(`Reusing existing repo ${owner}/${opts.repo}...`);
+  }
+
+  deps.log(
+    opts.path
+      ? `Publishing into ${opts.repo}/${opts.path}/ on the gh-pages branch...`
+      : "Pushing bundle to the gh-pages branch...",
+  );
+  await deps.pushBundleToPages({
+    bundleDir: opts.bundleDir,
+    owner,
+    repo: opts.repo,
+    path: opts.path,
+    message: opts.message,
+  });
+
+  deps.log("Enabling GitHub Pages...");
+  await deps.enablePages(owner, opts.repo);
+
+  return {
+    owner,
+    repo: opts.repo,
+    path: opts.path,
+    repoUrl: repoUrl(owner, opts.repo),
+    pagesUrl: pagesUrl(owner, opts.repo, opts.path),
+    created: !exists,
+  };
+}