@panelwave/mcp 0.0.0-stage → 0.1.0

package/dist/files.js

@@ -0,0 +1,316 @@
+"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.SKIP_DIRS = exports.MAX_DEPTH = void 0;
+exports.mimeOf = mimeOf;
+exports.kindOfMime = kindOfMime;
+exports.globToRegExp = globToRegExp;
+exports.matchesGlob = matchesGlob;
+exports.imageDimensions = imageDimensions;
+exports.naturalCompare = naturalCompare;
+exports.looksBinary = looksBinary;
+exports.decodeUtf8 = decodeUtf8;
+exports.readHead = readHead;
+exports.scanFolder = scanFolder;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const image_size_1 = require("image-size");
+const errors_1 = require("./errors");
+const sandbox_1 = require("./sandbox");
+const MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+    '.bmp': 'image/bmp',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+    '.mp4': 'video/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+    '.mkv': 'video/x-matroska',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.oga': 'audio/ogg',
+    '.m4a': 'audio/mp4',
+    '.aac': 'audio/aac',
+    '.flac': 'audio/flac',
+    '.opus': 'audio/opus',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.markdown': 'text/markdown',
+    '.fountain': 'text/x-fountain',
+    '.fdx': 'application/xml',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.tsv': 'text/tab-separated-values',
+    '.xml': 'application/xml',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.yaml': 'application/yaml',
+    '.yml': 'application/yaml',
+    '.srt': 'application/x-subrip',
+    '.vtt': 'text/vtt',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+};
+function mimeOf(filename) {
+    return MIME[path.extname(filename).toLowerCase()] ?? 'application/octet-stream';
+}
+/** Asset kind as the gateway understands it (image/video/audio/font), plus text and other. */
+function kindOfMime(mime) {
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (mime.startsWith('font/'))
+        return 'font';
+    if (mime.startsWith('text/') || ['application/json', 'application/xml', 'application/yaml', 'application/x-subrip'].includes(mime))
+        return 'text';
+    return 'other';
+}
+function escapeRe(s) {
+    return s.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+/**
+ * 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 `;`.
+ */
+function globToRegExp(glob) {
+    let re = '';
+    let depth = 0;
+    for (const ch of glob) {
+        if (ch === '*')
+            re += '[^/\\\\]*';
+        else if (ch === '?')
+            re += '[^/\\\\]';
+        else if (ch === '{') {
+            depth++;
+            re += '(?:';
+        }
+        else if (ch === '}' && depth > 0) {
+            depth--;
+            re += ')';
+        }
+        else if (ch === ',' && depth > 0)
+            re += '|';
+        else
+            re += escapeRe(ch);
+    }
+    if (depth > 0)
+        throw new errors_1.BridgeError('INVALID_INPUT', `Unbalanced "{" in glob ${glob}.`);
+    return new RegExp(`^${re}$`, 'i');
+}
+function matchesGlob(name, glob) {
+    if (!glob)
+        return true;
+    return glob
+        .split(';')
+        .map((g) => g.trim())
+        .filter(Boolean)
+        .some((g) => globToRegExp(g).test(name));
+}
+/**
+ * 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).
+ */
+async function imageDimensions(filePath) {
+    // Headers normally fit in 512 KB; JPEGs with a large EXIF/XMP block before
+    // the frame header get a second, bigger read.
+    for (const bytes of HEADER_READS) {
+        let head;
+        try {
+            head = await readHead(filePath, bytes);
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const r = (0, image_size_1.imageSize)(head.buf);
+            if (!r.width || !r.height)
+                return undefined;
+            const rotated = r.orientation !== undefined && r.orientation >= 5 && r.orientation <= 8;
+            return { width: rotated ? r.height : r.width, height: rotated ? r.width : r.height, ...(r.orientation ? { orientation: r.orientation } : {}) };
+        }
+        catch {
+            if (head.sizeBytes <= head.buf.length)
+                return undefined; // whole file read — not an image we understand
+        }
+    }
+    return undefined;
+}
+const HEADER_READS = [512 * 1024, 8 * 1024 * 1024];
+/** Natural sort (panel-2 before panel-10), case-insensitive. */
+function naturalCompare(a, b) {
+    return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+}
+function looksBinary(buf) {
+    const n = Math.min(buf.length, 8192);
+    for (let i = 0; i < n; i++)
+        if (buf[i] === 0)
+            return true;
+    return false;
+}
+/**
+ * Decode UTF-8 text, dropping a BOM and — when the buffer was cut — a partial
+ * multi-byte sequence at the end.
+ */
+function decodeUtf8(buf, cut) {
+    let end = buf.length;
+    if (cut) {
+        // Step back over continuation bytes to the lead byte of the last sequence.
+        let i = end - 1;
+        while (i >= 0 && i > end - 4 && (buf[i] & 0xc0) === 0x80)
+            i--;
+        if (i >= 0) {
+            const lead = buf[i];
+            const need = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+            if (end - i < need)
+                end = i;
+        }
+    }
+    let start = 0;
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf)
+        start = 3;
+    return new TextDecoder('utf-8').decode(buf.subarray(start, Math.max(start, end)));
+}
+async function readHead(filePath, maxBytes) {
+    const handle = await fs.open(filePath, 'r');
+    try {
+        const stat = await handle.stat();
+        const len = Math.min(stat.size, maxBytes);
+        const buf = Buffer.alloc(len);
+        let read = 0;
+        while (read < len) {
+            const { bytesRead } = await handle.read(buf, read, len - read, read);
+            if (!bytesRead)
+                break;
+            read += bytesRead;
+        }
+        return { buf: buf.subarray(0, read), sizeBytes: stat.size };
+    }
+    finally {
+        await handle.close();
+    }
+}
+exports.MAX_DEPTH = 12;
+exports.SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg', '__MACOSX', '$RECYCLE.BIN', 'System Volume Information']);
+/**
+ * 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.
+ */
+async function scanFolder(folder, allowedDirs, opts) {
+    const root = (0, sandbox_1.resolveAllowed)(folder, allowedDirs);
+    const stat = await fs.stat(root).catch((e) => {
+        throw (0, errors_1.toBridgeError)(e);
+    });
+    if (!stat.isDirectory())
+        throw new errors_1.BridgeError('INVALID_INPUT', `${folder} is a file, not a folder (pw_local_read_text reads a text file).`);
+    const found = [];
+    const skipped = [];
+    let truncated = false;
+    const walk = async (dir, rel, depth) => {
+        if (truncated)
+            return;
+        opts.signal?.throwIfAborted();
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            skipped.push(rel || '.');
+            return;
+        }
+        entries.sort((a, b) => naturalCompare(a.name, b.name));
+        const subdirs = [];
+        for (const entry of entries) {
+            if (!opts.includeHidden && entry.name.startsWith('.'))
+                continue;
+            const abs = path.join(dir, entry.name);
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            let isDir = entry.isDirectory();
+            let isFile = entry.isFile();
+            let target = abs;
+            if (entry.isSymbolicLink()) {
+                try {
+                    target = (0, sandbox_1.resolveAllowed)(abs, allowedDirs);
+                    const s = await fs.stat(target);
+                    isDir = s.isDirectory();
+                    isFile = s.isFile();
+                }
+                catch {
+                    skipped.push(relPath);
+                    continue;
+                }
+            }
+            if (isDir) {
+                if (opts.recursive && depth < exports.MAX_DEPTH && !exports.SKIP_DIRS.has(entry.name))
+                    subdirs.push({ abs: target, rel: relPath });
+                continue;
+            }
+            if (!isFile || !matchesGlob(entry.name, opts.glob) || (opts.accept && !opts.accept(entry.name)))
+                continue;
+            if (found.length >= opts.limit) {
+                truncated = true;
+                return;
+            }
+            try {
+                const s = await fs.stat(target);
+                found.push({ abs, rel: relPath, size: s.size, mtime: s.mtime });
+            }
+            catch {
+                skipped.push(relPath);
+            }
+        }
+        for (const sub of subdirs)
+            await walk(sub.abs, sub.rel, depth + 1);
+    };
+    await walk(root, '', 0);
+    return { root, found, skipped, truncated };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+export { startBridge, createBridgeServer, LOCAL_INSTRUCTIONS } from './bridge';
+export { loadConfig, ConfigError, DEFAULT_URL } from './config';
+export { RemoteProxy } from './remote';
+export { LOCAL_TOOLS } from './local-tools';
+export declare function main(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_TOOLS = exports.RemoteProxy = exports.DEFAULT_URL = exports.ConfigError = exports.loadConfig = exports.LOCAL_INSTRUCTIONS = exports.createBridgeServer = exports.startBridge = void 0;
+exports.main = main;
+/**
+ * panelwave-mcp — local stdio bridge to the hosted PanelWave MCP server.
+ *
+ *   npx -y @panelwave/mcp
+ *
+ * Environment:
+ *   PANELWAVE_TOKEN         personal access token (required)
+ *   PANELWAVE_MCP_URL       hosted endpoint (default https://mcp.panelwave.org/mcp)
+ *   PANELWAVE_ALLOWED_DIRS  folders the local file tools may read, separated by
+ *                           ";" on Windows and ":" elsewhere (default: the working directory)
+ *
+ * stdout carries the MCP protocol; all diagnostics go to stderr.
+ */
+const stdio_1 = require("@modelcontextprotocol/server/stdio");
+const bridge_1 = require("./bridge");
+const config_1 = require("./config");
+var bridge_2 = require("./bridge");
+Object.defineProperty(exports, "startBridge", { enumerable: true, get: function () { return bridge_2.startBridge; } });
+Object.defineProperty(exports, "createBridgeServer", { enumerable: true, get: function () { return bridge_2.createBridgeServer; } });
+Object.defineProperty(exports, "LOCAL_INSTRUCTIONS", { enumerable: true, get: function () { return bridge_2.LOCAL_INSTRUCTIONS; } });
+var config_2 = require("./config");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_2.loadConfig; } });
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_2.ConfigError; } });
+Object.defineProperty(exports, "DEFAULT_URL", { enumerable: true, get: function () { return config_2.DEFAULT_URL; } });
+var remote_1 = require("./remote");
+Object.defineProperty(exports, "RemoteProxy", { enumerable: true, get: function () { return remote_1.RemoteProxy; } });
+var local_tools_1 = require("./local-tools");
+Object.defineProperty(exports, "LOCAL_TOOLS", { enumerable: true, get: function () { return local_tools_1.LOCAL_TOOLS; } });
+const HELP = `panelwave-mcp ${config_1.version} — PanelWave MCP bridge (stdio)
+
+Add it to your MCP client, e.g. Claude Code:
+  claude mcp add panelwave --env PANELWAVE_TOKEN=pw_pat_… -- npx -y @panelwave/mcp
+
+Environment:
+  PANELWAVE_TOKEN         personal access token (required)
+  PANELWAVE_MCP_URL       hosted endpoint (default ${config_1.DEFAULT_URL})
+  PANELWAVE_ALLOWED_DIRS  folders the local file tools may read (default: working directory)
+`;
+function log(message) {
+    process.stderr.write(`[panelwave-mcp] ${message}\n`);
+}
+async function main(argv = process.argv.slice(2)) {
+    if (argv.includes('--version') || argv.includes('-v')) {
+        process.stdout.write(`${config_1.version}\n`);
+        return;
+    }
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const config = (0, config_1.loadConfig)();
+    log(config.allowedDirs.length
+        ? `v${config_1.version} → ${config.url}; local folders: ${config.allowedDirs.join(', ')}`
+        : `v${config_1.version} → ${config.url}; local file tools are OFF — set PANELWAVE_ALLOWED_DIRS to the folder with your scripts and artwork to use them`);
+    const bridge = await (0, bridge_1.startBridge)(config, { log });
+    let closing = false;
+    const shutdown = async (code = 0) => {
+        if (closing)
+            return;
+        closing = true;
+        await bridge.close().catch(() => undefined);
+        process.exit(code);
+    };
+    bridge.server.onclose = () => void shutdown(0);
+    process.on('SIGINT', () => void shutdown(0));
+    process.on('SIGTERM', () => void shutdown(0));
+    process.stdin.on('end', () => void shutdown(0));
+    await bridge.server.connect(new stdio_1.StdioServerTransport());
+}
+if (require.main === module) {
+    main().catch((e) => {
+        log(e instanceof config_1.ConfigError ? e.message : `failed to start: ${e instanceof Error ? e.stack ?? e.message : String(e)}`);
+        process.exit(1);
+    });
+}

