videobook 0.0.0-stage → 0.2.0

package/dist/chat-view-actions.js

@@ -0,0 +1,49 @@
+import { resolveNotebookCellArtifactId } from "videobook-engine";
+import { notebookGridTag } from "videobook-engine/notebook-grid";
+import { z } from "zod";
+import { resolveNotebookArtifactReference } from "./notebook-reference-resolver.js";
+const SHOW_MEDIA_FULLSCREEN = "show_media_fullscreen";
+const FULLSCREEN_MEDIA_KINDS = ["image", "video", "final"];
+const CHAT_VIEW_ACTIONS = [
+    {
+        name: SHOW_MEDIA_FULLSCREEN,
+        description: "Show, open, view or enlarge one notebook cell's image or video in the fullscreen viewer. Changes nothing in the book",
+        schema: {
+            asset_id: z.string().min(1).describe("Artifact ID or grid address of the cell's image or video"),
+        },
+    },
+];
+function resolveMediaFullscreen(engine, notebook, reference) {
+    if (!notebook)
+        return { ok: false, message: "Open a notebook before showing media fullscreen" };
+    const resolved = resolveNotebookArtifactReference({ engine, documents: [notebook], reference });
+    if ("code" in resolved)
+        return { ok: false, message: resolved.message };
+    const cell = notebook.cells.find((candidate) => resolved.cellId
+        ? candidate.id === resolved.cellId
+        : resolveNotebookCellArtifactId(notebook, candidate) === resolved.artifactId);
+    if (!cell)
+        return { ok: false, message: `No cell in this notebook holds ${resolved.mention}` };
+    const artifact = engine.artifacts.get(resolved.artifactId);
+    if (!artifact.ok)
+        return { ok: false, message: artifact.error.message };
+    if (!FULLSCREEN_MEDIA_KINDS.includes(artifact.value.kind)) {
+        return {
+            ok: false,
+            message: `${notebookGridTag(cell.slot)} holds ${artifact.value.kind}; fullscreen shows images and video`,
+        };
+    }
+    return { ok: true, params: { asset_id: resolved.artifactId, cell_id: cell.id } };
+}
+/** Validate a routed view action and pin it to the cell the app should open. */
+function resolveChatViewAction(engine, notebook, tool, params) {
+    const action = CHAT_VIEW_ACTIONS.find((candidate) => candidate.name === tool);
+    if (!action)
+        return { ok: false, message: `Unknown view action: ${tool}` };
+    const parsed = z.object(action.schema).safeParse(params);
+    if (!parsed.success) {
+        return { ok: false, message: `Invalid parameters for ${tool}: ${z.prettifyError(parsed.error)}` };
+    }
+    return resolveMediaFullscreen(engine, notebook, String(parsed.data.asset_id));
+}
+export { CHAT_VIEW_ACTIONS, resolveChatViewAction };

package/dist/cli/args.js

