diff --git a/.ai-work/01-fix-lint-and-ci.md b/.ai-work/01-fix-lint-and-ci.md deleted file mode 100644 index 0a22573..0000000 --- a/.ai-work/01-fix-lint-and-ci.md +++ /dev/null @@ -1,9 +0,0 @@ -# 01. Fix lint and add CI scripts - -Status: completed - -Make the hygiene baseline green and easy to run locally/CI: - -- fix current `npm run lint` failures; -- keep `npm run typecheck` green; -- add a single verification script that runs typecheck and lint. diff --git a/.ai-work/02-extract-shared-dto-event-types.md b/.ai-work/02-extract-shared-dto-event-types.md deleted file mode 100644 index 7861936..0000000 --- a/.ai-work/02-extract-shared-dto-event-types.md +++ /dev/null @@ -1,5 +0,0 @@ -# 02. Extract shared DTO/event types - -Status: completed - -Move duplicated API/session DTO definitions into shared modules used by both client and server. diff --git a/.ai-work/03-split-client-api.md b/.ai-work/03-split-client-api.md deleted file mode 100644 index 18cab13..0000000 --- a/.ai-work/03-split-client-api.md +++ /dev/null @@ -1,5 +0,0 @@ -# 03. Split client API into feature clients - -Status: completed - -Decompose `src/client/src/api.ts` into composable feature clients, shared HTTP helper, parsers, URL builders, and socket helpers. diff --git a/.ai-work/04-extract-file-git-controllers.md b/.ai-work/04-extract-file-git-controllers.md deleted file mode 100644 index 5768d52..0000000 --- a/.ai-work/04-extract-file-git-controllers.md +++ /dev/null @@ -1,5 +0,0 @@ -# 04. Extract file/git controllers from PiWebApp - -Status: completed - -Move file explorer and git orchestration out of `PiWebApp` into focused controllers. diff --git a/.ai-work/05-add-vitest-unit-tests.md b/.ai-work/05-add-vitest-unit-tests.md deleted file mode 100644 index 9e12e15..0000000 --- a/.ai-work/05-add-vitest-unit-tests.md +++ /dev/null @@ -1,5 +0,0 @@ -# 05. Add Vitest and pure unit tests - -Status: completed - -Add a test runner and cover pure/domain logic such as route parsing, chat transcript updates, cache merge, path safety, and git parsing. diff --git a/.ai-work/06-type-session-event-protocol.md b/.ai-work/06-type-session-event-protocol.md deleted file mode 100644 index ba69109..0000000 --- a/.ai-work/06-type-session-event-protocol.md +++ /dev/null @@ -1,5 +0,0 @@ -# 06. Type the session event protocol - -Status: completed - -Define a shared discriminated union for session UI events and use it across server event publishing, sockets, and transcript handling. diff --git a/.ai-work/07-session-daemon-health-lifecycle.md b/.ai-work/07-session-daemon-health-lifecycle.md deleted file mode 100644 index 6cc4d00..0000000 --- a/.ai-work/07-session-daemon-health-lifecycle.md +++ /dev/null @@ -1,5 +0,0 @@ -# 07. Improve session daemon health and lifecycle - -Status: completed - -Add health visibility and explicit lifecycle cleanup for the long-lived session daemon. diff --git a/.ai-work/testing-approach.md b/.ai-work/testing-approach.md deleted file mode 100644 index 6f4174d..0000000 --- a/.ai-work/testing-approach.md +++ /dev/null @@ -1,78 +0,0 @@ -# Testing approach - -Pi Web should be tested as a set of stable contracts, not as a collection of implementation details. The goal is confidence that users can safely manage projects, workspaces, sessions, and realtime agent interactions as the app evolves. - -## Priorities - -1. **Safety boundaries** - - Workspace path normalization and traversal prevention. - - File read/tree/suggestion APIs never escape the workspace. - - Git/file operations behave correctly for missing, binary, symlinked, large, and non-directory paths. - -2. **Server contracts** - - Fastify routes return stable status codes and response shapes. - - Project/workspace/git/session services are covered with real temporary directories and repositories where practical. - - Session daemon client/proxy behavior is tested separately from the browser-facing API process. - -3. **Session lifecycle and realtime behavior** - - Starting, listing, resuming, archiving/restoring, stopping, and aborting sessions should be tested with fakes at the Pi SDK boundary. - - WebSocket/event hub tests should verify event routing, global events, disconnect cleanup, and reconnect-safe state. - - Do not require real Pi credentials in normal CI; use fake runtimes/services for deterministic tests. - -4. **Client state and UX-critical flows** - - Test pure state helpers heavily: routes, chat history merging, transcript/message grouping, input modes, formatting, and API parsing. - - Browser tests should cover UX behavior, not styling: selecting project/workspace/session, sending a prompt, streaming status, file/git panels, and command-picker flows. - - Prefer durable `data-testid` selectors for Playwright instead of CSS/style assertions. - -## Test layers - -### Unit tests - -Use Vitest for pure functions and small state transitions. These tests should be fast, deterministic, and edge-case heavy. Good targets include: - -- `src/server/workspaces/pathSafety.ts` -- `src/client/src/chatHistoryCache.ts` -- `src/client/src/chatGroups.ts` -- `src/client/src/chatMessages.ts` -- `src/client/src/chatTranscript.ts` -- `src/client/src/inputModes.ts` -- `src/client/src/route.ts` -- `src/client/src/api/parsers.ts` -- formatting and URL helpers - -### Service tests - -Use real temporary directories via `mkdtemp()` and cleanup after each test. Prefer real filesystem/git behavior over mocks for workspace, file, and git services. Keep tests isolated and avoid depending on the repository checkout. - -### API integration tests - -Construct Fastify apps in tests, register routes with fake services, and use `app.inject()`. Assert public HTTP contracts: validation, status code, and response body. - -### Daemon/protocol tests - -Test the split-process session architecture with fake session services and temporary Unix sockets. Critical behavior: daemon unavailable errors, request/response framing, WebSocket proxying, and browser/API disconnects not stopping daemon-owned sessions. - -### Browser UX tests - -Use Playwright for a small set of happy-path and recovery flows. Do not test colors/layout. Test user-visible behavior: loading empty states, adding/selecting projects, starting sessions, chat updates, file/git panels, and command dialogs. - -## Coverage guidance - -Coverage numbers are a guardrail, not the goal. Start with moderate global thresholds and raise them as meaningful tests are added. Critical modules should receive targeted tests even if global coverage is already high. - -Recommended initial gates once coverage tooling is enabled: - -- statements: 70% -- branches: 60% -- functions: 70% -- lines: 70% - -## Conventions for future agents - -- Add tests near the code under test as `*.test.ts`. -- Prefer testing public functions/contracts over private implementation details. -- When a module is hard to test, first add a small composable seam instead of using broad mocks. -- Use fakes at external boundaries: Pi SDK, daemon process, network, and browser WebSockets. -- Use real temp directories for filesystem behavior. -- Run `npm run verify` before committing. -- Make progressive commits: one commit for test infrastructure/docs, then focused commits for each tested area.