|
|
|
|
@@ -0,0 +1,798 @@
|
|
|
|
|
# Electrobun Desktop: Production Mode via Child Process Architecture
|
|
|
|
|
|
|
|
|
|
## TL;DR
|
|
|
|
|
|
|
|
|
|
> **Quick Summary**: Redesign the Electrobun desktop app to support production mode by spawning the TanStack Start server as a child process. Currently only dev mode works (hardcoded `localhost:3000`). The desktop will detect dev/prod mode, spawn the server with `PORT=0` in prod, parse the actual port from stdout, and open the BrowserWindow.
|
|
|
|
|
>
|
|
|
|
|
> **Deliverables**:
|
|
|
|
|
> - Rewritten `apps/desktop/src/bun/index.ts` with dev/prod mode support
|
|
|
|
|
> - Updated `apps/desktop/electrobun.config.ts` with `build.copy` and platform configs
|
|
|
|
|
> - Cross-workspace build dependency in turbo pipeline
|
|
|
|
|
> - Updated `apps/desktop/AGENTS.md` reflecting new architecture
|
|
|
|
|
>
|
|
|
|
|
> **Estimated Effort**: Medium
|
|
|
|
|
> **Parallel Execution**: YES - 2 waves
|
|
|
|
|
> **Critical Path**: Tasks 1,2,3 (parallel) → Task 4 → Task 5
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Context
|
|
|
|
|
|
|
|
|
|
### Original Request
|
|
|
|
|
Redesign the Electrobun desktop app to support production mode. The desktop app should spawn the TanStack Start server as a child process, detect dev vs prod mode at runtime, use system-assigned ports for security, and handle server lifecycle (crash, quit).
|
|
|
|
|
|
|
|
|
|
### Confirmed Decisions
|
|
|
|
|
- **Architecture**: Desktop spawns server as child process via `Bun.spawn`
|
|
|
|
|
- **Server artifact**: `.output/server/index.mjs` (not compiled binary) — Electrobun already bundles Bun
|
|
|
|
|
- **Port strategy**: `PORT=0` (system-assigned), `HOST=127.0.0.1`
|
|
|
|
|
- **Dev/Prod detection**: `process.env.ELECTROBUN_BUILD_ENV` (see Defaults Applied below)
|
|
|
|
|
- **Target platforms**: All (Linux, macOS, Windows)
|
|
|
|
|
- **DATABASE_URL**: Pass-through via env var, no special handling
|
|
|
|
|
- **Crash handling**: MVP — log error to stderr, exit process
|
|
|
|
|
|
|
|
|
|
### Research Findings
|
|
|
|
|
|
|
|
|
|
**Electrobun APIs (verified from source code):**
|
|
|
|
|
- `build.copy` supports paths outside the project directory (e.g., `../server/.output`). Source paths are resolved relative to the project root. Destinations map into `Resources/app/` in the bundle.
|
|
|
|
|
- `PATHS` exported from `electrobun/bun` provides `RESOURCES_FOLDER` (absolute path to `Resources/`) and `VIEWS_FOLDER` (`Resources/app/views/`).
|
|
|
|
|
- `process.execPath` in a bundled Electrobun app points to the bundled Bun binary.
|
|
|
|
|
- `Electrobun.events.on('before-quit', callback)` fires before app quit. Callback receives an event with `response({ allow: false })` to cancel quit.
|
|
|
|
|
- `ELECTROBUN_BUILD_ENV` is set by the Electrobun CLI: `"dev"` for `electrobun dev`, `"stable"` for `electrobun build --env=stable`.
|
|
|
|
|
|
|
|
|
|
**Server startup behavior (verified from built output):**
|
|
|
|
|
- `.output/server/index.mjs` uses `Bun.serve` via the `h3+srvx` adapter (Nitro bun preset).
|
|
|
|
|
- Startup log format: `➜ Listening on: http://<address>:<port>/`
|
|
|
|
|
- The log uses the actual assigned address/port, not the requested one. So `PORT=0` will log the real port.
|
|
|
|
|
- `DATABASE_URL` is validated at startup via Zod (`@t3-oss/env-core`). Missing = immediate crash.
|
|
|
|
|
- The `.output/server/` directory contains `index.mjs` plus `_libs/` with bundled dependencies.
|
|
|
|
|
|
|
|
|
|
**Turbo pipeline:**
|
|
|
|
|
- Root `turbo.json` has `build.dependsOn: ["^build"]` which only builds workspace *dependencies*.
|
|
|
|
|
- Desktop does NOT depend on server in `package.json`, so `^build` won't trigger server build.
|
|
|
|
|
- Need explicit cross-workspace dependency via desktop's `turbo.json`.
|
|
|
|
|
|
|
|
|
|
### Metis Review
|
|
|
|
|
**Identified Gaps** (addressed):
|
|
|
|
|
- Dev/prod detection mechanism: Switched from custom `ELECTROBUN_DEV` to built-in `ELECTROBUN_BUILD_ENV`
|
|
|
|
|
- Server startup timeout: Added explicit timeout with error reporting
|
|
|
|
|
- Port parsing failure: Plan includes fallback and error handling
|
|
|
|
|
- Server crash during runtime: Watching `subprocess.exited` promise
|
|
|
|
|
- `cwd` for spawned server: Must set to server directory for relative import resolution
|
|
|
|
|
- Cross-platform considerations: `ELECTROBUN_BUILD_ENV` works everywhere (no `cross-env` needed)
|
|
|
|
|
|
|
|
|
|
### Unknowns Resolved
|
|
|
|
|
|
|
|
|
|
| Unknown | Resolution |
|
|
|
|
|
|---------|------------|
|
|
|
|
|
| Does `build.copy` support paths outside project? | **YES** — uses `cpSync` with source resolved from project root. `../server/.output` works. |
|
|
|
|
|
| Runtime API for resolving bundled resource paths? | **`PATHS.RESOURCES_FOLDER`** from `electrobun/bun`. Copied files land in `Resources/app/{dest}/`. |
|
|
|
|
|
| Does Nitro log actual port with PORT=0? | **YES** — format: `➜ Listening on: http://<addr>:<port>/` via h3+srvx adapter. |
|
|
|
|
|
| How does Electrobun detect dev mode? | **`ELECTROBUN_BUILD_ENV`** env var set by CLI. Values: `dev`, `canary`, `stable`. |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Work Objectives
|
|
|
|
|
|
|
|
|
|
### Core Objective
|
|
|
|
|
Enable the Electrobun desktop app to run in production mode by spawning the TanStack Start server as a managed child process, while preserving existing dev mode behavior.
|
|
|
|
|
|
|
|
|
|
### Concrete Deliverables
|
|
|
|
|
- `apps/desktop/src/bun/index.ts` — Complete rewrite with dual-mode support
|
|
|
|
|
- `apps/desktop/electrobun.config.ts` — `build.copy` + all-platform configs
|
|
|
|
|
- `apps/desktop/turbo.json` — Cross-workspace build dependency
|
|
|
|
|
- `apps/desktop/AGENTS.md` — Accurate documentation of new architecture
|
|
|
|
|
|
|
|
|
|
### Definition of Done
|
|
|
|
|
- [ ] `bun typecheck` passes from monorepo root (zero errors)
|
|
|
|
|
- [ ] `bun build` from root succeeds: server builds first, then desktop bundles server output
|
|
|
|
|
- [ ] `bun dev` from root still starts both apps (dev mode preserved)
|
|
|
|
|
- [ ] Desktop `index.ts` has zero hardcoded URLs (all dynamic)
|
|
|
|
|
|
|
|
|
|
### Must Have
|
|
|
|
|
- Dev mode: poll external `localhost:3000`, open window when ready (existing behavior, refactored)
|
|
|
|
|
- Prod mode: spawn server via `Bun.spawn`, parse port from stdout, open window
|
|
|
|
|
- Server bound to `127.0.0.1` only (no network exposure)
|
|
|
|
|
- `PORT=0` for system-assigned port (no conflicts)
|
|
|
|
|
- Server process killed on app quit (via `before-quit` event)
|
|
|
|
|
- Server crash detection (watch `exited` promise, log error, exit app)
|
|
|
|
|
- Startup timeout with clear error message
|
|
|
|
|
- Server `cwd` set to its own directory (for relative import resolution)
|
|
|
|
|
- `DATABASE_URL` passed through from parent environment
|
|
|
|
|
|
|
|
|
|
### Must NOT Have (Guardrails)
|
|
|
|
|
- No hardcoded port numbers (not even 3000 — use a named constant `DEV_SERVER_URL`)
|
|
|
|
|
- No `as any`, `@ts-ignore`, or `@ts-expect-error`
|
|
|
|
|
- No empty catch blocks — always handle or re-throw
|
|
|
|
|
- No `npm`, `npx`, `node` — Bun only
|
|
|
|
|
- No manual `useMemo`/`useCallback` (not relevant here, but per project rules)
|
|
|
|
|
- No suppressed type errors — fix them properly
|
|
|
|
|
- No custom env var for dev detection — use built-in `ELECTROBUN_BUILD_ENV`
|
|
|
|
|
- No compiled server binary — use `.output/server/index.mjs` with bundled Bun
|
|
|
|
|
- Do NOT edit `apps/server/` — only `apps/desktop/` files change
|
|
|
|
|
- Do NOT add `@furtherverse/server` as a package dependency of desktop (use turbo cross-workspace dependency instead)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Verification Strategy
|
|
|
|
|
|
|
|
|
|
> **UNIVERSAL RULE: ZERO HUMAN INTERVENTION**
|
|
|
|
|
>
|
|
|
|
|
> ALL tasks in this plan MUST be verifiable WITHOUT any human action.
|
|
|
|
|
> Every criterion is verified by running a command or using a tool.
|
|
|
|
|
|
|
|
|
|
### Test Decision
|
|
|
|
|
- **Infrastructure exists**: NO (no test framework in this project)
|
|
|
|
|
- **Automated tests**: NO (per project state — `AGENTS.md` says "No test framework configured yet")
|
|
|
|
|
- **Framework**: None
|
|
|
|
|
- **Agent-Executed QA**: ALWAYS (mandatory for all tasks)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Execution Strategy
|
|
|
|
|
|
|
|
|
|
### Parallel Execution Waves
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Wave 1 (Start Immediately — all independent, different files):
|
|
|
|
|
├── Task 1: Update electrobun.config.ts (build.copy + platform configs)
|
|
|
|
|
├── Task 2: Update turbo.json (cross-workspace build dependency)
|
|
|
|
|
└── Task 3: Rewrite index.ts (complete dev/prod mode implementation)
|
|
|
|
|
|
|
|
|
|
Wave 2 (After Wave 1 — needs final state of all files):
|
|
|
|
|
├── Task 4: Rewrite AGENTS.md (documentation reflecting new architecture)
|
|
|
|
|
└── Task 5: End-to-end verification (typecheck + build pipeline)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Dependency Matrix
|
|
|
|
|
|
|
|
|
|
| Task | Depends On | Blocks | Can Parallelize With |
|
|
|
|
|
|------|------------|--------|---------------------|
|
|
|
|
|
| 1 | None | 4, 5 | 2, 3 |
|
|
|
|
|
| 2 | None | 4, 5 | 1, 3 |
|
|
|
|
|
| 3 | None | 4, 5 | 1, 2 |
|
|
|
|
|
| 4 | 1, 2, 3 | 5 | None |
|
|
|
|
|
| 5 | 1, 2, 3, 4 | None | None (final) |
|
|
|
|
|
|
|
|
|
|
### Agent Dispatch Summary
|
|
|
|
|
|
|
|
|
|
| Wave | Tasks | Recommended Agents |
|
|
|
|
|
|------|-------|-------------------|
|
|
|
|
|
| 1 | 1, 2, 3 | Tasks 1,2: `delegate_task(category="quick")`. Task 3: `delegate_task(category="unspecified-high")` |
|
|
|
|
|
| 2 | 4, 5 | Task 4: `delegate_task(category="writing")`. Task 5: `delegate_task(category="quick")` |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## TODOs
|
|
|
|
|
|
|
|
|
|
- [ ] 1. Update `apps/desktop/electrobun.config.ts` — Add build.copy and platform configs
|
|
|
|
|
|
|
|
|
|
**What to do**:
|
|
|
|
|
- Add `build.copy` to include the server's Nitro build output in the desktop bundle:
|
|
|
|
|
```typescript
|
|
|
|
|
copy: {
|
|
|
|
|
'../server/.output': 'server-output',
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
This copies `apps/server/.output/` (the entire Nitro build output) into `Resources/app/server-output/` in the Electrobun bundle. The full server entry point will be at `Resources/app/server-output/server/index.mjs`.
|
|
|
|
|
- Add `macOS` platform config block (currently only `linux` exists):
|
|
|
|
|
```typescript
|
|
|
|
|
macOS: {
|
|
|
|
|
bundleCEF: true,
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
- Add `windows` platform config block:
|
|
|
|
|
```typescript
|
|
|
|
|
windows: {
|
|
|
|
|
bundleCEF: true,
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
- Verify the exact property names by checking Electrobun's `ElectrobunConfig` type definition. The `linux` block already uses `bundleCEF: true`, so follow the same pattern for other platforms. If the type doesn't support `macOS`/`windows` yet, skip those and leave a `// TODO:` comment explaining what's needed.
|
|
|
|
|
- Preserve existing config values exactly (app name, identifier, version, bun entrypoint, linux config).
|
|
|
|
|
|
|
|
|
|
**Must NOT do**:
|
|
|
|
|
- Do not change the app name, identifier, or version
|
|
|
|
|
- Do not change the bun entrypoint path
|
|
|
|
|
- Do not remove the existing `linux` config
|
|
|
|
|
- Do not add dependencies or scripts
|
|
|
|
|
|
|
|
|
|
**Recommended Agent Profile**:
|
|
|
|
|
- **Category**: `quick`
|
|
|
|
|
- Reason: Single file, small config change, clear specification
|
|
|
|
|
- **Skills**: `[]`
|
|
|
|
|
- No specialized skills needed — straightforward TypeScript config edit
|
|
|
|
|
- **Skills Evaluated but Omitted**:
|
|
|
|
|
- `frontend-ui-ux`: No UI work involved
|
|
|
|
|
|
|
|
|
|
**Parallelization**:
|
|
|
|
|
- **Can Run In Parallel**: YES
|
|
|
|
|
- **Parallel Group**: Wave 1 (with Tasks 2, 3)
|
|
|
|
|
- **Blocks**: Tasks 4, 5
|
|
|
|
|
- **Blocked By**: None (can start immediately)
|
|
|
|
|
|
|
|
|
|
**References**:
|
|
|
|
|
|
|
|
|
|
**Pattern References** (existing code to follow):
|
|
|
|
|
- `apps/desktop/electrobun.config.ts` — Current config structure. The `linux.bundleCEF: true` pattern should be replicated for other platforms. The `build.bun.entrypoint` key shows where build config lives.
|
|
|
|
|
|
|
|
|
|
**API/Type References** (contracts to implement against):
|
|
|
|
|
- The `ElectrobunConfig` type from `electrobun` — imported via `import type { ElectrobunConfig } from 'electrobun'`. Check its definition (likely in `node_modules/electrobun/`) to verify exact property names for `copy`, `macOS`, `windows`.
|
|
|
|
|
|
|
|
|
|
**External References**:
|
|
|
|
|
- Electrobun `build.copy` syntax: copies source (relative to project root) into `Resources/app/{dest}/` in the bundle. Uses `cpSync` with `dereference: true`.
|
|
|
|
|
|
|
|
|
|
**WHY Each Reference Matters**:
|
|
|
|
|
- `electrobun.config.ts`: You're editing this file — need to know its current shape to preserve existing values
|
|
|
|
|
- `ElectrobunConfig` type: Must match the type definition exactly — don't guess property names
|
|
|
|
|
|
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
|
- [ ] `build.copy` key exists with `'../server/.output': 'server-output'` mapping
|
|
|
|
|
- [ ] Platform configs added for all three platforms (or TODO comments if types don't support them)
|
|
|
|
|
- [ ] Existing config values unchanged (app.name = 'Desktop', etc.)
|
|
|
|
|
- [ ] File passes `bun typecheck` (no type errors)
|
|
|
|
|
|
|
|
|
|
**Agent-Executed QA Scenarios:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Scenario: Config file is valid TypeScript with correct types
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: None
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun typecheck (from apps/desktop/)
|
|
|
|
|
2. Assert: Exit code 0
|
|
|
|
|
3. Assert: No errors mentioning electrobun.config.ts
|
|
|
|
|
Expected Result: TypeScript compilation succeeds
|
|
|
|
|
Evidence: Terminal output captured
|
|
|
|
|
|
|
|
|
|
Scenario: build.copy key has correct structure
|
|
|
|
|
Tool: Bash (grep)
|
|
|
|
|
Preconditions: File has been edited
|
|
|
|
|
Steps:
|
|
|
|
|
1. Read apps/desktop/electrobun.config.ts
|
|
|
|
|
2. Assert: Contains '../server/.output'
|
|
|
|
|
3. Assert: Contains 'server-output'
|
|
|
|
|
4. Assert: File still contains 'satisfies ElectrobunConfig'
|
|
|
|
|
Expected Result: Config has copy mapping and type annotation
|
|
|
|
|
Evidence: File contents
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Commit**: YES (groups with 2)
|
|
|
|
|
- Message: `feat(desktop): add build.copy for server bundle and platform configs`
|
|
|
|
|
- Files: `apps/desktop/electrobun.config.ts`
|
|
|
|
|
- Pre-commit: `bun typecheck` (from `apps/desktop/`)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- [ ] 2. Update `apps/desktop/turbo.json` — Add cross-workspace build dependency
|
|
|
|
|
|
|
|
|
|
**What to do**:
|
|
|
|
|
- Add `dependsOn` to the existing `build` task to ensure the server builds before the desktop:
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"tasks": {
|
|
|
|
|
"build": {
|
|
|
|
|
"dependsOn": ["@furtherverse/server#build"],
|
|
|
|
|
"outputs": ["build/**", "artifacts/**"]
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
- This tells Turbo: "before running `build` for `@furtherverse/desktop`, first run `build` for `@furtherverse/server`."
|
|
|
|
|
- This ensures `apps/server/.output/` exists when `electrobun build` runs and tries to `build.copy` from `../server/.output`.
|
|
|
|
|
- Preserve the existing `outputs` array exactly.
|
|
|
|
|
|
|
|
|
|
**Must NOT do**:
|
|
|
|
|
- Do not modify the root `turbo.json` — only `apps/desktop/turbo.json`
|
|
|
|
|
- Do not remove existing `outputs`
|
|
|
|
|
- Do not add other tasks or change other config
|
|
|
|
|
|
|
|
|
|
**Recommended Agent Profile**:
|
|
|
|
|
- **Category**: `quick`
|
|
|
|
|
- Reason: Single file, one-line JSON change
|
|
|
|
|
- **Skills**: `[]`
|
|
|
|
|
- No specialized skills needed
|
|
|
|
|
- **Skills Evaluated but Omitted**:
|
|
|
|
|
- `git-master`: Commit will be grouped with Task 1
|
|
|
|
|
|
|
|
|
|
**Parallelization**:
|
|
|
|
|
- **Can Run In Parallel**: YES
|
|
|
|
|
- **Parallel Group**: Wave 1 (with Tasks 1, 3)
|
|
|
|
|
- **Blocks**: Tasks 4, 5
|
|
|
|
|
- **Blocked By**: None (can start immediately)
|
|
|
|
|
|
|
|
|
|
**References**:
|
|
|
|
|
|
|
|
|
|
**Pattern References** (existing code to follow):
|
|
|
|
|
- `apps/desktop/turbo.json` — Current file with `build.outputs` already defined. You're adding `dependsOn` alongside it.
|
|
|
|
|
- `turbo.json` (root) — Shows existing turbo patterns like `build.dependsOn: ["^build"]`. The root already uses `^build` for workspace dependencies, but since desktop doesn't list server as a package dependency, we need an explicit cross-workspace reference.
|
|
|
|
|
|
|
|
|
|
**API/Type References**:
|
|
|
|
|
- Turbo `dependsOn` syntax: `"@furtherverse/server#build"` means "run the `build` task in the `@furtherverse/server` workspace".
|
|
|
|
|
|
|
|
|
|
**Documentation References**:
|
|
|
|
|
- `apps/server/package.json` — The package name is `@furtherverse/server` (verify this is the exact name used in the `dependsOn` reference).
|
|
|
|
|
|
|
|
|
|
**WHY Each Reference Matters**:
|
|
|
|
|
- `apps/desktop/turbo.json`: You're editing this file — preserve existing outputs
|
|
|
|
|
- `apps/server/package.json`: Need exact package name for the cross-workspace reference
|
|
|
|
|
- Root `turbo.json`: Context for existing turbo patterns in this project
|
|
|
|
|
|
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
|
- [ ] `apps/desktop/turbo.json` has `dependsOn: ["@furtherverse/server#build"]` in the build task
|
|
|
|
|
- [ ] Existing `outputs` array is preserved
|
|
|
|
|
- [ ] Valid JSON (no syntax errors)
|
|
|
|
|
|
|
|
|
|
**Agent-Executed QA Scenarios:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Scenario: turbo.json is valid JSON with correct structure
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: File has been edited
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun -e "JSON.parse(require('fs').readFileSync('apps/desktop/turbo.json', 'utf8'))"
|
|
|
|
|
2. Assert: Exit code 0 (valid JSON)
|
|
|
|
|
3. Read the file and verify structure contains both dependsOn and outputs
|
|
|
|
|
Expected Result: Valid JSON with both keys present
|
|
|
|
|
Evidence: Terminal output captured
|
|
|
|
|
|
|
|
|
|
Scenario: Turbo resolves the cross-workspace dependency
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: turbo.json updated
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bunx turbo build --dry-run --filter=@furtherverse/desktop (from monorepo root)
|
|
|
|
|
2. Assert: Output shows @furtherverse/server#build runs BEFORE @furtherverse/desktop#build
|
|
|
|
|
Expected Result: Server build is listed as a dependency in the dry-run output
|
|
|
|
|
Evidence: Terminal output showing task execution order
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Commit**: YES (groups with 1)
|
|
|
|
|
- Message: `feat(desktop): add build.copy for server bundle and platform configs`
|
|
|
|
|
- Files: `apps/desktop/turbo.json`
|
|
|
|
|
- Pre-commit: Valid JSON check
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- [ ] 3. Rewrite `apps/desktop/src/bun/index.ts` — Complete dev/prod mode implementation
|
|
|
|
|
|
|
|
|
|
**What to do**:
|
|
|
|
|
|
|
|
|
|
This is the core task. Completely rewrite `index.ts` to support both dev and prod modes. The new file should have this structure:
|
|
|
|
|
|
|
|
|
|
**A. Imports and Constants**:
|
|
|
|
|
```typescript
|
|
|
|
|
import Electrobun, { BrowserWindow } from 'electrobun/bun'
|
|
|
|
|
// Import PATHS — verify exact import syntax from electrobun/bun type definitions
|
|
|
|
|
// It may be: import { PATHS } from 'electrobun/bun'
|
|
|
|
|
// Or it may be on the Electrobun default export: Electrobun.PATHS
|
|
|
|
|
// CHECK the type definitions in node_modules/electrobun/ before writing
|
|
|
|
|
import { join, dirname } from 'path'
|
|
|
|
|
|
|
|
|
|
const DEV_SERVER_URL = 'http://localhost:3000'
|
|
|
|
|
const SERVER_READY_TIMEOUT_MS = 30_000
|
|
|
|
|
const PORT_PATTERN = /Listening on:?\s*https?:\/\/[^\s:]+:(\d+)/
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**B. `isDev()` function**:
|
|
|
|
|
- Check `process.env.ELECTROBUN_BUILD_ENV === 'dev'`
|
|
|
|
|
- If `ELECTROBUN_BUILD_ENV` is not set, default to `true` (dev mode) — safe fallback
|
|
|
|
|
- Return a boolean
|
|
|
|
|
|
|
|
|
|
**C. `getServerEntryPath()` function**:
|
|
|
|
|
- Use `PATHS.RESOURCES_FOLDER` (or equivalent) to resolve the bundled server entry
|
|
|
|
|
- Path: `join(PATHS.RESOURCES_FOLDER, 'app', 'server-output', 'server', 'index.mjs')`
|
|
|
|
|
- **IMPORTANT**: Verify `PATHS.RESOURCES_FOLDER` points to `Resources/` and that `build.copy` destinations land in `Resources/app/`. If the pathing is different, adjust accordingly. The executor MUST verify by checking Electrobun's source or type definitions.
|
|
|
|
|
|
|
|
|
|
**D. `waitForServer(url, timeoutMs)` function** (preserved from current code):
|
|
|
|
|
- Polls a URL with `fetch` HEAD requests
|
|
|
|
|
- Returns `true` when server responds with `response.ok`
|
|
|
|
|
- Returns `false` on timeout
|
|
|
|
|
- Uses `Bun.sleep(100)` between attempts
|
|
|
|
|
- Catches fetch errors silently (server not up yet)
|
|
|
|
|
|
|
|
|
|
**E. `spawnServer()` function** (NEW — the critical piece):
|
|
|
|
|
- Returns a `Promise<{ process: Subprocess; url: string }>`
|
|
|
|
|
- Implementation:
|
|
|
|
|
1. Resolve the server entry path via `getServerEntryPath()`
|
|
|
|
|
2. Resolve the server directory via `dirname(serverEntryPath)` — used as `cwd`
|
|
|
|
|
3. Spawn with `Bun.spawn`:
|
|
|
|
|
```typescript
|
|
|
|
|
const serverProc = Bun.spawn([process.execPath, serverEntryPath], {
|
|
|
|
|
cwd: serverDir,
|
|
|
|
|
env: {
|
|
|
|
|
...process.env,
|
|
|
|
|
PORT: '0',
|
|
|
|
|
HOST: '127.0.0.1',
|
|
|
|
|
},
|
|
|
|
|
stdout: 'pipe',
|
|
|
|
|
stderr: 'pipe',
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
4. Read stdout as a stream to find the port:
|
|
|
|
|
- Use `serverProc.stdout` (a `ReadableStream<Uint8Array>`)
|
|
|
|
|
- Create a reader, accumulate chunks into a text buffer
|
|
|
|
|
- Test buffer against `PORT_PATTERN` regex after each chunk
|
|
|
|
|
- When match found: extract port, resolve promise with `{ process: serverProc, url: 'http://127.0.0.1:${port}' }`
|
|
|
|
|
5. Implement a timeout:
|
|
|
|
|
- Use `setTimeout` to reject the promise after `SERVER_READY_TIMEOUT_MS`
|
|
|
|
|
- On timeout, kill the server process before rejecting
|
|
|
|
|
6. Handle early exit:
|
|
|
|
|
- If stdout ends (stream done) before port is found, reject with error
|
|
|
|
|
- Include any stderr output in the error message for debugging
|
|
|
|
|
|
|
|
|
|
**F. `main()` async function**:
|
|
|
|
|
- Log startup message
|
|
|
|
|
- Branch on `isDev()`:
|
|
|
|
|
- **Dev mode**:
|
|
|
|
|
1. Log: "Dev mode: waiting for external server..."
|
|
|
|
|
2. Call `waitForServer(DEV_SERVER_URL)`
|
|
|
|
|
3. If timeout: log error with instructions (`"Run: bun dev in apps/server"`), `process.exit(1)`
|
|
|
|
|
4. Set `serverUrl = DEV_SERVER_URL`
|
|
|
|
|
- **Prod mode**:
|
|
|
|
|
1. Log: "Production mode: starting embedded server..."
|
|
|
|
|
2. Call `spawnServer()`
|
|
|
|
|
3. If error: log error, `process.exit(1)`
|
|
|
|
|
4. Store returned `process` and `url`
|
|
|
|
|
- Create `BrowserWindow` with the resolved `serverUrl`:
|
|
|
|
|
```typescript
|
|
|
|
|
new BrowserWindow({
|
|
|
|
|
title: 'Furtherverse',
|
|
|
|
|
url: serverUrl,
|
|
|
|
|
frame: { x: 100, y: 100, width: 1200, height: 800 },
|
|
|
|
|
renderer: 'cef',
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
- Register lifecycle handlers:
|
|
|
|
|
- `Electrobun.events.on('before-quit', ...)`: Kill server process if it exists
|
|
|
|
|
- Watch `serverProcess.exited` (if in prod mode): When server exits unexpectedly, log the exit code and stderr, then `process.exit(1)`
|
|
|
|
|
|
|
|
|
|
**G. Top-level execution**:
|
|
|
|
|
```typescript
|
|
|
|
|
main().catch((error) => {
|
|
|
|
|
console.error('Failed to start:', error)
|
|
|
|
|
process.exit(1)
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Critical implementation details**:
|
|
|
|
|
- The `PORT_PATTERN` regex must handle multiple log formats:
|
|
|
|
|
- `➜ Listening on: http://localhost:54321/` (srvx format)
|
|
|
|
|
- `Listening on http://127.0.0.1:54321` (node-server format)
|
|
|
|
|
- `Listening on http://[::]:54321` (IPv6 format)
|
|
|
|
|
- The regex `/Listening on:?\s*https?:\/\/[^\s:]+:(\d+)/` captures the port from all these formats.
|
|
|
|
|
- `cwd` MUST be set to the server directory (`dirname(serverEntryPath)`), not the app root. Nitro resolves internal `_libs/` imports relative to its directory.
|
|
|
|
|
- `process.execPath` in an Electrobun bundle points to the bundled Bun binary — this is what runs the server.
|
|
|
|
|
- `stderr: 'pipe'` — capture stderr for crash diagnostics but don't block on it during startup.
|
|
|
|
|
|
|
|
|
|
**Must NOT do**:
|
|
|
|
|
- Do not hardcode port numbers anywhere (use `PORT=0` and parse result)
|
|
|
|
|
- Do not use `as any` or type assertions to work around issues
|
|
|
|
|
- Do not use `child_process` module — use `Bun.spawn` (native Bun API)
|
|
|
|
|
- Do not bind server to `0.0.0.0` — always use `127.0.0.1`
|
|
|
|
|
- Do not leave the `waitForServer` function unused in dev mode
|
|
|
|
|
- Do not use synchronous I/O for stdout reading
|
|
|
|
|
|
|
|
|
|
**Recommended Agent Profile**:
|
|
|
|
|
- **Category**: `unspecified-high`
|
|
|
|
|
- Reason: Complex async logic (stream parsing, subprocess lifecycle, timeout management), multiple code paths (dev/prod), error handling across process boundaries. This is the architectural centerpiece.
|
|
|
|
|
- **Skills**: `[]`
|
|
|
|
|
- No specialized skills needed — pure Bun/TypeScript with Electrobun APIs
|
|
|
|
|
- **Skills Evaluated but Omitted**:
|
|
|
|
|
- `frontend-ui-ux`: No UI work — this is backend/process management code
|
|
|
|
|
- `playwright`: No browser testing needed for this task
|
|
|
|
|
|
|
|
|
|
**Parallelization**:
|
|
|
|
|
- **Can Run In Parallel**: YES
|
|
|
|
|
- **Parallel Group**: Wave 1 (with Tasks 1, 2)
|
|
|
|
|
- **Blocks**: Tasks 4, 5
|
|
|
|
|
- **Blocked By**: None (can start immediately — edits a different file from Tasks 1, 2)
|
|
|
|
|
|
|
|
|
|
**References**:
|
|
|
|
|
|
|
|
|
|
**Pattern References** (existing code to follow):
|
|
|
|
|
- `apps/desktop/src/bun/index.ts` — Current implementation. Preserve the `waitForServer` polling pattern (slightly refactored). Keep the `BrowserWindow` config (title, frame dimensions, renderer). Keep the top-level `main().catch(...)` pattern.
|
|
|
|
|
- `apps/desktop/src/bun/index.ts:1` — Current import: `import Electrobun, { BrowserWindow } from 'electrobun/bun'`. Extend this to also import `PATHS` (verify exact export name from type definitions).
|
|
|
|
|
|
|
|
|
|
**API/Type References** (contracts to implement against):
|
|
|
|
|
- `electrobun/bun` module — Exports `Electrobun` (default), `BrowserWindow` (named), and `PATHS` (named — verify). Check `node_modules/electrobun/` for exact type definitions.
|
|
|
|
|
- `Bun.spawn` API — Returns `Subprocess` with `.stdout` (ReadableStream when piped), `.stderr`, `.exited` (Promise<number>), `.kill()`.
|
|
|
|
|
- `PATHS.RESOURCES_FOLDER` — Absolute path to `Resources/` directory in the bundle. Verify by reading the Paths.ts source in electrobun package.
|
|
|
|
|
|
|
|
|
|
**Documentation References**:
|
|
|
|
|
- `apps/desktop/AGENTS.md` — Mentions production mode architecture (aspirational, but gives intent)
|
|
|
|
|
|
|
|
|
|
**External References**:
|
|
|
|
|
- Electrobun lifecycle events: `Electrobun.events.on('before-quit', callback)` — callback can call `event.response({ allow: false })` to cancel. Source: `electrobun/src/bun/core/Utils.ts`.
|
|
|
|
|
- Electrobun `PATHS`: Source at `electrobun/src/bun/core/Paths.ts`. Contains `RESOURCES_FOLDER` and `VIEWS_FOLDER`.
|
|
|
|
|
- Bun `Subprocess` docs: `stdout` is `ReadableStream<Uint8Array>` when `stdout: 'pipe'`.
|
|
|
|
|
|
|
|
|
|
**WHY Each Reference Matters**:
|
|
|
|
|
- Current `index.ts`: Preserving the `waitForServer` pattern, `BrowserWindow` config, and error handling style. You're rewriting this file, so understand what to keep vs. replace.
|
|
|
|
|
- `electrobun/bun` types: MUST verify `PATHS` export name and shape before using it. Don't assume — check.
|
|
|
|
|
- `Bun.spawn` API: Core to the entire prod mode implementation. Understand `stdout` stream reading.
|
|
|
|
|
- Lifecycle events: `before-quit` is where server cleanup happens. Understand the event contract.
|
|
|
|
|
|
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
|
- [ ] File compiles: `bun typecheck` passes (from `apps/desktop/`)
|
|
|
|
|
- [ ] No hardcoded port numbers (grep for `:3000` — should only appear in `DEV_SERVER_URL` constant)
|
|
|
|
|
- [ ] `isDev()` function uses `process.env.ELECTROBUN_BUILD_ENV`
|
|
|
|
|
- [ ] `spawnServer()` uses `PORT=0`, `HOST=127.0.0.1`, `process.execPath`
|
|
|
|
|
- [ ] `spawnServer()` sets `cwd` to `dirname(serverEntryPath)`
|
|
|
|
|
- [ ] `before-quit` handler kills server process
|
|
|
|
|
- [ ] Server crash watcher exists (watches `subprocess.exited`)
|
|
|
|
|
- [ ] Timeout handling exists in both dev and prod paths
|
|
|
|
|
- [ ] All Biome rules pass: `bun fix` produces no changes
|
|
|
|
|
|
|
|
|
|
**Agent-Executed QA Scenarios:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Scenario: File compiles with zero type errors
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun typecheck (from apps/desktop/)
|
|
|
|
|
2. Assert: Exit code 0
|
|
|
|
|
3. Assert: No errors in output
|
|
|
|
|
Expected Result: Clean TypeScript compilation
|
|
|
|
|
Evidence: Terminal output captured
|
|
|
|
|
|
|
|
|
|
Scenario: No hardcoded ports outside DEV_SERVER_URL
|
|
|
|
|
Tool: Bash (grep)
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Search apps/desktop/src/bun/index.ts for literal ':3000'
|
|
|
|
|
2. Assert: Only occurrence is in the DEV_SERVER_URL constant definition
|
|
|
|
|
3. Search for literal '3000' — should only appear once
|
|
|
|
|
Expected Result: Port 3000 only in constant, nowhere else
|
|
|
|
|
Evidence: Grep output
|
|
|
|
|
|
|
|
|
|
Scenario: Code passes Biome lint/format
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun fix (from apps/desktop/)
|
|
|
|
|
2. Run: git diff apps/desktop/src/bun/index.ts
|
|
|
|
|
3. Assert: No diff (bun fix made no changes)
|
|
|
|
|
Expected Result: Code already conforms to Biome rules
|
|
|
|
|
Evidence: Empty git diff
|
|
|
|
|
|
|
|
|
|
Scenario: Required patterns present in source
|
|
|
|
|
Tool: Bash (grep)
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Grep for 'ELECTROBUN_BUILD_ENV' — Assert: found
|
|
|
|
|
2. Grep for 'Bun.spawn' — Assert: found
|
|
|
|
|
3. Grep for 'process.execPath' — Assert: found
|
|
|
|
|
4. Grep for 'PORT.*0' — Assert: found
|
|
|
|
|
5. Grep for '127.0.0.1' — Assert: found
|
|
|
|
|
6. Grep for 'before-quit' — Assert: found
|
|
|
|
|
7. Grep for '.exited' — Assert: found (crash watcher)
|
|
|
|
|
8. Grep for 'dirname' — Assert: found (cwd for server)
|
|
|
|
|
Expected Result: All required patterns present
|
|
|
|
|
Evidence: Grep results for each pattern
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Commit**: YES
|
|
|
|
|
- Message: `feat(desktop): implement production mode with child process server`
|
|
|
|
|
- Files: `apps/desktop/src/bun/index.ts`
|
|
|
|
|
- Pre-commit: `bun typecheck && bun fix`
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- [ ] 4. Rewrite `apps/desktop/AGENTS.md` — Document new architecture
|
|
|
|
|
|
|
|
|
|
**What to do**:
|
|
|
|
|
- Completely rewrite `AGENTS.md` to reflect the actual implemented architecture
|
|
|
|
|
- Document:
|
|
|
|
|
- **Architecture overview**: Desktop spawns server as child process in prod, connects to external server in dev
|
|
|
|
|
- **Dev mode**: How it works (polls localhost:3000, requires server running separately)
|
|
|
|
|
- **Prod mode**: How it works (spawns server from bundle, PORT=0, parses port from stdout)
|
|
|
|
|
- **Environment detection**: `ELECTROBUN_BUILD_ENV` values (`dev`, `canary`, `stable`)
|
|
|
|
|
- **Build pipeline**: Server must build before desktop (turbo dependency), `build.copy` bundles output
|
|
|
|
|
- **Key files**: `src/bun/index.ts` (main process), `electrobun.config.ts` (build config)
|
|
|
|
|
- **Environment variables**: `DATABASE_URL` (required, passed to server), `ELECTROBUN_BUILD_ENV` (auto-set by CLI)
|
|
|
|
|
- **Server lifecycle**: Spawned on start, killed on quit, crash = exit
|
|
|
|
|
- **Commands**: `bun dev`, `bun build`, `bun typecheck`, `bun fix`
|
|
|
|
|
- Follow the style and conventions of the root `AGENTS.md` and `apps/server/AGENTS.md`
|
|
|
|
|
- Be factual — only document what actually exists, not aspirational features
|
|
|
|
|
|
|
|
|
|
**Must NOT do**:
|
|
|
|
|
- Do not document features that don't exist
|
|
|
|
|
- Do not copy content from the server's AGENTS.md verbatim
|
|
|
|
|
- Do not include implementation details that belong in code comments
|
|
|
|
|
|
|
|
|
|
**Recommended Agent Profile**:
|
|
|
|
|
- **Category**: `writing`
|
|
|
|
|
- Reason: Documentation task requiring clear technical writing
|
|
|
|
|
- **Skills**: `[]`
|
|
|
|
|
- No specialized skills needed
|
|
|
|
|
- **Skills Evaluated but Omitted**:
|
|
|
|
|
- `frontend-ui-ux`: Not a UI task
|
|
|
|
|
|
|
|
|
|
**Parallelization**:
|
|
|
|
|
- **Can Run In Parallel**: NO
|
|
|
|
|
- **Parallel Group**: Wave 2
|
|
|
|
|
- **Blocks**: Task 5
|
|
|
|
|
- **Blocked By**: Tasks 1, 2, 3 (needs to know final state of all files)
|
|
|
|
|
|
|
|
|
|
**References**:
|
|
|
|
|
|
|
|
|
|
**Pattern References** (existing code to follow):
|
|
|
|
|
- `AGENTS.md` (root) — Follow same structure: Overview, Build Commands, Code Style, Directory Structure sections
|
|
|
|
|
- `apps/server/AGENTS.md` — Follow same style for app-specific documentation. Use this as a template for tone and detail level.
|
|
|
|
|
|
|
|
|
|
**Content References** (what to document):
|
|
|
|
|
- `apps/desktop/src/bun/index.ts` — The rewritten file (Task 3 output). Document its behavior, not its code.
|
|
|
|
|
- `apps/desktop/electrobun.config.ts` — The updated config (Task 1 output). Document build.copy and platform configs.
|
|
|
|
|
- `apps/desktop/turbo.json` — The updated turbo config (Task 2 output). Document the build dependency.
|
|
|
|
|
|
|
|
|
|
**WHY Each Reference Matters**:
|
|
|
|
|
- Root `AGENTS.md`: Template for documentation style
|
|
|
|
|
- Server `AGENTS.md`: Template for app-specific docs
|
|
|
|
|
- All Task 1-3 outputs: The actual implemented behavior that must be accurately documented
|
|
|
|
|
|
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
|
- [ ] File exists and is valid Markdown
|
|
|
|
|
- [ ] Documents dev mode behavior accurately
|
|
|
|
|
- [ ] Documents prod mode behavior accurately
|
|
|
|
|
- [ ] Documents `ELECTROBUN_BUILD_ENV` mechanism
|
|
|
|
|
- [ ] Documents build pipeline (server → desktop dependency)
|
|
|
|
|
- [ ] Documents `DATABASE_URL` requirement
|
|
|
|
|
- [ ] Does NOT mention features that don't exist
|
|
|
|
|
- [ ] Follows conventions from root `AGENTS.md`
|
|
|
|
|
|
|
|
|
|
**Agent-Executed QA Scenarios:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Scenario: AGENTS.md contains all required sections
|
|
|
|
|
Tool: Bash (grep)
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Grep for 'dev' or 'Dev' — Assert: found (dev mode documented)
|
|
|
|
|
2. Grep for 'prod' or 'Prod' or 'production' — Assert: found (prod mode documented)
|
|
|
|
|
3. Grep for 'ELECTROBUN_BUILD_ENV' — Assert: found
|
|
|
|
|
4. Grep for 'DATABASE_URL' — Assert: found
|
|
|
|
|
5. Grep for 'child process' or 'spawn' — Assert: found (architecture documented)
|
|
|
|
|
6. Grep for 'bun dev' — Assert: found (commands documented)
|
|
|
|
|
7. Grep for 'bun build' — Assert: found (commands documented)
|
|
|
|
|
Expected Result: All key topics are covered
|
|
|
|
|
Evidence: Grep results
|
|
|
|
|
|
|
|
|
|
Scenario: No aspirational/unimplemented features documented
|
|
|
|
|
Tool: Bash (grep)
|
|
|
|
|
Preconditions: File has been rewritten
|
|
|
|
|
Steps:
|
|
|
|
|
1. Grep for 'TODO' or 'planned' or 'future' or 'coming soon' — Assert: not found (or minimal)
|
|
|
|
|
2. Grep for 'auto-update' — Assert: not found (not implemented)
|
|
|
|
|
3. Grep for 'tray' — Assert: not found (not implemented)
|
|
|
|
|
Expected Result: Only implemented features documented
|
|
|
|
|
Evidence: Grep results showing no aspirational content
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Commit**: YES
|
|
|
|
|
- Message: `docs(desktop): rewrite AGENTS.md to reflect production mode architecture`
|
|
|
|
|
- Files: `apps/desktop/AGENTS.md`
|
|
|
|
|
- Pre-commit: None (Markdown file)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
- [ ] 5. End-to-end verification — Typecheck and build pipeline
|
|
|
|
|
|
|
|
|
|
**What to do**:
|
|
|
|
|
- Run full monorepo typecheck to ensure no type errors were introduced
|
|
|
|
|
- Run full monorepo build to verify:
|
|
|
|
|
1. Server builds first (produces `.output/`)
|
|
|
|
|
2. Desktop builds second (copies server output into bundle)
|
|
|
|
|
3. No build errors
|
|
|
|
|
- Run Biome formatting/linting check on all changed files
|
|
|
|
|
- Verify dev mode still works conceptually (no runtime test — just verify the code path exists)
|
|
|
|
|
|
|
|
|
|
**Must NOT do**:
|
|
|
|
|
- Do not fix issues in server code — only desktop code
|
|
|
|
|
- Do not modify any files unless fixing issues found during verification
|
|
|
|
|
- Do not skip any verification step
|
|
|
|
|
|
|
|
|
|
**Recommended Agent Profile**:
|
|
|
|
|
- **Category**: `quick`
|
|
|
|
|
- Reason: Running commands and checking output, no creative work
|
|
|
|
|
- **Skills**: `[]`
|
|
|
|
|
- No specialized skills needed
|
|
|
|
|
- **Skills Evaluated but Omitted**:
|
|
|
|
|
- `playwright`: No browser testing in this verification
|
|
|
|
|
|
|
|
|
|
**Parallelization**:
|
|
|
|
|
- **Can Run In Parallel**: NO
|
|
|
|
|
- **Parallel Group**: Wave 2 (sequential after Task 4)
|
|
|
|
|
- **Blocks**: None (final task)
|
|
|
|
|
- **Blocked By**: Tasks 1, 2, 3, 4
|
|
|
|
|
|
|
|
|
|
**References**:
|
|
|
|
|
|
|
|
|
|
**Documentation References**:
|
|
|
|
|
- `AGENTS.md` (root) — Build/Lint/Test commands: `bun typecheck`, `bun fix`, `bun build`
|
|
|
|
|
- `apps/desktop/package.json` — Desktop-specific scripts
|
|
|
|
|
|
|
|
|
|
**WHY Each Reference Matters**:
|
|
|
|
|
- Root `AGENTS.md`: Canonical list of verification commands
|
|
|
|
|
- Desktop `package.json`: Desktop-specific build/typecheck commands
|
|
|
|
|
|
|
|
|
|
**Acceptance Criteria**:
|
|
|
|
|
- [ ] `bun typecheck` (monorepo root) exits with code 0
|
|
|
|
|
- [ ] `bun build` (monorepo root) exits with code 0
|
|
|
|
|
- [ ] `bun fix` (monorepo root) produces no changes (all code formatted)
|
|
|
|
|
- [ ] Build output shows server building before desktop
|
|
|
|
|
- [ ] Desktop build output includes server bundle (verify in build artifacts)
|
|
|
|
|
|
|
|
|
|
**Agent-Executed QA Scenarios:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Scenario: Monorepo typecheck passes
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: All tasks 1-4 completed
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun typecheck (from monorepo root)
|
|
|
|
|
2. Assert: Exit code 0
|
|
|
|
|
3. Assert: No error output
|
|
|
|
|
Expected Result: Zero type errors across entire monorepo
|
|
|
|
|
Evidence: Terminal output captured
|
|
|
|
|
|
|
|
|
|
Scenario: Monorepo build succeeds with correct order
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: All tasks 1-4 completed
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun build (from monorepo root)
|
|
|
|
|
2. Assert: Exit code 0
|
|
|
|
|
3. Assert: Output shows @furtherverse/server build task runs
|
|
|
|
|
4. Assert: Output shows @furtherverse/desktop build task runs AFTER server
|
|
|
|
|
Expected Result: Build pipeline executes in correct order
|
|
|
|
|
Evidence: Terminal output showing task order
|
|
|
|
|
|
|
|
|
|
Scenario: Biome finds no issues
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: All tasks 1-4 completed
|
|
|
|
|
Steps:
|
|
|
|
|
1. Run: bun fix (from monorepo root)
|
|
|
|
|
2. Run: git diff
|
|
|
|
|
3. Assert: No changes (all code already formatted)
|
|
|
|
|
Expected Result: All code passes Biome rules
|
|
|
|
|
Evidence: Empty git diff
|
|
|
|
|
|
|
|
|
|
Scenario: Desktop build artifacts include server bundle
|
|
|
|
|
Tool: Bash
|
|
|
|
|
Preconditions: Build succeeded
|
|
|
|
|
Steps:
|
|
|
|
|
1. Search desktop build output directory for server-output/ or index.mjs
|
|
|
|
|
2. Assert: Server files are present in the desktop bundle
|
|
|
|
|
Expected Result: Server bundle is included in desktop build output
|
|
|
|
|
Evidence: File listing of build artifacts
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Commit**: NO (verification only — no file changes unless fixing issues)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Commit Strategy
|
|
|
|
|
|
|
|
|
|
| After Task(s) | Message | Files | Verification |
|
|
|
|
|
|---------------|---------|-------|--------------|
|
|
|
|
|
| 1, 2 | `feat(desktop): add build.copy for server bundle and cross-workspace build dependency` | `electrobun.config.ts`, `turbo.json` | `bun typecheck` |
|
|
|
|
|
| 3 | `feat(desktop): implement production mode with child process server` | `src/bun/index.ts` | `bun typecheck && bun fix` |
|
|
|
|
|
| 4 | `docs(desktop): rewrite AGENTS.md to reflect production mode architecture` | `AGENTS.md` | None |
|
|
|
|
|
| 5 | (no commit — verification only) | — | — |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Success Criteria
|
|
|
|
|
|
|
|
|
|
### Verification Commands
|
|
|
|
|
```bash
|
|
|
|
|
bun typecheck # Expected: exit 0, no errors
|
|
|
|
|
bun build # Expected: exit 0, server builds before desktop
|
|
|
|
|
bun fix # Expected: no changes (already formatted)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Final Checklist
|
|
|
|
|
- [ ] All "Must Have" features present in `index.ts`
|
|
|
|
|
- [ ] All "Must NOT Have" exclusions verified absent
|
|
|
|
|
- [ ] All 3 verification commands pass
|
|
|
|
|
- [ ] `AGENTS.md` accurately reflects implemented architecture
|
|
|
|
|
- [ ] Server output is bundled into desktop build via `build.copy`
|
|
|
|
|
- [ ] Turbo builds server before desktop
|