@@ -0,0 +1,242 @@
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+const LOG_LEVELS = new Set(["silent", "error", "warn", "info", "debug"]);
+const COMMANDS = new Set(["serve", "mcp", "run", "tools", "gc-books", "doctor", "setup", "config", "version", "help"]);
+const CONFIG_ACTIONS = new Set(["list", "get", "set", "unset"]);
+const POSITIONAL_COMMANDS = new Set(["run", "setup", "config"]);
+const DEFAULT_RUN_TIMEOUT_SECONDS = 600;
+const GLOBAL_OPTIONS = {
+    port: { type: "string" },
+    library: { type: "string" },
+    home: { type: "string" },
+    "log-level": { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+};
+const COMMAND_OPTIONS = {
+    serve: { headless: { type: "boolean" }, "no-ui": { type: "boolean" }, open: { type: "boolean" } },
+    mcp: {},
+    run: { wait: { type: "boolean" }, "no-wait": { type: "boolean" }, timeout: { type: "string" } },
+    tools: {},
+    "gc-books": {},
+    doctor: { json: { type: "boolean" } },
+    setup: { "op-vault": { type: "string" }, "op-token": { type: "string" }, "no-verify": { type: "boolean" }, remove: { type: "boolean" } },
+    config: { json: { type: "boolean" } },
+};
+function splitCommand(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first.startsWith("-"))
+        return { command: "serve", rest: argv };
+    if (!COMMANDS.has(first))
+        throw new CliUsageError(`Unknown command "${first}".`);
+    return { command: first, rest };
+}
+function parsePort(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const port = Number(raw);
+    if (!/^\d+$/u.test(raw) || port > 65535)
+        throw new CliUsageError(`--port must be an integer from 0 to 65535, got "${raw}".`);
+    return port;
+}
+function parseLogLevel(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    if (!LOG_LEVELS.has(raw))
+        throw new CliUsageError(`--log-level must be one of silent, error, warn, info, debug; got "${raw}".`);
+    return raw;
+}
+function parseTimeout(raw) {
+    if (typeof raw !== "string")
+        return DEFAULT_RUN_TIMEOUT_SECONDS;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        throw new CliUsageError(`--timeout must be a positive number of seconds, got "${raw}".`);
+    return seconds;
+}
+function stringValue(raw) {
+    return typeof raw === "string" && raw.trim() !== "" ? raw : undefined;
+}
+function globalFlags(values) {
+    const flags = {};
+    const port = parsePort(values.port);
+    const library = stringValue(values.library);
+    const home = stringValue(values.home);
+    const logLevel = parseLogLevel(values["log-level"]);
+    if (port !== undefined)
+        flags.port = port;
+    if (library !== undefined)
+        flags.library = library;
+    if (home !== undefined)
+        flags.home = home;
+    if (logLevel !== undefined)
+        flags.logLevel = logLevel;
+    return flags;
+}
+function parseValue(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+export function parseToolArgs(pairs) {
+    const args = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            throw new CliUsageError(`Invalid tool argument "${pair}". Use key=value.`);
+        args[pair.slice(0, eq)] = parseValue(pair.slice(eq + 1));
+    }
+    return args;
+}
+function parseCommandArgs(command, rest) {
+    try {
+        const parsed = parseArgs({
+            args: rest,
+            options: { ...GLOBAL_OPTIONS, ...COMMAND_OPTIONS[command] },
+            allowPositionals: POSITIONAL_COMMANDS.has(command),
+            strict: true,
+        });
+        return { values: parsed.values, positionals: parsed.positionals };
+    }
+    catch (error) {
+        throw new CliUsageError(error instanceof Error ? error.message : String(error));
+    }
+}
+function buildSetup(values, positionals, flags) {
+    const [target, ...extra] = positionals;
+    if (target !== "1password" || extra.length > 0)
+        throw new CliUsageError("setup needs a target: videobook setup 1password --op-vault <vault> [--op-token env:OP_SERVICE_ACCOUNT_TOKEN]");
+    const vault = stringValue(values["op-vault"]);
+    const token = stringValue(values["op-token"]);
+    return {
+        command: "setup",
+        target,
+        flags: {
+            ...flags,
+            ...(vault === undefined ? {} : { vault }),
+            ...(token === undefined ? {} : { token }),
+            verify: values["no-verify"] !== true,
+            remove: values.remove === true,
+        },
+    };
+}
+function buildConfig(values, positionals, flags) {
+    const [action = "list", key, value, ...extra] = positionals;
+    if (!CONFIG_ACTIONS.has(action))
+        throw new CliUsageError(`Unknown config action "${action}". Use list, get, set or unset.`);
+    const needsKey = action !== "list";
+    const needsValue = action === "set";
+    const expected = 1 + (needsKey ? 1 : 0) + (needsValue ? 1 : 0);
+    if (positionals.length > Math.max(expected, 1) || extra.length > 0 || (needsKey && !key) || (needsValue && value === undefined)) {
+        throw new CliUsageError("Usage: videobook config list | get <KEY> | set <KEY> <VALUE> | unset <KEY>");
+    }
+    return {
+        command: "config",
+        action: action,
+        key: key ?? null,
+        value: value ?? null,
+        flags: { ...flags, json: values.json === true },
+    };
+}
+function buildCommand(command, values, positionals) {
+    const flags = globalFlags(values);
+    switch (command) {
+        case "serve":
+            return { command, flags: { ...flags, ui: values.headless !== true && values["no-ui"] !== true, open: values.open === true } };
+        case "run": {
+            const [tool, ...pairs] = positionals;
+            if (!tool)
+                throw new CliUsageError("run needs a tool name, for example: videobook run list_books");
+            return { command, tool, toolArgs: parseToolArgs(pairs), flags: { ...flags, wait: values["no-wait"] !== true, timeoutSeconds: parseTimeout(values.timeout) } };
+        }
+        case "doctor":
+            return { command, flags: { ...flags, json: values.json === true } };
+        case "setup":
+            return buildSetup(values, positionals, flags);
+        case "config":
+            return buildConfig(values, positionals, flags);
+        default:
+            return { command, flags };
+    }
+}
+export function parseCli(argv) {
+    const { command, rest } = splitCommand(argv);
+    if (command === "help")
+        return { command: "help" };
+    if (command === "version")
+        return { command: "version" };
+    const name = command;
+    const { values, positionals } = parseCommandArgs(name, rest);
+    if (values.help === true)
+        return { command: "help" };
+    if (values.version === true)
+        return { command: "version" };
+    return buildCommand(name, values, positionals);
+}
+const HOME_DERIVED_ENV = ["VIDEOBOOK_LIBRARY_DIR", "VIDEOBOOK_APP_STATE_PATH", "VIDEOBOOK_ENV_PATH"];
+function applyHome(home, env, cwd) {
+    env.VIDEOBOOK_HOME = resolve(cwd, home);
+    for (const name of HOME_DERIVED_ENV)
+        delete env[name];
+}
+export function applyFlagsToEnv(flags, env, cwd) {
+    if (flags.home !== undefined)
+        applyHome(flags.home, env, cwd);
+    if (flags.library !== undefined)
+        env.VIDEOBOOK_LIBRARY_DIR = resolve(cwd, flags.library);
+    if (flags.port !== undefined)
+        env.PORT = String(flags.port);
+    if (flags.logLevel !== undefined)
+        env.VIDEOBOOK_LOG_LEVEL = flags.logLevel;
+}
+export function resolvePort(env) {
+    const raw = env.PORT?.trim();
+    const port = raw ? Number(raw) : 3001;
+    return Number.isInteger(port) && port >= 0 && port <= 65535 ? port : 3001;
+}
+export function helpText() {
+    return [
+        "Usage: videobook [command] [options]",
+        "",
+        "Commands:",
+        "  serve              Run the MCP server with the web UI (default)",
+        "  mcp                Serve MCP over stdio for agent hosts such as Claude Code",
+        "  run <tool> [k=v]   Call one MCP tool and print its result",
+        "  tools              List the MCP tools and their parameters",
+        "  gc-books           Reclaim catalog storage in every book",
+        "  doctor             Check Node, media binaries, native modules and keys",
+        "  config [action]    list | get <KEY> | set <KEY> <VALUE> | unset <KEY> in the data-home .env",
+        "  setup 1password    Read keys from a 1Password vault (--op-vault, --op-token)",
+        "  version            Print versions",
+        "  help               Print this help",
+        "",
+        "Options:",
+        "  --port <n>         HTTP port on 127.0.0.1 (default 3001, or PORT)",
+        "  --library <dir>    Book library directory (default <data home>/books)",
+        "  --home <dir>       Data home (default ~/.videobook, or VIDEOBOOK_HOME)",
+        "  --log-level <l>    silent, error, warn, info or debug",
+        "  --headless         serve: MCP and API only, no web UI (alias --no-ui)",
+        "  --open             serve: open the web UI in a browser",
+        "  --no-wait          run: do not wait for queued jobs",
+        "  --timeout <s>      run: seconds to wait for jobs (default 600)",
+        "  --json             doctor, config: print machine-readable results",
+        "  --op-vault <name>  setup 1password: vault whose items are named after the keys",
+        "  --op-token <tok>   setup 1password: service-account token, best as env:VAR",
+        "  --no-verify        setup 1password: skip the op item list check",
+        "  --remove           setup 1password: remove the saved 1Password settings",
+        "  -v, --version      Print versions",
+        "  -h, --help         Print this help",
+        "",
+        "Agent hosts:  claude mcp add videobook -- videobook mcp",
+        "",
+    ].join("\n");
+}

