screencast-axi 0.1.0

package/dist/src/auth/strategies.js

@@ -0,0 +1,137 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { ScreencastError } from "../errors.js";
+/** Signed-out. The default, and correct for most public surfaces. */
+export function noAuth() {
+    return { name: "none" };
+}
+/**
+ * Sign in once by hand; every take afterwards reuses the session.
+ *
+ * This is the strategy that makes the tool work on a site nobody wrote a
+ * strategy for. The browser opens, a person signs in however that site wants -
+ * OAuth, SSO, a magic link, two-factor - and closes the window. The session
+ * lives in the persistent Chrome profile, so no code here has to know anything
+ * about how that site authenticates, and no credential is ever handled by this
+ * package.
+ *
+ * It needs `browser.profileDir` set, since a persistent profile is the thing
+ * doing the remembering.
+ */
+export function profileAuth(options = {}) {
+    return {
+        name: "profile",
+        async assertSignedIn(page, ctx) {
+            const landing = options.landingPath ?? "/";
+            await page.goto(new URL(landing, ctx.baseUrl).toString(), {
+                waitUntil: "domcontentloaded",
+            });
+            if (options.signedInSelector) {
+                try {
+                    await page.locator(options.signedInSelector).first().waitFor({ state: "visible" });
+                    return;
+                }
+                catch {
+                    throw notSignedIn(`nothing matched \`${options.signedInSelector}\` on ${page.url()}`, ctx);
+                }
+            }
+            if (options.signedInCookie) {
+                const [name, expected] = splitCookie(options.signedInCookie);
+                const deadline = Date.now() + 15_000;
+                for (;;) {
+                    const cookies = await page.context().cookies();
+                    const found = cookies.find((c) => c.name === name);
+                    if (found && (expected === undefined || found.value === expected))
+                        return;
+                    if (Date.now() > deadline) {
+                        throw notSignedIn(found
+                            ? `\`${name}\` is \`${found.value}\`, expected \`${expected}\``
+                            : `the \`${name}\` cookie never appeared`, ctx);
+                    }
+                    await page.waitForTimeout(250);
+                }
+            }
+            // Nothing to check against. Say so rather than implying it passed:
+            // "the URL is not /login" is a false pass, since a build-error page
+            // satisfies it too.
+            ctx.log("signed-in state was not verified - set signedInSelector or signedInCookie to check it");
+        },
+        async interactiveLogin(_context, page, ctx) {
+            await page.goto(ctx.baseUrl, { waitUntil: "domcontentloaded" });
+            ctx.log("Sign in in the browser window, then close it when you are done.");
+            // Resolves when the human closes the window, which is the signal that
+            // they consider themselves signed in.
+            await new Promise((done) => page.on("close", () => done()));
+        },
+        describe: () => ({
+            strategy: "profile",
+            ...(options.landingPath ? { landing: options.landingPath } : {}),
+            ...(options.signedInSelector ? { verifies: options.signedInSelector } : {}),
+            ...(options.signedInCookie ? { verifies_cookie: options.signedInCookie } : {}),
+            ...(options.label ? { as: options.label } : {}),
+        }),
+    };
+}
+/**
+ * A saved Playwright session file.
+ *
+ * Portable and CI-friendly in a way a Chrome profile is not: it is one JSON
+ * file that can be produced once and committed to a secret store. Needs an
+ * isolated context, so it cannot be combined with `browser.profileDir`.
+ */
+export function storageStateAuth(options) {
+    const at = (root) => isAbsolute(options.path) ? options.path : resolve(root, options.path);
+    return {
+        name: "storageState",
+        async preflight(ctx) {
+            const file = at(ctx.rootDir);
+            if (!existsSync(file)) {
+                throw new ScreencastError(`No saved session at ${file}`, "AUTH_NOT_READY", [
+                    "Create one: `screencast-axi auth login --interactive --save-state " +
+                        `${options.path}\``,
+                    "A storage state is produced once by a human and reused by every take",
+                ]);
+            }
+        },
+        prepareContext(ctx) {
+            return { storageState: at(ctx.rootDir) };
+        },
+        async assertSignedIn(page, ctx) {
+            if (!options.signedInSelector)
+                return;
+            await page.goto(new URL(options.landingPath ?? "/", ctx.baseUrl).toString(), {
+                waitUntil: "domcontentloaded",
+            });
+            try {
+                await page.locator(options.signedInSelector).first().waitFor({ state: "visible" });
+            }
+            catch {
+                throw notSignedIn(`nothing matched \`${options.signedInSelector}\` - the saved session may have expired`, ctx);
+            }
+        },
+        describe: () => ({ strategy: "storageState", file: options.path }),
+    };
+}
+/** HTTP basic auth, which is how most staging environments are gated. */
+export function basicAuth(options) {
+    return {
+        name: "basicAuth",
+        prepareContext: () => ({
+            httpCredentials: { username: options.username, password: options.password },
+        }),
+        // The password is deliberately absent: `describe` output is printed.
+        describe: () => ({ strategy: "basicAuth", username: options.username }),
+    };
+}
+/** Splits `name=value` into its parts; a bare name means "any value". */
+export function splitCookie(spec) {
+    const at = spec.indexOf("=");
+    return at === -1 ? [spec, undefined] : [spec.slice(0, at), spec.slice(at + 1)];
+}
+function notSignedIn(reason, ctx) {
+    return new ScreencastError(`Not signed in: ${reason}`, "NOT_SIGNED_IN", [
+        `Sign in by hand once: \`screencast-axi auth login --interactive --base-url ${ctx.baseUrl}\``,
+        "Then check it took: `screencast-axi auth check`",
+    ]);
+}
+//# sourceMappingURL=strategies.js.map

