videobook 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to the `videobook` npm package are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the package uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-19
+
+### Added
+
+- `videobook config` lists where every provider key comes from, with secret
+  values masked; `config get`, `config set` and `config unset` edit the
+  data-home `.env` atomically.
+- 1Password support: `op://` references in the environment or `.env` resolve
+  through the 1Password CLI when a server starts, and
+  `videobook setup 1password --op-vault <vault>` reads every key from a vault
+  whose items are named after the keys. `videobook doctor` reports the setup
+  and which keys 1Password supplied.
+- `VIDEOBOOK_YTDLP_PATH` selects the yt-dlp binary.
+- `list_jobs` accepts `job_keys`, the `job_id` strings other tools return.
+
+### Changed
+
+- ffprobe now comes from `@ffprobe-installer/ffprobe`, which installs one
+  native build for the current platform instead of `ffprobe-static`'s builds
+  for every platform. Apple Silicon and Linux arm64 get a bundled ffprobe, and
+  the install is about 300 MB smaller. When npm skips the package's chmod
+  script, videobook marks the binary executable itself.
+- The npm page no longer links to the private source repository, which
+  anonymous visitors cannot open; its homepage is the npm package page.
+- The README states that Windows is not supported yet, and why, instead of
+  calling it untested.
+
+### Fixed
+
+- Downloading videos from URLs works when npm blocked the yt-dlp download:
+  videobook falls back to `yt-dlp` on `PATH`, passes yt-dlp the resolved
+  ffmpeg so format merges work, and fails with install instructions when no
+  yt-dlp exists. `videobook doctor` shows which yt-dlp is used.
+- `videobook run` waits for queued jobs on an already running server too,
+  instead of returning while the job runs, and reports how the job ended.
+
+## [0.1.0] - 2026-10-19
+
+### Added
+
+- `videobook` command-line interface: `serve` runs the MCP server with the
+  bundled web UI (or `--headless` for MCP and API only), `mcp` serves MCP over
+  stdio for agent hosts, `run` and `tools` call MCP tools from the shell,
+  `gc-books` reclaims catalog storage, and `doctor` checks the local
+  environment.
+- Installed data defaults to `~/.videobook`, overridable with `VIDEOBOOK_HOME`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Tanner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,196 @@
-# Temporary Holding Version
+# videobook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Videobook is a local-first notebook studio for generative media: images,
+videos, audio, prompts, characters and scenes live as cells in an executable
+graph, and every change is recorded as a revision. This package installs one
+`videobook` command that runs the Videobook MCP server three ways:
+
+- with the web UI at `http://127.0.0.1:3001/`
+- headless, serving MCP and the HTTP API only
+- over stdio, for agent hosts such as Claude Code
+
+## Requirements
+
+- Node.js 22 or newer.
+- macOS (Apple Silicon or Intel) or Linux (x64 or arm64). Windows is not
+  supported yet; see the platform notes.
+- About 800 MB of disk. Installing downloads the ffmpeg and yt-dlp binaries
+  from GitHub, and the first video render downloads Chrome Headless Shell
+  (about 150 MB) into `~/.cache/videobook/remotion`.
+- Native ffmpeg, ffprobe and yt-dlp builds come with the package. Every
+  platform falls back to `ffmpeg`, `ffprobe` and `yt-dlp` on `PATH` when a
+  bundled binary is missing.
+
+## Install
+
+```bash
+npm install -g videobook
+videobook doctor
+```
+
+npm 12 and newer skip dependency install scripts unless you approve them.
+Approve the six that videobook needs, either per install or once for your
+user:
+
+```bash
+npm install -g videobook --allow-scripts=ffmpeg-static,ytdlp-nodejs,@dolthub/doltlite,usearch,onnxruntime-node,esbuild
+npm config set allow-scripts=ffmpeg-static,ytdlp-nodejs,@dolthub/doltlite,usearch,onnxruntime-node,esbuild --location=user
+```
+
+- `ffmpeg-static` downloads ffmpeg, which every media operation needs.
+- `ytdlp-nodejs` downloads yt-dlp, which downloading videos from URLs needs.
+  Without it, videobook uses `yt-dlp` on `PATH` or `VIDEOBOOK_YTDLP_PATH`.
+- `@dolthub/doltlite`, `usearch` and `onnxruntime-node` use prebuilt native
+  binaries and only compile or fetch extras on unusual platforms.
+- `esbuild` checks its platform binary for the Remotion renderer.
+
+npm also reports the install script of `@ffprobe-installer/<platform>`, for
+example `@ffprobe-installer/darwin-arm64`. It only marks ffprobe executable,
+which videobook does itself when it starts, so it can stay unapproved. With
+`--strict-allow-scripts`, approve it too.
+
+`videobook doctor` reports anything missing and prints the fix.
+
+## Run
+
+```bash
+videobook                      # same as videobook serve
+videobook serve --open         # serve MCP and the web UI, open a browser
+videobook serve --headless     # MCP and HTTP API only
+videobook mcp                  # MCP over stdio for agent hosts
+videobook run list_books       # call one MCP tool and print its result
+videobook run create_book name=demo
+videobook tools                # list tools and their parameters
+videobook gc-books             # reclaim catalog storage in every book
+videobook doctor               # check Node, binaries, native modules and keys
+videobook config               # show where each provider key comes from
+videobook config set FAL_API_KEY op://Private/FAL_API_KEY/password
+videobook setup 1password --op-vault Private
+videobook --version
+```
+
+Every command accepts `--port <n>` (default 3001), `--library <dir>`,
+`--home <dir>` and `--log-level <silent|error|warn|info|debug>`. Tool
+arguments are `key=value`; values that parse as JSON are passed as JSON. When
+a tool queues a job, `run` waits for it to finish, up to `--timeout <s>`
+(default 600), and exits 1 if the job fails. `--no-wait` returns at once,
+except on a server that `run` started for itself, which stops when `run`
+exits. Exit codes are 0 for success, 1 for a failure and 2 for a usage error.
+
+## Agent hosts
+
+```bash
+claude mcp add videobook -- videobook mcp
+```
+
+Other hosts take the same command, for example
+`{ "command": "videobook", "args": ["mcp"] }`. stdio accepts clients that
+start with the 2025-era `initialize` and clients that use MCP 2026-07-28.
+While `videobook serve` runs, HTTP clients can connect to
+`http://127.0.0.1:3001/mcp`, which speaks MCP 2026-07-28 only.
+
+## One server per library
+
+A library is owned by one videobook process at a time, recorded in
+`<library>/.videobook-server.json`. A second `videobook serve` for the same
+library exits and names the running URL. `videobook mcp` and `videobook run`
+relay to the running server when there is one; otherwise they start one in
+their own process, which `videobook mcp` keeps serving HTTP and the web UI
+for as long as the agent host keeps it open. `videobook gc-books` refuses to
+run while a server owns the library.
+
+## Data and configuration
+
+Installed data lives in `~/.videobook`:
+
+- `books/`, the library of books
+- `app-state.json`, connected X and Dropbox accounts
+- `.env`, provider keys, also editable from Settings in the web UI
+
+`VIDEOBOOK_HOME` or `--home` moves all three. `VIDEOBOOK_LIBRARY_DIR`,
+`VIDEOBOOK_APP_STATE_PATH` and `VIDEOBOOK_ENV_PATH` move one each; `--home`
+overrides any of them inherited from your shell. Set `VIDEOBOOK_HOME` and
+`VIDEOBOOK_ENV_PATH` in the environment, not in `.env`, because they decide
+which `.env` is read.
+
+Caches live in `~/.cache/videobook`. Other settings: `PORT`,
+`VIDEOBOOK_FFMPEG_PATH`, `VIDEOBOOK_FFPROBE_PATH`, `VIDEOBOOK_YTDLP_PATH`,
+`VIDEOBOOK_REMOTION_CACHE_DIR`, `VIDEOBOOK_MODEL_CACHE_DIR`,
+`VIDEOBOOK_DOWNLOADS_DIR` and `VIDEOBOOK_LOG_LEVEL`.
+
+## Provider keys
+
+The keys are `OPENAI_API_KEY`, `KIE_API_KEY`, `XAI_API_KEY`, `FAL_API_KEY`,
+`DASHSCOPE_API_KEY`, `ELEVENLABS_API_KEY`, `KIMI_CODING_API_KEY`,
+`X_CLIENT_ID` and `X_CLIENT_SECRET`, `DROPBOX_CLIENT_ID` and
+`DROPBOX_CLIENT_SECRET`, and the `B2_*` storage settings. The server starts
+without any of them; tools that need one report which.
+
+A key can come from four places. The first one that has it wins:
+
+1. The environment of the videobook process.
+2. A value in `.env`, set with `videobook config set <KEY> <value>` or from
+   Settings in the web UI.
+3. A 1Password secret reference in `.env`, such as
+   `op://Private/FAL_API_KEY/password`.
+4. A 1Password vault whose items are named after the keys.
+
+`videobook config` lists every key with its source and masks secret values.
+`config get`, `config set` and `config unset` work on one key and edit
+`.env` atomically. `config set` refuses a key that your shell already
+exports, because the exported value would win.
+
+### 1Password
+
+References and vaults need the [1Password CLI](https://developer.1password.com/docs/cli/)
+(`op`). When a server starts, videobook resolves every `op://` value in the
+environment and `.env`, and every key the vault has, in one `op inject` run.
+`videobook run` and `videobook mcp` skip this when they relay to a running
+server.
+
+```bash
+videobook setup 1password --op-vault Private      # use op's own sign-in
+videobook setup 1password --op-vault Apicity --op-token env:OP_SERVICE_ACCOUNT_TOKEN
+videobook doctor                                  # shows which keys came from 1Password
+videobook setup 1password --remove
+```
+
+`setup 1password` saves `VIDEOBOOK_OP_VAULT` and `VIDEOBOOK_OP_SERVICE_TOKEN`
+in `.env`, then lists the vault to report which keys it holds; `--no-verify`
+skips the listing. A vault item supplies a key when its title is the key name,
+and the value is read from its `password` field, for example
+`op://Apicity/OPENAI_API_KEY/password`.
+
+The token setting takes `env:VAR`, `$VAR` or a literal service-account
+token. Prefer `env:VAR`, which keeps the token out of the file. When
+`OP_SERVICE_ACCOUNT_TOKEN` is exported, setup records
+`env:OP_SERVICE_ACCOUNT_TOKEN`. Without a token, `op` uses its own sign-in.
+The token reaches `op` only through its environment, never its arguments.
+
+A reference that does not resolve is left unset, so it is never sent to a
+provider as a key. The server and `videobook doctor` report it. Keys that
+come from 1Password are read-only in Settings.
+
+## Platform notes
+
+- macOS on Apple Silicon is the primary platform.
+- macOS on Intel works, but ONNX Runtime has no Intel Mac build, so semantic
+  search is unavailable there.
+- Linux x64 and arm64 are supported.
+- Windows is not supported yet. Every native dependency has a Windows x64
+  build, but the release smoke test has not passed on Windows. Windows has no
+  SIGTERM, so stopping `videobook serve` from another process ends it without
+  a clean shutdown, and the next start replaces the lock file it leaves. The
+  Release check workflow runs the smoke test on Windows for every release tag
+  without blocking the release.
+
+## Security
+
+Videobook is a local, single-user service. It listens on `127.0.0.1` only and
+accepts requests from loopback hosts and origins. It has no user
+authentication, so do not expose it to other machines or share it between
+users.
+
+## License
+
+MIT

package/bin/videobook.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22) {
+  process.stderr.write(`videobook needs Node.js 22 or newer; this is ${process.version}.\nInstall Node.js 22+ from https://nodejs.org or your version manager, then run videobook again.\n`);
+  process.exit(1);
+}
+await import(new URL("../dist/cli/entry.js", import.meta.url).href);

