@pinta-ai/pinta-codex 1.2.0 → 1.2.1

package/README.md

@@ -2,18 +2,18 @@
 
 Generic OTLP forwarder for Codex hook events.
 
-> **엔드유저 설치 가이드:** [`docs/installation-guide.md`](./docs/installation-guide.md)
-> **pinta-cc와의 차이:** [`docs/codex-vs-claude-code.md`](./docs/codex-vs-claude-code.md)
-> 이 README는 개발자 관점 개요입니다.
+> **End-user install guide:** [`docs/installation-guide.md`](./docs/installation-guide.md)
+> **Differences from pinta-cc:** [`docs/codex-vs-claude-code.md`](./docs/codex-vs-claude-code.md)
+> This README is a developer-oriented overview.
 
 ## Channels
 
-두 채널이 병행 운영됩니다. `~/.codex/hooks.json` 의 absolute-path prefix 로 구분되어 같은 머신에서 공존 가능합니다.
+Two channels are operated in parallel. They coexist on the same machine because each entry in `~/.codex/hooks.json` is discriminated by its absolute-path prefix.
 
-| Channel | 사용자 | 설치 |
-|---------|-------|------|
-| **Pinta Manager** (v0.2+) | Pinta 사용자 | catalog 가 npm tarball install → manager root prefix 로 hooks.json entry 자동 등록. **manual setup 불필요.** |
-| **Git clone + npm run setup** | OSS / standalone | 아래 Quick start 참조. `~/.codex/pinta-codex.env` 에 직접 endpoint/token 작성. |
+| Channel | Audience | Install |
+|---------|----------|---------|
+| **Pinta Manager** (v0.2+) | Pinta users | The catalog installs the npm tarball and registers a `hooks.json` entry under the manager root prefix automatically. **No manual setup required.** |
+| **Git clone + npm run setup** | OSS / standalone | See Quick start below. Endpoint/token are written directly to `~/.codex/pinta-codex.env`. |
 
 ## Quick start (OSS / standalone)
 
@@ -26,11 +26,11 @@ codex              # hooks fire immediately
 npm run doctor     # verify everything green
 ```
 
-`setup`은 idempotent — 재실행해도 안전합니다. `doctor`는 read-only.
+`setup` is idempotent — re-running it is safe. `doctor` is read-only.
 
 ## What it captures
 
-Codex의 hook 시스템 (실험적; `~/.codex/config.toml`의 `features.codex_hooks = true` 활성화 필요) 이 현재 발화하는 5개 이벤트가 모두 핸들링됩니다.
+All five events that Codex's hook system (experimental; requires `features.codex_hooks = true` in `~/.codex/config.toml`) currently emits are handled.
 
 | Event | Notes |
 |-------|-------|
@@ -40,19 +40,19 @@ Codex의 hook 시스템 (실험적; `~/.codex/config.toml`의 `features.codex_ho
 | `PostToolUse` | **Bash tool only** (current Codex limitation) |
 | `Stop` | final flush |
 
-각 invocation은 `node dist/index.js`를 spawn하고, 이벤트를 OTLP span 하나로 매핑한 뒤 `{endpoint}/traces`로 POST합니다.
+Each invocation spawns `node dist/index.js`, maps the event to a single OTLP span, and POSTs it to `{endpoint}/traces`.
 
 ## Behavior
 
-- OTLP/HTTP JSON transport. 헤더는 `OTEL_EXPORTER_OTLP_HEADERS` 에서 읽음 (`key=val,key=val` 형식)
-- Top-level 이벤트 필드는 `codex.*` span attribute 로 평탄화 (Bronze; 형제 adaptor는 `cc.*`, `mcp.*`)
-- **No fail-close** — 모든 hook은 성공 시 exit 0 (전송 실패는 retry queue 로 흡수)
-- Disk-backed retry queue at `.plugin-data/failed-spans.jsonl` (cap 1000). 다음 hook 호출 시 일괄 drain
-- One trace per user turn — `UserPromptSubmit` ULID 기반
+- OTLP/HTTP JSON transport. Headers are read from `OTEL_EXPORTER_OTLP_HEADERS` (`key=val,key=val` format)
+- Top-level event fields are flattened into `codex.*` span attributes (Bronze; sibling adaptors use `cc.*`, `mcp.*`)
+- **No fail-close** — every hook exits 0 on success (transmission failures are absorbed by the retry queue)
+- Disk-backed retry queue at `.plugin-data/failed-spans.jsonl` (cap 1000). Drained on the next hook invocation
+- One trace per user turn — based on the `UserPromptSubmit` ULID
 
 ## Configuration
 
