screencast-axi 0.1.0

package/dist/src/encode.js

@@ -0,0 +1,225 @@
+import { mkdir, rm, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { detectToolchain, installHint, missingFfmpegError, runOrThrow, } from "./toolchain.js";
+export const DEFAULT_ENCODE_SETTINGS = {
+    width: 1280,
+    fps: 30,
+    mp4: { crf: 23, preset: "slow", profile: "high" },
+    webm: { crf: 34 },
+    poster: { quality: 82 },
+    gif: false,
+    animatedWebp: false,
+    gifWidth: 800,
+    gifFps: 15,
+    animatedWebpQuality: 55,
+};
+const QUIET = ["-y", "-hide_banner", "-loglevel", "error"];
+/**
+ * Turns the raw Playwright capture into web deliverables.
+ *
+ * - mp4  (h264, yuv420p, faststart) - the one a page plays.
+ * - webm (vp9) - smaller, served first via `<source>`.
+ * - poster - the frame shown before the video decodes, so nothing pops in.
+ * - gif  - optional, opt-in.
+ */
+export async function encode(opts) {
+    const toolchain = opts.toolchain ?? (await detectToolchain());
+    if (!toolchain.ffmpeg)
+        throw missingFfmpegError();
+    const ffmpeg = toolchain.ffmpeg.path;
+    await mkdir(opts.outDir, { recursive: true });
+    // Input seek: `-ss` before `-i` is the fast, frame-accurate-enough form for
+    // trimming dead air off the head.
+    const trim = opts.trimStart > 0.05 ? ["-ss", opts.trimStart.toFixed(2)] : [];
+    // `-2` keeps the height even, which h264's yuv420p requires.
+    const scale = `scale=${opts.width}:-2:flags=lanczos`;
+    const mp4 = join(opts.outDir, `${opts.id}.mp4`);
+    const webm = join(opts.outDir, `${opts.id}.webm`);
+    await runOrThrow(ffmpeg, [
+        ...QUIET,
+        ...trim,
+        "-i",
+        opts.input,
+        "-vf",
+        `fps=${opts.fps},${scale}`,
+        "-an",
+        "-c:v",
+        "libx264",
+        "-profile:v",
+        opts.mp4.profile,
+        "-preset",
+        opts.mp4.preset,
+        "-crf",
+        String(opts.mp4.crf),
+        "-pix_fmt",
+        "yuv420p",
+        "-movflags",
+        "+faststart",
+        mp4,
+    ]);
+    await runOrThrow(ffmpeg, [
+        ...QUIET,
+        ...trim,
+        "-i",
+        opts.input,
+        "-vf",
+        `fps=${opts.fps},${scale}`,
+        "-an",
+        "-c:v",
+        "libvpx-vp9",
+        "-crf",
+        String(opts.webm.crf),
+        "-b:v",
+        "0",
+        "-row-mt",
+        "1",
+        "-deadline",
+        "good",
+        webm,
+    ]);
+    const poster = await encodePoster(opts, toolchain, ffmpeg, trim, scale);
+    // Both looping formats come from the same palette pass, so asking for the
+    // pair costs one extra conversion rather than a second encode.
+    let gif;
+    let animatedWebp;
+    if (opts.gif || opts.animatedWebp) {
+        const wantsGif = opts.gif;
+        gif = join(opts.outDir, `${opts.id}.gif`);
+        const palette = join(opts.outDir, `.${opts.id}.palette.png`);
+        const gifScale = `fps=${opts.gifFps},scale=${opts.gifWidth}:-1:flags=lanczos`;
+        await runOrThrow(ffmpeg, [
+            ...QUIET,
+            ...trim,
+            "-i",
+            opts.input,
+            "-vf",
+            `${gifScale},palettegen=max_colors=192:stats_mode=diff`,
+            palette,
+        ]);
+        await runOrThrow(ffmpeg, [
+            ...QUIET,
+            ...trim,
+            "-i",
+            opts.input,
+            "-i",
+            palette,
+            "-lavfi",
+            `${gifScale}[x];[x][1:v]paletteuse=dither=sierra2_4a:diff_mode=rectangle`,
+            "-loop",
+            "0",
+            gif,
+        ]);
+        await rm(palette, { force: true });
+        if (opts.animatedWebp) {
+            // gif2webp rather than ffmpeg: the same builds that lack libwebp for the
+            // poster lack it here too, and gif2webp ships in the same package as the
+            // cwebp the poster already falls back to.
+            const converter = toolchain.gif2webp;
+            if (!converter) {
+                throw new Error("gif2webp was not found, so an animated WebP cannot be produced. " +
+                    `Install it with \`${installHint("cwebp")}\` (same package as cwebp), ` +
+                    "or drop `animatedWebp` and use the GIF.");
+            }
+            animatedWebp = join(opts.outDir, `${opts.id}.anim.webp`);
+            await runOrThrow(converter.path, [
+                "-quiet",
+                "-lossy",
+                "-q",
+                String(opts.animatedWebpQuality),
+                "-m",
+                "6",
+                gif,
+                "-o",
+                animatedWebp,
+            ]);
+        }
+        if (!wantsGif) {
+            await rm(gif, { force: true });
+            gif = undefined;
+        }
+    }
+    const sizes = {};
+    for (const file of [mp4, webm, poster, gif, animatedWebp].filter((f) => Boolean(f))) {
+        sizes[basename(file)] = (await stat(file)).size;
+    }
+    return {
+        mp4,
+        webm,
+        poster,
+        ...(gif ? { gif } : {}),
+        ...(animatedWebp ? { animatedWebp } : {}),
+        sizes,
+        posterEncoder: toolchain.posterEncoder,
+    };
+}
+/**
+ * The poster, by whichever route this machine can take.
+ *
+ * WebP matters here: a 1280x800 screenshot of an app is roughly 300 KB as PNG
+ * and 40 KB as WebP, and a page loads every poster up front because it is the
+ * frame a not-yet-playing clip shows. But WebP is an optimisation, not a
+ * requirement - falling back to PNG keeps a recording working on a machine
+ * with neither encoder.
+ */
+async function encodePoster(opts, toolchain, ffmpeg, trim, scale) {
+    if (toolchain.posterEncoder === "png") {
+        const png = join(opts.outDir, `${opts.id}.png`);
+        await runOrThrow(ffmpeg, [
+            ...QUIET,
+            ...trim,
+            "-i",
+            opts.input,
+            "-vf",
+            scale,
+            "-frames:v",
+            "1",
+            png,
+        ]);
+        return png;
+    }
+    const webp = join(opts.outDir, `${opts.id}.webp`);
+    if (toolchain.posterEncoder === "ffmpeg") {
+        await runOrThrow(ffmpeg, [
+            ...QUIET,
+            ...trim,
+            "-i",
+            opts.input,
+            "-vf",
+            scale,
+            "-frames:v",
+            "1",
+            "-c:v",
+            "libwebp",
+            "-quality",
+            String(opts.poster.quality),
+            webp,
+        ]);
+        return webp;
+    }
+    // cwebp: extract a frame, convert, drop the intermediate.
+    const frame = join(opts.outDir, `.${opts.id}.poster.png`);
+    await runOrThrow(ffmpeg, [
+        ...QUIET,
+        ...trim,
+        "-i",
+        opts.input,
+        "-vf",
+        scale,
+        "-frames:v",
+        "1",
+        frame,
+    ]);
+    await runOrThrow(toolchain.cwebp?.path ?? "cwebp", [
+        "-quiet",
+        "-q",
+        String(opts.poster.quality),
+        "-m",
+        "6",
+        frame,
+        "-o",
+        webp,
+    ]);
+    await rm(frame, { force: true });
+    return webp;
+}
+//# sourceMappingURL=encode.js.map

package/dist/src/encode.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The library's own error type. Zero dependencies, on purpose.
+ *
+ * `axi-sdk-js` is ESM-only with an `import`-only export map, so anything that
+ * imports it cannot be resolved through a CJS path - which is exactly how a
+ * TypeScript config file gets loaded, and how a bundler may resolve a website's
+ * build-time import of `screencast-axi/manifest`.
+ *
+ * So the SDK stays behind the CLI boundary: everything else throws this, and
+ * `cli.ts` converts it to an `AxiError` on the way out. The structure matches
+ * what the SDK renders - a message, a machine-readable code and actionable
+ * suggestions - so nothing is lost in the conversion.
+ */
+export declare class ScreencastError extends Error {
+    readonly code: string;
+    readonly suggestions: string[];
+    constructor(message: string, code: string, suggestions?: string[]);
+}
+export declare function isScreencastError(value: unknown): value is ScreencastError;

package/dist/src/errors.js

@@ -0,0 +1,27 @@
+/**
+ * The library's own error type. Zero dependencies, on purpose.
+ *
+ * `axi-sdk-js` is ESM-only with an `import`-only export map, so anything that
+ * imports it cannot be resolved through a CJS path - which is exactly how a
+ * TypeScript config file gets loaded, and how a bundler may resolve a website's
+ * build-time import of `screencast-axi/manifest`.
+ *
+ * So the SDK stays behind the CLI boundary: everything else throws this, and
+ * `cli.ts` converts it to an `AxiError` on the way out. The structure matches
+ * what the SDK renders - a message, a machine-readable code and actionable
+ * suggestions - so nothing is lost in the conversion.
+ */
+export class ScreencastError extends Error {
+    code;
+    suggestions;
+    constructor(message, code, suggestions = []) {
+        super(message);
+        this.name = "ScreencastError";
+        this.code = code;
+        this.suggestions = suggestions;
+    }
+}
+export function isScreencastError(value) {
+    return value instanceof ScreencastError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAS;IACb,WAAW,CAAW;IAE/B,YAAY,OAAe,EAAE,IAAY,EAAE,WAAW,GAAa,EAAE;QACnE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,KAAK,YAAY,eAAe,CAAC;AAC1C,CAAC"}

package/dist/src/flags.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Spec-driven flag parsing.
+ *
+ * The SDK owns the shape of the invocation (`<bin> <command> ...`) but not the
+ * flags inside a command, so this fills that gap with one rule: an unknown
+ * flag is a usage error, never a silently dropped argument. A dropped flag is
+ * worse than an error - the command appears to succeed while doing something
+ * the caller did not ask for - and an agent that cannot see the mistake will
+ * repeat it.
+ *
+ * Errors are self-correcting in one turn: they name the offending flag, the
+ * nearest real one when there is a plausible match, and the full list of what
+ * this command accepts, so nothing has to go and read `--help` to recover.
+ */
+export type FlagValue = string | number | boolean | string[];
+export interface FlagSpec {
+    readonly kind: "boolean" | "string" | "number";
+    readonly description: string;
+    /** Placeholder shown in help, e.g. `dir` renders as `--out <dir>`. */
+    readonly placeholder?: string;
+    /** Collect every occurrence instead of keeping the last. String flags only. */
+    readonly repeat?: boolean;
+}
+export type FlagSpecs = Record<string, FlagSpec>;
+export interface ParsedArgs {
+    readonly positionals: readonly string[];
+    readonly flags: Readonly<Record<string, FlagValue>>;
+}
+/** The closest known flag to `input`, when one is close enough to mean it. */
+export declare function nearestFlag(input: string, known: readonly string[]): string | null;
+/**
+ * Parses `args` against `specs`.
+ *
+ * Supports `--flag value`, `--flag=value`, `--no-flag` for booleans, and `--`
+ * to stop flag parsing. Everything else is a positional.
+ */
+export declare function parseFlags(args: readonly string[], specs: FlagSpecs): ParsedArgs;
+/** Renders a command's flags for its `--help` block. */
+export declare function renderFlagHelp(specs: FlagSpecs): string[];

package/dist/src/flags.js

@@ -0,0 +1,130 @@
+import { ScreencastError } from "./errors.js";
+/**
+ * Levenshtein distance, bounded by the shorter string. Used only to decide
+ * whether a typo is close enough to a real flag to be worth suggesting.
+ */
+function distance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, i) => i);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i, ...Array(cols - 1).fill(0)];
+        for (let j = 1; j < cols; j++) {
+            const substitution = (prev[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            const deletion = (prev[j] ?? 0) + 1;
+            const insertion = (curr[j - 1] ?? 0) + 1;
+            curr[j] = Math.min(substitution, deletion, insertion);
+        }
+        prev = curr;
+    }
+    return prev[cols - 1] ?? Math.max(a.length, b.length);
+}
+/** The closest known flag to `input`, when one is close enough to mean it. */
+export function nearestFlag(input, known) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const candidate of known) {
+        const d = distance(input, candidate);
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = candidate;
+        }
+    }
+    // Two edits on a short flag is already a different flag, not a typo.
+    return best !== null && bestDistance <= Math.max(2, Math.floor(input.length / 3)) ? best : null;
+}
+function usage(specs) {
+    const names = Object.keys(specs);
+    return names.length > 0 ? `Accepts: ${names.map((n) => `--${n}`).join(", ")}` : "";
+}
+function unknownFlag(name, specs) {
+    const known = Object.keys(specs);
+    const near = nearestFlag(name, known);
+    const help = [
+        ...(near ? [`Did you mean \`--${near}\`?`] : []),
+        ...(known.length > 0 ? [usage(specs)] : ["This command accepts no flags"]),
+    ];
+    throw new ScreencastError(`Unknown flag: --${name}`, "VALIDATION_ERROR", help);
+}
+function numeric(name, raw) {
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new ScreencastError(`--${name} expects a number, got \`${raw}\``, "VALIDATION_ERROR", [
+            `Example: --${name} 30`,
+        ]);
+    }
+    return value;
+}
+/**
+ * Parses `args` against `specs`.
+ *
+ * Supports `--flag value`, `--flag=value`, `--no-flag` for booleans, and `--`
+ * to stop flag parsing. Everything else is a positional.
+ */
+export function parseFlags(args, specs) {
+    const positionals = [];
+    const flags = {};
+    let literal = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (literal || !arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            literal = true;
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const name = (eq === -1 ? arg.slice(2) : arg.slice(2, eq)).trim();
+        const inlineValue = eq === -1 ? null : arg.slice(eq + 1);
+        // `--no-x` turns off a boolean `x`. Only meaningful for booleans, so an
+        // unknown `--no-y` still reports the flag the caller actually typed.
+        if (!specs[name] && name.startsWith("no-") && specs[name.slice(3)]?.kind === "boolean") {
+            flags[name.slice(3)] = false;
+            continue;
+        }
+        const spec = specs[name];
+        if (!spec)
+            unknownFlag(name, specs);
+        if (spec.kind === "boolean") {
+            if (inlineValue !== null && inlineValue !== "true" && inlineValue !== "false") {
+                throw new ScreencastError(`--${name} is a switch and takes no value`, "VALIDATION_ERROR", [
+                    `Pass \`--${name}\` on its own, or \`--no-${name}\` to turn it off`,
+                ]);
+            }
+            flags[name] = inlineValue !== "false";
+            continue;
+        }
+        const raw = inlineValue ?? args[++i];
+        if (raw === undefined) {
+            throw new ScreencastError(`--${name} expects a value`, "VALIDATION_ERROR", [
+                `Pass it as \`--${name} <${spec.placeholder ?? "value"}>\``,
+            ]);
+        }
+        if (spec.kind === "number") {
+            flags[name] = numeric(name, raw);
+        }
+        else if (spec.repeat) {
+            const existing = flags[name];
+            flags[name] = Array.isArray(existing) ? [...existing, raw] : [raw];
+        }
+        else {
+            flags[name] = raw;
+        }
+    }
+    return { positionals, flags };
+}
+/** Renders a command's flags for its `--help` block. */
+export function renderFlagHelp(specs) {
+    const entries = Object.entries(specs);
+    if (entries.length === 0)
+        return [];
+    const rendered = entries.map(([name, spec]) => ({
+        left: spec.kind === "boolean" ? `--${name}` : `--${name} <${spec.placeholder ?? "value"}>`,
+        description: spec.description,
+    }));
+    const width = Math.max(...rendered.map((r) => r.left.length));
+    return rendered.map((r) => `  ${r.left.padEnd(width)}  ${r.description}`);
+}
+//# sourceMappingURL=flags.js.map

