|
| 1 | +# GEMINI.md |
| 2 | + |
| 3 | +## Project Context |
| 4 | +Shopify Web Replicator is a monorepo containing a replication engine, an MCP server, a companion API, and a React frontend. It automates the replication of Shopify storefronts into a local theme workspace. |
| 5 | + |
| 6 | +## Critical Mandates |
| 7 | +- **Build Order:** You MUST build packages in the following order: `packages/shared` → `packages/engine` → `apps/api` | `apps/web` | `apps/mcp`. |
| 8 | +- **Logic Duplication:** `apps/api/src/services/` contains intentional duplicates of services in `packages/engine`. When modifying engine logic, you MUST check if the corresponding service in `apps/api` needs mirroring. |
| 9 | +- **Stable Artifacts:** Never change the filenames of generated artifacts defined as constants in `packages/shared/src/job.ts`. |
| 10 | +- **Preflight Checks:** The MCP server (`apps/mcp`) runs preflight checks on every tool call. Ensure any new dependencies or system requirements are added to `runtime-preflight.ts`. |
| 11 | + |
| 12 | +## Development Workflows |
| 13 | + |
| 14 | +### Build & Verify |
| 15 | +- **Full Verification:** `pnpm build && pnpm test && pnpm typecheck && pnpm theme:check` |
| 16 | +- **Install:** `pnpm install --frozen-lockfile --ignore-scripts` |
| 17 | +- **Build All:** `pnpm build` |
| 18 | +- **Type-check:** `pnpm typecheck` |
| 19 | +- **Theme Linting:** `pnpm theme:check` |
| 20 | + |
| 21 | +### Testing |
| 22 | +- **Run All Tests:** `pnpm test` |
| 23 | +- **Package Specific:** `pnpm --filter <package-name> test` (e.g., `@shopify-web-replicator/engine`) |
| 24 | +- **Single File:** `pnpm --filter <package-name> exec vitest run <path-to-test>` |
| 25 | + |
| 26 | +### Local Execution |
| 27 | +- **Dev Mode:** `pnpm dev` (starts watchers and servers in parallel) |
| 28 | +- **Database:** SQLite is used, located at `.data/replicator.db` by default. |
| 29 | + |
| 30 | +## Architectural Patterns |
| 31 | +- **Services:** All services depend on interfaces in `src/services/types.ts` to allow for easy testing with doubles. |
| 32 | +- **Persistence:** `SqliteJobRepository` handles job state persistence after each pipeline stage. |
| 33 | +- **Pipeline:** Deterministic sequence: `intake` → `analysis` → `mapping` → `theme_generation` → `store_setup` → `commerce_wiring` → `validation` → `integration_check` → `review`. |
| 34 | + |
| 35 | +## Environment Variables |
| 36 | +| Variable | Default | Purpose | |
| 37 | +|---|---|---| |
| 38 | +| `REPLICATOR_DB_PATH` | `.data/replicator.db` | SQLite database path | |
| 39 | +| `THEME_WORKSPACE_PATH` | `packages/theme-workspace` | Target Shopify theme directory | |
| 40 | +| `REPLICATOR_CAPTURE_ROOT` | `.data/captures` | Playwright capture storage | |
| 41 | +| `PORT` | `8787` | API server port | |
0 commit comments