@qiaolei81/copilot-session-viewer 0.3.2 → 0.3.3

package/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+## Project overview
+Web UI for viewing and analyzing GitHub Copilot CLI session logs. Built with Express.js, EJS templates, and vanilla JavaScript (Vue 3 for session detail view).
+
+## 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                    # Main Express app
+src/
+  config.js                  # Configuration constants
+  session.js                 # Session data model
+  sessionRepository.js       # Session loading/caching
+  insightService.js          # Copilot-based analysis
+  processManager.js          # Background process tracking
+  fileUtils.js              # File operations
+  helpers.js                # Utility functions
+views/
+  index.ejs                 # Session list (main page)
+  session-vue.ejs           # Session detail (Vue 3)
+  time-analyze.ejs          # Timeline analysis
+__tests__/                  # Jest unit tests
+__tests__/e2e/              # Playwright e2e tests
+```
+
+## Testing instructions
+- **Unit tests**: `npm test` (Jest)
+- **E2E tests**: `npm run test:e2e` (Playwright)
+- **Coverage**: `npm run test:coverage`
+- Always run `npm run lint` before committing
+- E2E tests expect server running on port 3838
+- Tests use `~/.copilot/session-state/` by default
+
+## Common tasks
+
+### Adding a new route
+1. Add route handler in `server.js`
+2. Create corresponding view in `views/`
+3. Add E2E test in `__tests__/e2e/`
+4. Update README if user-facing
+
+### Modifying session parsing
+1. Edit `src/session.js` or `src/fileUtils.js`
+2. Run unit tests: `npm test`
+3. Test with real sessions from `~/.copilot/session-state/`
+
+### UI changes
+- Main page: edit `views/index.ejs` (vanilla JS)
+- Session detail: edit `views/session-vue.ejs` (Vue 3 CDN)
+- Time analysis: edit `views/time-analyze.ejs` (vanilla JS)
+- Restart server to see changes: `npm run dev` (auto-reload)
+
+## Important constraints
+
+### Security
+- No authentication (local-only tool)
+- Helmet.js for basic security headers
+- Rate limiting on upload endpoint
+- Input validation on file paths
+- CORS restricted to localhost origins
+
+### Dependencies
+- **copilot CLI** must be in PATH (used by insightService)
+- Node.js 22+ (uses native fetch, improved performance)
+- Session files: `~/.copilot/session-state/` (configurable via SESSION_DIR env)
+
+### Performance
+- Session list caches for 30 seconds
+- Virtual scrolling for large event lists (vue-recycle-scroller)
+- Compression enabled (gzip)
+- Static assets served via Express
+
+## Debugging tips
+- Check server logs: `tail -f /tmp/copilot-session-viewer.log` (if running via nohup)
+- Inspect session files: `cat ~/.copilot/session-state/<session-id>/events.jsonl`
+- Browser DevTools console for client-side issues
+- Use `DEBUG=*` env var for verbose logging (if implemented)
+
+## Commit guidelines
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`
+- Run `npm run lint:fix` before committing
+- All tests must pass: `npm run test:all`
+- Keep commits atomic and focused
+
+## Known gotchas
+- Vue 3 templates auto-unwrap refs - don't use `.value` in templates
+- `filteredEvents` vs `flatEvents` - use correct one for virtual scroller indices
+- Platform-specific paths: always rely on system PATH, never hardcode `/opt/homebrew` etc.
+- EJS escaping: use `<%- %>` for trusted HTML, `<%= %>` for user input
+
+## PR instructions
+- Title format: `<type>: <description>` (e.g., `feat: add brand colors for model badges`)
+- Link related issues if any
+- Include screenshots for UI changes
+- Verify all tests pass locally before pushing

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-03-13
+
+### Added
+- **Frontend Build Pipeline** - esbuild-based build system (`scripts/build.mjs`) extracts inline JS from EJS templates into standalone minified bundles
+- **Application Insights Telemetry** - Backend telemetry via `applicationinsights@2.9.8` (11 custom events, 3 metrics); frontend telemetry via CDN SDK (13 interaction events)
+- **Browser Telemetry Snippet** - `views/telemetry-snippet.ejs` partial for consistent frontend telemetry injection
+- **Tarball Verification in CI** - E2E tests now run against `npx`-installed tgz package, verifying the published artifact works end-to-end
+- **npm Publish Smoke Test** - Pre-publish step installs tgz, starts server, and verifies HTTP 200
+
+### Changed
+- **Frontend Architecture** - 4642 lines of inline JS extracted from 3 EJS templates into 4 standalone bundles (net -3370 lines)
+  - `src/frontend/homepage.js` → `public/js/homepage.min.js` (9.7K)
+  - `src/frontend/session-detail.js` → `public/js/session-detail.min.js` (45.5K)
+  - `src/frontend/time-analyze.js` → `public/js/time-analyze.min.js` (54.6K)
+  - `src/frontend/telemetry-browser.js` → `public/js/telemetry-browser.min.js` (1.5K)
+- **Server Data Bridge** - EJS templates pass server data to external bundles via `window.__PAGE_DATA`
+- **CI Pipeline** - E2E tests run against packed tgz via `npx` (not source); telemetry disabled in all CI steps
+- **npm Package** - Source files (`src/frontend/`) excluded via `.npmignore`; only `.min.js` bundles shipped
+
+### Fixed
+- **Missing Runtime Dependency** - `adm-zip` moved from devDependencies to dependencies (was causing `MODULE_NOT_FOUND` when installed from npm)
+- **ESLint Config** - Added frontend globals (Vue, marked, DOMPurify), excluded `public/js/*.min.js` from linting, fixed unused vars and eqeqeq warnings
+
 ## [0.3.2] - 2026-03-08
 
 ### Fixed

