# AGENTS.md — Work Hub Server

## Project Structure

```
work-hub-server/
├── apps/
│   ├── api/          # NestJS 11 API (Express platform)
│   └── web/          # Nuxt 4 app (Vue 3 + Nuxt UI)
├── packages/
│   └── schema/       # Shared schema package (empty placeholder)
├── openspec/         # OpenSpec config
├── turbo.json        # Turborepo pipeline config
└── package.json      # Root workspace scripts
```

## Build / Dev / Lint / Test Commands

All commands run from the repository root.

### Root (Turborepo orchestrated)

| Command            | Description                           |
| ------------------ | ------------------------------------- |
| `pnpm build`       | Build all apps/packages               |
| `pnpm dev`         | Start all apps in dev mode            |
| `pnpm lint`        | Lint all apps                         |
| `pnpm format`      | Prettier format all `*.ts,*.tsx,*.md` |
| `pnpm check-types` | Type-check all apps                   |

**Filtering to a single app:** `pnpm --filter=api build`

### API (NestJS)

| Command                        | Description                     |
| ------------------------------ | ------------------------------- |
| `pnpm --filter=api test`       | Run all unit tests              |
| `pnpm --filter=api test:watch` | Watch mode                      |
| `pnpm --filter=api test:cov`   | With coverage                   |
| `pnpm --filter=api test:e2e`   | Run e2e tests                   |
| `pnpm --filter=api lint`       | ESLint with `--fix`             |
| `pnpm --filter=api dev`        | Start in watch mode (port 3001) |

**Single unit test:** `pnpm --filter=api jest -- --testPathPattern="app.controller"`

**Single e2e test:** `pnpm --filter=api jest --config ./test/jest-e2e.json --testPathPattern="app.e2e"`

### Web (Nuxt)

| Command                       | Description            |
| ----------------------------- | ---------------------- |
| `pnpm --filter=web dev`       | Dev server (port 3000) |
| `pnpm --filter=web build`     | Production build       |
| `pnpm --filter=web lint`      | ESLint                 |
| `pnpm --filter=web typecheck` | `nuxt typecheck`       |

## Code Style Guidelines

### Language & Runtime

- **100% TypeScript** throughout the monorepo.
- **Node >= 18** (root `engines` field).
- Package manager: **pnpm 9** (see `pnpm-workspace.yaml`).

### Imports

- Use **ESM `import` syntax** everywhere (`import { Foo } from './foo'`).
- No barrel/index re-exports unless the package explicitly defines them.
- API app: nestjs/common/core imports first, then local relative imports (`'./file'`).
- Web app: auto-imports via Nuxt (components, composables); explicit imports for external modules.

### Formatting

- **Prettier** with `singleQuote: false`, `trailingComma: 'all'`.
- Quote strings with double quotes (single quotes for JSX attributes).
- Run `pnpm format` before committing.

### Linting

- **ESLint flat config** (`eslint.config.mjs`) in each app.
- API uses `@typescript-eslint` with `recommendedTypeChecked` rules, plus `eslint-plugin-prettier`.
- Key relaxed rules:
  - `@typescript-eslint/no-explicit-any: off`
  - `@typescript-eslint/no-floating-promises: warn`
- Web uses `@nuxt/eslint` with stylistic config (`commaDangle: never`, `braceStyle: 1tbs`).

### TypeScript

- **Target:** ES2023
- **Module:** `nodenext` with `moduleResolution: nodenext`
- **Strict null checks** enabled (`strictNullChecks: true`).
- Decorators enabled (`emitDecoratorMetadata`, `experimentalDecorators`).
- `noImplicitAny: false` (API) — explicit `any` allowed but prefer proper types.
- `skipLibCheck: true`, `forceConsistentCasingInFileNames: true`.
- Web references Nuxt-generated tsconfig files (project references).

### Naming Conventions

- **Classes:** PascalCase (`AppController`, `AppService`).
- **Files:** kebab-case (`app.controller.ts`, `app.e2e-spec.ts`).
- **Variables/functions:** camelCase.
- **Test files:** `*.spec.ts` (unit), `*.e2e-spec.ts` (e2e), co-located with source.
- **Decorators:** PascalCase (`@Controller()`, `@Injectable()`, `@Get()`).

### Error Handling

- **API (NestJS):** Use NestJS exception filters, `@nestjs/common` exceptions (e.g., `NotFoundException`, `BadRequestException`). Avoid raw `throw Error`.
- **Web (Nuxt):** Use Nuxt layers/plugins for error handling. Vue composition API with `try/catch` in async handlers.

### Testing (API app)

- **Framework:** Jest 30 with `ts-jest`.
- **Test location:** Unit tests live in `src/` alongside source files (`*.spec.ts`). E2e tests in `test/` (`*.e2e-spec.ts`).
- **Pattern:** `describe`/`it` blocks. Use `@nestjs/testing` `Test.createTestingModule` for integration.
- SuperTest for HTTP e2e tests.
- Coverage output goes to `coverage/`.

### NestJS-Specific Conventions

- Modules import providers/controllers; root module is `AppModule`.
- Services decorated with `@Injectable()`, controllers with `@Controller()`.
- Constructor-based DI with `private readonly` shorthand.
- Default port 3001 (from `main.ts`).

### Vue/Nuxt-Specific Conventions

- **Composition API** with `<script setup>` (no Options API).
- **Single-file components** (`.vue`) with template, script, style sections.
- **Auto-imports** for Nuxt composables (`useHead`, `useSeoMeta`, `defineAppConfig`).
- **Nuxt UI** components (`UApp`, `UHeader`, `UButton`, etc.) are auto-imported.
- **CSS:** Tailwind CSS v4 via `@import "tailwindcss"` in `main.css`.
- **TypeScript config** references `.nuxt/tsconfig.*.json` — do not edit directly.