ragarciaruben 1.20.7

package/.planning/codebase/STACK.md

@@ -0,0 +1,78 @@
+# Technology Stack
+
+<!-- Generated by /map-codebase. Describes the full technology foundation.
+     Consumed by: plan-phase (setup/config/integration work), execute-phase (dependency decisions). -->
+
+## Runtime
+
+| Layer | Technology | Version | Notes |
+|-------|-----------|---------|-------|
+| Language | [e.g., TypeScript] | [X.X] | [any notes] |
+| Runtime | [e.g., Node.js] | [X.X] | [any notes] |
+| Package manager | [e.g., pnpm] | [X.X] | [any notes] |
+
+## Framework
+
+| Purpose | Library | Version | Role |
+|---------|---------|---------|------|
+| [Web framework] | [e.g., Express / Fastify / Next.js] | [X.X] | [What it does] |
+| [ORM / DB client] | [e.g., Prisma / Drizzle] | [X.X] | [What it does] |
+| [Auth] | [e.g., Passport.js / NextAuth] | [X.X] | [What it does] |
+
+## Key Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `[package-name]` | `^X.X` | [Why it exists] |
+| `[package-name]` | `^X.X` | [Why it exists] |
+| `[package-name]` | `^X.X` | [Why it exists] |
+
+## Dev Toolchain
+
+| Tool | Config File | Purpose |
+|------|------------|---------|
+| [TypeScript] | `tsconfig.json` | Compilation |
+| [ESLint] | `.eslintrc.js` | Linting |
+| [Prettier] | `.prettierrc` | Formatting |
+| [Vitest / Jest] | `vitest.config.ts` | Testing |
+| [Build tool] | `[config file]` | Bundle/compile |
+
+## Infrastructure
+
+| Layer | Technology | How configured |
+|-------|-----------|----------------|
+| Database | [e.g., PostgreSQL 15] | [e.g., Docker locally, RDS in prod] |
+| Cache | [e.g., Redis 7] | [e.g., ElastiCache in prod] |
+| Object storage | [e.g., S3] | [e.g., via AWS SDK v3] |
+| Message queue | [e.g., SQS / RabbitMQ] | [e.g., via @aws-sdk/client-sqs] |
+| Deployment | [e.g., AWS ECS / Vercel / K8s] | [How deployed] |
+
+## Environment Variables
+
+```bash
+# Application
+APP_PORT=3000
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# [Auth provider]
+AUTH_SECRET=
+AUTH_PROVIDER_CLIENT_ID=
+AUTH_PROVIDER_CLIENT_SECRET=
+
+# [External API]
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+```
+
+*Actual secrets in `.env` (gitignored). Example in `.env.example`.*
+
+## Version Constraints
+
+[Any locked versions, peer dependency requirements, or compatibility notes that affect future dependency changes]
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,75 @@
+# File Structure
+
+<!-- Generated by /map-codebase. Describes physical organization of the codebase.
+     Primary purpose: answer "where do I put new code?"
+     Consumed by: plan-phase (any), execute-phase (when creating new files). -->
+
+## Root Layout
+
+```
+/
+├── src/                  [Main application source]
+├── tests/                [Test files]
+├── docs/                 [Documentation]
+├── scripts/              [Build/deploy scripts]
+├── .github/              [Copilot context + CI/CD]
+├── .planning/            [Project context documents]
+├── package.json          [Node.js manifest / replace with appropriate manifest]
+└── [config files]        [tsconfig.json, .eslintrc, etc.]
+```
+
+## Source Tree
+
+```
+src/
+├── [describe your actual structure here]
+│   ├── [subdirectory]    [What goes here]
+│   └── [subdirectory]    [What goes here]
+├── [module/]             [Description]
+└── [module/]             [Description]
+```
+
+## Where To Put New Code
+
+<!-- This section is the primary value of this document. Be prescriptive. -->
+
+| I'm adding... | It goes in... | Naming convention |
+|---------------|---------------|-------------------|
+| A new API endpoint | `src/routes/[resource].route.ts` | `[resource].route.ts` (kebab-case) |
+| Business logic | `src/services/[resource].service.ts` | `[resource].service.ts` |
+| Database queries | `src/repositories/[resource].repository.ts` | `[resource].repository.ts` |
+| A new data model | `src/models/[Resource].model.ts` | `[Resource].model.ts` (PascalCase) |
+| Reusable utility | `src/utils/[descriptive-name].ts` | `[name].ts` (kebab-case) |
+| Shared types/interfaces | `src/types/[domain].types.ts` | `[domain].types.ts` |
+| Middleware | `src/middleware/[name].middleware.ts` | `[name].middleware.ts` |
+| Configuration | `src/config/[name].config.ts` | `[name].config.ts` |
+| A unit test | `tests/unit/[mirrors-src-path].test.ts` | Mirror src path |
+| An integration test | `tests/integration/[feature].test.ts` | Feature-scoped |
+| A new React component | `src/components/[Name]/[Name].tsx` | PascalCase directory + file |
+| A new page | `src/pages/[name]/page.tsx` | kebab-case directory |
+
+## File Naming Rules
+
+- **Components:** `PascalCase.tsx` (e.g., `UserCard.tsx`)
+- **Utilities/Services/Routes:** `kebab-case.ts` (e.g., `user-service.ts` or `user.service.ts`)
+- **Constants:** `SCREAMING_SNAKE_CASE.ts` (e.g., `API_CONSTANTS.ts`)
+- **Types/Interfaces:** exported with `I` prefix or `Type` suffix — [specify your convention]
+- **Test files:** mirror source path with `.test.ts` or `.spec.ts` suffix
+
+## Colocation Patterns
+
+[Describe any patterns for co-locating related files, e.g., feature folders, barrel files, index.ts patterns]
+
+```
+Example — feature folder pattern:
+src/features/auth/
+├── auth.route.ts
+├── auth.service.ts
+├── auth.controller.ts
+├── auth.types.ts
+└── index.ts          ← barrel export
+```
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/codebase/TESTING.md

