@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/testing-anti-patterns/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: testing-anti-patterns
+description: Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies
+version: 1.0.0
+tags: [testing, code-quality]
+dependencies: []
+---
+
+# Testing Anti-Patterns
+
+## When to Use
+
+- Writing or refactoring tests that introduce mocks or test-only helpers
+- Reviewing tests for mock misuse, incomplete mocks, or production pollution
+
+## When NOT to Use
+
+- Pure production code changes with no test work
+- Simple test updates that don’t involve mocks or structure changes
+
+## Overview
+
+Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
+
+**Core principle:** Test what the code does, not what the mocks do.
+
+**Following strict TDD prevents these anti-patterns.**
+
+## The Iron Laws
+
+```
+1. NEVER test mock behavior
+2. NEVER add test-only methods to production classes
+3. NEVER mock without understanding dependencies
+```
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+**The violation:**
+
+```typescript
+// ❌ BAD: Testing that the mock exists
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why this is wrong:**
+
+- You're verifying the mock works, not that the component works
+- Test passes when mock is present, fails when it's not
+- Tells you nothing about real behavior
+
+**your human partner's correction:** "Are we testing the behavior of a mock?"
+
+**The fix:**
+
+```typescript
+// ✅ GOOD: Test real component or don't mock it
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// OR if sidebar must be mocked for isolation:
+// Don't assert on the mock - test Page's behavior with sidebar present
+```
+
+### Gate Function
+
+```
+BEFORE asserting on any mock element:
+  Ask: "Am I testing real component behavior or just mock existence?"
+
+  IF testing mock existence:
+    STOP - Delete the assertion or unmock the component
+
+  Test real behavior instead
+```
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**The violation:**
+
+```typescript
+// ❌ BAD: destroy() only used in tests
+class Session {
+  async destroy() {
+    // Looks like production API!
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
+  }
+}
+
+// In tests
+afterEach(() => session.destroy());
+```
+
+**Why this is wrong:**
+
+- Production class polluted with test-only code
+- Dangerous if accidentally called in production
+- Violates YAGNI and separation of concerns
+- Confuses object lifecycle with entity lifecycle
+
+**The fix:**
+
+```typescript
+// ✅ GOOD: Test utilities handle test cleanup
+// Session has no destroy() - it's stateless in production
+
+// In test-utils/
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// In tests
+afterEach(() => cleanupSession(session));
+```
+
+### Gate Function
+
+```
+BEFORE adding any method to production class:
+  Ask: "Is this only used by tests?"
+
+  IF yes:
+    STOP - Don't add it
+    Put it in test utilities instead
+
+  Ask: "Does this class own this resource's lifecycle?"
+
+  IF no:
+    STOP - Wrong class for this method
+```
+
+## Anti-Pattern 3: Mocking Without Understanding
+
+**The violation:**
+
+```typescript
+// ❌ BAD: Mock breaks test logic
+test("detects duplicate server", () => {
+  // Mock prevents config write that test depends on!
+  vi.mock("ToolCatalog", () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined),
+  }));
+
+  await addServer(config);
+  await addServer(config); // Should throw - but won't!
+});
+```
+
+**Why this is wrong:**
+
+- Mocked method had side effect test depended on (writing config)
+- Over-mocking to "be safe" breaks actual behavior
+- Test passes for wrong reason or fails mysteriously
+
+**The fix:**
+
+```typescript
+// ✅ GOOD: Mock at correct level
+test("detects duplicate server", () => {
+  // Mock the slow part, preserve behavior test needs
+  vi.mock("MCPServerManager"); // Just mock slow server startup
+
+  await addServer(config); // Config written
+  await addServer(config); // Duplicate detected ✓
+});
+```
+
+### Gate Function
+
+```
+BEFORE mocking any method:
+  STOP - Don't mock yet
+
+  1. Ask: "What side effects does the real method have?"
+  2. Ask: "Does this test depend on any of those side effects?"
+  3. Ask: "Do I fully understand what this test needs?"
+
+  IF depends on side effects:
+    Mock at lower level (the actual slow/external operation)
+    OR use test doubles that preserve necessary behavior
+    NOT the high-level method the test depends on
+
+  IF unsure what test depends on:
+    Run test with real implementation FIRST
+    Observe what actually needs to happen
+    THEN add minimal mocking at the right level
+
+  Red flags:
+    - "I'll mock this to be safe"
+    - "This might be slow, better mock it"
+    - Mocking without understanding the dependency chain
+```
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**The violation:**
+
+```typescript
+// ❌ BAD: Partial mock - only fields you think you need
+const mockResponse = {
+  status: "success",
+  data: { userId: "123", name: "Alice" },
+  // Missing: metadata that downstream code uses
+};
+
+// Later: breaks when code accesses response.metadata.requestId
+```
+
+**Why this is wrong:**
+
+- **Partial mocks hide structural assumptions** - You only mocked fields you know about
+- **Downstream code may depend on fields you didn't include** - Silent failures
+- **Tests pass but integration fails** - Mock incomplete, real API complete
+- **False confidence** - Test proves nothing about real behavior
+
+**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
+
+**The fix:**
+
+```typescript
+// ✅ GOOD: Mirror real API completeness
+const mockResponse = {
+  status: "success",
+  data: { userId: "123", name: "Alice" },
+  metadata: { requestId: "req-789", timestamp: 1234567890 },
+  // All fields real API returns
+};
+```
+
+### Gate Function
+
+```
+BEFORE creating mock responses:
+  Check: "What fields does the real API response contain?"
+
+  Actions:
+    1. Examine actual API response from docs/examples
+    2. Include ALL fields system might consume downstream
+    3. Verify mock matches real response schema completely
+
+  Critical:
+    If you're creating a mock, you must understand the ENTIRE structure
+    Partial mocks fail silently when code depends on omitted fields
+
+  If uncertain: Include all documented fields
+```
+
+## Anti-Pattern 5: Integration Tests as Afterthought
+
+**The violation:**
+
+```
+✅ Implementation complete
+❌ No tests written
+"Ready for testing"
+```
+
+**Why this is wrong:**
+
+- Testing is part of implementation, not optional follow-up
+- TDD would have caught this
+- Can't claim complete without tests
+
+**The fix:**
+
+```
+TDD cycle:
+1. Write failing test
+2. Implement to pass
+3. Refactor
+4. THEN claim complete
+```
+
+## When Mocks Become Too Complex
+
+**Warning signs:**
+
+- Mock setup longer than test logic
+- Mocking everything to make test pass
+- Mocks missing methods real components have
+- Test breaks when mock changes
+
+**your human partner's question:** "Do we need to be using a mock here?"
+
+**Consider:** Integration tests with real components often simpler than complex mocks
+
+## TDD Prevents These Anti-Patterns
+
+**Why TDD helps:**
+
+1. **Write test first** → Forces you to think about what you're actually testing
+2. **Watch it fail** → Confirms test tests real behavior, not mocks
+3. **Minimal implementation** → No test-only methods creep in
+4. **Real dependencies** → You see what the test actually needs before mocking
+
+**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
+
+## Quick Reference
+
+| Anti-Pattern                    | Fix                                           |
+| ------------------------------- | --------------------------------------------- |
+| Assert on mock elements         | Test real component or unmock it              |
+| Test-only methods in production | Move to test utilities                        |
+| Mock without understanding      | Understand dependencies first, mock minimally |
+| Incomplete mocks                | Mirror real API completely                    |
+| Tests as afterthought           | TDD - tests first                             |
+| Over-complex mocks              | Consider integration tests                    |
+
+## Red Flags
+
+- Assertion checks for `*-mock` test IDs
+- Methods only called in test files
+- Mock setup is >50% of test
+- Test fails when you remove mock
+- Can't explain why mock is needed
+- Mocking "just to be safe"
+
+## The Bottom Line
+
+**Mocks are tools to isolate, not things to test.**
+
+If TDD reveals you're testing mock behavior, you've gone wrong.
+
+Fix: Test real behavior or question why you're mocking at all.

package/dist/template/.opencode/skill/think-in-code/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: think-in-code
+description: Use when answering questions that require counting, filtering, parsing, joining, or summarizing data — write a small script that prints only the answer instead of reading large files into context. Saves 90%+ tokens vs raw reads. Adapted from context-mode (mksglu/context-mode).
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
+---
+
+# Think in Code
+
+Compute answers with a small script. Don't drag raw data through context.
+
+## Core Principle
+
+> The model's job is to think. The script's job is to count, parse, filter, join. Then `console.log` only the answer.
+
+When you need a fact derived from data (logs, JSON, CSV, command output, file lists), the cheapest path is:
+
+1. Write 5–30 lines of code that produces the answer
+2. Run it
+3. Read **only** the printed answer
+
+Reading the raw data into context first is almost always wrong.
+
+## When to Use
+
+- Counting things in files / API output / logs ("how many failed runs in the last 100?")
+- Filtering large lists ("which dependencies haven't been updated in 6 months?")
+- Parsing structured output (`gh pr list --json`, `git log --pretty=...`, large JSON config)
+- Joining data across sources ("which files in `git diff` also have failing tests?")
+- Summarizing logs (top 10 error messages, error rate over time)
+- Computing diffs/intersections between two lists
+
+## When NOT to Use
+
+- The data is already small (<50 lines and you need most of it)
+- You need to **read** the content for understanding, not extract a fact (e.g. reviewing a PR)
+- The script itself would be longer than just reading the slice you need
+- A single `grep -c` or `wc -l` already answers it — just run that
+
+## Quick Decision
+
+| Situation                               | Approach                                        |
+| --------------------------------------- | ----------------------------------------------- |
+| "How many X in Y?"                      | Script → `console.log(count)`                   |
+| "Which Z match condition?"              | Script → `console.log(matches.join('\n'))`      |
+| "Top N by metric?"                      | Script → `console.log(top.map(...).join('\n'))` |
+| "What does this code do?"               | Read the file                                   |
+| "What's broken in this 30-line config?" | Read the file                                   |
+| "Count errors in 2MB log"               | Script — never `cat` it                         |
+
+## Patterns
+
+### Node one-liner (preferred for JSON / npm / fs work)
+
+```bash
+node -e "
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'));
+const deps = Object.keys(data.packages || {}).filter(k => k.startsWith('node_modules/'));
+console.log('Total deps:', deps.length);
+console.log('Unique top-level:', new Set(deps.map(d => d.split('/')[1])).size);
+"
+```
+
+### Python one-liner (preferred for CSV / data crunching)
+
+```bash
+python3 -c "
+import csv, sys
+with open('data.csv') as f:
+    rows = list(csv.DictReader(f))
+errors = [r for r in rows if r['status'] == 'error']
+print(f'errors: {len(errors)} / {len(rows)}')
+print(f'top hosts:', sorted({r[\"host\"] for r in errors})[:5])
+"
+```
+
+### Bash (only when output is guaranteed small)
+
+```bash
+# OK — output is one number
+git log --since='1 week ago' --oneline | wc -l
+
+# OK — already filtered small
+gh pr list --state open --json number,title --jq '.[] | select(.title | contains("fix")) | .number'
+
+# NOT OK — dumps everything into context
+cat huge-log.txt | grep ERROR
+# Better:
+grep -c ERROR huge-log.txt                    # if you only need the count
+grep ERROR huge-log.txt | head -20            # if you need samples
+```
+
+### Save script to a file when it's reusable
+
+```bash
+cat > /tmp/count-deps.js <<'EOF'
+const fs = require('fs');
+const lock = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const pkgs = Object.keys(lock.packages || {});
+const stale = pkgs.filter(p => p.includes('node_modules/') && !p.includes('node_modules/.'));
+console.log(JSON.stringify({ total: pkgs.length, packages: stale.length }, null, 2));
+EOF
+node /tmp/count-deps.js package-lock.json
+```
+
+## Anti-Patterns
+
+| Anti-Pattern                                              | Why It's Wrong                               | Do Instead                                  |
+| --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------- |
+| `cat huge.json` then "let me parse this in my head"       | Pulls 100KB+ into context for one answer     | `node -e "..."` to compute and print answer |
+| `gh pr list --json ...` printing all fields               | Dumps 50+ PRs of metadata you don't need     | `--jq` to filter to just the field you want |
+| `find . -name '*.ts'` to count files                      | Lists every path                             | `find . -name '*.ts' \| wc -l`              |
+| Reading 5 large logs to compare error rates               | 5x context bloat for one comparison          | Script that opens all 5 and prints summary  |
+| `curl https://api/...` raw piped to read                  | Whole response body in context               | `curl ... \| jq '.field'` or save to file   |
+| Asking the model to "estimate" instead of running a count | Hallucination risk; counts are deterministic | Run the script                              |
+
+## Verification
+
+Before considering an answer "done":
+
+1. The script ran without error
+2. The printed output is what you reasoned about (don't substitute memory for output)
+3. If the question was "how many", the script printed a number — not raw rows you then counted manually
+
+## Why This Skill Exists
+
+Adapted from the **Think in Code** pillar of [context-mode](https://github.com/mksglu/context-mode). The original ships a sandboxed executor that _forces_ this pattern; we keep the discipline as a prompt-level skill so it works without bundling new infrastructure.
+
+The savings compound: a single avoided 100KB read pays for many script iterations, and downstream summarization/handoff becomes cheaper too.
+
+## References
+
+- context-mode: https://github.com/mksglu/context-mode
+- Pairs with: `verification-before-completion`, `code-search-patterns`, `rtk-command-compression`