package/dist/src/auth/strategies.js.map

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

package/dist/src/auth/types.d.ts

@@ -0,0 +1,65 @@
+import type { BrowserContext, Page } from "playwright";
+/**
+ * How a take gets past a login.
+ *
+ * The four jobs the interface separates were, in the recorder this grew out
+ * of, one 300-line function - and the seams matter:
+ *
+ * - `preflight` runs before the browser opens, so "the auth server is down" is
+ *   discovered in a second rather than mid-take, after the capture has already
+ *   started rolling.
+ * - `assertSignedIn` is separate from `signIn` because they answer different
+ *   questions. The provider saying yes is not the app agreeing: a build-error
+ *   page, or an app that never booted, sails past any check based on the URL.
+ *   Naming it in the interface means a new strategy cannot skip it by
+ *   accident.
+ * - `interactiveLogin` is the human-in-the-loop path, kept apart because it is
+ *   the one thing that cannot run unattended.
+ */
+export interface AuthIdentity {
+    /** Stable id, if the strategy knows one. */
+    readonly id: string;
+    /** What to print: an email, a username, a profile name. Never a secret. */
+    readonly label: string;
+}
+export interface AuthPreflightContext {
+    readonly baseUrl: string;
+    /** Directory the config was loaded from; relative paths anchor here. */
+    readonly rootDir: string;
+    log(message: string): void;
+}
+export interface AuthContext extends AuthPreflightContext {
+    readonly scenario: {
+        readonly id: string;
+        readonly title: string;
+    };
+}
+/** Context options a strategy can set before any page exists. */
+export interface ContextPatch {
+    readonly storageState?: string;
+    readonly httpCredentials?: {
+        readonly username: string;
+        readonly password: string;
+    };
+}
+export interface AuthStrategy {
+    readonly name: string;
+    /** No browser: env vars present, a file on disk, a host reachable. */
+    preflight?(ctx: AuthPreflightContext): Promise<void>;
+    /** Cookies, storage state, HTTP credentials - applied at context creation. */
+    prepareContext?(ctx: AuthPreflightContext): ContextPatch;
+    /** Page-level sign-in. Returns who the take is now running as. */
+    signIn?(page: Page, ctx: AuthContext): Promise<AuthIdentity>;
+    /** Proves the app agrees someone is signed in, not just the provider. */
+    assertSignedIn?(page: Page, ctx: AuthContext): Promise<void>;
+    /**
+     * Opens a browser for a human to sign in by hand.
+     *
+     * Resolves when they are done - normally when they close the window. A
+     * strategy without this reports that `auth login` does not apply to it.
+     */
+    interactiveLogin?(context: BrowserContext, page: Page, ctx: AuthContext): Promise<void>;
+    /** Non-secret fields for `auth check` and `doctor` to print. */
+    describe?(): Record<string, string | number | boolean>;
+}
+export type AuthConfig = AuthStrategy | Record<string, AuthStrategy>;

