laundry-desk/docs/superpowers/plans/2026-04-23-m1-delivery.md

M1 Delivery Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Deliver laundry-desk M1 as a working Electron Windows NSIS app with receive, pickup, order list/detail, customer de-duplication, automatic/manual backup, type/lint/test gates, and CI artifact generation.

Architecture: Keep the approved Electron split: main owns SQLite and services, preload exposes a narrow typed API, renderer uses IPC only. Replace the current prototype DB/bootstrap with focused service modules, explicit Zod IPC schemas, Drizzle relations, and deterministic tests using in-memory SQLite. M2-M4 placeholders are removed or hidden unless needed by M1.

Tech Stack: Electron 41, React 19, TypeScript strict, Vite/electron-vite, better-sqlite3, Drizzle ORM, Zod, Vitest, Tailwind CSS, Playwright, electron-builder NSIS.

Status 2026-04-23: M1 local delivery completed by Codex. Windows x64 NSIS artifact generated at dist/laundry-desk Setup 0.1.0.exe; SHA256 stored next to it. Final gates passed: npm run lint, npm run typecheck, npm test -- --run, npm run test:e2e, npm run build:win, and npm audit --omit=dev --audit-level=high with no high-severity production findings. Remaining audit item is moderate uuid via exceljs / Tencent Cloud SDK; npm's automatic fix is breaking, so it is intentionally not applied for M1.

---

Task 1: Build And Tooling Baseline

Files:

• Modify: package.json

• Modify: tsconfig.node.json

• Modify: tsconfig.web.json

• Modify: electron.vite.config.ts

• Create: eslint.config.js

• Modify: vitest.config.ts

• Step 1: Run current failing gates

Run: npm run typecheck, npm run lint, npm test -- --run Expected: failures document the current baseline.

• Step 2: Fix TypeScript project boundaries

Set rootDir to src or use rootDirs so src/shared compiles for node and web. Keep strict inherited from electron-toolkit.

• Step 3: Add working ESLint flat config

Use TypeScript parser/config compatible with ESLint 8 and React JSX. Make the lint script run without "config not found".

• Step 4: Rebuild native dependencies for local Node if needed

Run: npm rebuild better-sqlite3. Expected: Vitest can import better-sqlite3.

• Step 5: Re-run gates

Run: npm run typecheck, npm run lint, npm test -- --run Expected: tooling errors are resolved or narrowed to real implementation failures.

Task 2: Database And Service Core

Files:

• Modify: src/main/db/schema.ts

• Modify: src/main/db/index.ts

• Create: src/main/db/migrate.ts

• Create: src/main/db/client.ts

• Modify: src/main/services/customerService.ts

• Modify: src/main/services/orderService.ts

• Modify: src/main/services/pickupCodeService.ts

• Modify: src/main/services/auditService.ts

• Modify: tests/unit/services.test.ts

• Step 1: Write service tests for M1 behavior

Cover customer upsert by phone, order creation transaction, integer cents validation, order number sequencing, pickup code format, pickup search by code/phone/order number, pickup balance settlement, and audit log creation.

• Step 2: Verify tests fail for missing/incorrect behavior

Run: npm test -- --run tests/unit/services.test.ts Expected: failures for missing search, transaction/audit, validation, or schema gaps.

• Step 3: Implement DB initialization

Expose a createDbClient(sqlite) helper for tests and getDb() for app runtime. Enable WAL and foreign keys. Run idempotent SQL migrations for all M1 tables and indexes from one source.

• Step 4: Implement service behavior

Use transactions for create order and pickup. Generate order_no and pickup_code inside the transaction with unique-conflict retry. Recompute totals from item rows, require integer cents, require paidAmount <= totalAmount, and write audit rows through the same transaction.

• Step 5: Re-run unit tests

Run: npm test -- --run tests/unit/services.test.ts Expected: service tests pass.

Task 3: IPC Contract And Preload API

Files:

• Modify: src/shared/index.ts

• Modify: src/shared/schemas.ts

• Modify: src/preload/index.ts

• Modify: src/main/ipc/orders.ts

• Modify: src/main/ipc/customers.ts

• Modify: src/main/ipc/settings.ts

• Create: src/main/ipc/backup.ts

• Modify: src/main/index.ts

• Step 1: Write IPC schema tests where practical

Cover invalid order id, invalid search query, invalid settings key, and invalid backup action schemas.

• Step 2: Implement uniform IPC helpers

Every handler returns { ok: true, data } | { ok: false, error }, logs detailed errors in main, and returns user-safe messages.

• Step 3: Narrow preload exposure

Expose only window.api; remove default window.electron; use typed request/response signatures instead of any.

• Step 4: Add CSP and production-safe window behavior

Remove debug background, alwaysOnTop, devtools auto-open, and fixed startup delay. Add CSP to renderer HTML.

• Step 5: Re-run typecheck/lint

Run: npm run typecheck && npm run lint Expected: zero errors.

Task 4: Renderer M1 Flows

Files:

• Modify: src/renderer/index.html

• Modify: src/renderer/src/assets/main.css

• Modify: src/renderer/src/env.d.ts

• Modify: src/renderer/src/routes/index.tsx

• Modify: src/renderer/src/components/Layout.tsx

• Modify: src/renderer/src/routes/Home.tsx

• Modify: src/renderer/src/routes/Receive.tsx

• Modify: src/renderer/src/routes/Pickup.tsx

• Modify: src/renderer/src/routes/Orders.tsx

• Modify: src/renderer/src/routes/OrderDetail.tsx

• Modify: src/renderer/src/routes/Customers.tsx

• Modify: src/renderer/src/routes/Settings.tsx

• Step 1: Add focused renderer tests if test harness exists, otherwise rely on typecheck and manual/E2E smoke

Validate route imports compile and typed IPC calls are correct.

• Step 2: Restore usable styling

Either configure Tailwind correctly or replace with a compact CSS utility layer sufficient for the current class usage. Preserve Apple HIG-inspired layout and responsive behavior.

• Step 3: Complete receive flow

Phone lookup, customer upsert, item rows with cents conversion, partial payment selection, validation messages, success reset, and navigation to order detail.

• Step 4: Complete pickup flow

Search by pickup code, phone, order number, or customer name; render results; support balance settlement and picked-up transition.

• Step 5: Complete list/detail/settings M1 routes

Order list pagination basics, order detail with print button hidden/disabled until M3, customers list/search, settings shop name, manual backup, and backup list/restore placeholder only if clearly marked out-of-scope.

Task 5: Backup And Delivery Verification

Files:

• Modify: src/main/services/backupService.ts

• Modify: src/main/ipc/backup.ts

• Modify: tests/unit/services.test.ts

• Modify: .github/workflows/build.yml

• Modify: README.md

• Create: docs/CHANGELOG.md

• Step 1: Add backup tests

Use a temp directory and a test database. Verify backup zip is created atomically, contains laundry.db, and rotate keeps 30 newest files.

• Step 2: Implement backup service

Checkpoint WAL, write to temp zip, finalize, rename atomically, rotate after success, and expose manual backup IPC.

• Step 3: Add CI gates

Run install, typecheck, lint, test, build, and build:win. Upload NSIS artifact and SHA256.

• Step 4: Run local verification

Run: npm run typecheck, npm run lint, npm test -- --run, npm run build Expected: all pass locally.

• Step 5: Attempt package verification

On macOS run npm run build:unpack if supported. Final .exe must be generated by GitHub Actions windows-latest.