Development Workflow Skill

You are a development workflow assistant for the Guren framework monorepo.

Your Role

Help users run builds, tests, type checks, and development servers with intelligent error diagnosis.

Commands

Build

Build all packages in the correct dependency order.

bun run build

The order is derived from each package's dependencies/peerDependencies, so new packages (plugins included) are picked up without editing any script. Print it with:

bun run build:list

Single package:

bun run build server  # @guren/server
bun run build orm     # @guren/orm
bun run build cli     # @guren/cli

On failure: Identify the failing package and show the TypeScript/build error. The issue is usually in that package's src/ directory.

Test

Two modes: smart (targeted) and full.

Smart Test (default for "test my changes", "quick test")

1. Get changed files:

git diff --name-only HEAD
git diff --name-only --cached

2. Map to packages:

   • packages/server/ → bun test packages/server
   • packages/orm/ → bun test packages/orm
   • packages/cli/ → bun test packages/cli
   • packages/testing/ → bun test packages/testing
   • examples/blog/ → bun run test:examples
   • examples/api/ → bun run test:examples

3. Decision logic:

   • < 3 files in same package → run package tests
   • Multiple packages changed → run affected packages

   • 10 files or cross-cutting → run full suite

   • No test impact detected → skip tests

4. After smart tests pass, remind: "Consider running full suite before PR: bun run test"

Full Test Suite (default for "run tests", "test")

bun run test

Runs:

• bun run test:bun — Framework tests. The package list is discovered from packages/* (every package whose test script uses Bun's runner), so new packages need no wiring. bun run test:bun:list prints it; bun run test:bun <pkg> narrows it.
• bun run test:examples — Example app tests (blog, api)
• bun run test:testing — @guren/testing only (vitest, so not part of test:bun)

On failure: Identify the failing test file and test name, show the error, suggest fixes.

Type Check

bun run typecheck

Runs root monorepo + blog example type checks.

On failure: List each error with file:line, show the message, suggest fixes for common issues (missing types, incorrect imports, type mismatches).

Lint

bun run lint

oxlint with the type-aware rules (typescript/no-floating-promises) plus the repo's own guren/await-async-assertion. Warnings fail the run too. bun run lint:fix applies the safe auto-fixes.

On failure: Show each finding with file:line and the rule name. A no-floating-promises finding on a call whose result is dropped on purpose takes a void in front; an un-awaited expect(...).rejects / .resolves takes await.

PR Check (pre-PR validation)

Run all checks in order. Stop and report on first failure:

bun run build && bun run typecheck && bun run lint && bun run test

On success, confirm:

• All packages built successfully
• No type errors found
• All tests passing

E2E Tests (default for "e2e", "playwright", "end to end")

Runs Playwright E2E tests against the blog example app.

Prerequisites: Database running + migrated + seeded, packages built, dev server NOT already running (Playwright starts its own).

cd examples/blog && bun run e2e

Opens Playwright UI for debugging:

cd examples/blog && bun run e2e:ui

Known flaky tests:

• Validation tests (Inertia XHR round-trip timing) are flaky in CI. They are skipped via test.skip(!!process.env.CI) but may occasionally fail locally too. If only validation tests fail, it is safe to proceed.

On failure:

1. Check if the failure is a known flaky test (validation spec)
2. If not, check the error screenshot in examples/blog/test-results/
3. Ensure the database is running and seeded: bun run db:up && bun run db:migrate && bun run db:seed

Dev Server

Start the blog example development server.

bun run dev

Available at http://localhost:3333

Prerequisites check before starting:

1. Database running? If not: bun run db:up
2. Migrations applied? If not: bun run db:migrate
3. Packages built? If not: bun run build

Package Test Commands

Package	Command
Server	bun test packages/server
ORM	bun test packages/orm
CLI	bun test packages/cli
Testing	bun test packages/testing
Core	bun test packages/core
Create App	bun test packages/create-app
Examples	bun run test:examples
All	bun run test