package/dist/src/auth/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/auth/types.ts"],"names":[],"mappings":""}

package/dist/src/browser.d.ts

@@ -0,0 +1,100 @@
+import type { Browser, BrowserContext, LaunchOptions, Page } from "playwright";
+import type { Viewport } from "./types.js";
+/**
+ * Finding Playwright, and opening the context a take records in.
+ *
+ * Playwright is an optional peer rather than a dependency: a consuming project
+ * almost always has its own, and a second copy would mean a second browser
+ * download and - the one that actually bites - a `Page` type that does not
+ * match the `Page` the recorder hands a scenario.
+ */
+export interface PlaywrightModule {
+    readonly chromium: {
+        launch(options?: LaunchOptions): Promise<Browser>;
+        launchPersistentContext(userDataDir: string, options?: object): Promise<BrowserContext>;
+    };
+    readonly devices: Record<string, DevicePreset>;
+}
+export interface DevicePreset {
+    readonly viewport: Viewport;
+    readonly userAgent: string;
+    readonly deviceScaleFactor: number;
+    readonly isMobile: boolean;
+    readonly hasTouch: boolean;
+}
+export declare function resolvePlaywright(): Promise<{
+    module: PlaywrightModule;
+    specifier: string;
+}>;
+export interface ResolvedViewport {
+    readonly viewport: Viewport;
+    readonly deviceScaleFactor: number;
+    readonly isMobile: boolean;
+    readonly hasTouch: boolean;
+    readonly userAgent?: string;
+    /** The preset this came from, for the manifest and the CLI to report. */
+    readonly device?: string;
+}
+export interface ViewportRequest {
+    readonly device?: string;
+    readonly viewport?: Viewport;
+    readonly orientation?: "portrait" | "landscape";
+    readonly deviceScaleFactor?: number;
+}
+/**
+ * Turns a device name, an explicit viewport, or both into what a context needs.
+ *
+ * Device presets are worth going through rather than just setting a width:
+ * they carry `deviceScaleFactor` (2-3 on phones), which is the difference
+ * between a crisp phone clip and a blurry one, plus the `isMobile` and
+ * `hasTouch` flags that decide whether the page's own `@media (hover: none)`
+ * rules apply at all.
+ */
+export declare function resolveViewport(request: ViewportRequest, fallback: Viewport): Promise<ResolvedViewport>;
+export interface ContextOptions {
+    readonly resolved: ResolvedViewport;
+    readonly headless: boolean;
+    readonly args: readonly string[];
+    readonly profileDir?: string;
+    /** Directory for the raw capture. Absent means no video is recorded. */
+    readonly recordVideoDir?: string;
+    readonly colorScheme?: "light" | "dark";
+    readonly locale?: string;
+    readonly timezoneId?: string;
+    /** Applied by an auth strategy before any page exists. */
+    readonly storageState?: string;
+    readonly httpCredentials?: {
+        readonly username: string;
+        readonly password: string;
+    };
+}
+/**
+ * The size the raw video is captured at.
+ *
+ * Never larger than the viewport. Playwright renders the page at the CSS
+ * viewport and composites it into a canvas of this size *without scaling up* -
+ * measured in Chromium, asking for three times the viewport puts the page in
+ * the top-left corner and leaves the rest empty grey. Scaling down does work,
+ * which is what the cap relies on.
+ *
+ * So a device preset's `deviceScaleFactor` cannot buy a sharper capture: it
+ * still matters for how the page renders and lays itself out, but the video is
+ * CSS-pixel resolution either way.
+ */
+export declare function captureSize(resolved: ResolvedViewport): Viewport;
+export interface OpenedContext {
+    readonly context: BrowserContext;
+    readonly page: Page;
+    /** When the context was created - the clock the head-trim is measured from. */
+    readonly createdAt: number;
+    close(): Promise<void>;
+}
+/**
+ * Opens the context a take runs in.
+ *
+ * A `profileDir` means a persistent context, which is what lets a session
+ * someone signed into by hand survive between takes. Without one the context
+ * is isolated, which is what `storageState` needs - the two are mutually
+ * exclusive, and saying so is better than silently preferring one.
+ */
+export declare function openContext(options: ContextOptions): Promise<OpenedContext>;

