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:

npm install
npm run build
node bin/mdview.js README.md

После npm/global install можно использовать console command:

mdview README.md

Использование

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:

CLI args > .md-viewer.json > user config > built-in default

Pi-extension priority:

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:

{
  "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:

{
  "defaultViewer": "chrome",
  "viewers": {
    "chrome": {
      "command": [
        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
        "--new-window",
        "{url}"
      ]
    }
  }
}

Viewer selection

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:

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:

pi install npm:@zkov/pi-md-viewer

Catalog metadata находится в package.json:

{
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./dist/extensions/show-markdown.js"]
  }
}

Package регистрирует tool:

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:

pi install /absolute/path/to/package
pi list

Для приватного git repository:

pi install git:https://github.com/zkov96/ai-md-shower

Example pi tool input:

{
  "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:

pi remove /absolute/path/to/package

Публикация package

Проверить состав tarball:

npm run build
npm pack --dry-run

Разработка

Архитектура и пошаговый implementation plan находятся в docs/superpowers/specs/ и docs/superpowers/plans/.