codex-usage-analyzer 0.1.0

package/README.md

@@ -0,0 +1,255 @@
+# codex-usage-analyzer
+
+`codex-usage-analyzer` is the local usage analysis package that emits `UsageSnapshot v2` JSON.
+
+The package is designed to be reused by product-specific CLIs and web services. It analyzes local usage sources and returns a validated snapshot; account identity, submit tokens, public profile URLs, and rendered cards belong to the product that wraps it.
+
+## CLI
+
+The published CLI entry point is:
+
+```bash
+npx codex-usage-analyzer@latest analyze --json
+```
+
+The `--json` mode writes a single `UsageSnapshot v2` object to stdout. Errors and usage text are written to stderr.
+
+The production `analyze --json` path reads local Codex session JSONL files from the Codex home directory. It uses `--codex-home <path>` when provided, otherwise `CODEX_HOME`, otherwise the default Codex home. When the session source is missing or unreadable, the command still emits a valid snapshot: required numeric totals are zero, unavailable usage details are `null` or empty arrays, and `extensions["codexUsageAnalyzer.diagnostics"]` explains the unavailable source. The production path does not return the sample fixture.
+
+The parser currently derives token totals, daily token buckets, model ranking, skill/plugin ranking, longest task duration, streaks, reasoning effort, and total thread count from allowlisted session event fields. Skill/plugin rankings are counted only from actual invocation events that can be classified by session tool catalog metadata; catalog or enabled-tool lists alone do not increment usage. Custom/local skill and plugin names may appear in `topSkills` and `topPlugins`, but the analyzer does not emit raw local file paths, raw JSONL lines, session ids, prompts, responses, tool input, or tool output.
+
+Streak fields are local-only analyzer results. The current parser treats a UTC date as active when local session JSONL contains positive `last_token_usage` for that date.
+
+Codex Desktop's profile screen is backed by its remote profile data and may include account-level usage that is no longer present in local session files, usage from another device, or data retained after local cleanup. For that reason, `activity.currentStreakDays` and `activity.longestStreakDays` are not guaranteed to match the Codex Desktop profile. The diagnostic extension includes `profileComparison.parity: "not_guaranteed"` when the analyzer has not compared against a remote profile baseline.
+
+The analyzer does not call Codex Desktop remote profile APIs or plugin-store APIs. `skills` and `plugins` are local session-derived fields, so they are unavailable when actual invocation source events are absent.
+
+`codexAssets.pet` is a safe logical reference, not an image export. The analyzer can report the Codex Desktop built-in pet catalog and the selected pet id when that setting is available. If no selected pet setting is persisted, it follows Codex Desktop's default and reports the built-in `codex` pet as `codex-built-in:pet:codex`. When a selected custom pet is found under `pets/<id>/pet.json` with an allowlisted spritesheet extension, the analyzer reports `codex-local:pet:custom-selected`.
+
+The default analyzer output does not include local file paths, custom pet directory names, image bytes, data URLs, or generated image artifacts. Files under `generated_images/` are treated as private generated artifacts and are not promoted to `codexAssets`. A wrapper that wants to render custom pet images in a web application must provide its own opt-in asset export, upload, or local serving layer.
+
+Local repository smoke command:
+
+```bash
+node bin/codex-usage-analyzer.js analyze --json
+```
+
+Parser fixture smoke command:
+
+```bash
+node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/parser
+```
+
+Asset fixture smoke command:
+
+```bash
+node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/assets
+```
+
+Development fixture command:
+
+```bash
+node bin/codex-usage-analyzer.js analyze --json --fixture-sample
+```
+
+The `--fixture-sample` mode is for tests, examples, and contract inspection only. It returns the packaged sample snapshot and must not be treated as real local Codex usage.
+
+## Profile Parity Smoke (Repository Only)
+
+Use the profile smoke helper from a repository checkout when you want to compare
+a local analyzer result with values manually copied from Codex Desktop's profile
+UI. The comparison uses a redacted baseline file; do not commit a baseline copied
+from a real account.
+
+The helper is not published as an npm package binary. It is a maintainer QA
+tool for release and parser parity checks.
+
+Create a production snapshot:
+
+```bash
+node bin/codex-usage-analyzer.js analyze --json > <local-snapshot.json>
+```
+
+Create a redacted baseline using
+`src/__tests__/fixtures/profile-baseline/redacted-baseline.json` as the shape
+reference, then compare:
+
+```bash
+node scripts/profile-smoke.js --baseline <redacted-baseline.json> --snapshot <local-snapshot.json>
+```
+
+The smoke output is a field-level summary. Result statuses mean:
+
+- `match`: expected and actual values are equal.
+- `within_tolerance`: numeric values differ only within the baseline tolerance.
+- `mismatch`: the field is comparable and differs outside tolerance.
+- `not_comparable`: the baseline intentionally marks the field as visible in
+  profile UI but not comparable to local analyzer data.
+- `skipped`: the baseline did not include that expected field.
+
+Mismatch reasons distinguish parser-bug candidates from expected source
+differences:
+
+- `numeric_mismatch`, `value_mismatch`, `actual_field_absent`, and ranking
+  shape reasons mean a comparable field differed.
+- `source_mismatch` means the baseline author marked that field as comparing
+  different sources, such as remote profile data versus local analyzer data.
+- `profile_parity_not_guaranteed` means the local snapshot itself reports that
+  remote profile parity is not guaranteed, and the field is source-sensitive.
+- `remote_profile_source_differs` is used with `not_comparable` fields that
+  should be visible in the profile baseline but intentionally not compared.
+
+Use optional baseline `sourcePolicy` metadata to keep a field comparable while
+labeling source-driven differences:
+
+```json
+{
+  "sourcePolicy": {
+    "activity.totalThreads": "source_mismatch",
+    "skills.topSkills": "source_mismatch",
+    "plugins.topPlugins": "source_mismatch"
+  }
+}
+```
+
+`sourcePolicy` belongs only to the redacted smoke baseline. It is not part of
+`UsageSnapshot v2`, and the analyzer output schema does not change. A
+source-aware mismatch still makes the smoke command exit nonzero; the field
+reason is what separates source differences from likely parser regressions.
+
+Known mismatch reasons:
+
+- Codex Desktop profile values can come from a remote account-level source,
+  while this analyzer reads local session files and local Codex metadata.
+- Local cleanup, migration, archiving, deletion, or another device can make the
+  profile UI and local analyzer cover different source ranges.
+- Streaks use the analyzer's UTC date buckets from local token events; profile
+  UI can use remote activity data.
+- Activity insights and thread counts can differ when the profile UI aggregates
+  remote account-level data and the analyzer reads retained local sessions.
+- Top skills/plugins require actual local invocation events. Catalog, enabled
+  tool lists, or remote profile rankings alone are not counted.
+- `--fixture-sample` snapshots are rejected by the profile smoke helper, so a
+  packaged example cannot pass as a real profile parity check.
+
+Redaction rules for real local baselines:
+
+- Keep only profile-visible numbers, model ids, ranking ids, and explicit
+  tolerance values needed for comparison.
+- Do not include real account handles, emails, local private paths, credential
+  material, conversation identifiers, conversation titles, prompts, responses,
+  tool input/output bodies, image captures, or unredacted session JSONL.
+
+## SDK
+
+```js
+import {
+  analyzeUsage,
+  assertUsageSnapshotV2,
+  createSampleUsageSnapshotV2,
+  validateUsageSnapshotV2
+} from "codex-usage-analyzer";
+
+const snapshot = await analyzeUsage();
+assertUsageSnapshotV2(snapshot);
+```
+
+`analyzeUsage()` returns the production analyzer result. You can pass `codexHome` for deterministic tests or custom Codex home discovery:
+
+```js
+const snapshot = await analyzeUsage({
+  codexHome: "/path/to/codex-home"
+});
+```
+
+When a local source is unavailable, fields use zero, `null`, empty arrays, and a namespaced diagnostic extension rather than sample values.
+
+Use `createSampleUsageSnapshotV2()` only for examples, tests, and contract inspection.
+
+Public exports:
+
+- `analyzeUsage(options?)`
+- `createSampleUsageSnapshotV2(overrides?)`
+- `validateUsageSnapshotV2(value)`
+- `assertUsageSnapshotV2(value)`
+- `isUsageSnapshotV2(value)`
+- `USAGE_SNAPSHOT_V2_SCHEMA_VERSION`
+- `sampleUsageSnapshotV2`
+
+## Package Contents
+
+The npm package includes the CLI entry point, runtime analyzer source, parser
+modules, snapshot validators, type declarations, and the sample snapshot fixture
+used by the SDK. It excludes repository tests, parser fixtures, working docs,
+and repository-only smoke helper scripts.
+
+## Ownership Boundary
+
+The analyzer owns local usage fields such as token totals, token breakdown, model usage, skill usage, plugin usage, activity statistics, and safe Codex pet logical references.
+
+Web products own GitHub login, display name, avatar URL, bio, profile visibility, submit tokens, devices, public URLs, rendered cards, and any uploaded or web-served pet image assets.
+
+Product-specific wrappers can call this SDK and submit the resulting snapshot to their own service:
+
+```js
+import {
+  analyzeUsage,
+  assertUsageSnapshotV2
+} from "codex-usage-analyzer";
+
+const snapshot = assertUsageSnapshotV2(await analyzeUsage());
+await submitToProductService({ snapshot });
+```
+
+Wrapper metadata such as bearer tokens, device ids, account handles, visibility, GitHub bio, GitHub avatar URLs, custom pet upload URLs, and card-only rendering hints must stay outside the analyzer snapshot.
+
+## Tests
+
+```bash
+npm test
+node bin/codex-usage-analyzer.js analyze --json
+node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/parser
+node bin/codex-usage-analyzer.js analyze --json --codex-home src/__tests__/fixtures/assets
+node bin/codex-usage-analyzer.js analyze --json --fixture-sample
+```
+
+The test suite validates the SDK exports, production parser behavior, asset safe output behavior, fixture-only CLI behavior, and `UsageSnapshot v2` schema rules.
+
+## Release Checklist
+
+Before publishing:
+
+```bash
+npm test
+npm pack --dry-run
+node bin/codex-usage-analyzer.js analyze --json
+npx --yes github:postmelee/codex-usage-analyzer analyze --json
+```
+
+After the package is published:
+
+```bash
+npx --yes codex-usage-analyzer@latest analyze --json
+```
+
+Do not paste raw production snapshot output into release notes, PR bodies, or
+issue comments. Record only structural pass/fail results, exit codes, and
+package metadata needed for release verification.
+
+## Non-Goals
+
+This package does not:
+
+- perform GitHub OAuth
+- use private Codex Desktop profile endpoints
+- export custom pet image files by default
+- issue or store submit tokens
+- own public profile handles
+- render cards or images
+- update GitHub README files
+- upload raw credential files
+- expose local private paths
+
+## Status
+
+This repository is the standalone home for the analyzer package. The production analyzer path is separated from the packaged sample fixture, and the release checklist above is the maintainer path for npm publishing and npx verification. Broader parity work against Codex Desktop profile data remains outside the npm release flow.

