pi-project-gate 1.1.0 → 1.2.0

package/AGENTS.md

@@ -1,12 +1,15 @@
 # Project Gate — Agent Usage Guide
 
-> You are an AI agent. Use project-gate tools to validate, start, and track work. Never start work on an issue without checking it first.
+> You are an AI agent. Use project-gate tools to manage issues, validate work readiness, and track progress.
 
-## Golden Rule
+## Golden Rules
 
 > **⚠️ DO NOT start work on an issue without calling `project_check()` first.**
 > This ensures the issue has required sections, no blockers, and you haven't exceeded WIP limits.
 
+> **📝 Use `project_create_issue()` to create issues — never use raw `curl` or the browser.**
+> This ensures issue templates are validated and governance gates are enforced.
+
 ## Workflow
 
 ```
@@ -74,6 +77,66 @@ Requires #789
 
 If any dependency is still open, `project_start()` blocks work.
 
+## Managing Issues (CRUD)
+
+### Create an Issue
+
+Always use `project_create_issue()` instead of raw curl or browser:
+
+```
+project_create_issue(
+  title="Add dark mode toggle",
+  body="## Problem\nNo dark mode support.\n\n## Proposed Solution\nAdd a toggle in settings.\n\n## Acceptance Criteria\n- [ ] Toggle switches themes\n- [ ] Persists preference",
+  labels=["enhancement", "frontend"],
+  milestone="v2.0"
+)
+```
+
+The body is validated against required sections (configurable in `.projectrc.yml`).
+
+### Update an Issue
+
+Modify any aspect of an existing issue:
+
+```
+project_update_issue(
+  issue_id="42",
+  state="closed"
+)
+
+project_update_issue(
+  issue_id="42",
+  title="Updated title",
+  labels=["bug", "high-priority"],
+  assignee="nandal"
+)
+```
+
+Only the fields you provide are changed. Omitted fields are left as-is.
+
+### List/Search Issues
+
+Find issues with flexible filters:
+
+```
+project_list_issues()                              ← all open issues
+project_list_issues(state="closed")                ← closed issues
+project_list_issues(labels="bug,high-priority")    ← by labels
+project_list_issues(milestone="v2.0")              ← by milestone
+project_list_issues(assignee="nandal")             ← by assignee
+project_list_issues(q="dark mode")                 ← text search
+project_list_issues(state="open", limit=50)        ← pagination
+```
+
+### Get Issue Details
+
+Fetch full issue info including comments:
+
+```
+project_get_issue(issue_id="42")                   ← full details + comments
+project_get_issue(issue_id="42", include_comments=false)  ← body only
+```
+
 ## Release Notes
 
 Generate release notes from conventional commits:
@@ -88,7 +151,9 @@ project_release_notes(from="v1.0.0", to="v1.1.0") ← between two tags
 
 | Problem | Solution |
 |---|---|
-| Issue missing sections | Add required sections to the issue body |
+| Issue missing sections | Add required sections to the issue body, or use `project_update_issue()` |
 | WIP limit reached | Close or merge an existing PR first |
 | Blocked by dependency | Help resolve the blocking issue or wait for it to be merged |
 | No complexity label | Add `Complexity: small/medium/large/epic` to issue body |
+| Cannot find an issue | Use `project_list_issues(q="keyword")` to search |
+| Need to close an issue | Use `project_update_issue(issue_id="42", state="closed")` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-project-gate",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Project orchestration gate for AI agents \u2014 structured issues, WIP limits, dependency blocking, and auto-generated release notes.",
   "keywords": [
     "pi-package",

package/src/__tests__/project-gate.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import { loadConfig, DEFAULT_CONFIG } from "../config";
 import { validateIssueTemplate, parseDependencies, parseConventionalCommits } from "../validate";
 import { exec } from "../helpers";
+import { createTool, updateTool, listTool, getTool } from "../tools/issues";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -184,3 +185,116 @@ describe("exec helper", () => {
     expect(r.ok).toBe(false);
   });
 });
+
+// ═══════════════════════════════════════
+// New config fields for issue CRUD
+// ═══════════════════════════════════════
+describe("issue config defaults", () => {
+  it("has default issue labels", () => {
+    expect(DEFAULT_CONFIG.issueLabels).toContain("enhancement");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("bug");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("documentation");
+    expect(DEFAULT_CONFIG.issueLabels).toContain("question");
+  });
+
+  it("has create flags defaulting to false", () => {
+    expect(DEFAULT_CONFIG.issueCreateRequireComplexity).toBe(false);
+    expect(DEFAULT_CONFIG.issueCreateRequireArea).toBe(false);
+  });
+
+  it("parses issueLabels from projectrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      'issueLabels: "enhancement,bug,frontend,backend"',
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.issueLabels).toEqual(["enhancement", "bug", "frontend", "backend"]);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses issueCreateRequire flags", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      "issueCreateRequireComplexity: true",
+      "issueCreateRequireArea: true",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.issueCreateRequireComplexity).toBe(true);
+    expect(config.issueCreateRequireArea).toBe(true);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Tool definitions
+// ═══════════════════════════════════════
+describe("issue CRUD tool definitions", () => {
+  it("createTool has proper metadata", () => {
+    expect(createTool.name).toBe("project_create_issue");
+    expect(createTool.label).toBe("Create Issue");
+    expect(createTool.description).toContain("Create a new issue");
+    expect(createTool.parameters).toBeDefined();
+  });
+
+  it("updateTool has proper metadata", () => {
+    expect(updateTool.name).toBe("project_update_issue");
+    expect(updateTool.label).toBe("Update Issue");
+    expect(updateTool.description).toContain("Update an existing issue");
+    // issue_id is required, all other fields optional
+    const props = (updateTool.parameters as any)?.properties;
+    expect(props["issue_id"]).toBeDefined();
+    expect(props["title"]).toBeDefined();
+    expect(props["body"]).toBeDefined();
+    expect(props["state"]).toBeDefined();
+    expect(props["labels"]).toBeDefined();
+    expect(props["milestone"]).toBeDefined();
+    expect(props["assignee"]).toBeDefined();
+  });
+
+  it("listTool has proper metadata", () => {
+    expect(listTool.name).toBe("project_list_issues");
+    expect(listTool.label).toBe("List Issues");
+    expect(listTool.description).toContain("Search and list issues");
+    const props = (listTool.parameters as any)?.properties;
+    expect(props["state"]).toBeDefined();
+    expect(props["labels"]).toBeDefined();
+    expect(props["milestone"]).toBeDefined();
+    expect(props["assignee"]).toBeDefined();
+    expect(props["q"]).toBeDefined();
+    expect(props["limit"]).toBeDefined();
+    expect(props["page"]).toBeDefined();
+  });
+
+  it("getTool has proper metadata", () => {
+    expect(getTool.name).toBe("project_get_issue");
+    expect(getTool.label).toBe("Get Issue");
+    expect(getTool.description).toContain("full details");
+    const props = (getTool.parameters as any)?.properties;
+    expect(props["issue_id"]).toBeDefined();
+    expect(props["include_comments"]).toBeDefined();
+  });
+});
+
+// ═══════════════════════════════════════
+// Issue body validation (reused by create/update)
+// ═══════════════════════════════════════
+describe("issue create body validation", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
+  };
+
+  it("accepts a well-formed issue body", () => {
+    const body = "## Problem\nBug exists\n\n## Proposed Solution\nFix it\n\n## Acceptance Criteria\n- [ ] Done";
+    expect(validateIssueTemplate(body, config).ok).toBe(true);
+  });
+
+  it("rejects body missing required sections", () => {
+    const body = "## Problem\nBug exists";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/config.ts

@@ -6,6 +6,9 @@ export interface ProjectConfig {
   requiredSections: string[];
   complexityLevels: string[];
   areas: string[];
+  issueLabels: string[];
+  issueCreateRequireComplexity: boolean;
+  issueCreateRequireArea: boolean;
   releaseNoteGroups: string[];
   releaseNoteIncludeHashes: boolean;
   dependencyPattern: string;
@@ -16,6 +19,9 @@ export const DEFAULT_CONFIG: ProjectConfig = {
   requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
   complexityLevels: ["trivial", "small", "medium", "large", "epic"],
   areas: [],
+  issueLabels: ["enhancement", "bug", "documentation", "question"],
+  issueCreateRequireComplexity: false,
+  issueCreateRequireArea: false,
   releaseNoteGroups: ["feat", "fix", "perf", "refactor", "chore", "docs", "test", "ci", "build"],
   releaseNoteIncludeHashes: false,
   dependencyPattern: "(?:Depends on|Blocked by|Requires)\\s+#(\\d+)",
@@ -40,6 +46,9 @@ export function loadConfig(cwd: string): ProjectConfig {
       requiredSections: (result["requiredSections"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.requiredSections,
       complexityLevels: (result["complexityLevels"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.complexityLevels,
       areas: (result["areas"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || [],
+      issueLabels: (result["issueLabels"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.issueLabels,
+      issueCreateRequireComplexity: result["issueCreateRequireComplexity"] === "true",
+      issueCreateRequireArea: result["issueCreateRequireArea"] === "true",
       releaseNoteGroups: (result["releaseNoteGroups"] as string)?.split(",").map(s => s.trim()).filter(Boolean) || DEFAULT_CONFIG.releaseNoteGroups,
       releaseNoteIncludeHashes: result["releaseNoteIncludeHashes"] === "true",
       dependencyPattern: (result["dependencyPattern"] as string) || DEFAULT_CONFIG.dependencyPattern,

package/src/index.ts

@@ -1,16 +1,22 @@
 /**
  * pi-project-gate — Project Orchestration Gate
  *
- * Tools: project_check, project_start, project_status, project_release_notes
+ * Tools: project_check, project_start, project_status, project_release_notes,
+ *        project_create_issue, project_update_issue, project_list_issues, project_get_issue
  * Config: .projectrc.yml
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { checkTool, startTool, statusTool, releaseTool } from "./tools/project";
+import { createTool, updateTool, listTool, getTool } from "./tools/issues";
 
 export default function (pi: ExtensionAPI) {
   pi.registerTool(checkTool);
   pi.registerTool(startTool);
   pi.registerTool(statusTool);
   pi.registerTool(releaseTool);
+  pi.registerTool(createTool);
+  pi.registerTool(updateTool);
+  pi.registerTool(listTool);
+  pi.registerTool(getTool);
   pi.on("session_shutdown", () => { delete (globalThis as any).__project_issueId; });
 }

package/src/tools/issues.ts

@@ -0,0 +1,328 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { resolveGitea, giteaApi } from "../helpers";
+import { validateIssueTemplate } from "../validate";
+
+// ─── Create Issue ───────────────────────────────────────────────────────────────
+
+export const createTool = {
+  name: "project_create_issue" as const,
+  label: "Create Issue",
+  description:
+    "Create a new issue with structured body. Validates required template sections before creation.",
+  parameters: Type.Object({
+    title: Type.String({ description: "Issue title" }),
+    body: Type.String({ description: "Issue body in markdown (must include required sections)" }),
+    labels: Type.Optional(Type.Array(Type.String({}), { description: "Labels to apply" })),
+    milestone: Type.Optional(Type.String({ description: "Milestone title or ID" })),
+    assignee: Type.Optional(Type.String({ description: "Username to assign" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const opts = resolveGitea(ctx.cwd);
+
+    // Validate template
+    const tpl = validateIssueTemplate(params.body, config);
+    if (!tpl.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Issue body is missing required sections:\n  - ${tpl.missingSections.join("\n  - ")}`,
+          },
+        ],
+        isError: true,
+        details: { missingSections: tpl.missingSections },
+      };
+    }
+
+    // Detect complexity from body
+    const complexity = config.complexityLevels.find((l) =>
+      params.body.toLowerCase().includes(l.toLowerCase()),
+    );
+
+    // Build payload
+    const payload: Record<string, unknown> = {
+      title: params.title,
+      body: params.body,
+    };
+    if (params.labels && params.labels.length > 0) payload.labels = params.labels;
+    if (params.milestone) payload.milestone = params.milestone;
+    if (params.assignee) payload.assignee = params.assignee;
+
+    const r = giteaApi("/issues", "POST", payload, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to create issue: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const lines = [
+      `✅ Issue #${issue.number} created: "${issue.title}"`,
+      `   URL: ${issue.html_url || `http://127.0.0.1:3001/${opts.repo}/issues/${issue.number}`}`,
+    ];
+    if (complexity) lines.push(`   Complexity: ${complexity}`);
+    if (params.labels?.length) lines.push(`   Labels: ${params.labels.join(", ")}`);
+    if (params.milestone) lines.push(`   Milestone: ${params.milestone}`);
+    if (params.assignee) lines.push(`   Assignee: ${params.assignee}`);
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { issueId: issue.number, url: issue.html_url },
+    };
+  },
+};
+
+// ─── Update Issue ───────────────────────────────────────────────────────────────
+
+export const updateTool = {
+  name: "project_update_issue" as const,
+  label: "Update Issue",
+  description:
+    "Update an existing issue — title, body, state (open/closed), labels, milestone, or assignee.",
+  parameters: Type.Object({
+    issue_id: Type.String({ description: "Issue number or ID" }),
+    title: Type.Optional(Type.String({ description: "New title" })),
+    body: Type.Optional(Type.String({ description: "New body in markdown" })),
+    state: Type.Optional(
+      Type.String({ description: 'State: "open" or "closed"' }),
+    ),
+    labels: Type.Optional(Type.Array(Type.String({}), { description: "Replacement labels" })),
+    milestone: Type.Optional(Type.String({ description: "Milestone title or ID, or null to remove" })),
+    assignee: Type.Optional(Type.String({ description: "Username to assign, or empty string to unassign" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const opts = resolveGitea(ctx.cwd);
+    const issueId = String(params.issue_id).replace(/^#/, "");
+
+    // Fetch current issue to verify it exists
+    const current = giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!current.ok || !current.data) {
+      return {
+        content: [{ type: "text", text: `❌ Issue #${issueId} not found.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    // Validate body template if body is being updated
+    if (params.body) {
+      const tpl = validateIssueTemplate(params.body, config);
+      if (!tpl.ok) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ Updated body is missing required sections:\n  - ${tpl.missingSections.join("\n  - ")}`,
+            },
+          ],
+          isError: true,
+          details: { missingSections: tpl.missingSections },
+        };
+      }
+    }
+
+    // Build patch payload — only include fields that were provided
+    const payload: Record<string, unknown> = {};
+    if (params.title !== undefined) payload.title = params.title;
+    if (params.body !== undefined) payload.body = params.body;
+    if (params.state !== undefined) payload.state = params.state;
+    if (params.labels !== undefined) payload.labels = params.labels;
+    if (params.milestone !== undefined) payload.milestone = params.milestone;
+    if (params.assignee !== undefined) payload.assignee = params.assignee;
+
+    if (Object.keys(payload).length === 0) {
+      return {
+        content: [{ type: "text", text: "⚠️ No fields to update." }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const r = giteaApi(`/issues/${issueId}`, "PATCH", payload, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to update issue: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const changes: string[] = [];
+    if (params.title !== undefined) changes.push("title");
+    if (params.body !== undefined) changes.push("body");
+    if (params.state !== undefined) changes.push(`state → ${params.state}`);
+    if (params.labels !== undefined) changes.push("labels");
+    if (params.milestone !== undefined) changes.push("milestone");
+    if (params.assignee !== undefined) changes.push("assignee");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `✅ Issue #${issueId} updated: "${issue.title}"\n   Changed: ${changes.join(", ")}`,
+        },
+      ],
+      details: { issueId, changed: changes },
+    };
+  },
+};
+
+// ─── List Issues ────────────────────────────────────────────────────────────────
+
+export const listTool = {
+  name: "project_list_issues" as const,
+  label: "List Issues",
+  description:
+    "Search and list issues with optional filters: state, labels, milestone, assignee, keyword, and pagination.",
+  parameters: Type.Object({
+    state: Type.Optional(Type.String({ description: 'Filter by state: "open" or "closed" (default: open)' })),
+    labels: Type.Optional(Type.String({ description: "Comma-separated label names" })),
+    milestone: Type.Optional(Type.String({ description: "Filter by milestone title" })),
+    assignee: Type.Optional(Type.String({ description: "Filter by assignee username" })),
+    q: Type.Optional(Type.String({ description: "Full-text search query (searches title + body)" })),
+    limit: Type.Optional(Type.Number({ description: "Max issues to return (default: 20, max: 100)" })),
+    page: Type.Optional(Type.Number({ description: "Page number (default: 1)" })),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    const queryParts: string[] = [];
+    queryParts.push(`state=${params.state || "open"}`);
+    queryParts.push(`limit=${Math.min(params.limit || 20, 100)}`);
+    queryParts.push(`page=${params.page || 1}`);
+    if (params.labels) queryParts.push(`labels=${encodeURIComponent(params.labels)}`);
+    if (params.milestone) queryParts.push(`milestone=${encodeURIComponent(params.milestone)}`);
+    if (params.assignee) queryParts.push(`assignee=${encodeURIComponent(params.assignee)}`);
+    if (params.q) queryParts.push(`q=${encodeURIComponent(params.q)}`);
+
+    const r = giteaApi(`/issues?${queryParts.join("&")}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to list issues: ${r.error || "unknown error"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issues = Array.isArray(r.data) ? r.data : [];
+    if (issues.length === 0) {
+      return {
+        content: [{ type: "text", text: "No issues found." }],
+        details: { count: 0 },
+      };
+    }
+
+    const lines = [`📋 Issues (${issues.length} found)`];
+    if (params.q) lines.push(`   Search: "${params.q}"`);
+    lines.push("");
+
+    for (const issue of issues as any[]) {
+      const labels =
+        issue.labels && issue.labels.length > 0
+          ? ` [${issue.labels.map((l: any) => l.name).join(", ")}]`
+          : "";
+      const assignee = issue.assignee ? ` (👤 ${issue.assignee.login})` : "";
+      lines.push(
+        `   #${issue.number} ${issue.state === "closed" ? "🔒" : "🟢"} ${issue.title}${labels}${assignee}`,
+      );
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { count: issues.length, issues: issues.map((i: any) => i.number) },
+    };
+  },
+};
+
+// ─── Get Issue ───────────────────────────────────────────────────────────────────
+
+export const getTool = {
+  name: "project_get_issue" as const,
+  label: "Get Issue",
+  description:
+    "Get full details of an issue including its body, labels, milestone, assignee, and recent comments.",
+  parameters: Type.Object({
+    issue_id: Type.String({ description: "Issue number or ID" }),
+    include_comments: Type.Optional(
+      Type.Boolean({ description: "Include recent comments (default: true)" }),
+    ),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const opts = resolveGitea(ctx.cwd);
+    const issueId = String(params.issue_id).replace(/^#/, "");
+
+    const r = giteaApi(`/issues/${issueId}`, "GET", null, opts, ctx.cwd);
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Issue #${issueId} not found.` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const issue = r.data as Record<string, unknown>;
+    const labels = Array.isArray(issue.labels)
+      ? (issue.labels as any[]).map((l) => l.name).join(", ")
+      : "(none)";
+
+    const lines = [
+      `📋 Issue #${issueId}`,
+      `   Title: ${issue.title}`,
+      `   State: ${issue.state}  |  Created: ${String(issue.created_at).slice(0, 10)}`,
+      `   Author: ${(issue.user as any)?.login || "?"}`,
+      `   Assignee: ${(issue.assignee as any)?.login || "(unassigned)"}`,
+      `   Milestone: ${(issue.milestone as any)?.title || "(none)"}`,
+      `   Labels: ${labels}`,
+      `   URL: ${issue.html_url || `http://127.0.0.1:3001/${opts.repo}/issues/${issueId}`}`,
+      "",
+      "─── Body ───",
+      issue.body || "(empty)",
+      "",
+    ];
+
+    // Fetch comments
+    const includeComments = params.include_comments !== false;
+    if (includeComments) {
+      const cr = giteaApi(
+        `/issues/${issueId}/comments?limit=20`,
+        "GET",
+        null,
+        opts,
+        ctx.cwd,
+      );
+      const comments = Array.isArray(cr.data) ? cr.data : [];
+      if (comments.length > 0) {
+        lines.push(`─── Comments (${comments.length}) ───`);
+        for (const c of comments as any[]) {
+          const date = String(c.created_at).slice(0, 10);
+          const user = c.user?.login || "?";
+          const body = (c.body || "").split("\n").slice(0, 5).join("\n");
+          lines.push(`\n   [${date}] ${user}:`);
+          for (const bl of body.split("\n")) {
+            lines.push(`   ${bl}`);
+          }
+          if ((c.body || "").split("\n").length > 5) lines.push("   ...");
+        }
+      } else {
+        lines.push("─── Comments ───");
+        lines.push("   (none)");
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: {
+        issueId,
+        state: issue.state,
+        title: issue.title,
+        url: issue.html_url,
+      },
+    };
+  },
+};