opencodekit 0.10.0 → 0.11.1

package/dist/template/.opencode/command/integration-test.md

@@ -1,40 +1,426 @@
 ---
 description: Create integration tests within task constraints
-argument-hint: "<bead-id>"
+argument-hint: "<bead-id|path> [--pattern=<pattern>] [--framework=<framework>]"
 agent: build
 ---
 
 # Integration Test: $ARGUMENTS
 
-**Load skills:**
+Create integration tests that verify module boundaries and system interactions.
 
-- `skill({ name: "test-driven-development" })`
-- `skill({ name: "condition-based-waiting" })` (for async tests)
-- `skill({ name: "testing-anti-patterns" })` (avoid common mistakes)
+## Load Skills
 
-## Task Validation
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "test-driven-development" });
+```
 
-1. **Check bead exists:** `bd_show({ id: "$ARGUMENTS" })`
-2. **Read constraints:** `.beads/artifacts/$ARGUMENTS/spec.md` Testing Notes section
-3. **If missing:** STOP. Create with `/create` first.
+```typescript
+skill({ name: "test-driven-development" });
+skill({ name: "condition-based-waiting" }); // For async tests
+skill({ name: "testing-anti-patterns" }); // Avoid common mistakes
+```
 
-## Workflow
+---
+
+## What Are Integration Tests?
+
+| Test Type       | Scope                       | Speed        | Dependencies         |
+| --------------- | --------------------------- | ------------ | -------------------- |
+| **Unit**        | Single function/class       | Fast (ms)    | All mocked           |
+| **Integration** | Module boundaries, APIs, DB | Medium (s)   | Real or test doubles |
+| **E2E**         | Full user flows             | Slow (s-min) | Real everything      |
+
+**Integration tests verify:**
+
+- API endpoints work end-to-end
+- Database queries return correct data
+- Services communicate correctly
+- External integrations behave as expected
+
+---
+
+## Phase 1: Task Validation
+
+```typescript
+// Check bead exists
+bd_show({ id: "$ARGUMENTS" });
+
+// Read test constraints
+read(".beads/artifacts/$ARGUMENTS/spec.md");
+```
+
+If bead missing: STOP. Create with `/create` first.
+
+---
+
+## Phase 2: Framework Detection
+
+```bash
+# Detect test framework
+glob pattern="**/jest.config.*"
+glob pattern="**/vitest.config.*"
+glob pattern="**/pytest.ini"
+glob pattern="**/pyproject.toml"
+
+# Read package.json for test command
+read package.json
+```
+
+| Framework | File Pattern             | Test Command |
+| --------- | ------------------------ | ------------ |
+| Jest      | `*.test.ts`, `*.spec.ts` | `npm test`   |
+| Vitest    | `*.test.ts`, `*.spec.ts` | `npm test`   |
+| pytest    | `test_*.py`, `*_test.py` | `pytest`     |
+| Go        | `*_test.go`              | `go test`    |
+
+---
+
+## Phase 3: Test Structure
+
+### File Location
+
+```
+src/
+├── auth/
+│   ├── login.ts
+│   └── login.test.ts          # Co-located unit tests
+tests/
+├── integration/
+│   ├── auth.test.ts           # Integration tests here
+│   ├── api.test.ts
+│   └── database.test.ts
+└── fixtures/
+    ├── users.json
+    └── factories.ts
+```
+
+### Test File Structure
+
+```typescript
+// tests/integration/auth.test.ts
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import { createTestDatabase, cleanupDatabase } from "../fixtures/database";
+import { createTestUser } from "../fixtures/factories";
+import { app } from "../../src/app";
+
+describe("Auth Integration", () => {
+  let db: TestDatabase;
+
+  beforeAll(async () => {
+    db = await createTestDatabase();
+  });
+
+  afterAll(async () => {
+    await cleanupDatabase(db);
+  });
+
+  beforeEach(async () => {
+    await db.clear(); // Clean slate each test
+  });
+
+  describe("POST /login", () => {
+    it("returns JWT for valid credentials", async () => {
+      // Arrange
+      const user = await createTestUser(db, { email: "test@example.com" });
+
+      // Act
+      const response = await app.request("/login", {
+        method: "POST",
+        body: JSON.stringify({ email: user.email, password: "password123" }),
+      });
+
+      // Assert
+      expect(response.status).toBe(200);
+      const body = await response.json();
+      expect(body.token).toBeDefined();
+      expect(body.user.email).toBe(user.email);
+    });
+
+    it("returns 401 for invalid password", async () => {
+      const user = await createTestUser(db);
+
+      const response = await app.request("/login", {
+        method: "POST",
+        body: JSON.stringify({ email: user.email, password: "wrong" }),
+      });
+
+      expect(response.status).toBe(401);
+    });
+  });
+});
+```
+
+---
+
+## Phase 4: Common Test Patterns
+
+### Database Integration
+
+```typescript
+describe("User Repository", () => {
+  let db: Database;
+
+  beforeAll(async () => {
+    db = await createTestDatabase();
+    await db.migrate();
+  });
+
+  afterEach(async () => {
+    await db.exec("DELETE FROM users"); // Clean between tests
+  });
+
+  afterAll(async () => {
+    await db.close();
+  });
+
+  it("creates user with hashed password", async () => {
+    const repo = new UserRepository(db);
+
+    const user = await repo.create({
+      email: "test@example.com",
+      password: "plaintext123",
+    });
+
+    expect(user.id).toBeDefined();
+    expect(user.password).not.toBe("plaintext123"); // Should be hashed
+  });
+});
+```
+
+### API Integration
+
+```typescript
+describe("API Integration", () => {
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await createTestServer();
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it("GET /users returns paginated list", async () => {
+    // Seed data
+    await seedUsers(10);
+
+    const response = await fetch(`${server.url}/users?page=1&limit=5`);
+    const data = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(data.users).toHaveLength(5);
+    expect(data.total).toBe(10);
+    expect(data.page).toBe(1);
+  });
+});
+```
+
+### External Service Integration
 
-1. **Load skill** - `skill({ name: "test-driven-development" })`
-2. **Follow TDD cycle:**
-   - Write failing integration test first
-   - Verify it fails for the right reason
-   - Implement minimal code to pass
-   - Refactor while green
-3. **Test only task integration points** from spec architecture
+```typescript
+describe("Payment Service", () => {
+  it("processes payment with Stripe test mode", async () => {
+    const stripe = new Stripe(process.env.STRIPE_TEST_KEY);
 
-## Anti-Hallucination
+    const paymentIntent = await stripe.paymentIntents.create({
+      amount: 1000,
+      currency: "usd",
+      payment_method: "pm_card_visa", // Stripe test card
+      confirm: true,
+    });
 
-- Test only modules from bead spec scope
-- Mock only dependencies from spec
-- Use test framework from spec testing notes
-- Update `.beads/artifacts/$ARGUMENTS/review.md` after work
+    expect(paymentIntent.status).toBe("succeeded");
+  });
+});
+```
+
+### Async/Queue Integration
+
+```typescript
+describe("Job Queue", () => {
+  it("processes email job within timeout", async () => {
+    const queue = createTestQueue();
+
+    // Add job
+    await queue.add("send-email", { to: "test@example.com" });
+
+    // Wait for processing (use condition-based-waiting skill)
+    await waitFor(
+      async () => {
+        const job = await queue.getJob("send-email");
+        return job?.status === "completed";
+      },
+      { timeout: 5000, interval: 100 },
+    );
+
+    const job = await queue.getJob("send-email");
+    expect(job.status).toBe("completed");
+  });
+});
+```
+
+---
+
+## Phase 5: Test Data Management
+
+### Factories
+
+```typescript
+// tests/fixtures/factories.ts
+
+export function createTestUser(db: Database, overrides = {}) {
+  return db.insert("users", {
+    id: randomUUID(),
+    email: `test-${Date.now()}@example.com`,
+    password: hashSync("password123", 10),
+    createdAt: new Date(),
+    ...overrides,
+  });
+}
+
+export function createTestOrder(db: Database, userId: string, overrides = {}) {
+  return db.insert("orders", {
+    id: randomUUID(),
+    userId,
+    status: "pending",
+    total: 100,
+    ...overrides,
+  });
+}
+```
+
+### Cleanup Strategies
+
+| Strategy                 | Pros        | Cons               |
+| ------------------------ | ----------- | ------------------ |
+| **Transaction rollback** | Fast, clean | Complex setup      |
+| **DELETE after each**    | Simple      | Slower             |
+| **Fresh DB per test**    | Isolated    | Very slow          |
+| **Truncate tables**      | Fast reset  | May miss FK issues |
+
+**Recommended:** Transaction rollback for speed, DELETE for simplicity.
+
+---
+
+## Phase 6: Isolation Patterns
+
+### Database Isolation
+
+```typescript
+// Wrap each test in transaction that rolls back
+beforeEach(async () => {
+  await db.exec("BEGIN");
+});
+
+afterEach(async () => {
+  await db.exec("ROLLBACK");
+});
+```
+
+### Port Isolation (Parallel Tests)
+
+```typescript
+// Use dynamic ports for parallel test runners
+const server = await app.listen(0); // Random available port
+const port = server.address().port;
+```
+
+### Environment Isolation
+
+```bash
+# .env.test
+DATABASE_URL=postgres://localhost/myapp_test
+STRIPE_KEY=sk_test_xxx
+REDIS_URL=redis://localhost:6379/1  # Separate DB number
+```
+
+---
+
+## Phase 7: TDD Workflow
+
+Follow the cycle:
+
+1. **Write failing test first**
+   - Test should fail for the RIGHT reason
+   - Not a syntax error, but missing functionality
+
+2. **Verify failure message**
+   - Should clearly indicate what's missing
+   - "Expected 200, got 404" = endpoint missing
+
+3. **Implement minimal code**
+   - Just enough to pass
+   - Don't over-engineer
+
+4. **Refactor while green**
+   - Improve code quality
+   - Keep tests passing
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                   | Problem                     | Do Instead                        |
+| ------------------------------ | --------------------------- | --------------------------------- |
+| Testing implementation details | Brittle tests               | Test behavior/outcomes            |
+| Excessive mocking              | Tests don't reflect reality | Use real dependencies             |
+| Shared mutable state           | Flaky tests                 | Isolate each test                 |
+| Testing third-party code       | Waste of time               | Trust libraries, test integration |
+| No cleanup                     | Tests affect each other     | Always clean up                   |
+| Hardcoded test data            | Fragile                     | Use factories                     |
+
+---
+
+## Coverage Guidelines
+
+| Coverage Type        | Target    | Notes                         |
+| -------------------- | --------- | ----------------------------- |
+| Line coverage        | 70-80%    | Higher for critical paths     |
+| Branch coverage      | 60-70%    | Cover main branches           |
+| Integration coverage | Key paths | All API endpoints, main flows |
+
+**Focus on:** Happy paths, error cases, edge cases in that order.
+
+---
+
+## CI Considerations
+
+```yaml
+# .github/workflows/test.yml
+jobs:
+  integration-tests:
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_DB: test
+    steps:
+      - run: npm run test:integration
+        env:
+          DATABASE_URL: postgres://postgres@localhost/test
+```
+
+---
+
+## Output
+
+After writing tests:
+
+1. **Run tests**: Verify all pass
+2. **Check coverage**: Meet guidelines
+3. **Update review.md**: `.beads/artifacts/$ARGUMENTS/review.md`
+4. **Complete**: `/finish $ARGUMENTS`
+
+---
 
-## Complete
+## Related Commands
 
-Run `/finish $ARGUMENTS` when done.
+| Need                | Command                   |
+| ------------------- | ------------------------- |
+| Create unit tests   | Use TDD skill directly    |
+| Fix failing tests   | `/fix`                    |
+| Review test quality | `/review-codebase tests/` |
+| Complete task       | `/finish <bead-id>`       |

package/dist/template/.opencode/command/issue.md

@@ -1,37 +1,121 @@
 ---
 description: Analyze GitHub issue and create bead for tracking
-argument-hint: "[issue-number]"
+argument-hint: "<issue-number>"
 agent: build
 ---
 
 # Analyze Issue: $ARGUMENTS
 
-## Fetch Issue
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
+## Phase 1: Check for Duplicates
+
+Before creating, search for existing beads:
+
+```typescript
+bd_ls({ status: "all", limit: 20 });
+memory - search({ query: "[keywords from issue title]" });
+```
+
+If similar bead exists:
+
+- Link as related, or
+- Add to existing bead, or
+- Confirm this is intentionally separate
+
+## Phase 2: Fetch GitHub Issue
 
 ```bash
