Skip to content

Commit 87483c3

Browse files
committed
more render changes, more plans
1 parent 54bc785 commit 87483c3

14 files changed

Lines changed: 611 additions & 60 deletions
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Plan: Centralize Model Normalization in Contracts
2+
3+
## Summary
4+
Move model alias/default normalization into `packages/contracts` so desktop and renderer use one shared source of truth.
5+
6+
## Motivation
7+
- Removes duplicated logic between:
8+
- `apps/desktop/src/codexAppServerManager.ts`
9+
- `apps/renderer/src/model-logic.ts`
10+
- Prevents behavior drift when model aliases/defaults are updated.
11+
12+
## Scope
13+
- Add shared model utilities to contracts.
14+
- Update desktop and renderer to consume shared utilities.
15+
- Keep renderer-specific display options in renderer.
16+
17+
## Proposed Changes
18+
1. Add `packages/contracts/src/model.ts` with:
19+
- Canonical model list
20+
- Alias map
21+
- `normalizeModelSlug`
22+
- `resolveModelSlug`
23+
- `DEFAULT_MODEL`
24+
2. Export model utilities from `packages/contracts/src/index.ts`.
25+
3. Update `apps/desktop/src/codexAppServerManager.ts` to replace local alias map/helper.
26+
4. Update `apps/renderer/src/model-logic.ts` to wrap or re-export shared functions.
27+
5. Update tests:
28+
- Move/duplicate normalization tests to contracts.
29+
- Keep renderer tests focused on renderer-only behavior.
30+
31+
## Risks
32+
- Desktop/renderer may currently rely on slightly different fallback behavior.
33+
- Import graph must avoid bundling issues for Electron main/preload.
34+
35+
## Validation
36+
- `bun run test`
37+
- `bun run typecheck`
38+
- Manual check that model selection and session start still send expected model slug.
39+
40+
## Done Criteria
41+
- No duplicated alias/default map in desktop and renderer.
42+
- Shared model utilities are contract-tested.

