pm-canvas-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 path
+
+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,112 @@
+# pm-canvas-viewer
+
+本地画板查看器 + 文档编辑工具。一键启动，浏览器操作。
+
+配合 [pm-canvas skill](../skill/) 使用：Agent 生成画板文件，人用 viewer 预览画板并编辑关联文档。
+
+## 安装
+
+```bash
+npm i -g pm-canvas-viewer
+```
+
+装好后全局命令 `canvas` 即可用（包内已含预构建前端，无需自行构建）。
+
+## 使用
+
+```bash
+canvas open ./我的画板/
+```
+
+浏览器自动打开，左侧画板预览，右侧文档编辑面板。
+
+### 画板目录结构
+
+```
+我的画板/
+├── index.html          ← 画板 shell（Agent 生成）
+├── canvas.json         ← 画板元数据（Agent 生成）
+├── rows/               ← 画板行文件（Agent 生成）
+│   ├── 01-home.html
+│   └── 02-profile.html
+└── docs/               ← 关联文档（人维护，viewer 读写）
+    ├── 需求规格.md
+    └── 业务流程.excalidraw
+```
+
+### 命令参数
+
+```bash
+canvas open [目录] [选项]
+
+# 选项
+-p, --port <端口>    指定端口（默认 4800）
+-V, --version        查看版本
+-h, --help           查看帮助
+```
+
+## 功能
+
+### 画板预览（左侧）
+- iframe 加载画板 index.html，所有 row 平铺展示
+
+### 文档面板（右侧，可收起）
+
+**Markdown 编辑器**
+- Tiptap 3 所见即所得编辑器（WYSIWYG，`@tiptap/markdown` 读写 MD）
+- 工具栏：标题、加粗、斜体、列表、代码、表格可视化编辑
+- `⌘B` 加粗、`⌘I` 斜体
+- `⌘S` 保存到本地文件
+
+**Excalidraw 编辑器**
+- 完整 Excalidraw 编辑器（画流程图、架构图等）
+- `⌘S` 保存为 .excalidraw 文件
+
+**文件管理**
+- 标签页切换不同文档
+- `+` 按钮新建 Markdown 或 Excalidraw 文件
+- 文件保存在画板目录的 `docs/` 下
+
+## 技术栈
+
+| 层 | 技术 |
+|---|---|
+| CLI | Commander.js |
+| 服务端 | Express（静态文件 + 文件读写 API） |
+| 前端框架 | React 18 + Vite |
+| MD 编辑器 | Tiptap 3 WYSIWYG（@tiptap/markdown） |
+| 流程图编辑 | @excalidraw/excalidraw |
+| 构建 | Vite 5 |
+
+## 开发
+
+```bash
+# 启动开发服务器（前后端同时启动）
+npm run dev
+
+# 仅构建前端
+npm run build
+
+# 用开发版直接测试
+node bin/cli.js open /path/to/canvas --port 4800
+```
+
+### 项目结构
+
+```
+pm-canvas-viewer/
+├── bin/cli.js                  ← CLI 入口
+├── server/
+│   ├── index.js                ← Express 服务器
+│   └── api/files.js            ← 文件 CRUD API（限定 docs/ 目录）
+├── frontend/
+│   ├── src/
+│   │   ├── App.jsx             ← 主布局
+│   │   ├── CanvasView/         ← 画板 iframe
+│   │   ├── DocPanel/           ← 右侧面板 + 标签页 + 新建
+│   │   ├── MdEditor/           ← Tiptap MD 编辑器
+│   │   └── ExcalidrawEditor/   ← Excalidraw 编辑器
+│   └── vite.config.js
+├── dist/                       ← 前端构建产物（gitignored）
+└── ai/                         ← AI 协作产物
+```