package/bin/codex-usage-analyzer.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+try {
+  const exitCode = await runCli(process.argv.slice(2));
+  process.exitCode = exitCode;
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "codex-usage-analyzer",
+  "version": "0.1.0",
+  "description": "Analyze local Codex usage and emit UsageSnapshot v2 JSON.",
+  "type": "module",
+  "homepage": "https://github.com/postmelee/codex-usage-analyzer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/postmelee/codex-usage-analyzer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/postmelee/codex-usage-analyzer/issues"
+  },
+  "types": "./src/index.d.ts",
+  "bin": {
+    "codex-usage-analyzer": "bin/codex-usage-analyzer.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "src/analyze.js",
+    "src/cli.js",
+    "src/fixtures/sample-v2-snapshot.js",
+    "src/index.d.ts",
+    "src/index.js",
+    "src/parser",
+    "src/snapshot",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/analyze.js

@@ -0,0 +1,239 @@
+import { sampleUsageSnapshotV2 } from "./fixtures/sample-v2-snapshot.js";
+import { aggregateActivityFromCodexHome } from "./parser/activity-aggregate.js";
+import { aggregateCodexAssetsFromCodexHome } from "./parser/asset-aggregate.js";
+import { aggregateModelUsageFromCodexHome } from "./parser/model-aggregate.js";
+import { aggregateSkillPluginUsageFromCodexHome } from "./parser/skill-plugin-aggregate.js";
+import { aggregateTokenUsageFromCodexHome } from "./parser/token-aggregate.js";
+import {
+  USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
+  assertUsageSnapshotV2
+} from "./snapshot/v2-schema.js";
+
+export const ANALYZER_NAME = "codex-usage-analyzer";
+export const ANALYZER_VERSION = "0.1.0";
+
+export async function analyzeUsage(options = {}) {
+  const [
+    usageAggregate,
+    modelAggregate,
+    activityAggregate,
+    skillPluginAggregate,
+    assetAggregate
+  ] = await Promise.all([
+    aggregateTokenUsageFromCodexHome(options),
+    aggregateModelUsageFromCodexHome(options),
+    aggregateActivityFromCodexHome(options),
+    aggregateSkillPluginUsageFromCodexHome(options),
+    aggregateCodexAssetsFromCodexHome(options)
+  ]);
+
+  const snapshot = createUnavailableUsageSnapshotV2({
+    capturedAt: normalizeCapturedAt(options.capturedAt),
+    producer: {
+      name: ANALYZER_NAME,
+      version: ANALYZER_VERSION
+    }
+  });
+
+  if (usageAggregate.diagnostics.status === "ok") {
+    snapshot.usage = usageAggregate.usage;
+  }
+
+  if (modelAggregate.diagnostics.status === "ok") {
+    snapshot.models = modelAggregate.models;
+  }
+
+  if (activityAggregate.diagnostics.status === "ok") {
+    snapshot.activity = activityAggregate.activity;
+  }
+
+  if (skillPluginAggregate.diagnostics.status === "ok") {
+    snapshot.skills = skillPluginAggregate.skills;
+    snapshot.plugins = skillPluginAggregate.plugins;
+  }
+
+  if (assetAggregate.diagnostics.status === "ok") {
+    snapshot.codexAssets = assetAggregate.codexAssets;
+  }
+
+  snapshot.extensions["codexUsageAnalyzer.diagnostics"] = createAnalyzerDiagnostics({
+    activity: activityAggregate,
+    assets: assetAggregate,
+    models: modelAggregate,
+    skillPlugin: skillPluginAggregate,
+    usage: usageAggregate
+  });
+
+  return assertUsageSnapshotV2(snapshot);
+}
+
+function createUnavailableUsageSnapshotV2(overrides = {}) {
+  return mergeSnapshot({
+    schemaVersion: USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
+    capturedAt: new Date().toISOString(),
+    producer: {
+      name: ANALYZER_NAME,
+      version: ANALYZER_VERSION
+    },
+    usage: {
+      totalTokens: 0,
+      peakDailyTokens: null,
+      tokenBreakdown: createUnavailableTokenBreakdown(),
+      daily: []
+    },
+    models: {
+      favoriteModel: null,
+      items: []
+    },
+    activity: {
+      longestTaskDurationMs: null,
+      currentStreakDays: null,
+      longestStreakDays: null,
+      fastModePercent: null,
+      reasoningEffort: null,
+      reasoningEffortPercent: null,
+      totalThreads: null
+    },
+    skills: {
+      exploredCount: null,
+      totalUsed: null,
+      topSkills: []
+    },
+    plugins: {
+      topPlugins: []
+    },
+    extensions: {
+      "codexUsageAnalyzer.diagnostics": {
+        status: "unavailable",
+        reason: "local_sources_unavailable",
+        unavailableFields: ["usage", "models", "activity", "skills", "plugins"]
+      }
+    }
+  }, overrides);
+}
+
+function createUnavailableTokenBreakdown() {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    cacheReadTokens: null,
+    cacheWriteTokens: null,
+    reasoningTokens: null
+  };
+}
+
+function createAnalyzerDiagnostics(aggregates) {
+  const skillPluginDiagnostics = aggregates.skillPlugin.diagnostics;
+  const diagnostics = {
+    usage: aggregates.usage.diagnostics,
+    models: aggregates.models.diagnostics,
+    activity: aggregates.activity.diagnostics,
+    skills: skillPluginDiagnostics,
+    plugins: skillPluginDiagnostics,
+    codexAssets: aggregates.assets.diagnostics
+  };
+
+  const parsedFields = [];
+  const unavailableFields = [];
+
+  for (const field of ["usage", "models", "activity"]) {
+    if (diagnostics[field].status === "ok") {
+      parsedFields.push(field);
+    } else {
+      unavailableFields.push(field);
+    }
+  }
+
+  if (skillPluginDiagnostics.status === "ok") {
+    parsedFields.push("skills", "plugins");
+  } else {
+    unavailableFields.push("skills", "plugins");
+  }
+
+  if (diagnostics.codexAssets.status === "ok") {
+    parsedFields.push("codexAssets");
+  } else {
+    unavailableFields.push("codexAssets");
+  }
+
+  if (diagnostics.activity.status === "ok") {
+    for (const field of diagnostics.activity.unavailableFields ?? []) {
+      unavailableFields.push(`activity.${field}`);
+    }
+  }
+
+  const status = parsedFields.length === 0
+    ? "unavailable"
+    : unavailableFields.length > 0
+      ? "partial"
+      : "ok";
+
+  return {
+    status,
+    reason: getAnalyzerDiagnosticReason(status, diagnostics),
+    parser: "session_jsonl",
+    source: diagnostics.usage.source,
+    profileComparison: {
+      status: "not_performed",
+      reason: "remote_profile_api_not_used",
+      localStreakBasis: "session_jsonl_utc_dates",
+      remoteProfileBasis: "codex_desktop_remote_profile_api",
+      parity: "not_guaranteed"
+    },
+    parsedFields,
+    unavailableFields,
+    ...diagnostics
+  };
+}
+
+function getAnalyzerDiagnosticReason(status, diagnostics) {
+  if (status === "ok") {
+    return null;
+  }
+
+  if (status === "partial") {
+    return "local_sources_partially_available";
+  }
+
+  return diagnostics.usage.reason
+    ?? diagnostics.models.reason
+    ?? diagnostics.activity.reason
+    ?? diagnostics.skills.reason
+    ?? diagnostics.plugins.reason
+    ?? diagnostics.codexAssets.reason
+    ?? "local_sources_unavailable";
+}
+
+export function createSampleUsageSnapshotV2(overrides = {}) {
+  return mergeSnapshot(structuredClone(sampleUsageSnapshotV2), overrides);
+}
+
+function normalizeCapturedAt(value) {
+  if (value === undefined || value === null) {
+    return new Date().toISOString();
+  }
+
+  const date = value instanceof Date ? value : new Date(value);
+
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("capturedAt must be a valid date");
+  }
+
+  return date.toISOString();
+}
+
+function mergeSnapshot(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (isPlainObject(value) && isPlainObject(target[key])) {
+      target[key] = mergeSnapshot(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+
+  return target;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/cli.js

@@ -0,0 +1,75 @@
+import {
+  analyzeUsage,
+  createSampleUsageSnapshotV2
+} from "./analyze.js";
+
+const USAGE = [
+  "Usage:",
+  "  codex-usage-analyzer analyze --json [--codex-home <path>]",
+  "  codex-usage-analyzer analyze --json --fixture-sample"
+].join("\n");
+
+export async function runCli(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  const [command, ...flags] = argv;
+
+  if (command !== "analyze") {
+    stderr.write(`${USAGE}\n`);
+    return 1;
+  }
+
+  const parsedFlags = parseAnalyzeFlags(flags);
+  if (!parsedFlags.ok) {
+    stderr.write(`${USAGE}\n`);
+    return 1;
+  }
+
+  const snapshot = parsedFlags.fixtureSample
+    ? createSampleUsageSnapshotV2()
+    : await analyzeUsage({
+      codexHome: parsedFlags.codexHome
+    });
+  stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+  return 0;
+}
+
+function parseAnalyzeFlags(flags) {
+  const parsed = {
+    codexHome: null,
+    fixtureSample: false,
+    hasJson: false,
+    ok: true
+  };
+
+  for (let index = 0; index < flags.length; index += 1) {
+    const flag = flags[index];
+
+    if (flag === "--json") {
+      parsed.hasJson = true;
+    } else if (flag === "--fixture-sample") {
+      parsed.fixtureSample = true;
+    } else if (flag === "--codex-home") {
+      const value = flags[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        return { ok: false };
+      }
+
+      parsed.codexHome = value;
+      index += 1;
+    } else {
+      return { ok: false };
+    }
+  }
+
+  return {
+    ...parsed,
+    ok: parsed.hasJson
+  };
+}