‎.plans/02-typed-ipc-boundaries.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Plan: Strengthen Typed IPC Boundaries in Main Process
2+
3+
## Summary
4+
Replace loose payload casting in IPC handlers with strict schema parsing and typed helper wrappers.
5+
6+
## Motivation
7+
- `apps/desktop/src/main.ts` currently uses casts like `payload as Parameters<...>`.
8+
- Casts can hide contract breakages until runtime.
9+
10+
## Scope
11+
- Desktop main process IPC registration.
12+
- Optional shared helper for handler registration.
13+
14+
## Proposed Changes
15+
1. Add IPC helper utility (e.g. `apps/desktop/src/ipcHelpers.ts`) to:
16+
- Parse payload(s) with Zod schemas
17+
- Standardize typed handler signatures
18+
2. Refactor provider IPC handlers in `apps/desktop/src/main.ts` to use:
19+
- `providerSessionStartInputSchema.parse`
20+
- `providerSendTurnInputSchema.parse`
21+
- `providerInterruptTurnInputSchema.parse`
22+
- `providerStopSessionInputSchema.parse`
23+
3. Apply same pattern to agent/terminal handlers where possible.
24+
4. Add tests for handler parsing failure paths (invalid payloads).
25+
26+
## Risks
27+
- Refactor can subtly change IPC error shape/messages.
28+
- Helper abstraction should stay simple and not obscure control flow.
29+
30+
## Validation
31+
- `bun run test`
32+
- `bun run typecheck`
33+
- Manual invalid payload check from renderer/devtools to confirm fast failure.
34+
35+
## Done Criteria
36+
- No provider handler uses `payload as Parameters<...>`.
37+
- All IPC entrypoints parse unknown payloads at boundary.
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Plan: Decompose CodexAppServerManager
2+
3+
## Summary
4+
Split `CodexAppServerManager` into smaller modules with clear responsibilities.
5+
6+
## Motivation
7+
- `apps/desktop/src/codexAppServerManager.ts` is large and mixes:
8+
- Process lifecycle
9+
- JSON-RPC parsing/routing
10+
- Session state transitions
11+
- Event emission
12+
- This increases regression risk and slows changes.
13+
14+
## Scope
15+
- Desktop provider internals only.
16+
- Keep external behavior/API stable.
17+
18+
## Proposed Changes
19+
1. Extract modules:
20+
- `codex/processLifecycle.ts`
21+
- `codex/jsonrpcRouter.ts`
22+
- `codex/sessionState.ts`
23+
- `codex/parsing.ts`
24+
2. Keep `CodexAppServerManager` as thin orchestrator/facade.
25+
3. Move pure helpers (`classifyCodexStderrLine`, route parsing) into unit-testable files.
26+
4. Add targeted unit tests for:
27+
- Message classification
28+
- Request/notification/response routing
29+
- Session state transitions
30+
31+
## Risks
32+
- Reordering event handling can change behavior.
33+
- Must preserve pending request timeout/cancellation semantics.
34+
35+
## Validation
36+
- Existing tests pass.
37+
- Add module-level tests for parsing and transition logic.
38+
39+
## Done Criteria
40+
- Main manager file materially smaller and orchestration-focused.
41+
- Core protocol/state logic covered by focused tests.
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Plan: Split ChatView into Smaller UI/Logic Units
2+
3+
## Summary
4+
Refactor `ChatView.tsx` into composable pieces with isolated responsibilities.
5+
6+
## Motivation
7+
- `apps/renderer/src/components/ChatView.tsx` is large and handles:
8+
- Session orchestration
9+
- Send/interrupt actions
10+
- Timeline rendering
11+
- Header/status UI
12+
- Composer UI
13+
- Hard to test and maintain as one component.
14+
15+
## Scope
16+
- Renderer component boundaries and hooks.
17+
- Keep visual behavior unchanged.
18+
19+
## Proposed Changes
20+
1. Create hook: `apps/renderer/src/hooks/useChatSession.ts`
21+
- `ensureSession`
22+
- `sendTurn`
23+
- `interruptTurn`
24+
2. Split presentational components:
25+
- `components/chat/ThreadHeader.tsx`
26+
- `components/chat/MessageTimeline.tsx`
27+
- `components/chat/ComposerBar.tsx`
28+
3. Keep `ChatView.tsx` as container wiring store + hook + child components.
29+
4. Add focused tests for hook behavior (error handling, session reuse).
30+
31+
## Risks
32+
- Refactor can break subtle UI interactions (auto-scroll, menu close, keyboard send).
33+
34+
## Validation
35+
- `bun run test`
36+
- Manual smoke: send, stream, interrupt, model switch.
37+
38+
## Done Criteria
39+
- `ChatView.tsx` significantly reduced and easier to scan.
40+
- Session logic isolated from rendering.
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Plan: Move Renderer Persisted-State Validation to Zod
2+
3+
## Summary
4+
Use explicit Zod schemas for localStorage state parsing and migration.
5+
6+
## Motivation
7+
- `apps/renderer/src/store.ts` has large manual sanitize functions.
8+
- Manual type guards are verbose and easier to get wrong during schema evolution.
9+
10+
## Scope
11+
- Renderer state hydration/persistence path.
12+
- No backend/protocol changes.
13+
14+
## Proposed Changes
15+
1. Add schema module: `apps/renderer/src/persistenceSchema.ts`
16+
- Persisted payload versions (`v1`, `v2`)
17+
- Thread/message/project schemas
18+
2. Replace `sanitizeProjects/sanitizeThreads/sanitizeMessages` with schema parsing + transforms.
19+
3. Keep migration logic explicit (legacy model migration and key migration).
20+
4. Add tests for:
21+
- Invalid payload fallback to initial state
22+
- Legacy payload migration
23+
- Unknown thread/project references filtered
24+
25+
## Risks
26+
- Overly strict schemas could drop valid historical data unexpectedly.
27+
28+
## Validation
29+
- Unit tests for migration/hydration.
30+
- Manual reload test with existing localStorage data.
31+
32+
## Done Criteria
33+
- Store hydration logic is schema-driven.
34+
- Migration behavior is tested and documented.
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Plan: Add Provider Log Stream Lifecycle Management
2+
3+
## Summary
4+
Ensure `ProviderManager` logging stream is initialized, rotated/structured, and closed safely.
5+
6+
## Motivation
7+
- `apps/desktop/src/providerManager.ts` opens a write stream in constructor.
8+
- Stream lifecycle is not explicit on shutdown.
9+
10+
## Scope
11+
- Desktop provider logging behavior.
12+
- App shutdown integration.
13+
14+
## Proposed Changes
15+
1. Add explicit `dispose()` on `ProviderManager`:
16+
- Remove event listeners
17+
- End/close log stream
18+
2. Call `providerManager.dispose()` from app shutdown path in `apps/desktop/src/main.ts`.
19+
3. Optional: change log format to JSON lines with stable fields.
20+
4. Optional: per-session log files under `.logs/providers/`.
21+
22+
## Risks
23+
- Improper close sequencing may lose final log lines.
24+
25+
## Validation
26+
- Manual run/quit cycle to ensure no open handle warnings.
27+
- Confirm logs flush on quit and file descriptors are not leaked.
28+
29+
## Done Criteria
30+
- ProviderManager owns complete log stream lifecycle.
31+
- Shutdown path explicitly disposes provider resources.

