@zkov/pi-md-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zkov
+
+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

@@ -0,0 +1,250 @@
+# pi-md-viewer
+
+Local loopback Markdown viewer and pi agent tool. `mdview` открывает один или
+несколько локальных Markdown-файлов в тёмном адаптивном browser UI. Повторный
+вызов использует тот же `127.0.0.1` server и обновляет уже открытую страницу.
+
+Runtime реализован на TypeScript/Node.js.
+
+## Требования
+
+- Node.js 22 или новее;
+- npm dependencies из `package.json`;
+- Linux desktop system opener: `xdg-open`;
+- macOS system opener: `open` — экспериментальная поддержка до проверки на macOS;
+- для Playwright viewer: manual `npm install playwright` и установленный browser binary;
+- для Termux system opener: `termux-open-url` из Termux:API package.
+
+Server слушает только `127.0.0.1`. Viewer не создаёт runtime HTML, PID, lock,
+socket, log, cache или bytecode files. Markdown raw HTML отключён.
+
+## Быстрый старт
+
+Из корня checkout:
+
+```bash
+npm install
+npm run build
+node bin/mdview.js README.md
+```
+
+После npm/global install можно использовать console command:
+
+```bash
+mdview README.md
+```
+
+## Использование
+
+```bash
+mdview README.md
+mdview README.md docs/design.md notes.markdown
+mdview --no-open README.md
+mdview --json README.md
+mdview --status
+mdview --close
+```
+
+Поддерживаются `.md`, `.markdown`, `.mdown` и `.mkd`. Paths разрешаются
+относительно текущего каталога, canonical paths дедуплицируются. Неверные paths
+показываются отдельно; корректная часть одного вызова всё равно открывается.
+
+Первый вызов запускает detached Node.js server на первом свободном порту из
+`127.0.0.1:18765–18774`. Последующие вызовы находят его по fingerprint и
+protocol version, а затем добавляют документы через локальный control API.
+Локальные control requests не используют proxy environment. Для изолированных
+тестов range можно переопределить переменной `PI_MD_VIEWER_PORT_RANGE`, например
+`19000-19009`.
+
+Browser UI позволяет переключать, обновлять и выгружать документы, копировать
+code blocks и закрывать всю viewer session. Выгрузка последнего документа
+завершает viewer и закрывает его вкладки. Markdown перечитывается и безопасно
+рендерится в памяти при каждом запросе.
+
+## Viewer configuration
+
+Standalone CLI priority:
+
+```text
+CLI args > .md-viewer.json > user config > built-in default
+```
+
+Pi-extension priority:
+
+```text
+CLI args passed by extension > pi tool input > .pi/pi-md-viewer.json > .md-viewer.json > user config > built-in default
+```
+
+Standalone CLI игнорирует `.pi/pi-md-viewer.json`. Pi extension читает
+`.pi/pi-md-viewer.json` только в trusted project.
+
+Built-in default:
+
+```json
+{
+  "defaultViewer": "system",
+  "playwright": { "browser": "chromium" },
+  "viewers": {}
+}
+```
+
+User config lookup:
+
+1. `PI_MD_VIEWER_CONFIG`, если задан;
+2. Windows: `%APPDATA%\\pi-md-viewer\\config.json`;
+3. macOS: `~/Library/Application Support/pi-md-viewer/config.json`;
+4. POSIX: `$XDG_CONFIG_HOME/pi-md-viewer/config.json`;
+5. fallback для всех платформ: `~/.config/pi-md-viewer/config.json`.
+
+Example `.md-viewer.json`:
+
+```json
+{
+  "defaultViewer": "chrome",
+  "viewers": {
+    "chrome": {
+      "command": [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "--new-window",
+        "{url}"
+      ]
+    }
+  }
+}
+```
+
+## Viewer selection
+
+```bash
+mdview --viewer system README.md
+mdview --viewer playwright README.md
+mdview --viewer chrome README.md
+mdview --viewer-command "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" README.md
+mdview --viewer-command '["firefox","--new-window","{url}"]' README.md
+```
+
+`--viewer` accepts built-ins (`system`, `playwright`) or a named custom viewer
+from config. `--viewer-command` is an ad-hoc command and has higher priority than
+`--viewer`.
+
+Custom commands are argv arrays, never shell command strings. `{url}` is replaced
+inside argv elements. If no argv element contains the final URL, URL is appended
+as the last argument.
+
+## Playwright viewer
+
+Playwright opens the viewer in a headed browser when explicitly selected:
+
+```bash
+npm install playwright
+npx playwright install chromium
+mdview --viewer playwright README.md
+```
+
+Playwright is not installed automatically by `pi-md-viewer`. Install it manually
+only on platforms where you explicitly want the headed Playwright viewer.
+
+The Playwright viewer uses the real browser window viewport so the Markdown UI
+resizes with the window instead of being locked to Playwright's default fixed
+viewport. Chromium also starts maximized where the browser supports that flag.
+
+Supported platforms: Windows, Linux desktop with `DISPLAY` or
+`WAYLAND_DISPLAY`, and experimental macOS support. On Linux Wayland-only sessions, Chromium is launched with
+Ozone/Wayland flags. Termux/Android is not a Playwright platform; `--viewer
+playwright` reports that the viewer is not available on that platform and does
+not attempt to import Playwright. Use the default `system` viewer on Termux,
+which opens URLs through `termux-open-url`.
+
+If Playwright is selected on a supported desktop platform but the package or
+browser binary is missing, the viewer returns install commands and does not
+silently fall back to `system`.
+
+## Lifecycle
+
+Browser page отправляет heartbeat и держит SSE connection. После закрытия
+последней страницы server даёт 5 секунд на refresh/reconnect, очищает in-memory
+registry и завершается. Если browser ни разу не подключился, startup instance
+завершается через 30 секунд. `mdview --close` завершает его явно.
+
+## Pi Package Catalog
+
+Package подготовлен для публикации в Pi Package Catalog через npm:
+
+```bash
+pi install npm:@zkov/pi-md-viewer
+```
+
+Catalog metadata находится в `package.json`:
+
+```json
+{
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./dist/extensions/show-markdown.js"]
+  }
+}
+```
+
+Package регистрирует tool:
+
+```text
+show_markdown(paths: string[], open?: boolean, viewer?: string, viewerCommand?: string)
+```
+
+Публикационный tarball собирается из TypeScript build output и runtime assets.
+Playwright не устанавливается автоматически; пользователи desktop-платформ
+устанавливают его вручную, только если нужен `--viewer playwright`.
+
+## Подключение к pi из checkout
+
+Установите trusted local checkout как pi package:
+
+```bash
+pi install /absolute/path/to/package
+pi list
+```
+
+Для приватного git repository:
+
+```bash
+pi install git:https://github.com/zkov96/ai-md-shower
+```
+
+Example pi tool input:
+
+```json
+{
+  "paths": ["README.md"],
+  "viewer": "playwright"
+}
+```
+
+Relative paths разрешаются от текущего рабочего каталога pi. `open: false`
+добавляет `--no-open`; иначе browser открывается только при отсутствии активной
+viewer page. Tool передаёт каждый path отдельным argv element, не использует
+shell и никогда не устанавливает dependencies автоматически.
+
+Pi extensions выполняются с полными правами пользователя. Устанавливайте package
+только из checkout/repository, исходникам которого доверяете. Viewer ограничивает
+HTTP bind loopback-интерфейсом и не позволяет browser API регистрировать
+произвольные filesystem paths.
+
+Удаление package из user settings:
+
+```bash
+pi remove /absolute/path/to/package
+```
+
+## Публикация package
+
+Проверить состав tarball:
+
+```bash
+npm run build
+npm pack --dry-run
+```
+
+## Разработка
+
+Архитектура и пошаговый implementation plan находятся в
+`docs/superpowers/specs/` и `docs/superpowers/plans/`.