package/bin/cli.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import open from 'open';
+import { createServer } from '../server/index.js';
+import { scanForCanvases, tryReadCanvasMeta } from '../lib/scanner.js';
+import { recordOpen, getRecentCanvases } from '../lib/history.js';
+import { findAvailablePort, isPortFree, getPortOccupant, killPort, listRunningInstances, registerInstance } from '../lib/port.js';
+import { fuzzySelectCanvas, fuzzySelectFromHistory, handlePortConflict } from '../lib/prompts.js';
+
+const program = new Command();
+
+program
+  .name('canvas')
+  .description('Local canvas viewer + doc editor')
+  .version('0.1.0');
+
+// Default command: canvas — interactive fuzzy search over history
+program
+  .action(async () => {
+    const entries = await getRecentCanvases();
+    const selected = await fuzzySelectFromHistory(entries);
+    if (!selected) process.exit(0);
+
+    const meta = await tryReadCanvasMeta(selected.path);
+    if (!meta) {
+      console.error(`  Canvas no longer exists: ${selected.path}`);
+      process.exit(1);
+    }
+
+    await startServer(selected.path, meta);
+  });
+
+// canvas open [path] — scan current directory or open a direct path
+program
+  .command('open [path]')
+  .description('Scan current directory for canvases, or open a path directly')
+  .option('-p, --port <port>', 'Server port', '4800')
+  .action(async (targetPath, opts) => {
+    portOverride = opts.port ? parseInt(opts.port) : null;
+
+    if (targetPath) {
+      const fullPath = resolve(targetPath);
+
+      if (!existsSync(fullPath)) {
+        console.error(`  Directory not found: ${fullPath}`);
+        process.exit(1);
+      }
+
+      // Direct canvas path
+      const meta = await tryReadCanvasMeta(fullPath);
+      if (meta) {
+        await startServer(meta.path, meta);
+        return;
+      }
+
+      // Not a canvas — scan it
+      console.log('  Scanning for canvases...');
+      const found = await scanForCanvases(fullPath, 4);
+      const history = await getRecentCanvases();
+      const selected = await fuzzySelectCanvas(found, history);
+      if (!selected) process.exit(0);
+      await startServer(selected.path, selected);
+    } else {
+      // No path — scan current directory
+      const cwd = process.cwd();
+      const cwdMeta = await tryReadCanvasMeta(cwd);
+
+      if (cwdMeta) {
+        await startServer(cwdMeta.path, cwdMeta);
+        return;
+      }
+
+      console.log('  Scanning for canvases...');
+      const found = await scanForCanvases(cwd, 4);
+      const history = await getRecentCanvases();
+      const selected = await fuzzySelectCanvas(found, history);
+      if (!selected) process.exit(0);
+      await startServer(selected.path, selected);
+    }
+  });
+
+program
+  .command('list')
+  .description('Show running canvas instances')
+  .action(async () => {
+    const instances = await listRunningInstances();
+    if (instances.length === 0) {
+      console.log('  No running canvas instances.');
+      return;
+    }
+
+    console.log(`\n  Running instances:\n`);
+    for (const inst of instances) {
+      console.log(`  Port ${inst.port}  PID ${inst.pid}`);
+      console.log(`  ${inst.title || 'unknown'}`);
+      console.log(`  ${inst.canvasDir}\n`);
+    }
+  });
+
+program
+  .command('stop [port]')
+  .description('Stop canvas instance(s)')
+  .option('-a, --all', 'Stop all instances')
+  .action(async (portArg, opts) => {
+    if (opts.all) {
+      const instances = await listRunningInstances();
+      if (instances.length === 0) {
+        console.log('  No running instances.');
+        return;
+      }
+      for (const inst of instances) {
+        killPort(inst.port);
+        console.log(`  Stopped port ${inst.port} (PID ${inst.pid})`);
+      }
+      return;
+    }
+
+    if (!portArg) {
+      const instances = await listRunningInstances();
+      if (instances.length === 0) {
+        console.log('  No running instances.');
+        return;
+      }
+      if (instances.length === 1) {
+        killPort(instances[0].port);
+        console.log(`  Stopped port ${instances[0].port} (PID ${instances[0].pid})`);
+        return;
+      }
+      console.log('  Multiple instances running. Specify a port or use --all:');
+      for (const inst of instances) {
+        console.log(`  canvas stop ${inst.port}`);
+      }
+      return;
+    }
+
+    const port = parseInt(portArg);
+    const occupant = getPortOccupant(port);
+    if (!occupant) {
+      console.log(`  Nothing running on port ${port}`);
+      return;
+    }
+    killPort(port);
+    console.log(`  Stopped port ${port} (PID ${occupant.pid})`);
+  });
+
+let portOverride = null;
+
+async function startServer(canvasDir, meta) {
+  const preferredPort = portOverride || 4800;
+  let port;
+
+  if (await isPortFree(preferredPort)) {
+    port = preferredPort;
+  } else {
+    const occupant = getPortOccupant(preferredPort);
+
+    if (occupant?.isPmCanvas) {
+      const action = await handlePortConflict(preferredPort, occupant);
+      if (!action) process.exit(0);
+
+      switch (action) {
+        case 'reuse':
+          const url = `http://localhost:${preferredPort}`;
+          console.log(`\n  Opening ${url}`);
+          await open(url);
+          process.exit(0);
+        case 'kill':
+          killPort(preferredPort);
+          await new Promise(r => setTimeout(r, 500));
+          port = preferredPort;
+          break;
+        case 'next':
+          port = await findAvailablePort(preferredPort + 1);
+          break;
+      }
+    } else {
+      port = await findAvailablePort(preferredPort);
+    }
+  }
+
+  const server = createServer(canvasDir);
+  const title = meta?.title || canvasDir.split('/').pop();
+  server.listen(port, async () => {
+    const url = `http://localhost:${port}`;
+    console.log(`\n  canvas-viewer`);
+    console.log(`  Canvas: ${title}`);
+    console.log(`  Path:   ${canvasDir}`);
+    console.log(`  URL:    ${url}\n`);
+    open(url);
+
+    await registerInstance(port, canvasDir, title).catch(() => {});
+    await recordOpen(canvasDir, meta?.title).catch(() => {});
+  });
+}
+
+program.parse();