@@ -0,0 +1,157 @@
+# Testing Patterns
+
+<!-- Generated by /map-codebase. Describes test framework, patterns, and organization.
+     Consumed by: execute-phase (all work), plan-phase (testing phases).
+     Auto-loaded by Copilot when editing *.test.* or *.spec.* files. -->
+
+## Test Framework
+
+- **Runner:** [Vitest / Jest / Pytest / Go test]
+- **Assertion library:** [Built-in expect / Chai]
+- **Mocking:** [vi.mock() / jest.mock() / unittest.mock]
+- **Coverage:** [v8 / istanbul] — threshold: [80%] lines/branches
+- **Snapshot testing:** [Used / Not used]
+
+## Running Tests
+
+```bash
+# All tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+
+# Specific file
+npx vitest run src/services/user.service.test.ts
+
+# Pattern match
+npx vitest run --grep "UserService"
+```
+
+## Test File Organization
+
+```
+tests/
+├── unit/               # Pure unit tests (no I/O)
+│   ├── services/       # Service layer tests
+│   ├── utils/          # Utility function tests
+│   └── models/         # Model/schema validation tests
+├── integration/        # Tests with real DB / HTTP
+│   ├── routes/         # API endpoint tests
+│   └── repositories/   # Database query tests
+├── e2e/                # End-to-end tests
+│   └── flows/          # User journey tests
+└── helpers/
+    ├── factories.ts    # Test data factories
+    ├── setup.ts        # Global test setup
+    └── mocks/          # Shared mock implementations
+```
+
+*Alternative: Test files co-located with source (`*.test.ts` next to `*.ts`). [Specify which pattern you use.]*
+
+## Test Structure Pattern
+
+Follow the **Arrange-Act-Assert** pattern with `describe`/`it` blocks:
+
+```typescript
+describe('UserService', () => {
+  describe('createUser()', () => {
+    it('creates a user with hashed password', async () => {
+      // Arrange
+      const dto = { email: 'test@example.com', password: 'plaintext' };
+      const mockRepo = createMockUserRepository();
+
+      // Act
+      const result = await new UserService(mockRepo).createUser(dto);
+
+      // Assert
+      expect(result.email).toBe('test@example.com');
+      expect(result.password).not.toBe('plaintext');
+      expect(mockRepo.save).toHaveBeenCalledOnce();
+    });
+
+    it('throws ValidationError when email already exists', async () => {
+      // Arrange
+      const mockRepo = createMockUserRepository({ emailExists: true });
+
+      // Act & Assert
+      await expect(
+        new UserService(mockRepo).createUser({ email: 'taken@test.com', password: 'pw' })
+      ).rejects.toThrow(ValidationError);
+    });
+  });
+});
+```
+
+## Mocking Strategy
+
+- **Services:** mock at repository layer — don't mock the service being tested
+- **External HTTP:** use [msw / nock] to intercept at network level
+- **Database:** [test database with transactions rolled back / in-memory DB / repository mocks]
+- **Environment variables:** set in `vitest.config.ts` under `env`; never `process.env` mutations in tests
+- **Time:** use `vi.useFakeTimers()` for time-dependent tests
+
+## Test Data
+
+Use factory functions, not hardcoded objects:
+```typescript
+// tests/helpers/factories.ts
+export function createUser(overrides: Partial<User> = {}): User {
+  return {
+    id: 'usr_test_123',
+    email: 'test@example.com',
+    name: 'Test User',
+    createdAt: new Date('2024-01-01'),
+    ...overrides,  // caller overrides specific fields for the test case
+  };
+}
+```
+
+## Integration Test Pattern
+
+```typescript
+describe('POST /api/users', () => {
+  let app: Express;
+  let db: TestDatabase;
+
+  beforeAll(async () => {
+    db = await createTestDatabase();
+    app = createApp(db);
+  });
+
+  afterEach(async () => {
+    await db.rollback();  // clean state between tests
+  });
+
+  afterAll(async () => {
+    await db.close();
+  });
+
+  it('returns 201 with created user', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'new@test.com', password: 'password123' })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(201);
+    expect(response.body).toMatchObject({ email: 'new@test.com' });
+    expect(response.body.password).toBeUndefined();  // never expose password
+  });
+});
+```
+
+## What To Test
+
+- ✅ Business logic in services (unit tests with mocked deps)
+- ✅ API contract (integration tests: status codes, response shape, error cases)
+- ✅ Edge cases: empty inputs, null values, boundary conditions
+- ✅ Error paths: what happens when dependencies fail
+- ❌ Don't test framework internals (ORM queries, Express routing)
+- ❌ Don't test private/internal implementation details
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/continue-here.md