package/dist/src/flags.js.map

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

package/dist/src/forensics.d.ts

@@ -0,0 +1,51 @@
+import type { Page } from "playwright";
+/**
+ * What a failed take leaves behind.
+ *
+ * Writing a scenario blind is the real cost of scripting rather than driving a
+ * browser live: a stale selector surfaces as a bare `TimeoutError`, with no
+ * page, no URL and nothing to look at, and the next attempt is another minute
+ * of guessing. Capturing the page's state before the context closes turns that
+ * into one sighted iteration, which is most of what a live session would have
+ * bought.
+ *
+ * All of it is written to disk and reported as absolute paths - never inlined
+ * into the output, where a screenshot would be megabytes of base64 nobody
+ * asked for.
+ */
+export interface NearMatch {
+    readonly selector: string;
+    readonly count: number;
+    readonly visible: boolean;
+}
+export interface Forensics {
+    readonly url?: string;
+    readonly title?: string;
+    readonly screenshot?: string;
+    readonly html?: string;
+    readonly nearMatches?: readonly NearMatch[];
+    /** Anything that went wrong while collecting the above. */
+    readonly notes?: readonly string[];
+}
+/**
+ * Selector fragments worth reporting counts for.
+ *
+ * A descendant selector that matches nothing tells you nothing about *which*
+ * part is wrong. Its pieces do: if `.grid` matches once and `.grid .row`
+ * matches zero times, the container rendered and the rows did not, which is a
+ * data problem rather than a selector typo.
+ */
+export declare function selectorCandidates(selector: string): string[];
+/** Pulls a CSS selector out of a Playwright timeout message, if there is one. */
+export declare function selectorFromError(message: string): string | null;
+export interface CaptureOptions {
+    readonly page: Page;
+    readonly rawDir: string;
+    readonly id: string;
+    readonly error: unknown;
+}
+/**
+ * Collects everything useful about a failure. Never throws: a problem here
+ * must not replace the scenario's own error with a worse one.
+ */
+export declare function captureFailure(options: CaptureOptions): Promise<Forensics>;