-`npm run setup` 이 `~/.codex/pinta-codex.env` 에 endpoint + 헤더를 씁니다. 환경변수로 파일 값을 덮어쓸 수 있습니다.
+`npm run setup` writes the endpoint and headers to `~/.codex/pinta-codex.env`. Environment variables override file values.
 
 ```bash
 # OTel-spec (primary)
@@ -63,7 +63,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="x-pinta-relay-token=YOUR-TOKEN"
 export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR-TOKEN"
 ```
 
-`~/.codex/pinta-codex.env` 예시:
+Example `~/.codex/pinta-codex.env`:
 
 ```env
 OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector.example.com
@@ -86,11 +86,11 @@ export CODEX_HOME="/abs/path/to/.codex"                  # override ~/.codex dur
 
 ## Identity — not needed
 
-v1.2부터 Pinta CLI 의존이 제거되었습니다. Identity 부착은 relay 계층 책임입니다. Pinta Manager 가 forward 시 첨부하며, OSS 사용자는 자기 pipeline 에서 처리합니다. 플러그인 자체는 identity 없이 동작하며, 어떤 hook 도 identity 부재로 차단되지 않습니다.
+Since v1.2 the Pinta CLI dependency has been removed. Identity attachment is the responsibility of the relay layer. Pinta Manager attaches it on forward, and OSS users handle it in their own pipeline. The plugin itself runs without identity, and no hook is blocked by its absence.
 
 ## Manual install (advanced)
 
-interactive setup 을 쓰지 않으려면:
+If you don't want to use the interactive setup:
 
 ```bash
 npm run build
@@ -98,16 +98,16 @@ npm run install-hooks                  # merges absolute paths into ~/.codex/hoo
 npm run install-hooks -- --dry-run     # preview without writing
 ```
 
-`install-hooks` 는 idempotent: `~/.codex/hooks.json` 이 번들 템플릿과 이미 일치하면 `already up to date` 로 no-op. 이전 경로의 stale pinta-codex 엔트리는 자동 감지·제거 (`removed N stale pinta-codex entries`).
+`install-hooks` is idempotent: if `~/.codex/hooks.json` already matches the bundled template, it's a no-op (`already up to date`). Stale pinta-codex entries from previous paths are detected and removed automatically (`removed N stale pinta-codex entries`).
 
-`~/.codex/config.toml` 에 수동으로 추가:
+Add the following manually to `~/.codex/config.toml`:
 
 ```toml
 [features]
 codex_hooks = true
 ```
 
-> **Why an install script?** Codex는 아직 `.codex-plugin/plugin.json` 에서 hook 을 자동 로드하지 않습니다. `install-hooks` 가 번들 `hooks.json` 템플릿의 `${CODEX_PLUGIN_ROOT}` 를 절대경로로 교체하고 user-level 파일에 merge 합니다. Codex 가 plugin-hook auto-discovery 를 추가하면 이 단계는 사라집니다.
+> **Why an install script?** Codex does not yet auto-load hooks from `.codex-plugin/plugin.json`. `install-hooks` substitutes `${CODEX_PLUGIN_ROOT}` in the bundled `hooks.json` template with an absolute path and merges it into the user-level file. Once Codex adds plugin-hook auto-discovery, this step will go away.
 
 ## Uninstall
 
@@ -115,13 +115,13 @@ codex_hooks = true
 npm run uninstall-hooks
 ```
 