package/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to Copilot Session Viewer
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and collaborative environment.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues. When creating a bug report, include:
+
+- **Clear title and description**
+- **Steps to reproduce** the behavior
+- **Expected vs actual behavior**
+- **Environment details** (Node.js version, OS, browser)
+- **Session file examples** (if applicable, sanitize sensitive data)
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:
+
+- **Use case** - What problem does this solve?
+- **Proposed solution** - How should it work?
+- **Alternatives considered** - What other approaches did you think about?
+
+### Pull Requests
+
+1. **Fork** the repository
+2. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes** following the code style guidelines
+4. **Write or update tests** - maintain or improve test coverage
+5. **Run all tests**:
+   ```bash
+   npm run lint:fix
+   npm run test:all
+   ```
+6. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add new feature
+   fix: resolve bug in session parsing
+   docs: update README
+   test: add e2e test for filtering
+   ```
+7. **Push** to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+8. **Submit a pull request** to the `main` branch
+
+**Note for fork contributors:**
+- CI tests will run automatically on your PR
+- You don't need access to secrets (NPM_TOKEN) - only maintainers publish releases
+- Your PR will be labeled `external-contribution` automatically
+
+
+### Code Style Guidelines
+
+- **JavaScript**: Single quotes, no unused variables
+- **Error handling**: Always include `{ cause }` when re-throwing
+- **Vue 3**: Don't use `.value` in templates (auto-unwrapped)
+- **Comments**: Explain *why*, not *what*
+- **ESLint**: Zero errors, warnings acceptable
+
+### Testing Requirements
+
+- **Unit tests** for all new logic in `src/`
+- **E2E tests** for user-facing features
+- **All tests must pass** before merging
+
+### Development Workflow
+
+```bash
+# Install dependencies
+npm install
+
+# Run dev server (auto-reload)
+npm run dev
+
+# Run tests
+npm run test:all
+
+# Lint and fix
+npm run lint:fix
+```
+
+### Project Structure
+
+See `AGENTS.md` for detailed architecture and common tasks.
+
+### Need Help?
+
+- Check `AGENTS.md` for development guidelines
+- Review existing issues and pull requests
+- Ask questions in issue discussions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/RELEASE.md

@@ -0,0 +1,146 @@
+# Release Process
+
+## Automatic Version Bumping
+
+### Using npm scripts (recommended)
+
+```bash
+# Patch release (0.1.0 → 0.1.1) - bug fixes
+npm run release:patch
+
+# Minor release (0.1.0 → 0.2.0) - new features
+npm run release:minor
+
+# Major release (0.1.0 → 1.0.0) - breaking changes
+npm run release:major
+```
+
+**What happens:**
+1. ✅ Updates `package.json` version
+2. ✅ Creates git commit (`chore: release vX.Y.Z`)
+3. ✅ Creates git tag (`vX.Y.Z`)
+4. ✅ Pushes to GitHub
+5. ✅ Creates GitHub release with auto-generated notes
+6. ✅ Triggers npm publish workflow
+
+---
+
+### Manual npm version command
+
+```bash
+# Bump version
+npm version patch -m "chore: release v%s"
+
+# Push tag and code
+git push --follow-tags
+
+# Create GitHub release
+gh release create v0.1.1 --title "v0.1.1" --generate-notes
+```
+
+---
+
+## Semantic Versioning
+
+Follow [SemVer](https://semver.org/):
+
+- **Patch** (0.1.x) - Bug fixes, documentation, minor improvements
+- **Minor** (0.x.0) - New features, backward-compatible changes
+- **Major** (x.0.0) - Breaking changes, API changes
+
+---
+
+## Pre-Release Checklist
+
+Before running `npm run release:*`, ensure:
+
+- [ ] All tests pass (`npm run test:all`)
+- [ ] Lint passes (`npm run lint:check`)
+- [ ] `CHANGELOG.md` is updated
+- [ ] Working directory is clean (`git status`)
+- [ ] You're on `main` branch
+- [ ] Branch is up to date with remote
+
+---
+
+## Release Workflow
+
+```mermaid
+graph LR
+    A[npm run release:patch] --> B[Update package.json]
+    B --> C[Git commit + tag]
+    C --> D[Push to GitHub]
+    D --> E[Create GitHub Release]
+    E --> F[Trigger npm-publish.yml]
+    F --> G[Publish to npm]
+    F --> H[Upload .tgz to release]
+```
+
+---
+
+## Troubleshooting
+
+### "Working directory is not clean"
+```bash
+# Check what's uncommitted
+git status
+
+# Commit or stash changes
+git add .
+git commit -m "chore: prepare for release"
+```
+
+### "Tag already exists"
+```bash
+# Delete local tag
+git tag -d v0.1.0
+
+# Delete remote tag
+git push origin :refs/tags/v0.1.0
+```
+
+### "gh command not found"
+```bash
+# Install GitHub CLI
+brew install gh
+
+# Authenticate
+gh auth login
+```
+
+---
+
+## Examples
+
+### Patch release (bug fix)
+
+```bash
+# Fix bug
+git commit -m "fix: resolve session parsing error"
+
+# Release
+npm run release:patch
+# → v0.1.0 → v0.1.1
+```
+
+### Minor release (new feature)
+
+```bash
+# Add feature
+git commit -m "feat: add dark mode toggle"
+
+# Release
+npm run release:minor
+# → v0.1.0 → v0.2.0
+```
+
+### Major release (breaking change)
+
+```bash
+# Breaking change
+git commit -m "feat!: redesign API endpoints"
+
+# Release
+npm run release:major
+# → v0.1.0 → v1.0.0
+```