@panelwave/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 PanelWave Project
+
+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,157 @@
-# Temporary Holding Version
-
-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.
+# @panelwave/mcp
+
+Local [MCP](https://modelcontextprotocol.io) bridge for [PanelWave](https://panelwave.org). It connects Claude Desktop, Claude Code, Cowork, Cursor and other MCP clients to the hosted PanelWave MCP server. It also adds tools that work on files of your computer: find panel artwork in a folder, read a script, and upload a whole folder of artwork into a work.
+
+```
+MCP client ──stdio──▶ @panelwave/mcp ──HTTPS + token──▶ mcp.panelwave.org ──▶ your PanelWave works
+                          │
+                          └── pw_local_* tools (only inside PANELWAVE_ALLOWED_DIRS)
+```
+
+The bridge mirrors the hosted server. Tool names, schemas, results and errors pass through unchanged, and its resources are forwarded too. When PanelWave adds or changes a tool, your client picks it up without a bridge update. If you only need the hosted tools and your client supports remote MCP servers, you can connect to `https://mcp.panelwave.org/mcp` directly instead. Uploading local files needs the bridge.
+
+## Quick start
+
+1. Create a personal access token in PanelWave: **Profile → Connected apps & access tokens**. Tokens start with `pw_pat_`. For the script-to-work flow below, tick `works:read`, `works:write`, `assets:read` and `assets:write`.
+2. Install Node.js 20 or newer.
+3. Add the bridge to your client as shown below. Set `PANELWAVE_ALLOWED_DIRS` to the folder that holds your scripts and artwork.
+
+### Claude Code
+
+```bash
+claude mcp add panelwave \
+  --env PANELWAVE_TOKEN=pw_pat_… \
+  --env PANELWAVE_ALLOWED_DIRS="$HOME/comics" \
+  -- npx -y @panelwave/mcp
+```
+
+Run `/mcp` inside Claude Code to check that `panelwave` is connected.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "panelwave": {
+      "command": "npx",
+      "args": ["-y", "@panelwave/mcp"],
+      "env": {
+        "PANELWAVE_TOKEN": "pw_pat_…",
+        "PANELWAVE_ALLOWED_DIRS": "/Users/me/comics"
+      }
+    }
+  }
+}
+```
+
+On Windows, write the folder as `"C:\\Users\\me\\comics"`. If Claude Desktop cannot find `npx`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@panelwave/mcp"]`.
+
+### Cowork
+
+Cowork runs inside the Claude Desktop app. Configure the bridge as for Claude Desktop above. Point `PANELWAVE_ALLOWED_DIRS` at the same folder you give Cowork to work in, so both see the same files.
+
+### Cursor
+
+Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:
+
+```json
+{
+  "mcpServers": {
+    "panelwave": {
+      "command": "npx",
+      "args": ["-y", "@panelwave/mcp"],
+      "env": { "PANELWAVE_TOKEN": "pw_pat_…", "PANELWAVE_ALLOWED_DIRS": "/Users/me/comics" }
+    }
+  }
+}
+```
+
+### Other clients
+
+Any client that starts stdio servers works the same way. The command is `npx -y @panelwave/mcp`, and the environment variables below are the configuration.
+
+## Walkthrough: from a script and a folder of panels to a work
+
+Say `~/comics/rooftop` holds a script and the finished panels:
+
+```
+rooftop/
+  script.md          (or .fountain / .txt)
+  panels/
+    panel-01.png
+    panel-02.png
+    …
+    panel-12.jpg
+```
+
+Then ask the assistant, one step at a time or all at once:
+
+1. **"Read rooftop/script.md and turn it into a PanelWave work: one panel per shot, speech balloons from the dialogue, mobile and A4 formats."** The assistant reads the script with `pw_local_read_text` and drafts an outline. It shows you a dry run of `pw_works_create_from_outline`, then creates the work.
+2. **"Upload the images in rooftop/panels into that work, into a folder called Panels."** `pw_local_upload_files` hashes each file, reads its dimensions and uploads it. Large videos go up in parts. Files already in the library are reused, so running this again after an interruption only uploads what is missing.
+3. **"Attach panel-01 to the first panel, panel-02 to the second, and so on."** `pw_panels_attach_artwork` sets each image as the panel's background. It fits the panel to the image's aspect ratio on every page format.
+4. **"Check the work."** `pw_validation_run` lists what is still missing, such as panels without artwork or untranslated balloons. Open the editor link from step 1 to review and publish.
+
+The assistant asks before destructive steps such as deleting pages or panels.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `PANELWAVE_TOKEN` | *(required)* | Personal access token. The bridge refuses to start without it. |
+| `PANELWAVE_MCP_URL` | `https://mcp.panelwave.org/mcp` | Hosted endpoint. Plain `http` is accepted only for `localhost`. |
+| `PANELWAVE_ALLOWED_DIRS` | *(none — local tools off)* | Folders the local tools may read, separated by `;` on Windows and `:` on macOS/Linux. Without it the bridge only mirrors the hosted tools. A drive root or your whole home folder is refused. |
+
+`panelwave-mcp --version` prints the version and `--help` a short usage. The bridge writes diagnostics to stderr, and your client shows them in its MCP log.
+
+## Local tools
+
+| Tool | What it does |
+|------|--------------|
+| `pw_local_list_files` | Lists a folder: absolute path, size, mime type, kind, and for images the pixel dimensions with EXIF orientation applied. Supports a name glob such as `*.{png,jpg}`, subfolders and a limit. Files sort naturally, so `panel-2` comes before `panel-10`. |
+| `pw_local_read_text` | Reads a UTF-8 text file such as a script, `.fountain` screenplay or outline. Files over 1 MiB are cut and flagged `truncated`; `maxBytes` goes up to 5 MiB. Binary files are refused. |
+| `pw_local_upload_files` | Uploads images, videos, audio and fonts into a work's asset library, from a folder with an optional glob or from a list of paths. See below. |
+
+Every path is resolved, with symlinks followed, and must stay inside `PANELWAVE_ALLOWED_DIRS`. Anything else fails with `INVALID_INPUT`. The check runs on the path text before the filesystem is touched, and network paths (`\\server\share`) are refused, so a path can never make Windows connect to another machine. Relative paths are taken from the first allowed folder. Hidden files and `node_modules` are skipped in listings unless you ask for them, and `pw_local_read_text` never reads hidden files or folders such as `.ssh` or `.env`. The list and read tools never change anything.
+
+Uploads go only to the https storage URLs the hosted server signs (plain http only on localhost, for development), and the bridge never sends its token or cookies there.
+
+### How uploads work
+
+- **Deduplicated.** Each file's SHA-256 is compared with the library first. Content that is already there, or appears twice in one batch, is not uploaded again; its row reports the existing asset id. Pass `skipDuplicates: false` to get a `CONFLICT` row instead.
+- **Resumable.** Because finished files are recognised by their hash, running the same upload again after a failure only sends the files that are missing.
+- **Large files in parts.** Files of 10 MB or more are uploaded in 5 MiB parts. Each part is read from disk just before it is sent, so a 2 GB video does not need 2 GB of memory.
+- **Retries.** Each transfer is tried up to 3 times with backoff. An expired upload URL is renewed automatically. An unfinished multipart upload is aborted so storage discards its parts.
+- **Parallel.** Three files are uploaded at a time by default, configurable up to 6 with `concurrency`.
+- **Metadata.** Image width and height are read locally with EXIF orientation applied. Video duration and dimensions are filled in by PanelWave after transcoding.
+- **Folders and tags.** `folderName` files every upload into an asset-library folder and creates it when missing. Use `"Chapter 1/Panels"` for a nested folder. Files that were already in the library are added to the folder too. `tags` are stored on new assets.
+- **Progress.** The tool reports byte progress to clients that show it.
+
+The result has one row per file with the status `uploaded`, `exists`, `failed` or `cancelled`, the asset id, and any warnings. An example warning is an image over 5 MB that needs an optimized variant before publishing.
+
+## Errors
+
+Tool errors come back as results with `isError: true` and a structured body `{ code, message }`. The codes are the same as on the hosted server:
+
+- **`UNAUTHENTICATED`** means PanelWave rejected the token because it expired, was revoked or was mistyped. Create a new token and update the client configuration.
+- **`UPSTREAM_UNAVAILABLE`** means the hosted server or the upload storage is unreachable. The list and read tools keep working. The bridge retries in the background and announces the PanelWave tools once it reaches the server.
+- **`INVALID_INPUT`**, **`NOT_FOUND`** and **`PRECONDITION_FAILED`** come from the local tools, for example for a path outside the allowed folders, a missing file or a binary file.
+- **`QUOTA_EXCEEDED`**, **`PERMISSION_DENIED`** and other hosted codes are passed through unchanged, also inside upload rows.
+
+## Development
+
+From the repository root:
+
+```bash
+npm install
+npm run build:mcp
+npm test --workspace=packages/mcp
+MCP_BIG_UPLOAD=1 npm test --workspace=packages/mcp   # adds the 100 MB streaming upload test
+```
+
+The tests run the bridge against an in-process stand-in for the hosted server, over both in-memory and Streamable HTTP transports. Uploads are tested against a simulated gateway and a mock S3 endpoint that can fail on demand.
+
+## License
+
+MIT

