@mogulmoretti/skrape 0.1.0

package/dist/tui/App.js

@@ -0,0 +1,285 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { SelectList } from './SelectList.js';
+import { applyProgress, createProgressState, formatProgressBar } from './progress.js';
+import { formatSummary } from './summary.js';
+import { isValidSlug, normalizeSlug } from './slug.js';
+import { MENU_ITEMS, nextStepForMenuChoice } from './flow.js';
+import { revealOutputFolder } from './reveal.js';
+const MAX_ERROR_LINES = 6;
+const MAX_ERROR_CHARS = 800;
+/**
+ * Caps error text shown in the TUI. Some failures (e.g. a raw Playwright
+ * browser-launch error) can be a multi-hundred-line dump — that's useless in
+ * a terminal UI and pushes everything else off screen, so keep only the
+ * first few lines and a hard character cap.
+ */
+export function truncateErrorText(message) {
+    const lines = message.split('\n');
+    const truncatedByLines = lines.length > MAX_ERROR_LINES;
+    const limitedLines = lines.slice(0, MAX_ERROR_LINES).join('\n');
+    const truncatedByChars = limitedLines.length > MAX_ERROR_CHARS;
+    const limited = limitedLines.slice(0, MAX_ERROR_CHARS);
+    return truncatedByLines || truncatedByChars ? `${limited}\n… (truncated)` : limited;
+}
+function errorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return truncateErrorText(message);
+}
+function ConfirmPrompt({ onConfirm }) {
+    const { exit } = useApp();
+    useInput((input, key) => {
+        if (key.return)
+            onConfirm();
+        else if (input === 'q' || key.escape)
+            exit();
+    });
+    return _jsx(Text, { dimColor: true, children: "[enter] continue    [q] quit" });
+}
+function ExitPrompt({ label }) {
+    const { exit } = useApp();
+    useInput(() => exit());
+    return _jsx(Text, { dimColor: true, children: label });
+}
+function ManualSlugInput({ value, onChange, onSubmit, }) {
+    useInput((input, key) => {
+        if (key.return) {
+            onSubmit(value);
+            return;
+        }
+        if (key.backspace || key.delete) {
+            onChange(value.slice(0, -1));
+            return;
+        }
+        if (key.ctrl || key.meta || key.upArrow || key.downArrow || key.leftArrow || key.rightArrow)
+            return;
+        if (input)
+            onChange(value + input);
+    });
+    return null;
+}
+export function App({ controllers }) {
+    const { exit } = useApp();
+    const [step, setStep] = React.useState({ kind: 'checking-session' });
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c')
+            exit();
+    });
+    const fail = React.useCallback((error) => {
+        setStep({ kind: 'error', message: errorMessage(error) });
+    }, []);
+    // Step 1: is the saved Chrome profile signed in?
+    React.useEffect(() => {
+        if (step.kind !== 'checking-session')
+            return;
+        let cancelled = false;
+        controllers
+            .checkLoggedIn()
+            .then((loggedIn) => {
+            if (cancelled)
+                return;
+            setStep(loggedIn ? { kind: 'discovering' } : { kind: 'login-needed' });
+        })
+            .catch((error) => {
+            if (!cancelled)
+                fail(error);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [step.kind]);
+    // Step 1b: the user asked us to open the browser so they can sign in.
+    React.useEffect(() => {
+        if (step.kind !== 'logging-in')
+            return;
+        let cancelled = false;
+        controllers
+            .login()
+            .then(() => {
+            if (!cancelled)
+                setStep({ kind: 'discovering' });
+        })
+            .catch((error) => {
+            if (!cancelled)
+                fail(error);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [step.kind]);
+    // Step 2: fetch the communities the signed-in user belongs to.
+    React.useEffect(() => {
+        if (step.kind !== 'discovering')
+            return;
+        let cancelled = false;
+        controllers
+            .discoverCommunities()
+            .then((communities) => {
+            if (cancelled)
+                return;
+            if (communities && communities.length > 0) {
+                setStep({ kind: 'picking', communities });
+            }
+            else {
+                setStep({ kind: 'manual-slug', value: '', error: null });
+            }
+        })
+            .catch((error) => {
+            if (!cancelled)
+                fail(error);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [step.kind]);
+    const chooseCommunity = React.useCallback((slug, name) => {
+        setStep({ kind: 'counting', slug, name });
+    }, []);
+    // Step 2b/3: count accessible courses for the confirmation screen.
+    React.useEffect(() => {
+        if (step.kind !== 'counting')
+            return;
+        let cancelled = false;
+        const { slug, name } = step;
+        controllers
+            .countAccessibleCourses(slug)
+            .then((courseCount) => {
+            if (cancelled)
+                return;
+            setStep({ kind: 'confirming', slug, name, courseCount, outDir: `${controllers.outRoot}/${slug}` });
+        })
+            .catch((error) => {
+            if (!cancelled)
+                fail(error);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [step]);
+    // Step 4: run the sync, folding progress events into render state.
+    React.useEffect(() => {
+        if (step.kind !== 'syncing')
+            return;
+        let cancelled = false;
+        const { slug, name, courseCount, outDir } = step;
+        controllers
+            .runSync(slug, outDir, (event) => {
+            if (cancelled)
+                return;
+            setStep((previous) => previous.kind === 'syncing' ? { ...previous, progress: applyProgress(previous.progress, event) } : previous);
+        })
+            .then((summary) => {
+            if (!cancelled)
+                setStep({ kind: 'done', slug, name, courseCount, outDir, summary });
+        })
+            .catch((error) => {
+            if (!cancelled)
+                fail(error);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [step.kind]);
+    // Step 5: after a sync finishes, act on the post-summary menu choice —
+    // loops back into an earlier step (never nests/recurses; `step` is simply
+    // replaced again like every other transition) or performs an in-place
+    // side effect that leaves the menu on screen.
+    const handleMenuChoice = React.useCallback((done, choice) => {
+        if (choice === 'quit') {
+            exit();
+            return;
+        }
+        if (choice === 'open-folder') {
+            // revealOutputFolder never throws (it falls back to printing the
+            // path on failure) — this catch is a last-resort guard so a future
+            // change there can never crash the TUI.
+            void revealOutputFolder(done.outDir).catch(() => { });
+            return;
+        }
+        const transition = nextStepForMenuChoice(done, choice);
+        if (!transition)
+            return;
+        if (transition.kind === 'discovering') {
+            setStep({ kind: 'discovering' });
+        }
+        else {
+            setStep({
+                kind: 'confirming',
+                slug: transition.slug,
+                name: transition.name,
+                courseCount: transition.courseCount,
+                outDir: transition.outDir,
+            });
+        }
+    }, [exit]);
+    switch (step.kind) {
+        case 'checking-session':
+            return _jsx(Text, { children: "Checking your Skool session\u2026" });
+        case 'login-needed':
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "yellow", children: "You are not signed in to Skool." }), _jsx(Text, { dimColor: true, children: "Nothing is typed for you \u2014 a browser window opens and you sign in yourself." }), _jsx(ConfirmPrompt, { onConfirm: () => setStep({ kind: 'logging-in' }) })] }));
+        case 'logging-in':
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "A browser window is open. Sign in there." }), _jsx(Text, { dimColor: true, children: "Waiting for you to finish (Ctrl+C to cancel)\u2026" })] }));
+        case 'discovering':
+            return _jsx(Text, { children: "Looking up the communities you belong to\u2026" });
+        case 'picking': {
+            const items = [
+                ...step.communities.map((community) => ({
+                    label: `${community.name}  (skool.com/${community.slug})`,
+                    value: community,
+                })),
+                { label: 'Enter a slug manually…', value: null },
+            ];
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Which community?" }), _jsx(SelectList, { items: items, onSelect: (value) => {
+                            if (value === null)
+                                setStep({ kind: 'manual-slug', value: '', error: null });
+                            else
+                                chooseCommunity(value.slug, value.name);
+                        } })] }));
+        }
+        case 'manual-slug':
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Enter the community slug \u2014 the part after skool.com/" }), _jsxs(Text, { children: ["Slug: ", step.value, _jsx(Text, { color: "gray", children: "\u2588" })] }), step.error && _jsx(Text, { color: "red", children: step.error }), _jsx(ManualSlugInput, { value: step.value, onChange: (value) => setStep({ kind: 'manual-slug', value, error: null }), onSubmit: (value) => {
+                            const slug = normalizeSlug(value);
+                            if (!isValidSlug(slug)) {
+                                setStep({ kind: 'manual-slug', value, error: `"${value}" doesn't look like a valid slug.` });
+                                return;
+                            }
+                            chooseCommunity(slug, slug);
+                        } })] }));
+        case 'counting':
+            return _jsxs(Text, { children: ["Looking up courses in ", step.name, "\u2026"] });
+        case 'confirming':
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Community: ", step.name, " (skool.com/", step.slug, ")"] }), _jsxs(Text, { children: ["Courses found: ", step.courseCount] }), _jsxs(Text, { children: ["Output will be written to: ", step.outDir] }), _jsx(Text, { children: " " }), _jsx(ConfirmPrompt, { onConfirm: () => setStep({
+                            kind: 'syncing',
+                            slug: step.slug,
+                            name: step.name,
+                            courseCount: step.courseCount,
+                            outDir: step.outDir,
+                            progress: createProgressState(0),
+                        }) })] }));
+        case 'syncing': {
+            const { progress } = step;
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: formatProgressBar(progress.done, progress.total) }), progress.current && (_jsxs(Text, { dimColor: true, children: ["current: ", progress.current.course, " / ", progress.current.title] })), _jsxs(Text, { dimColor: true, children: ["ok ", progress.counts.ok, "  skipped ", progress.counts.skipped, "  no-video ", progress.counts['no-video'], ' ', "no-access ", progress.counts['no-access'], "  unavailable ", progress.counts.unavailable, "  failed", ' ', progress.counts.failed] })] }));
+        }
+        case 'done': {
+            const lines = formatSummary(step.summary, step.outDir);
+            const done = {
+                slug: step.slug,
+                name: step.name,
+                courseCount: step.courseCount,
+                outDir: step.outDir,
+                summary: step.summary,
+            };
+            return (_jsxs(Box, { flexDirection: "column", children: [lines.map((line, index) => (
+                    // eslint-disable-next-line react/no-array-index-key
+                    _jsx(Text, { children: line || ' ' }, index))), _jsx(Text, { children: " " }), _jsx(Text, { children: "What next?" }), _jsx(SelectList, { items: MENU_ITEMS, onSelect: (choice) => handleMenuChoice(done, choice) })] }));
+        }
+        case 'error':
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: "red", children: ["Something went wrong: ", step.message] }), _jsx(ExitPrompt, { label: "Press any key to exit." })] }));
+    }
+}