-gh issue view $ARGUMENTS
+gh issue view $ARGUMENTS --json title,body,labels,state,assignees,milestone
 ```
 
-## Analysis
+Extract:
+
+- **Title**: Issue title
+- **Labels**: For tag mapping
+- **Body**: For analysis
+
+## Phase 3: Analysis
+
+Parse the issue content:
+
+| Field        | Extract From                    |
+| ------------ | ------------------------------- |
+| **Problem**  | What's broken/needed?           |
+| **Expected** | What should happen?             |
+| **Current**  | What happens now?               |
+| **Steps**    | How to reproduce?               |
+| **Files**    | Mentioned files or components   |
+| **Labels**   | bug, feature, enhancement, etc. |
 
-1. **Problem:** What's broken/needed?
-2. **Expected:** What should happen?
-3. **Current:** What happens now?
-4. **Steps:** How to reproduce?
+## Phase 4: Map Labels & Priority
 
-## Create Tracking Bead
+**Label → Tag mapping:**
 
-Create a bead to track this work, linking it to the GitHub issue:
+| GitHub Label  | Bead Tag |
+| ------------- | -------- |
+| bug           | bug      |
+| enhancement   | feature  |
+| feature       | feature  |
+| documentation | docs     |
+| frontend, ui  | fe       |
+| backend, api  | be       |
+| mobile        | mobile   |
+| devops, infra | devops   |
+| testing       | qa       |
+
+**Priority mapping:**
+
+| GitHub Signal             | Bead Priority |
+| ------------------------- | ------------- |
+| critical, P0, blocker     | 0             |
+| high, P1, urgent          | 1             |
+| medium, P2 (default)      | 2             |
+| low, P3                   | 3             |
+| backlog, P4, nice-to-have | 4             |
+
+## Phase 5: Estimate Complexity
+
+Based on issue analysis:
+
+| Signals                               | Estimate | Next Step  |
+| ------------------------------------- | -------- | ---------- |
+| Single file, obvious fix, clear repro | S (~10)  | /implement |
+| Few files, clear scope, known area    | M (~30)  | /implement |
+| Multiple files, needs investigation   | L (~100) | /research  |
+| Vague, architectural, cross-cutting   | XL       | Decompose  |
+
+## Phase 6: Create Tracking Bead
+
+Reserve spec file:
 
 ```typescript
