homebox/.github/instructions/code.instructions.md

Homebox Repository Instructions for Coding Agents

Repository Overview

Type: Full-stack home inventory management web app (monorepo)
Size: ~265 Go files, ~371 TypeScript/Vue files
Build Tool: Task (Taskfile.yml) - ALWAYS use task commands
Database: SQLite (default) or PostgreSQL

Stack

• Backend (/backend): Go 1.24+, Chi router, Ent ORM, port 7745
• Frontend (/frontend): Nuxt 4, Vue 3, TypeScript, Tailwind CSS, pnpm 9.1.4+, dev proxies to backend

Critical Build & Validation Commands

Initial Setup (Run Once)

task setup  # Installs swag, goose, Go deps, pnpm deps

Code Generation (Required Before Backend Work)

task generate  # Generates Ent ORM, Swagger docs, TypeScript types

ALWAYS run after: schema changes, API handler changes, before backend server/tests
Note: "TypeSpecDef is nil" warnings are normal - ignore them

Backend Commands

task go:build    # Build binary (60-90s)
task go:test     # Unit tests (5-10s)
task go:lint     # golangci-lint (6m timeout in CI)
task go:all      # Tidy + lint + test
task go:run      # Start server (SQLite)
task pr          # Full PR validation (3-5 min)

Frontend Commands

task ui:dev    # Dev server port 3000
task ui:check  # Type checking
task ui:fix    # eslint --fix + prettier
task ui:watch  # Vitest watch mode

Lint: Max 1 warning in CI (pnpm run lint:ci)

Testing

task test:ci            # Integration tests (15-30s + startup)
task test:e2e           # Playwright E2E (60s+ per shard, needs playwright install)
task pr                 # Full PR validation: generate + go:all + ui:check + ui:fix + test:ci (3-5 min)

Project Structure

Key Root Files

• Taskfile.yml - All commands (always use task)
• docker-compose.yml, Dockerfile* - Docker configs
• CONTRIBUTING.md - Contribution guidelines

Backend Structure (/backend)

backend/
├── app/
│   ├── api/              # Main API application
│   │   ├── main.go       # Entry point
│   │   ├── routes.go     # Route definitions
│   │   ├── handlers/     # HTTP handlers (v1 API)
│   │   ├── static/       # Swagger docs, embedded frontend
│   │   └── providers/    # Service providers
│   └── tools/
│       └── typegen/      # TypeScript type generation tool
├── internal/
│   ├── core/
│   │   └── services/     # Business logic layer
│   ├── data/
│   │   ├── ent/          # Ent ORM generated code + schemas
│   │   │   └── schema/   # Schema definitions (edit these)
│   │   └── repo/         # Repository pattern implementations
│   ├── sys/              # System utilities (config, validation)
│   └── web/              # Web middleware
├── pkgs/                 # Reusable packages
├── go.mod, go.sum        # Go dependencies
└── .golangci.yml         # Linter configuration

Patterns: Schema/API changes → edit source → task generate. Never edit generated code in ent/.

Frontend Structure (/frontend)

frontend/
├── app.vue               # Root component
├── nuxt.config.ts        # Nuxt configuration
├── package.json          # Frontend dependencies
├── components/           # Vue components (auto-imported)
├── pages/                # File-based routing
├── layouts/              # Layout components
├── composables/          # Vue composables (auto-imported)
├── stores/               # Pinia state stores
├── lib/
│   └── api/
│       └── types/        # Generated TypeScript API types
├── locales/              # i18n translations
├── test/                 # Vitest + Playwright tests
├── eslint.config.mjs     # ESLint configuration
└── tailwind.config.js    # Tailwind configuration

Patterns: Auto-imports for components/ and composables/. API types auto-generated - never edit manually.

CI/CD Workflows

PR checks (.github/workflows/pull-requests.yaml) on main/vnext:

1. Backend: Go 1.24, golangci-lint, task go:build, task go:coverage
2. Frontend: Lint (max 1 warning), typecheck, task test:ci (SQLite + PostgreSQL v15-17)
3. E2E: 4 sharded Playwright runs (60min timeout)

All must pass before merge.

Common Pitfalls

1. Missing tools: Run task setup first (installs swag, goose, deps)
2. Stale generated code: Always task generate after schema/API changes
3. Test failures: Integration tests may fail first run (race condition) - retry
4. Port in use: Backend uses 7745 - kill existing process
5. SQLite locked: Delete .data/homebox.db-* files
6. Clean build: rm -rf build/ backend/app/api/static/public/ frontend/.nuxt

Environment Variables

Backend defaults in Taskfile.yml:

• HBOX_LOG_LEVEL=debug
• HBOX_DATABASE_DRIVER=sqlite3 (or postgres)
• HBOX_DATABASE_SQLITE_PATH=.data/homebox.db?_pragma=busy_timeout=1000&_pragma=journal_mode=WAL&_fk=1
• PostgreSQL: HBOX_DATABASE_* vars for username/password/host/port/database

Validation Checklist

Before PR:

• task generate after schema/API changes
• task pr passes (includes lint, test, typecheck)
• No build artifacts committed (check .gitignore)
• Code matches existing patterns

Quick Reference

Dev environment: task go:run (terminal 1) + task ui:dev (terminal 2)

API changes: Edit handlers → add Swagger comments → task generate → task go:build → task go:test

Schema changes: Edit ent/schema/*.go → task generate → update repo methods → task go:test

Specific tests: cd backend && go test ./path -v or cd frontend && pnpm run test:watch

Trust These Instructions

Instructions are validated and current. Only explore further if info is incomplete, incorrect, or you encounter undocumented errors. Use task --list-all for all commands.