turnstamp 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +170 -2
- package/bin/turnstamp.js +284 -0
- package/hooks/claude-code.js +173 -0
- package/opencode.js +31 -0
- package/package.json +55 -4
- package/src/events.js +58 -0
- package/src/index.js +18 -0
- package/src/install.js +114 -0
- package/src/ledger.js +261 -0
- package/src/opencode-plugin.js +115 -0
- package/src/tools.js +87 -0
- package/src/tree.js +91 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Akshay (akshaytheflash)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,171 @@
|
|
|
1
|
-
#
|
|
1
|
+
# turnstamp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Prove what your AI coding agent actually did, and which files a human touched.
|
|
4
|
+
|
|
5
|
+
Your agent says it changed three files. turnstamp tells you which files the agent
|
|
6
|
+
wrote, and flags every file a human changed after the agent said it was done.
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
npm install -g turnstamp
|
|
10
|
+
turnstamp install # wires up OpenCode and Claude Code
|
|
11
|
+
turnstamp verify
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Works with **OpenCode** and **Claude Code**, using each tool's own hooks. No
|
|
15
|
+
filesystem watching and no guessing, because the agent reports each file it
|
|
16
|
+
touches at the moment it touches it.
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
A diff shows the end state of a file. It does not tell you who wrote it, or
|
|
21
|
+
whether something changed after the agent finished.
|
|
22
|
+
|
|
23
|
+
turnstamp records the agent's tool calls as they happen. Before the call it
|
|
24
|
+
hashes the files the call is about to touch, after the call it hashes them
|
|
25
|
+
again. That pair is the agent's own account of what it did, and it goes into a
|
|
26
|
+
hash chain that breaks the moment anyone edits history.
|
|
27
|
+
|
|
28
|
+
Anything the chain does not cover is not the agent. That is how a human edit is
|
|
29
|
+
told apart from an agent edit without guessing.
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
npm install -g turnstamp
|
|
35
|
+
cd your-project
|
|
36
|
+
turnstamp install
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
That writes:
|
|
40
|
+
|
|
41
|
+
- `.opencode/plugins/turnstamp/index.js` for OpenCode
|
|
42
|
+
- `.claude/settings.json` hook entries for Claude Code, merged with whatever is already there
|
|
43
|
+
|
|
44
|
+
Start a new agent session and the hooks are live. Use `turnstamp install opencode`
|
|
45
|
+
or `turnstamp install claude` to do just one. Add `--scope user` to install for
|
|
46
|
+
every project instead of just this one.
|
|
47
|
+
|
|
48
|
+
### What gets recorded
|
|
49
|
+
|
|
50
|
+
| Agent | Tool | Recorded as |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| OpenCode | `write`, `edit`, `patch` | file event with before and after hashes |
|
|
53
|
+
| OpenCode | `shell` | call event with the command, since the files cannot be known up front |
|
|
54
|
+
| Claude Code | `Write`, `Edit`, `MultiEdit`, `NotebookEdit` | file event with before and after hashes |
|
|
55
|
+
| Claude Code | `Bash` | call event with the command |
|
|
56
|
+
|
|
57
|
+
## Commands
|
|
58
|
+
|
|
59
|
+
| Command | What it does |
|
|
60
|
+
| --- | --- |
|
|
61
|
+
| `turnstamp install [agent]` | Wire up the hooks, create the ledger |
|
|
62
|
+
| `turnstamp verify` | Check the chain and say who changed what |
|
|
63
|
+
| `turnstamp log` | Read the ledger back, optionally `--turn N` |
|
|
64
|
+
| `turnstamp stamp` | Manual snapshot, for when no hook is installed |
|
|
65
|
+
| `turnstamp event --json '{...}'` | Record one event from your own tooling |
|
|
66
|
+
|
|
67
|
+
### verify
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
ledger .turnstamp/ledger.jsonl
|
|
71
|
+
entries 14
|
|
72
|
+
head 40af85f1ae3ce639
|
|
73
|
+
chain intact
|
|
74
|
+
files every file matches what the agent recorded
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Exit code is 0 when everything checks out and 1 when something does not, so it
|
|
78
|
+
works as a CI gate or a pre-commit hook.
|
|
79
|
+
|
|
80
|
+
When a human edits a file the agent wrote:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
chain intact
|
|
84
|
+
files changed with no agent call behind them
|
|
85
|
+
hello.txt: last written by write, now 2a688f29a91d0f54...
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
When someone edits the ledger itself:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
chain BROKEN
|
|
92
|
+
entry 6: digest - content changed after it was stamped
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## What it catches
|
|
96
|
+
|
|
97
|
+
- a file rewritten after the agent said it was done
|
|
98
|
+
- an agent claiming a write that never landed on disk
|
|
99
|
+
- an entry edited to hide a file
|
|
100
|
+
- an entry deleted from the middle
|
|
101
|
+
- a careful forger who fixes one digest but not the link to the next entry
|
|
102
|
+
|
|
103
|
+
## What it does not do
|
|
104
|
+
|
|
105
|
+
It does not stop an agent from doing something, it records what happened so you
|
|
106
|
+
can check afterwards. A shell command is recorded as a call, not as a list of
|
|
107
|
+
files, because there is no way to know what a command will touch before it runs.
|
|
108
|
+
|
|
109
|
+
It also cannot prove anything against someone who deletes the whole ledger and
|
|
110
|
+
starts over. Signing the head with a key is the next step, not something 0.1.0
|
|
111
|
+
does.
|
|
112
|
+
|
|
113
|
+
## Library
|
|
114
|
+
|
|
115
|
+
The CLI is a thin wrapper. Everything is exported.
|
|
116
|
+
|
|
117
|
+
```js
|
|
118
|
+
import { appendEvent, verifyEntries, readLedger, ledgerPath } from "turnstamp";
|
|
119
|
+
|
|
120
|
+
const file = ledgerPath(process.cwd());
|
|
121
|
+
appendEvent(file, {
|
|
122
|
+
actor: "agent",
|
|
123
|
+
kind: "file",
|
|
124
|
+
tool: "custom",
|
|
125
|
+
action: "write",
|
|
126
|
+
target: "src/app.js",
|
|
127
|
+
detail: "sha256 of the file",
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
const report = verifyEntries(readLedger(file));
|
|
131
|
+
console.log(report.ok, report.problems);
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The OpenCode plugin lives at `turnstamp/opencode` if you would rather import it
|
|
135
|
+
directly than use the installer.
|
|
136
|
+
|
|
137
|
+
## Ledger format
|
|
138
|
+
|
|
139
|
+
One JSON object per line in `.turnstamp/ledger.jsonl`. Fixed key order, so the
|
|
140
|
+
hash is stable across machines and Node versions.
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"schema": 2,
|
|
145
|
+
"seq": 2,
|
|
146
|
+
"at": "2026-11-16T14:20:18.417Z",
|
|
147
|
+
"turn": null,
|
|
148
|
+
"actor": "opencode",
|
|
149
|
+
"kind": "file",
|
|
150
|
+
"session": "ses_abc",
|
|
151
|
+
"call": "call_def",
|
|
152
|
+
"tool": "write",
|
|
153
|
+
"action": "write",
|
|
154
|
+
"target": "hello.txt",
|
|
155
|
+
"before": "missing",
|
|
156
|
+
"detail": "40af85f1ae3ce639...",
|
|
157
|
+
"prev": "cab1073cf729ddf1...",
|
|
158
|
+
"chain": "8a1b9b0d0e6d0b4b..."
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`prev` is the previous entry's `chain`. The first entry points at 64 zeroes.
|
|
163
|
+
`detail` is the hash after the call, `before` is the hash before it. `missing`
|
|
164
|
+
means the file did not exist.
|
|
165
|
+
|
|
166
|
+
Commit the ledger if you want other people to be able to check your work. It is
|
|
167
|
+
a record, not a secret.
|
|
168
|
+
|
|
169
|
+
## Licence
|
|
170
|
+
|
|
171
|
+
MIT
|
package/bin/turnstamp.js
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
appendEvent,
|
|
7
|
+
checkTree,
|
|
8
|
+
ledgerPath,
|
|
9
|
+
readLedger,
|
|
10
|
+
treeDigest,
|
|
11
|
+
} from "../src/ledger.js";
|
|
12
|
+
import { diffTrees, hashTree } from "../src/tree.js";
|
|
13
|
+
import { initLedger, installClaudeCode, installOpencode } from "../src/install.js";
|
|
14
|
+
|
|
15
|
+
const HELP = `turnstamp - prove what your agent actually did
|
|
16
|
+
|
|
17
|
+
Usage
|
|
18
|
+
turnstamp init create the ledger for this project
|
|
19
|
+
turnstamp install [agent] wire up OpenCode and Claude Code hooks
|
|
20
|
+
turnstamp stamp [options] manual snapshot, when no hook is installed
|
|
21
|
+
turnstamp event --json '{...}' record one agent event yourself
|
|
22
|
+
turnstamp verify [--json] check the chain and who changed what
|
|
23
|
+
turnstamp log [--turn N] [--json] read the ledger back
|
|
24
|
+
|
|
25
|
+
install takes: opencode, claude, both (default)
|
|
26
|
+
and --scope user to write to your home directory
|
|
27
|
+
|
|
28
|
+
verify exits 1 when the chain is broken or a file no longer matches what an
|
|
29
|
+
agent recorded.
|
|
30
|
+
`;
|
|
31
|
+
|
|
32
|
+
export function parseArgs(argv) {
|
|
33
|
+
const args = { _: [] };
|
|
34
|
+
for (let i = 0; i < argv.length; i++) {
|
|
35
|
+
const token = argv[i];
|
|
36
|
+
if (token.startsWith("--")) {
|
|
37
|
+
const key = token.slice(2);
|
|
38
|
+
const next = argv[i + 1];
|
|
39
|
+
if (next === undefined || next.startsWith("--")) {
|
|
40
|
+
args[key] = true;
|
|
41
|
+
} else {
|
|
42
|
+
args[key] = next;
|
|
43
|
+
i++;
|
|
44
|
+
}
|
|
45
|
+
} else {
|
|
46
|
+
args._.push(token);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
return args;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
// Rebuilds the file map as it stood at the end of a turn, by replaying the per
|
|
53
|
+
// file entries that belong to that turn.
|
|
54
|
+
function snapshotAtTurn(entries, turn) {
|
|
55
|
+
const map = new Map();
|
|
56
|
+
for (const entry of entries) {
|
|
57
|
+
if (!entry.target || entry.turn !== turn) continue;
|
|
58
|
+
if (entry.action === "delete") {
|
|
59
|
+
map.delete(entry.target);
|
|
60
|
+
} else {
|
|
61
|
+
map.set(entry.target, entry.detail);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
return map;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function snapshotTurns(entries) {
|
|
68
|
+
const turns = new Set();
|
|
69
|
+
for (const entry of entries) {
|
|
70
|
+
if (!entry.target && entry.action === "snapshot" && typeof entry.turn === "number") {
|
|
71
|
+
turns.add(entry.turn);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
return [...turns].sort((a, b) => a - b);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function nextTurn(entries) {
|
|
78
|
+
let max = -1;
|
|
79
|
+
for (const entry of entries) {
|
|
80
|
+
if (typeof entry.turn === "number" && entry.turn > max) {
|
|
81
|
+
max = entry.turn;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return max + 1;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function cmdInit() {
|
|
88
|
+
const file = initLedger(process.cwd());
|
|
89
|
+
console.log(`ready ${path.relative(process.cwd(), file)}`);
|
|
90
|
+
return 0;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function cmdInstall(args) {
|
|
94
|
+
const which = args._[0] || "both";
|
|
95
|
+
const scope = args.scope === "user" ? "user" : "project";
|
|
96
|
+
const cwd = process.cwd();
|
|
97
|
+
|
|
98
|
+
if (which === "opencode" || which === "both") {
|
|
99
|
+
const result = installOpencode(scope, cwd);
|
|
100
|
+
console.log(`opencode plugin written to ${result.dir}`);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
if (which === "claude" || which === "both") {
|
|
104
|
+
const result = installClaudeCode(scope, cwd);
|
|
105
|
+
console.log(`claude code hooks merged into ${result.file}`);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const file = initLedger(cwd);
|
|
109
|
+
console.log(`ledger ready at ${path.relative(cwd, file)}`);
|
|
110
|
+
console.log("restart the agent, or start a new session, to pick this up");
|
|
111
|
+
return 0;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// A stamp records the files that changed since the previous snapshot, one entry
|
|
115
|
+
// each, then a summary entry. verify replays those entries to catch rewrites.
|
|
116
|
+
function cmdStamp(args) {
|
|
117
|
+
const root = process.cwd();
|
|
118
|
+
const file = ledgerPath(root);
|
|
119
|
+
const entries = readLedger(file);
|
|
120
|
+
const tool = args.tool || "manual";
|
|
121
|
+
const action = args.action || "snapshot";
|
|
122
|
+
const turn = args.turn ? Number(args.turn) : nextTurn(entries);
|
|
123
|
+
|
|
124
|
+
const now = hashTree(root);
|
|
125
|
+
const previousTurns = snapshotTurns(entries);
|
|
126
|
+
const previous =
|
|
127
|
+
previousTurns.length > 0 ? snapshotAtTurn(entries, previousTurns.at(-1)) : new Map();
|
|
128
|
+
|
|
129
|
+
const delta = diffTrees(previous, now);
|
|
130
|
+
const touched = [...new Set([...delta.added, ...delta.changed, ...delta.removed])].sort();
|
|
131
|
+
|
|
132
|
+
for (const target of touched) {
|
|
133
|
+
const detail = now.get(target) ?? "missing";
|
|
134
|
+
appendEvent(file, {
|
|
135
|
+
turn,
|
|
136
|
+
actor: "agent",
|
|
137
|
+
kind: "file",
|
|
138
|
+
tool,
|
|
139
|
+
action: detail === "missing" ? "delete" : "write",
|
|
140
|
+
target,
|
|
141
|
+
detail,
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
const summary = appendEvent(file, {
|
|
146
|
+
turn,
|
|
147
|
+
actor: "agent",
|
|
148
|
+
kind: "call",
|
|
149
|
+
tool,
|
|
150
|
+
action,
|
|
151
|
+
target: null,
|
|
152
|
+
detail: JSON.stringify({
|
|
153
|
+
files: now.size,
|
|
154
|
+
added: delta.added.length,
|
|
155
|
+
changed: delta.changed.length,
|
|
156
|
+
removed: delta.removed.length,
|
|
157
|
+
tree: treeDigest(now),
|
|
158
|
+
}),
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
console.log(
|
|
162
|
+
`stamped turn ${turn}: ${delta.added.length} added, ${delta.changed.length} changed, ` +
|
|
163
|
+
`${delta.removed.length} removed (${now.size} files, ${summary.chain.slice(0, 12)})`,
|
|
164
|
+
);
|
|
165
|
+
return 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function short(value) {
|
|
169
|
+
if (typeof value !== "string") return String(value);
|
|
170
|
+
return value.length > 16 ? `${value.slice(0, 16)}...` : value;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
function cmdVerify(args) {
|
|
174
|
+
const root = process.cwd();
|
|
175
|
+
const file = ledgerPath(root);
|
|
176
|
+
const report = checkTree(file, root);
|
|
177
|
+
const ok = report.ok && report.drift.length === 0;
|
|
178
|
+
|
|
179
|
+
if (args.json) {
|
|
180
|
+
console.log(JSON.stringify(report, null, 2));
|
|
181
|
+
return ok ? 0 : 1;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
console.log(`ledger ${path.relative(root, file)}`);
|
|
185
|
+
console.log(`entries ${report.count}`);
|
|
186
|
+
console.log(`head ${report.head.slice(0, 16)}`);
|
|
187
|
+
|
|
188
|
+
if (report.ok) {
|
|
189
|
+
console.log("chain intact");
|
|
190
|
+
} else {
|
|
191
|
+
console.log("chain BROKEN");
|
|
192
|
+
for (const problem of report.problems) {
|
|
193
|
+
console.log(` ${problem.at}: ${problem.kind} - ${problem.message}`);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
if (report.drift.length === 0) {
|
|
198
|
+
console.log("files every file matches what the agent recorded");
|
|
199
|
+
} else {
|
|
200
|
+
console.log("files changed with no agent call behind them");
|
|
201
|
+
for (const item of report.drift) {
|
|
202
|
+
const by = item.tool ? `last written by ${item.tool}` : "never seen by an agent";
|
|
203
|
+
console.log(` ${item.target}: ${by}, now ${short(item.current)}`);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
return ok ? 0 : 1;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function cmdLog(args) {
|
|
211
|
+
const entries = readLedger(ledgerPath(process.cwd()));
|
|
212
|
+
const filtered =
|
|
213
|
+
args.turn !== undefined
|
|
214
|
+
? entries.filter((entry) => String(entry.turn) === String(args.turn))
|
|
215
|
+
: entries;
|
|
216
|
+
|
|
217
|
+
if (args.json) {
|
|
218
|
+
console.log(JSON.stringify(filtered, null, 2));
|
|
219
|
+
return 0;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
if (filtered.length === 0) {
|
|
223
|
+
console.log("nothing recorded yet");
|
|
224
|
+
return 0;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
for (const entry of filtered) {
|
|
228
|
+
const when = entry.at.slice(11, 19);
|
|
229
|
+
const turn = entry.turn === null ? "-" : String(entry.turn);
|
|
230
|
+
console.log(
|
|
231
|
+
`${when} t${turn} ${entry.tool}/${entry.action} ${entry.target || "(turn)"} ${entry.chain.slice(0, 10)}`,
|
|
232
|
+
);
|
|
233
|
+
}
|
|
234
|
+
return 0;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
function cmdEvent(args) {
|
|
238
|
+
if (!args.json || args.json === true) {
|
|
239
|
+
console.error("event needs --json '{...}'");
|
|
240
|
+
return 1;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
let payload;
|
|
244
|
+
try {
|
|
245
|
+
payload = JSON.parse(String(args.json));
|
|
246
|
+
} catch (err) {
|
|
247
|
+
console.error(`bad json: ${err.message}`);
|
|
248
|
+
return 1;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const entry = appendEvent(ledgerPath(process.cwd()), payload);
|
|
252
|
+
console.log(`${entry.seq} ${entry.chain.slice(0, 12)}`);
|
|
253
|
+
return 0;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function main(argv) {
|
|
257
|
+
const [command, ...rest] = argv;
|
|
258
|
+
const args = parseArgs(rest);
|
|
259
|
+
|
|
260
|
+
if (!command || command === "help" || args.help) {
|
|
261
|
+
console.log(HELP);
|
|
262
|
+
return 0;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
switch (command) {
|
|
266
|
+
case "init":
|
|
267
|
+
return cmdInit();
|
|
268
|
+
case "install":
|
|
269
|
+
return cmdInstall(args);
|
|
270
|
+
case "stamp":
|
|
271
|
+
return cmdStamp(args);
|
|
272
|
+
case "event":
|
|
273
|
+
return cmdEvent(args);
|
|
274
|
+
case "verify":
|
|
275
|
+
return cmdVerify(args);
|
|
276
|
+
case "log":
|
|
277
|
+
return cmdLog(args);
|
|
278
|
+
default:
|
|
279
|
+
console.error(`unknown command: ${command}`);
|
|
280
|
+
return 1;
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
process.exitCode = main(process.argv.slice(2));
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import { appendEvent, ledgerPath } from "../src/ledger.js";
|
|
6
|
+
import { normalizeTarget } from "../src/events.js";
|
|
7
|
+
import { isFileTool, readState, shellCommand, toolPaths } from "../src/tools.js";
|
|
8
|
+
|
|
9
|
+
// Claude Code hook.
|
|
10
|
+
//
|
|
11
|
+
// Reads the event JSON on stdin and appends one entry. It runs inline on every
|
|
12
|
+
// tool call, so it does no tree walking and makes no network calls.
|
|
13
|
+
//
|
|
14
|
+
// Register it for PreToolUse and PostToolUse on the file tools, and for Bash so
|
|
15
|
+
// shell commands show up too.
|
|
16
|
+
|
|
17
|
+
async function readStdin() {
|
|
18
|
+
if (process.stdin.isTTY) {
|
|
19
|
+
return "";
|
|
20
|
+
}
|
|
21
|
+
const chunks = [];
|
|
22
|
+
for await (const chunk of process.stdin) {
|
|
23
|
+
chunks.push(chunk);
|
|
24
|
+
}
|
|
25
|
+
return Buffer.concat(chunks).toString("utf8");
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function rootOf(payload) {
|
|
29
|
+
return path.resolve(payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function pendingFile(root, call) {
|
|
33
|
+
const safe = String(call).replace(/[^A-Za-z0-9_-]/g, "_");
|
|
34
|
+
return path.join(root, ".turnstamp", "pending", `${safe}.json`);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// The before state has to survive until the after hook runs, and that is a
|
|
38
|
+
// separate process, so it goes to a small side file.
|
|
39
|
+
function writePending(root, call, states) {
|
|
40
|
+
if (!call) return;
|
|
41
|
+
const file = pendingFile(root, call);
|
|
42
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
43
|
+
fs.writeFileSync(file, JSON.stringify(states), "utf8");
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function readPending(root, call) {
|
|
47
|
+
if (!call) return [];
|
|
48
|
+
try {
|
|
49
|
+
return JSON.parse(fs.readFileSync(pendingFile(root, call), "utf8"));
|
|
50
|
+
} catch {
|
|
51
|
+
return [];
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function clearPending(root, call) {
|
|
56
|
+
if (!call) return;
|
|
57
|
+
try {
|
|
58
|
+
fs.unlinkSync(pendingFile(root, call));
|
|
59
|
+
} catch {
|
|
60
|
+
// Already gone.
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function fileStates(root, tool, input) {
|
|
65
|
+
return toolPaths(tool, input)
|
|
66
|
+
.map((p) => normalizeTarget(root, p))
|
|
67
|
+
.filter(Boolean)
|
|
68
|
+
.map((target) => ({ target, before: readState(path.join(root, target)) }));
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function onBefore(root, file, fields) {
|
|
72
|
+
const { tool, session, call, input } = fields;
|
|
73
|
+
|
|
74
|
+
if (isFileTool(tool)) {
|
|
75
|
+
const states = fileStates(root, tool, input);
|
|
76
|
+
appendEvent(file, {
|
|
77
|
+
actor: "claude-code",
|
|
78
|
+
kind: "call",
|
|
79
|
+
session,
|
|
80
|
+
call,
|
|
81
|
+
tool,
|
|
82
|
+
action: "call",
|
|
83
|
+
detail: JSON.stringify({ phase: "before", files: states.map((s) => s.target) }),
|
|
84
|
+
});
|
|
85
|
+
writePending(root, call, states);
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const command = tool === "Bash" || tool === "PowerShell" ? shellCommand(input) : null;
|
|
90
|
+
appendEvent(file, {
|
|
91
|
+
actor: "claude-code",
|
|
92
|
+
kind: "call",
|
|
93
|
+
session,
|
|
94
|
+
call,
|
|
95
|
+
tool,
|
|
96
|
+
action: command ? "shell" : "call",
|
|
97
|
+
target: command,
|
|
98
|
+
detail: JSON.stringify({ phase: "before" }),
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function onAfter(root, file, fields) {
|
|
103
|
+
const { tool, session, call, input, failed } = fields;
|
|
104
|
+
|
|
105
|
+
if (!isFileTool(tool)) {
|
|
106
|
+
appendEvent(file, {
|
|
107
|
+
actor: "claude-code",
|
|
108
|
+
kind: "call",
|
|
109
|
+
session,
|
|
110
|
+
call,
|
|
111
|
+
tool,
|
|
112
|
+
action: failed ? "failed" : "done",
|
|
113
|
+
detail: null,
|
|
114
|
+
});
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const held = readPending(root, call);
|
|
119
|
+
const states = held.length ? held : fileStates(root, tool, input);
|
|
120
|
+
|
|
121
|
+
for (const item of states) {
|
|
122
|
+
if (!item.target) continue;
|
|
123
|
+
const after = readState(path.join(root, item.target));
|
|
124
|
+
appendEvent(file, {
|
|
125
|
+
actor: "claude-code",
|
|
126
|
+
kind: "file",
|
|
127
|
+
session,
|
|
128
|
+
call,
|
|
129
|
+
tool,
|
|
130
|
+
action: after === "missing" ? "delete" : "write",
|
|
131
|
+
target: item.target,
|
|
132
|
+
before: item.before ?? null,
|
|
133
|
+
detail: after,
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
clearPending(root, call);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function main(payload) {
|
|
141
|
+
const root = rootOf(payload);
|
|
142
|
+
const file = ledgerPath(root);
|
|
143
|
+
const fields = {
|
|
144
|
+
tool: String(payload.tool_name || "unknown"),
|
|
145
|
+
session: String(payload.session_id || ""),
|
|
146
|
+
call: String(payload.tool_use_id || ""),
|
|
147
|
+
input: payload.tool_input || {},
|
|
148
|
+
failed: payload.hook_event_name === "PostToolUseFailure",
|
|
149
|
+
};
|
|
150
|
+
|
|
151
|
+
switch (payload.hook_event_name) {
|
|
152
|
+
case "PreToolUse":
|
|
153
|
+
onBefore(root, file, fields);
|
|
154
|
+
break;
|
|
155
|
+
case "PostToolUse":
|
|
156
|
+
case "PostToolUseFailure":
|
|
157
|
+
onAfter(root, file, fields);
|
|
158
|
+
break;
|
|
159
|
+
default:
|
|
160
|
+
break;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const raw = await readStdin();
|
|
165
|
+
if (raw.trim()) {
|
|
166
|
+
try {
|
|
167
|
+
main(JSON.parse(raw));
|
|
168
|
+
} catch (err) {
|
|
169
|
+
// A hook must never break the session. Exit 0 with no output is a no-op.
|
|
170
|
+
process.stderr.write(`turnstamp hook: ${err.message}\n`);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
process.exit(0);
|
package/opencode.js
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { Plugin } from "@opencode/plugin";
|
|
2
|
+
|
|
3
|
+
import { createTracker } from "./src/opencode-plugin.js";
|
|
4
|
+
|
|
5
|
+
// OpenCode plugin entrypoint.
|
|
6
|
+
//
|
|
7
|
+
// This is both the package default export and the "./opencode" subpath, so
|
|
8
|
+
// OpenCode can load the package directly from a plugins entry.
|
|
9
|
+
//
|
|
10
|
+
// Options:
|
|
11
|
+
// actor name written into the ledger, defaults to opencode
|
|
12
|
+
// root project root, defaults to the location directory
|
|
13
|
+
// debug print ledger errors instead of swallowing them
|
|
14
|
+
export default Plugin.define({
|
|
15
|
+
id: "turnstamp",
|
|
16
|
+
async setup(ctx) {
|
|
17
|
+
const tracker = createTracker({
|
|
18
|
+
root: ctx.options.root || ctx.location.directory,
|
|
19
|
+
actor: ctx.options.actor || "opencode",
|
|
20
|
+
debug: ctx.options.debug === true,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
await ctx.tool.hook("execute.before", (event) => {
|
|
24
|
+
tracker.before(event);
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
await ctx.tool.hook("execute.after", (event) => {
|
|
28
|
+
tracker.after(event);
|
|
29
|
+
});
|
|
30
|
+
},
|
|
31
|
+
});
|