-bd_add({ title: "<issue title>", type: "task", pri: 2 });
+bd_reserve({
+  paths: [".beads/artifacts/<bead-id>/spec.md"],
+  reason: "Creating issue bead",
+  ttl: 600,
+});
 ```
 
-Save the bead ID for subsequent commands. Add the GitHub issue reference via `bd_msg` or in the spec.
+Create bead with mapped values:
 
-## Create Spec from PRD Template
+```typescript
+bd_add({
+  title: "<issue title>",
+  type: "[bug|feature|task]", // from label mapping
+  pri: [0 - 4], // from priority mapping
+  tags: ["[role]", "[estimate]"], // e.g., ["fe", "M"]
+  desc: "GitHub Issue #$ARGUMENTS",
+});
+```
 
-Use `.opencode/memory/_templates/prd.md` as the base structure.
+## Phase 7: Create Spec
+
+Use `.opencode/memory/_templates/prd.md` as base structure.
 
 Save to `.beads/artifacts/<bead-id>/spec.md`:
 
@@ -42,6 +126,7 @@ Save to `.beads/artifacts/<bead-id>/spec.md`:
 **Created:** [date]
 **Status:** To Do
 **GitHub Issue:** #$ARGUMENTS
+**Estimate:** [S/M/L/XL] (~[N] tool calls)
 
 ## Goal
 
@@ -49,12 +134,12 @@ Save to `.beads/artifacts/<bead-id>/spec.md`:
 
 ## Scope
 
-### In-Scope:
+**In-Scope:**
 
 - [Files to change]
 - [Specific functionality to fix/add]
 
-### Out-of-Scope:
+**Out-of-Scope:**
 
 - [What we are NOT touching]
 
@@ -65,9 +150,22 @@ Save to `.beads/artifacts/<bead-id>/spec.md`:
 
 ## Success Criteria
 
-- [ ] [Specific fix verified]
-- [ ] [Test cases pass]
-- [ ] [No regression]
+- [ ] [Criterion 1]
+  - Verify: `[actual command to test]`
+- [ ] [Criterion 2]
+  - Verify: `[actual command to test]`
+- [ ] No regression in related functionality
+  - Verify: `npm test`
+
+## Constraints
+
+**Must:**
+
+- [Required constraint from issue]
+
+**Never:**
+
+- [Anti-pattern or forbidden action]
 
 ## Dependencies
 
@@ -77,11 +175,62 @@ Save to `.beads/artifacts/<bead-id>/spec.md`:
 
 - **Risks/edge cases:** [What could go wrong]
 - **Testing strategy:** [How to verify fix]
+- **Related issues:** [Link to related GitHub issues]
 ```
 