-`dist/index.js` 를 참조하는 이 플러그인의 `~/.codex/hooks.json` 엔트리만 제거합니다. 다른 hook 은 건드리지 않습니다.
+This removes only this plugin's entries from `~/.codex/hooks.json` (those referencing `dist/index.js`). Other hooks are left untouched.
 
-완전 제거:
+For a complete removal:
 
 ```bash
 rm ~/.codex/pinta-codex.env
-# ~/.codex/config.toml 에서 [features] codex_hooks = true 라인 수동 삭제
+# Manually remove the [features] codex_hooks = true line from ~/.codex/config.toml
 ```
 
 ## Local development
@@ -132,13 +132,13 @@ Mock server (OTLP viewer at `http://localhost:3000`):
 npm run mock-server
 ```
 
-다른 터미널에서 endpoint 를 mock 으로 설정하고 Codex 시작:
+In another terminal, point the endpoint at the mock and start Codex:
 
 ```bash
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000 codex
 ```
 
-또는 stdin pipe 로 setup:
+Or set up via stdin pipe:
 
 ```bash
 printf 'http://localhost:3000\n\n' | npm run setup
@@ -161,21 +161,21 @@ printf 'http://localhost:3000\n\n' | npm run setup
 
 ## BREAKING CHANGES from 1.0.x / 1.1.x
 
-상세한 마이그레이션 안내는 [`CHANGELOG.md`](./CHANGELOG.md) 를 참조하세요.
+See [`CHANGELOG.md`](./CHANGELOG.md) for the full migration guide.
 
-요약:
-- Pinta CLI 의존 제거. `pinta login` 불필요
-- `PINTA_CODEX_ENDPOINT` / `PINTA_CODEX_API_KEY` → `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` (legacy 키는 backward-compat 으로 인식되며 다음 `npm run setup` 시 자동 마이그레이션)
-- PreToolUse fail-close 제거. 모든 hook 은 exit 0 on success
-- `member.identity.*` resource attribute 제거
+Summary:
+- Pinta CLI dependency removed. `pinta login` no longer required
+- `PINTA_CODEX_ENDPOINT` / `PINTA_CODEX_API_KEY` → `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` (legacy keys are still recognized for backward compatibility and auto-migrated on the next `npm run setup`)
+- PreToolUse fail-close removed. Every hook exits 0 on success
+- `member.identity.*` resource attributes removed
 
-### 마이그레이션 액션
+### Migration actions
 
-| 채널 | 액션 |
-|------|------|
-| **Pinta Manager v0.2+** | 자동. 다음 reconcile 에 기존 hook entry 가 manager-installed 1.2.0 entry 로 교체되고 `~/.codex/pinta-codex.env` 의 PINTA_* 키는 OTEL_* 로 갱신. |
-| **Git clone (기존 사용자)** | `git pull && npm run setup` 1회 재실행. setup 이 legacy `PINTA_CODEX_*` 키를 OTel 키로 자동 마이그레이션 (.bak 백업). |
-| **재setup 안 함** | hook 자체는 1.0.x/1.1.x 코드 그대로라면 동작 유지. 단 dist/ 가 1.2.0 으로 빌드된 상태에서 PINTA_CODEX_* 만 남아있으면 backward-compat path 로 동작 (재setup 권장). |
+| Channel | Action |
+|---------|--------|
+| **Pinta Manager v0.2+** | Automatic. On the next reconcile, the existing hook entry is replaced with the manager-installed 1.2.0 entry, and `PINTA_*` keys in `~/.codex/pinta-codex.env` are renamed to `OTEL_*`. |
+| **Git clone (existing users)** | Run `git pull && npm run setup` once. Setup auto-migrates legacy `PINTA_CODEX_*` keys to OTel keys (with a `.bak` backup). |
+| **No re-setup** | If the hooks themselves are still 1.0.x/1.1.x code, they keep working. If `dist/` has been built at 1.2.0 but only `PINTA_CODEX_*` keys remain, the backward-compat path kicks in (re-setup recommended). |
 
 ## Repo layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinta-ai/pinta-codex",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Generic OTLP forwarder for Codex hook events",
   "main": "dist/index.js",
   "license": "SEE LICENSE IN ./LICENSE",