@shelken/simple-plannotator 0.1.3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 CNife
+Modifications Copyright (c) 2026 shelken
+
+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,25 @@
+# simple-plannotator
+
+基于浏览器的代码审查和 Markdown 标注。依赖 `@plannotator/pi-extension` 提供 UI 与服务端能力。
+
+初始 fork 自 [CNife/pi-extensions](https://github.com/CNife/pi-extensions)。
+
+## 安装
+
+```bash
+pi install npm:@shelken/simple-plannotator
+```
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/pnr` | 审查本地 git 改动 |
+| `/pna <file.md\|folder/>` | 标注 markdown 文件或目录 |
+| `/pnl` | 标注最近一条 assistant 消息 |
+
+## 验证
+
+```bash
+bun --filter @shelken/simple-plannotator test
+```

package/index.ts

@@ -0,0 +1,257 @@
+/**
+ * pn — Minimal Plannotator for Pi
+ *
+ * Three slash commands:
+ *   /pnr        — Open browser-based code review for local git changes
+ *   /pna <path> — Open browser-based annotation for a markdown file or folder
+ *   /pnl        — Annotate the last assistant message
+ *
+ * Depends on @plannotator/pi-extension for server infrastructure and browser UIs.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+// 启动时不拉 plannotator 整图（~500ms+）；命令触发时再加载。
+type PlannotatorBrowser =
+  typeof import("@plannotator/pi-extension/plannotator-browser");
+
+let browserPromise: Promise<PlannotatorBrowser> | undefined;
+function loadBrowser(): Promise<PlannotatorBrowser> {
+  return (browserPromise ??= import(
+    "@plannotator/pi-extension/plannotator-browser"
+  ));
+}
+
+/** Shared result handling for all browser session decisions. */
+function handleDecision(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  label: string,
+  result: { exit?: boolean; approved?: boolean; feedback?: string },
+): void {
+  if (result.exit) {
+    ctx.ui.notify(`${label} closed.`, "info");
+  } else if (result.approved) {
+    ctx.ui.notify(`${label} approved.`, "info");
+  } else if (result.feedback) {
+    pi.sendUserMessage(result.feedback, { deliverAs: "followUp" });
+  } else {
+    ctx.ui.notify(`${label} closed (no feedback).`, "info");
+  }
+}
+
+export default function pn(pi: ExtensionAPI): void {
+  // ── /pnr: Code Review ────────────────────────────────────────────
+
+  pi.registerCommand("pnr", {
+    description: "Open code review for local git changes",
+    handler: async (_args, ctx) => {
+      const {
+        hasReviewBrowserHtml,
+        startCodeReviewBrowserSession,
+        getStartupErrorMessage,
+      } = await loadBrowser();
+
+      if (!hasReviewBrowserHtml()) {
+        ctx.ui.notify(
+          "Code review UI not available. Rebuild @plannotator/pi-extension.",
+          "error",
+        );
+        return;
+      }
+
+      try {
+        const session = await startCodeReviewBrowserSession(ctx, {});
+        ctx.ui.notify("Code review opened in browser.", "info");
+
+        void session.waitForDecision().then(
+          (result) => handleDecision(pi, ctx, "Code review", result),
+          (err) =>
+            ctx.ui.notify(
+              `Code review failed: ${getStartupErrorMessage(err)}`,
+              "error",
+            ),
+        );
+      } catch (err) {
+        ctx.ui.notify(
+          `Failed to start code review: ${getStartupErrorMessage(err)}`,
+          "error",
+        );
+      }
+    },
+  });
+
+  // ── /pna: Annotate ───────────────────────────────────────────────
+
+  pi.registerCommand("pna", {
+    description: "Open annotation UI for a markdown file or folder",
+    handler: async (args, ctx) => {
+      const normalized = normalizeUserPath(args ?? "");
+      if (!normalized) {
+        ctx.ui.notify("Usage: /pna <file.md | folder/>", "error");
+        return;
+      }
+
+      const {
+        hasPlanBrowserHtml,
+        startMarkdownAnnotationSession,
+        getStartupErrorMessage,
+      } = await loadBrowser();
+
+      if (!hasPlanBrowserHtml()) {
+        ctx.ui.notify(
+          "Annotation UI not available. Rebuild @plannotator/pi-extension.",
+          "error",
+        );
+        return;
+      }
+
+      const absPath = isAbsolute(normalized)
+        ? normalized
+        : resolve(ctx.cwd, normalized);
+
+      if (!existsSync(absPath)) {
+        ctx.ui.notify(`Not found: ${absPath}`, "error");
+        return;
+      }
+
+      try {
+        const isDir = statSync(absPath).isDirectory();
+        let session: Awaited<
+          ReturnType<typeof startMarkdownAnnotationSession>
+        >;
+
+        if (isDir) {
+          if (!scanMarkdownFiles(absPath)) {
+            ctx.ui.notify(`No markdown files found in ${normalized}`, "error");
+            return;
+          }
+          ctx.ui.notify(
+            `Opening annotation UI for folder ${normalized}...`,
+            "info",
+          );
+          session = await startMarkdownAnnotationSession(
+            ctx,
+            absPath,
+            "",
+            "annotate-folder",
+            absPath,
+          );
+        } else {
+          const content = readFileSync(absPath, "utf-8");
+          ctx.ui.notify(`Opening annotation UI for ${normalized}...`, "info");
+          session = await startMarkdownAnnotationSession(
+            ctx,
+            absPath,
+            content,
+            "annotate",
+          );
+        }
+
+        void session.waitForDecision().then(
+          (result) => handleDecision(pi, ctx, "Annotation", result),
+          (err) =>
+            ctx.ui.notify(
+              `Annotation failed: ${getStartupErrorMessage(err)}`,
+              "error",
+            ),
+        );
+      } catch (err) {
+        ctx.ui.notify(
+          `Failed to open UI: ${getStartupErrorMessage(err)}`,
+          "error",
+        );
+      }
+    },
+  });
+
+  // ── /pnl: Annotate Last Message ──────────────────────────────
+
+  pi.registerCommand("pnl", {
+    description: "Annotate the last assistant message",
+    handler: async (_args, ctx) => {
+      const {
+        hasPlanBrowserHtml,
+        getLastAssistantMessageText,
+        startLastMessageAnnotationSession,
+        getStartupErrorMessage,
+      } = await loadBrowser();
+
+      if (!hasPlanBrowserHtml()) {
+        ctx.ui.notify(
+          "Annotation UI not available. Rebuild @plannotator/pi-extension.",
+          "error",
+        );
+        return;
+      }
+
+      const lastText = getLastAssistantMessageText(ctx);
+      if (!lastText) {
+        ctx.ui.notify("No assistant message found in session.", "error");
+        return;
+      }
+
+      try {
+        ctx.ui.notify("Opening annotation UI for last message...", "info");
+        const session = await startLastMessageAnnotationSession(ctx, lastText);
+
+        void session.waitForDecision().then(
+          (result) => handleDecision(pi, ctx, "Annotation", result),
+          (err) =>
+            ctx.ui.notify(
+              `Annotation failed: ${getStartupErrorMessage(err)}`,
+              "error",
+            ),
+        );
+      } catch (err) {
+        ctx.ui.notify(
+          `Failed to open UI: ${getStartupErrorMessage(err)}`,
+          "error",
+        );
+      }
+    },
+  });
+}
+
+/** Normalize a user-provided path: strip @ prefix, quotes, expand ~ to home directory. */
+export function normalizeUserPath(raw: string): string {
+  const trimmed = raw.trim();
+  const unquoted = trimmed.replace(/^["']|["']$/g, "");
+  // Strip @ prefix from file references (e.g. @file.md -> file.md)
+  const stripped = unquoted.startsWith("@") ? unquoted.slice(1) : unquoted;
+  return expandHomePath(stripped);
+}
+
+export function expandHomePath(input: string): string {
+  const home = homedir();
+  if (input === "~") return home;
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return home + input.slice(1);
+  }
+  return input;
+}
+
+function scanMarkdownFiles(dirPath: string, depth = 0): boolean {
+  if (depth > 8) return false;
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const fullPath = resolve(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (scanMarkdownFiles(fullPath, depth + 1)) return true;
+      } else if (/\.mdx?$/i.test(entry.name)) {
+        return true;
+      }
+    }
+  } catch {
+    /* permission denied, skip */
+  }
+  return false;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@shelken/simple-plannotator",
+  "version": "0.1.3",
+  "description": "基于浏览器的代码审查和 Markdown 标注（/pnr /pna /pnl）",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "plannotator-browser.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shelken/pi-extensions.git",
+    "directory": "extensions/simple-plannotator"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": [
+    "pi-package",
+    "plannotator",
+    "code-review"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@plannotator/pi-extension": "^0.23.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/plannotator-browser.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 上游 @plannotator/pi-extension 分发的是原始 .ts 源文件，
+ * 其内部 import 了大量未在 node_modules 中声明的 SDK 包，
+ * 导致 TypeScript 递归检查时报 module-not-found 错误。
+ *
+ * 这个 .d.ts 和上游源文件共用一个 module 名，TypeScript 会选择
+ * 声明文件而非解析实际源文件，从而阻断递归类型检查。
+ *
+ * 仅声明 simple-plannotator 实际使用的 API。
+ */
+
+declare module "@plannotator/pi-extension/plannotator-browser" {
+  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+  // ── 基础类型 ──────────────────────────────────────
+
+  export type AnnotateMode =
+    | "annotate"
+    | "annotate-folder"
+    | "annotate-last";
+
+  export interface BrowserDecisionSession<T> {
+    url: string;
+    waitForDecision: () => Promise<T>;
+    stop: () => void;
+  }
+
+  // ── 纯函数（无递归依赖） ──────────────────────────
+
+  export function getLastAssistantMessageText(
+    ctx: ExtensionContext,
+  ): string | null;
+
+  export function getStartupErrorMessage(err: unknown): string;
+
+  export function hasPlanBrowserHtml(): boolean;
+  export function hasReviewBrowserHtml(): boolean;
+
+  // ── 浏览器 session 启动函数 ───────────────────────
+
+  export function startCodeReviewBrowserSession(
+    ctx: ExtensionContext,
+    options?: {
+      cwd?: string;
+      defaultBranch?: string;
+      diffType?: string;
+      prUrl?: string;
+      vcsType?: string;
+      useLocal?: boolean;
+    },
+  ): Promise<
+    BrowserDecisionSession<{
+      approved: boolean;
+      feedback?: string;
+      annotations?: unknown[];
+      agentSwitch?: string;
+      exit?: boolean;
+    }>
+  >;
+
+  export function startMarkdownAnnotationSession(
+    ctx: ExtensionContext,
+    filePath: string,
+    markdown: string,
+    mode: AnnotateMode,
+    folderPath?: string,
+    sourceInfo?: string,
+    sourceConverted?: boolean,
+    gate?: boolean,
+    rawHtml?: string,
+    renderHtml?: boolean,
+    recentMessages?: {
+      messageId: string;
+      text: string;
+      timestamp?: string;
+    }[],
+  ): Promise<
+    BrowserDecisionSession<{
+      feedback: string;
+      exit?: boolean;
+      approved?: boolean;
+      selectedMessageId?: string;
+      feedbackScope?: "message" | "messages";
+    }>
+  >;
+
+  export function startLastMessageAnnotationSession(
+    ctx: ExtensionContext,
+    lastText: string,
+    gate?: boolean,
+    recentMessages?: {
+      messageId: string;
+      text: string;
+      timestamp?: string;
+    }[],
+  ): Promise<
+    BrowserDecisionSession<{
+      feedback: string;
+      exit?: boolean;
+      approved?: boolean;
+      selectedMessageId?: string;
+      feedbackScope?: "message" | "messages";
+    }>
+  >;
+}