package/dist/tui/SelectList.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface SelectItem<T> {
+    label: string;
+    value: T;
+}
+interface SelectListProps<T> {
+    items: Array<SelectItem<T>>;
+    onSelect: (value: T) => void;
+}
+/** Minimal arrow-key list, built directly on Ink's useInput rather than pulling
+ *  in a select-input dependency. Cheap to render: a handful of Text lines,
+ *  re-rendered only on cursor movement or selection. */
+export declare function SelectList<T>({ items, onSelect }: SelectListProps<T>): React.JSX.Element;
+export {};

package/dist/tui/SelectList.js

@@ -0,0 +1,25 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+/** Minimal arrow-key list, built directly on Ink's useInput rather than pulling
+ *  in a select-input dependency. Cheap to render: a handful of Text lines,
+ *  re-rendered only on cursor movement or selection. */
+export function SelectList({ items, onSelect }) {
+    const [cursor, setCursor] = React.useState(0);
+    useInput((input, key) => {
+        if (items.length === 0)
+            return;
+        if (key.upArrow || input === 'k') {
+            setCursor((current) => (current - 1 + items.length) % items.length);
+        }
+        else if (key.downArrow || input === 'j') {
+            setCursor((current) => (current + 1) % items.length);
+        }
+        else if (key.return) {
+            const item = items[cursor];
+            if (item)
+                onSelect(item.value);
+        }
+    });
+    return (_jsx(Box, { flexDirection: "column", children: items.map((item, index) => (_jsxs(Text, { color: index === cursor ? 'cyan' : undefined, children: [index === cursor ? '> ' : '  ', item.label] }, item.label))) }));
+}