package/dist/bridge.d.ts

@@ -0,0 +1,34 @@
+import { Server } from '@modelcontextprotocol/server';
+import type { BridgeConfig } from './config';
+import { type LocalTool } from './local-tools';
+import { RemoteProxy } from './remote';
+export declare const LOCAL_INSTRUCTIONS: string;
+export interface BridgeOptions {
+    config: BridgeConfig;
+    remote: RemoteProxy;
+    localTools?: LocalTool[];
+    log?: (message: string) => void;
+}
+/**
+ * The stdio-facing MCP server: local file tools plus a transparent mirror of
+ * the hosted PanelWave server (tool names, schemas, results and errors are
+ * passed through untouched).
+ */
+export declare function createBridgeServer(opts: BridgeOptions): Server;
+export interface RunningBridge {
+    server: Server;
+    remote: RemoteProxy;
+    close(): Promise<void>;
+}
+/**
+ * Build the proxy + server. The remote is contacted once up front (for its
+ * instructions and tool list); when that fails the bridge still starts and
+ * retries in the background, announcing the remote tools via list_changed
+ * once they are reachable.
+ */
+export declare function startBridge(config: BridgeConfig, opts?: {
+    log?: (message: string) => void;
+    remote?: RemoteProxy;
+    connectTimeoutMs?: number;
+    retryMs?: number;
+}): Promise<RunningBridge>;

