tracehub 0.0.0-stage → 0.5.2

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 (48) hide show
  1. package/README.md +431 -2
  2. package/dist/cli/args.js +28 -0
  3. package/dist/cli/clipboard.js +46 -0
  4. package/dist/cli/commands/context.js +115 -0
  5. package/dist/cli/commands/hook.js +215 -0
  6. package/dist/cli/commands/providers.js +55 -0
  7. package/dist/cli/commands/setup.js +448 -0
  8. package/dist/cli/commands/uninstall.js +156 -0
  9. package/dist/cli/io.js +26 -0
  10. package/dist/cli/remote.js +81 -0
  11. package/dist/cli/repo.js +70 -0
  12. package/dist/cli/signin.js +90 -0
  13. package/dist/cli/ui.js +130 -0
  14. package/dist/cli/usage.js +151 -0
  15. package/dist/cli.js +38 -0
  16. package/dist/client/auth.js +70 -0
  17. package/dist/client/consent.js +94 -0
  18. package/dist/client/errors.js +4 -0
  19. package/dist/client/github.js +129 -0
  20. package/dist/client/registry.js +112 -0
  21. package/dist/client/tracehub.js +98 -0
  22. package/dist/client/upload.js +106 -0
  23. package/dist/client/uploadPolicy.js +60 -0
  24. package/dist/git/git.js +163 -0
  25. package/dist/git/global-hooks.js +221 -0
  26. package/dist/git/hooks.js +67 -0
  27. package/dist/git/markers.js +93 -0
  28. package/dist/git/trailers.js +36 -0
  29. package/dist/local/commitBoundary.js +38 -0
  30. package/dist/local/discover.js +283 -0
  31. package/dist/local/files.js +55 -0
  32. package/dist/local/lines.js +16 -0
  33. package/dist/local/opencode.js +124 -0
  34. package/dist/local/paths.js +51 -0
  35. package/dist/local/providers.js +171 -0
  36. package/dist/local/subagents.js +63 -0
  37. package/dist/protocol/context.js +202 -0
  38. package/dist/protocol/sessionRef.js +24 -0
  39. package/dist/protocol/trace.js +111 -0
  40. package/dist/redact/deny.js +25 -0
  41. package/dist/redact/redact.js +189 -0
  42. package/dist/trace/build.js +256 -0
  43. package/dist/transcript/parseClaude.js +105 -0
  44. package/dist/transcript/parseCodex.js +164 -0
  45. package/dist/transcript/parseOpencode.js +84 -0
  46. package/dist/transcript/title.js +27 -0
  47. package/dist/transcript/transcript.js +120 -0
  48. package/package.json +44 -4
