@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.
- package/.claude-plugin/marketplace.json +20 -0
- package/.claude-plugin/plugin.json +20 -0
- package/CHANGELOG.md +42 -0
- package/LICENSE +136 -0
- package/README.md +200 -0
- package/dist/core/config.d.ts +13 -0
- package/dist/core/config.js +22 -0
- package/dist/core/config.js.map +1 -0
- package/dist/core/env-bridge.d.ts +16 -0
- package/dist/core/env-bridge.js +28 -0
- package/dist/core/env-bridge.js.map +1 -0
- package/dist/core/identity.d.ts +1 -0
- package/dist/core/identity.js +3 -0
- package/dist/core/identity.js.map +1 -0
- package/dist/core/otlp.d.ts +57 -0
- package/dist/core/otlp.js +214 -0
- package/dist/core/otlp.js.map +1 -0
- package/dist/core/redact.d.ts +57 -0
- package/dist/core/redact.js +149 -0
- package/dist/core/redact.js.map +1 -0
- package/dist/core/retry-queue.d.ts +26 -0
- package/dist/core/retry-queue.js +127 -0
- package/dist/core/retry-queue.js.map +1 -0
- package/dist/core/trace.d.ts +10 -0
- package/dist/core/trace.js +61 -0
- package/dist/core/trace.js.map +1 -0
- package/dist/core/transport.d.ts +18 -0
- package/dist/core/transport.js +97 -0
- package/dist/core/transport.js.map +1 -0
- package/dist/core/types.d.ts +65 -0
- package/dist/core/types.js +39 -0
- package/dist/core/types.js.map +1 -0
- package/dist/handlers/default.d.ts +6 -0
- package/dist/handlers/default.js +11 -0
- package/dist/handlers/default.js.map +1 -0
- package/dist/handlers/permission.d.ts +3 -0
- package/dist/handlers/permission.js +15 -0
- package/dist/handlers/permission.js.map +1 -0
- package/dist/handlers/post-tool-use.d.ts +3 -0
- package/dist/handlers/post-tool-use.js +15 -0
- package/dist/handlers/post-tool-use.js.map +1 -0
- package/dist/handlers/pre-tool-use.d.ts +3 -0
- package/dist/handlers/pre-tool-use.js +15 -0
- package/dist/handlers/pre-tool-use.js.map +1 -0
- package/dist/handlers/session.d.ts +3 -0
- package/dist/handlers/session.js +15 -0
- package/dist/handlers/session.js.map +1 -0
- package/dist/handlers/stop.d.ts +3 -0
- package/dist/handlers/stop.js +15 -0
- package/dist/handlers/stop.js.map +1 -0
- package/dist/handlers/subagent.d.ts +3 -0
- package/dist/handlers/subagent.js +15 -0
- package/dist/handlers/subagent.js.map +1 -0
- package/dist/handlers/user-prompt.d.ts +3 -0
- package/dist/handlers/user-prompt.js +15 -0
- package/dist/handlers/user-prompt.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +65 -0
- package/dist/index.js.map +1 -0
- package/hooks/hooks.json +18 -0
- 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 @@
|
|
|
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;
|