@traice/codex-collector 0.1.0 → 0.1.3

package/README.md

@@ -12,26 +12,50 @@ collector data goes to `/api/v1/internal-usage`, not `/api/v1/events`.
 - Codex OTel `response.completed` token events from `127.0.0.1:4318/v1/logs`
 - local install identity: employee email/name, team name, device principal
 - Codex context metadata: repo/cwd, model, thread id, sandbox/approval mode
-- optional monthly seat/subscription commitment, e.g. `--seat-monthly-usd 200`
+- optional monthly seat/subscription commitment, e.g. `--seat-monthly-usd 100`
 
 Prompts are not sent. Codex OTel is configured with `log_user_prompt = false`.
 
+For an overview of OTel, the collector data path, and how Codex differs from the planned Claude Code collector, see
+[Coding-agent collectors](../../docs/collectors.md).
+
 ## Install On This Device
 
 Published install shape:
 
 ```sh
-read -rsp "trAIce API key: " TRAICE_API_KEY; echo
+printf "trAIce API key: "
+stty -echo
+IFS= read -r TRAICE_API_KEY
+stty echo
+printf "\n"
 export TRAICE_API_KEY
 npx @traice/codex-collector@latest install \
-  --server-url https://app.runtraice.com \
+  --server-url https://www.runtraice.com \
   --employee-email you@company.com \
   --employee-name "Your Name" \
   --team-name Engineering \
-  --seat-monthly-usd 200
+  --seat-monthly-usd 100 \
+  --backfill-hours all \
+  --patch-codex-config
 unset TRAICE_API_KEY
 ```
 
+PowerShell on Windows:
+
+```powershell
+$secureKey = Read-Host "trAIce API key" -AsSecureString
+$plainKey = [Net.NetworkCredential]::new("", $secureKey).Password
+$plainKey | npx @traice/codex-collector@latest install --api-key-stdin `
+  --server-url 'https://www.runtraice.com' `
+  --employee-email 'you@company.com' `
+  --team-name 'Engineering' `
+  --seat-monthly-usd 100 `
+  --backfill-hours all `
+  --patch-codex-config
+Remove-Variable plainKey, secureKey
+```
+
 Local repo development can still run:
 
 ```sh
@@ -39,7 +63,7 @@ node tools/internal-spend-codex/install.mjs \
   --employee-email you@company.com \
   --employee-name "Your Name" \
   --team-name Engineering \
-  --seat-monthly-usd 200
+  --seat-monthly-usd 100
 ```
 
 The installer:
@@ -47,7 +71,9 @@ The installer:
 - creates or reuses the `internal-spend-poc` workspace in local dev
 - enables the workspace `internalSpendEnabled` flag
 - creates a real API key for `/api/v1/internal-usage`
-- writes private collector config to `~/.traice/internal-spend-codex/install.json`
+- stores the API key in macOS Keychain, Windows Credential Manager, or Linux
+  Secret Service and writes only its reference to
+  `~/.traice/internal-spend-codex/install.json`
 - appends an idempotent trAIce `[otel]` block to user-level
   `~/.codex/config.toml`
 
@@ -67,13 +93,18 @@ Local repo development can use `node tools/internal-spend-codex/collector.mjs`.
 macOS LaunchAgent:
 
 ```sh
-read -rsp "trAIce API key: " TRAICE_API_KEY; echo
+printf "trAIce API key: "
+stty -echo
+IFS= read -r TRAICE_API_KEY
+stty echo
+printf "\n"
 export TRAICE_API_KEY
 npx @traice/codex-collector@latest install \
-  --server-url https://app.runtraice.com \
+  --server-url https://www.runtraice.com \
   --employee-email you@company.com \
   --team-name Engineering \
-  --seat-monthly-usd 200 \
+  --seat-monthly-usd 100 \
+  --backfill-hours all \
   --launch-agent
 unset TRAICE_API_KEY
 ```
@@ -113,7 +144,21 @@ contract and fill employee/team fields directly or via identity mapping.
 
 The API key can be provided with `TRAICE_API_KEY`, `--api-key-stdin`, or
 `--api-key`. Prefer `TRAICE_API_KEY` or `--api-key-stdin` for user installs so
-keys do not end up in shell history.
+keys do not end up in shell history. A later `install` reuses the saved key, and
+`collect` resolves it from secure storage, so neither command prompts again.
+
+Credential storage defaults to `--credential-store auto`. It uses the native OS
+credential manager when available. On headless systems it falls back explicitly
+to `~/.traice/internal-spend-codex/credentials.json` with a user-only directory
+and file (`0700`/`0600` on POSIX); that fallback is not encrypted at rest. Use
+`--credential-store keyring` to require native secure storage and fail rather
+than fall back, or `--credential-store file` for an externally encrypted or
+managed environment. Existing plaintext `install.json` credentials migrate on
+the next `install` or `collect`.
+
+For containers, CI, MDM, or an external secret manager, inject
+`TRAICE_API_KEY` only into the `collect` process. That override is used without
+being persisted.
 
 Private config and collector state default to `~/.traice/internal-spend-codex`.
 Use `--out /path/to/private-dir` only when an org installer manages that
@@ -134,12 +179,17 @@ New or restarted Codex agents use native OTel export through the installed
 `[otel]` config. Already-open agents are covered by session JSONL token-count
 tailing where those files are available.
 
+By default the first session scan imports all available Codex history. To limit
+history, pass `--backfill-hours N` to `install` or `collect`; use
+`--backfill-hours all` explicitly for a full import. Collector state is scoped
+to the configured trAIce destination and source event IDs dedupe later restarts.
+
 ## One-Shot Backfill
 
 Run a single session-file scan without opening the OTel listener:
 
 ```sh
-npx @traice/codex-collector@latest collect --once
+npx @traice/codex-collector@latest collect --once --backfill-hours 6
 ```
 
 The collector keeps local dedupe state in:
@@ -149,3 +199,16 @@ The collector keeps local dedupe state in:
 ```
 
 so restarting it should not intentionally duplicate historical rows.
+
+## Releasing
+
+Do not run `npm publish` locally. From the platform repository, run:
+
+```bash
+npm run release:prepare
+```
+
+This opens a version PR. Merging the reviewed PR triggers GitHub Actions and npm
+trusted publishing (OIDC), so publishing never requires an npm token or an
+interactive `npm login`. Pass `minor`, `major`, or an explicit version after `--`
+when the default patch bump is not appropriate.

package/cli.mjs

@@ -1,23 +1,20 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const dir = dirname(fileURLToPath(import.meta.url));
-const [command = 'collect', ...args] = process.argv.slice(2);
-const script = command === 'install'
-  ? 'install.mjs'
-  : command === 'collect' || command === 'collector'
-    ? 'collector.mjs'
-    : null;
+const [command = "collect", ...args] = process.argv.slice(2);
+const script =
+  command === "install" ? "install.mjs" : command === "collect" || command === "collector" ? "collector.mjs" : null;
 
 if (!script) {
-  console.error('Usage: traice-codex-collector <install|collect> [options]');
+  console.error("Usage: traice-codex-collector <install|collect> [options]");
   process.exit(2);
 }
 
 const result = spawnSync(process.execPath, [resolve(dir, script), ...args], {
-  stdio: 'inherit',
+  stdio: "inherit",
 });
 
 if (result.signal) {