@@ -0,0 +1,115 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { freshAuth } from "../../client/auth.js";
3
+ import { tracehubUrl } from "../../client/tracehub.js";
4
+ import { UPLOAD_POLICY_ERROR } from "../../client/uploadPolicy.js";
5
+ import { fetchContext, manualConversations } from "../../local/providers.js";
6
+ import { mergeConversations, parseContextRef, } from "../../protocol/context.js";
7
+ import { formatFindings, redactValue } from "../../redact/redact.js";
8
+ import { flagValue } from "../args.js";
9
+ import { out, warn } from "../io.js";
10
+ import { clientFor, redactOptions, usableAuth } from "../remote.js";
11
+ import { consentFor, uploadTargetFor } from "../repo.js";
12
+ import { commandUsage } from "../usage.js";
13
+ // stdin read as a stream: a pipe can be non-blocking, which readFileSync(0)
14
+ // answers with EAGAIN.
15
+ async function readStdin() {
16
+ const chunks = [];
17
+ for await (const chunk of process.stdin)
18
+ chunks.push(chunk);
19
+ return Buffer.concat(chunks).toString("utf8");
20
+ }
21
+ function prOf(args) {
22
+ const pr = Number(flagValue(args, "pr"));
23
+ if (!Number.isSafeInteger(pr) || pr < 1)
24
+ throw new Error('--pr <number> is required; see "tracehub context --help"');
25
+ return pr;
26
+ }
27
+ // The conversations to attach: from their providers or the file, merged,
28
+ // redacted.
29
+ async function conversationsOf(args, allowed) {
30
+ const refs = args.positional.slice(2);
31
+ const from = flagValue(args, "from");
32
+ if (!refs.length && !from)
33
+ throw new Error('name a conversation (<provider>:<id>) or --from <file|->; "-" reads stdin');
34
+ const lists = [];
35
+ if (from) {
36
+ const text = from === "-" ? await readStdin() : readFileSync(from, "utf8");
37
+ lists.push(manualConversations(text));
38
+ }
39
+ for (const ref of refs) {
40
+ try {
41
+ lists.push([await fetchContext(ref, allowed)]);
42
+ }
43
+ catch (err) {
44
+ throw new Error(`context ${ref}: ${err.message}`);
45
+ }
46
+ }
47
+ return mergeConversations(lists);
48
+ }
49
+ async function add(args, cwd) {
50
+ const pr = prOf(args);
51
+ const target = uploadTargetFor(cwd);
52
+ if (!target)
53
+ throw new Error(UPLOAD_POLICY_ERROR);
54
+ // The rule comes first: no provider runs for a repository without one.
55
+ if (consentFor(cwd) !== true)
56
+ throw new Error(`no permission rule allows uploads for ${target.owner}/${target.repo}; run "tracehub setup"`);
57
+ const redacted = redactValue(await conversationsOf(args, true), redactOptions());
58
+ const context = redacted.value;
59
+ if (redacted.findings.length)
60
+ warn(`masked ${formatFindings(redacted.findings)} before upload`);
61
+ const where = `${target.owner}/${target.repo}#${pr}`;
62
+ const count = context.reduce((n, c) => n + c.messages.length, 0);
63
+ if (args.flags["dry-run"]) {
64
+ out(`would attach ${context.length} conversation(s), ${count} message(s), to ${where}:`);
65
+ out(JSON.stringify(context, null, 2));
66
+ return;
67
+ }
68
+ const stored = usableAuth();
69
+ if (!stored)
70
+ throw new Error('not signed in; run "tracehub setup"');
71
+ const client = clientFor(await freshAuth(stored));
72
+ const result = await client.putContext(target, pr, context);
73
+ if (result.withheld)
74
+ warn(`tracehub withheld ${result.withheld} message(s) that look sensitive`);
75
+ out(`attached ${context.length} conversation(s), ${count} message(s), to ${where}`);
76
+ out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
77
+ }
78
+ // Detaches conversations from the pull request: the uploader's or, for a
79
+ // maintainer, anyone's. Nothing is fetched or uploaded, so no permission
80
+ // rule is needed; the API checks push access as it does for add.
81
+ async function remove(args, cwd) {
82
+ const pr = prOf(args);
83
+ const refs = [...new Set(args.positional.slice(2))];
84
+ if (!refs.length)
85
+ throw new Error("name a conversation to remove (<provider>:<id>)");
86
+ for (const ref of refs)
87
+ if (!parseContextRef(ref))
88
+ throw new Error(`"${ref}" is not a conversation (<provider>:<id>)`);
89
+ const target = uploadTargetFor(cwd);
90
+ if (!target)
91
+ throw new Error(UPLOAD_POLICY_ERROR);
92
+ const where = `${target.owner}/${target.repo}#${pr}`;
93
+ const stored = usableAuth();
94
+ if (!stored)
95
+ throw new Error('not signed in; run "tracehub setup"');
96
+ const client = clientFor(await freshAuth(stored));
97
+ const { removed } = await client.deleteContext(target, pr, refs);
98
+ for (const ref of refs)
99
+ if (!removed.includes(ref))
100
+ warn(`${ref} is not attached to ${where}`);
101
+ out(`removed ${removed.length} conversation(s) from ${where}`);
102
+ out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
103
+ }
104
+ export async function cmdContext(args, cwd) {
105
+ const sub = args.positional[1];
106
+ if (args.flags["help"] || args.flags["h"] || !sub) {
107
+ out(commandUsage("context"));
108
+ return;
109
+ }
110
+ if (sub === "add")
111
+ return add(args, cwd);
112
+ if (sub === "remove")
113
+ return remove(args, cwd);
114
+ throw new Error(`unknown context command "${sub}"; use add or remove`);
115
+ }
@@ -0,0 +1,215 @@
1
+ import { spawn } from "node:child_process";
2
+ import { closeSync, openSync, readFileSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { freshAuth } from "../../client/auth.js";
5
+ import { readConsent } from "../../client/consent.js";
6
+ import { registerConsent, registrationPending } from "../../client/registry.js";
7
+ import { tracehubUrl } from "../../client/tracehub.js";
8
+ import { consentFile } from "../../local/paths.js";
9
+ import { firstLine } from "../../client/errors.js";
10
+ import { uploadMarkers } from "../../client/upload.js";
11
+ import { UPLOAD_OWNER, UPLOAD_POLICY_ERROR, } from "../../client/uploadPolicy.js";
12
+ import { git, pushedTraceIds, repoRoot, tracesInPushedHistory, } from "../../git/git.js";
13
+ import { pendingMarkers, readMarkers, recordMarkers, } from "../../git/markers.js";
14
+ import { interpretTrailersArgs, newTraceId, shouldSkipCommit, traceIds, } from "../../git/trailers.js";
15
+ import { formatContextRef, parseContextRef } from "../../protocol/context.js";
16
+ import { formatSessionRef } from "../../protocol/sessionRef.js";
17
+ import { ENV_CONTEXT, ENV_SESSION_ID } from "../../local/paths.js";
18
+ import { warn } from "../io.js";
19
+ import { BACKGROUND_BUDGET_MS, clientFor, commitCount, pushBudgetMs, ranOutOfTime, reportUpload, redactOptions, usableAuth, } from "../remote.js";
20
+ import { consentFor, hooksDisabled, resolveSessions, stateDir, uploadTargetFor, } from "../repo.js";
21
+ // The trailer names the commit's sessions on tracehub, so a message that
22
+ // already carries one (amend, rebase, cherry-pick, a squash folding earlier
23
+ // messages) keeps it, and the markers recorded under it stay with the commit.
24
+ function hookPrepareCommitMsg(args, cwd) {
25
+ const [messageFile, source] = [args.positional[2], args.positional[3]];
26
+ if (!messageFile || shouldSkipCommit(source, process.env))
27
+ return;
28
+ const root = repoRoot(cwd);
29
+ if (!root)
30
+ return;
31
+ const target = uploadTargetFor(cwd);
32
+ if (!target) {
33
+ if (process.env[ENV_SESSION_ID]?.trim())
34
+ warn(`${ENV_SESSION_ID} is set, but origin is not one GitHub repository owned by ${UPLOAD_OWNER}; no trace attached to this commit`);
35
+ return;
36
+ }
37
+ const consent = consentFor(cwd);
38
+ if (consent === false)
39
+ return;
40
+ const { refs } = resolveSessions(cwd, root);
41
+ if (!refs.length)
42
+ return;
43
+ if (consent === undefined) {
44
+ warn(`${refs.length} agent session(s) could have been attached to this commit; run "tracehub setup" to allow uploads for this repository or its organization`);
45
+ return;
46
+ }
47
+ let id = traceIds(readFileSync(messageFile, "utf8")).at(-1);
48
+ if (!id) {
49
+ id = newTraceId();
50
+ git(interpretTrailersArgs(target, id, messageFile), { cwd });
51
+ }
52
+ for (const ref of recordMarkers(stateDir(cwd), id, refs, new Date(), envContextRefs())) {
53
+ warn(`session ${formatSessionRef(ref)} not found on this machine; no marker recorded`);
54
+ }
55
+ }
56
+ // The context refs of TRACEHUB_CONTEXT; one that is not a ref is reported.
57
+ function envContextRefs() {
58
+ const refs = [];
59
+ for (const word of (process.env[ENV_CONTEXT] ?? "").split(/[\s,]+/)) {
60
+ if (!word)
61
+ continue;
62
+ const ref = parseContextRef(word);
63
+ if (ref)
64
+ refs.push(formatContextRef(ref));
65
+ else
66
+ warn(`${ENV_CONTEXT}: "${word}" is not a <provider>:<id> reference`);
67
+ }
68
+ return [...new Set(refs)];
69
+ }
70
+ async function hookPrePush(args, cwd) {
71
+ if (hooksDisabled() || consentFor(cwd) !== true)
72
+ return;
73
+ const pushedUrl = args.positional[3];
74
+ if (!pushedUrl) {
75
+ warn('pre-push requires Git\'s destination arguments; forward "$@" from the hook; nothing was uploaded');
76
+ return;
77
+ }
78
+ const target = uploadTargetFor(cwd, {
79
+ remote: args.positional[2],
80
+ url: pushedUrl,
81
+ });
82
+ if (!target) {
83
+ warn(UPLOAD_POLICY_ERROR);
84
+ return;
85
+ }
86
+ const dir = stateDir(cwd);
87
+ const input = process.stdin.isTTY ? "" : readFileSync(0, "utf8");
88
+ if (!input.trim()) {
89
+ if (pendingMarkers(readMarkers(dir)).length)
90
+ warn("pre-push received no pushed refs; traces stay pending until the next push");
91
+ return;
92
+ }
93
+ const ids = pushedTraceIds(cwd, args.positional[2], input);
94
+ const all = readMarkers(dir);
95
+ // A trace left pending by an earlier push is retried once a push carries
96
+ // its commit's history.
97
+ const earlier = tracesInPushedHistory(cwd, input, [
98
+ ...new Set(all.filter((marker) => !marker.uploaded).map((m) => m.traceId)),
99
+ ].filter((id) => !ids.has(id)));
100
+ const markers = all.filter((marker) => ids.has(marker.traceId) || earlier.has(marker.traceId));
101
+ if (!markers.length)
102
+ return;
103
+ const pending = pendingMarkers(markers);
104
+ if (pending.length)
105
+ warn(`uploading traces for ${commitCount(pending)} pushed commit(s) from ${new Set(markers.map((marker) => marker.session)).size} session(s)`);
106
+ const stay = `the markers of ${commitCount(pending)} commit(s) stay pending`;
107
+ const stored = usableAuth();
108
+ if (!stored) {
109
+ if (pending.length) {
110
+ warn(`not signed in; ${stay} until a push after "tracehub setup"`);
111
+ }
112
+ return;
113
+ }
114
+ try {
115
+ const auth = await freshAuth(stored);
116
+ await retryRegistration(auth.accessToken);
117
+ const client = clientFor(auth, pushBudgetMs());
118
+ await client.verifyTarget(target);
119
+ const result = await uploadMarkers(client, target, dir, cwd, repoRoot(cwd) ?? cwd, markers, redactOptions(), consentFor(cwd) === true);
120
+ // A big session can take longer than a push waits. The rest goes on in
121
+ // the background, so a commit whose branch is never pushed again (a
122
+ // squash-merged pull request) still gets its trace.
123
+ const log = ranOutOfTime(result)
124
+ ? continueInBackground(cwd, dir, pushedUrl, result.skipped)
125
+ : undefined;
126
+ reportUpload(result, target, warn, log);
127
+ }
128
+ catch (err) {
129
+ warn(`upload failed, left pending for the next push: ${firstLine(err)}`);
130
+ }
131
+ }
132
+ const UPLOAD_LOG = "upload.log";
133
+ // Starts `tracehub hook upload` for the traces of these markers, detached,
134
+ // with its output in .git/tracehub/upload.log. Returns the log's path.
135
+ function continueInBackground(cwd, dir, pushedUrl, pending) {
136
+ const ids = [...new Set(pending.map((marker) => marker.traceId))];
137
+ if (!ids.length || !process.argv[1])
138
+ return undefined;
139
+ const log = join(dir, UPLOAD_LOG);
140
+ const fd = openSync(log, "w");
141
+ try {
142
+ spawn(process.execPath, [process.argv[1], "hook", "upload", pushedUrl, ...ids], { cwd, detached: true, stdio: ["ignore", fd, fd] }).unref();
143
+ }
144
+ finally {
145
+ closeSync(fd);
146
+ }
147
+ return log;
148
+ }
149
+ // The background half of a push: uploads the sessions and markers of the
150
+ // given traces, which the push already chose, with a longer budget.
151
+ async function hookUpload(args, cwd) {
152
+ if (hooksDisabled() || consentFor(cwd) !== true)
153
+ return;
154
+ const [pushedUrl, ...ids] = args.positional.slice(2);
155
+ if (!pushedUrl || !ids.length)
156
+ return;
157
+ const target = uploadTargetFor(cwd, { url: pushedUrl });
158
+ if (!target) {
159
+ warn(UPLOAD_POLICY_ERROR);
160
+ return;
161
+ }
162
+ const dir = stateDir(cwd);
163
+ const markers = readMarkers(dir).filter((marker) => ids.includes(marker.traceId));
164
+ if (!pendingMarkers(markers).length)
165
+ return;
166
+ const stored = usableAuth();
167
+ if (!stored) {
168
+ warn("not signed in; the markers stay pending");
169
+ return;
170
+ }
171
+ try {
172
+ const auth = await freshAuth(stored);
173
+ const client = clientFor(auth, BACKGROUND_BUDGET_MS);
174
+ await client.verifyTarget(target);
175
+ const result = await uploadMarkers(client, target, dir, cwd, repoRoot(cwd) ?? cwd, markers, redactOptions(), consentFor(cwd) === true);
176
+ reportUpload(result, target, warn);
177
+ }
178
+ catch (err) {
179
+ warn(`upload failed, left pending for the next push: ${firstLine(err)}`);
180
+ }
181
+ }
182
+ const REGISTRY_TIMEOUT_MS = 5_000;
183
+ // Rules TraceHub has not heard of yet (setup was offline, or they are from
184
+ // a version before the registry) are sent on push. A failure leaves them
185
+ // pending, quietly: setup already said so.
186
+ async function retryRegistration(token) {
187
+ const store = readConsent(consentFile());
188
+ if (!registrationPending(store))
189
+ return;
190
+ try {
191
+ await registerConsent(tracehubUrl(), token, store, {
192
+ timeoutMs: REGISTRY_TIMEOUT_MS,
193
+ });
194
+ warn("registered your consent with TraceHub");
195
+ }
196
+ catch {
197
+ /* still pending; the next push or setup tries again */
198
+ }
199
+ }
200
+ // A hook never fails the git command that called it.
201
+ export async function cmdHook(args, cwd) {
202
+ try {
203
+ switch (args.positional[1]) {
204
+ case "prepare-commit-msg":
205
+ return hookPrepareCommitMsg(args, cwd);
206
+ case "pre-push":
207
+ return await hookPrePush(args, cwd);
208
+ case "upload":
209
+ return await hookUpload(args, cwd);
210
+ }
211
+ }
212
+ catch (err) {
213
+ warn(`hook error ignored: ${firstLine(err)}`);
214
+ }
215
+ }
@@ -0,0 +1,55 @@
1
+ import { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, readProviders, writeProviders, } from "../../local/providers.js";
2
+ import { PROVIDER_NAME } from "../../protocol/context.js";
3
+ import { flagValue } from "../args.js";
4
+ import { out } from "../io.js";
5
+ import { commandUsage } from "../usage.js";
6
+ function add(args) {
7
+ const name = args.positional[2];
8
+ if (!name || !PROVIDER_NAME.test(name))
9
+ throw new Error("a provider name is [a-z][a-z0-9-]*, 40 characters at most");
10
+ const command = args.rest ?? [];
11
+ if (!command.length)
12
+ throw new Error('the command goes after "--": tracehub providers add <name> -- <command> … {id} …');
13
+ if (!command.some((arg) => arg.includes("{id}")))
14
+ throw new Error('the command needs "{id}" where the conversation id goes');
15
+ const provider = { command };
16
+ const timeout = flagValue(args, "timeout");
17
+ if (timeout !== undefined) {
18
+ const ms = Number(timeout);
19
+ if (!Number.isInteger(ms) || ms < 1 || ms > MAX_TIMEOUT_MS)
20
+ throw new Error(`--timeout is 1 to ${MAX_TIMEOUT_MS} ms`);
21
+ provider.timeoutMs = ms;
22
+ }
23
+ writeProviders({ ...readProviders(), [name]: provider });
24
+ out(`provider ${name}: ${command.join(" ")}`);
25
+ }
26
+ function list() {
27
+ const providers = Object.entries(readProviders());
28
+ if (!providers.length)
29
+ out("no providers");
30
+ for (const [name, p] of providers)
31
+ out(`${name} ${p.command.join(" ")} (${p.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms)`);
32
+ }
33
+ function remove(args) {
34
+ const name = args.positional[2];
35
+ const providers = readProviders();
36
+ if (!name || !providers[name])
37
+ throw new Error(`no provider "${name ?? ""}"`);
38
+ delete providers[name];
39
+ writeProviders(providers);
40
+ out(`removed provider ${name}`);
41
+ }
42
+ export function cmdProviders(args) {
43
+ const sub = args.positional[1];
44
+ if (args.flags["help"] || args.flags["h"] || !sub) {
45
+ out(commandUsage("providers"));
46
+ return;
47
+ }
48
+ if (sub === "add")
49
+ return add(args);
50
+ if (sub === "list")
51
+ return list();
52
+ if (sub === "remove")
53
+ return remove(args);
54
+ throw new Error(`unknown providers command "${sub}"; use add, list or remove`);
55
+ }