md-review-server 0.1.0

package/server/comment-store.js

@@ -0,0 +1,277 @@
+import { mkdir, readFile, readdir, rename, writeFile } from 'fs/promises';
+import { dirname, extname, isAbsolute, join, resolve } from 'path';
+
+const VALID_STATUSES = new Set([
+  'open',
+  'resolved',
+  'partially_resolved',
+  'unresolved',
+  'ignored',
+]);
+
+function normalizeReviewFile(file) {
+  if (!file || typeof file !== 'string') {
+    throw new Error('Comment file is required');
+  }
+
+  const normalized = file.replaceAll('\\', '/');
+  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+    throw new Error(`Invalid comment file: ${file}`);
+  }
+
+  return normalized;
+}
+
+function reviewFilenameFor(file) {
+  const normalized = normalizeReviewFile(file);
+  const ext = extname(normalized);
+  const withoutExt = ext ? normalized.slice(0, -ext.length) : normalized;
+  return `${withoutExt.replaceAll('/', '__').replace(/[^A-Za-z0-9._-]/g, '_')}.review.json`;
+}
+
+function extractDocumentVersion(file) {
+  const filename = file.split('/').pop() || '';
+  const match = filename.match(/(?:^|[._-])(v\d+)(?=[._-]|$)/);
+  return match?.[1];
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function initialReviewDocument(file) {
+  const now = nowIso();
+  return {
+    schemaVersion: 1,
+    document: file,
+    createdAt: now,
+    updatedAt: now,
+    comments: [],
+  };
+}
+
+function nextCommentId(comments) {
+  const max = comments.reduce((currentMax, comment) => {
+    const match = /^c(\d+)$/.exec(comment.id || '');
+    return match ? Math.max(currentMax, Number(match[1])) : currentMax;
+  }, 0);
+  return `c${String(max + 1).padStart(3, '0')}`;
+}
+
+function applyPatch(comment, patch, timestamp) {
+  const next = { ...comment };
+  const fields = [
+    'comment',
+    'status',
+    'targetFile',
+    'resolution',
+    'consumedBy',
+    'startLine',
+    'endLine',
+    'startOffset',
+    'endOffset',
+    'selectedText',
+    'beforeText',
+    'afterText',
+  ];
+
+  for (const field of fields) {
+    if (patch[field] !== undefined) {
+      next[field] = patch[field];
+    }
+  }
+
+  if (patch.status !== undefined) {
+    if (!VALID_STATUSES.has(patch.status)) {
+      throw new Error(`Invalid comment status: ${patch.status}`);
+    }
+    if (patch.status !== 'open' && patch.status !== comment.status) {
+      next.consumedAt = timestamp;
+    }
+  }
+
+  next.updatedAt = timestamp;
+  return next;
+}
+
+export class FileCommentStore {
+  constructor({ rootDir, reviewDir = '.reviews' }) {
+    this.rootDir = resolve(rootDir);
+    this.reviewDir = isAbsolute(reviewDir) ? reviewDir : resolve(this.rootDir, reviewDir);
+  }
+
+  async ensureReviewDir() {
+    await mkdir(this.reviewDir, { recursive: true });
+  }
+
+  getReviewFilePath(file) {
+    return join(this.reviewDir, reviewFilenameFor(file));
+  }
+
+  async listComments(filter = {}) {
+    if (filter.file) {
+      const review = await this.readReviewFile(filter.file);
+      return this.applyFilter(review.comments, filter);
+    }
+
+    const reviews = await this.readAllReviewFiles();
+    return this.applyFilter(
+      reviews.flatMap((review) => review.comments),
+      filter,
+    );
+  }
+
+  async createComment(input) {
+    const file = normalizeReviewFile(input.file);
+    const review = await this.readReviewFile(file);
+    const timestamp = nowIso();
+    const comment = {
+      id: nextCommentId(review.comments),
+      file,
+      documentVersion: extractDocumentVersion(file),
+      startLine: input.startLine,
+      endLine: input.endLine,
+      startOffset: input.startOffset,
+      endOffset: input.endOffset,
+      selectedText: input.selectedText,
+      beforeText: input.beforeText,
+      afterText: input.afterText,
+      comment: input.comment,
+      status: 'open',
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+
+    review.comments.push(comment);
+    await this.writeReviewFile(file, review, timestamp);
+    return comment;
+  }
+
+  async updateComment(id, patch) {
+    const { file, review } = await this.findReviewForComment(id, patch.file);
+    const timestamp = nowIso();
+    const index = review.comments.findIndex((comment) => comment.id === id);
+    if (index === -1) {
+      throw new Error(`Comment not found: ${id}`);
+    }
+
+    review.comments[index] = applyPatch(review.comments[index], patch, timestamp);
+    await this.writeReviewFile(file, review, timestamp);
+    return review.comments[index];
+  }
+
+  async batchUpdateComments(updates) {
+    const updated = [];
+    for (const update of updates) {
+      updated.push(await this.updateComment(update.id, update));
+    }
+    return updated;
+  }
+
+  async deleteComment(id, options = {}) {
+    const { file, review } = await this.findReviewForComment(id, options.file);
+    const nextComments = review.comments.filter((comment) => comment.id !== id);
+    if (nextComments.length === review.comments.length) {
+      throw new Error(`Comment not found: ${id}`);
+    }
+
+    review.comments = nextComments;
+    await this.writeReviewFile(file, review, nowIso());
+  }
+
+  applyFilter(comments, filter) {
+    return comments.filter((comment) => {
+      if (filter.status && comment.status !== filter.status) {
+        return false;
+      }
+      return true;
+    });
+  }
+
+  async readReviewFile(file) {
+    const normalized = normalizeReviewFile(file);
+    const reviewFile = this.getReviewFilePath(normalized);
+
+    try {
+      const parsed = JSON.parse(await readFile(reviewFile, 'utf-8'));
+      return {
+        ...parsed,
+        document: parsed.document || normalized,
+        comments: Array.isArray(parsed.comments) ? parsed.comments : [],
+      };
+    } catch (err) {
+      if (err?.code === 'ENOENT') {
+        return initialReviewDocument(normalized);
+      }
+      if (err instanceof SyntaxError) {
+        throw new Error(`Invalid review file JSON: ${reviewFile}`);
+      }
+      throw err;
+    }
+  }
+
+  async readAllReviewFiles() {
+    await this.ensureReviewDir();
+    const entries = await readdir(this.reviewDir, { withFileTypes: true });
+    const reviews = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.review.json')) {
+        continue;
+      }
+
+      const reviewFile = join(this.reviewDir, entry.name);
+      try {
+        const parsed = JSON.parse(await readFile(reviewFile, 'utf-8'));
+        reviews.push({
+          ...parsed,
+          comments: Array.isArray(parsed.comments) ? parsed.comments : [],
+        });
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          throw new Error(`Invalid review file JSON: ${reviewFile}`);
+        }
+        throw err;
+      }
+    }
+
+    return reviews;
+  }
+
+  async writeReviewFile(file, review, timestamp) {
+    await this.ensureReviewDir();
+    const reviewFile = this.getReviewFilePath(file);
+    const nextReview = {
+      schemaVersion: review.schemaVersion || 1,
+      document: review.document || file,
+      createdAt: review.createdAt || timestamp,
+      updatedAt: timestamp,
+      comments: review.comments,
+    };
+    const tempFile = `${reviewFile}.${process.pid}.${Date.now()}.tmp`;
+
+    await mkdir(dirname(reviewFile), { recursive: true });
+    await writeFile(tempFile, `${JSON.stringify(nextReview, null, 2)}\n`, 'utf-8');
+    await rename(tempFile, reviewFile);
+  }
+
+  async findReviewForComment(id, file) {
+    if (file) {
+      const normalized = normalizeReviewFile(file);
+      return { file: normalized, review: await this.readReviewFile(normalized) };
+    }
+
+    const reviews = await this.readAllReviewFiles();
+    const matches = reviews.filter((review) =>
+      review.comments.some((comment) => comment.id === id),
+    );
+    if (matches.length === 0) {
+      throw new Error(`Comment not found: ${id}`);
+    }
+    if (matches.length > 1) {
+      throw new Error(`Ambiguous comment id without file: ${id}`);
+    }
+
+    return { file: normalizeReviewFile(matches[0].document), review: matches[0] };
+  }
+}

