vlc-files 0.0.1

package/dist/index.cjs

@@ -0,0 +1,198 @@
+"use strict";
+const { join, sep, relative } = require("path");
+const { readdir, stat } = require("fs/promises");
+const { spawn } = require("child_process");
+
+// ─── Path utilities ───────────────────────────────────────────────────────────
+
+function sanitize(input, root) {
+  const normalized = input.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (normalized === "" || normalized === ".") return root;
+  const sanitized = normalized.replace(/\.\./g, "").replace(/^\//, "");
+  return join(root, sanitized).replace(/\\/g, "/");
+}
+
+// ─── VLC arg whitelist ────────────────────────────────────────────────────────
+
+const ALLOWED_VLC_ARGS = new Set([
+  "--play-and-pause",
+  "--play",
+  "--pause",
+  "--stop",
+  "--rate",
+  "--aspect-ratio",
+  "--audio",
+  "--volume",
+  "--zoom",
+  "--fullscreen",
+  "--no-fullscreen",
+  "--video-on-top",
+  "--video-wallpaper",
+  "--snapshot-path",
+  "--video-snapshot",
+]);
+
+function buildCvlcArgs(raw) {
+  const filtered = (raw || "--play-and-pause").split(/\s+/).filter(Boolean).filter((a) => ALLOWED_VLC_ARGS.has(a));
+  return filtered.length > 0 ? filtered : ["--play-and-pause"];
+}
+
+// ─── Media kind detection ─────────────────────────────────────────────────────
+
+function mediaKind(name) {
+  const ext = (name.split(".").pop() || "").toLowerCase();
+  if (["mp4", "mkv", "avi", "mov", "wmv", "flv", "webm", "m4v", "mpg", "mpeg"].includes(ext))
+    return "video";
+  if (["mp3", "flac", "wav", "aac", "ogg", "m4a", "wma", "ape"].includes(ext)) return "audio";
+  if (["srt", "ssa", "ass", "vtt", "sub"].includes(ext)) return "subtitle";
+  return "other";
+}
+
+// ─── Plugin entry ─────────────────────────────────────────────────────────────
+
+module.exports = {
+  id: "vlc-files",
+  name: "vlc-files",
+  description: "Media library browsing and VLC playback",
+  configSchema: {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+      mediaRoot: { type: "string", default: "/media/raven/M&Serials" },
+      vlcArgs: { type: "string", default: "--play-and-pause" },
+    },
+  },
+  register(api) {
+    // ── media_list ────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => {
+        const pluginConfig = (ctx.config && ctx.config.plugins && ctx.config.plugins.entries && ctx.config.plugins.entries["vlc-files"] && ctx.config.plugins.entries["vlc-files"].config) || {};
+        const root = pluginConfig.mediaRoot;
+        if (!root) {
+          return {
+            name: "media_list",
+            label: "media_list",
+            description: "List files in the media library",
+            parameters: {
+              type: "object",
+              properties: {
+                path: { type: "string", description: "Relative subdirectory under mediaRoot (default: root)", default: "" },
+                includeKind: { type: "boolean", description: "Include media kind (video/audio/subtitle) and mtime for files", default: false },
+              },
+            },
+            execute(id, params) {
+              return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true, details: undefined };
+            },
+          };
+        }
+        return {
+          name: "media_list",
+          label: "media_list",
+          description: "List files in the media library",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Relative subdirectory under mediaRoot (default: root)", default: "" },
+              includeKind: { type: "boolean", description: "Include media kind (video/audio/subtitle) and mtime for files", default: false },
+            },
+          },
+          async execute(id, { path: target, includeKind }) {
+            const safePath = sanitize(target || "", root);
+            if (!safePath.startsWith(root)) {
+              return { content: [{ type: "text", text: "Path escapes media root" }], isError: true, details: undefined };
+            }
+            try {
+              const dirents = await readdir(safePath, { withFileTypes: true });
+              const entries = dirents.map((e) => {
+                const name = String(e.name);
+                const type = e.isDirectory() ? "dir" : "file";
+                const fullPath = join(safePath, name);
+                const rel = sep === "/" ? relative(root, fullPath) : relative(root, fullPath).replace(/\\/g, "/");
+                return { name, type, path: rel };
+              });
+              if (includeKind) {
+                for (const e of entries.filter((e) => e.type === "file")) {
+                  try {
+                    const s = await stat(join(safePath, e.name));
+                    e.kind = mediaKind(e.name);
+                    e.size = s.size;
+                    e.modified = s.mtime.toISOString();
+                  } catch (_) {
+                    e.kind = "other";
+                  }
+                }
+              }
+              entries.sort((a, b) => a.type !== b.type ? (a.type === "dir" ? -1 : 1) : a.name.localeCompare(b.name));
+              return { content: [{ type: "text", text: JSON.stringify({ ok: true, entries, path: target || "." }) }], details: undefined };
+            } catch (err) {
+              return { content: [{ type: "text", text: String(err.message || err) }], isError: true, details: undefined };
+            }
+          },
+        };
+      },
+      { names: ["media_list"] }
+    );
+
+    // ── vlc_play ──────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => {
+        const pluginConfig = (ctx.config && ctx.config.plugins && ctx.config.plugins.entries && ctx.config.plugins.entries["vlc-files"] && ctx.config.plugins.entries["vlc-files"].config) || {};
+        const root = pluginConfig.mediaRoot;
+        if (!root) {
+          return {
+            name: "vlc_play",
+            label: "vlc_play",
+            description: "Play a media file with VLC on the host",
+            parameters: {
+              type: "object",
+              properties: { file: { type: "string", description: "Relative media file path (relative to mediaRoot)" } },
+              required: ["file"],
+            },
+            execute(id, params) {
+              return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true, details: undefined };
+            },
+          };
+        }
+        return {
+          name: "vlc_play",
+          label: "vlc_play",
+          description: "Play a media file with VLC on the host",
+          parameters: {
+            type: "object",
+            properties: { file: { type: "string", description: "Relative media file path (relative to mediaRoot)" } },
+            required: ["file"],
+          },
+          async execute(id, { file }) {
+            const safePath = sanitize(file, root);
+            if (!safePath.startsWith(root)) {
+              return { content: [{ type: "text", text: "Path escapes media root" }], isError: true, details: undefined };
+            }
+            try {
+              const st = await stat(safePath);
+              if (!st.isFile()) {
+                return { content: [{ type: "text", text: "Not a file" }], isError: true, details: undefined };
+              }
+            } catch (_) {
+              return { content: [{ type: "text", text: "File not found" }], isError: true, details: undefined };
+            }
+            const cvlcArgs = buildCvlcArgs(pluginConfig.vlcArgs);
+            const kind = mediaKind(file);
+            const child = spawn("cvlc", [...cvlcArgs, safePath], { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+            const stderrLines = [];
+            child.stderr && child.stderr.on("data", (chunk) => { if (stderrLines.length < 8) stderrLines.push(chunk.toString().trim()); });
+            child.unref();
+            const exitCode = await Promise.race([
+              new Promise((resolve) => child.on("exit", (code) => resolve(code || 0))),
+              new Promise((resolve) => setTimeout(() => resolve(null), 1500)),
+            ]);
+            if (exitCode !== null && exitCode !== 0) {
+              return { content: [{ type: "text", text: `cvlc exited ${exitCode}: ${stderrLines.join("\n")}` }], isError: true, details: undefined };
+            }
+            return { content: [{ type: "text", text: `Playing: ${relative(root, safePath)}` }], details: undefined };
+          },
+        };
+      },
+      { names: ["vlc_play"] }
+    );
+  },
+};

