screencast-axi 0.1.0

package/dist/src/commands/record.js

@@ -0,0 +1,266 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { loadConfig, loadScenarioFiles, loadScenarios } from "../config.js";
+import { ScreencastError } from "../errors.js";
+import { parseFlags } from "../flags.js";
+import { ScenarioFailure, runScenario } from "../run.js";
+import { parseDuration, solvePace } from "../duration.js";
+import { detectToolchain } from "../toolchain.js";
+const SHARED = {
+    config: { kind: "string", description: "Path to a config file", placeholder: "path" },
+    "base-url": {
+        kind: "string",
+        description: "Override the scenario's base URL",
+        placeholder: "url",
+    },
+    pace: { kind: "number", description: "Speed multiplier; lower is faster" },
+    device: { kind: "string", description: "Playwright device preset", placeholder: "name" },
+    viewport: { kind: "string", description: "Explicit size, e.g. 390x844", placeholder: "WxH" },
+    orientation: { kind: "string", description: "portrait or landscape", placeholder: "o" },
+    headed: { kind: "boolean", description: "Watch it happen in a real browser window" },
+    auth: { kind: "string", description: "Named auth strategy from the config", placeholder: "name" },
+    "no-auth": { kind: "boolean", description: "Record signed out" },
+};
+export const RECORD_FLAGS = {
+    ...SHARED,
+    duration: {
+        kind: "string",
+        description: "Aim for this length, e.g. 30s (measures first, then solves for pace)",
+        placeholder: "30s",
+    },
+    out: { kind: "string", description: "Output directory", placeholder: "dir" },
+    all: { kind: "boolean", description: "Record every scenario the config lists" },
+    full: { kind: "boolean", description: "Include the full action log" },
+    gif: { kind: "boolean", description: "Also emit a looping GIF" },
+    webp: { kind: "boolean", description: "Also emit a looping WebP (half a GIF's size)" },
+    "loop-width": { kind: "number", description: "Width of the looping formats" },
+    "loop-fps": { kind: "number", description: "Frame rate of the looping formats" },
+    "keep-raw": { kind: "boolean", description: "Keep the raw capture for inspection" },
+};
+export const REHEARSE_FLAGS = SHARED;
+/**
+ * Resolves ids or file paths to scenarios.
+ *
+ * A path is accepted as well as an id so a first run needs no config: someone
+ * recording one page of a site they do not own should be able to write a file
+ * and point at it.
+ */
+async function select(targets, config, all) {
+    const paths = targets.filter((t) => t.includes("/") || t.endsWith(".ts") || t.endsWith(".mjs"));
+    const ids = targets.filter((t) => !paths.includes(t));
+    const loaded = [
+        ...(paths.length > 0
+            ? await loadScenarioFiles(paths.map((p) => (isAbsolute(p) ? p : resolve(process.cwd(), p))))
+            : []),
+        ...(ids.length > 0 || all ? await loadScenarios(config) : []),
+    ];
+    if (all)
+        return loaded;
+    const chosen = [];
+    for (const id of ids) {
+        const match = loaded.find((l) => l.scenario.id === id);
+        if (!match) {
+            const known = loaded.map((l) => l.scenario.id);
+            throw new ScreencastError(`Unknown scenario: ${id}`, "UNKNOWN_SCENARIO", [
+                known.length > 0
+                    ? `This config knows: ${known.join(", ")}`
+                    : "No scenarios are configured. Create one with `screencast-axi scaffold <id>`",
+                "You can also pass a file path instead of an id",
+            ]);
+        }
+        chosen.push(match);
+    }
+    for (const path of paths) {
+        const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+        for (const l of loaded.filter((l) => l.file === absolute))
+            chosen.push(l);
+    }
+    return chosen;
+}
+function viewportOf(value) {
+    if (value === undefined)
+        return undefined;
+    const match = /^(\d+)\s*[x×]\s*(\d+)$/.exec(String(value).trim());
+    if (!match) {
+        throw new ScreencastError(`--viewport must look like 1280x800`, "VALIDATION_ERROR", [
+            "Example: --viewport 390x844",
+            'Or use a device preset: --device "iPhone 13"',
+        ]);
+    }
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+function orientationOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== "portrait" && value !== "landscape") {
+        throw new ScreencastError(`--orientation must be portrait or landscape`, "VALIDATION_ERROR", [
+            "Example: --orientation portrait",
+        ]);
+    }
+    return value;
+}
+/**
+ * The action log, trimmed for reading.
+ *
+ * Full detail is behind `--full`: a long tour is dozens of lines, and the
+ * point of the short form is that someone can scan it.
+ */
+function performed(result, full) {
+    const rows = result.performed.map((a) => ({
+        at_s: Number((a.atMs / 1000).toFixed(1)),
+        did: a.kind,
+        ...(a.target ? { target: truncate(a.target, full) } : {}),
+        ...(a.detail ? { detail: truncate(a.detail, full) } : {}),
+    }));
+    return full ? rows : rows.slice(0, 24);
+}
+function truncate(text, full) {
+    return full || text.length <= 70 ? text : `${text.slice(0, 67)}...`;
+}
+function describe(result, solution) {
+    const files = result.encoded
+        ? Object.entries(result.encoded.sizes).map(([name, bytes]) => ({
+            file: name,
+            kb: Math.round(bytes / 1024),
+        }))
+        : [];
+    return {
+        [result.mode === "record" ? "recorded" : "rehearsed"]: result.id,
+        duration_s: Number((result.durationMs / 1000).toFixed(1)),
+        pace: result.pace,
+        viewport: `${result.viewport.viewport.width}x${result.viewport.viewport.height}`,
+        ...(solution
+            ? {
+                target_s: Number((solution.targetMs / 1000).toFixed(1)),
+                natural_s: Number((solution.naturalMs / 1000).toFixed(1)),
+                ...(solution.warning ? { warning: solution.warning } : {}),
+            }
+            : {}),
+        ...(result.viewport.device ? { device: result.viewport.device } : {}),
+        ...(result.identity ? { as: result.identity.label } : {}),
+        ...(files.length > 0 ? { files } : {}),
+        ...(result.steps.length > 0 ? { steps: result.steps } : {}),
+        ...(result.manifestPath ? { manifest: result.manifestPath } : {}),
+    };
+}
+export async function recordCommand(args, mode) {
+    const specs = mode === "record" ? RECORD_FLAGS : REHEARSE_FLAGS;
+    const { positionals, flags } = parseFlags(args, specs);
+    const all = flags["all"] === true;
+    if (positionals.length === 0 && !all) {
+        throw new ScreencastError("Nothing to run", "VALIDATION_ERROR", [
+            `Name a scenario: \`screencast-axi ${mode} <id>\``,
+            `Or a file: \`screencast-axi ${mode} ./scenarios/tour.ts\``,
+            "Or `--all` to run every scenario the config lists",
+        ]);
+    }
+    const config = await loadConfig(flags["config"]);
+    const selected = await select(positionals, config, all);
+    if (selected.length === 0) {
+        return { [mode]: [], totals: "0 scenarios matched", help: ["Run `screencast-axi list`"] };
+    }
+    // Probed once for the batch rather than per clip, and before any browser
+    // opens - a missing ffmpeg should not cost a forty-second take first.
+    const toolchain = mode === "record" ? await detectToolchain() : undefined;
+    const orientation = orientationOf(flags["orientation"]);
+    const viewport = viewportOf(flags["viewport"]);
+    const targetMs = flags["duration"] !== undefined ? parseDuration(flags["duration"]) : null;
+    // Looping formats are for the places a <video> does not render. They are far
+    // heavier than the mp4, so they stay opt-in per run.
+    const loops = flags["gif"] === true ||
+        flags["webp"] === true ||
+        flags["loop-width"] !== undefined ||
+        flags["loop-fps"] !== undefined
+        ? {
+            ...(flags["gif"] === true ? { gif: true } : {}),
+            ...(flags["webp"] === true ? { animatedWebp: true } : {}),
+            ...(flags["loop-width"] !== undefined ? { gifWidth: flags["loop-width"] } : {}),
+            ...(flags["loop-fps"] !== undefined ? { gifFps: flags["loop-fps"] } : {}),
+        }
+        : null;
+    const results = [];
+    const solutions = new Map();
+    for (const { scenario, file } of selected) {
+        const sourceText = await readFile(file, "utf8").catch(() => undefined);
+        // Everything except the mode and the pace, which the measuring pass and
+        // the real take each set for themselves.
+        const base = {
+            scenario,
+            config,
+            ...(sourceText ? { sourceText } : {}),
+            ...(flags["base-url"] ? { baseUrl: flags["base-url"] } : {}),
+            ...(flags["out"] ? { outDir: resolve(process.cwd(), flags["out"]) } : {}),
+            ...(flags["device"] ? { device: flags["device"] } : {}),
+            ...(orientation ? { orientation } : {}),
+            ...(flags["headed"] === true ? { headed: true } : {}),
+            ...(flags["keep-raw"] === true ? { keepRaw: true } : {}),
+            ...(flags["no-auth"] === true
+                ? { auth: false }
+                : flags["auth"]
+                    ? { auth: flags["auth"] }
+                    : {}),
+            ...(viewport ? { viewport } : {}),
+            ...(loops ? { deliverables: loops } : {}),
+            ...(toolchain ? { toolchain } : {}),
+            // stderr: stdout stays reserved for the final payload.
+            log: (message) => void process.stderr.write(`${message}\n`),
+        };
+        let pace = flags["pace"];
+        if (targetMs !== null) {
+            // Measured, not assumed: a scenario's length is only roughly linear in
+            // pace, because the app's own waits do not scale with it. One no-encode
+            // pass is the cheapest honest way to learn the natural length.
+            process.stderr.write(`${scenario.id}: measuring for a ${targetMs / 1000}s target\n`);
+            const probe = await runScenario({ ...base, mode: "rehearse", pace: 1 });
+            const solution = solvePace(probe.durationMs, targetMs, probe.scaledPauseMs);
+            solutions.set(scenario.id, solution);
+            pace = solution.pace;
+            if (solution.warning)
+                process.stderr.write(`${scenario.id}: ${solution.warning}\n`);
+        }
+        results.push(await runScenario({ ...base, mode, ...(pace !== undefined ? { pace } : {}) }));
+    }
+    if (results.length === 1) {
+        const only = results[0];
+        const full = flags["full"] === true;
+        // A rehearsal is where someone checks what a scenario does before trusting
+        // it, so the log is the point of the output rather than an extra.
+        const showLog = mode === "rehearse" || full;
+        return {
+            ...describe(only, solutions.get(only.id)),
+            ...(only.hosts.length > 0 ? { hosts: only.hosts } : {}),
+            ...(showLog ? { performed: performed(only, full) } : {}),
+            help: nextSteps(only, showLog),
+        };
+    }
+    return {
+        [mode === "record" ? "recorded" : "rehearsed"]: results.map((r) => ({
+            id: r.id,
+            duration_s: Number((r.durationMs / 1000).toFixed(1)),
+        })),
+        totals: `${results.length} scenarios`,
+        help: [`Run \`screencast-axi show <id>\` for one clip in full`],
+    };
+}
+function nextSteps(result, showedLog = false) {
+    if (result.mode === "rehearse") {
+        return [
+            ...(showedLog
+                ? [
+                    "`performed` above is every action the scenario took - read it before trusting a script you did not write",
+                ]
+                : []),
+            `Selectors and narration hold. Run \`screencast-axi record ${result.id}\` for the real take`,
+            "A rehearsal runs faster than a take, so it can trip on an animation a recording would wait out",
+        ];
+    }
+    return [
+        ...(showedLog ? [] : ["Add `--full` to see every action the scenario took"]),
+        `The clip is ${(result.durationMs / 1000).toFixed(1)}s. Re-cut it with \`screencast-axi record ${result.id} --pace 0.8\` (lower is faster)`,
+        result.manifestPath
+            ? `Title, description and steps are in ${relative(process.cwd(), result.manifestPath)} for a site to read`
+            : "",
+    ].filter(Boolean);
+}
+export { ScenarioFailure };
+//# sourceMappingURL=record.js.map