package/dist/acestep/client.js

@@ -0,0 +1,203 @@
+import { readFile } from "node:fs/promises";
+import { AceStepError } from "./errors.js";
+// The live ace-server job flow (tools/ace-server.cpp, verified against version
+// 9761469): POST /synth returns {"id"} immediately, a FIFO worker thread runs
+// the GPU job, GET /job?id reports running|done|failed|cancelled, GET
+// /job?id&result=1 serves the multipart/mixed body (fixed boundary
+// "ace-batch-boundary": one audio part plus one latent part per track), and
+// POST /job?id&cancel=1 cancels a running job. Completed jobs are evicted FIFO
+// past 32, so the result is fetched immediately after the poll reports done.
+const DEFAULT_SYNTH_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const SUBMIT_TIMEOUT_MS = 60_000;
+const POLL_TIMEOUT_MS = 5_000;
+const RESULT_TIMEOUT_MS = 120_000;
+const ERROR_BODY_PREVIEW_CHARS = 500;
+export async function isHealthy(baseUrl, timeoutMs = 500) {
+    try {
+        const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function wireRequest(request) {
+    return {
+        caption: request.caption,
+        lyrics: request.lyrics,
+        task_type: request.taskType,
+        output_format: request.outputFormat,
+        seed: request.seed,
+        inference_steps: request.inferenceSteps,
+        audio_cover_strength: request.audioCoverStrength,
+        synth_batch_size: request.synthBatchSize,
+        synth_model: request.synthModel,
+        duration: request.duration,
+    };
+}
+function headerRecord(headerBlock) {
+    const headers = {};
+    for (const line of headerBlock.split("\r\n")) {
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    return headers;
+}
+export function parseMultipartMixed(body, contentType) {
+    const boundaryMatch = /boundary="?([^";]+)"?/u.exec(contentType);
+    if (boundaryMatch === null) {
+        throw new AceStepError("malformed_response", `ace-server response has no multipart boundary (content-type: "${contentType}")`);
+    }
+    const delimiter = Buffer.from(`--${boundaryMatch[1]}`);
+    const parts = [];
+    let offset = body.indexOf(delimiter);
+    while (offset !== -1) {
+        const afterDelimiter = offset + delimiter.length;
+        if (body.subarray(afterDelimiter, afterDelimiter + 2).toString("latin1") === "--")
+            break;
+        const boundaryLineEnd = body.indexOf("\r\n", afterDelimiter);
+        const headerEnd = body.indexOf("\r\n\r\n", afterDelimiter);
+        const next = headerEnd === -1 ? -1 : body.indexOf(delimiter, headerEnd + 4);
+        if (boundaryLineEnd === -1 || headerEnd === -1 || next === -1) {
+            throw new AceStepError("malformed_response", "ace-server multipart response is truncated");
+        }
+        const headerBlock = body.subarray(boundaryLineEnd + 2, headerEnd).toString("utf8");
+        let dataEnd = next;
+        if (body.subarray(dataEnd - 2, dataEnd).toString("latin1") === "\r\n")
+            dataEnd -= 2;
+        parts.push({ headers: headerRecord(headerBlock), data: body.subarray(headerEnd + 4, dataEnd) });
+        offset = next;
+    }
+    if (parts.length === 0) {
+        throw new AceStepError("malformed_response", "ace-server multipart response contained no parts");
+    }
+    return parts;
+}
+function describeFetchError(error) {
+    if (error instanceof Error) {
+        const cause = error.cause instanceof Error ? `: ${error.cause.message}` : "";
+        return `${error.message}${cause}`;
+    }
+    return String(error);
+}
+async function readErrorPreview(response) {
+    const bodyText = await response.text().catch(() => "");
+    return bodyText.slice(0, ERROR_BODY_PREVIEW_CHARS);
+}
+async function submitSynthJob(baseUrl, srcWavPath, request, signal) {
+    const sourceBytes = await readFile(srcWavPath);
+    const form = new FormData();
+    form.set("request", new Blob([JSON.stringify(wireRequest(request))], { type: "application/json" }), "request.json");
+    form.set("audio", new Blob([sourceBytes], { type: "audio/wav" }), "source.wav");
+    const response = await fetch(`${baseUrl}/synth`, { method: "POST", body: form, signal });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /synth returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const body = (await response.json().catch(() => null));
+    if (typeof body?.id !== "string" || body.id.length === 0) {
+        throw new AceStepError("malformed_response", "ace-server /synth returned no job id");
+    }
+    return body.id;
+}
+async function readJobStatus(baseUrl, jobId) {
+    const response = await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}`, {
+        signal: AbortSignal.timeout(POLL_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /job returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const body = (await response.json().catch(() => null));
+    if (typeof body?.status !== "string") {
+        throw new AceStepError("malformed_response", "ace-server /job returned no status");
+    }
+    return body.status;
+}
+async function cancelSynthJob(baseUrl, jobId) {
+    try {
+        await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}&cancel=1`, {
+            method: "POST",
+            signal: AbortSignal.timeout(POLL_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Best-effort: the job also dies with the server, and an orphaned
+        // generation is discarded when its result is never fetched.
+    }
+}
+async function fetchSynthResult(baseUrl, jobId) {
+    const response = await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}&result=1`, {
+        signal: AbortSignal.timeout(RESULT_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /job result returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = Buffer.from(await response.arrayBuffer());
+    if (contentType.startsWith("audio/")) {
+        return { audio: body, audioContentType: contentType, latents: null };
+    }
+    const parts = parseMultipartMixed(body, contentType);
+    const audioPart = parts.find((part) => (part.headers["content-type"] ?? "").startsWith("audio/"));
+    if (audioPart === undefined) {
+        throw new AceStepError("malformed_response", "ace-server synth result contained no audio part");
+    }
+    const latentPart = parts.find((part) => (part.headers["content-type"] ?? "").startsWith("application/octet-stream"));
+    return {
+        audio: audioPart.data,
+        audioContentType: audioPart.headers["content-type"] ?? "audio/wav",
+        latents: latentPart?.data ?? null,
+    };
+}
+async function delay(ms, signal) {
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new Error("Aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export async function synthCover(baseUrl, srcWavPath, request, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SYNTH_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadlineSignal = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, deadlineSignal])
+        : deadlineSignal;
+    let jobId = null;
+    try {
+        jobId = await submitSynthJob(baseUrl, srcWavPath, request, AbortSignal.any([signal, AbortSignal.timeout(SUBMIT_TIMEOUT_MS)]));
+        for (;;) {
+            const status = await readJobStatus(baseUrl, jobId);
+            if (status === "done")
+                return await fetchSynthResult(baseUrl, jobId);
+            if (status === "failed") {
+                throw new AceStepError("synth_failed", "ace-server reported the cover synthesis job as failed; the reason is in the [ace-step] logs above");
+            }
+            if (status === "cancelled") {
+                throw new AceStepError("synth_failed", "ace-server cancelled the cover synthesis job");
+            }
+            signal.throwIfAborted();
+            await delay(pollIntervalMs, signal);
+        }
+    }
+    catch (error) {
+        if (error instanceof AceStepError)
+            throw error;
+        if (jobId !== null && signal.aborted)
+            await cancelSynthJob(baseUrl, jobId);
+        if (options.signal?.aborted)
+            throw error;
+        if (deadlineSignal.aborted) {
+            throw new AceStepError("synth_timeout", `ace-server cover synthesis did not finish within ${timeoutMs}ms`);
+        }
+        throw new AceStepError("server_exited", `ace-server request failed: ${describeFetchError(error)}. The server may have crashed or been stopped; check [ace-step] logs.`);
+    }
+}

package/dist/acestep/config.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isHealthy } from "./client.js";
+const DEFAULT_PORT = 8317;
+const DEFAULT_MODEL = "acestep-v15-turbo-Q4_K_M.gguf";
+const TEXT_ENCODER_MODEL = "Qwen3-Embedding-0.6B-Q8_0.gguf";
+const VAE_MODEL = "vae-BF16.gguf";
+const GATE_HEALTH_TIMEOUT_MS = 500;
+function acestepRoot() {
+    return join(homedir(), ".cache", "videobook", "acestep");
+}
+export function aceStepConfig() {
+    const baseUrl = process.env.VIDEOBOOK_ACESTEP_BASE_URL?.trim();
+    const parsedPort = Number.parseInt(process.env.VIDEOBOOK_ACESTEP_PORT ?? "", 10);
+    return {
+        baseUrl: baseUrl ? baseUrl.replace(/\/+$/u, "") : null,
+        serverPath: process.env.VIDEOBOOK_ACESTEP_SERVER_PATH?.trim() || join(acestepRoot(), "bin", "ace-server"),
+        modelsDir: process.env.VIDEOBOOK_ACESTEP_MODELS_DIR?.trim() || join(acestepRoot(), "models"),
+        port: Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : DEFAULT_PORT,
+        model: process.env.VIDEOBOOK_ACESTEP_MODEL?.trim() || DEFAULT_MODEL,
+        keepLoaded: process.env.VIDEOBOOK_ACESTEP_KEEP_LOADED === "1",
+    };
+}
+function requiredModelFiles(config = aceStepConfig()) {
+    return [config.model, TEXT_ENCODER_MODEL, VAE_MODEL];
+}
+export function checkLocalAvailability(config = aceStepConfig()) {
+    if (!existsSync(config.serverPath)) {
+        return {
+            available: false,
+            kind: "binary_missing",
+            reason: `acestep.cpp runtime is not installed: ace-server not found at ${config.serverPath}. ` +
+                `Run "npm run install:acestep", or set VIDEOBOOK_ACESTEP_SERVER_PATH / VIDEOBOOK_ACESTEP_BASE_URL.`,
+        };
+    }
+    const missing = requiredModelFiles(config).filter((name) => !existsSync(join(config.modelsDir, name)));
+    if (missing.length > 0) {
+        return {
+            available: false,
+            kind: "models_missing",
+            reason: `ACE-Step models missing from ${config.modelsDir}: ${missing.join(", ")}. Run "npm run install:acestep".`,
+        };
+    }
+    return { available: true };
+}
+export async function checkAceStepAvailability() {
+    const config = aceStepConfig();
+    if (config.baseUrl !== null) {
+        const healthy = await isHealthy(config.baseUrl, GATE_HEALTH_TIMEOUT_MS);
+        if (!healthy) {
+            return {
+                available: false,
+                kind: "unreachable",
+                reason: `ace-server at ${config.baseUrl} did not answer /health within ${GATE_HEALTH_TIMEOUT_MS}ms ` +
+                    `(VIDEOBOOK_ACESTEP_BASE_URL). Start it or unset the variable.`,
+            };
+        }
+        return { available: true };
+    }
+    return checkLocalAvailability(config);
+}

package/dist/acestep/errors.js

@@ -0,0 +1,8 @@
+export class AceStepError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "AceStepError";
+        this.kind = kind;
+    }
+}