package/dist/src/browser.js

@@ -0,0 +1,168 @@
+import { ScreencastError } from "./errors.js";
+/** Where a consumer's Playwright might live, best first. */
+const CANDIDATES = ["playwright", "playwright-core", "@playwright/test"];
+let cached = null;
+export async function resolvePlaywright() {
+    if (cached)
+        return cached;
+    const tried = [];
+    for (const specifier of CANDIDATES) {
+        try {
+            const loaded = (await import(specifier));
+            // `@playwright/test` re-exports chromium, which is why it qualifies.
+            if (loaded.chromium) {
+                cached = { module: loaded, specifier };
+                return cached;
+            }
+            tried.push(`${specifier} (no chromium export)`);
+        }
+        catch {
+            tried.push(specifier);
+        }
+    }
+    throw new ScreencastError("Playwright is not installed", "PLAYWRIGHT_MISSING", [
+        "Install it: `pnpm add -D playwright`",
+        "Then download the browser: `pnpm exec playwright install chromium`",
+        `Looked for: ${tried.join(", ")}`,
+    ]);
+}
+/**
+ * Turns a device name, an explicit viewport, or both into what a context needs.
+ *
+ * Device presets are worth going through rather than just setting a width:
+ * they carry `deviceScaleFactor` (2-3 on phones), which is the difference
+ * between a crisp phone clip and a blurry one, plus the `isMobile` and
+ * `hasTouch` flags that decide whether the page's own `@media (hover: none)`
+ * rules apply at all.
+ */
+export async function resolveViewport(request, fallback) {
+    let base = {
+        viewport: request.viewport ?? fallback,
+        deviceScaleFactor: request.deviceScaleFactor ?? 1,
+        isMobile: false,
+        hasTouch: false,
+    };
+    if (request.device) {
+        const { module } = await resolvePlaywright();
+        const preset = module.devices[request.device];
+        if (!preset) {
+            const names = Object.keys(module.devices);
+            const near = names.filter((n) => n.toLowerCase().includes(request.device.toLowerCase()));
+            throw new ScreencastError(`Unknown device: ${request.device}`, "UNKNOWN_DEVICE", [
+                near.length > 0
+                    ? `Did you mean: ${near.slice(0, 5).join(", ")}?`
+                    : `Playwright ships ${names.length} presets, e.g. ${names.slice(0, 4).join(", ")}`,
+                "Device names are Playwright's own and are case-sensitive",
+            ]);
+        }
+        base = {
+            viewport: request.viewport ?? preset.viewport,
+            deviceScaleFactor: request.deviceScaleFactor ?? preset.deviceScaleFactor,
+            isMobile: preset.isMobile,
+            hasTouch: preset.hasTouch,
+            userAgent: preset.userAgent,
+            device: request.device,
+        };
+    }
+    if (request.orientation) {
+        const { width, height } = base.viewport;
+        const wantsPortrait = request.orientation === "portrait";
+        const isPortrait = height >= width;
+        if (wantsPortrait !== isPortrait) {
+            base = { ...base, viewport: { width: height, height: width } };
+        }
+    }
+    return base;
+}
+/**
+ * Upper bound on either dimension of the raw capture.
+ *
+ * A very large desktop viewport would otherwise produce a needlessly heavy
+ * capture that the deliverable scales down anyway.
+ */
+const MAX_CAPTURE_EDGE = 1600;
+/**
+ * The size the raw video is captured at.
+ *
+ * Never larger than the viewport. Playwright renders the page at the CSS
+ * viewport and composites it into a canvas of this size *without scaling up* -
+ * measured in Chromium, asking for three times the viewport puts the page in
+ * the top-left corner and leaves the rest empty grey. Scaling down does work,
+ * which is what the cap relies on.
+ *
+ * So a device preset's `deviceScaleFactor` cannot buy a sharper capture: it
+ * still matters for how the page renders and lays itself out, but the video is
+ * CSS-pixel resolution either way.
+ */
+export function captureSize(resolved) {
+    const { width, height } = resolved.viewport;
+    const scale = Math.min(1, MAX_CAPTURE_EDGE / Math.max(width, height));
+    // Even dimensions: h264's yuv420p requires them, and rounding here avoids a
+    // one-pixel scale in the encoder.
+    const even = (n) => Math.max(2, Math.round((n * scale) / 2) * 2);
+    return { width: even(width), height: even(height) };
+}
+/**
+ * Opens the context a take runs in.
+ *
+ * A `profileDir` means a persistent context, which is what lets a session
+ * someone signed into by hand survive between takes. Without one the context
+ * is isolated, which is what `storageState` needs - the two are mutually
+ * exclusive, and saying so is better than silently preferring one.
+ */
+export async function openContext(options) {
+    if (options.profileDir && options.storageState) {
+        throw new ScreencastError("A persistent profile and a saved storage state cannot both be used", "CONFIG_CONFLICT", [
+            "A storage state needs an isolated context; a profile needs a persistent one",
+            "Drop `browser.profileDir`, or use an auth strategy that does not set storageState",
+        ]);
+    }
+    const { module } = await resolvePlaywright();
+    const { resolved } = options;
+    const shared = {
+        viewport: resolved.viewport,
+        deviceScaleFactor: resolved.deviceScaleFactor,
+        isMobile: resolved.isMobile,
+        hasTouch: resolved.hasTouch,
+        ...(resolved.userAgent ? { userAgent: resolved.userAgent } : {}),
+        ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
+        ...(options.locale ? { locale: options.locale } : {}),
+        ...(options.timezoneId ? { timezoneId: options.timezoneId } : {}),
+        ...(options.httpCredentials ? { httpCredentials: options.httpCredentials } : {}),
+        ...(options.recordVideoDir
+            ? { recordVideo: { dir: options.recordVideoDir, size: captureSize(resolved) } }
+            : {}),
+    };
+    if (options.profileDir) {
+        const context = await module.chromium.launchPersistentContext(options.profileDir, {
+            headless: options.headless,
+            args: [...options.args],
+            ...shared,
+        });
+        const createdAt = Date.now();
+        const page = context.pages()[0] ?? (await context.newPage());
+        return { context, page, createdAt, close: () => context.close() };
+    }
+    const browser = await module.chromium.launch({
+        headless: options.headless,
+        args: [...options.args],
+    });
+    const context = await browser.newContext({
+        ...shared,
+        ...(options.storageState ? { storageState: options.storageState } : {}),
+    });
+    const createdAt = Date.now();
+    const page = await context.newPage();
+    return {
+        context,
+        page,
+        createdAt,
+        // The capture is only finalised when the context closes, so the context
+        // has to go first and the browser after it.
+        close: async () => {
+            await context.close();
+            await browser.close();
+        },
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/src/browser.js.map

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

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+export declare const DESCRIPTION = "Record cinematic product screencasts from scripted Playwright scenarios";
+export declare function main(argv?: string[]): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,160 @@
+import { runAxiCli } from "axi-sdk-js";
+import { encode as toon } from "@toon-format/toon";
+import { isScreencastError } from "./errors.js";
+import { ScenarioFailure } from "./run.js";
+import { VERSION } from "./version.js";
+import { homeView } from "./commands/home.js";
+import { guideCommand, guideHelp } from "./commands/guide.js";
+import { recordCommand, RECORD_FLAGS, REHEARSE_FLAGS } from "./commands/record.js";
+import { scaffoldCommand, SCAFFOLD_FLAGS } from "./commands/scaffold.js";
+import { authCommand, AUTH_FLAGS } from "./commands/auth.js";
+import { listCommand, showCommand, LIST_FLAGS, SHOW_FLAGS } from "./commands/list.js";
+import { checkCommand, CHECK_FLAGS } from "./commands/check.js";
+import { doctorCommand, DOCTOR_FLAGS } from "./commands/doctor.js";
+import { setupCommand, initCommand, SETUP_FLAGS, INIT_FLAGS } from "./commands/setup.js";
+import { renderFlagHelp } from "./flags.js";
+export const DESCRIPTION = "Record cinematic product screencasts from scripted Playwright scenarios";
+/**
+ * Top-level help.
+ *
+ * Terse by design: the agent-facing source of truth is this block plus
+ * `<command> --help`, and every line an agent reads costs tokens. Deeper
+ * guidance lives behind `guide <topic>` so it is pulled a topic at a time.
+ */
+const TOP_LEVEL_HELP = `${[
+    `usage: screencast-axi <command> [args] [flags]`,
+    ``,
+    `commands:`,
+    `  init                 Write a config and a scenarios directory`,
+    `  scaffold <id>        Write a scenario skeleton`,
+    `  rehearse <id|path>   Dry run: prints what it does. --headed to watch it`,
+    `  record   <id|path>   Run it for real and encode the clip`,
+    `  auth login|check     Sign in by hand once, or check the saved session`,
+    `  list                 Every scenario, and what needs re-shooting`,
+    `  show <id>            One clip in full`,
+    `  check                Manifest, scenarios and files, cross-referenced`,
+    `  doctor               Everything a recording needs, checked at once`,
+    `  setup                Install the browser; name what you must install`,
+    `  guide [topic]        Topic-sized guidance. Run bare to list topics`,
+    ``,
+    `flags must come after the command. \`--version\`, \`--help\` excepted.`,
+].join("\n")}\n`;
+function commandHelp(name, description, usage, specs) {
+    const flags = renderFlagHelp(specs);
+    return `${[
+        `command: ${name}`,
+        `description: ${description}`,
+        ``,
+        `usage:`,
+        ...usage.map((u) => `  ${u}`),
+        ...(flags.length > 0 ? [``, `flags:`, ...flags] : []),
+    ].join("\n")}\n`;
+}
+const COMMAND_HELP = {
+    guide: guideHelp(),
+    record: commandHelp("record", "Run a scenario and encode the clip", [
+        "screencast-axi record <id>            A scenario the config lists",
+        "screencast-axi record ./tour.ts       A file, no config needed",
+        "screencast-axi record --all           Every configured scenario",
+    ], RECORD_FLAGS),
+    rehearse: commandHelp("rehearse", "Run a scenario without recording or encoding, to prove its selectors", ["screencast-axi rehearse <id>", "screencast-axi rehearse ./tour.ts --headed"], REHEARSE_FLAGS),
+    auth: commandHelp("auth", "Sign in by hand once; every take afterwards reuses the session", [
+        "screencast-axi auth login --interactive   Opens a browser for a person to sign in",
+        "screencast-axi auth check                 Reports whether the session still works",
+        "screencast-axi auth check <name>          A named strategy from the config",
+    ], AUTH_FLAGS),
+    list: commandHelp("list", "Every scenario, with what needs re-shooting", ["screencast-axi list", "screencast-axi list --stale", "screencast-axi list --full"], LIST_FLAGS),
+    show: commandHelp("show", "One clip in full: its files, sizes, narration and when it was shot", ["screencast-axi show product-tour"], SHOW_FLAGS),
+    check: commandHelp("check", "Cross-references the manifest, the scenarios and the files on disk", ["screencast-axi check", "screencast-axi check --fix-orphans"], CHECK_FLAGS),
+    doctor: commandHelp("doctor", "Checks everything a recording needs, in one pass", ["screencast-axi doctor"], DOCTOR_FLAGS),
+    setup: commandHelp("setup", "Installs the browser and names anything you have to install yourself", ["screencast-axi setup", "screencast-axi setup --browsers-only"], SETUP_FLAGS),
+    init: commandHelp("init", "Writes a config, a scenarios directory, and a gitignore entry", ["screencast-axi init", "screencast-axi init --url https://example.com"], INIT_FLAGS),
+    scaffold: commandHelp("scaffold", "Write a scenario skeleton so the boilerplate is never what goes wrong", [
+        "screencast-axi scaffold product-tour --url https://example.com",
+        "screencast-axi scaffold product-tour --url https://example.com --tour 5",
+    ], SCAFFOLD_FLAGS),
+};
+/**
+ * Renders an error with everything needed to act on it.
+ *
+ * The SDK's own error shape is message + code + suggestions, which is right
+ * for a usage error but throws away the point of the forensics. A take that
+ * failed on a stale selector should hand back the URL it reached, a
+ * screenshot, and what each part of the selector actually matched - so the
+ * next attempt is informed rather than another blind minute.
+ *
+ * Rendering here also means the library half never has to construct an SDK
+ * error, which is what keeps it free of an ESM-only dependency.
+ */
+function formatError(error) {
+    if (error instanceof ScenarioFailure) {
+        const f = error.forensics;
+        return {
+            output: `${toon({
+                error: error.message,
+                code: error.code,
+                scenario: error.scenarioId,
+                phase: error.phase,
+                ...(error.lastStep !== null ? { last_step: error.lastStep } : {}),
+                ...(f.url ? { url: f.url } : {}),
+                ...(f.screenshot ? { screenshot: f.screenshot } : {}),
+                ...(f.nearMatches
+                    ? {
+                        near_matches: f.nearMatches.map((m) => ({
+                            selector: m.selector,
+                            count: m.count,
+                            visible: m.visible,
+                        })),
+                    }
+                    : {}),
+                ...(f.notes ? { notes: f.notes } : {}),
+                ...(error.suggestions.length > 0 ? { help: error.suggestions } : {}),
+            })}\n`,
+            exitCode: 1,
+        };
+    }
+    if (isScreencastError(error)) {
+        return {
+            output: `${toon({
+                error: error.message,
+                code: error.code,
+                ...(error.suggestions.length > 0 ? { help: error.suggestions } : {}),
+            })}\n`,
+            // A usage error is the caller's to fix, and exits 2 so a script can tell
+            // it apart from work that ran and failed.
+            exitCode: error.code === "VALIDATION_ERROR" ? 2 : 1,
+        };
+    }
+    return {
+        output: `${toon({
+            error: error instanceof Error ? error.message : String(error),
+            code: "UNKNOWN",
+        })}\n`,
+        exitCode: 1,
+    };
+}
+export async function main(argv) {
+    await runAxiCli({
+        formatError,
+        description: DESCRIPTION,
+        version: VERSION,
+        topLevelHelp: TOP_LEVEL_HELP,
+        ...(argv ? { argv } : {}),
+        home: () => homeView(),
+        commands: {
+            guide: (args) => guideCommand(args),
+            scaffold: (args) => scaffoldCommand(args),
+            auth: (args) => authCommand(args),
+            list: (args) => listCommand(args),
+            show: (args) => showCommand(args),
+            check: (args) => checkCommand(args),
+            doctor: (args) => doctorCommand(args),
+            setup: (args) => setupCommand(args),
+            init: (args) => initCommand(args),
+            record: (args) => recordCommand(args, "record"),
+            rehearse: (args) => recordCommand(args, "rehearse"),
+        },
+        getCommandHelp: (command) => COMMAND_HELP[command],
+    });
+}
+//# sourceMappingURL=cli.js.map