@@ -0,0 +1,44 @@
+# Continue Here
+
+<!-- Generated at session pause. Gives the next session full context to resume immediately.
+     Reference: .planning/STATE.md for project-wide position. -->
+
+## Where We Are
+
+**Phase:** [X] — [Phase Name]
+**Plan:** [A] of [B]
+**As of:** [YYYY-MM-DD HH:MM]
+
+## What Was Just Completed
+
+[Concrete description of the last completed action — file changed, test passed, API endpoint shipped, etc.]
+
+- ✅ [Completed item 1]
+- ✅ [Completed item 2]
+- ✅ [Completed item 3]
+
+## What Remains
+
+- [ ] [Next immediate task]
+- [ ] [Task after that]
+- [ ] [Remaining items in current plan]
+
+## Decisions Made This Session
+
+<!-- Lock these in — don't re-litigate next session -->
+
+- [Decision 1 and its rationale]
+- [Decision 2 and its rationale]
+
+## Blockers / Watch-Outs
+
+<!-- Anything the next session needs to know before touching code -->
+
+- [Blocker or warning — e.g., "Auth middleware has a race condition in tests, skip until Phase 3"]
+
+## Exact Next Action
+
+**Resume by doing:** [Single clear action — e.g., "Run `npm test` to verify the auth middleware, then open `src/routes/user.ts` and implement the POST /users endpoint per plan 02-01"]
+
+---
+*Saved: [YYYY-MM-DD HH:MM]*

package/.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  // Tell Copilot where to find the context engineering system files.
+  // All context files are isolated in .github/copilot-context/ — configure
+  // each feature type to look there instead of the default .github/ root.
+
+  "chat.instructionsFilesLocations": [
+    ".github/copilot-context/instructions"
+  ],
+  "chat.promptFilesLocations": [
+    ".github/copilot-context/prompts"
+  ],
+  "chat.agentFilesLocations": [
+    ".github/copilot-context/agents",
+    ".github/copilot-context/skills"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.