package/dist/src/commands/record.js.map

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

package/dist/src/commands/scaffold.d.ts

@@ -0,0 +1,4 @@
+import { type FlagSpecs } from "../flags.js";
+import type { AxiStructuredOutput } from "../output.js";
+export declare const SCAFFOLD_FLAGS: FlagSpecs;
+export declare function scaffoldCommand(args: string[]): AxiStructuredOutput;

package/dist/src/commands/scaffold.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { ScreencastError } from "../errors.js";
+import { parseFlags } from "../flags.js";
+export const SCAFFOLD_FLAGS = {
+    url: { kind: "string", description: "Base URL the scenario opens", placeholder: "url" },
+    title: { kind: "string", description: "Human title for the clip", placeholder: "text" },
+    dir: { kind: "string", description: "Where to write it", placeholder: "path" },
+    tour: { kind: "number", description: "Write an n-stop page walkthrough instead" },
+    device: { kind: "string", description: "Playwright device preset", placeholder: "name" },
+};
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function titleFrom(id) {
+    const words = id.split("-");
+    const first = words[0] ?? id;
+    return [first.charAt(0).toUpperCase() + first.slice(1), ...words.slice(1)].join(" ");
+}
+/**
+ * A scenario skeleton, so the boilerplate is never the thing that goes wrong.
+ *
+ * This is what makes a TypeScript-only authoring format cheap: the author -
+ * often an agent - supplies only the `run()` body and the narration, not the
+ * imports, the id or the shape.
+ */
+function template(id, title, url, device) {
+    return `import { defineScenario } from "screencast-axi";
+
+export default defineScenario({
+  id: ${JSON.stringify(id)},
+  title: ${JSON.stringify(title)},
+  description: "TODO: one line describing what this clip shows.",
+  baseUrl: ${JSON.stringify(url)},${device ? `\n  device: ${JSON.stringify(device)},` : ""}
+
+  // Each line goes on screen once, in order, via d.step(i). The same array
+  // becomes the manifest's step list, so the workflow is readable without
+  // watching the video.
+  steps: ["TODO: the first beat", "TODO: the second beat"],
+
+  async run(d) {
+    await d.goto("/");
+    await d.step(0, 900);
+
+    // TODO: drive the page. d.click, d.type, d.drag, d.scrollBy, d.waitFor.
+    // Reach past them with d.page for anything they do not cover.
+
+    await d.step(1, 1200);
+  },
+});
+`;
+}
+function tourTemplate(id, title, url, stops, device) {
+    const paths = ["/", "/pricing", "/docs", "/blog", "/contact"];
+    const chosen = Array.from({ length: stops }, (_, i) => paths[i] ?? `/page-${i + 1}`);
+    return `import { defineScenario } from "screencast-axi";
+
+export default defineScenario({
+  id: ${JSON.stringify(id)},
+  title: ${JSON.stringify(title)},
+  description: "TODO: one line describing what this walkthrough shows.",
+  baseUrl: ${JSON.stringify(url)},${device ? `\n  device: ${JSON.stringify(device)},` : ""}
+
+  // One line per stop, in the order they appear.
+  steps: [
+${chosen.map((_, i) => `    "TODO: what stop ${i + 1} shows",`).join("\n")}
+  ],
+
+  async run(d) {
+${chosen
+        .map((path, i) => `    await d.goto(${JSON.stringify(path)});\n` +
+        `    await d.step(${i}, 1200);\n` +
+        `    await d.scrollBy(500);`)
+        .join("\n\n")}
+  },
+});
+`;
+}
+export function scaffoldCommand(args) {
+    const { positionals, flags } = parseFlags(args, SCAFFOLD_FLAGS);
+    const id = positionals[0];
+    if (!id) {
+        throw new ScreencastError("Name the scenario", "VALIDATION_ERROR", [
+            "Run `screencast-axi scaffold <id> --url <url>`",
+            "The id is the output file stem, e.g. `product-tour`",
+        ]);
+    }
+    if (!ID_PATTERN.test(id)) {
+        // The id is a file stem, so it has to be safe on every filesystem and
+        // usable in a URL without escaping.
+        throw new ScreencastError(`Invalid id: ${id}`, "VALIDATION_ERROR", [
+            "Use lower-case words joined by dashes, e.g. `product-tour`",
+            "The id becomes the file name of every deliverable",
+        ]);
+    }
+    const url = flags["url"] ?? "http://localhost:3000";
+    const title = flags["title"] ?? titleFrom(id);
+    const device = flags["device"];
+    const dir = resolve(process.cwd(), flags["dir"] ?? "scenarios");
+    const file = join(dir, `${id}.ts`);
+    if (existsSync(file)) {
+        throw new ScreencastError(`Already exists: ${file}`, "ALREADY_EXISTS", [
+            "Edit it, or pick a different id",
+        ]);
+    }
+    const stops = flags["tour"];
+    const body = stops !== undefined
+        ? tourTemplate(id, title, url, Math.max(1, Math.min(12, Math.round(stops))), device)
+        : template(id, title, url, device);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, body);
+    return {
+        created: file,
+        id,
+        help: [
+            `Fill in the TODOs in ${relative(process.cwd(), file)}, then run \`screencast-axi rehearse ${relative(process.cwd(), file)}\``,
+            "Rehearsing runs the scenario without encoding, so a wrong selector shows up in seconds",
+            "Record it once it rehearses clean: `screencast-axi record " +
+                relative(process.cwd(), file) +
+                "`",
+        ],
+    };
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/src/commands/scaffold.js.map

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

