My 2026 Developer Productivity Stack (Tools, Workflow & Hard Lessons)

return {
  {
    'LazyVim/LazyVim',
    opts = {
      colorscheme = 'tokyonight-storm',
    },
  },
  -- TypeScript language server
  {
    'neovim/nvim-lspconfig',
    opts = {
      servers = {
        -- ts_ls is the correct server name in nvim-lspconfig 2025+
        -- (renamed from tsserver in earlier versions)
        ts_ls = {
          settings = {
            typescript = {
              inlayHints = {
                includeInlayParameterNameHints = 'all',
                includeInlayFunctionParameterTypeHints = true,
                includeInlayVariableTypeHints = true,
              },
            },
          },
        },
        -- Biome as LSP for lint diagnostics inline
        biome = {},
      },
    },
  },
  -- Format on save via Biome
  {
    'stevearc/conform.nvim',
    opts = {
      formatters_by_ft = {
        typescript = { 'biome' },
        typescriptreact = { 'biome' },
        javascript = { 'biome' },
        javascriptreact = { 'biome' },
        json = { 'biome' },
        jsonc = { 'biome' },
      },
      -- Format on save, but not if save is triggered by autoread
      format_on_save = { timeout_ms = 500, lsp_fallback = true },
    },
  },
  -- Git integration
  {
    'lewis6991/gitsigns.nvim',
    opts = {
      signs = {
        add = { text = '+' },
        change = { text = '~' },
        delete = { text = '_' },
      },
    },
  },
}

# Project Conventions for AI Assistance
# Last updated: 2026-04-14
# These rules apply to all AI-generated code in this repository

## What AI should generate
- Boilerplate: CRUD operations, type definitions, component shells
- Refactoring: renames, extractions, import path updates
- Test structure: describe blocks, test names, mock setup
- Documentation: JSDoc comments, README sections

## What AI must NOT generate without explicit human review
- Financial calculations, aggregations, or reconciliation logic
- Authentication or authorization logic
- Boundary conditions in date ranges, pagination, or numeric comparisons
- Database migration files — generate the schema change, human writes the migration
- Security-sensitive operations: encryption, token validation, input sanitization

## Code Style
- TypeScript strict mode — no `any` types, no `as` type assertions without a comment
- Use Zod for runtime validation at all API boundaries (Server Actions, API routes)
- Prefer `async/await` over `.then()` chains
- Return Result types for errors in library code — never throw except in React error boundaries
- Named exports only — no default exports

## Architecture
- React Server Components by default — add 'use client' only for interactivity or browser APIs
- Server Actions for all mutations — no REST endpoints for internal operations
- Database access through repository functions in src/db/repositories/ — no Drizzle queries in components
- Environment variables accessed only through src/env.ts (validated with Zod at startup)

## Testing
- Vitest for unit and integration tests — colocated at src/**/*.test.ts
- Playwright for E2E — one test file per critical user journey in e2e/
- AI generates test structure (describe, it, beforeEach) — humans write business logic assertions
- Boundary conditions MUST be written manually: date ranges, pagination edges, null/undefined handling

## Import conventions
- Import from barrel exports in src/components/ui — not direct file paths
- Import types with `import type` — enforced by Biome
- No barrel exports (index.ts) for internal modules — import directly from source

## Anti-patterns — flag and reject
- useEffect for data fetching — use Server Components or use() hook
- Raw Drizzle queries in React components — use repository functions
- Hardcoded color values in Tailwind — use semantic tokens from globals.css @theme
- forwardRef wrappers — ref is a standard prop in React 19

