@scenar/cli 0.1.20 → 0.2.0

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":"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"}

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

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

@@ -0,0 +1,41 @@
+import type { Viewport } from "../pack/viewport.js";
+import { type PublishFlowDeps, type PublishResult } from "./publish-flow.js";
+/** Options for {@link runPublish}. */
+export interface RunPublishOptions {
+    readonly bundleDir: string;
+    /** Target repository name (default: {@link DEFAULT_REPO}). */
+    readonly repo?: string;
+    /**
+     * Subdirectory within the repo (default: the packed scenario slug). Pass "/"
+     * or "" to publish at the repo root (a dedicated single-tour repo).
+     */
+    readonly path?: string;
+    /** Target GitHub org (default: the authenticated user). */
+    readonly org?: string;
+    /** Create the repo private (GitHub Pages needs Pro for private repos). */
+    readonly private?: boolean;
+    /** Commit message for the published snapshot. */
+    readonly message?: string;
+    /** Progress sink for flow messages. */
+    readonly onLog?: (message: string) => void;
+    /**
+     * Override the publish backend (the gh/git deps). Defaults to the real
+     * {@link createGithubPublisher}; tests inject a fake to avoid live calls.
+     */
+    readonly deps?: Omit<PublishFlowDeps, "log">;
+}
+/** The published location plus the derived embed snippet. */
+export interface PublishRunResult {
+    readonly result: PublishResult;
+    readonly viewport: Viewport;
+    readonly recordedViewport: boolean;
+    readonly snippet: string;
+}
+/**
+ * Validate a packed bundle and publish it to GitHub Pages — the orchestration
+ * behind `scenar publish`, with no process/exit coupling. Resolves the default
+ * repo name, runs the publish flow, and builds the embed snippet. Throws on an
+ * invalid bundle, an invalid repo name, or any flow failure.
+ */
+export declare function runPublish(options: RunPublishOptions): Promise<PublishRunResult>;
+//# sourceMappingURL=run-publish.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-publish.d.ts","sourceRoot":"","sources":["../../../src/publish/run-publish.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAc3B,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;CAC9C;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+CtF"}

package/src/publish/run-publish.js

@@ -0,0 +1,77 @@
+import { resolve, join, basename } from "node:path";
+import { stat, readFile } from "node:fs/promises";
+import { PACK_MANIFEST_FILE } from "../pack/pack-manifest.js";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { createGithubPublisher } from "./github.js";
+import { runPublishFlow, validateRepoName, validatePublishPath, normalizePath, } from "./publish-flow.js";
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+/** Repo-name rule for the default (same shape as scenario slugs). */
+const REPO_FALLBACK_PATTERN = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+/**
+ * Default shared repo for embeds. Many tours live here, each under its own slug
+ * path, so previews never land in the user's source repo. Override with --repo.
+ */
+const DEFAULT_REPO = "scenar-embeds";
+/**
+ * Validate a packed bundle and publish it to GitHub Pages — the orchestration
+ * behind `scenar publish`, with no process/exit coupling. Resolves the default
+ * repo name, runs the publish flow, and builds the embed snippet. Throws on an
+ * invalid bundle, an invalid repo name, or any flow failure.
+ */
+export async function runPublish(options) {
+    const onLog = options.onLog ?? (() => { });
+    const resolvedDir = resolve(options.bundleDir);
+    const info = await stat(resolvedDir).catch(() => null);
+    if (!info || !info.isDirectory()) {
+        throw new Error(`${options.bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`);
+    }
+    const indexInfo = await stat(join(resolvedDir, INDEX_FILE)).catch(() => null);
+    if (!indexInfo || !indexInfo.isFile()) {
+        throw new Error(`no ${INDEX_FILE} in ${options.bundleDir}. Run \`scenar pack\` to produce a servable bundle first.`);
+    }
+    const slug = await scenarioSlug(resolvedDir);
+    const repo = options.repo ?? DEFAULT_REPO;
+    const repoError = validateRepoName(repo);
+    if (repoError) {
+        throw new Error(`${repoError}. Pass --repo <name> to override.`);
+    }
+    // Path defaults to the scenario slug so tours coexist in one repo; an explicit
+    // "/" (or "") publishes at the repo root.
+    const path = normalizePath(options.path ?? slug);
+    const pathError = validatePublishPath(path);
+    if (pathError) {
+        throw new Error(`${pathError}. Pass --path <subpath> to override.`);
+    }
+    const deps = { ...(options.deps ?? createGithubPublisher()), log: onLog };
+    const result = await runPublishFlow(deps, {
+        bundleDir: resolvedDir,
+        repo,
+        path,
+        org: options.org,
+        private: Boolean(options.private),
+        message: options.message ?? "Publish Scenar embed",
+    });
+    const { viewport, recorded } = await readBundleViewport(resolvedDir);
+    const snippet = buildEmbedSnippet({ embedUrl: result.pagesUrl, viewport });
+    return { result, viewport, recordedViewport: recorded, snippet };
+}
+/**
+ * The packed scenario slug (from pack-manifest.json), falling back to the bundle
+ * directory's base name. Used as the default publish subpath. The downstream
+ * validatePublishPath guards the result.
+ */
+async function scenarioSlug(bundleDir) {
+    try {
+        const raw = await readFile(join(bundleDir, PACK_MANIFEST_FILE), "utf-8");
+        const id = JSON.parse(raw).scenarioId;
+        if (typeof id === "string" && REPO_FALLBACK_PATTERN.test(id))
+            return id;
+    }
+    catch {
+        // No/invalid manifest — fall back to the directory name.
+    }
+    return basename(bundleDir);
+}
+//# sourceMappingURL=run-publish.js.map

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

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