+## Phase 8: Comment on GitHub Issue
+
+Add bead reference back to GitHub:
+
+```bash
+gh issue comment $ARGUMENTS --body "Tracking: \`<bead-id>\`
+
+Estimate: [S/M/L/XL]
+Next: [/implement or /research]"
+```
+
+## Phase 9: Assign Role (optional)
+
+For multi-agent workflows:
+
+```typescript
+bd_assign({ id: "<bead-id>", role: "[fe/be/mobile/devops/qa]", notify: true });
+```
+
+## Phase 10: Sync & Report
+
+```typescript
+bd_release({ _: true });
+bd_sync({ reason: "Created bead for issue #$ARGUMENTS" });
+```
+
+```
+Issue Imported: #$ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Bead: <bead-id>
+Type: [bug/feature/task]
+Priority: [0-4]
+Estimate: [S/M/L/XL] (~[N] tool calls)
+
+Labels mapped: [list]
+Tags: [list]
+
+Spec: .beads/artifacts/<bead-id>/spec.md
+GitHub: Commented with bead reference ✓
+```
+
+**Next steps by estimate:**
+
+| Estimate | Command                |
+| -------- | ---------------------- |
+| S/M      | `/implement <bead-id>` |
+| L        | `/research <bead-id>`  |
+| XL       | Decompose first        |
+
 ## Discovered Work
 
-If analysis reveals additional issues, create child beads:
+If analysis reveals additional issues:
 
 ```typescript
 bd_add({
@@ -89,7 +238,14 @@ bd_add({
   type: "task",
   pri: 2,
   parent: "<parent-bead-id>",
+  tags: ["[role]", "[estimate]"],
 });
 ```
 
-**Next:** Use `/implement <bead-id>` to start implementation.
+Report discovered work:
+
+```
+Discovered Work:
+- <child-bead-id>: [title] ([estimate])
+- <child-bead-id>: [title] ([estimate])
+```