@trim21/personal-pi-extensions 0.1.20261011230807 → 0.1.20261012000609

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.20261011230807",
+  "version": "0.1.20261012000609",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/codemode/declarations.ts

@@ -26,7 +26,28 @@ function propertyName(name: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
 }
 
-function renderType(schema: unknown, indent: string): string {
+/** schema 自带的字段说明：没有或为空时不渲染注释。 */
+function descriptionOf(schema: unknown): string {
+  if (!isRecord(schema) || typeof schema.description !== "string") {
+    return "";
+  }
+  return schema.description.trim();
+}
+
+/** 字段注释：单行用 `//`，多行才用 JSDoc；缩进与它下面的属性对齐。 */
+function fieldComment(description: string, indent: string): string {
+  const lines = description.split("\n").map((line) => line.trim());
+  if (lines.length === 1) {
+    return `${indent}// ${lines[0]}`;
+  }
+  return [
+    `${indent}/**`,
+    ...lines.map((line) => (line === "" ? `${indent} *` : `${indent} * ${line}`)),
+    `${indent} */`,
+  ].join("\n");
+}
+
+export function renderType(schema: unknown, indent: string): string {
   if (!isRecord(schema)) {
     return "unknown";
   }
@@ -67,7 +88,11 @@ function renderType(schema: unknown, indent: string): string {
       }
       const lines = entries.map(([key, value]) => {
         const optional = required.has(key) ? "" : "?";
-        return `${indent}  ${propertyName(key)}${optional}: ${renderType(value, `${indent}  `)};`;
+        const property = `${indent}  ${propertyName(key)}${optional}: ${renderType(value, `${indent}  `)};`;
+        const description = descriptionOf(value);
+        return description === ""
+          ? property
+          : `${fieldComment(description, `${indent}  `)}\n${property}`;
       });
       return `{\n${lines.join("\n")}\n${indent}}`;
     }
@@ -82,12 +107,24 @@ function renderType(schema: unknown, indent: string): string {
  * 返回类型取自工具声明的输出结构，未声明就是文本（`string`）。
  */
 function renderOverload(tool: ToolLike): string {
-  const summary = tool.description?.split("\n", 1)[0]?.trim();
-  const doc = summary ? `/** ${summary} */\n` : "";
+  const description = tool.description?.trim();
+  const doc = description ? `${docComment(description)}\n` : "";
   const output = renderType(tool.structuredSchema, "");
   return `${doc}declare function call(name: ${JSON.stringify(tool.name)}, args: ${renderType(tool.parameters, "")}): Promise<${output}>;`;
 }
 
+/**
+ * 工具的 JSDoc 注释：description 的每一行都要进描述——只取首行会让工具作者写的说明
+ * 在 codemode 里凭空消失。多行按 JSDoc 缩进渲染，单行仍是一行注释。
+ */
+function docComment(description: string): string {
+  const lines = description.split("\n").map((line) => line.trim());
+  if (lines.length === 1) {
+    return `/** ${lines[0]} */`;
+  }
+  return ["/**", ...lines.map((line) => (line === "" ? " *" : ` * ${line}`)), " */"].join("\n");
+}
+
 /** 给脚本用的工具清单（名字 + 说明）。 */
 export function toScriptTools(tools: readonly ToolLike[]): ScriptTool[] {
   return tools.map((tool) => ({

package/src/gh/tools/download-release-assets.ts

@@ -197,9 +197,8 @@ export function addDownloadReleaseAssetsTool(gh: GhClient, bus: ToolBus) {
         "Download a GitHub release's assets (or its source archive) into " +
         "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the GitHub credentials, " +
         "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
-        "Files already in that directory are kept, never re-fetched. The result is the JSON " +
-        "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
-        "directory; file contents are not echoed. Read the entries you need from `path`.",
+        "Files already in that directory are kept, never re-fetched. The result lists everything " +
+        "now in the directory; file contents are not echoed. Read the entries you need from `path`.",
       promptSnippet: "Download GitHub release assets",
       parameters: Type.Object({
         repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),

package/src/gh/tools/get-workflow-jobs.ts

@@ -41,7 +41,7 @@ export function addGetWorkflowJobsTool(gh: GhClient, bus: ToolBus) {
       name: "get-github-workflow-jobs",
       label: "GitHub Workflow Jobs",
       description:
-        "Get every job of a workflow run as JSON {total_count, jobs:[{id, run_id, run_url, name, status, conclusion, html_url, steps:[{name, number, status, conclusion, started_at}]}]}. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
+        "Get every job of a workflow run. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
       promptSnippet: "Get GitHub workflow run jobs",
       parameters: Type.Object({
         run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),

package/src/gh/tools/list-issues.ts

@@ -38,7 +38,7 @@ export function addListIssuesTool(gh: GhClient, bus: ToolBus) {
       name: "list-github-issues",
       label: "GitHub Issues List",
       description:
-        'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones. Set fields to choose the columns of each result row.',
+        'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones.',
       promptSnippet: "List or search GitHub issues",
       parameters: listFilterParameters("issue"),
       structuredSchema: ghHitListPayloadSchema,

package/src/gh/tools/list-prs.ts

@@ -38,7 +38,7 @@ export function addListPrsTool(gh: GhClient, bus: ToolBus) {
       name: "list-github-prs",
       label: "GitHub PRs List",
       description:
-        'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden. Set fields to choose the columns of each result row.',
+        'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden.',
       promptSnippet: "List or search GitHub PRs",
       parameters: listFilterParameters("pr"),
       structuredSchema: ghHitListPayloadSchema,

package/src/gh/tools/list-releases.ts

@@ -17,8 +17,7 @@ export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
     defineStructuredTool({
       name: "list-github-releases",
       label: "GitHub Releases List",
-      description:
-        "List GitHub releases. Each row is: tag, flags (latest/prerelease/draft), published date, name.",
+      description: "List GitHub releases.",
       promptSnippet: "List GitHub releases",
       parameters: Type.Object({
         repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),

package/src/gh/tools/list-workflow-runs.ts

@@ -17,8 +17,7 @@ export function addListWorkflowRunsTool(gh: GhClient, bus: ToolBus) {
     defineStructuredTool({
       name: "list-github-workflow-runs",
       label: "GitHub Workflow Runs",
-      description:
-        "List GitHub Actions workflow runs. Each row is: id, status, conclusion, workflow, branch, event, created date, url.",
+      description: "List GitHub Actions workflow runs.",
       promptSnippet: "List GitHub workflow runs",
       parameters: Type.Object({
         repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),

package/src/gh/tools/read-ci-logs.ts

@@ -414,8 +414,9 @@ export function addReadCiLogsTool(gh: GhClient, bus: ToolBus) {
       name: "read-github-ci-logs",
       label: "GitHub CI Logs",
       description:
-        "Download one GitHub Actions job's CI log by job ID and index its steps. Returns JSON {name, id, status, conclusion, log_file, steps:[{number, name, conclusion, start_line?, end_line?}]}: `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file. Read the content out of the file yourself (read/grep with offset/limit) — it is not echoed back. Get the job IDs from get-github-workflow-jobs, then call this once per job you need." +
-        " Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
+        "Download one GitHub Actions job's CI log by job ID and index its steps. `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file." +
+        " The log text is not echoed back: `log_file` is the only copy, so read the parts you need out of it with Read/Grep — e.g. `Read(log_file, offset=start_line, limit=end_line - start_line + 1)` for one step's block, or grep for a pattern. Do not slice or filter the returned JSON to reconstruct log text: it carries only the step index, not the log. Fetch each job once; re-reading that file is how you get every further part of the log." +
+        " Get the job IDs from get-github-workflow-jobs, then call this once per job you need. Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
       promptSnippet: "Read GitHub CI logs",
       parameters: Type.Object({
         job_id: Type.Union([Type.Number(), Type.String()], {

package/src/gh/tools/read-pr-status.ts

@@ -76,7 +76,7 @@ export function addReadPrStatusTool(gh: GhClient, bus: ToolBus) {
       name: "read-github-pr-status",
       label: "GitHub PR Status",
       description:
-        "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, suite_id, url}]}. `bucket` is pass / fail / pending / skipped / action_required; `action_required` means the workflow is waiting for a maintainer's approval (a fork PR's first run) and has created no check run yet, so it is listed from its check suite and named after its workflow run. Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take; `suite_id` groups the checks of one suite. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
+        "Get the current checks of a pull request's head commit. Each check's `bucket` is pass / fail / pending / skipped / action_required; `action_required` means the workflow is waiting for a maintainer's approval (a fork PR's first run) and has created no check run yet, so it is listed from its check suite and named after its workflow run. Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take; `suite_id` groups the checks of one suite. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
       promptSnippet: "Read GitHub PR status checks",
       parameters: Type.Object({
         number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),