mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
940898c1c5
* chore: add proposal for PostHog analytics integration Introduces the proposal artifact for adding opt-in telemetry to OpenSpec using PostHog. Covers command tracking, feature adoption metrics, and privacy-respecting consent management. * feat: add optional anonymous usage statistics Introduces privacy-first usage analytics to help understand how OpenSpec is being used. Key privacy protections: - Only tracks command names and version (no arguments, paths, or content) - Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1 - Auto-disabled in CI environments - No IP address collection (explicitly disabled) - Anonymous ID is a random UUID with no PII Uses PostHog with a reverse proxy to avoid ad blockers. First-run shows a one-line notice informing users about the collection. * docs: make telemetry section collapsible and concise
1.9 KiB
1.9 KiB
1. Setup
- 1.1 Add
posthog-nodepackage as a dependency - 1.2 Create
src/telemetry/module directory - 1.3 Add PostHog API key configuration (environment variable or embedded)
2. Global Config
- 2.1 Create or extend global config module for
~/.config/openspec/config.json - 2.2 Implement read/write functions that preserve existing config fields
- 2.3 Define telemetry config structure (
anonymousId,noticeSeen)
3. Core Telemetry Module
- 3.1 Implement
isTelemetryEnabled()checkingOPENSPEC_TELEMETRY,DO_NOT_TRACK, andCIenv vars - 3.2 Implement
getOrCreateAnonymousId()with lazy UUID generation - 3.3 Initialize PostHog client with
flushAt: 1andflushInterval: 0 - 3.4 Implement
trackCommand(commandName, version)with$ip: null - 3.5 Implement
shutdown()with try/catch for silent failure handling
4. First-Run Notice
- 4.1 Implement
maybeShowTelemetryNotice()function - 4.2 Check
noticeSeenflag before displaying notice - 4.3 Display notice text: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0"
- 4.4 Update
noticeSeenin config after first display
5. CLI Integration
- 5.1 Add Commander.js
preActionhook to show notice and track command - 5.2 Add Commander.js
postActionhook to call shutdown - 5.3 Handle subcommand path extraction (e.g.,
change:apply)
6. Testing
- 6.1 Test opt-out via
OPENSPEC_TELEMETRY=0 - 6.2 Test opt-out via
DO_NOT_TRACK=1 - 6.3 Test auto-disable in CI environment
- 6.4 Test first-run notice display and noticeSeen persistence
- 6.5 Test anonymous ID generation and persistence
- 6.6 Test silent failure on network error (mock PostHog)
7. Documentation
- 7.1 Add telemetry disclosure section to README
- 7.2 Document opt-out methods (
OPENSPEC_TELEMETRY=0,DO_NOT_TRACK=1) - 7.3 Document what data is collected and not collected