@c0x12c/ai-toolkit 1.15.0

package/commands/spartan/deploy.md

@@ -0,0 +1,207 @@
+---
+name: spartan:deploy
+description: Deployment guide and checklist for Railway (primary), AWS, or GCP. Validates readiness, generates config, and walks through the deployment steps.
+argument-hint: "[service name] [railway | aws | gcp]"
+---
+
+# Deploy: {{ args[0] }}
+Target: {{ args[1] | default: "railway" }}
+
+---
+
+## Pre-flight Checklist (run first, always)
+
+```bash
+# Tests must all pass
+./gradlew test                          # Kotlin BE
+npm test -- --run 2>/dev/null           # Next.js FE (if applicable)
+
+# Build must succeed
+./gradlew build -x test                 # Kotlin
+npm run build 2>/dev/null               # Next.js
+
+# No uncommitted changes
+git status
+git diff --stat
+
+# Current branch
+git branch --show-current
+```
+
+**Blocker:** Any failing test or build error = do NOT deploy.
+
+---
+
+{% if args[1] == "railway" or args[1] == nil %}
+## Railway Deployment
+
+### First-time setup (new service)
+
+```bash
+# Install Railway CLI if needed
+npm install -g @railway/cli
+
+# Login
+railway login
+
+# Link to project (if not already)
+railway link
+
+# Check current project
+railway status
+```
+
+### Validate railway.toml
+
+Ensure `railway.toml` exists at project root:
+
+```toml
+[build]
+builder = "nixpacks"
+
+[deploy]
+# Kotlin/Micronaut:
+startCommand = "java -jar build/libs/*-all.jar"
+# OR: startCommand = "./gradlew bootRun"
+
+# Next.js:
+# startCommand = "npm start"
+
+healthcheckPath = "/health"      # Kotlin
+# healthcheckPath = "/api/health"         # Next.js custom
+healthcheckTimeout = 60
+restartPolicyType = "on-failure"
+restartPolicyMaxRetries = 3
+```
+
+### Environment variables check
+
+```bash
+# List current vars
+railway variables
+
+# Set missing vars (one by one)
+railway variables set KEY=value
+
+# Critical vars to verify for Kotlin BE:
+# DATASOURCES_DEFAULT_URL
+# DATASOURCES_DEFAULT_USERNAME  
+# DATASOURCES_DEFAULT_PASSWORD
+# MICRONAUT_ENVIRONMENTS=prod
+
+# Critical vars for Next.js:
+# NEXT_PUBLIC_API_URL (pointing to BE service)
+# Any auth secrets
+```
+
+### Deploy
+
+```bash
+# Deploy current branch
+railway up
+
+# Or deploy a specific service
+railway up --service [service-name]
+
+# Watch logs during deploy
+railway logs --follow
+```
+
+### Post-deploy verification
+
+```bash
+# Check service is healthy
+railway status
+
+# Check health endpoint
+curl https://[service-url]/health
+
+# Check recent logs for errors
+railway logs | tail -50
+```
+
+### Rollback if needed
+
+```bash
+# View deployment history in Railway dashboard
+# Or redeploy previous commit:
+git log --oneline -5
+railway up --detach  # after checking out previous commit
+```
+{% endif %}
+
+{% if args[1] == "aws" %}
+## AWS Deployment
+
+### Service type check
+
+Ask: What AWS service is this deploying to?
+- **ECS (Fargate)** — containerized service
+- **Lambda** — serverless function
+- **Elastic Beanstalk** — managed app platform
+- **S3 + CloudFront** — static Next.js export
+
+### ECS Fargate (Kotlin BE)
+
+```bash
+# Build and push Docker image
+aws ecr get-login-password --region ap-southeast-1 | \
+  docker login --username AWS --password-stdin [account].dkr.ecr.ap-southeast-1.amazonaws.com
+
+docker build -t [service-name] .
+docker tag [service-name]:latest [account].dkr.ecr.ap-southeast-1.amazonaws.com/[service-name]:latest
+docker push [account].dkr.ecr.ap-southeast-1.amazonaws.com/[service-name]:latest
+
+# Update ECS service
+aws ecs update-service \
+  --cluster [cluster-name] \
+  --service [service-name] \
+  --force-new-deployment
+```
+
+### Post-deploy
+
+```bash
+# Watch deployment status
+aws ecs describe-services \
+  --cluster [cluster-name] \
+  --services [service-name] \
+  --query 'services[0].deployments'
+
+# Check task health
+aws ecs list-tasks --cluster [cluster-name] --service-name [service-name]
+```
+{% endif %}
+
+---
+
+## Common Issues & Fixes
+
+| Issue | Fix |
+|---|---|
+| Health check failing | Check `/health` returns 200, increase `healthcheckTimeout` |
+| Out of memory | Increase Railway service RAM, or tune JVM: `-Xmx512m` |
+| DB connection failed | Verify `DATABASE_URL` env var, check Railway DB is in same project |
+| Build timeout | Gradle daemon issue — add `org.gradle.daemon=false` to `gradle.properties` |
+| CORS errors | Check `ALLOWED_ORIGINS` env var includes FE URL |
+| Cold start too slow | For Railway: disable `sleep` on free tier, or upgrade plan |
+
+---
+
+## Deployment Summary
+
+After successful deploy, output:
+
+```markdown
+## Deploy Summary: [service] → [target]
+
+- URL: [service URL]
+- Git commit: [hash]
+- Deploy time: [timestamp]
+- Health: ✅ / ❌
+
+## Smoke Tests Run
+- [ ] Health endpoint: [result]
+- [ ] Key user-facing endpoint: [result]
+- [ ] Logs clean (no errors): [result]
+```