package/dist/tui/browserLifecycle.d.ts

@@ -0,0 +1,71 @@
+import type { Fetcher } from '../types.js';
+/**
+ * A Fetcher that also owns a real Chrome process and must be closed to
+ * release it.
+ */
+export interface CloseableFetcher extends Fetcher {
+    close(): Promise<void>;
+}
+/**
+ * ============================================================================
+ * INVARIANT: only one Chrome process may hold the persistent profile
+ * directory at a time. Chrome enforces this itself (SingletonLock) and
+ * aborts a second launch against the same profile. Every operation below
+ * that needs a browser always closes whatever browser is currently live
+ * (via closeCurrent()) before handing out a new one — so the profile is
+ * provably held by at most one Chrome at any instant.
+ * ============================================================================
+ */
+/** A handle callers can use to force-close a launched login context, e.g. on Ctrl+C. */
+export interface LoginContextHandle {
+    close(): Promise<void>;
+}
+export interface BrowserLifecycleDeps {
+    http: Fetcher;
+    isLoggedIn: (html: string) => boolean;
+    /** Creates a fresh, not-yet-launched BrowserFetcher over the profile dir. */
+    makeBrowserFetcher: () => CloseableFetcher;
+    /**
+     * The real interactive sign-in flow (headed Chrome, same profile dir).
+     * `onContext` is called as soon as the headed browser launches, so the
+     * lifecycle can track it and force-close it on SIGINT even while
+     * performLogin() is still awaiting the user.
+     */
+    performLogin: (onContext: (context: LoginContextHandle) => void) => Promise<void>;
+}
+export interface BrowserLifecycle {
+    /**
+     * Checks whether the saved profile is already signed in. Owns a
+     * short-lived browser for the duration of the check only — the profile is
+     * guaranteed free again the instant this call resolves or rejects, so a
+     * following login() never collides with it.
+     */
+    checkLoggedIn(): Promise<boolean>;
+    /**
+     * Runs the interactive login flow. Closes any browser this lifecycle is
+     * currently holding first, so the profile is always free before the real
+     * (headed) Chrome launches against it.
+     */
+    login(): Promise<void>;
+    /**
+     * Returns the long-lived fetcher used for discovery and sync. Lazily
+     * launches one fresh browser behind it on first call and reuses it for
+     * every call after that.
+     */
+    getFetcher(): Fetcher;
+    /**
+     * Closes whichever browser instance is currently live, if any. Safe to
+     * call when nothing was ever created and safe to call more than once.
+     */
+    cleanup(): Promise<void>;
+}
+/** True when an error looks like Chrome's "profile already in use" failure. */
+export declare function isProfileLockError(error: unknown): boolean;
+/**
+ * Turns Playwright's multi-hundred-line ProcessSingleton/SingletonLock dump
+ * into one short, actionable line. The raw error is kept on `.cause` for
+ * non-TUI diagnostics (e.g. `--verbose` logging) rather than shown to the
+ * user. Anything else passes through unchanged.
+ */
+export declare function translateLaunchError(error: unknown): Error;
+export declare function createBrowserLifecycle(deps: BrowserLifecycleDeps): BrowserLifecycle;