{
  "name": "@acme/app",
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "test": "bun test",
    "test:watch": "bun test --watch",
    "test:coverage": "bun test --coverage",
    "test:node": "node --experimental-vm-modules node_modules/.bin/vitest run",
    "lint": "biome check --write .",
    "lint:ci": "biome ci .",
    "typecheck": "tsc --noEmit",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio",
    "db:seed": "bun run src/db/seed.ts",
    "setup": "bun install && bun run db:migrate && bun run db:seed && cp .env.example .env.local",
    "setup:verify": "bun run typecheck && bun run lint:ci && bun test"
  },
  "dependencies": {
    "next": "15.x",
    "react": "19.x",
    "react-dom": "19.x",
    "drizzle-orm": "latest",
    "@neondatabase/serverless": "latest",
    "zod": "^3",
    "@t3-oss/env-nextjs": "latest"
  },
  "devDependencies": {
    "@biomejs/biome": "latest",
    "typescript": "5.x",
    "drizzle-kit": "latest",
    "@playwright/test": "latest",
    "husky": "latest",
    "lint-staged": "latest",
    "commitlint": "latest",
    "@commitlint/config-conventional": "latest"
  }
}

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "inputs": [
        "src/**",
        "tsconfig.json",
        "package.json",
        "next.config.ts",
        "tailwind.config.ts"
      ]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": [
        "src/**",
        "test/**",
        "vitest.config.ts",
        "bun.test.ts"
      ]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": [],
      "inputs": ["src/**", "tsconfig.json"]
    },
    "lint": {
      "dependsOn": [],
      "outputs": [],
      "inputs": ["src/**", "biome.json"]
    },
    "db:generate": {
      "cache": false,
      "outputs": ["drizzle/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

{
  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "ignore": ["node_modules", ".next", "dist", "coverage", "drizzle"]
  },
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "error"
      },
      "style": {
        "noNonNullAssertion": "warn",
        "useImportType": "error",
        "noDefaultExport": "warn"
      },
      "suspicious": {
        "noExplicitAny": "error",
        "noConsoleLog": "warn"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "asNeeded",
      "trailingCommas": "all",
      "arrowParentheses": "always"
    }
  }
}

#!/usr/bin/env bash
# tmux session manager
# Usage: tms [project-name]
# If no project name given, uses current directory name
# Idempotent: attaches to existing session if it exists

set -euo pipefail

PROJECT_NAME=${1:-$(basename "$(pwd)")}
SESSION="dev-${PROJECT_NAME}"
PROJECT_DIR=${2:-$(pwd)}

# Check if session already exists
if tmux has-session -t "$SESSION" 2>/dev/null; then
  echo "Attaching to existing session: $SESSION"
  tmux attach-session -t "$SESSION"
  exit 0
fi

echo "Creating new session: $SESSION"

# Window 1: Editor
tmux new-session -d -s "$SESSION" -n editor -c "$PROJECT_DIR"
tmux send-keys -t "$SESSION:editor" 'nvim .' Enter

# Window 2: Dev server
tmux new-window -t "$SESSION" -n server -c "$PROJECT_DIR"
tmux send-keys -t "$SESSION:server" 'bun run dev' Enter

# Window 3: Git (lazygit)
tmux new-window -t "$SESSION" -n git -c "$PROJECT_DIR"
tmux send-keys -t "$SESSION:git" 'lazygit' Enter

# Window 4: Logs — tails Fly.io logs for the app matching project name
# Falls back to local docker compose logs if fly cli not available
tmux new-window -t "$SESSION" -n logs -c "$PROJECT_DIR"
if command -v flyctl &>/dev/null; then
  tmux send-keys -t "$SESSION:logs" "flyctl logs --app ${PROJECT_NAME} --tail" Enter
else
  tmux send-keys -t "$SESSION:logs" 'docker compose logs -f --tail=100' Enter
fi

# Window 5: Tests in watch mode
tmux new-window -t "$SESSION" -n tests -c "$PROJECT_DIR"
tmux send-keys -t "$SESSION:tests" 'bun test --watch' Enter

# Return to editor
tmux select-window -t "$SESSION:editor"

tmux attach-session -t "$SESSION"

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
  # Skip env validation in CI — secrets are injected directly
  SKIP_ENV_VALIDATION: 'true'

jobs:
  verify:
    name: Typecheck and Unit Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Type check
        run: bun run typecheck

      - name: Unit tests
        run: bun test --coverage
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

      - name: Security lint
        run: bunx eslint --config eslint.security.config.js 'src/**/*.{ts,tsx}'

  integrate:
    name: Build and Integration Tests
    needs: verify
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Build (with Turborepo cache)
        run: bun run build
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

      - name: Run database migrations on test branch
        run: bun run db:migrate
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

      - name: Integration tests
        run: bun test --testPathPattern='*.integration.test.ts'
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

  e2e:
    name: End-to-End Tests
    needs: integrate
    # E2E only runs on main — too expensive to run on every PR
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Install Playwright browsers
        run: bunx playwright install --with-deps chromium

      - name: Run E2E tests
        run: bunx playwright test
        env:
          PLAYWRIGHT_BASE_URL: ${{ secrets.STAGING_URL }}

  deploy-preview:
    name: Deploy Preview
    needs: integrate
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel preview
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          scope: ${{ secrets.VERCEL_ORG_ID }}

  deploy-production:
    name: Deploy Production
    needs: [integrate, e2e]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel production
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'
          scope: ${{ secrets.VERCEL_ORG_ID }}