package/dist/local-tools.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { type LocalTool } from './tool';
+export type { LocalTool, LocalToolContext, LocalToolResult } from './tool';
+export { errorResult } from './tool';
+export declare const LIST_LIMIT_DEFAULT = 1000;
+export declare const LIST_LIMIT_MAX = 5000;
+declare const zLocalFile: z.ZodObject<{
+    path: z.ZodString;
+    relativePath: z.ZodString;
+    name: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    mime: z.ZodString;
+    kind: z.ZodEnum<{
+        image: "image";
+        video: "video";
+        audio: "audio";
+        font: "font";
+        text: "text";
+        other: "other";
+    }>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    orientation: z.ZodOptional<z.ZodNumber>;
+    modifiedAt: z.ZodString;
+}, z.core.$strip>;
+export type LocalFile = z.infer<typeof zLocalFile>;
+export declare const listFiles: LocalTool;
+export declare const READ_DEFAULT_BYTES: number;
+export declare const READ_MAX_BYTES: number;
+export declare const readText: LocalTool;
+export declare const LOCAL_TOOLS: LocalTool[];

package/dist/local-tools.js

@@ -0,0 +1,176 @@
+"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.LOCAL_TOOLS = exports.readText = exports.READ_MAX_BYTES = exports.READ_DEFAULT_BYTES = exports.listFiles = exports.LIST_LIMIT_MAX = exports.LIST_LIMIT_DEFAULT = exports.errorResult = void 0;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const files_1 = require("./files");
+const sandbox_1 = require("./sandbox");
+const tool_1 = require("./tool");
+const upload_1 = require("./upload");
+var tool_2 = require("./tool");
+Object.defineProperty(exports, "errorResult", { enumerable: true, get: function () { return tool_2.errorResult; } });
+// ---------------------------------------------------------------------------
+// pw_local_list_files
+// ---------------------------------------------------------------------------
+exports.LIST_LIMIT_DEFAULT = 1000;
+exports.LIST_LIMIT_MAX = 5000;
+const zFileKind = zod_1.z.enum(['image', 'video', 'audio', 'font', 'text', 'other']);
+const zLocalFile = zod_1.z.object({
+    path: zod_1.z.string().describe('Absolute path — pass it to pw_local_read_text or pw_local_upload_files.'),
+    relativePath: zod_1.z.string().describe('Path relative to the listed folder, with forward slashes.'),
+    name: zod_1.z.string(),
+    sizeBytes: zod_1.z.number().int(),
+    mime: zod_1.z.string(),
+    kind: zFileKind,
+    width: zod_1.z.number().int().optional().describe('Display width in px (EXIF orientation applied).'),
+    height: zod_1.z.number().int().optional(),
+    orientation: zod_1.z.number().int().optional().describe('EXIF orientation (1–8) when present.'),
+    modifiedAt: zod_1.z.string(),
+});
+const listFilesInput = zod_1.z.object({
+    folder: zod_1.z.string().min(1).describe('Folder to list — absolute, or relative to the first allowed folder.'),
+    glob: zod_1.z.string().max(500).optional().describe('File-name filter: * ? and {a,b}, several patterns separated by ";" — e.g. "*.{png,jpg,webp}". Case-insensitive.'),
+    recursive: zod_1.z.boolean().default(false).describe('Include subfolders (node_modules/.git are always skipped).'),
+    includeHidden: zod_1.z.boolean().default(false).describe('Include dot files and dot folders.'),
+    dimensions: zod_1.z.boolean().default(true).describe('Read pixel dimensions of images (reads only the file header).'),
+    limit: zod_1.z.number().int().min(1).max(exports.LIST_LIMIT_MAX).default(exports.LIST_LIMIT_DEFAULT),
+});
+const listFilesOutput = zod_1.z.object({
+    folder: zod_1.z.string(),
+    files: zod_1.z.array(zLocalFile),
+    count: zod_1.z.number().int(),
+    truncated: zod_1.z.boolean().describe('True when more files matched than `limit`.'),
+    totalSizeBytes: zod_1.z.number().int(),
+    byKind: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int()),
+    skipped: zod_1.z.array(zod_1.z.string()).describe('Entries that could not be read or point outside the allowed folders.'),
+});
+exports.listFiles = (0, tool_1.defineLocalTool)({
+    name: 'pw_local_list_files',
+    title: 'List local files',
+    description: 'List files in a folder on this computer (only inside the folders the PanelWave bridge was allowed to read). Returns absolute paths, size, mime type, kind (image/video/audio/font/text/other) and — for images — pixel dimensions with EXIF orientation applied. Files are sorted naturally (panel-2 before panel-10). Use it to find panel artwork before pw_local_upload_files, or a script before pw_local_read_text.',
+    input: listFilesInput,
+    output: listFilesOutput,
+    async run(args, ctx) {
+        const { root, found, skipped, truncated } = await (0, files_1.scanFolder)(args.folder, ctx.allowedDirs, {
+            glob: args.glob,
+            recursive: args.recursive,
+            includeHidden: args.includeHidden,
+            limit: args.limit,
+            signal: ctx.signal,
+        });
+        const files = await (0, tool_1.mapLimit)(found, 8, async (f) => {
+            const name = path.basename(f.abs);
+            const mime = (0, files_1.mimeOf)(name);
+            const kind = (0, files_1.kindOfMime)(mime);
+            const row = { path: f.abs, relativePath: f.rel, name, sizeBytes: f.size, mime, kind, modifiedAt: f.mtime.toISOString() };
+            if (args.dimensions && kind === 'image') {
+                const dim = await (0, files_1.imageDimensions)(f.abs);
+                if (dim)
+                    Object.assign(row, dim);
+            }
+            return row;
+        });
+        const byKind = {};
+        let totalSizeBytes = 0;
+        for (const f of files) {
+            byKind[f.kind] = (byKind[f.kind] ?? 0) + 1;
+            totalSizeBytes += f.sizeBytes;
+        }
+        const kinds = Object.entries(byKind)
+            .map(([k, n]) => `${n} ${k}`)
+            .join(', ');
+        const lines = files.slice(0, 200).map((f) => `- ${f.relativePath} (${(0, tool_1.formatBytes)(f.sizeBytes)}${f.width ? `, ${f.width}×${f.height}` : ''})`);
+        const text = [
+            files.length ? `${files.length} file${files.length === 1 ? '' : 's'} in ${root} (${kinds}; ${(0, tool_1.formatBytes)(totalSizeBytes)})${truncated ? ` — truncated at ${args.limit}, narrow the glob or raise limit` : ''}:` : `No matching files in ${root}.`,
+            ...lines,
+            ...(files.length > lines.length ? [`… and ${files.length - lines.length} more (see structured result).`] : []),
+            ...(skipped.length ? [`Skipped ${skipped.length} unreadable or out-of-sandbox entr${skipped.length === 1 ? 'y' : 'ies'}.`] : []),
+        ].join('\n');
+        return { text, data: { folder: root, files, count: files.length, truncated, totalSizeBytes, byKind, skipped } };
+    },
+});
+// ---------------------------------------------------------------------------
+// pw_local_read_text
+// ---------------------------------------------------------------------------
+exports.READ_DEFAULT_BYTES = 1024 * 1024;
+exports.READ_MAX_BYTES = 5 * 1024 * 1024;
+const readTextInput = zod_1.z.object({
+    path: zod_1.z.string().min(1).describe('File to read — absolute, or relative to the first allowed folder.'),
+    maxBytes: zod_1.z.number().int().min(1).max(exports.READ_MAX_BYTES).default(exports.READ_DEFAULT_BYTES).describe('Read at most this many bytes (default 1 MiB, max 5 MiB).'),
+});
+const readTextOutput = zod_1.z.object({
+    path: zod_1.z.string(),
+    name: zod_1.z.string(),
+    mime: zod_1.z.string(),
+    text: zod_1.z.string(),
+    sizeBytes: zod_1.z.number().int(),
+    returnedBytes: zod_1.z.number().int(),
+    truncated: zod_1.z.boolean(),
+});
+exports.readText = (0, tool_1.defineLocalTool)({
+    name: 'pw_local_read_text',
+    title: 'Read a local text file',
+    description: 'Read a UTF-8 text file on this computer — a script, screenplay (.fountain), outline (.md/.json) or subtitle file — from the folders the PanelWave bridge may read. Long files are cut at maxBytes (default 1 MiB) and flagged `truncated`. Binary files are refused.',
+    input: readTextInput,
+    output: readTextOutput,
+    async run(args, ctx) {
+        // No dotfiles or dot-folders (.ssh, .env, .git …): scripts never live there, secrets often do.
+        const file = (0, sandbox_1.resolveAllowed)(args.path, ctx.allowedDirs, { allowHidden: false });
+        const stat = await fs.stat(file).catch((e) => {
+            throw (0, errors_1.toBridgeError)(e);
+        });
+        if (stat.isDirectory())
+            throw new errors_1.BridgeError('INVALID_INPUT', `${args.path} is a folder. Use pw_local_list_files to list it.`);
+        const { buf, sizeBytes } = await (0, files_1.readHead)(file, args.maxBytes).catch((e) => {
+            throw (0, errors_1.toBridgeError)(e);
+        });
+        if ((0, files_1.looksBinary)(buf))
+            throw new errors_1.BridgeError('PRECONDITION_FAILED', `${path.basename(file)} is a binary file (${(0, files_1.mimeOf)(file)}), not text. Upload media with pw_local_upload_files instead.`);
+        const truncated = sizeBytes > buf.length;
+        const text = (0, files_1.decodeUtf8)(buf, truncated);
+        const name = path.basename(file);
+        const header = truncated
+            ? `${name}: first ${(0, tool_1.formatBytes)(buf.length)} of ${(0, tool_1.formatBytes)(sizeBytes)} (truncated — raise maxBytes up to 5 MiB to read more).`
+            : `${name} (${(0, tool_1.formatBytes)(sizeBytes)}):`;
+        return {
+            text: `${header}\n\n${text}`,
+            data: { path: file, name, mime: (0, files_1.mimeOf)(name), text, sizeBytes, returnedBytes: Buffer.byteLength(text, 'utf8'), truncated },
+        };
+    },
+});
+exports.LOCAL_TOOLS = [exports.listFiles, exports.readText, upload_1.uploadFiles];