Project Task Plan

Milestone 0 – Spec Alignment & Decisions

Context: The current app is built on Next.js 14 (App Router) with Vitest for tests, Tailwind, Radix primitives, and shadcn-style components. The original spec mentions Vite; we will keep Next.js for the integrated API/filesystem access and document SSR considerations. A Vite migration remains optional.

Document decision to keep Next.js for now and why. (2025-10-20: Added to README and this plan.)
Evaluate Vite migration feasibility (benefits vs. effort); record decision in docs/architecture.md.
Document SSR/ISR considerations and static export trade-offs.

Milestone 1.A – Schema-Based Log Normalisation

Goal: Drive Claude & Codex parsing from JSON Schemas so tool calls/results land in a consistent UI with minimal provider-specific logic.

A1. Fixtures & Source Analysis

Refresh anonymised fixtures under fixtures/{claude,codex} covering current event types (tooluse/tool_result, item.* events, response_item variants). (2025-10-15: Added schema-aligned Claude/Codex logs with commandexecution, reasoning, and error cases.)
Document key field mappings and schema coverage notes in docs/data-sources.md. (2025-10-14: Recorded Codex and Claude schema variants in docs/data-sources.md.)

A2. Schema Layer

Author JSON Schemas for Claude tool events (tool_use, tool_result, text) and Codex events (item.started/updated/completed, response_item, function_call, function_call_output). (2025-10-14: Added claude/message.* mappings alongside Codex coverage.)
Build an Ajv-based validator/normaliser that consumes schema + mapping definitions to emit ChatMessage objects. (2025-10-14: normalise() now drives Codex & Claude providers behind the schema flag.)
Implement reusable transforms (ISO timestamps, exitCode/duration extraction, diff parsing, toolType inference, stdout/stderr capture). (2025-10-14: Added join-text-array, append-suffix, and nested property extraction for Codex schemas.)
Document schema versioning, contribution workflow, and testing expectations. (2025-10-15: Added docs/schema-contribution.md and cross-linked from docs/data-sources.md.)

A3. Adapter Migration & Tests

Wire Codex adapter to the schema normaliser for tool events with a controlled fallback path. (2025-10-14: Provider switches to schema mappings when NEXT_PUBLIC_SCHEMA_NORMALISER=1.)
Update (2025-10-14): Codex session topic now prefers the user prompt preceding the first assistant message (including reasoning/tool preambles) to match UX expectations. (2025-10-14: Covered by schema-mode tests.)
Wire Claude adapter to the same pipeline (tool_use/tool_result/text) while preserving raw payloads for audit. (2025-10-14: Adapter emits schema-derived messages when NEXT_PUBLIC_SCHEMA_NORMALISER=1, with legacy fallback.)
Add unit/snapshot tests that validate + normalise fixtures through the schema layer and guard regressions. (2025-10-14: Added src/schema/providers/codex/mappings.test.ts to exercise new mappings.)
Benchmark parsing performance on large logs and record baseline metrics. (Deferred: lightweight benchmarking approach TBD after settling on toolchain.)
Fix Cursor workspace matching to handle case differences across resource paths. (2025-10-31: Normalised provider paths and added regression tests covering mixed-case URIs.)
Fix Cursor session detail loading by deriving the accurate provider root from snapshot files. (2025-10-31: Detail API resolves snapshot IDs via normalizeProviderRoot, reloads sessions, and surfaces debug telemetry for ingestion.)
Repair build regression from Cursor debug helpers by aligning provider error typing and chat-store persistence migration. (2025-10-31: ProviderImportError now imports from @/types/providers and chat-store migration returns a typed object to satisfy pnpm run build.)

A4. Structured Tool Call UI

Support pagination for long conversation lists (client-side pager in ChatList). (2025-10-20: Added page controls in src/components/chats/chat-list.tsx.)
Add virtualisation for extra-large lists (e.g., @tanstack/react-virtual).
Add page-size selector (10/20/50/100) to ChatList pager. (2025-10-20.)
Implement fast navigation affordances (keyboard shortcuts, breadcrumbs, recent sessions).
Enhance ToolCallCard diff navigation (previous/next hunk indicators, keyboard bindings).

1.B – UI & Interaction

Goal: Deliver the core SPA shell, responsive layouts, and conversation ergonomics.

1.C – Ingestion & Provider Setup

Goal: Robust local import via server routes and in‑browser import with clear errors.

1.D – Quality Gates, Hooks, Testing

Goal: Enforce reproducibility and ≥80% coverage with fast local feedback.

Husky pre-commit: require agents_chat record, validate sections, block unstaged changes, run pnpm lint + pnpm test. (2025-10-02: .husky/pre-commit.)
CI mirrors lint, tests, and build on pushes/PRs. (2025-10-03: .github/workflows/ci.yml.)
Add commitlint + husky commit-msg to enforce Conventional Commits.
Add pre-push hook to re-run integration/E2E (when defined).
Introduce Storybook for core components (button, ToolCallCard, ChatList); add smoke stories.
Add Stylelint config and wire into hooks/CI.
Enforce coverage ≥80% (configure thresholds in Vitest) and backfill tests for parsing edge cases.

1.E – Packaging & Deployment

Goal: Multi-stage Docker targeting <200MB; clear runbooks for macOS/Windows/Docker.