package/dist/cli/config-command.js

@@ -0,0 +1,103 @@
+import { hasControlCharacters, readEnvValues, updateEnvFile } from "../env-file.js";
+import { MANAGED_ENV_KEYS, getDefaultSecretStore, isSecretEnvKey, maskEnvValue, } from "../env-secrets.js";
+import { OP_TOKEN_SETTING, OP_VAULT_SETTING, isOpReference, vaultReference } from "../one-password.js";
+const SETTING_KEYS = [OP_VAULT_SETTING, OP_TOKEN_SETTING];
+const CONFIG_KEYS = [...MANAGED_ENV_KEYS, ...SETTING_KEYS];
+const TOKEN_VARIABLE_FORM = /^(env:|\$)?[A-Z_][A-Z0-9_]*$/u;
+function isSecret(key) {
+    if (key === OP_VAULT_SETTING)
+        return false;
+    if (key === OP_TOKEN_SETTING)
+        return true;
+    return isSecretEnvKey(key);
+}
+function displayValue(key, value) {
+    if (isOpReference(value))
+        return value.trim();
+    if (key === OP_TOKEN_SETTING && TOKEN_VARIABLE_FORM.test(value))
+        return value;
+    return isSecret(key) ? maskEnvValue(value) : value;
+}
+function configuredVault(file) {
+    return process.env[OP_VAULT_SETTING]?.trim() || file[OP_VAULT_SETTING]?.trim() || null;
+}
+function configRow(key, file) {
+    const shell = process.env[key]?.trim();
+    if (shell)
+        return { key, source: "environment", value: displayValue(key, shell) };
+    const stored = file[key]?.trim();
+    if (stored)
+        return { key, source: isOpReference(stored) ? "1password reference" : ".env", value: displayValue(key, stored) };
+    const vault = configuredVault(file);
+    if (vault && !SETTING_KEYS.includes(key))
+        return { key, source: "1password vault", value: vaultReference(vault, key) };
+    return { key, source: "missing", value: null };
+}
+function vaultNote(rows, vault) {
+    if (!vault || !rows.some((row) => row.source === "1password vault"))
+        return "";
+    return `\nKeys marked "1password vault" come from ${vault} when it has an item with that name; videobook doctor shows which do.\n`;
+}
+function printRows(rows, file, json, envPath) {
+    const vault = configuredVault(file);
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ envPath, vault, keys: rows }, null, 2)}\n`);
+        return;
+    }
+    const lines = rows.map((row) => `${row.key.padEnd(28)} ${row.source.padEnd(20)} ${row.value ?? ""}`.trimEnd());
+    process.stdout.write(`${lines.join("\n")}\n${vaultNote(rows, vault)}`);
+}
+function knownKey(key) {
+    if (CONFIG_KEYS.includes(key))
+        return true;
+    process.stderr.write(`${key} is not a videobook setting. Known keys: ${CONFIG_KEYS.join(", ")}\n`);
+    return false;
+}
+function invalidValue(key, value) {
+    if (!value || hasControlCharacters(value))
+        return `${key} needs a non-empty value without control characters`;
+    if (value.includes("'") && value.includes("\""))
+        return `${key} cannot contain both single and double quotes`;
+    if (process.env[key]?.trim())
+        return `${key} is set in the environment, which overrides the .env file; change it where it is exported instead`;
+    return null;
+}
+async function setKey(key, raw, envPath) {
+    const value = raw.trim();
+    const problem = invalidValue(key, value);
+    if (problem) {
+        process.stderr.write(`${problem}\n`);
+        return 1;
+    }
+    await updateEnvFile(envPath, { [key]: value });
+    process.stdout.write(`Set ${key}=${displayValue(key, value)} in ${envPath}\n`);
+    return 0;
+}
+async function unsetKey(key, envPath) {
+    const present = key in readEnvValues(envPath);
+    if (present)
+        await updateEnvFile(envPath, { [key]: null });
+    process.stdout.write(present ? `Removed ${key} from ${envPath}\n` : `${key} was not set in ${envPath}\n`);
+    if (process.env[key]?.trim())
+        process.stderr.write(`Note: ${key} is still set in the environment.\n`);
+    return 0;
+}
+export async function runConfigCommand(command) {
+    const envPath = getDefaultSecretStore().envPath();
+    if (command.action === "list") {
+        const file = readEnvValues(envPath);
+        printRows(CONFIG_KEYS.map((key) => configRow(key, file)), file, command.flags.json, envPath);
+        return 0;
+    }
+    const key = command.key ?? "";
+    if (!knownKey(key))
+        return 1;
+    if (command.action === "get") {
+        const file = readEnvValues(envPath);
+        printRows([configRow(key, file)], file, command.flags.json, envPath);
+        return 0;
+    }
+    if (command.action === "set")
+        return setKey(key, command.value ?? "", envPath);
+    return unsetKey(key, envPath);
+}

package/dist/cli/doctor-command.js

@@ -0,0 +1,289 @@
+import { execFile } from "node:child_process";
+import { access, constants, readdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { SCHEMA_VERSION } from "videobook-engine/catalog-metadata";
+import { resolvePort } from "./args.js";
+import { dataLayout } from "../data-home.js";
+import { bookManager } from "../engine.js";
+import { MANAGED_ENV_KEYS, getDefaultSecretStore } from "../env-secrets.js";
+import { FFMPEG } from "../ffmpeg-binary.js";
+import { FFPROBE, bundledFfprobe } from "../ffprobe-binary.js";
+import { inspectServerOwner } from "../server-lock.js";
+import { readOnePasswordSettings } from "../one-password.js";
+import { remotionBrowserDir, remotionCacheRoot } from "../remotion/browser.js";
+import { resolveYtdlp } from "../ytdlp-binary.js";
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const ALLOW_SCRIPTS = "ffmpeg-static,ytdlp-nodejs,@dolthub/doltlite,usearch,onnxruntime-node,esbuild";
+const INSTALL_REMEDY = `Reinstall with install scripts allowed: npm install -g videobook --allow-scripts=${ALLOW_SCRIPTS}`;
+function check(fields) {
+    return fields;
+}
+function message(error) {
+    return error instanceof Error ? error.message.split("\n")[0] ?? error.message : String(error);
+}
+function nodeCheck() {
+    const engines = require("../../package.json").engines?.node ?? ">=22";
+    const minimum = Number(/(\d+)/u.exec(engines)?.[1] ?? 22);
+    const major = Number(process.versions.node.split(".")[0]);
+    return check({
+        id: "node",
+        label: "Node.js",
+        status: major >= minimum ? "ok" : "fail",
+        detail: `${process.version} (needs ${engines})`,
+        ...(major >= minimum ? {} : { remedy: `Install Node.js ${minimum} or newer.` }),
+        required: true,
+    });
+}
+async function nearestExisting(path) {
+    let current = path;
+    for (;;) {
+        try {
+            await access(current);
+            return current;
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return current;
+            current = parent;
+        }
+    }
+}
+async function dataHomeCheck() {
+    const layout = dataLayout();
+    const kind = layout.kind === "checkout" ? "source checkout" : process.env.VIDEOBOOK_HOME?.trim() ? "VIDEOBOOK_HOME" : "default";
+    const target = await nearestExisting(layout.root);
+    try {
+        await access(target, constants.W_OK);
+        return check({ id: "data-home", label: "Data home", status: "ok", detail: `${layout.root} (${kind}); .env ${layout.envPath}`, required: true });
+    }
+    catch {
+        return check({
+            id: "data-home",
+            label: "Data home",
+            status: "fail",
+            detail: `${layout.root} is not writable (${kind})`,
+            remedy: "Set VIDEOBOOK_HOME or pass --home to a writable directory.",
+            required: true,
+        });
+    }
+}
+async function libraryCheck() {
+    const libraryDir = bookManager.rootDir;
+    try {
+        const books = (await readdir(libraryDir, { withFileTypes: true })).filter((entry) => entry.isDirectory() && UUID_V7.test(entry.name));
+        return check({ id: "library", label: "Library", status: "ok", detail: `${libraryDir}: ${books.length} book(s), schema ${SCHEMA_VERSION}`, required: false });
+    }
+    catch {
+        return check({ id: "library", label: "Library", status: "ok", detail: `${libraryDir} is created on first start (schema ${SCHEMA_VERSION})`, required: false });
+    }
+}
+function bundledPath(moduleName) {
+    try {
+        const value = require(moduleName);
+        return typeof value === "string" ? value : value?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function binaryCheck(id, label, binary, bundled, envName) {
+    const origin = binary === bundled ? "bundled" : binary.includes("/") ? envName : "from PATH";
+    try {
+        const { stdout } = await execFileAsync(binary, ["-version"], { timeout: 15_000 });
+        return check({ id, label, status: "ok", detail: `${stdout.split("\n")[0]} (${origin}: ${binary})`, required: true });
+    }
+    catch (error) {
+        return check({
+            id,
+            label,
+            status: "fail",
+            detail: `${binary} did not run: ${message(error)}`,
+            remedy: `${INSTALL_REMEDY}, install ${label} on PATH, or set ${envName}.`,
+            required: true,
+        });
+    }
+}
+function ytdlpCheck() {
+    const binary = resolveYtdlp();
+    if (binary) {
+        const origin = binary.source === "PATH" ? "from PATH" : binary.source;
+        return check({ id: "yt-dlp", label: "yt-dlp", status: "ok", detail: `${binary.path} (${origin})`, required: false });
+    }
+    return check({
+        id: "yt-dlp",
+        label: "yt-dlp",
+        status: "warn",
+        detail: "not found; download_video and archive_clip from URLs will fail",
+        remedy: `${INSTALL_REMEDY}, install yt-dlp on PATH, or set VIDEOBOOK_YTDLP_PATH.`,
+        required: false,
+    });
+}
+function sharedObjects(pattern) {
+    const report = process.report.getReport();
+    return (report.sharedObjects ?? []).filter((name) => pattern.test(name));
+}
+function engineRequire() {
+    return createRequire(require.resolve("videobook-engine/package.json"));
+}
+function nativeCoreCheck() {
+    try {
+        const { DatabaseSync } = engineRequire()("@dolthub/doltlite");
+        const database = new DatabaseSync(":memory:");
+        const dolt = database.doltVersion();
+        database.close();
+        const sharp = require("sharp");
+        const copies = sharedObjects(/sharp[^/\\]*\.node$/u).length;
+        return check({
+            id: "native-runtime",
+            label: "Native modules",
+            status: copies > 1 ? "fail" : "ok",
+            detail: `DoltLite ${dolt}; Sharp ${sharp.versions.sharp ?? "?"} / libvips ${sharp.versions.vips ?? "?"}${copies > 1 ? `; ${copies} Sharp copies loaded` : ""}`,
+            ...(copies > 1 ? { remedy: "Reinstall videobook so npm dedupes Sharp to one copy." } : {}),
+            required: true,
+        });
+    }
+    catch (error) {
+        return check({ id: "native-runtime", label: "Native modules", status: "fail", detail: message(error), remedy: INSTALL_REMEDY, required: true });
+    }
+}
+function searchRuntimeCheck() {
+    const fromEngine = engineRequire();
+    try {
+        fromEngine("onnxruntime-node");
+        fromEngine("usearch");
+        return check({ id: "search-runtime", label: "Semantic search", status: "ok", detail: "ONNX Runtime and USearch load", required: false });
+    }
+    catch (error) {
+        return check({
+            id: "search-runtime",
+            label: "Semantic search",
+            status: "warn",
+            detail: `unavailable on ${process.platform}-${process.arch}: ${message(error)}`,
+            required: false,
+        });
+    }
+}
+async function renderBrowserCheck() {
+    const root = remotionCacheRoot();
+    if (!root) {
+        return check({ id: "render-browser", label: "Render browser", status: "ok", detail: "managed by Remotion in this source checkout", required: false });
+    }
+    const directory = remotionBrowserDir(root);
+    try {
+        await access(join(directory, "chrome-headless-shell"));
+        return check({ id: "render-browser", label: "Render browser", status: "ok", detail: `Chrome Headless Shell in ${directory}`, required: false });
+    }
+    catch {
+        return check({
+            id: "render-browser",
+            label: "Render browser",
+            status: "warn",
+            detail: `not downloaded yet; the first render downloads Chrome Headless Shell into ${directory}`,
+            required: false,
+        });
+    }
+}
+async function opVersion() {
+    try {
+        return (await execFileAsync("op", ["--version"], { timeout: 10_000 })).stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+function describeResolution(resolution) {
+    const filled = resolution.fromReferences.length + resolution.fromVault.length;
+    const vault = resolution.vault ? `vault ${resolution.vault}` : "op:// references";
+    const token = resolution.tokenSource ? `token ${resolution.tokenSource}` : "op's own sign-in";
+    return `${vault}, ${token}: ${filled} key(s) from 1Password`;
+}
+function unresolvedDetail(resolution) {
+    const failures = resolution.unresolved.map((item) => `${item.key} from ${item.reference} (${item.reason})`);
+    return [resolution.error, ...failures].filter((part) => Boolean(part)).join("; ");
+}
+async function onePasswordCheck() {
+    const resolution = getDefaultSecretStore().onePasswordResolution();
+    const version = await opVersion();
+    const cli = version ? `op ${version}` : "op not on PATH";
+    if (!resolution?.attempted) {
+        const tokenSource = readOnePasswordSettings(process.env).token.source;
+        const token = tokenSource ? `token ${tokenSource}, ` : "";
+        return check({ id: "one-password", label: "1Password", status: "ok", detail: `not used (${token}${cli}); to read keys from a vault: videobook setup 1password --op-vault <vault>`, required: false });
+    }
+    const problems = unresolvedDetail(resolution);
+    return check({
+        id: "one-password",
+        label: "1Password",
+        status: problems ? "warn" : "ok",
+        detail: `${describeResolution(resolution)}${problems ? `; unresolved: ${problems}` : ""} (${cli})`,
+        ...(problems ? { remedy: "Check the references and the service-account token, or run videobook setup 1password again." } : {}),
+        required: false,
+    });
+}
+function providerKeysCheck() {
+    const store = getDefaultSecretStore();
+    const configured = MANAGED_ENV_KEYS.filter((key) => key.endsWith("_API_KEY") && store.getSource(key) !== "missing");
+    if (configured.length === 0) {
+        return check({
+            id: "provider-keys",
+            label: "Provider keys",
+            status: "warn",
+            detail: "none configured; generation and transcription tools will fail",
+            remedy: `Add keys such as OPENAI_API_KEY to ${dataLayout().envPath} or the environment.`,
+            required: false,
+        });
+    }
+    const shown = configured.map((key) => `${key} (${store.getSource(key)})`);
+    return check({ id: "provider-keys", label: "Provider keys", status: "ok", detail: shown.join(", "), required: false });
+}
+async function ownerCheck(port) {
+    const owner = await inspectServerOwner(bookManager.rootDir);
+    if (owner.kind === "running") {
+        return check({ id: "owner", label: "Server", status: "ok", detail: `running at ${owner.record.url} (pid ${owner.record.pid})`, required: false });
+    }
+    if (owner.kind === "unresponsive") {
+        return check({ id: "owner", label: "Server", status: "warn", detail: `pid ${owner.record.pid} holds the library but does not answer at ${owner.record.url}`, required: false });
+    }
+    return check({ id: "owner", label: "Server", status: "ok", detail: `not running (videobook serve listens on 127.0.0.1:${port})`, required: false });
+}
+async function collectDoctorChecks() {
+    return [
+        nodeCheck(),
+        await dataHomeCheck(),
+        await libraryCheck(),
+        await binaryCheck("ffmpeg", "ffmpeg", FFMPEG, bundledPath("ffmpeg-static"), "VIDEOBOOK_FFMPEG_PATH"),
+        await binaryCheck("ffprobe", "ffprobe", FFPROBE, bundledFfprobe(), "VIDEOBOOK_FFPROBE_PATH"),
+        ytdlpCheck(),
+        nativeCoreCheck(),
+        searchRuntimeCheck(),
+        await renderBrowserCheck(),
+        await onePasswordCheck(),
+        providerKeysCheck(),
+        await ownerCheck(resolvePort(process.env)),
+    ];
+}
+function statusLabel(status) {
+    return status === "ok" ? "ok  " : status === "warn" ? "warn" : "FAIL";
+}
+function renderText(checks) {
+    const lines = checks.flatMap((item) => [
+        `${statusLabel(item.status)}  ${item.label.padEnd(16)} ${item.detail}`,
+        ...(item.remedy && item.status !== "ok" ? [`      ${"".padEnd(16)} fix: ${item.remedy}`] : []),
+    ]);
+    return `${lines.join("\n")}\n`;
+}
+function doctorExitCode(checks) {
+    return checks.some((item) => item.required && item.status === "fail") ? 1 : 0;
+}
+export async function runDoctorCommand(flags) {
+    getDefaultSecretStore().resolveOnePassword();
+    const checks = await collectDoctorChecks();
+    const code = doctorExitCode(checks);
+    process.stdout.write(flags.json ? `${JSON.stringify({ ok: code === 0, checks }, null, 2)}\n` : renderText(checks));
+    return code;
+}