copilot-session-viewer: Instructions file for Codex

AGENTS.md

Project overview

Web UI for viewing and analyzing AI coding-agent session logs (GitHub Copilot CLI, Claude Code, Pi-Mono, VSCode, Modernize). Built with Express.js backend and a Vue 3 SPA frontend (Vite + Pinia + Vue Router).

Setup commands

• Install deps: npm install
• Start server: npm start
• Dev mode (auto-reload): npm run dev
• Run all tests: npm run test:all
• Lint code: npm run lint
• Fix lint issues: npm run lint:fix

Code style

• JavaScript (Node.js 22+)
• Single quotes for strings
• No unused variables (prefix with _ if intentionally unused in catch blocks)
• Error handling: always include { cause } when re-throwing errors
• ESLint enforced (no errors, warnings acceptable)

File structure

server.js                          # Entry: telemetry init + app.listen
src/
  server/
    app.js                         # Express app factory (middleware, routes)
    config.js                      # Configuration constants
    telemetry.js                   # App Insights init (must load first)
    controllers/                   # Route handlers (session, dir, tag, insight, upload, ...)
    middleware/                    # Express middleware (rate limit, validation, ...)
    services/                      # sessionService, sessionRepository, insightService,
                                   #   eventNormalizer, dirRegistryService, tagService, ...
    adapters/                      # Per-source session adapters (Copilot, Claude, Pi-Mono,
                                   #   VSCode, Modernize) — extend BaseSourceAdapter
    models/                        # Session domain model
    schemas/                       # Zod schemas (unified event schema)
    utils/                         # fileUtils, helpers, processManager, sourceMapping
  client/                          # Vue 3 SPA (built by Vite, served from dist/client)
    main.js, App.vue
    router/                        # Vue Router (hash mode)
    stores/                        # Pinia stores
    api/                           # fetch wrappers
    views/                         # Route-level views (HomeView, SessionView, TimeAnalyzeView)
    components/                    # Reusable components (home/, session/, time-analyze/)
    utils/, styles/
lib/parsers/                       # Legacy parser stack used by ClaudeAdapter via ParserFactory
__tests__/                         # Jest unit tests
__tests__/e2e/                     # Playwright e2e tests
__tests__/fixtures/sessions/       # Synthetic CLI-generated session fixtures (E2E_USE_FIXTURES=1)
public/                            # Static assets served by Express
dist/                              # Vite build output (client/) + bundled server.min.js
index.html                         # Vite entry HTML
vite.config.js                     # Vite config (Vue plugin, build targets)