@dirstack/kodeks 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piotr Kulpinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Kodeks
+
+[![npm version](https://img.shields.io/npm/v/%40dirstack%2Fkodeks.svg)](https://www.npmjs.com/package/@dirstack/kodeks)
+[![license](https://img.shields.io/npm/l/%40dirstack%2Fkodeks.svg)](https://github.com/dirstack/kodeks/blob/main/LICENSE)
+
+Shared linter configurations for TypeScript projects.
+
+Kodeks provides reusable, opinionated configurations for maintaining consistent code quality across TypeScript projects.
+
+## Installation
+
+```bash
+bun add -d @dirstack/kodeks
+```
+
+This will automatically install all required dependencies.
+
+> [!NOTE]
+> All tools are installed together for simplicity, even if you only use some of the configurations. This ensures all CLIs and configs work correctly and avoids resolution issues.
+
+## Usage
+
+### oxlint Configuration
+
+Create a `.oxlintrc.json` file in your project root:
+
+```json
+{
+  "extends": ["./node_modules/@dirstack/kodeks/configs/oxlint-base.json"]
+}
+```
+
+For Next.js projects, use the Next.js preset:
+
+```json
+{
+  "extends": ["./node_modules/@dirstack/kodeks/configs/oxlint-next.json"]
+}
+```
+
+For TanStack projects, use the TanStack preset:
+
+```json
+{
+  "extends": ["./node_modules/@dirstack/kodeks/configs/oxlint-tanstack.json"]
+}
+```
+
+### oxfmt Configuration
+
+Since oxfmt does not support configuration inheritance, you have two options:
+
+**Option 1: Reference via CLI flag**
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "format": "oxfmt --config ./node_modules/@dirstack/kodeks/configs/oxfmt.json --write ."
+  }
+}
+```
+
+**Option 2: Copy configuration locally**
+
+Copy the configuration file to your project root and reference it directly:
+
+```bash
+cp ./node_modules/@dirstack/kodeks/configs/oxfmt.json .
+```
+
+Then use:
+
+```bash
+oxfmt --config ./oxfmt.json --write .
+```
+
+### Commitlint Configuration
+
+Create a `commitlint.json` file in your project root:
+
+```json
+{
+  "extends": ["./node_modules/@dirstack/kodeks/configs/commitlint.json"]
+}
+```
+
+### Lefthook Configuration
+
+Create a `lefthook.json` file in your project root and extend the hooks you need:
+
+```json
+{
+  "extends": [
+    "node_modules/@dirstack/kodeks/configs/lefthook-oxlint.json",
+    "node_modules/@dirstack/kodeks/configs/lefthook-oxfmt.json",
+    "node_modules/@dirstack/kodeks/configs/lefthook-commitlint.json"
+  ]
+}
+```
+
+**Available hooks:**
+- `lefthook-oxlint.json` - Lints and fixes staged files with oxlint (pre-commit)
+- `lefthook-oxfmt.json` - Formats staged files with oxfmt (pre-commit)
+- `lefthook-commitlint.json` - Validates commit messages (commit-msg)
+
+## Agentic Coding
+
+### Skills
+
+This package includes agent skills for code formatting, testing, and commit conventions.
+
+**Available skills:**
+- `formatting` - Code formatting rules not handled by auto-formatters (arrow functions, exports, types, naming, comments, JSX)
+- `testing` - Best practices, structure, coverage categories, and formatting conventions for writing tests
+- `commits` - Conventional commit types, scopes, and message formatting guidelines
+
+Install all skills using [skills.sh](https://skills.sh):
+
+```bash
+npx skills add dirstack/kodeks
+```
+
+Or install individual skills:
+
+```bash
+npx skills add dirstack/kodeks --skill formatting
+npx skills add dirstack/kodeks --skill testing
+npx skills add dirstack/kodeks --skill commits
+```

package/configs/commitlint.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/commitlintrc.json",
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "subject-case": [2, "always", "lower-case"]
+  }
+}

package/configs/lefthook-commitlint.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/lefthook.json",
+  "commit-msg": {
+    "commands": {
+      "lint:commitlint": {
+        "run": "bunx commitlint --config ./commitlint.json --edit {1}"
+      }
+    }
+  }
+}

package/configs/lefthook-oxfmt.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/lefthook.json",
+  "pre-commit": {
+    "parallel": true,
+    "commands": {
+      "format:oxfmt": {
+        "glob": "*.{ts,tsx,js,jsx,json,jsonc,css}",
+        "run": "bunx oxfmt --write {staged_files}",
+        "stage_fixed": true
+      }
+    }
+  }
+}

package/configs/lefthook-oxlint.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/lefthook.json",
+  "pre-commit": {
+    "parallel": true,
+    "commands": {
+      "lint:oxlint": {
+        "glob": "*.{ts,tsx,js,jsx}",
+        "run": "bunx oxlint --fix --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}",
+        "stage_fixed": true
+      }
+    }
+  }
+}

package/configs/lefthook-typescript.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/lefthook.json",
+  "pre-commit": {
+    "commands": {
+      "typecheck": {
+        "glob": "*.{ts,tsx}",
+        "run": "bunx tsc --noEmit"
+      }
+    }
+  }
+}

package/configs/oxfmt.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/refs/heads/main/npm/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": false,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "experimentalSortImports": {
+    "enabled": true,
+    "groups": [
+      ["side_effect"],
+      ["value-builtin", "type-builtin"],
+      ["value-external", "type-external"],
+      ["value-internal", "type-internal"]
+    ],
+    "newlinesBetween": false
+  }
+}

package/configs/oxlint-base.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/refs/heads/main/npm/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "jsx-a11y", "oxc"],
+  "rules": {
+    "react-hooks/exhaustive-deps": "off",
+    "jsx-a11y/anchor-has-content": "off",
+    "jsx-a11y/heading-has-content": "off"
+  }
+}

package/configs/oxlint-next.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/refs/heads/main/npm/oxlint/configuration_schema.json",
+  "extends": ["./oxlint-base.json"],
+  "plugins": ["nextjs"],
+  "rules": {
+    "nextjs/no-img-element": "off",
+    "nextjs/no-html-link-for-pages": "off"
+  }
+}

package/configs/oxlint-tanstack.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/refs/heads/main/npm/oxlint/configuration_schema.json",
+  "extends": ["./oxlint-base.json"]
+}

package/configs/semantic-release-dry-run.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/semantic-release.json",
+  "branches": [
+    "main",
+    { "name": "beta", "channel": "beta", "prerelease": "beta" },
+    { "name": "alpha", "channel": "alpha", "prerelease": "alpha" },
+    { "name": "next", "channel": "next", "prerelease": "next" }
+  ],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [{ "breaking": true, "release": "major" }]
+      }
+    ]
+  ]
+}

package/configs/semantic-release.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/semantic-release.json",
+  "branches": [
+    "main",
+    { "name": "beta", "channel": "beta", "prerelease": "beta" },
+    { "name": "alpha", "channel": "alpha", "prerelease": "alpha" },
+    { "name": "next", "channel": "next", "prerelease": "next" }
+  ],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [{ "breaking": true, "release": "major" }]
+      }
+    ],
+    ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits" }],
+    ["@semantic-release/npm", { "provenance": true }],
+    "@semantic-release/github"
+  ]
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dirstack/kodeks",
+  "description": "Shared linter configurations for TypeScript projects.",
+  "homepage": "https://github.com/dirstack/kodeks#readme",
+  "bugs": {
+    "url": "https://github.com/dirstack/kodeks/issues"
+  },
+  "license": "MIT",
+  "author": "Piotr Kulpinski",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dirstack/kodeks"
+  },
+  "files": [
+    "configs",
+    "skills"
+  ],
+  "type": "module",
+  "exports": {
+    "./oxlint": "./configs/oxlint-base.json",
+    "./oxlint-next": "./configs/oxlint-next.json",
+    "./oxlint-tanstack": "./configs/oxlint-tanstack.json",
+    "./commitlint": "./configs/commitlint.json",
+    "./semantic-release": "./configs/semantic-release.json",
+    "./semantic-release-dry-run": "./configs/semantic-release-dry-run.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "lefthook install"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.2",
+    "@commitlint/config-conventional": "^20.4.2",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "lefthook": "^2.1.1",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@commitlint/cli": ">=20.4.2",
+    "@commitlint/config-conventional": ">=20.4.2",
+    "conventional-changelog-conventionalcommits": ">=9.1.0",
+    "lefthook": ">=2.1.1",
+    "oxfmt": ">=0.35.0",
+    "oxlint": ">=1.50.0",
+    "semantic-release": ">=25.0.3",
+    "typescript": ">=5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "packageManager": "bun@1.3.9",
+  "version": "1.0.0"
+}

package/skills/commits/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: commits
+description: Conventional commit message guidelines. Use when writing commit messages, reviewing commits, or when asked to commit changes. Covers commit types, subject rules (lowercase, imperative), atomic commits, and examples of good vs bad messages.
+---
+
+# Commit Convention
+
+Guidelines for writing consistent and clear commit messages.
+
+## Format
+
+```
+<type>: <description>
+```
+
+- No scope required.
+- No body or footer for simple changes.
+- Max 72 characters for the subject line.
+
+## Types
+
+- `feat` — new feature or capability
+- `fix` — bug fix
+- `docs` — documentation only changes
+- `style` — code style/formatting (no logic changes)
+- `refactor` — code restructuring (no feature, no fix)
+- `perf` — performance improvements
+- `test` — adding or updating tests
+- `build` — build system or dependency changes
+- `ci` — CI/CD configuration changes
+- `chore` — maintenance tasks, configs
+- `revert` — reverting a previous commit
+
+## Subject Rules
+
+- **lowercase**: description starts with a lowercase letter.
+- **imperative mood**: use "add", not "added" or "adds".
+- **no period**: do not end the subject with a period.
+- **max 72 chars**: keep it concise.
+
+## Atomic Commits
+
+One logical change per commit. If the description requires "and", consider splitting the changes into separate commits.
+
+## Breaking Changes
+
+Use the `!` suffix after the type for breaking changes:
+
+```
+feat!: remove deprecated API endpoint
+```
+
+## Good vs Bad Examples
+
+### Good
+- `feat: add user authentication flow`
+- `fix: resolve login redirect loop`
+- `refactor: extract validation logic into separate module`
+- `docs: update API documentation for v2 endpoints`
+- `chore: update dependencies to latest versions`
+
+### Bad
+- `feat: Added user authentication` (past tense)
+- `fix: Bug fix` (vague)
+- `feat: add user auth and update profile page` (multiple logical changes)
+- `FEAT: Add user auth` (uppercase type)
+- `feat: Add user auth` (uppercase description)

package/skills/formatting/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: formatting
+description: Code formatting and style rules not handled by auto-formatters (oxfmt). Use when writing or modifying TypeScript/React code. Covers function declarations, exports, types, comments, JSX, naming conventions, and import patterns.
+---
+
+# Code Formatting Rules
+
+Style guide for code formatting decisions not handled by auto-formatters (oxfmt).
+
+## 1. Function Declaration Style
+
+Always use arrow functions with explicit types. Avoid the `function` keyword for components and utilities.
+
+```typescript
+// Correct
+export const processData = (input: string): string => {
+  return `Processed: ${input}`
+}
+
+// Avoid
+export function processData(input: string): string {
+  return "Processed: " + input
+}
+```
+
+---
+
+## 2. Export Patterns
+
+Use named exports only. Never use default exports.
+
+```typescript
+// Correct
+export const Button = () => {
+  return <button>Click me</button>
+}
+
+// Avoid
+const Button = () => {
+  return <button>Click me</button>
+}
+export default Button
+```
+
+---
+
+## 3. Early Returns
+
+Use early returns for validation and edge cases to keep the main logic flat.
+
+```typescript
+export const processUser = (user: User | null) => {
+  if (!user) {
+    return
+  }
+
+  if (!user.isActive) {
+    return
+  }
+
+  return doSomething(user)
+}
+```
+
+---
+
+## 4. Type Definitions
+
+Prefer `type` over `interface`. Use namespaces for related types and generics for reusable structures.
+
+```typescript
+// Correct
+export type User = {
+  id: string
+  name: string
+}
+
+// Avoid
+export interface User {
+  id: string
+  name: string
+}
+
+// Namespaces for related types
+export namespace UserApi {
+  export type Request = {
+    userId: string
+  }
+  export type Response = {
+    user: User
+  }
+}
+```
+
+---
+
+## 5. File Structure
+
+Follow a standard file order to maintain consistency across the codebase:
+1. Imports (grouped: builtin, external, internal)
+2. Type definitions
+3. Constants and Helpers
+4. Main exports (Components/Functions)
+
+---
+
+## 6. Curly Braces
+
+Always use curly braces for arrow functions, even for single-line returns.
+
+```typescript
+// Correct
+export const getName = (user: User) => {
+  return user.name
+}
+
+// Avoid
+export const getName = (user: User) => user.name
+```
+
+---
+
+## 7. Variable Naming
+
+Use full, descriptive words. Avoid abbreviations like `err`, `req`, `res`, or `btn`.
+
+```typescript
+// Correct
+const error = new Error("Failed")
+const request = await fetch(url)
+const button = document.querySelector("button")
+
+// Avoid
+const err = new Error("Failed")
+const req = await fetch(url)
+const btn = document.querySelector("button")
+```
+
+**Function name prefixes:**
+- `parse*` (e.g., `parseInput`)
+- `generate*` (e.g., `generateId`)
+- `get*` / `fetch*` (e.g., `getUser`)
+- `is*` / `has*` (e.g., `isValid`, `hasPermission`)
+- `validate*` (e.g., `validateEmail`)
+
+---
+
+## 8. Comments
+
+Write comments as full sentences with proper capitalization and punctuation. Place them above the subject.
+
+```typescript
+// Correct
+// This calculates the final price including tax and discounts.
+const finalPrice = calculatePrice(items)
+
+// Avoid
+const finalPrice = calculatePrice(items) // calculate price
+```
+
+**Inline comments** are allowed for arrays, object properties, and complex types:
+```typescript
+export type Config = {
+  timeout: number // Timeout in milliseconds.
+  retries: number // Number of retry attempts.
+}
+```
+
+---
+
+## 9. Array Type Syntax
+
+Use the generic `Array<T>` syntax instead of the `T[]` shorthand.
+
+```typescript
+// Correct
+const tags: Array<string> = ["react", "typescript"]
+
+// Avoid
+const tags: string[] = ["react", "typescript"]
+```
+
+---
+
+## 10. Nullish Coalescing
+
+Use the nullish coalescing operator `??` instead of logical OR `||` for default values.
+
+```typescript
+// Correct
+const port = process.env.PORT ?? 3000
+const username = user.name ?? "Anonymous"
+
+// Avoid
+const port = process.env.PORT || 3000
+```
+
+---
+
+## 11. Template Literals
+
+Always use template literals for string composition. Never use `+` for string concatenation.
+
+```typescript
+// Correct
+const message = `Hello, ${user.name}!`
+
+// Avoid
+const message = "Hello, " + user.name + "!"
+```
+
+---
+
+## 12. Bare Return
+
+When a function returns `| undefined`, use a bare `return` instead of `return undefined`.
+
+```typescript
+// Correct
+export const findItem = (items: Array<Item>, id: string): Item | undefined => {
+  const item = items.find((i) => { return i.id === id })
+  if (!item) {
+    return
+  }
+  return item
+}
+
+// Avoid
+if (!item) {
+  return undefined
+}
+```
+
+---
+
+## 13. Void Prefix
+
+Use the `void` operator for intentionally non-awaited async calls (fire-and-forget).
+
+```typescript
+// Correct
+void trackEvent("page_view")
+
+// Avoid
+trackEvent("page_view")
+```
+
+---
+
+## 14. Empty Catch
+
+Use an empty `catch {}` block for expected or ignorable failures, and return a safe default.
+
+```typescript
+export const safeParseJson = (json: string): unknown => {
+  try {
+    return JSON.parse(json)
+  } catch {}
+}
+```
+
+---
+
+## 15. Config via Constants
+
+Isolate all `process.env` access in dedicated constants or environment modules. Business logic should never touch `process.env`.
+
+```typescript
+// Correct (in ~/lib/env.ts)
+export const DATABASE_URL = process.env.DATABASE_URL
+
+// Avoid (in business logic)
+const client = new Client(process.env.DATABASE_URL)
+```
+
+---
+
+## 16. JSX Attributes
+
+Order attributes logically: `id` first, then standard props, then `className`, and finally event handlers (`on*`).
+
+```tsx
+// Correct
+<Button
+  id="submit-btn"
+  type="submit"
+  disabled={isLoading}
+  className="w-full bg-blue-500"
+  onClick={handleSubmit}
+>
+  Submit
+</Button>
+```
+
+---
+
+## 17. Path Aliases
+
+Always use `~/*` path aliases for imports. Never use relative paths like `./` or `../`.
+
+```typescript
+// Correct
+import { Button } from "~/components/ui/button"
+
+// Avoid
+import { Button } from "../../components/ui/button"
+```
+
+---
+
+## 18. TypeScript Strict
+
+Maintain strict TypeScript usage. Never use `any`. Use `unknown` if the type is truly unknown, or define a specific type/interface.
+
+```typescript
+// Correct
+export const handleData = (data: unknown) => {
+  if (typeof data === "string") {
+    return data.toUpperCase()
+  }
+}
+
+// Avoid
+export const handleData = (data: any) => {
+  return data.toUpperCase()
+}
+```

package/skills/testing/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: testing
+description: Guide for writing comprehensive, well-structured tests with full coverage. Use when creating test files, adding tests to existing files, reviewing test coverage, or when asked to write, fix, or expand tests. Covers test organization (flat vs nested), coverage categories (happy/sad/edge), .todo patterns for planned tests, and formatting conventions.
+---
+
+# Test Writing Guide
+
+Detect the test library from project (bun:test, vitest, jest, etc.) and use its idioms. Never assume a specific framework.
+
+## File Conventions
+
+- Test files use `*.test.ts` naming
+- Co-locate tests next to their source file (not in `__tests__/` directories)
+- Example: `src/lib/utils/validators.ts` → `src/lib/utils/validators.test.ts`
+
+## Structure: Flat vs Nested
+
+**Flat** — for pure/simple functions (parsers, validators, formatters):
+
+```typescript
+import { describe, it, expect } from "bun:test"
+
+describe("functionName", () => {
+  it("should return X with valid input", () => {
+    // ...
+  })
+
+  it("should return undefined for empty string", () => {
+    // ...
+  })
+})
+```
+
+**Nested 3-category** — for complex functions (DB operations, API handlers, side effects):
+
+```typescript
+import { describe, it, expect } from "bun:test"
+
+describe("functionName", () => {
+  describe("happy paths", () => {
+    it("should create record with all fields", async () => {
+      // ...
+    })
+
+    it("should create record with minimal fields", async () => {
+      // ...
+    })
+  })
+
+  describe("sad paths", () => {
+    it("should throw NotFoundError when record missing", async () => {
+      // ...
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle duplicate operation idempotently", async () => {
+      // ...
+    })
+  })
+})
+```
+
+**When to use which:**
+- Side effects, external deps, DB, API calls → nested
+- Pure transformation, parser, validator → flat
+- Flat file growing beyond ~15 tests → consider switching to nested
+
+## Coverage Categories
+
+**Happy paths** — normal successful operations:
+- Success with full/complete input
+- Success with minimal/partial input
+- Expected return values and side effects
+
+**Sad paths** — expected failures:
+- Thrown exceptions (NotFoundError, ValidationError, etc.)
+- Validation failures on invalid input
+- Unauthorized/wrong-user access
+- Missing required data or dependencies
+
+**Edge cases** — boundary conditions:
+- Idempotency (repeating the same operation)
+- Pagination and cursor handling
+- Null, empty, or zero values
+- Concurrent or conflicting operations
+- Already-existing data (upsert behavior)
+- Computed/derived fields and timestamps
+
+## Coverage Checklist
+
+For every function, consider:
+1. What does success look like with full input?
+2. What does success look like with minimal input?
+3. What errors can this function throw?
+4. What happens with unauthorized/wrong-user access?
+5. What are the boundary conditions?
+6. What if the operation is repeated (idempotent)?
+7. What if related data is missing or empty?
+
+Implement the most critical tests first (happy paths). Use `.todo` for the rest.
+
+## Principles
+
+- **Test behavior, not implementation** — test through public API. If behavior doesn't change, tests shouldn't break. If private logic is complex, extract it into its own module and test that.
+- **Mock at boundaries only** — mock external services (HTTP, email, payment), never your own DB or internal modules. Prefer stubs/spies over mocks (verify state, not calls).
+- **Each test is self-contained** — never rely on test execution order. No shared mutable state. Reset mocks in `beforeEach`.
+- **Hard-code expected values** — never compute them with string concat, loops, or conditionals in test code.
+- **Use realistic data** — not "foo"/"bar". Include only data relevant to the specific test.
+- **One behavior per test** — no piggyback assertions testing unrelated things.
+- **Convert production bugs to regression tests** — every bug gets a test before fixing.
+
+For detailed guidance on mocking, isolation, data patterns, and common anti-patterns, see [references/best-practices.md](references/best-practices.md).
+
+## The .todo Pattern
+
+Use `it.todo` for planned but unimplemented tests. Every `.todo` MUST include a comment inside the callback body explaining the scenario:
+
+```typescript
+import { it } from "bun:test"
+
+// Simple scenario — single sentence.
+it.todo("should preserve existing title when feed title is null", () => {
+  // Feed has null title — channel should keep its existing title.
+})
+
+// Complex scenario — multi-line with setup and expected behavior.
+it.todo("should timeout when headers delayed beyond maxTimeout", () => {
+  // Server delays sending headers for 16+ seconds (> maxTimeout: 15s).
+  // Expected: ETIMEDOUT error after ~15 seconds, retry triggered,
+  // after 3 retries throw UnreachableUrlError.
+})
+```
+
+Use `describe.todo` for entire groups of planned tests:
+
+```typescript
+import { describe, it } from "bun:test"
+
+describe.todo("error handling", () => {
+  it.todo("should throw on invalid URL", () => {
+    // Pass malformed URL like "not-a-url" or "ht!tp://bad".
+    // Expected: URL parse error before safety check runs.
+  })
+})
+```
+
+**Guidelines:**
+- Never leave a `.todo` without a comment
+- Comments go inside the callback, not above `it.todo`
+- Implement happy paths first, `.todo` sad paths and edge cases when not immediately critical
+
+## Formatting Reference
+
+Code examples should follow these conventions:
+- Use double quotes for strings
+- No semicolons
+- Arrow functions for test callbacks
+- `bun:test` as primary reference for `describe`, `it`, `expect`

package/skills/testing/references/best-practices.md

@@ -0,0 +1,59 @@
+# Testing Best Practices
+
+Detailed guidance for writing high-quality tests with `bun:test`.
+
+## Mocking Strategies
+
+- **Mock at boundaries**: Focus on mocking external systems like third-party APIs (Stripe, Resend, IPinfo), file system access, or network requests.
+- **Avoid mocking internals**: Don't mock your own database (use a test database or Prisma's client features), local utility functions, or internal business logic modules.
+- **`mock()` vs `mock.module()`**:
+    - Use `mock()` for simple function mocks or spies.
+    - Use `mock.module()` for entire module replacements.
+    - **CRITICAL**: `mock.module()` leaks across files in the same Bun process. Avoid using it for service modules in orchestrator-level tests where parallel execution might occur.
+
+```typescript
+import { mock, it, expect } from "bun:test"
+
+const myMock = mock(() => "result")
+expect(myMock()).toBe("result")
+expect(myMock).toHaveBeenCalled()
+```
+
+## Test Isolation
+
+- **No shared state**: Every test should be able to run in any order. Avoid global variables that change during tests.
+- **`beforeEach` reset**: Always clear mocks and reset database state before each test.
+- **Independent data**: Create the data you need within the test or in a `beforeEach` block rather than relying on existing state.
+
+```typescript
+import { beforeEach, mock } from "bun:test"
+import { myService } from "~/lib/services/myService"
+
+mock.module("~/lib/services/externalApi", () => ({
+  fetchData: mock(() => Promise.resolve({ success: true }))
+}))
+
+beforeEach(() => {
+  // Clear mock history between tests
+})
+```
+
+## Data Patterns
+
+- **Realistic data**: Use data that resembles production values. Instead of "test", "foo", or "bar", use "user_123", "example.com", or "192.168.1.1".
+- **Minimal relevance**: Only include fields in your test objects that are relevant to the behavior being tested.
+- **Fixed expectations**: Hard-code your expected results. If you calculate them in the test, you might just be duplicating the bug in the production code.
+
+## Common Anti-patterns
+
+- **Testing implementation**: If you're checking private methods or specific internal variables, your tests will break when you refactor, even if the feature still works.
+- **Over-mocking**: Mocking everything makes your tests pass even if the real integration is broken.
+- **Piggyback assertions**: Adding unrelated checks to a single test makes it harder to diagnose failures. One test, one behavior.
+
+## framework-specific notes for bun:test
+
+- **`mock()`**: Creates a mock function.
+- **`spyOn()`**: Wraps an existing method to track calls while preserving original behavior.
+- **`mock.module()`**: Replaces a module for the entire process.
+- **Snapshots**: Use `expect(value).toMatchSnapshot()` for complex object comparisons.
+- **Cleanup**: Bun automatically handles some cleanup, but manual mock restoration is often safer in complex suites.