package/bin/mdview.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/src-ts/main.js";

package/dist/extensions/show-markdown.js

@@ -0,0 +1,137 @@
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { Type } 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 function buildInvocation(cwd, extensionFile, input, options = {}) {
+    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) {
+    let value;
+    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) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    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) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.path === "string"
+        && typeof candidate.code === "string"
+        && typeof candidate.message === "string";
+}
+function safeError(stderr, stdout) {
+    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);
+        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) {
+    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) {
+    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,
+            };
+        },
+    });
+}

package/dist/src-ts/cli.js

@@ -0,0 +1,219 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadEffectiveConfig } from "./config.js";
+import { discover, portRangeFromEnv, sendFiles, shutdownInstance } from "./discovery.js";
+import { FileRegistry } from "./registry.js";
+import { MarkdownRenderer } from "./renderer.js";
+import { ViewerServer } from "./server.js";
+import { launchViewer } from "./viewer-launcher.js";
+const STARTUP_TIMEOUT_MS = 5000;
+function operationResult(payload) {
+    return { url: null, added: [], rejected: [], viewerClients: 0, ...payload };
+}
+function parseArgs(argv, cwd) {
+    const parsed = {
+        paths: [],
+        json: false,
+        noOpen: false,
+        status: false,
+        close: false,
+        serve: false,
+        launchedFromPi: false,
+        projectTrusted: false,
+        cwd,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--json")
+            parsed.json = true;
+        else if (arg === "--no-open")
+            parsed.noOpen = true;
+        else if (arg === "--status")
+            parsed.status = true;
+        else if (arg === "--close")
+            parsed.close = true;
+        else if (arg === "--serve")
+            parsed.serve = true;
+        else if (arg === "--launched-from-pi")
+            parsed.launchedFromPi = true;
+        else if (arg === "--project-trusted")
+            parsed.projectTrusted = true;
+        else if (arg === "--port")
+            parsed.port = Number(requireValue(argv, ++index, arg));
+        else if (arg === "--cwd")
+            parsed.cwd = requireValue(argv, ++index, arg);
+        else if (arg === "--viewer")
+            parsed.viewer = requireValue(argv, ++index, arg);
+        else if (arg === "--viewer-command")
+            parsed.viewerCommand = requireValue(argv, ++index, arg);
+        else
+            parsed.paths.push(arg);
+    }
+    return parsed;
+}
+function requireValue(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function printResult(result, jsonMode, io) {
+    if (jsonMode) {
+        io.stdout(JSON.stringify(result));
+        return;
+    }
+    if (!result.ok) {
+        io.stderr(result.message ?? "Viewer operation failed");
+        return;
+    }
+    io.stdout(result.message ?? result.url ?? result.action);
+}
+export async function main(argv, io = {}) {
+    const env = io.env ?? process.env;
+    const output = { stdout: io.stdout ?? console.log, stderr: io.stderr ?? console.error };
+    let args;
+    try {
+        args = parseArgs(argv, process.cwd());
+        if (args.serve)
+            return await serve(args.port, args.paths);
+        const result = await operate(args, env);
+        printResult(result, args.json, output);
+        return result.ok ? 0 : 1;
+    }
+    catch (error) {
+        const json = argv.includes("--json");
+        const result = operationResult({ ok: false, action: "error", message: error instanceof Error ? error.message : String(error) });
+        printResult(result, json, output);
+        return 1;
+    }
+}
+async function operate(args, env) {
+    const modes = Number(args.status) + Number(args.close);
+    if (modes > 1)
+        return operationResult({ ok: false, action: "error", message: "Choose only one control mode" });
+    const ports = portRangeFromEnv(env);
+    let instance = await discover(ports, env);
+    if (args.status) {
+        if (!instance)
+            return operationResult({ ok: false, action: "error", message: "Viewer is not running" });
+        return operationResult({ ok: true, action: "status", url: instance.url, viewerClients: instance.viewerClients, message: `PID ${instance.pid}; ${instance.files} file(s)` });
+    }
+    if (args.close) {
+        if (!instance)
+            return operationResult({ ok: false, action: "error", message: "Viewer is not running" });
+        await shutdownInstance(instance);
+        await waitForShutdown(instance, env);
+        return operationResult({ ok: true, action: "closed", url: instance.url });
+    }
+    if (args.paths.length === 0)
+        return operationResult({ ok: false, action: "error", message: "At least one Markdown file is required" });
+    const registry = new FileRegistry();
+    const added = registry.addMany(args.paths.map((item) => path.resolve(args.cwd, item)));
+    const accepted = [...added.added, ...added.existing].map((record) => record.path);
+    if (accepted.length === 0) {
+        return operationResult({ ok: false, action: "error", rejected: added.rejected, message: "No valid Markdown files" });
+    }
+    let action = "updated";
+    if (!instance) {
+        instance = await startDetached(ports, accepted, env);
+        if (!instance)
+            return operationResult({ ok: false, action: "error", added: accepted, rejected: added.rejected, message: "No free port in the configured viewer port range" });
+        action = "started";
+    }
+    else {
+        const response = await sendFiles(instance, accepted);
+        const serverRejected = Array.isArray(response.rejected) ? response.rejected : [];
+        added.rejected.push(...serverRejected);
+        instance = await discover([instance.port], env) ?? instance;
+    }
+    const result = operationResult({ ok: true, action, url: instance.url, added: accepted, rejected: added.rejected, viewerClients: instance.viewerClients });
+    if (!args.noOpen && instance.viewerClients === 0) {
+        const cliOverrides = { viewer: args.viewer, viewerCommand: args.viewerCommand };
+        const selection = loadEffectiveConfig({
+            cwd: args.cwd,
+            env,
+            platform: process.platform,
+            homeDir: os.homedir(),
+            launchedFromPi: args.launchedFromPi,
+            projectTrusted: args.projectTrusted,
+            piOverrides: cliOverrides,
+            cliOverrides,
+        });
+        await launchViewer({ url: instance.url, selection, platform: process.platform, env });
+    }
+    return result;
+}
+async function serve(port, paths) {
+    if (!port)
+        return 2;
+    const registry = new FileRegistry();
+    const result = registry.addMany(paths);
+    if (result.added.length === 0 && result.existing.length === 0)
+        return 2;
+    const server = new ViewerServer({ host: "127.0.0.1", port, registry, renderer: new MarkdownRenderer(), monitorLifecycle: true });
+    await server.start();
+    await new Promise((resolve) => {
+        process.once("SIGINT", () => { void server.stop().then(resolve); });
+    });
+    return 0;
+}
+async function startDetached(ports, paths, env) {
+    for (const port of ports) {
+        if (!(await portIsFree(port))) {
+            const winner = await discover([port], env);
+            if (winner) {
+                await sendFiles(winner, paths);
+                return await discover([port], env) ?? winner;
+            }
+            continue;
+        }
+        const child = spawn(process.execPath, [entrypointPath(), "--serve", "--port", String(port), ...paths], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: { ...env, NODE_NO_WARNINGS: "1" },
+        });
+        child.unref();
+        const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            const instance = await discover([port], env);
+            if (instance)
+                return instance;
+            if (child.exitCode !== null)
+                break;
+            await delay(50);
+        }
+    }
+    return await discover(ports, env);
+}
+function entrypointPath() {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const dist = path.join(root, "dist", "src-ts", "main.js");
+    if (existsSync(dist))
+        return dist;
+    return fileURLToPath(import.meta.url).replace(/cli\.(ts|js)$/, "main.js");
+}
+async function portIsFree(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+    });
+}
+async function waitForShutdown(instance, env) {
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline) {
+        const current = await discover([instance.port], env);
+        if (!current || current.pid !== instance.pid)
+            return;
+        await delay(50);
+    }
+    throw new Error(`Viewer PID ${instance.pid} did not stop within 3 seconds`);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}