‎.plans/07-ci-quality-gates.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Plan: Add CI Workflow for Core Quality Gates
2+
3+
## Summary
4+
Add GitHub Actions workflow to run lint/typecheck/test (and optionally smoke-test) on pushes and PRs.
5+
6+
## Motivation
7+
- Repository currently has no CI workflow files.
8+
- Quality checks are only local/manual.
9+
10+
## Scope
11+
- `.github/workflows/ci.yml`
12+
- Bun + Turbo setup in CI.
13+
14+
## Proposed Changes
15+
1. Add `ci.yml` with jobs:
16+
- Setup Bun and Node environment
17+
- Install deps
18+
- `bun run lint`
19+
- `bun run typecheck`
20+
- `bun run test`
21+
2. Add separate optional job for `bun run smoke-test` (desktop/Electron).
22+
3. Configure caching for Bun/Turbo as appropriate.
23+
24+
## Risks
25+
- Smoke test may be flaky in headless CI environments.
26+
- CI runtime can grow if caching is misconfigured.
27+
28+
## Validation
29+
- Verify workflow runs on a branch PR.
30+
- Ensure failures surface clearly by job name.
31+
32+
## Done Criteria
33+
- CI blocks regressions in lint/typecheck/test.
34+
- Workflow docs added to README.
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Plan: Add Pre-Commit Formatting/Lint Hooks
2+
3+
## Summary
4+
Introduce pre-commit automation so formatting and basic lint checks happen before commits.
5+
6+
## Motivation
7+
- Current lint failures include formatting-only issues.
8+
- Shift-left feedback reduces noisy CI failures and cleanup churn.
9+
10+
## Scope
11+
- Root tooling config and package scripts.
12+
- No runtime code changes.
13+
14+
## Proposed Changes
15+
1. Add hook tooling (e.g. Husky + lint-staged or Lefthook).
16+
2. Configure staged-file tasks:
17+
- `biome format --write`
18+
- `biome check`
19+
3. Add setup docs in README.
20+
4. Keep checks fast to avoid developer friction.
21+
22+
## Risks
23+
- Slow hooks can frustrate contributors and be bypassed.
24+
- Need to ensure compatibility with Bun workspace setup.
25+
26+
## Validation
27+
- Create sample staged changes and verify hook behavior.
28+
- Confirm formatting fixes are applied automatically.
29+
30+
## Done Criteria
31+
- Pre-commit hook installed and documented.
32+
- Formatting-only lint failures drop significantly.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Plan: Expand Event/State Transition Test Coverage
2+
3+
## Summary
4+
Add focused tests for renderer event handling and session evolution logic.
5+
6+
## Motivation
7+
- Core behavior is event-driven and stateful.
8+
- Existing renderer tests cover only a subset of timeline/model behavior.
9+
10+
## Scope
11+
- `apps/renderer/src/session-logic.test.ts`
12+
- Optional reducer tests for `apps/renderer/src/store.ts`.
13+
14+
## Proposed Changes
15+
1. Add tests for `evolveSession`:
16+
- `thread/started`
17+
- `turn/started`
18+
- `turn/completed` success/failure
19+
- error/session closed events
20+
2. Add tests for `applyEventToMessages`:
21+
- start/delta/completed flow
22+
- out-of-order event cases
23+
- turn completion clearing streaming flags
24+
3. Add reducer integration tests for `APPLY_EVENT`.
25+
26+
## Risks
27+
- Tests may be brittle if event payload fixtures are too coupled to implementation details.
28+
29+
## Validation
30+
- `bun run test`
31+
- Ensure new tests remain deterministic and fast.
32+
33+
## Done Criteria
34+
- High-risk event transitions are covered by unit tests.
35+
- Regressions in stream assembly/session status are caught quickly.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Plan: Unify Process and PTY Session Abstractions in ProcessManager
2+
3+
## Summary
4+
Refactor `ProcessManager` to use a single runtime-session interface for child-process and PTY modes.
5+
6+
## Motivation
7+
- `apps/desktop/src/processManager.ts` maintains parallel maps and branch-heavy logic.
8+
- New execution backends/providers will multiply complexity.
9+
10+
## Scope
11+
- Desktop process execution internals.
12+
- Preserve public `ProcessManager` API.
13+
14+
## Proposed Changes
15+
1. Introduce internal interface (e.g. `RuntimeSession`):
16+
- `write(data)`
17+
- `kill()`
18+
- lifecycle/output event hooks
19+
2. Implement:
20+
- `ChildProcessSession`
21+
- `PtySession`
22+
3. Replace dual maps with one `Map<string, RuntimeSession>`.
23+
4. Keep output/exit event contract unchanged.
24+
5. Add tests for both implementations.
25+
26+
## Risks
27+
- PTY behavior differs by platform; abstraction must not hide required differences.
28+
29+
## Validation
30+
- Existing `processManager.test.ts` passes.
31+
- Add PTY-path tests where feasible.
32+
33+
## Done Criteria
34+
- Manager no longer branches per backend in `write/kill/killAll`.
35+
- Session backends are independently testable.

0 commit comments

Comments
 (0)