package/dist/src/forensics.js

@@ -0,0 +1,107 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Selector fragments worth reporting counts for.
+ *
+ * A descendant selector that matches nothing tells you nothing about *which*
+ * part is wrong. Its pieces do: if `.grid` matches once and `.grid .row`
+ * matches zero times, the container rendered and the rows did not, which is a
+ * data problem rather than a selector typo.
+ */
+export function selectorCandidates(selector) {
+    const trimmed = selector.trim();
+    if (!trimmed || /[>~+]/.test(trimmed))
+        return [trimmed].filter(Boolean);
+    const parts = trimmed.split(/\s+/).filter(Boolean);
+    if (parts.length < 2)
+        return [trimmed];
+    const candidates = [];
+    // Progressively shorter prefixes, then the trailing piece on its own.
+    for (let i = parts.length - 1; i >= 1; i--) {
+        candidates.push(parts.slice(0, i).join(" "));
+    }
+    const last = parts[parts.length - 1];
+    if (last && !candidates.includes(last))
+        candidates.push(last);
+    return candidates;
+}
+/** Pulls a CSS selector out of a Playwright timeout message, if there is one. */
+export function selectorFromError(message) {
+    const patterns = [
+        /waiting for locator\('([^']+)'\)/,
+        /locator\('([^']+)'\)/,
+        /selector "([^"]+)"/,
+        /no element matched "([^"]+)"/,
+    ];
+    for (const pattern of patterns) {
+        const match = pattern.exec(message);
+        if (match?.[1])
+            return match[1];
+    }
+    return null;
+}
+async function probe(page, selector) {
+    try {
+        const locator = page.locator(selector);
+        const count = await locator.count();
+        const visible = count > 0
+            ? await locator
+                .first()
+                .isVisible()
+                .catch(() => false)
+            : false;
+        return { selector, count, visible };
+    }
+    catch {
+        return { selector, count: 0, visible: false };
+    }
+}
+/**
+ * Collects everything useful about a failure. Never throws: a problem here
+ * must not replace the scenario's own error with a worse one.
+ */
+export async function captureFailure(options) {
+    const { page, rawDir, id, error } = options;
+    const notes = [];
+    const result = {};
+    try {
+        await mkdir(rawDir, { recursive: true });
+    }
+    catch {
+        return { notes: ["could not create the scratch directory"] };
+    }
+    try {
+        result.url = page.url();
+    }
+    catch {
+        notes.push("page was already closed");
+        return { ...result, notes };
+    }
+    try {
+        result.title = await page.title();
+    }
+    catch {
+        notes.push("could not read the page title");
+    }
+    try {
+        const screenshot = join(rawDir, `${id}.failure.png`);
+        await page.screenshot({ path: screenshot, fullPage: false });
+        result.screenshot = screenshot;
+    }
+    catch {
+        notes.push("could not take a screenshot");
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const selector = selectorFromError(message);
+    if (selector) {
+        const candidates = selectorCandidates(selector);
+        const matches = [];
+        for (const candidate of candidates.slice(0, 4)) {
+            matches.push(await probe(page, candidate));
+        }
+        if (matches.length > 0)
+            result.nearMatches = matches;
+    }
+    return { ...result, ...(notes.length > 0 ? { notes } : {}) };
+}
+//# sourceMappingURL=forensics.js.map

package/dist/src/forensics.js.map

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

package/dist/src/hooks.d.ts

@@ -0,0 +1,9 @@
+import type { AxiStructuredOutput } from "./output.js";
+/**
+ * Session integration.
+ *
+ * The AXI convention is a setup command that registers hooks with the agent
+ * harness, so the tool is ambient rather than something to remember. That is
+ * not built yet, and saying so beats registering something that does nothing.
+ */
+export declare function installHooks(scope: string | undefined): AxiStructuredOutput;

package/dist/src/hooks.js

@@ -0,0 +1,20 @@
+import { ScreencastError } from "./errors.js";
+/**
+ * Session integration.
+ *
+ * The AXI convention is a setup command that registers hooks with the agent
+ * harness, so the tool is ambient rather than something to remember. That is
+ * not built yet, and saying so beats registering something that does nothing.
+ */
+export function installHooks(scope) {
+    if (scope && scope !== "user" && scope !== "project") {
+        throw new ScreencastError("--scope must be user or project", "VALIDATION_ERROR", [
+            "Example: --scope project",
+        ]);
+    }
+    throw new ScreencastError("Session hooks are not implemented yet", "NOT_IMPLEMENTED", [
+        "Install the skill instead: `npx skills add Valzon/screencast-axi --skill screencast-axi -g`",
+        "The CLI works without either - `npx -y screencast-axi --help`",
+    ]);
+}
+//# sourceMappingURL=hooks.js.map