devlyn-cli 0.2.1 → 0.4.0

package/optional-skills/better-auth-setup/references/testing.md

@@ -0,0 +1,241 @@
+# Test Infrastructure Reference
+
+Test setup, seed factories, and integration test patterns for Better Auth with Bun.
+
+## Table of Contents
+1. [Test Preload](#test-preload)
+2. [Seed Data Factory](#seed-data-factory)
+3. [Integration Test App](#integration-test-app)
+4. [Database Cleanup](#database-cleanup)
+5. [Key Testing Patterns](#key-testing-patterns)
+
+## Test Preload
+
+Prevents the most common testing pitfall: real emails sent during test runs.
+
+```typescript
+// src/test-utils/setup.ts — preloaded via bunfig.toml
+// Without this, test signups send real emails through Resend
+// when RESEND_API_KEY is in your .env file.
+process.env.NODE_ENV = "test";
+process.env.RESEND_API_KEY = ""; // Force email to console-log fallback
+
+// Bridge test database — use a separate DB for tests
+if (process.env.TEST_DATABASE_URL) {
+  process.env.DATABASE_URL = process.env.TEST_DATABASE_URL;
+}
+```
+
+```toml
+# bunfig.toml
+[test]
+preload = ["./src/test-utils/setup.ts"]
+```
+
+**Why preload?** Bun's preload runs before any test file imports. This guarantees that config validation (which runs at import time) sees the correct environment variables. Setting `RESEND_API_KEY = ""` before any module loads ensures the email module's lazy client never initializes.
+
+## Seed Data Factory
+
+Creates a complete tenant hierarchy for integration tests. Every call produces unique identifiers to prevent collisions in parallel test runs.
+
+```typescript
+// src/test-utils/db.ts
+import { db } from "../db";
+import {
+  organizations, users, orgMemberships,
+  projects, apiKeys, sessions, accounts,
+  verifications, invitations,
+} from "../db/schema";
+
+export async function seedTestData() {
+  const uniqueSuffix = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+  // Create org → user → membership → project → API key
+  const [org] = await db.insert(organizations).values({
+    name: `Test Org ${uniqueSuffix}`,
+    slug: `test-org-${uniqueSuffix}`,
+    plan: "free",
+  }).returning();
+
+  const [user] = await db.insert(users).values({
+    email: `test-${uniqueSuffix}@example.com`,
+    name: "Test User",
+    emailVerified: true,
+  }).returning();
+
+  await db.insert(orgMemberships).values({
+    organizationId: org.id,
+    userId: user.id,
+    role: "owner",
+  });
+
+  const [project] = await db.insert(projects).values({
+    organizationId: org.id,
+    name: `Test Project ${uniqueSuffix}`,
+    slug: `test-project-${uniqueSuffix}`,
+  }).returning();
+
+  // Generate API key
+  const { key, hash, prefix } = await generateTestApiKey();
+  const [apiKey] = await db.insert(apiKeys).values({
+    projectId: project.id,
+    name: "Test Key",
+    keyHash: hash,
+    keyPrefix: prefix,
+  }).returning();
+
+  return { org, user, project, apiKey, plaintextKey: key };
+}
+
+// Helper: generate a test API key
+async function generateTestApiKey() {
+  const { API_KEY_PREFIX, base62Encode, hashKey } = await import("../lib/api-keys");
+  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+  const key = API_KEY_PREFIX + base62Encode(randomBytes);
+  const hash = await hashKey(key);
+  const prefix = key.slice(0, 12);
+  return { key, hash, prefix };
+}
+```
+
+**Key design decisions:**
+- `uniqueSuffix` uses `Date.now()` + random chars for collision-free parallel tests
+- `emailVerified: true` so tests don't need to go through email verification flow
+- Returns `plaintextKey` so tests can immediately make authenticated requests
+
+## Integration Test App
+
+Builds the full middleware chain matching production. This catches middleware ordering bugs before they reach production.
+
+```typescript
+// src/test-utils/app.ts
+import { Hono } from "hono";
+
+// Lazy imports to avoid circular dependency issues during test setup
+export function createIntegrationApp() {
+  const { authMiddleware } = require("../middleware/auth");
+  const { tenantContextMiddleware } = require("../middleware/tenant-context");
+  const { rateLimitMiddleware } = require("../middleware/rate-limit");
+
+  const app = new Hono();
+
+  // Request ID
+  app.use("*", async (c, next) => {
+    c.set("requestId", crypto.randomUUID());
+    await next();
+  });
+
+  // Auth → Tenant Context → Rate Limit (same order as production)
+  app.use("*", authMiddleware);
+  app.use("*", tenantContextMiddleware);
+  app.use("*", rateLimitMiddleware);
+
+  // Mount route handlers here...
+  return app;
+}
+```
+
+**Why lazy imports?** The auth module imports the database module, which reads `DATABASE_URL` from the environment. If imported eagerly at the top level, the test preload script might not have run yet, causing config validation to fail.
+
+## Database Cleanup
+
+Delete tables in FK dependency order to avoid constraint violations.
+
+```typescript
+// Clean tables in FK dependency order
+export async function cleanupDatabase() {
+  // Children first, parents last
+  await db.delete(apiKeys);
+  await db.delete(projects);
+  await db.delete(orgMemberships);
+  await db.delete(sessions);
+  await db.delete(accounts);
+  await db.delete(verifications);
+  await db.delete(invitations);
+  await db.delete(organizations);
+  await db.delete(users);
+}
+```
+
+**Order matters.** If you try to delete `organizations` before `projects`, the FK constraint on `projects.organization_id` will reject the delete. Start from leaf tables and work toward root tables.
+
+## Key Testing Patterns
+
+### Test Auth via API Key
+
+```typescript
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+
+describe("Protected endpoint", () => {
+  let testData: Awaited<ReturnType<typeof seedTestData>>;
+
+  beforeAll(async () => {
+    testData = await seedTestData();
+  });
+
+  afterAll(async () => {
+    await cleanupDatabase();
+  });
+
+  test("returns 200 with valid API key", async () => {
+    const app = createIntegrationApp();
+    const res = await app.request("/v1/endpoint", {
+      headers: {
+        Authorization: `Bearer ${testData.plaintextKey}`,
+      },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("returns 401 without auth", async () => {
+    const app = createIntegrationApp();
+    const res = await app.request("/v1/endpoint");
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+### Test Signup Flow
+
+```typescript
+test("signup creates user and personal org", async () => {
+  const res = await app.request("/auth/sign-up/email", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      email: `signup-test-${Date.now()}@example.com`,
+      password: "secure-password-123",
+      name: "Test User",
+    }),
+  });
+
+  expect(res.status).toBe(200);
+
+  // Verify auto-org creation via databaseHooks
+  const user = await db.select().from(users)
+    .where(eq(users.email, email)).limit(1);
+
+  const membership = await db.select().from(orgMemberships)
+    .where(eq(orgMemberships.userId, user[0].id)).limit(1);
+
+  expect(membership).toHaveLength(1);
+  expect(membership[0].role).toBe("owner");
+});
+```
+
+### Test Tenant Isolation
+
+```typescript
+test("cannot access resources from another org", async () => {
+  const org1 = await seedTestData();
+  const org2 = await seedTestData();
+
+  // Use org1's API key to try accessing org2's project
+  const res = await app.request(`/v1/projects/${org2.project.id}`, {
+    headers: { Authorization: `Bearer ${org1.plaintextKey}` },
+  });
+
+  // Should be 404 (not 403, to prevent ID enumeration)
+  expect(res.status).toBe(404);
+});
+```

package/optional-skills/generate-skill/CHECKLIST.md

@@ -0,0 +1,60 @@
+# Skill Quality Checklist
+
+Verify the generated skill against every item below before finalizing.
+
+---
+
+## Frontmatter
+
+- [ ] `name` is lowercase, hyphens and digits only, max 64 chars
+- [ ] `name` does not contain "anthropic", "claude", or "official"
+- [ ] `description` is third-person, max 1024 chars
+- [ ] `description` includes specific trigger phrases ("Use when user says...")
+- [ ] `description` first sentence states what the skill does
+- [ ] `allowed-tools` uses the minimal set needed (not all tools)
+- [ ] `argument-hint` shows expected input format if skill takes arguments
+- [ ] No XML tags in any frontmatter field values
+
+## Body Structure
+
+- [ ] Starts with a title (`#`) and one-line purpose statement
+- [ ] Lists reference files with descriptions (if multi-file)
+- [ ] Workflow uses numbered steps with `###` headings
+- [ ] Each step starts with an action verb (Parse, Read, Generate, Validate)
+- [ ] Each step has clear entry and exit criteria
+- [ ] Output format is explicitly defined
+
+## Content Quality
+
+- [ ] Instructions are explicit, not vague ("Review for X, Y, Z" not "Review the code")
+- [ ] Includes WHY context for non-obvious rules
+- [ ] Uses XML tags for complex structure (`<example>`, `<rules>`, `<output-format>`)
+- [ ] Uses "consider"/"evaluate" instead of "think"
+- [ ] Contains at least one concrete `<example>` block
+- [ ] Scope is bounded (file limits, directory limits, or explicit boundaries)
+- [ ] No conflicting instructions
+
+## Error Handling
+
+- [ ] Handles empty `$ARGUMENTS` (asks user or uses sensible detection)
+- [ ] Handles missing files (clear error message, not silent fallback)
+- [ ] Handles unexpected input (validation with actionable error)
+- [ ] No silent fallbacks to defaults (project convention)
+
+## Prompt Engineering
+
+- [ ] No over-triggering (description is specific, not generic)
+- [ ] No aggressive language ("MUST", "NEVER EVER", "ABSOLUTELY")
+- [ ] No wall of text without headings or structure
+- [ ] No unbounded scope ("analyze everything")
+- [ ] Anti-hallucination patterns applied (grounded in file content)
+- [ ] Degree of freedom matches skill type (guardrails for high, specs for low)
+
+## Completeness
+
+- [ ] All reference files mentioned in SKILL.md exist
+- [ ] Reference files have table of contents if over 100 lines
+- [ ] Reference files are one level deep (no nested references)
+- [ ] Total SKILL.md is under 500 lines (split if over)
+- [ ] Skill is self-contained (works without external dependencies)
+- [ ] Installation path is correct (`.claude/skills/<skill-name>/`)

package/optional-skills/generate-skill/PROMPT-PATTERNS.md

@@ -0,0 +1,370 @@
+# Prompt Patterns for Claude 4.6 Skills
+
+Patterns and anti-patterns for writing effective skill body content that works well with Claude 4.6 models.
+
+## Table of Contents
+
+- [Core Principles](#core-principles)
+- [Structural Patterns](#structural-patterns)
+- [Anti-Patterns](#anti-patterns)
+- [Anti-Hallucination Patterns](#anti-hallucination-patterns)
+- [Degree of Freedom Guide](#degree-of-freedom-guide)
+
+---
+
+## Core Principles
+
+### 1. Be Explicit
+
+Claude 4.6 follows instructions precisely. Vague prompts get literal interpretations.
+
+```markdown
+# Bad — vague
+Review the code and fix issues.
+
+# Good — explicit
+Review the code for:
+1. Security vulnerabilities (SQL injection, XSS, command injection)
+2. Performance anti-patterns (N+1 queries, unnecessary re-renders)
+3. Missing error handling
+
+For each issue found, output:
+- File and line number
+- Severity (critical/warning/info)
+- Description of the issue
+- Suggested fix with code snippet
+```
+
+### 2. Provide WHY Context
+
+Claude generalizes better when it understands the reasoning behind instructions.
+
+```markdown
+# Bad — no context
+Always use `const` instead of `let`.
+
+# Good — with WHY
+Use `const` by default because it signals immutability to other developers
+and prevents accidental reassignment. Only use `let` when the variable
+must be reassigned within its scope.
+```
+
+### 3. Use XML Tags for Structure
+
+XML tags create clear semantic boundaries. Use them for complex sections.
+
+```markdown
+<rules>
+- Never modify files outside the project directory
+- Always create a backup before destructive operations
+- Ask for confirmation before deleting more than 3 files
+</rules>
+
+<output-format>
+## Review Report
+- **File**: {path}
+- **Issues**: {count}
+- **Severity**: {critical|warning|info}
+</output-format>
+
+<example>
+Input: `/review src/auth.ts`
+Output: Review report with 3 issues found...
+</example>
+```
+
+### 4. Avoid "Think"
+
+When extended thinking is disabled, "think" can cause confusion. Use alternatives:
+
+| Instead of | Use |
+|---|---|
+| "Think about..." | "Consider..." |
+| "Think through..." | "Evaluate..." |
+| "Think step by step" | "Work through each step" |
+| "Let me think" | "Let me analyze" |
+
+---
+
+## Structural Patterns
+
+### Pattern 1: Workflow (Most Common)
+
+Sequential steps with clear entry/exit criteria. Best for medium-freedom skills.
+
+```markdown
+## Workflow
+
+### Step 1: Parse Input
+Extract the target from `$ARGUMENTS`.
+If empty, ask the user for the target.
+
+### Step 2: Analyze
+Read the target file(s) and identify {specific things}.
+
+### Step 3: Generate Output
+Produce {specific output format}.
+
+### Step 4: Validate
+Verify the output meets {specific criteria}.
+```
+
+**When to use**: Most skills. Provides clear structure while allowing flexibility within steps.
+
+### Pattern 2: Template (Fill-in-the-Blanks)
+
+Fixed output structure with variable content. Best for low-freedom skills.
+
+```markdown
+## Output Template
+
+Generate the following file:
+
+\```yaml
+name: {extracted-name}
+version: {detected-version}
+dependencies:
+  {for each dependency}
+  - name: {dep-name}
+    version: {dep-version}
+  {end for}
+\```
+
+Rules:
+- `name` must be lowercase with hyphens
+- `version` must follow semver (x.y.z)
+- Dependencies sorted alphabetically
+```
+
+**When to use**: Config generation, scaffolding, report generation.
+
+### Pattern 3: Decision Tree
+
+Branching logic based on input analysis. Best for skills that adapt behavior.
+
+```markdown
+## Decision Logic
+
+Analyze the input and follow the appropriate path:
+
+### Path A: Single File
+If `$ARGUMENTS` points to a single file:
+1. Read the file
+2. Analyze for {criteria}
+3. Output inline suggestions
+
+### Path B: Directory
+If `$ARGUMENTS` points to a directory:
+1. Glob for relevant files (`**/*.{ts,tsx}`)
+2. Analyze each file
+3. Output a summary report
+
+### Path C: No Input
+If `$ARGUMENTS` is empty:
+1. Detect the project type from package.json / pyproject.toml
+2. Find the most relevant files
+3. Follow Path A or Path B based on results
+```
+
+**When to use**: Skills that handle multiple input types or contexts.
+
+### Pattern 4: Conditional Workflow
+
+Workflow with conditional steps based on context. Combines workflow + decision tree.
+
+```markdown
+## Workflow
+
+### Step 1: Detect Context
+Read the project structure and determine:
+- Language (TypeScript, Python, Go, etc.)
+- Framework (Next.js, FastAPI, etc.)
+- Test runner (Jest, Pytest, etc.)
+
+### Step 2: Analyze (language-specific)
+
+**If TypeScript/JavaScript:**
+- Check for type errors with LSP
+- Scan for common JS anti-patterns
+
+**If Python:**
+- Check for type hints
+- Scan for common Python anti-patterns
+
+### Step 3: Report
+Output findings in a unified format regardless of language.
+```
+
+**When to use**: Skills that work across different project types.
+
+### Pattern 5: Examples-Driven
+
+Heavy use of examples to specify behavior. Best for high-freedom skills.
+
+```markdown
+## Behavior
+
+Generate code following these examples exactly:
+
+<example>
+Input: "a function that fetches user data"
+Output:
+\```typescript
+async function fetchUserData(userId: string): Promise<User> {
+  const response = await fetch(`/api/users/${userId}`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch user ${userId}: ${response.statusText}`);
+  }
+  return response.json();
+}
+\```
+</example>
+
+<example>
+Input: "a React hook for local storage"
+Output:
+\```typescript
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  // ...
+}
+\```
+</example>
+
+Key patterns shown in examples:
+- Always include error handling
+- Use TypeScript generics where appropriate
+- Async functions return typed Promises
+```
+
+**When to use**: Code generation, formatting, transformation skills.
+
+---
+
+## Anti-Patterns
+
+Common mistakes when writing Claude 4.6 skills:
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Over-triggering | Description matches too many scenarios | Add specific trigger phrases: `"Use when user says X, Y, Z"` |
+| Aggressive language | "You MUST", "NEVER EVER", "ABSOLUTELY" | Use calm, clear directives: "Always X", "Do not Y" |
+| Vague triggers | "Use when helpful" | Specific: "Use when reviewing TypeScript code for security" |
+| Wall of text | No structure, no headings | Break into steps with `###` headings |
+| Conflicting rules | "Be concise" + "Include all details" | Prioritize: "Be concise. Include details only for critical issues." |
+| No examples | Claude guesses at desired output | Add 1-2 concrete `<example>` blocks |
+| Unbounded scope | "Analyze everything" | Limit: "Analyze files in `src/` matching `*.ts`" |
+| Silent failures | No error handling instructions | Add: "When X fails, display the error and suggest next steps" |
+
+### Over-Triggering Fix
+
+```markdown
+# Bad — triggers on any code question
+description: Helps with code. Use for any coding task.
+
+# Good — specific triggers
+description: >
+  Generate unit tests for TypeScript functions using Jest.
+  Use when user says "generate tests", "add tests", "write tests for",
+  or when reviewing untested code.
+```
+
+### Scope Bounding
+
+```markdown
+# Bad — unbounded
+Analyze the entire codebase for issues.
+
+# Good — bounded
+Analyze files matching `$ARGUMENTS` (default: `src/**/*.ts`).
+Limit to 50 files maximum. If more files match, ask the user to narrow the scope.
+```
+
+---
+
+## Anti-Hallucination Patterns
+
+Prevent Claude from inventing information in skills:
+
+### 1. Ground in File Content
+
+```markdown
+# Bad
+Describe the project architecture.
+
+# Good
+Read `README.md`, `package.json`, and the `src/` directory structure.
+Describe the architecture based ONLY on what these files contain.
+Do not infer or assume features not present in the code.
+```
+
+### 2. Explicit Unknowns
+
+```markdown
+If you cannot determine {X} from the available files:
+- State "Unable to determine {X} from the codebase"
+- List what files you checked
+- Suggest what the user could provide to resolve this
+```
+
+### 3. Verify Before Acting
+
+```markdown
+Before generating code:
+1. Read the existing implementation in `$1`
+2. Identify the patterns already used (naming, error handling, imports)
+3. Generate code that matches these existing patterns
+Do not introduce new patterns or dependencies without explicit instruction.
+```
+
+---
+
+## Degree of Freedom Guide
+
+How much latitude to give Claude based on skill type:
+
+### High Freedom
+The skill makes autonomous decisions. Requires strong guardrails.
+
+```markdown
+## Guardrails
+- Do NOT modify files outside `$ARGUMENTS` path
+- Do NOT add new dependencies without asking
+- Do NOT delete existing code without replacement
+- Maximum 200 lines of generated code per invocation
+- Always show a diff preview before applying changes
+```
+
+**Examples**: code generation, refactoring, migration skills
+
+### Medium Freedom
+The skill follows a workflow but adapts to context. Requires clear decision criteria.
+
+```markdown
+## Decision Criteria
+- If the file has fewer than 50 lines: inline review
+- If the file has 50-500 lines: section-by-section review
+- If the file has more than 500 lines: focus on public API and entry points only
+```
+
+**Examples**: review, analysis, documentation skills
+
+### Low Freedom
+The skill executes a fixed procedure. Requires exact input/output specs.
+
+```markdown
+## Input
+- `$1`: PR number (required, integer)
+- `$2`: Template name (optional, default: "standard")
+
+## Output
+A markdown report with exactly these sections:
+1. Summary (1-2 sentences)
+2. Checklist (pass/fail for each template requirement)
+3. Missing Items (list of unfulfilled requirements)
+```
+
+**Examples**: validation, scanning, formatting skills