package/commands/spartan/e2e.md

@@ -0,0 +1,264 @@
+---
+name: spartan:e2e
+description: Set up Playwright end-to-end testing for a Next.js app. Scaffold config, page objects, and critical path tests. Use when the app has enough features to warrant E2E coverage.
+argument-hint: "[optional: feature or critical path to test first]"
+---
+
+# E2E Testing Setup: {{ args[0] | default: "full setup" }}
+
+You are setting up **Playwright** for end-to-end testing in a Next.js project.
+E2E tests complement unit tests (Vitest) — they test real user flows across the full stack.
+
+---
+
+## Step 1: Install Playwright
+
+```bash
+npm install -D @playwright/test
+npx playwright install chromium  # Only chromium for speed; add more later if needed
+```
+
+---
+
+## Step 2: Configure
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? 'github' : 'html',
+
+  use: {
+    baseURL: process.env.E2E_BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    // Add when ready:
+    // { name: 'mobile', use: { ...devices['iPhone 14'] } },
+  ],
+
+  // Start Next.js dev server for local runs
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 30_000,
+  },
+})
+```
+
+---
+
+## Step 3: Directory Structure
+
+```
+e2e/
+├── fixtures/              ← Shared test fixtures and setup
+│   ├── base.fixture.ts    ← Extended test with common helpers
+│   └── test-data.ts       ← Test data factories
+├── pages/                 ← Page Object Models
+│   ├── BasePage.ts
+│   └── [Feature]Page.ts
+├── [feature].spec.ts      ← Test files
+└── global-setup.ts        ← One-time setup (auth, seed data)
+```
+
+---
+
+## Step 4: Base Page Object
+
+```typescript
+// e2e/pages/BasePage.ts
+import { type Page, type Locator, expect } from '@playwright/test'
+
+export abstract class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  // Common helpers
+  async waitForPageReady() {
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async expectToastMessage(text: string) {
+    await expect(this.page.getByRole('alert')).toContainText(text)
+  }
+
+  async expectUrl(pattern: string | RegExp) {
+    await expect(this.page).toHaveURL(pattern)
+  }
+}
+```
+
+```typescript
+// e2e/pages/HomePage.ts — example
+import { type Page, type Locator, expect } from '@playwright/test'
+import { BasePage } from './BasePage'
+
+export class HomePage extends BasePage {
+  readonly heading: Locator
+  readonly ctaButton: Locator
+
+  constructor(page: Page) {
+    super(page)
+    this.heading = page.getByRole('heading', { level: 1 })
+    this.ctaButton = page.getByRole('link', { name: /get started/i })
+  }
+
+  async goto() {
+    await this.page.goto('/')
+    await this.waitForPageReady()
+  }
+
+  async clickCta() {
+    await this.ctaButton.click()
+  }
+}
+```
+
+---
+
+## Step 5: Test Fixture
+
+```typescript
+// e2e/fixtures/base.fixture.ts
+import { test as base } from '@playwright/test'
+import { HomePage } from '../pages/HomePage'
+
+type Fixtures = {
+  homePage: HomePage
+  // Add more page objects as features grow
+}
+
+export const test = base.extend<Fixtures>({
+  homePage: async ({ page }, use) => {
+    const homePage = new HomePage(page)
+    await use(homePage)
+  },
+})
+
+export { expect } from '@playwright/test'
+```
+
+---
+
+## Step 6: First E2E Test
+
+{% if args[0] and args[0] != "full setup" %}
+Write tests for: **{{ args[0] }}**
+{% else %}
+Write a smoke test for the critical happy path:
+{% endif %}
+
+```typescript
+// e2e/smoke.spec.ts
+import { test, expect } from './fixtures/base.fixture'
+
+test.describe('Smoke Tests', () => {
+  test('home page loads and renders correctly', async ({ homePage }) => {
+    await homePage.goto()
+    await expect(homePage.heading).toBeVisible()
+  })
+
+  test('health endpoint returns ok', async ({ request }) => {
+    const response = await request.get('/api/health')
+    expect(response.ok()).toBeTruthy()
+    const body = await response.json()
+    expect(body.status).toBe('ok')
+  })
+})
+```
+
+---
+
+## Step 7: Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:report": "playwright show-report"
+  }
+}
+```
+
+---
+
+## Step 8: CI Integration
+
+Add to `.github/workflows/ci.yml`:
+
+```yaml
+  e2e:
+    runs-on: ubuntu-latest
+    needs: test  # Run after unit tests pass
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx playwright install chromium --with-deps
+      - run: npm run test:e2e
+        env:
+          CI: true
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+```
+
+---
+
+## Step 9: .gitignore additions
+
+```
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+```
+
+---
+
+## Step 10: Verify
+
+```bash
+# Run E2E tests
+npm run test:e2e
+
+# Debug with UI mode
+npm run test:e2e:ui
+```
+
+After setup, say:
+"✅ Playwright E2E configured. Smoke test passing.
+Use Page Object pattern in `e2e/pages/` for each new feature.
+Run `npm run test:e2e:ui` for interactive debugging."
+
+---
+
+## E2E Test Writing Conventions
+
+When writing new E2E tests, follow these rules:
+
+1. **Use Page Objects** — never raw selectors in test files
+2. **Prefer accessible locators**: `getByRole`, `getByLabel`, `getByText` over CSS selectors
+3. **One assertion per test** (prefer) or closely related assertions
+4. **Test user flows**, not implementation — "user can complete checkout" not "checkout button has class X"
+5. **Isolate test data** — each test creates its own data, never depends on other tests
+6. **Name tests as user stories**: `test('user can add item to cart and checkout')`

