YeonGyu-Kim
bd867019f9
Adds a new Codex plugin component `telemetry` that emits a single omo_codex_daily_active event (reason: session_start) from every Codex SessionStart hook, with the same UTC-day deduplication, hashed installation identifier, and four-flag opt-out as the install-time event. Previously omo-codex telemetry only fired on install_completed, so DAU/WAU/MAU under-reported real Codex usage. - New plugin component packages/omo-codex/plugin/components/telemetry/ mirrors the rules/comment-checker/lsp pattern: own src/, tsc build, vitest tests, package.json (posthog-node dep), hooks/hooks.json. - src/codex-hook.ts wraps createPluginPostHog().trackActive(..., "session_start") with safeShutdown so Codex session startup never blocks on telemetry. - Plugin root hooks.json + workspaces register the new component alongside rules and ultrawork on SessionStart. - Aggregate test expectations updated to include the telemetry directory. - cross-package-equivalence.test.ts pins product-identity constants and shouldDisablePostHog behavior to stay byte-equivalent between the CLI installer (src/telemetry/) and the plugin runtime (plugin/components/telemetry/src/), so the two PostHog sources never drift on event name, distinct_id base, dedup file path, or opt-out flags. - PostHogActivityReason union in the CLI-side posthog.ts gains "session_start" so future CLI paths can emit the same reason without a type break.
38 lines
2.1 KiB
Markdown
38 lines
2.1 KiB
Markdown
# Repository Conventions
|
|
|
|
Conventions for human contributors and AI agents working on this component.
|
|
|
|
## Style
|
|
|
|
- Terse technical prose. No emojis in commits, issues, PR comments, or code.
|
|
- TypeScript strict mode. No `any`, no `@ts-ignore`, no `@ts-expect-error`, no enums.
|
|
- ESM modules with `.js` suffix in runtime import paths.
|
|
- Tabs for indentation. Double quotes for strings.
|
|
- Tests use vitest with `#given .. #when .. #then` descriptions or plain `// given / // when / // then` body comments.
|
|
|
|
## Commands
|
|
|
|
- `npm install` - install dependencies.
|
|
- `npm test` - run vitest once.
|
|
- `npm run typecheck` - strict TypeScript check.
|
|
- `npm run check` - type check, biome, and build.
|
|
- `npm run build` - emit `dist/`.
|
|
- `node dist/cli.js hook session-start < fixture.json` - smoke-test the SessionStart hook.
|
|
|
|
## Constraints
|
|
|
|
- No Bun APIs. Runtime is Node only because Codex launches plugin hooks with Node.
|
|
- The single hook handler is `runSessionStartHook`. Do not add new hook handlers without also wiring them in `hooks/hooks.json` and `plugin/hooks/hooks.json`.
|
|
- Telemetry MUST be silent on every failure path. The CLI MUST exit 0 with empty stdout even when PostHog construction, capture, or shutdown throws.
|
|
- Telemetry MUST be daily-deduplicated. Adding a new event type requires a new state file slot, not removal of the existing dedup.
|
|
- Hook output MUST stay empty (no `additionalContext`, no `systemMessage`). This component is observability-only and MUST NOT inject context into the Codex conversation.
|
|
- Constants in `src/product-identity.ts` MUST stay byte-equivalent with `packages/omo-codex/src/telemetry/product-identity.ts`. The cross-package equivalence test will fail otherwise.
|
|
- Do not couple this component back to omo internal source paths beyond what `cross-package-equivalence.test.ts` already asserts at the constants layer.
|
|
|
|
## Don'ts
|
|
|
|
- No `git add -A` or `git add .`. Stage only the files you changed.
|
|
- No `git commit --no-verify`. No force pushes. No history rewriting on shared branches.
|
|
- No new network calls. PostHog is the only allowed sink.
|
|
- No new env vars without README + privacy-policy update.
|