package/dist/index.js

@@ -0,0 +1,198 @@
+"use strict";
+const { join, sep, relative } = require("path");
+const { readdir, stat } = require("fs/promises");
+const { spawn } = require("child_process");
+
+// ─── Path utilities ───────────────────────────────────────────────────────────
+
+function sanitize(input, root) {
+  const normalized = input.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (normalized === "" || normalized === ".") return root;
+  const sanitized = normalized.replace(/\.\./g, "").replace(/^\//, "");
+  return join(root, sanitized).replace(/\\/g, "/");
+}
+
+// ─── VLC arg whitelist ────────────────────────────────────────────────────────
+
+const ALLOWED_VLC_ARGS = new Set([
+  "--play-and-pause",
+  "--play",
+  "--pause",
+  "--stop",
+  "--rate",
+  "--aspect-ratio",
+  "--audio",
+  "--volume",
+  "--zoom",
+  "--fullscreen",
+  "--no-fullscreen",
+  "--video-on-top",
+  "--video-wallpaper",
+  "--snapshot-path",
+  "--video-snapshot",
+]);
+
+function buildCvlcArgs(raw) {
+  const filtered = (raw || "--play-and-pause").split(/\s+/).filter(Boolean).filter((a) => ALLOWED_VLC_ARGS.has(a));
+  return filtered.length > 0 ? filtered : ["--play-and-pause"];
+}
+
+// ─── Media kind detection ─────────────────────────────────────────────────────
+
+function mediaKind(name) {
+  const ext = (name.split(".").pop() || "").toLowerCase();
+  if (["mp4", "mkv", "avi", "mov", "wmv", "flv", "webm", "m4v", "mpg", "mpeg"].includes(ext))
+    return "video";
+  if (["mp3", "flac", "wav", "aac", "ogg", "m4a", "wma", "ape"].includes(ext)) return "audio";
+  if (["srt", "ssa", "ass", "vtt", "sub"].includes(ext)) return "subtitle";
+  return "other";
+}
+
+// ─── Plugin entry ─────────────────────────────────────────────────────────────
+
+module.exports = {
+  id: "vlc-files",
+  name: "vlc-files",
+  description: "Media library browsing and VLC playback",
+  configSchema: {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+      mediaRoot: { type: "string", default: "/media/raven/M&Serials" },
+      vlcArgs: { type: "string", default: "--play-and-pause" },
+    },
+  },
+  register(api) {
+    // ── media_list ────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => {
+        const pluginConfig = (ctx.config && ctx.config.plugins && ctx.config.plugins.entries && ctx.config.plugins.entries["vlc-files"] && ctx.config.plugins.entries["vlc-files"].config) || {};
+        const root = pluginConfig.mediaRoot;
+        if (!root) {
+          return {
+            name: "media_list",
+            label: "media_list",
+            description: "List files in the media library",
+            parameters: {
+              type: "object",
+              properties: {
+                path: { type: "string", description: "Relative subdirectory under mediaRoot (default: root)", default: "" },
+                includeKind: { type: "boolean", description: "Include media kind (video/audio/subtitle) and mtime for files", default: false },
+              },
+            },
+            execute(id, params) {
+              return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true, details: undefined };
+            },
+          };
+        }
+        return {
+          name: "media_list",
+          label: "media_list",
+          description: "List files in the media library",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Relative subdirectory under mediaRoot (default: root)", default: "" },
+              includeKind: { type: "boolean", description: "Include media kind (video/audio/subtitle) and mtime for files", default: false },
+            },
+          },
+          async execute(id, { path: target, includeKind }) {
+            const safePath = sanitize(target || "", root);
+            if (!safePath.startsWith(root)) {
+              return { content: [{ type: "text", text: "Path escapes media root" }], isError: true, details: undefined };
+            }
+            try {
+              const dirents = await readdir(safePath, { withFileTypes: true });
+              const entries = dirents.map((e) => {
+                const name = String(e.name);
+                const type = e.isDirectory() ? "dir" : "file";
+                const fullPath = join(safePath, name);
+                const rel = sep === "/" ? relative(root, fullPath) : relative(root, fullPath).replace(/\\/g, "/");
+                return { name, type, path: rel };
+              });
+              if (includeKind) {
+                for (const e of entries.filter((e) => e.type === "file")) {
+                  try {
+                    const s = await stat(join(safePath, e.name));
+                    e.kind = mediaKind(e.name);
+                    e.size = s.size;
+                    e.modified = s.mtime.toISOString();
+                  } catch (_) {
+                    e.kind = "other";
+                  }
+                }
+              }
+              entries.sort((a, b) => a.type !== b.type ? (a.type === "dir" ? -1 : 1) : a.name.localeCompare(b.name));
+              return { content: [{ type: "text", text: JSON.stringify({ ok: true, entries, path: target || "." }) }], details: undefined };
+            } catch (err) {
+              return { content: [{ type: "text", text: String(err.message || err) }], isError: true, details: undefined };
+            }
+          },
+        };
+      },
+      { names: ["media_list"] }
+    );
+
+    // ── vlc_play ──────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => {
+        const pluginConfig = (ctx.config && ctx.config.plugins && ctx.config.plugins.entries && ctx.config.plugins.entries["vlc-files"] && ctx.config.plugins.entries["vlc-files"].config) || {};
+        const root = pluginConfig.mediaRoot;
+        if (!root) {
+          return {
+            name: "vlc_play",
+            label: "vlc_play",
+            description: "Play a media file with VLC on the host",
+            parameters: {
+              type: "object",
+              properties: { file: { type: "string", description: "Relative media file path (relative to mediaRoot)" } },
+              required: ["file"],
+            },
+            execute(id, params) {
+              return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true, details: undefined };
+            },
+          };
+        }
+        return {
+          name: "vlc_play",
+          label: "vlc_play",
+          description: "Play a media file with VLC on the host",
+          parameters: {
+            type: "object",
+            properties: { file: { type: "string", description: "Relative media file path (relative to mediaRoot)" } },
+            required: ["file"],
+          },
+          async execute(id, { file }) {
+            const safePath = sanitize(file, root);
+            if (!safePath.startsWith(root)) {
+              return { content: [{ type: "text", text: "Path escapes media root" }], isError: true, details: undefined };
+            }
+            try {
+              const st = await stat(safePath);
+              if (!st.isFile()) {
+                return { content: [{ type: "text", text: "Not a file" }], isError: true, details: undefined };
+              }
+            } catch (_) {
+              return { content: [{ type: "text", text: "File not found" }], isError: true, details: undefined };
+            }
+            const cvlcArgs = buildCvlcArgs(pluginConfig.vlcArgs);
+            const kind = mediaKind(file);
+            const child = spawn("cvlc", [...cvlcArgs, safePath], { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+            const stderrLines = [];
+            child.stderr && child.stderr.on("data", (chunk) => { if (stderrLines.length < 8) stderrLines.push(chunk.toString().trim()); });
+            child.unref();
+            const exitCode = await Promise.race([
+              new Promise((resolve) => child.on("exit", (code) => resolve(code || 0))),
+              new Promise((resolve) => setTimeout(() => resolve(null), 1500)),
+            ]);
+            if (exitCode !== null && exitCode !== 0) {
+              return { content: [{ type: "text", text: `cvlc exited ${exitCode}: ${stderrLines.join("\n")}` }], isError: true, details: undefined };
+            }
+            return { content: [{ type: "text", text: `Playing: ${relative(root, safePath)}` }], details: undefined };
+          },
+        };
+      },
+      { names: ["vlc_play"] }
+    );
+  },
+};

