@ai-content-space/loopx 0.1.1 → 0.1.3

package/skills/debug/defense-in-depth.md

@@ -0,0 +1,122 @@
+# Defense-in-Depth Validation
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/skills/debug/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/skills/debug/root-cause-tracing.md

@@ -0,0 +1,169 @@
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script `find-polluter.sh` in this directory:
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution

package/skills/go-style/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: go-style
+description: Go language style support for loopx. Use before creating or editing Go (.go) files, especially inside build execution lanes.
+---
+
+# Go Style
+
+## Purpose
+
+`go-style` is a lightweight Go coding discipline skill. It should guide edits to `.go` files without overriding the repository's established conventions.
+
+Use it as a support skill from `build` when Go files are created or modified, and directly when the user asks for Go style, idiomatic Go, or Go code cleanup.
+
+## Core Rules
+
+- Preserve local project style first. If nearby code conflicts with this skill, follow the local pattern unless it is clearly broken.
+- Keep the happy path straight down. Return early for errors and guard clauses.
+- Put `context.Context` first in functions that accept a context.
+- Wrap propagated errors with operation context using `%w` when the caller benefits from the cause.
+- Do not wrap errors when returning framework/status errors that must preserve exact type or code semantics.
+- Use sentinel errors, typed errors, or framework errors according to the existing project pattern; do not force sentinel errors everywhere.
+- Avoid shadowing Go predeclared identifiers such as `len`, `error`, `string`, `copy`, `new`, and `make`.
+- Keep interfaces small and define them at the consumer boundary when practical.
+- Prefer table-driven tests for behavior matrices.
+- Run `gofmt` on edited Go files before verification.
+
+## Error Handling
+
+Good default:
+
+```go
+user, err := repo.GetUser(ctx, userID)
+if err != nil {
+    return nil, fmt.Errorf("get user %s: %w", userID, err)
+}
+```
+
+Use exact framework errors when the framework contract requires them:
+
+```go
+if !allowed {
+    return nil, errors.Forbidden("PERMISSION_DENIED", "permission denied")
+}
+```
+
+Expected error categories may be represented by:
+
+- package-level sentinel errors with `errors.Is`
+- typed errors with structured fields
+- Kratos/API status errors
+- existing project domain error helpers
+
+Choose the one already used in the codebase.
+
+## Comments
+
+- Exported symbols should have Go doc comments that start with the symbol name.
+- Short local comments are acceptable when they explain why, not what.
+- Prefer complete sentences for package, exported type, exported function, and non-obvious behavior comments.
+
+## Verification
+
+For Go edits, prefer the narrowest meaningful verification first, then broaden if the touched surface is shared:
+
+```bash
+gofmt -w <edited-go-files>
+go test ./...
+go vet ./...
+```
+
+Use project-specific commands when present, such as `make test`, `make lint`, `golangci-lint run`, or repository scripts.

package/skills/kratos/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: kratos
+description: Go-Kratos framework support for loopx. Use for Kratos microservices, proto/buf API work, service/biz/data layering, Kratos middleware, auth, configuration, and troubleshooting.
+---
+
+# Kratos
+
+## Purpose
+
+`kratos` supports Go-Kratos microservice work while staying subordinate to the repository's existing architecture.
+
+Use this skill when the user mentions Kratos, protobuf APIs, buf, service/biz/data layering, Kratos HTTP/gRPC servers, middleware, JWT/Casbin auth, or when the repository shows Kratos signals.
+
+## Project Detection
+
+Before applying Kratos-specific patterns, inspect for these signals:
+
+- `buf.yaml` or `buf.gen.yaml`
+- `api/**/*.proto`
+- `internal/service/`
+- `internal/biz/`
+- `internal/data/`
+- imports containing `github.com/go-kratos/kratos/v2`
+
+If signals are weak, ask whether to proceed with Kratos conventions before creating framework-specific structure.
+
+## Decision Map
+
+Use only the reference file needed for the current task:
+
+- New API / proto: `references/proto-api-design.md`
+- Service, biz, data layering: `references/architecture.md`
+- Configuration / startup: `references/configuration.md`
+- HTTP response customization, WebSocket, files: `references/http-customization.md`
+- JWT / Casbin / auth: `references/security-auth.md`
+- Middleware / logging: `references/middleware-logging.md`
+- Errors and troubleshooting: `references/troubleshooting.md`
+- MCP / advanced extensions: `references/advanced-features.md`
+
+## Architecture Defaults
+
+- Keep protocol concerns in `internal/service`.
+- Keep business rules and use cases in `internal/biz`.
+- Keep persistence, repositories, and external clients in `internal/data`.
+- Avoid leaking proto types into `biz` unless the existing project already does.
+- Prefer existing dependency injection style. Use `fx` examples only when the project already uses `fx`.
+- Preserve generated-code boundaries; edit source `.proto` or handwritten layers, not generated files.
+
+## Proto/API Defaults
+
+- Confirm package and `go_package` before adding proto files.
+- Add HTTP annotations only when HTTP exposure is required.
+- Use validation annotations when the project already uses `buf.validate` or `protovalidate`.
+- Regenerate code with the repository's existing command, such as `buf generate`, `make api`, or project scripts.
+
+## Integration With Other loopx Skills
+
+- Use `go-style` for handwritten `.go` edits.
+- Use `tdd` for behavior changes when a meaningful failing test can be written before implementation.
+- Use `debug` for Kratos runtime failures, generated-code mismatches, middleware ordering bugs, or request/response behavior that is not understood.
+- Use `verify` before claiming the API, generated code, or service behavior is ready.
+
+## Verification
+
+Prefer project-native commands. Common Kratos verification commands include:
+
+```bash
+buf lint
+buf generate
+go test ./...
+go vet ./...
+```
+
+If the project uses Make targets, prefer those over ad hoc commands.