import { pgTable, text, timestamp, uuid, integer, boolean, decimal } from 'drizzle-orm/pg-core'

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
})

export const subscriptions = pgTable('subscriptions', {
  id: uuid('id').primaryKey().defaultRandom(),
  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
  planId: text('plan_id').notNull(),
  status: text('status', {
    enum: ['active', 'cancelled', 'past_due', 'trialing'],
  }).notNull(),
  currentPeriodStart: timestamp('current_period_start', { withTimezone: true }).notNull(),
  currentPeriodEnd: timestamp('current_period_end', { withTimezone: true }).notNull(),
  // Financial columns — boundary conditions tested manually
  // See: production incident in this article
  cancelledAt: timestamp('cancelled_at', { withTimezone: true }),
  trialEndsAt: timestamp('trial_ends_at', { withTimezone: true }),
})

// Type exports — derived from schema, no codegen required
export type User = typeof users.$inferSelect
export type NewUser = typeof users.$inferInsert
export type Subscription = typeof subscriptions.$inferSelect
export type NewSubscription = typeof subscriptions.$inferInsert

import { withSentryConfig } from '@sentry/nextjs'
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    // Turbopack is stable in Next.js 15+ — enabled by default with next dev --turbopack
    // ppr: true, // Partial Prerendering — evaluate for your use case
  },
  // Enforce that all environment variables are validated at build time
  // via src/env.ts — missing variables fail the build, not the runtime
  serverExternalPackages: ['@neondatabase/serverless'],
}

export default withSentryConfig(nextConfig, {
  // Sentry organization and project from environment variables
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  // Upload source maps to Sentry at build time
  // Allows production errors to show original TypeScript source
  silent: true,
  widenClientFileUpload: true,
  // Hide source maps from client bundle — uploaded to Sentry only
  hideSourceMaps: true,
  disableLogger: true,
})

import { describe, it, expect, beforeEach } from 'bun:test'
import { getSubscriptionsInPeriod } from './subscriptions'
import { db } from '@/db/client'
import { subscriptions } from '@/db/schema'
import { testDb } from '@/test/helpers/db'

// These tests were written manually after the production incident
// They test the SPECIFICATION (inclusive boundaries) not the implementation
// Do not replace with AI-generated tests

describe('getSubscriptionsInPeriod', () => {
  beforeEach(async () => {
    await testDb.reset()
    await testDb.seed.subscriptions()
  })

  it('includes subscriptions starting exactly on the start date (inclusive boundary)', async () => {
    const startDate = new Date('2026-01-01T00:00:00Z')
    const endDate = new Date('2026-01-31T23:59:59Z')

    // Subscription starting exactly at startDate must be included
    await testDb.insert.subscription({
      currentPeriodStart: startDate, // exactly on boundary
      currentPeriodEnd: new Date('2026-01-31T00:00:00Z'),
      status: 'active',
    })

    const results = await getSubscriptionsInPeriod(startDate, endDate)

    expect(results).toHaveLength(1)
    // Business rule: period start is inclusive — subscriptions starting on the
    // exact start date are part of the period
  })

  it('includes subscriptions ending exactly on the end date (inclusive boundary)', async () => {
    const startDate = new Date('2026-01-01T00:00:00Z')
    const endDate = new Date('2026-01-31T23:59:59Z')

    // Subscription ending exactly at endDate must be included
    await testDb.insert.subscription({
      currentPeriodStart: new Date('2026-01-15T00:00:00Z'),
      currentPeriodEnd: endDate, // exactly on boundary
      status: 'active',
    })

    const results = await getSubscriptionsInPeriod(startDate, endDate)

    expect(results).toHaveLength(1)
    // Business rule: period end is inclusive — subscriptions ending on the
    // exact end date are part of the period
  })

  it('excludes subscriptions starting after the end date', async () => {
    const startDate = new Date('2026-01-01T00:00:00Z')
    const endDate = new Date('2026-01-31T23:59:59Z')

    await testDb.insert.subscription({
      currentPeriodStart: new Date('2026-02-01T00:00:00Z'), // one day after endDate
      currentPeriodEnd: new Date('2026-02-28T00:00:00Z'),
      status: 'active',
    })

    const results = await getSubscriptionsInPeriod(startDate, endDate)

    expect(results).toHaveLength(0)
  })

  it('returns empty array when no subscriptions exist in period', async () => {
    const startDate = new Date('2025-01-01T00:00:00Z')
    const endDate = new Date('2025-01-31T23:59:59Z')

    const results = await getSubscriptionsInPeriod(startDate, endDate)

    expect(results).toHaveLength(0)
  })
})