@pinta-ai/pinta-cc 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/.claude-plugin/marketplace.json +20 -0
  2. package/.claude-plugin/plugin.json +20 -0
  3. package/CHANGELOG.md +42 -0
  4. package/LICENSE +136 -0
  5. package/README.md +200 -0
  6. package/dist/core/config.d.ts +13 -0
  7. package/dist/core/config.js +22 -0
  8. package/dist/core/config.js.map +1 -0
  9. package/dist/core/env-bridge.d.ts +16 -0
  10. package/dist/core/env-bridge.js +28 -0
  11. package/dist/core/env-bridge.js.map +1 -0
  12. package/dist/core/identity.d.ts +1 -0
  13. package/dist/core/identity.js +3 -0
  14. package/dist/core/identity.js.map +1 -0
  15. package/dist/core/otlp.d.ts +57 -0
  16. package/dist/core/otlp.js +214 -0
  17. package/dist/core/otlp.js.map +1 -0
  18. package/dist/core/redact.d.ts +57 -0
  19. package/dist/core/redact.js +149 -0
  20. package/dist/core/redact.js.map +1 -0
  21. package/dist/core/retry-queue.d.ts +26 -0
  22. package/dist/core/retry-queue.js +127 -0
  23. package/dist/core/retry-queue.js.map +1 -0
  24. package/dist/core/trace.d.ts +10 -0
  25. package/dist/core/trace.js +61 -0
  26. package/dist/core/trace.js.map +1 -0
  27. package/dist/core/transport.d.ts +18 -0
  28. package/dist/core/transport.js +97 -0
  29. package/dist/core/transport.js.map +1 -0
  30. package/dist/core/types.d.ts +65 -0
  31. package/dist/core/types.js +39 -0
  32. package/dist/core/types.js.map +1 -0
  33. package/dist/handlers/default.d.ts +6 -0
  34. package/dist/handlers/default.js +11 -0
  35. package/dist/handlers/default.js.map +1 -0
  36. package/dist/handlers/permission.d.ts +3 -0
  37. package/dist/handlers/permission.js +15 -0
  38. package/dist/handlers/permission.js.map +1 -0
  39. package/dist/handlers/post-tool-use.d.ts +3 -0
  40. package/dist/handlers/post-tool-use.js +15 -0
  41. package/dist/handlers/post-tool-use.js.map +1 -0
  42. package/dist/handlers/pre-tool-use.d.ts +3 -0
  43. package/dist/handlers/pre-tool-use.js +15 -0
  44. package/dist/handlers/pre-tool-use.js.map +1 -0
  45. package/dist/handlers/session.d.ts +3 -0
  46. package/dist/handlers/session.js +15 -0
  47. package/dist/handlers/session.js.map +1 -0
  48. package/dist/handlers/stop.d.ts +3 -0
  49. package/dist/handlers/stop.js +15 -0
  50. package/dist/handlers/stop.js.map +1 -0
  51. package/dist/handlers/subagent.d.ts +3 -0
  52. package/dist/handlers/subagent.js +15 -0
  53. package/dist/handlers/subagent.js.map +1 -0
  54. package/dist/handlers/user-prompt.d.ts +3 -0
  55. package/dist/handlers/user-prompt.js +15 -0
  56. package/dist/handlers/user-prompt.js.map +1 -0
  57. package/dist/index.d.ts +1 -0
  58. package/dist/index.js +65 -0
  59. package/dist/index.js.map +1 -0
  60. package/hooks/hooks.json +18 -0
  61. package/package.json +37 -0
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "pinta-ai",
3
+ "owner": {
4
+ "name": "awarecorp",
5
+ "email": "dev@pinta.sh"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "pinta-cc",
10
+ "source": {
11
+ "source": "url",
12
+ "url": "https://github.com/awarecorp/pinta-cc.git"
13
+ },
14
+ "description": "Claude Code security monitoring plugin — emits OTLP spans for hook events and fail-closes on missing Pinta identity.",
15
+ "homepage": "https://pinta.sh",
16
+ "repository": "https://github.com/awarecorp/pinta-cc",
17
+ "category": "security"
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "pinta-cc",
3
+ "description": "Generic OTLP forwarder for Claude Code hook events. Converts hook events into OTLP/HTTP spans and sends them to any OpenTelemetry-compatible collector.",
4
+ "version": "1.2.0",
5
+ "license": "PolyForm-Noncommercial-1.0.0",
6
+ "userConfig": {
7
+ "endpoint": {
8
+ "title": "OTLP endpoint",
9
+ "description": "OTLP/HTTP traces endpoint. Pinta Manager auto-fills this. OSS users: any OTel collector.",
10
+ "type": "string",
11
+ "sensitive": false
12
+ },
13
+ "api_key": {
14
+ "title": "OTLP authentication",
15
+ "description": "Token sent as x-pinta-relay-token header. Pinta Manager auto-fills.",
16
+ "type": "string",
17
+ "sensitive": true
18
+ }
19
+ }
20
+ }
package/CHANGELOG.md ADDED
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ All notable changes to pinta-cc are documented here.
4
+
5
+ ## [1.2.0] - 2026-04-29 (BREAKING)
6
+
7
+ ### BREAKING CHANGES
8
+
9
+ - **Guard module removed** — PreToolUse no longer evaluates server-side block rules. Enforcement is deferred to a future manager-side endpoint.
10
+ - **Pinta CLI dependency removed** — `pinta identity id/email` is no longer invoked. Identity attribution moves to the relay layer (Pinta Manager attaches on forward; OSS users handle in their own pipeline).
11
+ - **`api_key` semantics changed** — was: Pinta backend API key sent as `x-api-key`. Now: token sent as `x-pinta-relay-token` header (or any header via `OTEL_EXPORTER_OTLP_HEADERS` override).
12
+ - **`endpoint` semantics changed** — was: Pinta backend URL. Now: any OTLP/HTTP traces collector URL.
13
+ - **PreToolUse fail-close removed** — without identity to check, the deny path no longer fires. All hooks exit 0 on success, 1 on transport-only failures (handled internally — fail-open).
14
+ - **`member.identity.*` resource attributes removed** — relay attaches identity if present.
15
+ - **`src/enterprise/` directory removed** — `PintaIdentityResolver`, `PintaGuardClient` deleted.
16
+ - **`src/handlers/auth-message.ts` removed** — no auth message to print.
17
+ - **`src/core/guard.ts` removed**.
18
+
19
+ ### Added
20
+
21
+ - `src/core/env-bridge.ts` — aliases Claude Code's `CLAUDE_PLUGIN_OPTION_*` env vars to OTel-spec `OTEL_EXPORTER_OTLP_*`. Explicit OTel env vars take precedence over the bridge.
22
+ - `vitest` test suite (`tests/core/*.test.ts`) — covers OTLP builder + env-bridge.
23
+ - `hasOtlpEndpoint()` helper in `src/core/config.ts` (currently unused — reserved for future signaling).
24
+
25
+ ### Changed
26
+
27
+ - `buildOtlpPayload` signature: `{event, traceId, identity, now?}` → `{event, traceId, now?}`.
28
+ - `Transport` reads OTel env vars at every send/flush call; silent-disables when endpoint missing (was: `loadConfig()` threw).
29
+ - `package.json` name: `pinta` → `@pinta-ai/pinta-cc`.
30
+ - `.claude-plugin/plugin.json` description and userConfig descriptions updated for OTel collector framing.
31
+ - Mock server (`tools/mock-server.ts`) reduced to a generic OTLP collector + viewer (removed Pinta-backend-specific endpoints).
32
+
33
+ ### Migration
34
+
35
+ **For Pinta Manager users:** No action required. Pinta Manager M9d will auto-inject `CLAUDE_PLUGIN_OPTION_ENDPOINT` and `CLAUDE_PLUGIN_OPTION_API_KEY` via Claude Code's settings.json. Marketplace install picks up 1.2.0 on next Claude Code startup.
36
+
37
+ **For standalone users:**
38
+ 1. Update `endpoint` userConfig to your OTLP/HTTP collector URL.
39
+ 2. Update `api_key` to whatever token your collector expects (will be sent as `x-pinta-relay-token`).
40
+ 3. For non-Pinta collectors needing different auth headers, set `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>` directly in the environment — this overrides the userConfig-based bridge.
41
+
42
+ **Identity attribution:** v1.1's `member.identity.*` resource attrs are gone. If you depended on them in your pipeline, attach them at your collector / forwarder layer.
package/LICENSE ADDED
@@ -0,0 +1,136 @@
1
+ # PolyForm Noncommercial License 1.0.0
2
+
3
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
4
+
5
+ ## Acceptance
6
+
7
+ In order to get any license under these terms, you must agree
8
+ to them as both strict obligations and conditions to all
9
+ your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the
14
+ software to do everything you might do with the software
15
+ that would otherwise infringe the licensor's copyright
16
+ in it for any permitted purpose. However, you may
17
+ only distribute the software according to [Distribution
18
+ License](#distribution-license) and make changes or new works
19
+ based on the software according to [Changes and New Works
20
+ License](#changes-and-new-works-license).
21
+
22
+ ## Distribution License
23
+
24
+ The licensor grants you an additional copyright license to
25
+ distribute copies of the software. Your license to distribute
26
+ covers distributing the software with changes and new works
27
+ permitted by [Changes and New Works
28
+ License](#changes-and-new-works-license).
29
+
30
+ ## Notices
31
+
32
+ You must ensure that anyone who gets a copy of any part of
33
+ the software from you also gets a copy of these terms or the
34
+ URL for them above, as well as copies of any plain-text lines
35
+ beginning with `Required Notice:` that the licensor provided
36
+ with the software. For example:
37
+
38
+ > Required Notice: Copyright Pinta AI (https://pinta.sh)
39
+
40
+ ## Changes and New Works License
41
+
42
+ The licensor grants you an additional copyright license to make
43
+ changes and new works based on the software for any permitted
44
+ purpose.
45
+
46
+ ## Patent License
47
+
48
+ The licensor grants you a patent license for the software that
49
+ covers patent claims the licensor can license, or becomes able
50
+ to license, that you would infringe by using the software.
51
+
52
+ ## Noncommercial Purposes
53
+
54
+ Any noncommercial purpose is a permitted purpose.
55
+
56
+ ## Personal Uses
57
+
58
+ Personal use for research, experiment, and testing for
59
+ the benefit of public knowledge, personal study, private
60
+ entertainment, hobby projects, amateur pursuits, or religious
61
+ observance, without any anticipated commercial application,
62
+ is use for a permitted purpose.
63
+
64
+ ## Noncommercial Organizations
65
+
66
+ Use by any charitable organization, educational institution,
67
+ public research organization, public safety or health
68
+ organization, environmental protection organization, or
69
+ government institution is use for a permitted purpose
70
+ regardless of the source of funding or obligations resulting
71
+ from the funding.
72
+
73
+ ## Fair Use
74
+
75
+ You may have "fair use" rights for the software under the
76
+ law. These terms do not limit them.
77
+
78
+ ## No Other Rights
79
+
80
+ These terms do not allow you to sublicense or transfer any of
81
+ your licenses to anyone else, or prevent the licensor from
82
+ granting licenses to anyone else. These terms do not imply
83
+ any other licenses.
84
+
85
+ ## Patent Defense
86
+
87
+ If you make any written claim that the software infringes or
88
+ contributes to infringement of any patent, your patent license
89
+ for the software granted under these terms ends immediately. If
90
+ your company makes such a claim, your patent license ends
91
+ immediately for work on behalf of your company.
92
+
93
+ ## Violations
94
+
95
+ The first time you are notified in writing that you have
96
+ violated any of these terms, or done anything with the software
97
+ not covered by your licenses, your licenses can nonetheless
98
+ continue if you come into full compliance with these terms,
99
+ and take practical steps to correct past violations, within
100
+ 32 days of receiving notice. Otherwise, all your licenses
101
+ end immediately.
102
+
103
+ ## No Liability
104
+
105
+ ***As far as the law allows, the software comes as is, without
106
+ any warranty or condition, and the licensor will not be liable
107
+ to you for any damages arising out of these terms or the use
108
+ or nature of the software, under any kind of legal claim.***
109
+
110
+ ## Definitions
111
+
112
+ The **licensor** is the individual or entity offering these
113
+ terms, and the **software** is the software the licensor makes
114
+ available under these terms.
115
+
116
+ **You** refers to the individual or entity agreeing to these
117
+ terms.
118
+
119
+ **Your company** is any legal entity, sole proprietorship,
120
+ or other kind of organization that you work for, plus all
121
+ organizations that have control over, are under the control
122
+ of, or are under common control with that organization.
123
+ **Control** means ownership of substantially all the assets of
124
+ an entity, or the power to direct its management and policies
125
+ by vote, contract, or otherwise. Control can be direct or
126
+ indirect.
127
+
128
+ **Your licenses** are all the licenses granted to you for the
129
+ software under these terms.
130
+
131
+ **Use** means anything you do with the software requiring one
132
+ of your licenses.
133
+
134
+ ---
135
+
136
+ Required Notice: Copyright (c) 2026 Pinta AI
package/README.md ADDED
@@ -0,0 +1,200 @@
1
+ # pinta-cc — Generic OTLP forwarder for Claude Code hook events
2
+
3
+ Converts Claude Code hook events into OTLP/HTTP spans and forwards them to any OpenTelemetry-compatible collector. No Pinta CLI dependency. No identity check at plugin time. Vendor-neutral.
4
+
5
+ ## Features
6
+
7
+ - **OTLP transport**: converts 11 hook event types into OTLP/HTTP `resourceSpans` and sends them via `POST {endpoint}/traces`
8
+ - **Bronze flattening**: every top-level field of a hook event is flattened into `cc.<key>` span attributes
9
+ - **ULID per-turn traceId**: `UserPromptSubmit` starts a new ULID-based trace; all subsequent hooks in the same turn share it
10
+ - **Retry queue**: on transport failure, payloads are appended to `.plugin-data/failed-spans.jsonl` (cap 1000) and flushed on the next hook invocation
11
+ - **Vendor-neutral**: any OTel-compatible collector works. Pinta Manager auto-configures the endpoint and token
12
+ - **Identity at relay**: `member.identity.*` attributes are no longer attached at plugin time. Pinta Manager (or your own pipeline) attaches identity at the forwarding layer
13
+
14
+ ## Channels
15
+
16
+ | Channel | Install path | Auto-update |
17
+ |---------|-------------|-------------|
18
+ | **Pinta Manager v0.2+** | Manager installs and configures automatically | Yes — on manager reconcile |
19
+ | **Marketplace `pinta-cc@pinta-ai`** | `/plugin marketplace add awarecorp/pinta-cc` then `/plugin install pinta-cc@pinta-ai` | Yes — on Claude Code startup |
20
+
21
+ ## Installation
22
+
23
+ ### Pinta Manager (recommended for enterprise)
24
+
25
+ Pinta Manager v0.2+ handles installation and configuration automatically. No manual steps required.
26
+
27
+ ### Marketplace
28
+
29
+ ```bash
30
+ /plugin marketplace add awarecorp/pinta-cc
31
+ /plugin install pinta-cc@pinta-ai
32
+ ```
33
+
34
+ After installation, Claude Code automatically pulls new versions from the marketplace on every startup.
35
+
36
+ ### Direct from GitHub
37
+
38
+ ```bash
39
+ claude plugin install github:awarecorp/pinta-cc
40
+ ```
41
+
42
+ ### Local development
43
+
44
+ ```bash
45
+ git clone https://github.com/awarecorp/pinta-cc.git
46
+ cd pinta-cc
47
+ npm install && npm run build
48
+ claude --plugin-dir .
49
+ ```
50
+
51
+ ## Configuration
52
+
53
+ ### userConfig (Claude Code plugin settings)
54
+
55
+ | Setting | Description | Required |
56
+ |---------|-------------|----------|
57
+ | `endpoint` | OTLP/HTTP traces endpoint. Pinta Manager auto-fills. OSS: any OTel collector URL | Yes |
58
+ | `api_key` | Token sent as `x-pinta-relay-token` header. Pinta Manager auto-fills | Conditional |
59
+
60
+ ### Pinta Manager scenario
61
+
62
+ Pinta Manager v0.2+ injects `CLAUDE_PLUGIN_OPTION_ENDPOINT` and `CLAUDE_PLUGIN_OPTION_API_KEY` automatically via Claude Code's `settings.json`. No manual configuration needed.
63
+
64
+ ### OSS / direct scenario
65
+
66
+ Set `endpoint` to your OTLP collector URL (e.g. `http://localhost:4318`) and `api_key` to whatever token your collector expects. The token is sent as `x-pinta-relay-token`.
67
+
68
+ For collectors that need a different auth header, set `OTEL_EXPORTER_OTLP_HEADERS` directly in your environment — this overrides the `api_key` userConfig:
69
+
70
+ ```bash
71
+ export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
72
+ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
73
+ ```
74
+
75
+ ### OTel env var precedence
76
+
77
+ The plugin reads OTel env vars directly. `CLAUDE_PLUGIN_OPTION_*` env vars (set by Claude Code from userConfig) are bridged to their `OTEL_EXPORTER_OTLP_*` equivalents **only when the OTel var is not already set**. Explicit `OTEL_EXPORTER_OTLP_*` always win.
78
+
79
+ | Plugin userConfig | Bridged to |
80
+ |------------------|-|
81
+ | `CLAUDE_PLUGIN_OPTION_ENDPOINT` | `OTEL_EXPORTER_OTLP_ENDPOINT` |
82
+ | `CLAUDE_PLUGIN_OPTION_API_KEY` | `OTEL_EXPORTER_OTLP_HEADERS=x-pinta-relay-token=<key>` |
83
+
84
+ ## Span attribute conventions
85
+
86
+ ### Resource attributes
87
+
88
+ | Attribute | Value |
89
+ |-----------|-------|
90
+ | `service.name` | `"claude-code"` |
91
+ | `service.version` | Claude Code CLI version |
92
+ | `telemetry.sdk.name` | `"pinta-cc"` |
93
+ | `telemetry.sdk.version` | Plugin version |
94
+ | `process.pid` | Hook process PID |
95
+ | `process.owner` | OS username |
96
+ | `host.name` | Machine hostname |
97
+ | `host.arch` | CPU architecture |
98
+
99
+ Note: `member.identity.*` attributes are **not** attached at plugin time (moved to relay layer).
100
+
101
+ ### Span attributes
102
+
103
+ | Attribute | Value |
104
+ |-----------|-------|
105
+ | `ingest.type` | `"cc"` (discriminator for aware-backend parser) |
106
+ | `cc.hook` | Hook event name (e.g. `PreToolUse`) |
107
+ | `cc.<key>` | All other top-level hook event fields (Bronze flattening) |
108
+
109
+ ## Architecture
110
+
111
+ ```
112
+ src/
113
+ ├── index.ts # Entry point: env-bridge → stdin parse → handler routing
114
+ ├── core/
115
+ │ ├── env-bridge.ts # CLAUDE_PLUGIN_OPTION_* → OTEL_EXPORTER_OTLP_* alias
116
+ │ ├── types.ts # Hook event types, type guards, skip-list
117
+ │ ├── config.ts # loadConfig() + hasOtlpEndpoint()
118
+ │ ├── otlp.ts # OTLP payload builder + Bronze flattening + ULID→traceId
119
+ │ ├── transport.ts # POST {endpoint}/traces (5s timeout, reads OTel env at call time)
120
+ │ ├── retry-queue.ts # File-based JSONL queue (cap 1000, 30s stale lock TTL)
121
+ │ ├── trace.ts # traceId management (ULID, file-based sharing)
122
+ │ ├── identity.ts # Empty stub (identity attribution moved to relay)
123
+ │ └── redact.ts # Tier-1 redaction + Tier-3 truncation
124
+ └── handlers/
125
+ ├── pre-tool-use.ts # flush → currentTrace → buildOtlpPayload → send → exit 0
126
+ ├── post-tool-use.ts
127
+ ├── user-prompt.ts # flush → newTrace → buildOtlpPayload → send → exit 0
128
+ ├── session.ts
129
+ ├── subagent.ts
130
+ ├── stop.ts
131
+ ├── permission.ts
132
+ └── default.ts # Notification, TaskCreated, TaskCompleted → exit 0 immediately
133
+ ```
134
+
135
+ ## Event flow
136
+
137
+ ```
138
+ UserPromptSubmit (newTrace() → POST /traces)
139
+ → PreToolUse (currentTrace() → POST /traces)
140
+ → PostToolUse (currentTrace() → POST /traces)
141
+ → ...
142
+ UserPromptSubmit (next turn, new traceId)
143
+ → ...
144
+ ```
145
+
146
+ Each hook invocation spawns a fresh Node process. One hook = one OTLP span = one `resourceSpans` entry. Retry queue flush batches multiple spans into a single body.
147
+
148
+ ## Captured events (11)
149
+
150
+ PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SessionStart, SessionEnd, PermissionRequest, PermissionDenied, SubagentStart, SubagentStop, Stop
151
+
152
+ ## Skipped events (3, exit 0 immediately)
153
+
154
+ Notification, TaskCreated, TaskCompleted
155
+
156
+ ## Development
157
+
158
+ ```bash
159
+ npm install
160
+ npm run build # tsc → dist/
161
+ npm test # vitest run
162
+ npm run mock-server # Generic OTLP collector at http://localhost:3000
163
+ ```
164
+
165
+ ### Local integration test
166
+
167
+ ```bash
168
+ # Terminal 1: start the mock OTLP collector
169
+ npm run mock-server
170
+
171
+ # Terminal 2: run Claude Code with the plugin
172
+ CLAUDE_PLUGIN_OPTION_ENDPOINT=http://localhost:3000 \
173
+ CLAUDE_PLUGIN_OPTION_API_KEY=test-token \
174
+ claude --plugin-dir .
175
+ ```
176
+
177
+ Open `http://localhost:3000` to inspect captured spans.
178
+
179
+ ## BREAKING CHANGES from 1.1.x
180
+
181
+ | What changed | 1.1.x | 1.2.x | Migration |
182
+ |---|---|---|---|
183
+ | Pinta CLI dependency | Required (`pinta login`) | Removed | Nothing; Pinta Manager or direct OTel env |
184
+ | `endpoint` meaning | Pinta backend URL | Any OTLP collector URL | Update to your collector's `/v1/traces` or equivalent |
185
+ | `api_key` meaning | Pinta backend API key (`x-api-key` header) | Relay token (`x-pinta-relay-token` header) | Pinta Manager: automatic. Standalone: update token |
186
+ | Identity attributes | `member.identity.id/email` in resource attrs | Removed | Attach at your collector/forwarder layer |
187
+ | PreToolUse fail-close | Exit 2 (deny) when identity unresolved | Removed — always exit 0 | No action needed |
188
+ | `src/enterprise/` | Present | Removed | No action needed |
189
+
190
+ **Pinta Manager users:** No action required. Manager v0.2 auto-injects config on next reconcile.
191
+
192
+ **Marketplace users:** Auto-updated on next Claude Code startup. Update `endpoint` userConfig to your OTLP collector URL if you manage your own pipeline.
193
+
194
+ **Direct env var users:** Replace `CLAUDE_PLUGIN_OPTION_API_KEY` token semantics and ensure your collector accepts `x-pinta-relay-token`, or set `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>` directly.
195
+
196
+ ## License
197
+
198
+ [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0) — see [LICENSE](LICENSE).
199
+
200
+ Commercial use is **not permitted** under this license. Noncommercial use (personal projects, research, educational institutions, nonprofits, government) is allowed. For a commercial license, please contact Pinta AI.
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Plugin config — ONLY the bits we actually use after v1.2.
3
+ * Endpoint/headers come from OTEL_EXPORTER_OTLP_* env vars (set by
4
+ * env-bridge.ts at process startup) — they are NOT in this struct.
5
+ */
6
+ export interface PintaConfig {
7
+ pluginRoot: string;
8
+ pluginData: string;
9
+ tracePath: string;
10
+ }
11
+ export declare function loadConfig(): PintaConfig;
12
+ /** Returns true if OTel endpoint is configured (signal to silently disable telemetry). */
13
+ export declare function hasOtlpEndpoint(): boolean;
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.loadConfig = loadConfig;
7
+ exports.hasOtlpEndpoint = hasOtlpEndpoint;
8
+ const path_1 = __importDefault(require("path"));
9
+ function loadConfig() {
10
+ const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || process.cwd();
11
+ const pluginData = process.env.CLAUDE_PLUGIN_DATA || path_1.default.join(pluginRoot, ".plugin-data");
12
+ return {
13
+ pluginRoot,
14
+ pluginData,
15
+ tracePath: path_1.default.join(pluginData, "trace.json"),
16
+ };
17
+ }
18
+ /** Returns true if OTel endpoint is configured (signal to silently disable telemetry). */
19
+ function hasOtlpEndpoint() {
20
+ return Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
21
+ }
22
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":";;;;;AAaA,gCASC;AAGD,0CAEC;AA3BD,gDAAwB;AAaxB,SAAgB,UAAU;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACnE,MAAM,UAAU,GACd,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAC1E,OAAO;QACL,UAAU;QACV,UAAU;QACV,SAAS,EAAE,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,SAAgB,eAAe;IAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAC1D,CAAC"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Bridge Claude Code's userConfig env vars (CLAUDE_PLUGIN_OPTION_*) to the
3
+ * OTel SDK standard env vars (OTEL_EXPORTER_OTLP_*).
4
+ *
5
+ * Claude Code maps each plugin.json `userConfig.<key>` to a corresponding
6
+ * `CLAUDE_PLUGIN_OPTION_<KEY>` env var on hook spawn. We keep the user-
7
+ * facing names friendly (`endpoint`, `api_key`) and translate them into the
8
+ * canonical OTel env names so transport.ts (and any future OTel SDK adoption)
9
+ * can read them via the OTel-spec names.
10
+ *
11
+ * Pinta Manager auto-injects `CLAUDE_PLUGIN_OPTION_*` via Claude Code's
12
+ * settings.json. OSS users fill them in via the `/plugin install` UI.
13
+ *
14
+ * Existing OTEL_EXPORTER_OTLP_* env vars take precedence (explicit override).
15
+ */
16
+ export declare function bridgeUserConfigToOtelEnv(): void;
@@ -0,0 +1,28 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.bridgeUserConfigToOtelEnv = bridgeUserConfigToOtelEnv;
4
+ /**
5
+ * Bridge Claude Code's userConfig env vars (CLAUDE_PLUGIN_OPTION_*) to the
6
+ * OTel SDK standard env vars (OTEL_EXPORTER_OTLP_*).
7
+ *
8
+ * Claude Code maps each plugin.json `userConfig.<key>` to a corresponding
9
+ * `CLAUDE_PLUGIN_OPTION_<KEY>` env var on hook spawn. We keep the user-
10
+ * facing names friendly (`endpoint`, `api_key`) and translate them into the
11
+ * canonical OTel env names so transport.ts (and any future OTel SDK adoption)
12
+ * can read them via the OTel-spec names.
13
+ *
14
+ * Pinta Manager auto-injects `CLAUDE_PLUGIN_OPTION_*` via Claude Code's
15
+ * settings.json. OSS users fill them in via the `/plugin install` UI.
16
+ *
17
+ * Existing OTEL_EXPORTER_OTLP_* env vars take precedence (explicit override).
18
+ */
19
+ function bridgeUserConfigToOtelEnv() {
20
+ if (process.env.CLAUDE_PLUGIN_OPTION_ENDPOINT && !process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
21
+ process.env.OTEL_EXPORTER_OTLP_ENDPOINT = process.env.CLAUDE_PLUGIN_OPTION_ENDPOINT;
22
+ }
23
+ if (process.env.CLAUDE_PLUGIN_OPTION_API_KEY && !process.env.OTEL_EXPORTER_OTLP_HEADERS) {
24
+ process.env.OTEL_EXPORTER_OTLP_HEADERS =
25
+ `x-pinta-relay-token=${process.env.CLAUDE_PLUGIN_OPTION_API_KEY}`;
26
+ }
27
+ }
28
+ //# sourceMappingURL=env-bridge.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env-bridge.js","sourceRoot":"","sources":["../../src/core/env-bridge.ts"],"names":[],"mappings":";;AAeA,8DAQC;AAvBD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,yBAAyB;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,CAAC;QAC1F,OAAO,CAAC,GAAG,CAAC,2BAA2B,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC;IACtF,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QACxF,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACpC,uBAAuB,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,CAAC;IACtE,CAAC;AACH,CAAC"}
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=identity.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/core/identity.ts"],"names":[],"mappings":""}
@@ -0,0 +1,57 @@
1
+ import type { BaseEvent } from "./types.js";
2
+ export interface OtlpAttribute {
3
+ key: string;
4
+ value: {
5
+ stringValue: string;
6
+ } | {
7
+ intValue: number;
8
+ } | {
9
+ doubleValue: number;
10
+ } | {
11
+ boolValue: boolean;
12
+ };
13
+ }
14
+ export interface OtlpSpan {
15
+ traceId: string;
16
+ spanId: string;
17
+ name: string;
18
+ kind: number;
19
+ startTimeUnixNano: string;
20
+ endTimeUnixNano: string;
21
+ attributes: OtlpAttribute[];
22
+ }
23
+ export interface ResourceSpans {
24
+ resource: {
25
+ attributes: OtlpAttribute[];
26
+ };
27
+ scopeSpans: Array<{
28
+ scope: {
29
+ name: string;
30
+ version: string;
31
+ };
32
+ spans: OtlpSpan[];
33
+ }>;
34
+ }
35
+ export interface OtlpPayload {
36
+ resourceSpans: ResourceSpans[];
37
+ }
38
+ /**
39
+ * Convert a 26-char Crockford ULID into 32 lowercase hex chars (16 bytes)
40
+ * suitable for an OTLP traceId. Decoding is straightforward because each
41
+ * Crockford char carries 5 bits and 26 chars = 130 bits; we keep the low
42
+ * 128 bits (the spec already pads timestamp+randomness into 128 bits).
43
+ */
44
+ export declare function ulidToTraceId(ulid: string): string;
45
+ /** Generate a fresh 16-hex-char (8-byte) span ID. */
46
+ export declare function newSpanId(): string;
47
+ export declare function buildOtlpPayload(args: {
48
+ event: BaseEvent;
49
+ traceId: string;
50
+ now?: number;
51
+ }): OtlpPayload;
52
+ /**
53
+ * Combine multiple per-hook payloads into a single OTLP payload by
54
+ * concatenating their resourceSpans arrays. aware-backend's parser
55
+ * iterates over resourceSpans natively.
56
+ */
57
+ export declare function mergeBatch(payloads: OtlpPayload[]): OtlpPayload;