@zkov/pi-md-viewer 0.1.0

package/dist/src-ts/server.js

@@ -0,0 +1,326 @@
+import { randomBytes } from "node:crypto";
+import { createReadStream, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ClientLifecycle } from "./lifecycle.js";
+import { RenderError } from "./renderer.js";
+const APPLICATION = "pi-md-viewer";
+const PROTOCOL_VERSION = "1.0";
+const MAX_REQUEST_BYTES = 256 * 1024;
+const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = [path.resolve(runtimeDir, ".."), path.resolve(runtimeDir, "..", "..")]
+    .find((candidate) => {
+    try {
+        statSync(path.join(candidate, "src", "pi_md_viewer"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}) ?? path.resolve(runtimeDir, "..");
+const legacyAssetRoot = path.join(projectRoot, "src", "pi_md_viewer");
+export class ViewerServer {
+    registry;
+    renderer;
+    csrfToken = randomBytes(32).toString("base64url");
+    lifecycle = new ClientLifecycle(Date.now() / 1000);
+    server;
+    host;
+    requestedPort;
+    actualPort = 0;
+    monitorLifecycle;
+    monitor;
+    subscribers = new Set();
+    constructor(options) {
+        if (options.host !== "127.0.0.1")
+            throw new Error("ViewerServer only binds to 127.0.0.1");
+        this.host = options.host;
+        this.requestedPort = options.port;
+        this.registry = options.registry;
+        this.renderer = options.renderer;
+        this.monitorLifecycle = options.monitorLifecycle ?? true;
+        this.server = createServer((request, response) => {
+            void this.handle(request, response);
+        });
+    }
+    get port() {
+        return this.actualPort;
+    }
+    get url() {
+        return `http://127.0.0.1:${this.port}/`;
+    }
+    async start() {
+        await new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(this.requestedPort, this.host, () => {
+                this.server.off("error", reject);
+                const address = this.server.address();
+                if (typeof address === "object" && address)
+                    this.actualPort = address.port;
+                if (this.monitorLifecycle)
+                    this.startMonitor();
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.monitor) {
+            clearInterval(this.monitor);
+            this.monitor = undefined;
+        }
+        this.emit("server_closing");
+        for (const subscriber of this.subscribers) {
+            subscriber.end();
+        }
+        this.subscribers.clear();
+        await new Promise((resolve, reject) => {
+            if (!this.server.listening) {
+                resolve();
+                return;
+            }
+            this.server.close((error) => error ? reject(error) : resolve());
+        });
+        this.registry.clear();
+    }
+    async handle(request, response) {
+        if (!this.requestIsAllowed(request, response))
+            return;
+        const parsed = new URL(request.url ?? "/", this.url);
+        try {
+            if (request.method === "GET") {
+                await this.handleGet(parsed, request, response);
+            }
+            else if (request.method === "POST") {
+                await this.handlePost(parsed, request, response);
+            }
+            else if (request.method === "DELETE") {
+                await this.handleDelete(parsed, request, response);
+            }
+            else {
+                this.error(response, 405, "method_not_allowed", "Method not allowed");
+            }
+        }
+        catch (error) {
+            this.error(response, 500, "internal_error", error instanceof Error ? error.message : String(error));
+        }
+    }
+    requestIsAllowed(request, response) {
+        const remote = request.socket.remoteAddress;
+        if (remote && !["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(remote)) {
+            this.error(response, 403, "forbidden", "Only loopback clients are allowed");
+            return false;
+        }
+        const host = String(request.headers.host ?? "");
+        const hostname = host.replace(/^\[/, "").replace(/\].*$/, "").split(":")[0]?.toLowerCase() ?? "";
+        if (!["127.0.0.1", "localhost", "::1"].includes(hostname)) {
+            this.error(response, 400, "invalid_host", "Invalid Host header");
+            return false;
+        }
+        return true;
+    }
+    async handleGet(parsed, request, response) {
+        if (parsed.pathname === "/") {
+            const template = readFileSync(path.join(legacyAssetRoot, "templates", "viewer.html"), "utf8");
+            this.sendBytes(response, 200, Buffer.from(template.replace("{{CSRF_TOKEN}}", this.csrfToken)), "text/html; charset=utf-8");
+        }
+        else if (["/static/viewer.css", "/static/viewer.js", "/static/viewer-actions.js"].includes(parsed.pathname)) {
+            await this.serveAsset(parsed.pathname.replace("/static/", ""), response);
+        }
+        else if (parsed.pathname === "/api/v1/status") {
+            this.sendJson(response, 200, {
+                application: APPLICATION,
+                protocolVersion: PROTOCOL_VERSION,
+                pid: process.pid,
+                url: this.url,
+                viewerClients: this.lifecycle.clientCount,
+                files: this.registry.list().length,
+            });
+        }
+        else if (parsed.pathname === "/api/v1/files") {
+            this.sendJson(response, 200, { files: this.registry.list().map(recordJson) });
+        }
+        else if (parsed.pathname === "/api/v1/events") {
+            this.handleEvents(parsed, response);
+        }
+        else if (parsed.pathname.startsWith("/api/v1/files/")) {
+            const id = parsed.pathname.split("/").pop() ?? "";
+            const record = this.registry.get(id);
+            if (!record) {
+                this.error(response, 404, "not_found", "File is not registered");
+                return;
+            }
+            try {
+                const rendered = this.renderer.render(record.path);
+                this.sendJson(response, 200, { file: recordJson(record), html: rendered.html, toc: rendered.toc, revision: rendered.revision });
+            }
+            catch (error) {
+                if (error instanceof RenderError)
+                    this.error(response, 422, error.code, error.message);
+                else
+                    throw error;
+            }
+        }
+        else {
+            this.error(response, 404, "not_found", "Endpoint not found");
+        }
+    }
+    async handlePost(parsed, request, response) {
+        if (parsed.pathname === "/api/v1/files") {
+            if (request.headers.origin || request.headers["x-pi-md-viewer-cli"] !== "1") {
+                this.error(response, 403, "forbidden", "CLI authorization required");
+                return;
+            }
+            const payload = await this.readJson(request);
+            const paths = payload.paths;
+            if (!Array.isArray(paths) || !paths.every((item) => typeof item === "string")) {
+                this.error(response, 400, "invalid_request", "paths must be an array of strings");
+                return;
+            }
+            const result = this.registry.addMany(paths);
+            const accepted = [...result.added, ...result.existing];
+            if (accepted.length > 0)
+                this.emit("files_changed");
+            this.sendJson(response, accepted.length > 0 ? 200 : 400, {
+                ok: accepted.length > 0,
+                added: result.added.map(recordJson),
+                existing: result.existing.map(recordJson),
+                rejected: result.rejected,
+                viewerClients: this.lifecycle.clientCount,
+            });
+        }
+        else if (parsed.pathname === "/api/v1/clients/open") {
+            if (!this.validCsrf(request, parsed)) {
+                this.error(response, 403, "forbidden", "Invalid CSRF token");
+                return;
+            }
+            const payload = await this.readJson(request);
+            if (typeof payload.clientId !== "string" || !payload.clientId) {
+                this.error(response, 400, "invalid_request", "clientId is required");
+                return;
+            }
+            this.lifecycle.open(payload.clientId, Date.now() / 1000);
+            this.sendJson(response, 200, { ok: true, clientId: payload.clientId });
+        }
+        else if (parsed.pathname === "/api/v1/clients/close") {
+            if (!this.validCsrf(request, parsed)) {
+                this.error(response, 403, "forbidden", "Invalid CSRF token");
+                return;
+            }
+            const payload = await this.readJson(request);
+            if (typeof payload.clientId !== "string" || !payload.clientId) {
+                this.error(response, 400, "invalid_request", "clientId is required");
+                return;
+            }
+            this.lifecycle.close(payload.clientId, Date.now() / 1000);
+            this.sendJson(response, 200, { ok: true, clientId: payload.clientId });
+        }
+        else if (parsed.pathname === "/api/v1/shutdown") {
+            if (request.headers["x-pi-md-viewer-cli"] !== "1") {
+                this.error(response, 403, "forbidden", "CLI authorization required");
+                return;
+            }
+            this.sendJson(response, 200, { ok: true });
+            setTimeout(() => { void this.stop(); }, 0);
+        }
+        else {
+            this.error(response, 404, "not_found", "Endpoint not found");
+        }
+    }
+    async handleDelete(parsed, request, response) {
+        if (!parsed.pathname.startsWith("/api/v1/files/")) {
+            this.error(response, 404, "not_found", "Endpoint not found");
+            return;
+        }
+        if (!this.validCsrf(request, parsed)) {
+            this.error(response, 403, "forbidden", "Invalid CSRF token");
+            return;
+        }
+        const id = parsed.pathname.split("/").pop() ?? "";
+        const removed = this.registry.remove(id);
+        if (!removed) {
+            this.error(response, 404, "not_found", "File is not registered");
+            return;
+        }
+        this.emit("file_removed");
+        this.sendJson(response, 200, { ok: true, removed: recordJson(removed) });
+    }
+    handleEvents(parsed, response) {
+        const clientId = parsed.searchParams.get("clientId");
+        if (clientId)
+            this.lifecycle.open(clientId, Date.now() / 1000);
+        response.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        });
+        response.write(": connected\n\n");
+        this.subscribers.add(response);
+        response.on("close", () => {
+            this.subscribers.delete(response);
+            if (clientId)
+                this.lifecycle.close(clientId, Date.now() / 1000);
+        });
+    }
+    emit(event) {
+        for (const subscriber of this.subscribers) {
+            subscriber.write(`event: ${event}\ndata: {}\n\n`);
+        }
+    }
+    validCsrf(request, parsed) {
+        return request.headers["x-csrf-token"] === this.csrfToken || parsed.searchParams.get("csrf") === this.csrfToken;
+    }
+    startMonitor() {
+        this.monitor ??= setInterval(() => {
+            if (this.lifecycle.decision(Date.now() / 1000).shouldShutdown) {
+                void this.stop();
+            }
+        }, 500);
+    }
+    async serveAsset(name, response) {
+        const file = path.join(legacyAssetRoot, "static", name);
+        try {
+            const stat = statSync(file);
+            const type = name.endsWith(".css") ? "text/css; charset=utf-8" : "application/javascript; charset=utf-8";
+            response.writeHead(200, { "Content-Type": type, "Content-Length": stat.size });
+            createReadStream(file).pipe(response);
+        }
+        catch {
+            this.error(response, 404, "not_found", "Asset not found");
+        }
+    }
+    async readJson(request) {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of request) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += buffer.length;
+            if (size > MAX_REQUEST_BYTES)
+                throw new Error("Request body is too large");
+            chunks.push(buffer);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    sendJson(response, status, payload) {
+        const body = Buffer.from(JSON.stringify(payload));
+        this.sendBytes(response, status, body, "application/json; charset=utf-8");
+    }
+    sendBytes(response, status, body, contentType) {
+        response.writeHead(status, { "Content-Type": contentType, "Content-Length": body.length });
+        response.end(body);
+    }
+    error(response, status, code, message) {
+        this.sendJson(response, status, { error: { code, message } });
+    }
+}
+function recordJson(record) {
+    return {
+        id: record.id,
+        path: record.path,
+        displayName: record.displayName,
+        parentLabel: record.parentLabel,
+        size: record.size,
+        mtimeMs: record.mtimeMs,
+        order: record.order,
+    };
+}

package/dist/src-ts/types.js

@@ -0,0 +1,5 @@
+export const builtInDefaultConfig = {
+    defaultViewer: "system",
+    playwright: { browser: "chromium" },
+    viewers: {},
+};

package/dist/src-ts/viewer-command.js

@@ -0,0 +1,31 @@
+export function parseViewerCommand(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("viewer command must be non-empty");
+    if (trimmed.startsWith("[")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new Error(`viewer command JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0) {
+            throw new Error("viewer command JSON must be a non-empty string array");
+        }
+        if (!parsed.every((item) => typeof item === "string")) {
+            throw new Error("viewer command JSON array must contain only strings");
+        }
+        return parsed;
+    }
+    return [trimmed];
+}
+export function expandViewerCommand(command, url) {
+    if (command.length === 0)
+        throw new Error("viewer command must be non-empty");
+    const expanded = command.map((item) => item.replaceAll("{url}", url));
+    if (!expanded.some((item) => item.includes(url))) {
+        expanded.push(url);
+    }
+    return expanded;
+}

package/dist/src-ts/viewer-launcher.js

@@ -0,0 +1,107 @@
+import { spawn } from "node:child_process";
+import { headedPlaywrightUnavailableReason, systemOpenCommand } from "./platform.js";
+import { expandViewerCommand, parseViewerCommand } from "./viewer-command.js";
+async function defaultSpawnDetached(command, args) {
+    const child = spawn(command, args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+    return { code: 0 };
+}
+async function launchCommand(command, url, spawnDetached) {
+    const expanded = expandViewerCommand(command, url);
+    const [executable, ...args] = expanded;
+    if (!executable)
+        throw new Error("viewer command must be non-empty");
+    const result = await spawnDetached(executable, args);
+    if (typeof result.code === "number" && result.code !== 0) {
+        throw new Error(`viewer command exited with status ${result.code}; open ${url} manually`);
+    }
+}
+function isMissingPlaywrightPackage(error) {
+    const candidate = error;
+    return candidate.code === "ERR_MODULE_NOT_FOUND"
+        || candidate.code === "MODULE_NOT_FOUND"
+        || candidate.message?.includes("Cannot find package 'playwright'") === true
+        || candidate.message?.includes('Cannot find module "playwright"') === true;
+}
+function isMissingPlaywrightBrowser(error) {
+    const message = error.message ?? "";
+    return message.includes("Executable doesn't exist")
+        || message.includes("Executable doesn't exist at")
+        || message.includes("browserType.launch: Executable")
+        || message.includes("Please run the following command to download new browsers");
+}
+function playwrightInstallHint(browserName) {
+    return `Viewer "playwright" requires Playwright. Install it with:\nnpm install playwright\nnpx playwright install ${browserName}`;
+}
+function playwrightBrowserInstallHint(browserName) {
+    return `Viewer "playwright" browser is not installed. Install it with:\nnpx playwright install ${browserName}`;
+}
+function playwrightLaunchOptions(browserName, platform, env) {
+    const options = { headless: false };
+    if (browserName === "chromium") {
+        options.args = ["--start-maximized"];
+        if (platform === "linux" && env.WAYLAND_DISPLAY && !env.DISPLAY) {
+            options.args.push("--ozone-platform=wayland", "--enable-features=UseOzonePlatform");
+        }
+    }
+    return options;
+}
+async function launchPlaywright(request) {
+    const reason = headedPlaywrightUnavailableReason(request.platform, request.env);
+    if (reason === "unsupported-platform")
+        throw new Error('Viewer "playwright" is not available on this platform');
+    if (reason)
+        throw new Error(`Viewer "playwright" is not available: ${reason}`);
+    const browserName = request.selection.config.playwright.browser;
+    let imported;
+    try {
+        imported = request.importPlaywright ? await request.importPlaywright() : await import("playwright");
+    }
+    catch (error) {
+        if (isMissingPlaywrightPackage(error))
+            throw new Error(playwrightInstallHint(browserName));
+        throw error;
+    }
+    const api = imported;
+    const browserType = api[browserName];
+    if (!browserType)
+        throw new Error(`Playwright browser "${browserName}" is unavailable`);
+    let browser;
+    try {
+        browser = await browserType.launch(playwrightLaunchOptions(browserName, request.platform, request.env));
+    }
+    catch (error) {
+        if (isMissingPlaywrightBrowser(error))
+            throw new Error(playwrightBrowserInstallHint(browserName));
+        throw error;
+    }
+    const context = await browser.newContext({ viewport: null });
+    const page = await context.newPage();
+    await page.goto(request.url);
+}
+export async function launchViewer(request) {
+    const spawnDetached = request.spawnDetached ?? defaultSpawnDetached;
+    if (request.selection.viewerCommand) {
+        await launchCommand(parseViewerCommand(request.selection.viewerCommand), request.url, spawnDetached);
+        return;
+    }
+    if (request.selection.viewer === "system") {
+        const command = systemOpenCommand(request.platform, request.env);
+        if (!command)
+            throw new Error(`No system opener is available; open ${request.url} manually`);
+        await launchCommand(command, request.url, spawnDetached);
+        return;
+    }
+    if (request.selection.viewer === "playwright") {
+        await launchPlaywright(request);
+        return;
+    }
+    const named = request.selection.config.viewers[request.selection.viewer];
+    if (!named)
+        throw new Error(`Viewer "${request.selection.viewer}" is not configured`);
+    await launchCommand(named.command, request.url, spawnDetached);
+}

package/extensions/show-markdown.ts

@@ -0,0 +1,159 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { Type, type Static } from "typebox";
+
+const showMarkdownSchema = Type.Object({
+  paths: Type.Array(Type.String({ description: "Markdown path, absolute or relative to the current project" }), {
+    minItems: 1,
+    description: "One or more Markdown files to show in the local browser viewer",
+  }),
+  open: Type.Optional(Type.Boolean({
+    description: "Open the browser when no viewer page is connected (default: true)",
+  })),
+  viewer: Type.Optional(Type.String({
+    description: "Viewer strategy: system, playwright, or a named viewer from config",
+  })),
+  viewerCommand: Type.Optional(Type.String({
+    description: "Ad-hoc viewer command: plain executable or JSON argv array with optional {url}",
+  })),
+});
+
+export type ShowMarkdownInput = Static<typeof showMarkdownSchema>;
+
+export interface ViewerResult {
+  ok: boolean;
+  action: string;
+  url: string | null;
+  added: string[];
+  rejected: Array<{ path: string; code: string; message: string }>;
+  viewerClients: number;
+}
+
+export interface Invocation {
+  command: string;
+  args: string[];
+}
+
+export interface InvocationOptions {
+  platform?: NodeJS.Platform;
+  projectTrusted?: boolean;
+}
+
+export function buildInvocation(
+  cwd: string,
+  extensionFile: string,
+  input: ShowMarkdownInput,
+  options: InvocationOptions = {},
+): Invocation {
+  if (input.paths.length === 0) {
+    throw new Error("show_markdown requires at least one path");
+  }
+  const platform = options.platform ?? process.platform;
+  const pathForCwd = platform === "win32" ? path.win32 : path.posix;
+  const extensionPath = fileURLToPath(extensionFile);
+  const launcher = path.resolve(path.dirname(extensionPath), "..", "bin", "mdview.js");
+  const resolvedPaths = input.paths.map((supplied) => {
+    const normalized = supplied.startsWith("@") ? supplied.slice(1) : supplied;
+    if (!normalized) throw new Error("show_markdown path cannot be empty");
+    return pathForCwd.resolve(cwd, normalized);
+  });
+  const args = [launcher, "--json", "--launched-from-pi", "--cwd", cwd];
+  if (options.projectTrusted) args.push("--project-trusted");
+  if (input.open === false) args.push("--no-open");
+  if (input.viewer) args.push("--viewer", input.viewer);
+  if (input.viewerCommand) args.push("--viewer-command", input.viewerCommand);
+  args.push(...resolvedPaths);
+  return { command: process.execPath, args };
+}
+
+export function parseViewerResult(stdout: string): ViewerResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`Viewer returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isViewerResult(value)) {
+    throw new Error("Viewer returned an invalid result object");
+  }
+  return value;
+}
+
+function isViewerResult(value: unknown): value is ViewerResult {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.ok === "boolean"
+    && typeof candidate.action === "string"
+    && (typeof candidate.url === "string" || candidate.url === null)
+    && Array.isArray(candidate.added)
+    && candidate.added.every((item) => typeof item === "string")
+    && Array.isArray(candidate.rejected)
+    && candidate.rejected.every(isRejectedPath)
+    && typeof candidate.viewerClients === "number";
+}
+
+function isRejectedPath(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.path === "string"
+    && typeof candidate.code === "string"
+    && typeof candidate.message === "string";
+}
+
+function safeError(stderr: string, stdout: string): string {
+  const diagnostic = stderr.trim();
+  if (diagnostic) return diagnostic.slice(0, 4096);
+  const output = stdout.trim();
+  if (!output) return "mdview failed without diagnostic output";
+  try {
+    const parsed = JSON.parse(output) as { message?: unknown; error?: { message?: unknown } };
+    const message = parsed.message ?? parsed.error?.message;
+    if (typeof message === "string" && message.trim()) return message.trim().slice(0, 4096);
+  } catch {
+    // Fall back to the bounded raw output below.
+  }
+  return output.slice(0, 4096);
+}
+
+function formatResult(result: ViewerResult): string {
+  const pieces = [`${result.action}: ${result.added.length} Markdown file(s)`];
+  if (result.url) pieces.push(result.url);
+  if (result.rejected.length > 0) {
+    pieces.push(`${result.rejected.length} rejected: ${result.rejected.map((item) => item.path).join(", ")}`);
+  }
+  return pieces.join("\n");
+}
+
+export default function registerExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "show_markdown",
+    label: "Show Markdown",
+    description: "Open one or more local Markdown files in the local browser viewer. Reuses the active viewer and returns a loopback URL. Does not install dependencies.",
+    promptSnippet: "Open local Markdown files in a responsive browser viewer",
+    promptGuidelines: [
+      "Use show_markdown when the user asks to show, demonstrate, preview, or conveniently open one or more Markdown documents.",
+    ],
+    parameters: showMarkdownSchema,
+    async execute(_toolCallId, input, signal, _onUpdate, ctx) {
+      const projectTrusted = typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : false;
+      const invocation = buildInvocation(ctx.cwd, import.meta.url, input, { projectTrusted });
+      const child = await pi.exec(invocation.command, invocation.args, {
+        signal,
+        timeout: 15_000,
+      });
+      if (child.code !== 0) {
+        throw new Error(safeError(child.stderr, child.stdout));
+      }
+      const result = parseViewerResult(child.stdout);
+      if (!result.ok) {
+        throw new Error(formatResult(result));
+      }
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        details: result,
+      };
+    },
+  });
+}