package/commands/spartan/env-setup.md

@@ -0,0 +1,166 @@
+---
+name: spartan:env-setup
+description: Set up and audit environment variables for a service across local, Railway, and AWS environments. Generates .env.example, validates required vars, and flags missing ones.
+argument-hint: "[service name] [local | railway | aws | audit]"
+---
+
+# Environment Setup: {{ args[0] }}
+Mode: {{ args[1] | default: "audit" }}
+
+Environment variables are the #1 cause of "works locally but breaks in prod."
+This command audits, generates, and validates env vars across environments.
+
+---
+
+## Step 1: Discover required variables
+
+Scan the codebase to find all env var references:
+
+```bash
+# Kotlin Micronaut — application.yml and @Property annotations
+grep -r "\${" src/main/resources/ --include="*.yml" | grep -v "^Binary"
+grep -r "@Property\|@ConfigurationProperties\|Environment\|System.getenv" \
+  src/main/kotlin/ --include="*.kt" | grep -v "test\|Test"
+
+# Next.js — process.env references
+grep -r "process\.env\." --include="*.ts" --include="*.tsx" src/ app/ lib/ 2>/dev/null | \
+  grep -v "test\|spec\|node_modules"
+
+# Docker Compose
+cat docker-compose.yml 2>/dev/null | grep "environment\|env_file" -A5
+```
+
+---
+
+## Step 2: Generate .env.example
+
+Based on findings, create/update `.env.example` (safe to commit — no real values):
+
+### Kotlin Micronaut template:
+```bash
+# .env.example for [service-name]
+# Copy to .env.local and fill in values
+
+# === Database ===
+DATASOURCES_DEFAULT_URL=jdbc:postgresql://localhost:5432/[dbname]
+DATASOURCES_DEFAULT_USERNAME=postgres
+DATASOURCES_DEFAULT_PASSWORD=changeme
+
+# === Application ===
+MICRONAUT_ENVIRONMENTS=local
+MICRONAUT_SERVER_PORT=8080
+
+# === External Services ===
+# [SERVICE]_API_KEY=your-key-here
+# [SERVICE]_BASE_URL=https://api.example.com
+
+# === Auth (if applicable) ===
+# JWT_SECRET=generate-with: openssl rand -base64 32
+# JWT_EXPIRY_MS=86400000
+
+# === Observability ===
+# SENTRY_DSN=
+# DATADOG_API_KEY=
+```
+
+### Next.js template:
+```bash
+# .env.example for [fe-service]
+
+# === API Connection ===
+NEXT_PUBLIC_API_URL=http://localhost:8080
+
+# === Auth ===
+# NEXTAUTH_URL=http://localhost:3000
+# NEXTAUTH_SECRET=generate-with: openssl rand -base64 32
+
+# === External Services ===
+# NEXT_PUBLIC_ANALYTICS_ID=
+```
+
+---
+
+## Step 3: Audit current environments
+
+### Local
+```bash
+# Check .env.local exists and has all required vars
+cat .env.local 2>/dev/null || echo "⚠️  .env.local missing"
+
+# Find vars in .env.example but missing from .env.local
+comm -23 <(grep "^[A-Z]" .env.example | cut -d= -f1 | sort) \
+         <(grep "^[A-Z]" .env.local 2>/dev/null | cut -d= -f1 | sort)
+```
+
+### Railway
+```bash
+railway variables 2>/dev/null || echo "Not linked to Railway project"
+
+# Check for missing vars (compare with .env.example)
+railway variables --json 2>/dev/null | \
+  python3 -c "import json,sys; vars=json.load(sys.stdin); [print(k) for k in vars]"
+```
+
+### AWS (if applicable)
+```bash
+# List SSM Parameter Store entries for this service
+aws ssm get-parameters-by-path \
+  --path "/spartan/[service-name]/" \
+  --query "Parameters[*].Name"
+
+# Or check Secrets Manager
+aws secretsmanager list-secrets \
+  --query "SecretList[?contains(Name, '[service-name]')].Name"
+```
+
+---
+
+## Step 4: Output audit report
+
+```markdown
+## Env Audit: [service-name]
+
+### Variables found in code: [N]
+
+### Status by environment:
+
+| Variable | Local | Railway | AWS | Notes |
+|---|---|---|---|---|
+| DATASOURCES_DEFAULT_URL | ✅ | ✅ | ✅ | |
+| JWT_SECRET | ✅ | ✅ | ❌ | Missing in AWS |
+| SENTRY_DSN | ❌ | ✅ | ✅ | Missing locally (ok) |
+
+### Issues Found:
+- [MISSING_VAR]: Required in prod but not set in Railway
+- [SECRET_IN_CODE]: Found hardcoded value in [file:line] — move to env var
+
+### All clear:
+- .env.example is up to date
+- No secrets committed to git
+```
+
+---
+
+## Step 5: Security check
+
+```bash
+# Check nothing sensitive was committed
+git log --all --full-history -- "*.env" "**/.env" "**/.env.local"
+git grep -I "password\|secret\|api_key\|apikey\|token" -- '*.yml' '*.yaml' '*.properties' | \
+  grep -v "placeholder\|example\|changeme\|your-"
+
+# Verify .gitignore covers env files
+grep "\.env" .gitignore || echo "⚠️  .env files not in .gitignore!"
+```
+
+If any secrets found in git history:
+```bash
+# Remove from history (nuclear option — coordinate with team first)
+git filter-branch --force --index-filter \
+  'git rm --cached --ignore-unmatch .env.local' HEAD
+```
+
+---
+
+After audit, summarize what's missing and offer to set the Railway vars interactively:
+"Found [N] missing variables. Want me to help set them in Railway now? I'll ask for each value one at a time."