package/server/index.js

@@ -0,0 +1,161 @@
+// server/index.js
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { readFile } from 'fs/promises';
+import { dirname, relative, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { watch } from 'chokidar';
+import { createApp, isMarkdownFile } from './app.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+const distDir = resolve(packageRoot, 'dist');
+
+function validatePort(value) {
+  const port = parseInt(value, 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return port;
+}
+
+async function startServer(app, port, host, maxRetries = 10) {
+  for (let i = 0; i < maxRetries; i++) {
+    const tryPort = port + i;
+    try {
+      await new Promise((resolveServer, reject) => {
+        const server = serve({
+          fetch: app.fetch,
+          port: tryPort,
+          hostname: host,
+        });
+        server.once('listening', () => resolveServer(server));
+        server.once('error', reject);
+      });
+      return tryPort;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        console.log(`Port ${tryPort} is in use, trying ${tryPort + 1}...`);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`Could not find an available port after ${maxRetries} attempts`);
+}
+
+const PORT = validatePort(process.env.API_PORT || 3030);
+const HOST = process.env.API_HOST || '127.0.0.1';
+const MARKDOWN_FILE_PATH = process.env.MARKDOWN_FILE_PATH;
+const BASE_DIR = process.env.BASE_DIR || process.cwd();
+const REVIEW_DIR = process.env.REVIEW_DIR || '.reviews';
+const ACTIVE_FILE = process.env.ACTIVE_FILE || null;
+const READONLY = process.env.READONLY === 'true';
+
+if (HOST === '0.0.0.0') {
+  console.warn('Warning: md-review-server is listening on 0.0.0.0 without authentication.');
+}
+
+const app = new Hono();
+const serverOptions = {
+  markdownFilePath: MARKDOWN_FILE_PATH,
+  baseDir: BASE_DIR,
+  reviewDir: REVIEW_DIR,
+  activeFile: ACTIVE_FILE,
+  readonly: READONLY,
+  port: PORT,
+  host: HOST,
+};
+const apiApp = createApp(serverOptions);
+
+const sseClients = new Set();
+
+app.get('/api/watch', (c) => {
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder();
+      controller.enqueue(encoder.encode('data: {"type":"connected"}\n\n'));
+
+      const client = { controller, encoder };
+      sseClients.add(client);
+
+      c.req.raw.signal.addEventListener('abort', () => {
+        sseClients.delete(client);
+      });
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+});
+
+app.route('/', apiApp);
+app.use('/*', serveStatic({ root: relative(process.cwd(), distDir) || '.' }));
+
+app.get('*', async (c) => {
+  try {
+    const indexPath = resolve(distDir, 'index.html');
+    const html = await readFile(indexPath, 'utf-8');
+    return c.html(html);
+  } catch {
+    return c.text('Not found', 404);
+  }
+});
+
+const SERVER_READY_MESSAGE = 'md-review server started';
+
+const watchTarget = MARKDOWN_FILE_PATH || BASE_DIR;
+const watchBase = MARKDOWN_FILE_PATH ? dirname(MARKDOWN_FILE_PATH) : BASE_DIR;
+const watcher = watch(watchTarget, {
+  ignored: MARKDOWN_FILE_PATH ? undefined : /(^|[/\\])\..|(node_modules|dist)/,
+  persistent: true,
+  ignoreInitial: true,
+  awaitWriteFinish: {
+    stabilityThreshold: 100,
+    pollInterval: 100,
+  },
+});
+
+function broadcastWatchEvent(type, path) {
+  if (!isMarkdownFile(path)) {
+    return;
+  }
+
+  const relativePath = relative(watchBase, path);
+  console.log(`File ${type === 'file-added' ? 'added' : 'changed'}: ${relativePath}`);
+
+  const message = JSON.stringify({
+    type,
+    path: relativePath,
+  });
+
+  sseClients.forEach((client) => {
+    try {
+      client.controller.enqueue(client.encoder.encode(`data: ${message}\n\n`));
+    } catch {
+      sseClients.delete(client);
+    }
+  });
+}
+
+watcher.on('change', (path) => broadcastWatchEvent('file-changed', path));
+watcher.on('add', (path) => broadcastWatchEvent('file-added', path));
+
+startServer(app, PORT, HOST)
+  .then((actualPort) => {
+    serverOptions.port = actualPort;
+    console.log(`API Server running on http://${HOST}:${actualPort}`);
+    console.log(`Watching for file changes in: ${watchTarget}`);
+    console.log(SERVER_READY_MESSAGE);
+  })
+  .catch((err) => {
+    console.error('Failed to start server:', err.message);
+    process.exit(1);
+  });

package/skills/markdown-review-loop/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: markdown-review-loop
+description: 运行面向 Codex 的 Markdown 文档评审循环，提供浏览器可视化预览、选区批注、评论收集、下一版修订稿生成和评论状态跟踪。适用于用户要求可视化评审 Markdown、打开浏览器批注文档、启动评审、继续评审、读取评论、应用评论、生成下一版 Markdown、处理 md-review-server 评论或维护 Markdown review queue 的场景。
+---
+
+# Markdown Review Loop
+
+## 目标
+
+使用本 skill 帮助用户以稳定流程迭代 Markdown 文档：
+
+1. 创建或识别一个版本化 Markdown 草稿。
+2. 启动或复用本地 `md-review-server` 评审会话。
+3. 通过 review HTTP API 读取 `open` 评论；API 不可用时使用粘贴评论作为降级路径。
+4. 根据评论生成下一版 Markdown，不覆盖历史版本。
+5. 汇总每条评论的处理结果，并通过 HTTP API 回写状态。
+
+该流程面向 Codex 协作场景。默认让用户只在浏览器中选区批注，由 Codex 负责启动服务、读取评论、生成新版本和回写状态。
+
+## 启动评审
+
+当用户要求启动 Markdown 评审循环时，按以下步骤处理：
+
+1. 确认源 Markdown 文档。
+2. 如果文档尚不存在，创建版本化文件，例如 `topic.v1.md`。
+3. 保留旧版本。生成 `v2`、`v3` 时不要覆盖 `v1`。
+4. 本地执行可用时，优先尝试静默更新本 skill；更新失败时继续使用当前本地版本：
+
+```bash
+npx -y md-review-server@latest skill update --quiet
+```
+
+5. 自动启动 `md-review-server`。迭代评审优先服务父目录，使新生成的 `v2`、`v3` 可在文件树中直接切换：
+
+```bash
+npx md-review-server path/to/docs --port 3030 --active-file path/to/docs/document.v1.md
+```
+
+6. 如果任务只涉及单文件且目录模式会增加歧义，可以使用文件模式：
+
+```bash
+npx md-review-server path/to/document.v1.md --port 3030
+```
+
+7. 将 `3030` 视为首选起始端口，不视为固定端口。`md-review-server` 会在请求端口被占用时自动尝试后续端口，服务输出会打印实际 URL。后续链接和 API 调用必须使用实际端口。
+8. 只有在确认已有 `md-review-server` 服务正在服务正确文件或父目录时，才复用已有服务。
+9. 回复用户时，用文档文件名作为 Markdown 链接文本，不直接暴露裸 URL。目录模式下链接应包含 `?file=<document>`，便于用户直接打开目标文件。
+
+生成新版本后保持评审面可继续使用：如果父目录已在服务中，提示用户选择新文件；否则为新文件启动新的 review session。
+
+## 读取评论
+
+当用户表示评论已准备好时，按以下顺序读取：
+
+1. 优先使用当前 review HTTP API。先请求 `GET /api/session`，确认服务根目录、active file 和 reviewDir。
+2. 使用服务实际端口读取 `open` 评论：
+
+```bash
+curl 'http://127.0.0.1:<port>/api/comments?file=<document>&status=open'
+```
+
+3. 将 API 评论转换为评审项：
+   - `selectedText` 对应 `quote`
+   - `startLine` / `endLine` 对应源行范围
+   - `startOffset` / `endOffset` 与 `beforeText` / `afterText` 用作长行局部定位
+   - `comment` 对应评审指令
+4. HTTP API 不可用时，要求用户粘贴复制出的评论或 review queue。
+5. 粘贴评论缺少选区文本时，仍可按行号处理；如果评论只要求修改长行中的局部内容且定位有歧义，应要求用户提供精确 quote。
+
+读取评论不会消费评论。只有在下一版 Markdown 已生成并形成处理结论后，才回写评论状态。
+
+## 应用评论
+
+应用评论时按以下规则处理：
+
+1. 修改前读取目标 Markdown 文件。
+2. 创建下一版本文件：
+   - `name.v1.md` -> `name.v2.md`
+   - `name.v2.md` -> `name.v3.md`
+3. 如果源文件未版本化，优先创建 `name.v1.md`；如果该选择不符合用户语境，可创建 `name.reviewed.md` 并说明原因。
+4. 将改动限制在评论指向的范围：
+   - 有 `quote` 时，只修改目标行范围内匹配的选区文本。
+   - `quote` 出现多次时，用行范围和上下文作为定位依据。
+   - 仍存在歧义时，将该评论标记为 `unresolved` 并说明原因。
+   - 无 `quote` 时，按行范围处理。
+5. 除非评论明确要求调整结构，否则保持原文档结构。
+6. 除非评论明确指向事实、引用或代码块，否则保留这些内容。
+7. 不静默丢弃评论。每条评论都必须出现在处理结果中。
+
+## 回写评论状态
+
+生成下一版 Markdown 后，通过 review HTTP API 回写每条已处理评论。优先使用批量 PATCH：
+
+```bash
+curl -X PATCH 'http://127.0.0.1:<port>/api/comments' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "updates": [
+      {
+        "id": "c001",
+        "file": "docs/example.v1.md",
+        "status": "resolved",
+        "targetFile": "docs/example.v2.md",
+        "resolution": "已补充一致性边界说明。"
+      }
+    ]
+  }'
+```
+
+状态使用规则：
+
+- `resolved`：评论已完整处理。
+- `partially_resolved`：评论已部分处理，`resolution` 中说明剩余问题。
+- `unresolved`：评论未处理，`resolution` 中说明阻塞原因。
+- `ignored`：仅在用户或 agent 明确跳过评论时使用。
+
+## 接收粘贴评论
+
+当用户粘贴评论时，将 `md-review-server` API 评论、复制评论和 review queue 条目统一视为评审项。
+
+支持以下格式：
+
+```text
+docs/example.v1.md:L42-L48
+评论内容...
+```
+
+```text
+docs/example.v1.md:L42
+评论内容...
+```
+
+```md
+## C001
+source: docs/example.v1.md:L42-L48
+quote: "长行中的局部选区"
+status: open
+comment: 评论内容...
+```
+
+定位信息缺失时，使用 `quote` 或上下文推断目标位置。推断会改变语义时，将评论标记为 `unresolved` 并要求更清晰的定位信息。
+
+## 维护 Review Queue
+
+当评论超过三条，或用户要求保留可读队列时，创建或更新同级 review queue 文件：
+
+```text
+<document-stem>.review.md
+```
+
+使用 `references/review-template.md` 作为格式参考。队列保持简洁，每条评论使用以下状态之一：
+
+- `open`
+- `resolved`
+- `partially_resolved`
+- `unresolved`
+
+## 完成一轮评审
+
+生成下一版本后，回复内容包含：
+
+1. 新文件路径。
+2. 评论处理摘要。
+3. 未处理评论或关键假设。
+4. 当前 review 链接，以及用户应选择的新文件。只有在用户需要手动启动时才给出命令。
+
+review 链接使用文件名作为链接文本，例如：
+
+```md
+[sample.v2.md](http://127.0.0.1:3030/?file=sample.v2.md)
+```
+
+回复保持简短，使用户可以立即继续下一轮评审。
+
+## md-review-server 说明
+
+`md-review-server` 是本地 Markdown 评审 UI，用作人类批注界面和机器可读评论 API：
+
+```bash
+npx md-review-server docs --port 3030 --active-file docs/example.v1.md
+```
+
+评论不存储在 Markdown 文件中，而是存储在 `.reviews/*.review.json` sidecar 文件中。Codex 读取 `GET /api/comments?status=open`，并通过 `PATCH /api/comments` 写回处理结果。
+
+## 参考文件
+
+创建或更新 review queue 时读取 `references/review-template.md`。

package/skills/markdown-review-loop/VERSION

@@ -0,0 +1 @@
+0.1.0

package/skills/markdown-review-loop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Markdown 评审循环"
+  short_description: "可视化批注、修订并跟踪 Markdown 评审。"
+  default_prompt: "使用 $markdown-review-loop 打开可视化 Markdown 评审，收集批注并生成下一版修订稿。"

package/skills/markdown-review-loop/references/review-template.md

@@ -0,0 +1,42 @@
+# Review Queue 模板
+
+该模板用于 Markdown 评审循环。存在 `quote` 时优先使用 `quote` 定位，因为它比行号更适合处理长行中的局部反馈。
+
+```md
+# Review Queue
+
+document: docs/example.v1.md
+next_version: docs/example.v2.md
+
+## C001
+source: docs/example.v1.md:L42-L48
+quote: "ABase 写入不在 RDS 事务内"
+status: open
+comment: 需要补充 RDS 与 ABase 一致性边界。
+resolution:
+
+## C002
+source: docs/example.v1.md:L77
+quote:
+status: open
+comment: 在该段后补充读取链路时序。
+resolution:
+```
+
+应用评论后更新每条记录：
+
+```md
+## C001
+source: docs/example.v1.md:L42-L48
+quote: "ABase 写入不在 RDS 事务内"
+status: resolved
+comment: 需要补充 RDS 与 ABase 一致性边界。
+resolution: 已补充说明：ABase 写入位于 RDS 事务外，当前实现先写 ABase 内容，再写 RDS 消息元数据。
+```
+
+状态说明：
+
+- `open`：尚未处理。
+- `resolved`：已完整处理。
+- `partially_resolved`：已部分处理，在 `resolution` 中说明剩余问题。
+- `unresolved`：未处理，在 `resolution` 中说明阻塞原因。