Multi-stage Docker build on node:18-alpine using Next standalone output. (2025-10-10: Dockerfile.)
.dockerignore tuned to reduce context size. (2025-10-02.)
README documents Docker and host runtime flows (envs, volumes, Windows/WSL notes). (2025-10-13.)
Release workflow: auto-draft version PR + Docker publish on release. (2025-10-22: revamped prepare-release.yml, build-on-release.yml, added docs.)
Measure image size in CI; document size and optimise if >200MB (alpine libc, prune locales, strip dev deps from standalone if needed).
Optional NGINX/alpine scratch serving of static assets, document trade-offs.

1.F – npx CLI Distribution

Goal: Ship a one-command npx talk-replay experience with automated packaging, CI, and documentation.

Prepare npm publishing config (un-set private, add bin entry, files, publishConfig, prepack build/test guard). (2025-11-01: package.json now exposes the CLI bin, packaging files, and prepack verification.)
Implement CLI runner that exposes --port/--hostname flags and starts the prebuilt Next server. (2025-11-01: Added bin/talk-replay.mjs using Next standalone output with env/flag parsing.)
Add automated tests covering CLI option parsing and failure messaging when build assets are missing. (2025-11-01: src/cli/cli.test.ts exercises flag parsing and artifact validation.)
Extend GitHub Actions to pack the npm artifact and ensure CLI smoke tests run on pushes/PRs. (2025-11-01: CI packs tarball + help smoke test; new npm-publish workflow publishes on release.)
Document npx usage, release workflow, and troubleshooting in README.md + docs/. (2025-11-01: README (EN/中文) covers npx talk-replay; release doc updated with npm steps.)
Provide release checklist in agents_chat template to capture publish context (new subsection or linked doc). (2025-11-01: Added guidance in docs/release-process.md for agents_chat release sections.)

1.G – First-run Provider Onboarding

Goal: Guide users through provider directory selection with OS-aware auto-detection.

Restore a first-run provider setup dialog backed by persisted preferences, auto-opening until completion. (2025-11-01: Added ProviderSetupDialog with skip/continue flows and store gating.)
Surface OS-aware default paths through /api/providers/defaults with client fallbacks for offline contexts. (2025-11-01: New API route leveraging resolveDefaultProviderRoot, dialog fetch with graceful fallback.)
Update UI copy and docs to mention automated detection on first launch (EN/中文). (2025-11-01: README variants and locale strings refreshed for the onboarding wizard.)

Milestone 2 – Collaborative Server Platform

Goal: Introduce a backend service that aggregates shared directories from team members, enabling collaborative browsing while preserving the frontend UX.

1. Backend Architecture & Infrastructure

Select backend stack (e.g., Node + Fastify/Express) and persistence layer (PostgreSQL/SQLite).
Define API contract for provider sync (manifests, diff updates, attachments).
Implement authentication/authorisation with RBAC for directories.
Set up background jobs for periodic sync and conflict resolution.
Provide database migration + seeding workflow.

2. Sync & Storage Pipeline

Build CLI/agent for teammates to register local directories and push metadata.
Reuse schema normalisation on the server to avoid duplicating frontend logic.
Handle binary attachments (images, files) with pluggable storage (S3-compatible + local fallback).
Introduce privacy controls (masking, redaction) for shared sessions.

3. Frontend Integration (Phase 2)

Create account management flows (login, directory management, sharing settings).
Add workspace/team selector with real-time updates (websocket/SSE).
Surface sync status indicators, conflict prompts, and activity logs.
Support mixed mode (local-only + shared sessions) via toggle or merged view.
Expand i18n strings to cover collaboration terminology.

4. DevOps, Deployment, Observability

Extend Docker setup for multi-service development (frontend, backend, database, proxy).
Add CI pipelines (lint, test, build, integration) for both frontend and backend.
Instrument logging/metrics (pino + OpenTelemetry) and hook basic alerting.
Publish deployment guides (self-hosted, cloud) including TLS, backups, scaling.
Define security checklist (input validation, rate limiting, dependency audits).

5. QA & Documentation

Expand automated tests: backend unit/integration, contract tests, end-to-end flows.
Update README.md and add docs/architecture.md describing system components and onboarding.
Provide runbooks for administrators (user management, directory onboarding, recovery drills).
Review agents_chat process to capture cross-team collaboration sessions.
Define Milestone 2 acceptance criteria and release plan.

Cross-Milestone Continuous Tasks

Maintain detailed agents_chat logs per collaboration session and keep hooks up to date.
Track dependency updates and security advisories (dependabot/renovate).
Periodically profile parsing/rendering performance on large transcripts.
Capture user feedback/feature requests and update backlog regularly.
Keep commits small and focused; reflect significant progress in tasks.md.

Notes

Frontend currently uses Next.js 14 (App Router). We will revisit Vite if SSR/API needs change; document decisions in docs/architecture.md.
Environment toggles: schema mode via NEXT_PUBLIC_SCHEMA_NORMALISER=1; provider roots via NEXT_PUBLIC_{CLAUDE,CODEX,GEMINI}_ROOT with server fallbacks (CLAUDE_ROOT, etc.).

FilesExpand file tree

tasks.md

Latest commit

History