package/dist/tui/browserLifecycle.js

@@ -0,0 +1,114 @@
+import { ResilientFetcher } from '../fetch/resilient.js';
+const LOCK_ERROR_PATTERN = /ProcessSingleton|SingletonLock/i;
+/** True when an error looks like Chrome's "profile already in use" failure. */
+export function isProfileLockError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return LOCK_ERROR_PATTERN.test(message);
+}
+/**
+ * Turns Playwright's multi-hundred-line ProcessSingleton/SingletonLock dump
+ * into one short, actionable line. The raw error is kept on `.cause` for
+ * non-TUI diagnostics (e.g. `--verbose` logging) rather than shown to the
+ * user. Anything else passes through unchanged.
+ */
+export function translateLaunchError(error) {
+    if (isProfileLockError(error)) {
+        const friendly = new Error('The Chrome profile is already in use. Another skrape process may be running — ' +
+            'if not, delete ~/.skool-skrape/chrome-profile/SingletonLock and try again.');
+        friendly.cause = error;
+        return friendly;
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+function wrapLaunchErrors(browser) {
+    return {
+        async getPage(url) {
+            try {
+                return await browser.getPage(url);
+            }
+            catch (error) {
+                throw translateLaunchError(error);
+            }
+        },
+        async close() {
+            try {
+                await browser.close();
+            }
+            catch (error) {
+                throw translateLaunchError(error);
+            }
+        },
+    };
+}
+export function createBrowserLifecycle(deps) {
+    const { http, isLoggedIn, makeBrowserFetcher, performLogin } = deps;
+    // Tracks whichever browser (BrowserFetcher-backed, or the raw login
+    // context) currently owns the profile directory, if any. Never held by
+    // more than one at a time — see invariant above. At most one of these two
+    // is non-null at any instant.
+    let current = null;
+    let loginContext = null;
+    let sharedFetcher = null;
+    async function closeCurrent() {
+        const browser = current;
+        current = null;
+        const login = loginContext;
+        loginContext = null;
+        if (browser)
+            await browser.close();
+        if (login)
+            await login.close();
+    }
+    return {
+        async checkLoggedIn() {
+            const browser = wrapLaunchErrors(makeBrowserFetcher());
+            current = browser;
+            const fetcher = new ResilientFetcher(http, async () => browser, isLoggedIn);
+            try {
+                const html = await fetcher.getPage('https://www.skool.com/');
+                return isLoggedIn(html);
+            }
+            finally {
+                // The check's browser is never reused — always release it here so
+                // the profile is free the instant the check is done, whatever the
+                // outcome.
+                await closeCurrent();
+            }
+        },
+        async login() {
+            // Defensive: guarantees the invariant even if a caller invokes login()
+            // out of the usual check -> login order.
+            await closeCurrent();
+            try {
+                await performLogin((context) => {
+                    loginContext = context;
+                });
+                // performLogin() already closed its own context on success.
+                loginContext = null;
+            }
+            catch (error) {
+                // If a browser did launch before the failure, close it ourselves —
+                // otherwise a failed/interrupted login leaves the profile locked
+                // for the next run. If SIGINT already closed it (see cleanup()),
+                // loginContext is already null here and there is nothing to do.
+                const context = loginContext;
+                loginContext = null;
+                if (context) {
+                    await context.close().catch(() => {
+                        // Best-effort: we're already reporting the original error.
+                    });
+                }
+                throw translateLaunchError(error);
+            }
+        },
+        getFetcher() {
+            if (!sharedFetcher) {
+                const browser = wrapLaunchErrors(makeBrowserFetcher());
+                current = browser;
+                sharedFetcher = new ResilientFetcher(http, async () => browser, isLoggedIn);
+            }
+            return sharedFetcher;
+        },
+        cleanup: closeCurrent,
+    };
+}

package/dist/tui/chromeSetup.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure decision logic for the one-time "make sure Chrome is installed" step
+ * that runs before the session check. Kept free of fs/child_process/Playwright
+ * details (those live in `../fetch/chromeSetup.ts`) so the branching here is
+ * unit-testable against plain fakes, the same split used by `flow.ts` and
+ * `browserLifecycle.ts` elsewhere in this package.
+ */
+export interface ChromeSetupDeps {
+    /** Cheap on-disk check: was this already confirmed on a past run, and does
+     *  the executable path recorded then still exist now? */
+    isConfirmedInstalled: () => Promise<boolean> | boolean;
+    /** Real (but cheap: headless, throwaway, closes fast) launch-and-close
+     *  check. Resolves the launched Chrome's executable path on success, or
+     *  `undefined` if it couldn't be launched. */
+    probeLaunchable: () => Promise<string | undefined>;
+    /** Persists the confirmed executable path so future calls can skip
+     *  straight to it (via a cheap existence check, not another launch). */
+    markInstalled: (executablePath: string) => Promise<void>;
+    /** Runs the actual installer and resolves the freshly-installed Chrome's
+     *  executable path; rejects on failure (network/disk/permissions/platform,
+     *  or an install that "succeeded" but still isn't launchable). */
+    installChrome: (onProgress: (elapsedSeconds: number) => void) => Promise<string>;
+}
+export interface ChromeReadyResult {
+    /** True only when this call actually ran the installer. */
+    installed: boolean;
+}
+/** Thrown when the automatic install fails. Its message is already
+ *  human-actionable (includes the manual fallback command) — callers can
+ *  surface `.message` directly without needing to know install internals. */
+export declare class ChromeInstallFailedError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Ensures Chrome is installed and launchable, installing it if not.
+ *
+ * Order, cheapest-first:
+ *  1. Trust a previously-written "confirmed installed" marker — no launch at
+ *     all, as long as the executable path it recorded still exists on disk.
+ *  2. Otherwise, do the real (but cheap) launch-and-close probe.
+ *  3. Only if that fails, run the installer — and mark the resolved path it
+ *     hands back so steps 2/3 are never repeated on later runs.
+ *
+ * Never throws a raw/undecorated error: any installChrome() failure is
+ * wrapped in `ChromeInstallFailedError` with the manual fallback command
+ * included, per this project's no-silent-failures rule.
+ */
+export declare function ensureChromeReady(deps: ChromeSetupDeps, onProgress?: (elapsedSeconds: number) => void): Promise<ChromeReadyResult>;

package/dist/tui/chromeSetup.js

@@ -0,0 +1,52 @@
+/**
+ * Pure decision logic for the one-time "make sure Chrome is installed" step
+ * that runs before the session check. Kept free of fs/child_process/Playwright
+ * details (those live in `../fetch/chromeSetup.ts`) so the branching here is
+ * unit-testable against plain fakes, the same split used by `flow.ts` and
+ * `browserLifecycle.ts` elsewhere in this package.
+ */
+const MANUAL_FALLBACK = 'npx playwright install chrome';
+/** Thrown when the automatic install fails. Its message is already
+ *  human-actionable (includes the manual fallback command) — callers can
+ *  surface `.message` directly without needing to know install internals. */
+export class ChromeInstallFailedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ChromeInstallFailedError';
+    }
+}
+/**
+ * Ensures Chrome is installed and launchable, installing it if not.
+ *
+ * Order, cheapest-first:
+ *  1. Trust a previously-written "confirmed installed" marker — no launch at
+ *     all, as long as the executable path it recorded still exists on disk.
+ *  2. Otherwise, do the real (but cheap) launch-and-close probe.
+ *  3. Only if that fails, run the installer — and mark the resolved path it
+ *     hands back so steps 2/3 are never repeated on later runs.
+ *
+ * Never throws a raw/undecorated error: any installChrome() failure is
+ * wrapped in `ChromeInstallFailedError` with the manual fallback command
+ * included, per this project's no-silent-failures rule.
+ */
+export async function ensureChromeReady(deps, onProgress) {
+    if (await deps.isConfirmedInstalled()) {
+        return { installed: false };
+    }
+    const probedPath = await deps.probeLaunchable();
+    if (probedPath) {
+        await deps.markInstalled(probedPath);
+        return { installed: false };
+    }
+    let installedPath;
+    try {
+        installedPath = await deps.installChrome(onProgress ?? (() => { }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ChromeInstallFailedError(`Could not automatically install the browser skrape needs.\n${message}\n\n` +
+            `You can install it yourself, then run skrape again:\n  ${MANUAL_FALLBACK}`, { cause: error });
+    }
+    await deps.markInstalled(installedPath);
+    return { installed: true };
+}

package/dist/tui/flow.d.ts

@@ -0,0 +1,53 @@
+import type { SyncSummary } from '../sync.js';
+/**
+ * Pure screen-sequencing logic for what happens after a sync finishes and the
+ * user picks an option from the post-summary menu. Kept free of Ink/React so
+ * the transitions themselves — independent of how they get rendered or which
+ * keys drive them — are unit-testable.
+ *
+ * This models a genuine loop: the caller (App.tsx) folds the returned Step
+ * back into its single `step` state slot exactly like every other
+ * transition already in the guided flow, so a long interactive session
+ * (sync A -> menu -> sync A again -> menu -> sync B -> menu -> quit -> ...)
+ * never nests components or accumulates state — each transition just
+ * replaces `step`.
+ */
+/** The subset of an App `Step` this module needs to know about, expressed
+ *  structurally so this file doesn't have to import App's full Step union
+ *  (which would create a cycle back into the Ink-aware module). */
+export interface DoneState {
+    slug: string;
+    name: string;
+    courseCount: number;
+    outDir: string;
+    summary: SyncSummary;
+}
+export type MenuChoice = 'sync-another' | 'sync-again' | 'open-folder' | 'quit';
+export interface MenuItem {
+    label: string;
+    value: MenuChoice;
+}
+export declare const MENU_ITEMS: MenuItem[];
+/** The next screen-sequencing step to fold into state after a menu choice.
+ *  `'discovering'` re-enters the same community-discovery step that ran
+ *  after login, skipping the session check entirely since the user is
+ *  already signed in. `'confirming'` re-uses the slug/name/courseCount/outDir
+ *  from the sync that just finished, skipping both the picker and the course
+ *  count so "sync again" goes straight to confirm -> progress -> summary. */
+export type FlowTransition = {
+    kind: 'discovering';
+} | {
+    kind: 'confirming';
+    slug: string;
+    name: string;
+    courseCount: number;
+    outDir: string;
+};
+/**
+ * Given the state of the sync that just completed and the menu choice the
+ * user made, returns the next step transition — or `null` when the choice
+ * doesn't move to a new screen at all: `'open-folder'` is a side effect
+ * performed in place (the menu stays up), and `'quit'` exits instead of
+ * transitioning to another step.
+ */
+export declare function nextStepForMenuChoice(done: DoneState, choice: MenuChoice): FlowTransition | null;