pi-project-gate 1.0.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,7 +1,7 @@
 {
   "name": "pi-project-gate",
-  "version": "1.0.0",
-  "description": "Project orchestration gate for AI agents — structured issues, WIP limits, dependency blocking, and auto-generated release notes.",
+  "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",
     "pi-extension",
@@ -39,5 +39,12 @@
     "extensions": [
       "./src/index.ts"
     ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
   }
-}
+}

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

@@ -0,0 +1,300 @@
+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";
+
+// ═══════════════════════════════════════
+// Config
+// ═══════════════════════════════════════
+describe("ProjectConfig", () => {
+  it("returns defaults when no config", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    const config = loadConfig(tmp);
+    expect(config.maxWip).toBe(3);
+    expect(config.requiredSections).toContain("## Problem");
+    expect(config.requiredSections).toContain("## Proposed Solution");
+    expect(config.requiredSections).toContain("## Acceptance Criteria");
+    expect(config.complexityLevels).toContain("medium");
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses projectrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "project-test-"));
+    fs.writeFileSync(path.join(tmp, ".projectrc.yml"), [
+      "maxWip: 5",
+      'requiredSections: "## Problem,## Solution"',
+      'areas: "backend,frontend,infra"',
+      "releaseNoteIncludeHashes: true",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.maxWip).toBe(5);
+    expect(config.requiredSections).toEqual(["## Problem", "## Solution"]);
+    expect(config.areas).toEqual(["backend", "frontend", "infra"]);
+    expect(config.releaseNoteIncludeHashes).toBe(true);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Issue template validation
+// ═══════════════════════════════════════
+describe("validateIssueTemplate", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    requiredSections: ["## Problem", "## Proposed Solution", "## Acceptance Criteria"],
+  };
+
+  it("passes a complete template", () => {
+    const body = "## Problem\nSomething is broken\n\n## Proposed Solution\nFix it\n\n## Acceptance Criteria\n- [ ] Tests pass";
+    expect(validateIssueTemplate(body, config).ok).toBe(true);
+  });
+
+  it("fails when missing a section", () => {
+    const body = "## Problem\nSomething is broken\n\n## Proposed Solution\nFix it";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections).toContain("## Acceptance Criteria");
+    }
+  });
+
+  it("fails when all sections missing", () => {
+    const body = "Just a description with no sections";
+    const result = validateIssueTemplate(body, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.missingSections.length).toBe(3);
+    }
+  });
+
+  it("passes with custom required sections", () => {
+    const customConfig = { ...config, requiredSections: ["## Description"] };
+    expect(validateIssueTemplate("## Description\nSome text", customConfig).ok).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════
+// Dependency parsing
+// ═══════════════════════════════════════
+describe("parseDependencies", () => {
+  const config = {
+    ...DEFAULT_CONFIG,
+    dependencyPattern: "(?:Depends on|Blocked by|Requires)\\s+#(\\d+)",
+  };
+
+  it("parses Depends on", () => {
+    const deps = parseDependencies("Depends on #42", config);
+    expect(deps).toEqual(["42"]);
+  });
+
+  it("parses Blocked by", () => {
+    const deps = parseDependencies("Blocked by #123", config);
+    expect(deps).toEqual(["123"]);
+  });
+
+  it("parses Requires", () => {
+    const deps = parseDependencies("Requires #789", config);
+    expect(deps).toEqual(["789"]);
+  });
+
+  it("parses multiple dependencies", () => {
+    const deps = parseDependencies("Depends on #42 and Blocked by #123", config);
+    expect(deps).toContain("42");
+    expect(deps).toContain("123");
+    expect(deps.length).toBe(2);
+  });
+
+  it("returns empty for no dependencies", () => {
+    expect(parseDependencies("No dependencies here", config)).toEqual([]);
+  });
+
+  it("is case insensitive", () => {
+    const deps = parseDependencies("depends on #42 and blocked by #99", config);
+    expect(deps).toContain("42");
+    expect(deps).toContain("99");
+  });
+
+  it("deduplicates", () => {
+    const deps = parseDependencies("Depends on #42 and Depends on #42", config);
+    expect(deps).toEqual(["42"]);
+  });
+});
+
+// ═══════════════════════════════════════
+// Conventional commit parsing
+// ═══════════════════════════════════════
+describe("parseConventionalCommits", () => {
+  it("parses feat commits", () => {
+    const log = "commit abc12345\nfeat(api): add new endpoint\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(1);
+    expect(commits[0].type).toBe("feat");
+    expect(commits[0].scope).toBe("api");
+    expect(commits[0].subject).toBe("add new endpoint");
+    expect(commits[0].hash).toBe("abc12345");
+  });
+
+  it("parses fix commits without scope", () => {
+    const log = "commit def67890\nfix: resolve null pointer\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(1);
+    expect(commits[0].type).toBe("fix");
+    expect(commits[0].scope).toBe("");
+    expect(commits[0].subject).toBe("resolve null pointer");
+  });
+
+  it("skips non-conventional commits", () => {
+    const log = "commit ghi11111\nUpdated some stuff\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(0);
+  });
+
+  it("parses multiple commits", () => {
+    const log = "commit aaa11111\nfeat: first feature\n---\n\ncommit bbb22222\nfix: bug fix\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(2);
+    expect(commits[0].type).toBe("feat");
+    expect(commits[1].type).toBe("fix");
+  });
+
+  it("handles chore and refactor types", () => {
+    const log = "commit ccc33333\nchore(deps): update packages\n---\n\ncommit ddd44444\nrefactor: clean up\n---";
+    const commits = parseConventionalCommits(log);
+    expect(commits.length).toBe(2);
+    expect(commits[0].type).toBe("chore");
+    expect(commits[1].type).toBe("refactor");
+  });
+});
+
+// ═══════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════
+describe("exec helper", () => {
+  it("returns ok for valid command", () => {
+    const r = exec("echo project-test");
+    expect(r.ok).toBe(true);
+    expect(r.stdout).toBe("project-test");
+  });
+
+  it("returns not ok for invalid command", () => {
+    const r = exec("nonexistent-cmd-xyz-999 2>/dev/null");
+    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

@@ -0,0 +1,57 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ProjectConfig {
+  maxWip: number;
+  requiredSections: string[];
+  complexityLevels: string[];
+  areas: string[];
+  issueLabels: string[];
+  issueCreateRequireComplexity: boolean;
+  issueCreateRequireArea: boolean;
+  releaseNoteGroups: string[];
+  releaseNoteIncludeHashes: boolean;
+  dependencyPattern: string;
+}
+
+export const DEFAULT_CONFIG: ProjectConfig = {
+  maxWip: 3,
+  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+)",
+};
+
+export function loadConfig(cwd: string): ProjectConfig {
+  const configPath = path.join(cwd, ".projectrc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*([\w][\w.]*):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+        result[m[1]] = val;
+      }
+    }
+    return {
+      maxWip: parseInt(result["maxWip"] as string) || DEFAULT_CONFIG.maxWip,
+      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,
+    };
+  } catch { return { ...DEFAULT_CONFIG }; }
+}

package/src/helpers.ts

@@ -0,0 +1,28 @@
+import * as cp from "node:child_process";
+
+export function exec(cmd: string, cwd?: string): { ok: boolean; stdout: string; stderr: string } {
+  try { const r = cp.execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000 }); return { ok: true, stdout: r.trim(), stderr: "" }; }
+  catch (e: any) { return { ok: false, stdout: e.stdout?.trim() || "", stderr: e.stderr?.trim() || e.message }; }
+}
+
+export function currentBranch(cwd: string): string { return exec("git branch --show-current", cwd).stdout; }
+
+export function resolveGitea(cwd: string): { repo: string; token: string } {
+  const remote = exec("git remote get-url gitea 2>/dev/null || git remote get-url origin", cwd);
+  const url = remote.stdout || "";
+  const match = url.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  const repo = match ? `${match[1]}/${match[2]}` : "factory/wrok.in";
+  const credMatch = url.match(/:\/\/([^:]+):([^@]+)@/);
+  return { repo, token: credMatch ? credMatch[2] : "" };
+}
+
+export function giteaApi(path: string, method: string, body: Record<string, unknown> | null, opts: { repo: string; token?: string }, cwd: string): { ok: boolean; data: unknown; error?: string } {
+  const base = `http://127.0.0.1:3001/api/v1/repos/${opts.repo}`;
+  const headers = [opts.token ? `-H "Authorization: token ${opts.token}"` : "", `-H "Content-Type: application/json"`].filter(Boolean).join(" ");
+  const dataFlag = body ? `-d '${JSON.stringify(body).replace(/'/g, "'\\''")}'` : "";
+  const cmd = `curl -sf -w "\\n%{http_code}" -X ${method} "${base}${path}" ${headers} ${dataFlag}`;
+  const r = exec(cmd, cwd);
+  if (!r.ok) { const lines = r.stdout.split("\n"); return { ok: false, data: null, error: r.stderr || lines.slice(0, -1).join("\n") || "API error" }; }
+  const lines = r.stdout.split("\n"); const bodyText = lines.slice(0, -1).join("\n");
+  try { return { ok: true, data: JSON.parse(bodyText) }; } catch { return { ok: true, data: bodyText }; }
+}