From 4cd5cbf893af75dc3b6415ff561e81b5e166c61f Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Fri, 13 Mar 2026 02:25:31 +0000 Subject: [PATCH] feat: Woodpecker CI pipeline + project docs (P0-007, P0-008) (#69) Co-authored-by: Jason Woltje Co-committed-by: Jason Woltje --- .woodpecker/ci.yml | 57 ++++++++++++++++++++++++++++++++++++++++++++++ AGENTS.md | 53 ++++++++++++++++++++++++++++++------------ CLAUDE.md | 45 ++++++++++++++++++++++++++++++++++++ docs/TASKS.md | 2 +- 4 files changed, 142 insertions(+), 15 deletions(-) create mode 100644 .woodpecker/ci.yml create mode 100644 CLAUDE.md diff --git a/.woodpecker/ci.yml b/.woodpecker/ci.yml new file mode 100644 index 0000000..3bcf79b --- /dev/null +++ b/.woodpecker/ci.yml @@ -0,0 +1,57 @@ +variables: + - &node_image 'node:22-alpine' + - &install_deps | + corepack enable + pnpm install --frozen-lockfile + +when: + - event: [push, pull_request, manual] + +steps: + install: + image: *node_image + commands: + - *install_deps + + typecheck: + image: *node_image + commands: + - *install_deps + - pnpm typecheck + depends_on: + - install + + lint: + image: *node_image + commands: + - *install_deps + - pnpm lint + depends_on: + - install + + format: + image: *node_image + commands: + - *install_deps + - pnpm format:check + depends_on: + - install + + test: + image: *node_image + commands: + - *install_deps + - pnpm test + depends_on: + - install + + build: + image: *node_image + commands: + - *install_deps + - pnpm build + depends_on: + - typecheck + - lint + - format + - test diff --git a/AGENTS.md b/AGENTS.md index 1160d39..47e49e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# Agent Guidelines +# Agent Guidelines — Mosaic Stack ## Required Load Order @@ -8,23 +8,48 @@ 4. `~/.config/mosaic/guides/E2E-DELIVERY.md` 5. `AGENTS.md` (this file) 6. Runtime-specific guide: `~/.config/mosaic/runtime//RUNTIME.md` -7. `.mosaic/repo-hooks.sh` -## Session Lifecycle +## Project Context + +Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo with NestJS gateway, Next.js web dashboard, Pi SDK agent runtime, and plugin architecture for Discord/Telegram. + +## Package Map + +| Package | Purpose | Key Dependencies | +| ------------------ | ------------------------------- | -------------------------------- | +| `apps/gateway` | NestJS API + WebSocket hub | Fastify, Socket.IO, Pi SDK, OTEL | +| `apps/web` | Next.js dashboard | React 19, Tailwind | +| `packages/types` | Shared TypeScript contracts | class-validator | +| `packages/db` | Drizzle ORM schema + migrations | drizzle-orm, postgres | +| `packages/auth` | BetterAuth configuration | better-auth, @mosaic/db | +| `packages/brain` | Data layer (PG-backed) | @mosaic/db | +| `packages/queue` | Valkey task queue + MCP | ioredis | +| `packages/coord` | Mission coordination | @mosaic/queue | +| `packages/cli` | Unified CLI + Pi TUI | Ink, Pi SDK | +| `plugins/discord` | Discord channel plugin | discord.js | +| `plugins/telegram` | Telegram channel plugin | Telegraf | + +## Architecture Rules + +1. Gateway is the single API surface — all clients connect through it +2. Pi SDK is ESM-only — gateway and CLI must use ESM +3. Socket.IO typed events defined in `@mosaic/types` enforce compile-time contracts +4. OTEL auto-instrumentation loads before NestJS bootstrap +5. BetterAuth manages auth tables; schema defined in `@mosaic/db` +6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686) +7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata) + +## Development Workflow ```bash -bash scripts/agent/session-start.sh -bash scripts/agent/critical.sh -bash scripts/agent/session-end.sh +docker compose up -d # Infrastructure +pnpm install # Dependencies +pnpm typecheck && pnpm lint && pnpm format:check # Quality gates ``` -## Shared Tools - -- Quality and orchestration guides: `~/.config/mosaic/guides/` -- Shared automation tools: `~/.config/mosaic/tools/` - ## Repo-Specific Notes -- Add project constraints and workflows here. -- Implement hook functions in `.mosaic/repo-hooks.sh`. -- Scratchpads are mandatory for non-trivial tasks. +- DTOs in `*.dto.ts` files at module boundaries +- ESM everywhere (`"type": "module"`, `.js` extensions in imports) +- NodeNext module resolution in all tsconfigs +- Scratchpads are mandatory for non-trivial tasks diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a5502aa --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,45 @@ +# CLAUDE.md — Mosaic Stack + +## Project + +Self-hosted, multi-user AI agent platform. TypeScript monorepo. + +## Stack + +- **API**: NestJS + Fastify adapter (`apps/gateway`) +- **Web**: Next.js 16 + React 19 (`apps/web`) +- **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`) +- **Auth**: BetterAuth (`packages/auth`) +- **Agent**: Pi SDK (`packages/agent`, `packages/cli`) +- **Queue**: Valkey 8 (`packages/queue`) +- **Build**: pnpm workspaces + Turborepo +- **CI**: Woodpecker CI +- **Observability**: OpenTelemetry → Jaeger + +## Commands + +```bash +pnpm typecheck # TypeScript check (all packages) +pnpm lint # ESLint (all packages) +pnpm format:check # Prettier check +pnpm test # Vitest (all packages) +pnpm build # Build all packages + +# Database +pnpm --filter @mosaic/db db:push # Push schema to PG (dev) +pnpm --filter @mosaic/db db:generate # Generate migrations +pnpm --filter @mosaic/db db:migrate # Run migrations + +# Dev +docker compose up -d # Start PG, Valkey, OTEL, Jaeger +pnpm --filter @mosaic/gateway exec tsx src/main.ts # Start gateway +``` + +## Conventions + +- ESM everywhere (`"type": "module"`, `.js` extensions in imports) +- NodeNext module resolution +- Explicit `@Inject()` decorators in NestJS (tsx/esbuild doesn't support emitDecoratorMetadata) +- DTOs in `*.dto.ts` files at module boundaries +- OTEL tracing imported before NestJS bootstrap (`import './tracing.js'`) +- All three gates must pass before push: typecheck, lint, format:check diff --git a/docs/TASKS.md b/docs/TASKS.md index 972ee22..1906210 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -7,7 +7,7 @@ | P0-001 | done | Phase 0 | Scaffold monorepo | #60 | #1 | | P0-002 | done | Phase 0 | @mosaic/types — migrate and extend shared types | #65 | #2 | | P0-003 | done | Phase 0 | @mosaic/db — Drizzle schema and PG connection | #67 | #3 | -| P0-004 | not-started | Phase 0 | @mosaic/auth — BetterAuth email/password setup | — | #4 | +| P0-004 | done | Phase 0 | @mosaic/auth — BetterAuth email/password setup | #68 | #4 | | P0-005 | done | Phase 0 | Docker Compose — PG 17, Valkey 8, SigNoz | #65 | #5 | | P0-006 | done | Phase 0 | OTEL foundation — OpenTelemetry SDK setup | #65 | #6 | | P0-007 | not-started | Phase 0 | CI pipeline — Woodpecker config | — | #7 |