package/dist/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+ "id": "vlc-files",
+ "name": "vlc-files",
+ "description": "Media library browsing and VLC playback",
+ "version": "0.0.1",
+ "contracts": {
+ "tools": ["media_list", "vlc_play"]
+ },
+ "skills": ["./skills/vlc"],
+ "configSchema": {
+ "type": "object",
+ "additionalProperties": true,
+ "properties": {
+ "mediaRoot": { "type": "string", "default": "/media/raven/M&Serials" },
+ "vlcArgs": { "type": "string", "default": "--play-and-pause" }
+ }
+ }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+ "name": "vlc-files",
+ "version": "0.0.1",
+ "description": "Media library browsing and VLC playback",
+ "type": "module",
+ "openclaw": {
+  "extensions": [
+   "./dist/index.js"
+  ]
+ },
+ "devDependencies": {
+  "@types/node": "^25.6.2",
+  "openclaw": "^2026.5.7",
+  "typescript": "^6.0.3"
+ }
+}

package/src/index.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const fs_1 = require("fs/promises");
+const child_process_1 = require("child_process");
+function sanitize(input, root) {
+    const normalized = input.replace(/\\/g, "/").replace(/\/+/g, "/");
+    if (normalized === "" || normalized === ".") return root;
+    const sanitized = normalized.replace(/\.\./g, "").replace(/^\//, "");
+    return (0, path_1.join)(root, sanitized).replace(/\\/g, "/");
+}
+const ALLOWED_VLC_ARGS = new Set([
+    "--play-and-pause", "--play", "--pause", "--stop", "--rate",
+    "--aspect-ratio", "--audio", "--volume", "--zoom", "--fullscreen",
+    "--no-fullscreen", "--video-on-top", "--video-wallpaper",
+    "--snapshot-path", "--video-snapshot",
+]);
+function buildCvlcArgs(raw) {
+    const filtered = raw.split(/\s+/).filter(Boolean).filter((a) => ALLOWED_VLC_ARGS.has(a));
+    return filtered.length > 0 ? filtered : ["--play-and-pause"];
+}
+function mediaKind(name) {
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    if (["mp4", "mkv", "avi", "mov", "wmv", "flv", "webm", "m4v", "mpg", "mpeg"].includes(ext))
+        return "video";
+    if (["mp3", "flac", "wav", "aac", "ogg", "m4a", "wma", "ape"].includes(ext)) return "audio";
+    if (["srt", "ssa", "ass", "vtt", "sub"].includes(ext)) return "subtitle";
+    return "other";
+}
+const plugin = {
+    id: "vlc-files",
+    config: {
+        mediaRoot: { type: "string", required: true },
+        vlcArgs: { type: "string", default: "--play-and-pause" },
+    },
+    register(api) {
+        // dir_list
+        api.registerTool({
+            name: "dir_list",
+            description: "List files in the media library",
+            input: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Relative subdirectory under mediaRoot", default: "" },
+                    includeKind: { type: "boolean", description: "Include media kind and mtime for files", default: false },
+                },
+            },
+            async execute(id, { path: target, includeKind }, ctx) {
+                const root = ctx.config.mediaRoot;
+                const safePath = sanitize(target ?? "", root);
+                let dirents;
+                try {
+                    dirents = await (0, fs_1.readdir)(safePath, { withFileTypes: true });
+                } catch (err) {
+                    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+                const entries = dirents.map((e) => {
+                    const name = e.name;
+                    const type = e.isDirectory() ? "dir" : "file";
+                    const rel = process.platform === "win32"
+                        ? (0, path_1.relative)(root, (0, path_1.join)(safePath, name)).replace(/\\/g, "/")
+                        : (0, path_1.relative)(root, (0, path_1.join)(safePath, name));
+                    return { name, type, path: rel };
+                });
+                if (includeKind) {
+                    const fileEntries = entries.filter((e) => e.type === "file");
+                    const stats = await Promise.all(fileEntries.map((e) =>
+                        (0, fs_1.stat)((0, path_1.join)(safePath, e.name))
+                            .then((s) => ({ e, size: s.size, modified: s.mtime.toISOString() }))
+                            .catch(() => ({ e, size: 0, modified: undefined }))
+                    ));
+                    for (const { e, size, modified } of stats) {
+                        e.kind = mediaKind(e.name);
+                        e.size = size;
+                        e.modified = modified;
+                    }
+                }
+                entries.sort((a, b) =>
+                    a.type !== b.type ? (a.type === "dir" ? -1 : 1) : a.name.localeCompare(b.name)
+                );
+                return { ok: true, entries, path: target || "." };
+            },
+        });
+        // vlc_play
+        api.registerTool({
+            name: "vlc_play",
+            description: "Play a media file with VLC on the host",
+            input: {
+                type: "object",
+                properties: {
+                    file: { type: "string", description: "Relative media file path (relative to mediaRoot)" },
+                },
+                required: ["file"],
+            },
+            async execute(id, { file }, ctx) {
+                const root = ctx.config.mediaRoot;
+                const safePath = sanitize(file, root);
+                if (!safePath.startsWith(root)) {
+                    return { ok: false, error: "Path escapes media root" };
+                }
+                try {
+                    const st = await (0, fs_1.stat)(safePath);
+                    if (!st.isFile()) return { ok: false, error: "Not a file" };
+                } catch {
+                    return { ok: false, error: "File not found" };
+                }
+                const cvlcArgs = buildCvlcArgs(ctx.config.vlcArgs ?? "--play-and-pause");
+                const kind = mediaKind(file);
+                const child = (0, child_process_1.spawn)("cvlc", [...cvlcArgs, safePath], {
+                    detached: true,
+                    stdio: ["ignore", "ignore", "pipe"],
+                });
+                const stderrLines = [];
+                child.stderr?.on("data", (chunk) => {
+                    if (stderrLines.length < 8) stderrLines.push(chunk.toString().trim());
+                });
+                child.unref();
+                const exitCode = await Promise.race([
+                    new Promise((resolve) => child.on("exit", (code) => resolve(code ?? null))),
+                    new Promise((resolve) => setTimeout(() => resolve(null), 1500)),
+                ]);
+                if (exitCode !== null && exitCode !== 0) {
+                    return {
+                        ok: false,
+                        error: `cvlc exited ${exitCode}`,
+                        detail: stderrLines.join("\n") || undefined,
+                        kind,
+                        playing: process.platform === "win32"
+                            ? (0, path_1.relative)(root, safePath).replace(/\\/g, "/")
+                            : (0, path_1.relative)(root, safePath),
+                    };
+                }
+                return {
+                    ok: true,
+                    playing: process.platform === "win32"
+                        ? (0, path_1.relative)(root, safePath).replace(/\\/g, "/")
+                        : (0, path_1.relative)(root, safePath),
+                    args: cvlcArgs,
+                    kind,
+                };
+            },
+        });
+    },
+};
+exports.default = plugin;
+module.exports = plugin;
+exports.default = plugin;