package/dist/src/commands/setup.d.ts

@@ -0,0 +1,14 @@
+import { type FlagSpecs } from "../flags.js";
+import type { AxiStructuredOutput } from "../output.js";
+export declare const SETUP_FLAGS: FlagSpecs;
+export declare const INIT_FLAGS: FlagSpecs;
+/**
+ * Does what can be done safely, and names what cannot.
+ *
+ * Downloading a browser is expected and reversible, so it happens. Installing
+ * a system package is not something this should do behind anyone's back - a
+ * tool that shells out to a package manager inside an agent loop is not one
+ * you want - so a missing ffmpeg is reported with the exact command instead.
+ */
+export declare function setupCommand(args: string[]): Promise<AxiStructuredOutput>;
+export declare function initCommand(args: string[]): AxiStructuredOutput;

package/dist/src/commands/setup.js

@@ -0,0 +1,137 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { installHooks } from "../hooks.js";
+import { ScreencastError } from "../errors.js";
+import { parseFlags } from "../flags.js";
+import { detectToolchain, installHint, run } from "../toolchain.js";
+import { CONFIG_BASENAMES } from "../config.js";
+export const SETUP_FLAGS = {
+    "browsers-only": { kind: "boolean", description: "Install Chromium and stop" },
+    scope: { kind: "string", description: "For `setup hooks`: user or project", placeholder: "s" },
+};
+export const INIT_FLAGS = {
+    out: { kind: "string", description: "Where clips should be written", placeholder: "dir" },
+    url: { kind: "string", description: "Base URL for the site you record", placeholder: "url" },
+    force: { kind: "boolean", description: "Overwrite an existing config" },
+};
+/**
+ * Does what can be done safely, and names what cannot.
+ *
+ * Downloading a browser is expected and reversible, so it happens. Installing
+ * a system package is not something this should do behind anyone's back - a
+ * tool that shells out to a package manager inside an agent loop is not one
+ * you want - so a missing ffmpeg is reported with the exact command instead.
+ */
+export async function setupCommand(args) {
+    const { positionals, flags } = parseFlags(args, SETUP_FLAGS);
+    if (positionals[0] === "hooks") {
+        return installHooks(flags["scope"]);
+    }
+    if (positionals[0]) {
+        throw new ScreencastError(`Unknown setup target: ${positionals[0]}`, "VALIDATION_ERROR", [
+            "`screencast-axi setup` installs the browser and checks the rest",
+            "`screencast-axi setup hooks` registers the session integration",
+        ]);
+    }
+    const done = [];
+    const manual = [];
+    const install = await run("npx", ["--yes", "playwright", "install", "chromium"]);
+    if (install.code === 0) {
+        done.push("chromium installed (or already present)");
+    }
+    else {
+        manual.push("npx playwright install chromium");
+    }
+    if (flags["browsers-only"] !== true) {
+        const toolchain = await detectToolchain();
+        if (toolchain.ffmpeg) {
+            done.push(`ffmpeg found at ${toolchain.ffmpeg.path}`);
+        }
+        else {
+            manual.push(installHint("ffmpeg"));
+        }
+        if (toolchain.posterEncoder === "png") {
+            manual.push(`${installHint("cwebp")}   # optional: smaller posters, and --webp`);
+        }
+    }
+    return {
+        done,
+        ...(manual.length > 0 ? { "run yourself": manual } : {}),
+        totals: manual.length === 0 ? "ready to record" : `${manual.length} thing(s) need installing by hand`,
+        help: manual.length === 0
+            ? ["`screencast-axi doctor` confirms it, `scaffold <id>` starts a scenario"]
+            : [
+                "These are system packages, so they are not installed for you",
+                "`screencast-axi doctor` re-checks once they are in place",
+            ],
+    };
+}
+const TEMPLATE = (outDir, url) => `import { defineConfig } from "screencast-axi";
+
+export default defineConfig({
+  // Origin only. A baseUrl carrying a path is a trap: \`goto("/")\` resolves
+  // against the origin and silently drops the path.
+  baseUrl: ${JSON.stringify(url)},
+
+  scenarios: ["scenarios/*.ts"],
+  outDir: ${JSON.stringify(outDir)},
+
+  viewport: { width: 1440, height: 900 },
+
+  // Uncomment to record pages behind a login. A person then runs
+  // \`screencast-axi auth login --interactive\` once, signs in in the browser
+  // window that opens, and every take afterwards reuses the session.
+  //
+  // browser: { profileDir: ".screencast/profile" },
+  // auth: profileAuth({ signedInSelector: "[data-testid=user-menu]" }),
+
+  overlay: {
+    // Page chrome that should never end up in footage.
+    hideSelectors: [],
+  },
+});
+`;
+const GITIGNORE = `
+# screencast-axi: raw captures, and the profile holding a real session
+.screencast/
+`;
+export function initCommand(args) {
+    const { flags } = parseFlags(args, INIT_FLAGS);
+    const cwd = process.cwd();
+    const existing = CONFIG_BASENAMES.map((n) => join(cwd, n)).find((f) => existsSync(f));
+    if (existing && flags["force"] !== true) {
+        throw new ScreencastError(`A config is already here: ${existing}`, "ALREADY_EXISTS", [
+            "Edit it, or pass `--force` to overwrite it",
+        ]);
+    }
+    const outDir = flags["out"] ?? "screencasts";
+    const url = flags["url"] ?? "http://localhost:3000";
+    const configPath = join(cwd, "screencast.config.ts");
+    writeFileSync(configPath, TEMPLATE(outDir, url));
+    mkdirSync(join(cwd, "scenarios"), { recursive: true });
+    // Appended rather than created: a project almost always has one already, and
+    // the profile directory holds a real signed-in session.
+    const gitignore = join(cwd, ".gitignore");
+    let ignored = false;
+    if (existsSync(gitignore)) {
+        const current = readFileSync(gitignore, "utf8");
+        if (!current.includes(".screencast/")) {
+            appendFileSync(gitignore, GITIGNORE);
+            ignored = true;
+        }
+    }
+    else {
+        writeFileSync(gitignore, GITIGNORE.trimStart());
+        ignored = true;
+    }
+    return {
+        created: relative(cwd, configPath),
+        scenarios: relative(cwd, resolve(cwd, "scenarios")),
+        ...(ignored ? { gitignored: ".screencast/" } : {}),
+        help: [
+            `Write your first scenario: \`screencast-axi scaffold <id> --url ${url}\``,
+            "`screencast-axi doctor` checks ffmpeg and the browser are in place",
+        ],
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/src/commands/setup.js.map

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