package/dist/bridge.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_INSTRUCTIONS = void 0;
+exports.createBridgeServer = createBridgeServer;
+exports.startBridge = startBridge;
+const server_1 = require("@modelcontextprotocol/server");
+const errors_1 = require("./errors");
+const local_tools_1 = require("./local-tools");
+const remote_1 = require("./remote");
+exports.LOCAL_INSTRUCTIONS = [
+    'This PanelWave connection runs through the local bridge (@panelwave/mcp).',
+    'Besides the hosted pw_* tools it offers pw_local_* tools that work on files of this computer:',
+    'pw_local_list_files finds panel artwork or scripts in a folder, pw_local_read_text reads a script or outline,',
+    'pw_local_upload_files uploads a folder of artwork into a work (deduplicated, resumable) before pw_panels_attach_artwork.',
+    'Only folders listed in PANELWAVE_ALLOWED_DIRS are readable; paths may be absolute or relative to the first allowed folder.',
+].join(' ');
+function toTool(t) {
+    return {
+        name: t.name,
+        title: t.title,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        ...(t.outputSchema ? { outputSchema: t.outputSchema } : {}),
+        annotations: t.annotations,
+    };
+}
+/** Rethrow a remote JSON-RPC error unchanged; anything else becomes an internal protocol error. */
+function asProtocolError(e) {
+    if (e instanceof server_1.ProtocolError)
+        return e;
+    if (e instanceof errors_1.BridgeError)
+        return new server_1.ProtocolError(server_1.ProtocolErrorCode.InternalError, `${e.code}: ${e.message}`, { code: e.code });
+    return new server_1.ProtocolError(server_1.ProtocolErrorCode.InternalError, e instanceof Error ? e.message : String(e));
+}
+/**
+ * The stdio-facing MCP server: local file tools plus a transparent mirror of
+ * the hosted PanelWave server (tool names, schemas, results and errors are
+ * passed through untouched).
+ */
+function createBridgeServer(opts) {
+    const { config, remote } = opts;
+    const log = opts.log ?? (() => undefined);
+    // The local tools exist only when folders were allowed explicitly (PANELWAVE_ALLOWED_DIRS).
+    const localTools = opts.localTools ?? (config.allowedDirs.length ? local_tools_1.LOCAL_TOOLS : []);
+    const localByName = new Map(localTools.map((t) => [t.name, t]));
+    const instructions = [remote.instructions, localTools.length ? exports.LOCAL_INSTRUCTIONS : ''].filter(Boolean).join('\n\n');
+    const server = new server_1.Server({ name: 'panelwave', title: 'PanelWave', version: config.version }, {
+        capabilities: { tools: { listChanged: true }, resources: { listChanged: true } },
+        instructions,
+    });
+    remote.onToolsChanged = () => void server.sendToolListChanged().catch(() => undefined);
+    remote.onResourcesChanged = () => void server.sendResourceListChanged().catch(() => undefined);
+    server.setRequestHandler('tools/list', async () => {
+        let remoteTools = [];
+        try {
+            remoteTools = await remote.listTools();
+        }
+        catch (e) {
+            log(`remote tools unavailable: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return { tools: [...localTools.map(toTool), ...remoteTools.filter((t) => !localByName.has(t.name))] };
+    });
+    server.setRequestHandler('tools/call', async (request, ctx) => {
+        const { name, arguments: args } = request.params;
+        const meta = request.params._meta;
+        const progressToken = ctx.mcpReq._meta?.progressToken ?? meta?.progressToken;
+        const notify = progressToken === undefined
+            ? undefined
+            : (p) => ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken, ...p } }).catch(() => undefined);
+        const local = localByName.get(name);
+        if (local) {
+            return (await local.call(args, {
+                allowedDirs: config.allowedDirs,
+                signal: ctx.mcpReq.signal,
+                callRemote: (toolName, toolArgs, signal) => remote.callTool(toolName, toolArgs, { signal }),
+                progress: async (progress, total, message) => {
+                    await notify?.({ progress, ...(total !== undefined ? { total } : {}), ...(message ? { message } : {}) });
+                },
+            }));
+        }
+        try {
+            return await remote.callTool(name, args, {
+                signal: ctx.mcpReq.signal,
+                onprogress: notify ? (p) => void notify(p) : undefined,
+            });
+        }
+        catch (e) {
+            if (e instanceof server_1.ProtocolError)
+                throw e;
+            if (ctx.mcpReq.signal.aborted)
+                return (0, local_tools_1.errorResult)(new errors_1.BridgeError('CANCELLED', 'The call was cancelled.'));
+            return (0, local_tools_1.errorResult)(e);
+        }
+    });
+    server.setRequestHandler('resources/list', async () => {
+        try {
+            return { resources: await remote.listResources() };
+        }
+        catch (e) {
+            log(`remote resources unavailable: ${e instanceof Error ? e.message : String(e)}`);
+            return { resources: [] };
+        }
+    });
+    server.setRequestHandler('resources/templates/list', async () => {
+        try {
+            return { resourceTemplates: await remote.listResourceTemplates() };
+        }
+        catch (e) {
+            log(`remote resource templates unavailable: ${e instanceof Error ? e.message : String(e)}`);
+            return { resourceTemplates: [] };
+        }
+    });
+    server.setRequestHandler('resources/read', async (request, ctx) => {
+        try {
+            return await remote.readResource(request.params.uri, ctx.mcpReq.signal);
+        }
+        catch (e) {
+            throw asProtocolError(e);
+        }
+    });
+    return server;
+}
+/**
+ * Build the proxy + server. The remote is contacted once up front (for its
+ * instructions and tool list); when that fails the bridge still starts and
+ * retries in the background, announcing the remote tools via list_changed
+ * once they are reachable.
+ */
+async function startBridge(config, opts = {}) {
+    const log = opts.log ?? (() => undefined);
+    const remote = opts.remote ?? new remote_1.RemoteProxy({ url: config.url, token: config.token, version: config.version, log });
+    /** 'connected', 'fatal' (bad token — retrying cannot help) or 'retry'. */
+    const tryConnect = async () => {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', 'connect timed out')), opts.connectTimeoutMs ?? 15_000);
+        });
+        try {
+            await Promise.race([remote.connect().then(() => remote.listTools()), timeout]);
+            return 'connected';
+        }
+        catch (e) {
+            const err = e instanceof errors_1.BridgeError ? e : new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', e instanceof Error ? e.message : String(e));
+            log(`PanelWave MCP server not reachable: ${err.message}`);
+            return err.code === 'UNAUTHENTICATED' ? 'fatal' : 'retry';
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const first = await tryConnect();
+    const server = createBridgeServer({ config, remote, log });
+    let retry;
+    if (first === 'retry') {
+        retry = setInterval(() => {
+            void tryConnect().then((state) => {
+                if (state === 'retry' || !retry)
+                    return;
+                clearInterval(retry);
+                retry = undefined;
+                if (state === 'connected') {
+                    log('connected to the PanelWave MCP server');
+                    void server.sendToolListChanged().catch(() => undefined);
+                    void server.sendResourceListChanged().catch(() => undefined);
+                }
+            });
+        }, opts.retryMs ?? 30_000);
+        retry.unref();
+    }
+    return {
+        server,
+        remote,
+        async close() {
+            if (retry)
+                clearInterval(retry);
+            await remote.close();
+            await server.close().catch(() => undefined);
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+/** Package version — package.json sits one level above both src/ and dist/. */
+export declare const version: string;
+/** Bridge configuration from the environment the MCP client starts it with. */
+export interface BridgeConfig {
+    /** The hosted PanelWave MCP endpoint. */
+    url: string;
+    /** Personal access token (or MCP access token) sent as the bearer credential. */
+    token: string;
+    /** Absolute directories the local file tools may read. */
+    allowedDirs: string[];
+    version: string;
+}
+export declare const DEFAULT_URL = "https://mcp.panelwave.org/mcp";
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv, cwd?: string): BridgeConfig;

package/dist/config.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = exports.DEFAULT_URL = exports.version = void 0;
+exports.loadConfig = loadConfig;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** Package version — package.json sits one level above both src/ and dist/. */
+exports.version = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+exports.DEFAULT_URL = 'https://mcp.panelwave.org/mcp';
+class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+function loadConfig(env = process.env, cwd = process.cwd()) {
+    const token = (env.PANELWAVE_TOKEN ?? '').trim();
+    if (!token) {
+        throw new ConfigError('PANELWAVE_TOKEN is not set. Create a personal access token in PanelWave (Profile → Connected apps & access tokens) and add it to the "env" of this MCP server in your client configuration.');
+    }
+    const url = (env.PANELWAVE_MCP_URL ?? '').trim() || exports.DEFAULT_URL;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new ConfigError(`PANELWAVE_MCP_URL is not a URL: ${url}`);
+    }
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname))) {
+        throw new ConfigError('PANELWAVE_MCP_URL must use https (plain http only for localhost).');
+    }
+    const dirs = (env.PANELWAVE_ALLOWED_DIRS ?? '')
+        .split(path.delimiter)
+        .map((d) => d.trim())
+        .filter(Boolean);
+    // No default folder: without PANELWAVE_ALLOWED_DIRS the local tools are off. Clients often start stdio
+    // servers in the home folder or "/", which would expose everything (security review 2026-09-30).
+    const allowedDirs = dirs.map((d) => path.resolve(cwd, d));
+    const home = path.resolve(os.homedir());
+    const same = (a, b) => (process.platform === 'win32' || process.platform === 'darwin' ? a.toLowerCase() === b.toLowerCase() : a === b);
+    for (const d of allowedDirs) {
+        if (path.parse(d).root === d || same(d.replace(/[\\/]+$/, ''), home)) {
+            throw new ConfigError(`PANELWAVE_ALLOWED_DIRS must name the folders with your comics, not a drive root or your whole home folder (${d}).`);
+        }
+    }
+    return { url: parsed.toString(), token, allowedDirs, version: exports.version };
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error codes of the local tools — the same vocabulary the hosted gateway
+ * uses, so a remote tool error re-raised by a local tool keeps its code.
+ */
+export declare const BRIDGE_ERROR_CODES: readonly ["INVALID_INPUT", "NOT_FOUND", "PERMISSION_DENIED", "UNAUTHENTICATED", "QUOTA_EXCEEDED", "CONFLICT", "RATE_LIMITED", "CONFIRMATION_REQUIRED", "CANCELLED", "PRECONDITION_FAILED", "UPSTREAM_UNAVAILABLE", "FEATURE_DISABLED", "INTERNAL"];
+export type BridgeErrorCode = (typeof BRIDGE_ERROR_CODES)[number];
+export declare class BridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(code: BridgeErrorCode, message: string, details?: unknown | undefined);
+}
+export declare function isBridgeErrorCode(code: unknown): code is BridgeErrorCode;
+export declare function toBridgeError(e: unknown): BridgeError;

package/dist/errors.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeError = exports.BRIDGE_ERROR_CODES = void 0;
+exports.isBridgeErrorCode = isBridgeErrorCode;
+exports.toBridgeError = toBridgeError;
+/**
+ * Error codes of the local tools — the same vocabulary the hosted gateway
+ * uses, so a remote tool error re-raised by a local tool keeps its code.
+ */
+exports.BRIDGE_ERROR_CODES = [
+    'INVALID_INPUT',
+    'NOT_FOUND',
+    'PERMISSION_DENIED',
+    'UNAUTHENTICATED',
+    'QUOTA_EXCEEDED',
+    'CONFLICT',
+    'RATE_LIMITED',
+    'CONFIRMATION_REQUIRED',
+    'CANCELLED',
+    'PRECONDITION_FAILED',
+    'UPSTREAM_UNAVAILABLE',
+    'FEATURE_DISABLED',
+    'INTERNAL',
+];
+class BridgeError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'BridgeError';
+    }
+}
+exports.BridgeError = BridgeError;
+function isBridgeErrorCode(code) {
+    return typeof code === 'string' && exports.BRIDGE_ERROR_CODES.includes(code);
+}
+function toBridgeError(e) {
+    if (e instanceof BridgeError)
+        return e;
+    const err = e;
+    if (err?.name === 'AbortError')
+        return new BridgeError('CANCELLED', 'The call was cancelled.');
+    if (err?.code === 'ENOENT')
+        return new BridgeError('NOT_FOUND', 'No such file or folder.');
+    if (err?.code === 'EACCES' || err?.code === 'EPERM')
+        return new BridgeError('PRECONDITION_FAILED', 'The file cannot be read (permission denied).');
+    return new BridgeError('INTERNAL', e instanceof Error ? e.message : String(e));
+}

package/dist/files.d.ts

@@ -0,0 +1,65 @@
+export type FileKind = 'image' | 'video' | 'audio' | 'font' | 'text' | 'other';
+export declare function mimeOf(filename: string): string;
+/** Asset kind as the gateway understands it (image/video/audio/font), plus text and other. */
+export declare function kindOfMime(mime: string): FileKind;
+/**
+ * Compile a file-name glob: `*` (any run), `?` (one char), `{a,b}` (alternatives),
+ * matched case-insensitively against the file name. Several patterns may be
+ * given separated by `;`.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchesGlob(name: string, glob: string | undefined): boolean;
+export interface ImageDimensions {
+    width: number;
+    height: number;
+    /** EXIF orientation when present (1–8). */
+    orientation?: number;
+}
+/**
+ * Display dimensions of an image file. EXIF orientations 5–8 rotate the image
+ * by 90°, so width and height are swapped to match what viewers show.
+ * Returns undefined for files image-size cannot read (and for SVGs without size).
+ */
+export declare function imageDimensions(filePath: string): Promise<ImageDimensions | undefined>;
+/** Natural sort (panel-2 before panel-10), case-insensitive. */
+export declare function naturalCompare(a: string, b: string): number;
+export declare function looksBinary(buf: Uint8Array): boolean;
+/**
+ * Decode UTF-8 text, dropping a BOM and — when the buffer was cut — a partial
+ * multi-byte sequence at the end.
+ */
+export declare function decodeUtf8(buf: Uint8Array, cut: boolean): string;
+export declare function readHead(filePath: string, maxBytes: number): Promise<{
+    buf: Buffer;
+    sizeBytes: number;
+}>;
+export declare const MAX_DEPTH = 12;
+export declare const SKIP_DIRS: Set<string>;
+export interface ScanOptions {
+    /** File-name glob (see globToRegExp). */
+    glob?: string;
+    /** Extra filter applied after the glob (e.g. "media files only"). */
+    accept?: (name: string) => boolean;
+    recursive?: boolean;
+    includeHidden?: boolean;
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface ScannedFile {
+    abs: string;
+    /** Relative to the scanned folder, forward slashes. */
+    rel: string;
+    size: number;
+    mtime: Date;
+}
+/**
+ * Walk a folder inside the sandbox: natural order, subfolders after the files
+ * of a folder, symlinks followed only when their target is allowed too,
+ * node_modules/.git and (unless asked) dot entries skipped.
+ */
+export declare function scanFolder(folder: string, allowedDirs: string[], opts: ScanOptions): Promise<{
+    root: string;
+    found: ScannedFile[];
+    skipped: string[];
+    truncated: boolean;
+}>;