package/src/index.ts

@@ -0,0 +1,218 @@
+import { definePluginEntry, buildJsonPluginConfigSchema } from "openclaw/plugin-sdk/plugin-entry";
+import { join, sep, relative } from "path";
+import { readdir } from "fs/promises";
+import { stat } from "fs/promises";
+import { spawn } from "child_process";
+
+// ─── Path utilities ───────────────────────────────────────────────────────────
+
+function sanitize(input: string, root: string): string {
+  const normalized = input.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (normalized === "" || normalized === ".") return root;
+  const sanitized = normalized.replace(/\.\./g, "").replace(/^\//, "");
+  return join(root, sanitized).replace(/\\/g, "/");
+}
+
+// ─── VLC arg whitelist ────────────────────────────────────────────────────────
+
+const ALLOWED_VLC_ARGS = new Set([
+  "--play-and-pause",
+  "--play",
+  "--pause",
+  "--stop",
+  "--rate",
+  "--aspect-ratio",
+  "--audio",
+  "--volume",
+  "--zoom",
+  "--fullscreen",
+  "--no-fullscreen",
+  "--video-on-top",
+  "--video-wallpaper",
+  "--snapshot-path",
+  "--video-snapshot",
+]);
+
+function buildCvlcArgs(raw: string): string[] {
+  const filtered = raw.split(/\s+/).filter(Boolean).filter((a) => ALLOWED_VLC_ARGS.has(a));
+  return filtered.length > 0 ? filtered : ["--play-and-pause"];
+}
+
+// ─── Media kind detection ─────────────────────────────────────────────────────
+
+function mediaKind(name: string): "video" | "audio" | "subtitle" | "other" {
+  const ext = name.split(".").pop()?.toLowerCase() ?? "";
+  if (["mp4", "mkv", "avi", "mov", "wmv", "flv", "webm", "m4v", "mpg", "mpeg"].includes(ext))
+    return "video";
+  if (["mp3", "flac", "wav", "aac", "ogg", "m4a", "wma", "ape"].includes(ext)) return "audio";
+  if (["srt", "ssa", "ass", "vtt", "sub"].includes(ext)) return "subtitle";
+  return "other";
+}
+
+// ─── Plugin entry ─────────────────────────────────────────────────────────────
+
+interface DirEntry {
+  name: string;
+  type: "dir" | "file";
+  path: string;
+  kind?: "video" | "audio" | "subtitle" | "other";
+  size?: number;
+  modified?: string;
+}
+
+export default definePluginEntry({
+  id: "vlc-files",
+  name: "vlc-files",
+  description: "Media library browsing and VLC playback",
+  configSchema: buildJsonPluginConfigSchema({
+    type: "object",
+    properties: {
+      mediaRoot: { type: "string" },
+      vlcArgs: { type: "string", default: "--play-and-pause" },
+    },
+    required: ["mediaRoot"],
+  }),
+  register(api) {
+    // ── media_list ────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => ({
+        name: "media_list",
+        label: "media_list",
+        description: "List files in the media library",
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Relative subdirectory under mediaRoot (default: root)",
+              default: "",
+            },
+            includeKind: {
+              type: "boolean",
+              description: "Include media kind (video/audio/subtitle) and mtime for files",
+              default: false,
+            },
+          },
+        },
+        async execute(id, { path: target, includeKind }, signal) {
+          const pluginConfig = ctx.config?.plugins?.entries?.["vlc-files"]?.config as { mediaRoot?: string; vlcArgs?: string } | undefined;
+          const root = pluginConfig?.mediaRoot;
+          if (!root) return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true , details: undefined };
+
+          const safePath = sanitize(target ?? "", root);
+          if (!safePath.startsWith(root)) {
+            return { content: [{ type: "text", text: "Path escapes media root" }], isError: true , details: undefined };
+          }
+
+          let dirents: Awaited<ReturnType<typeof readdir>>;
+          try {
+            dirents = await readdir(safePath, { withFileTypes: true });
+          } catch (err: unknown) {
+            return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true , details: undefined };
+          }
+
+          const entries: DirEntry[] = dirents.map((e) => {
+            const name = String(e.name);
+            const type = e.isDirectory() ? "dir" : "file";
+            const fullPath = join(safePath, name);
+            const rel = sep === "/"
+              ? relative(root, fullPath)
+              : relative(root, fullPath).replace(/\\/g, "/");
+            return { name, type, path: rel };
+          });
+
+          if (includeKind) {
+            const fileEntries = entries.filter((e) => e.type === "file");
+            const stats = await Promise.all(
+              fileEntries.map((e) =>
+                stat(join(safePath, e.name))
+                  .then((s) => ({ e, size: s.size, modified: s.mtime.toISOString() }))
+                  .catch(() => ({ e, size: 0, modified: undefined }))
+              )
+            );
+            for (const { e, size, modified } of stats) {
+              e.kind = mediaKind(e.name);
+              e.size = size;
+              e.modified = modified;
+            }
+          }
+
+          entries.sort((a, b) =>
+            a.type !== b.type ? (a.type === "dir" ? -1 : 1) : a.name.localeCompare(b.name)
+          );
+
+          return { content: [{ type: "text", text: JSON.stringify({ ok: true, entries, path: target || "." }) }], details: undefined };
+        },
+      }),
+      { names: ["media_list"] }
+    );
+
+    // ── vlc_play ──────────────────────────────────────────────────────────────
+    api.registerTool(
+      (ctx) => ({
+        name: "vlc_play",
+        label: "vlc_play",
+        description: "Play a media file with VLC on the host",
+        parameters: {
+          type: "object",
+          properties: {
+            file: {
+              type: "string",
+              description: "Relative media file path (relative to mediaRoot)",
+            },
+          },
+          required: ["file"],
+        },
+        async execute(id, { file }, signal) {
+          const pluginConfig = ctx.config?.plugins?.entries?.["vlc-files"]?.config as { mediaRoot?: string; vlcArgs?: string } | undefined;
+          const root = pluginConfig?.mediaRoot;
+          if (!root) return { content: [{ type: "text", text: "mediaRoot not configured" }], isError: true , details: undefined };
+
+          const safePath = sanitize(file, root);
+          if (!safePath.startsWith(root)) {
+            return { content: [{ type: "text", text: "Path escapes media root" }], isError: true , details: undefined };
+          }
+
+          try {
+            const st = await stat(safePath);
+            if (!st.isFile()) return { content: [{ type: "text", text: "Not a file" }], isError: true , details: undefined };
+          } catch {
+            return { content: [{ type: "text", text: "File not found" }], isError: true , details: undefined };
+          }
+
+          const cvlcArgs = buildCvlcArgs(pluginConfig?.vlcArgs ?? "--play-and-pause");
+          const kind = mediaKind(file);
+
+          const child = spawn("cvlc", [...cvlcArgs, safePath], {
+            detached: true,
+            stdio: ["ignore", "ignore", "pipe"],
+          });
+
+          const stderrLines: string[] = [];
+          child.stderr?.on("data", (chunk: Buffer) => {
+            if (stderrLines.length < 8) stderrLines.push(chunk.toString().trim());
+          });
+
+          child.unref();
+
+          const exitCode: number | null = await Promise.race<number | null>([
+            new Promise<number>((resolve) =>
+              child.on("exit", (code) => resolve(code ?? 0))
+            ),
+            new Promise<null>((resolve) => setTimeout(() => resolve(null), 1500)),
+          ]);
+
+          if (exitCode !== null && exitCode !== 0) {
+            return {
+              content: [{ type: "text", text: `cvlc exited ${exitCode}: ${stderrLines.join("\n")}` }],
+              isError: true,
+            };
+          }
+
+          return { content: [{ type: "text", text: `Playing: ${relative(root, safePath)}` }], details: undefined };
+        },
+      }),
+      { names: ["vlc_play"] }
+    );
+  },
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "ignoreDeprecations": "6.0"
+  },
+  "include": ["src/**/*"]
+}