tracehub 0.5.7 → 0.5.9

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tracehub CLI
2
2
 
3
- Tracehub has four parts: the **Tracehub CLI** (this package, the `tracehub` command), the **Tracehub API** (a Cloudflare Worker that stores the traces), the **Tracehub web app** (`https://tracehub.aui.dev`, a static preview of the traces behind a commit or pull request, with `.json` twins) and the **Tracehub GitHub App**.
3
+ Tracehub has three parts: the **Tracehub CLI** (this package, the `tracehub` command), the **Tracehub Worker** (the API and web pages, with `.json` twins) and the **Tracehub GitHub App**. One Cloudflare Worker serves the API on `https://assisted-by.aui.dev` and pages on `https://tracehub.aui.dev`, reading storage on every authorized request with no page cache between uploads and reads.
4
4
 
5
5
  Attach the conversations behind coding-agent work (Claude Code, Codex, OpenCode) to git commits: the conversation that asked for the work, the user's and the agent's messages, the files each turn changed, and which turn wrote each line of the diff.
6
6
 
@@ -78,7 +78,7 @@ Everything is computed on the developer's machine, redacted there, checked again
78
78
  Set it up once with `setup` (the other commands are under [Commands](#commands)). Run it in your terminal:
79
79
 
80
80
  ```sh
81
- npx --yes tracehub@0.5.7 setup
81
+ npx --yes tracehub@0.5.9 setup
82
82
  ```
83
83
 
84
84
  Setup is a form of three steps. Each step saves what you chose before the next one starts; cancelling (Ctrl-C) keeps the steps already done.
@@ -89,7 +89,7 @@ Setup is a form of three steps. Each step saves what you chose before the next o
89
89
 
90
90
  It ends with a summary of the account, the allowed rules and the hooks, and what is left to do. Setup needs an interactive terminal; without one it exits 1.
91
91
 
92
- To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.7`, then `tracehub setup`.
92
+ To skip npx on every commit, install it globally instead: `npm install -g tracehub@0.5.9`, then `tracehub setup`.
93
93
 
94
94
  ### Git hooks
95
95
 
@@ -110,7 +110,7 @@ Setup installs global Git hooks: it points the global `core.hooksPath` at `~/.co
110
110
  ### Uninstall
111
111
 
112
112
  ```sh
113
- npx --yes tracehub@0.5.7 uninstall
113
+ npx --yes tracehub@0.5.9 uninstall
114
114
  ```
115
115
 
116
116
  Lists what it removes and asks first (default no); with nothing set up it says so and asks nothing. Then it removes the global Git hooks and restores your previous global `core.hooksPath` setting, deletes the permission rules (`consent.json`) and signs you out (`auth.json`). It asks before deleting the deny list and the current repository's `.git/tracehub` (its markers, including ones not uploaded yet). Other repositories keep their `.git/tracehub`; delete it by hand if you want. Before signing out it asks TraceHub to forget this machine's rules (see [Consent registry](#consent-registry)); when TraceHub can't be reached it says that TraceHub still lists them, and goes on. If the global hooks setting was changed by another tool since setup, uninstall leaves the hooks alone, still removes the rest, and exits 1.
@@ -146,7 +146,7 @@ An allowed repository means: the traces of the agent sessions that ran in it (th
146
146
 
147
147
  The rules are kept in `~/.config/tracehub/consent.json` under normalized GitHub keys: `github.com/owner/*` for an organization, `github.com/owner/repo` for a repository. Every clone and worktree shares them; filesystem paths never identify a rule. A repository's rule wins over its organization's.
148
148
 
149
- - **Older consents.** A consent for all GitHub repositories (`github.com/*`, from `consent --all`) no longer allows anything: the hooks ignore it, and setup removes it from the file and says so. Add an organization or repository rule instead. A repository refusal from `consent --no` still blocks that repository; setup lists it as declined, and revoking it removes it.
149
+ - A rule for all GitHub repositories (`github.com/*`) allows no uploads; setup removes it from the file. Add an organization or repository rule instead. A repository refusal blocks that repository until it is revoked in setup.
150
150
  - Rules are separate from upload eligibility and the hooks. A rule does not authorize non-GitHub origins or bypass the current **assistant-ui-only** ownership policy, GitHub App installation, repository access, or sign-in checks. A rule for another organization is stored but uploads nothing in this release. It does not make traces public.
151
151
 
152
152
  | rule for the repository | a commit with an active session |
@@ -166,11 +166,11 @@ TraceHub keeps a copy of your rules (`_consent/users/<your id>`).
166
166
 
167
167
  ## How it works
168
168
 
169
- 1. **Commit.** `prepare-commit-msg` finds the sessions of the commit (see Discovery). If the message has no `Assisted-by` trailer yet, it uses a new 16-hex trace id and adds the trailer once at least one session's marker is recorded; a commit whose sessions are all missing from this machine gets no trailer. For each session found it appends a marker to `.git/tracehub/markers.jsonl` (in the repository's common git directory, so a linked worktree's markers outlive the worktree): `{traceId, session, line, ts, context?, file, committer?, uploaded}`, where `line` is the number of complete lines the session file had, `context` the references of `TRACEHUB_CONTEXT`, `file` the session file it was found in, and `committer` that the session made the commit with a call of its own (see Discovery). The marker never leaves the machine. Merge and squash commits are skipped.
170
- 2. **Amend, rebase, squash.** The message keeps its trailer, so the commit keeps its trace id. A new marker for the same trace id and session replaces the old one.
169
+ 1. **Commit.** `prepare-commit-msg` finds the sessions of the commit (see Discovery). If the message has no `Assisted-by` trailer yet, it uses a new 16-hex trace id and adds the trailer once at least one session's marker is recorded; a commit whose sessions are all missing from this machine gets no trailer. For each session found it appends a marker to `.git/tracehub/markers.jsonl` (in the repository's common git directory, so a linked worktree's markers outlive the worktree): `{traceId, session, line, ts, context?, file?, committer?, commit?, uploaded}`, where `line` is the number of complete lines the session file had, `context` the references of `TRACEHUB_CONTEXT`, `file` the session file it was found in, `committer` that the session made the commit with a call of its own, and `commit` the SHA of a backfilled commit whose message does not name the trace (see Discovery). The marker never leaves the machine. Merge and squash commits are skipped.
170
+ 2. **Amend, rebase, squash.** The message keeps its trailer, so the commit keeps its trace id. A new marker for the same trace id and session replaces the old one. A squash merge on GitHub runs no hook and keeps no trailer by itself; whoever merges writes the body. One line, `Assisted-by: https://tracehub.aui.dev/pr/<owner>/<repo>/<number>`, stands for every trace of the pull request's commits: the commit's page and its check resolve it through the pull request.
171
171
  3. **Push.** `pre-push` reads Git's ref updates and uploads only the traces of commits being pushed. New branches exclude commits already known on that remote. Deletions upload nothing; an unavailable remote base leaves traces pending with a recovery warning. For each pending marker the CLI builds the trace (below) from the marker's `file`, or the session's file wherever the push's environment keeps it when that one is gone, so a push from a plain terminal uploads what an agent with its own `CLAUDE_CONFIG_DIR` committed; fetches its context conversations from their providers and `PUT`s it; each success is recorded before the next. A later push also retries the pending traces of earlier commits in its history. When the 15 s run out, the push says so and a detached `tracehub hook upload` goes on with the same traces for up to 10 minutes, writing to `.git/tracehub/upload.log`.
172
172
  4. **Pull request.** The GitHub App receives the `pull_request` event, reads the trace ids from the commit messages, and writes a link at the bottom of the description, between `<!-- tracehub:start -->` and `<!-- tracehub:end -->`: an "Agent traces" badge, next to Rupic's "Track in Rupic" badge when there is one. A pull request with attached context gets the link too.
173
- 5. **Reading.** The badge links to `/pr/<owner>/<repo>/<number>`: the intent and effort at a glance (first prompt, wall-clock time, prompts, commits, agents), then one timeline of the context conversations and the sessions of its commits, each message clamped to three lines, subagent runs folded to one line. A trace is at `/t/<owner>/<repo>/<trace id>`, a commit's traces at `/c/<owner>/<repo>/<sha>`. Add `.json` to any of them for the data (sign-in cookie or `Authorization: Bearer <token>` with the token `tracehub setup` keeps). The pages are rendered when their data changes and served from the cache.
173
+ 5. **Reading.** The badge links to `/pr/<owner>/<repo>/<number>`: the intent and effort at a glance (first prompt, wall-clock time, prompts, commits, agents), then its context conversations and the sessions of its commits, listed in a rail and read one at a time, each in time order with the commits it made; each message is clamped to three lines and subagent runs fold to one line. A trace is at `/t/<owner>/<repo>/<trace id>`, a commit's traces at `/c/<owner>/<repo>/<sha>`. Add `.json` to any of them for the data (sign-in cookie or `Authorization: Bearer <token>` with the token `tracehub setup` keeps). Each authorized request renders the page from storage.
174
174
  6. **Without a pull request.** A push prints a link per commit it marked, `/t/<owner>/<repo>/<trace id>`.
175
175
 
176
176
  ### What a trace holds
@@ -182,6 +182,7 @@ The trace of a session at a commit, built from the session's file up to the mark
182
182
  - **Turns.** A turn starts at each user prompt; its messages are the user's (the prompt, then any steering) and the agent's text replies. The replies after the commit that finish the commit's turn are included; the next prompt is not.
183
183
  - **Changes.** Each turn lists the files its edit tools changed, as paths in the repository with lines added and removed. Edits outside the repository are left out.
184
184
  - **Runs.** A subagent (a Claude Code subagent, a Codex sub-thread, an OpenCode task) is a run under the turn whose call launched it, else under the last turn that started before it did. A run has its own turns: the prompt the parent gave it, its replies and its changes.
185
+ - **Delegated sessions.** A session or subagent whose output contains a line `<agent>-session: <id>` (where agent is claude, codex or opencode) shows that session's turns as a run inside it when the session is on the uploading machine.
185
186
  - **The sourcemap** of the commit's added lines (see [The sourcemap](#the-sourcemap)).
186
187
  - **Context conversations** the session's first message, its subagents' briefs or the marker name (see [Context conversations](#context-conversations)).
187
188
  - The title Claude Code gave the session, the model, and when the commit was made.
@@ -341,6 +342,7 @@ The agent's own file is never changed. The `pre-push` hook reports what it maske
341
342
  | `jwt` | `eyJ….….…` |
342
343
  | `authorization_header`, `bearer_token`, `basic_auth` | what follows `Authorization:`, `Bearer`, `Basic` |
343
344
  | `keyed_assignment` | the value of `<name>_key=`, `token:`, `password=`, `SECRET=` and the like |
345
+ | `json_secret_assignment` | the quoted value of a JSON property whose name contains `password`, `secret`, `token`, `api_key`, `apikey`, `private_key` or `credential` |
344
346
  | `long_hex` | 64 or more hex characters |
345
347
  | `keyed_hex` | 32 to 63 hex characters with `token`, `secret`, `key`, `password`, `bearer`, `auth` or `api` in the 40 characters before them; a bare git sha is left alone |
346
348
  | `high_entropy` | 32 or more characters of `[A-Za-z0-9_\-+/=.]` with two digits or more, two character classes or more, and an entropy above 3.8 bits per character; not hex, a UUID, a hostname or a path |
@@ -354,81 +356,11 @@ The agent's own file is never changed. The `pre-push` hook reports what it maske
354
356
 
355
357
  Messages are asked in windows of 4000 characters; a window that is sensitive is asked again message by message. The redacted messages leave the Tracehub API for TypeSafe's API. Without `TYPESAFE_API_KEY` the Tracehub API skips steps 2 to 4.
356
358
 
357
- ### Translation
358
-
359
- Pages show a message written in another language in English, with "Translated from <language> · Show original" to read it as written. The stored trace and context keep the original; the `.json` twins carry both (`translation: { from, text }` beside `text`).
360
-
361
- - Which messages: a count of the prose's letters by script (code, links, paths and identifiers left out). A message mostly in Han, kana, Hangul, Cyrillic, Arabic, Hebrew, Greek, Thai or Devanagari is translated; English never reaches the model. Latin-script languages (Spanish, German…) are not detected.
362
- - How: Cloudflare Workers AI (`@cf/qwen/qwen3.8-27b`), called by the Tracehub API Worker on the messages it already stores, after the redaction and the sensitivity check above; withheld messages are never sent. Code blocks, inline code, URLs, paths and identifiers are replaced by tokens before the model sees the text and put back after; a translation that loses one is dropped.
363
- - When: as a page's data is read for rendering (after each upload, and for traces stored before translation existed, on their next render). Each text is translated once and cached in the bucket under `_translations/<sha256 of model and text>`; a changed message is translated again.
364
- - Limits: messages over 8000 characters are not translated; at most 100 model calls per read, 4 at a time.
365
-
366
359
  ### Deny list
367
360
 
368
361
  Literals in `~/.config/tracehub/deny.txt`, one per line, are always redacted. Edit the file by hand (keep it mode `0600`); lines under 6 characters are ignored. The file holds the literals themselves, so treat it like the secrets.
369
362
 
370
- ## Tracehub API
371
-
372
- `tracehub/` is a Cloudflare Worker over an R2 bucket; `tracehub/README.md` says how to deploy it. GitHub signs the users in and says who may push to a repository.
373
-
374
- | route | does |
375
- | --- | --- |
376
- | `PUT /repos/:owner/:repo/traces/:trace/sessions/:name` | stores a session's trace at a commit, replacing the one there |
377
- | `PUT /repos/:owner/:repo/pulls/:number/context` | attaches context conversations to a pull request (`{context: [...]}`), merged into the uploader's by conversation and message id |
378
- | `DELETE /repos/:owner/:repo/pulls/:number/context?ref=<provider>:<id>` | detaches the conversations (`ref` repeated) from every uploader's document; answers `{removed}`, 404 when none was attached |
379
- | `PUT /repos/:owner/:repo/commits/:sha/traces/:trace` | links an uploaded trace to a commit whose message does not name it (a backfill); only who uploaded one of its sessions may; answers `{sha, traceId, pulls}`, 404 without a session, 503 when the GitHub App is not configured |
380
- | `POST /repos/:owner/:repo/pulls/:number/check` | recomputes the pull request's head check; answers `{submitted: true}` (bearer, push access), 503 when the GitHub App is not configured |
381
- | `PUT /consent` | registers a machine's permission rules for the signed-in user; `rules: []` forgets the machine |
382
- | `GET /login`, `/logout`, `/api/auth/callback` | browser sign-in (through the web app) |
383
- | `POST /github/webhook` | the GitHub App's webhook |
384
- | `GET /healthz` | `{ok: true}` |
385
-
386
- Bucket keys: `<owner>/<repo>/traces/<trace id>/<session name>` (an uploaded session, JSON), `<owner>/<repo>/commits/<trace id>.json` (the trace document) and `<owner>/<repo>/context/<number>/<user id>` (one uploader's context conversations for a pull request, JSON).
387
-
388
- A trace or context is shown to who uploaded it and to the repository's maintainers (GitHub write, maintain or admin access); everyone else sees nothing.
389
-
390
- The `PUT` routes and the pull request's `/check` route take `Authorization: Bearer <access token of the GitHub user>` with push access to the repository. The web app's pages (`/t`, `/c`, `/pr`, each with a `.json` twin) take the cookie of the browser sign-in or a bearer token GitHub issued to TraceHub's App, and send a signed-out browser to `/login`; `tracehub/README.md` has the page list and the JSON schemas.
391
-
392
- ### GitHub App (once)
393
-
394
- The App of the deployed Tracehub API exists; the Tracehub API reads its key from the bucket, `_config/github-app.json` (`{appId, pem, webhookSecret}`).
395
-
396
- For another deployment, create an App in the GitHub organization:
397
-
398
- - Permissions: Pull requests: write, Checks: write (the TraceHub traces check), Contents: read, Metadata: read, Merge queues: read. Events: Pull request, Push, Merge group, Check run, Check suite. Webhook `<tracehub>/github/webhook`.
399
- - Callback URL `<tracehub>/api/auth/callback`, for the browser sign-in.
400
- - Device flow enabled, for the sign-in of `tracehub setup`.
401
- - A client secret, for the browser sign-in.
402
-
403
- Install it on the repositories. An existing App installation must accept the new Merge queues: read permission. Set its client id as `GITHUB_CLIENT_ID` in `tracehub/wrangler.jsonc` and as `TRACEHUB_GITHUB_CLIENT_ID` for the CLI, and store its values as secrets; the three of the key win over the bucket:
404
-
405
- ```sh
406
- cd tracehub
407
- npx wrangler secret put GITHUB_CLIENT_SECRET
408
- printf %s "<app id>" | npx wrangler secret put GITHUB_APP_ID
409
- npx wrangler secret put GITHUB_APP_PRIVATE_KEY < <app>.private-key.pem
410
- printf %s "<webhook secret>" | npx wrangler secret put GITHUB_WEBHOOK_SECRET
411
- ```
412
-
413
- ### The TraceHub traces check
414
-
415
- The App reports a check run named **TraceHub traces** on the head of every pull request of `assistant-ui` repositories, and on commits that have a known trace (an uploaded session marked by a trace id the commit message names, or linked to the commit by `tracehub backfill`).
416
-
417
- - First party: the pull request's author is an organization member or collaborator, or has write access. Bots (`[bot]` logins, `type: Bot`) and outside contributors are exempt.
418
- - **Success** when at least one of the pull request's current commits has a known trace with content: a session that shows at least one prompt or reply with text, in its turns or a subagent's. A session whose messages are all empty or withheld is empty, and a trace of only empty sessions does not count. The output lists each trace with content with a link to its TraceHub page, its agents and its number of sessions with content; the details link goes to the pull request's TraceHub page.
419
- - **Success** also when no commit has one but the pull request has context fetched from a provider attached (`tracehub context add --pr <n> <provider>:<id>`): at least one conversation with at least one message with text, from any uploader; withheld messages do not count. Conversations pasted from a file (`--from`, ref `manual:…`) stay on the page but never pass the check alone. The output says it passed on the attached context, with the number of conversations and a link to the pull request's TraceHub page, which the details link also opens.
420
- - **Skipped** when every pull request headed at the commit is exempt and has neither a trace nor context. GitHub treats this as passing for a required check.
421
- - **Failure** when a first-party pull request has neither. The title says what was found: `No trace found`, `<n> traces found, all empty` (the summary lists them), or `Only pasted context found`. The output links to the public npm package and says how to fix it: run `npx --yes tracehub setup`, then push a new commit made in an agent session (Claude Code, Codex, OpenCode), or, for commits made before that, run `npx --yes tracehub backfill --pr <n>` (see Backfill). A pull request without agent work passes once the conversation that asked for it is attached from its provider with `npx --yes tracehub context add --pr <n> <provider>:<id>`. No comment is posted.
422
- - Any other commit gets a success when it has a known trace with content itself: on a push, and when an upload attaches a trace to a commit TraceHub has seen.
423
- - A trace uploaded later updates the check on the pull request heads and commits the index knows for the trace, so a failure turns into a success.
424
- - Attaching context (`PUT …/pulls/<n>/context`) or detaching it (`DELETE`) runs the check on the pull request's head again right away: a failure turns into a success, and detaching the last conversation can turn it back into a failure.
425
- - An unchanged check is not written again; a changed one updates the same check run.
426
- - **Re-run** on GitHub (`check_run` or `check_suite` with action `rerequested`) lists the pull request's commits again and writes a new check run on the head, changed or not.
427
- - R2 calls it turns away for a moment (10058 too many reads or writes of one object, 10001, 10043) are tried again a few times with a short backoff, so a busy object does not drop the job that updates the check.
428
- - On `merge_group` with action `checks_requested`, the App refreshes the pull request named by the queue ref and mirrors its stored head check onto the merge-group commit, including its conclusion, title, summary and details link. Queue branch pushes are ignored. A missing stored output is logged and no queue check is written.
429
- - `POST /repos/:owner/:repo/pulls/:number/check` recomputes the head check for a pull request opened before the App handled it. Push access is required.
430
-
431
- To require the check, add **TraceHub traces** from the **TraceHub App** as a required status check in the branch's ruleset. The `merge_group` mirror covers the merge queue, including squash merges.
363
+ For Worker routes, GitHub App setup, check behavior and translation, see [the Worker documentation](tracehub/README.md).
432
364
 
433
365
  ## Trying it end to end
434
366
 
@@ -436,7 +368,7 @@ Do not try it with the session you are working in: what is uploaded stays in the
436
368
 
437
369
  ```sh
438
370
  gh repo create assistant-ui/tracehub-playground --private --clone && cd tracehub-playground
439
- npx --yes tracehub@0.5.7 setup # allow this repository, install the hooks
371
+ npx --yes tracehub@0.5.9 setup # allow this repository, install the hooks
440
372
 
441
373
  # open a fresh agent session in this directory, ask it for something harmless
442
374
  export TRACEHUB_ID=claude:<throwaway session id>
@@ -459,13 +391,14 @@ Needs Node.js 26.13.0 (pinned in `.node-version`).
459
391
  Development on `main` is allowed; feature branches and pull requests are optional. Preserve other contributors' changes and validate before pushing. Use a separate checkout when the working tree contains unrelated edits.
460
392
 
461
393
  ```sh
462
- npm run format:fix && npm run typecheck && npm test
463
- cd tracehub && npm test
394
+ pnpm install
395
+ pnpm run format:fix && pnpm run typecheck && pnpm test
396
+ cd tracehub && pnpm test
464
397
  ```
465
398
 
466
- Tests are in `test/` and `tracehub/test/`, fixtures in `fixtures/`, and run on Vitest; `npm run test:coverage` also checks the coverage thresholds in `vitest.config.ts`. The end-to-end tests run the built CLI against the real Tracehub API over an in-memory bucket (`test/support/fakeTracehub.ts`); nothing in the tests reads a real session. The CLI and the fake Tracehub run outside Vitest, so `npm test` compiles them to `dist-test` first. The test setup file clears the agent variables (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `TRACEHUB_ID`) a suite run by an agent inherits.
399
+ Tests are in `test/` and `tracehub/test/`, fixtures in `fixtures/`, and run on Vitest; `pnpm run test:coverage` also checks the coverage thresholds in `vitest.config.ts`. The end-to-end tests run the built CLI against the real Tracehub API over an in-memory bucket (`test/support/fakeTracehub.ts`); nothing in the tests reads a real session. The CLI and the fake Tracehub run outside Vitest, so `pnpm test` compiles them to `dist-test` first. The test setup file clears the agent variables (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `TRACEHUB_ID`) a suite run by an agent inherits.
467
400
 
468
- The CLI is published to npm as [`tracehub`](https://www.npmjs.com/package/tracehub). `npm pack` builds a fresh `dist` (`prepack`) and ships only `dist`, `README.md` and `package.json`. A clone needs `npm run build` after pulling; `npm install` doesn't build.
401
+ The CLI is published to npm as [`tracehub`](https://www.npmjs.com/package/tracehub). `pnpm pack` builds a fresh `dist` (`prepack`) and ships only `dist`, `README.md` and `package.json`. A clone needs `pnpm run build` after pulling; `pnpm install` doesn't build.
469
402
 
470
403
  A release is a tag:
471
404
 
package/dist/cli/args.js CHANGED
@@ -7,6 +7,10 @@ export function parseArgs(argv) {
7
7
  const arg = argv[i];
8
8
  if (arg === "--")
9
9
  return { positional, flags, rest: argv.slice(i + 1) };
10
+ if (arg === "-h") {
11
+ flags["help"] = true;
12
+ continue;
13
+ }
10
14
  if (!arg.startsWith("--")) {
11
15
  positional.push(arg);
12
16
  continue;
@@ -26,3 +30,14 @@ export function flagValue(args, name) {
26
30
  const value = args.flags[name];
27
31
  return typeof value === "string" ? value : undefined;
28
32
  }
33
+ export function prOf(args, required = false) {
34
+ const raw = flagValue(args, "pr");
35
+ if (raw === undefined && !required)
36
+ return undefined;
37
+ const pr = Number(raw);
38
+ if (!Number.isSafeInteger(pr) || pr < 1)
39
+ throw new Error(required
40
+ ? '--pr <number> is required; see "tracehub context --help"'
41
+ : "--pr <number> must be a pull request number");
42
+ return pr;
43
+ }
@@ -1,36 +1,26 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
- import { basename, dirname, join } from "node:path";
3
- import { freshAuth } from "../../client/auth.js";
2
+ import { basename, dirname } from "node:path";
4
3
  import { pullCommits } from "../../client/github.js";
5
- import { traceUploaded, tracehubUrl, } from "../../client/tracehub.js";
4
+ import { traceUploaded, webUrl } from "../../client/tracehub.js";
6
5
  import { uploadMarkers } from "../../client/upload.js";
7
6
  import { sameTarget, targetOfUploadRemotes, UPLOAD_POLICY_ERROR, } from "../../client/uploadPolicy.js";
8
7
  import { addedLines, git, remoteUrls, repoRoot, tryGit, } from "../../git/git.js";
9
8
  import { appendMarkers, readMarkers, } from "../../git/markers.js";
10
- import { newTraceId, traceIds } from "../../git/trailers.js";
9
+ import { newTraceId } from "../../git/trailers.js";
10
+ import { traceIds } from "../../protocol/trailers.js";
11
11
  import { candidateOf, chosen, commitTimeMs, rankMatches, } from "../../local/backfill.js";
12
12
  import { claudeIdFromFile, ranInside, walkCodexFiles, } from "../../local/discover.js";
13
- import { fileEntry, firstLineOf, listDir } from "../../local/files.js";
13
+ import { firstLineOf, walkClaudeTranscripts } from "../../local/files.js";
14
14
  import { completeLines } from "../../local/lines.js";
15
15
  import { listOpencodeSessions, opencodeLines } from "../../local/opencode.js";
16
16
  import { claudeProjectsDir, home, opencodeDb } from "../../local/paths.js";
17
17
  import { formatSessionRef, parseSessionRef, } from "../../protocol/sessionRef.js";
18
18
  import { codexSessionMeta } from "../../transcript/parseCodex.js";
19
- import { flagValue } from "../args.js";
19
+ import { flagValue, prOf } from "../args.js";
20
20
  import { out, warn } from "../io.js";
21
- import { clientFor, redactOptions, reportUpload, usableAuth, } from "../remote.js";
22
- import { consentFor, stateDir, uploadTargetFor } from "../repo.js";
23
- import { commandUsage } from "../usage.js";
21
+ import { signedInClient, redactOptions, reportUpload } from "../remote.js";
22
+ import { requireConsent, stateDir, uploadTargetFor } from "../repo.js";
24
23
  const HOUR_MS = 3600_000;
25
- function prOf(args) {
26
- const raw = flagValue(args, "pr");
27
- if (raw === undefined)
28
- return undefined;
29
- const pr = Number(raw);
30
- if (!Number.isSafeInteger(pr) || pr < 1)
31
- throw new Error("--pr <number> must be a pull request number");
32
- return pr;
33
- }
34
24
  // The commit as git has it; undefined when this clone does not have it.
35
25
  function commitFacts(cwd, sha) {
36
26
  const head = tryGit(["show", "-s", "--format=%H%x00%P%x00%s%x00%at%x00%ct", sha], { cwd });
@@ -112,35 +102,19 @@ function candidates(sinceMs, hints) {
112
102
  return "";
113
103
  }
114
104
  };
115
- const base = claudeProjectsDir();
116
- for (const project of listDir(base)) {
117
- for (const name of listDir(join(base, project))) {
118
- const path = join(base, project, name);
119
- if (name.endsWith(".jsonl")) {
120
- const id = claudeIdFromFile(name);
121
- const entry = fileEntry(path);
122
- if (!id || !entry || entry.mtimeMs < sinceMs)
123
- continue;
124
- const text = read(path);
125
- if (!mentions(text))
126
- continue;
127
- found.push(candidateOf({ agent: "claude", id }, path, completeLines(text)));
128
- continue;
129
- }
130
- const dir = join(path, "subagents");
131
- for (const sub of listDir(dir)) {
132
- if (!/^agent-[A-Za-z0-9_-]+\.jsonl$/.test(sub))
133
- continue;
134
- const file = join(dir, sub);
135
- const entry = fileEntry(file);
136
- if (!entry || entry.mtimeMs < sinceMs)
137
- continue;
138
- const text = read(file);
139
- if (!mentions(text))
140
- continue;
141
- found.push(candidateOf({ agent: "claude", id: basename(sub, ".jsonl") }, file, completeLines(text), { sidechain: true, parent: `claude:${name}` }));
105
+ for (const entry of walkClaudeTranscripts(claudeProjectsDir())) {
106
+ const id = entry.parent ? entry.id : claudeIdFromFile(entry.file);
107
+ if (!id || entry.mtimeMs < sinceMs)
108
+ continue;
109
+ const text = read(entry.file);
110
+ if (!mentions(text))
111
+ continue;
112
+ found.push(candidateOf({ agent: "claude", id }, entry.file, completeLines(text), entry.parent
113
+ ? {
114
+ sidechain: true,
115
+ parent: `claude:${basename(entry.parent, ".jsonl")}`,
142
116
  }
143
- }
117
+ : {}));
144
118
  }
145
119
  for (const { file } of walkCodexFiles(sinceMs)) {
146
120
  const meta = codexSessionMeta(firstLineOf(file));
@@ -189,12 +163,9 @@ async function backfill(args, cwd) {
189
163
  throw new Error(`--session: "${s}" is not <claude|codex|opencode>:<id>`);
190
164
  return formatSessionRef(ref);
191
165
  });
192
- if (!dryRun && consentFor(cwd) !== true)
193
- throw new Error(`no permission rule allows uploads for ${target.owner}/${target.repo}; run "tracehub setup"`);
194
- const stored = usableAuth();
195
- if (!stored)
196
- throw new Error('not signed in; run "tracehub setup"');
197
- const auth = await freshAuth(stored);
166
+ if (!dryRun)
167
+ requireConsent(cwd, target);
168
+ const { client, auth } = await signedInClient();
198
169
  // The commits and their messages, and the pull request's head branch.
199
170
  let branch;
200
171
  let listed;
@@ -293,7 +264,6 @@ async function backfill(args, cwd) {
293
264
  return;
294
265
  }
295
266
  appendMarkers(dir, markers);
296
- const client = clientFor(auth);
297
267
  const result = await uploadMarkers(client, target, dir, cwd, root, markers, redactOptions(), true);
298
268
  reportUpload(result, target, out);
299
269
  const linked = new Map();
@@ -306,15 +276,11 @@ async function backfill(args, cwd) {
306
276
  if (pr && linked.size) {
307
277
  await client.checkPull(target, pr);
308
278
  out(`asked TraceHub to check ${target.owner}/${target.repo}#${pr} again`);
309
- out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
279
+ out(`${webUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
310
280
  }
311
281
  if (result.failed)
312
282
  throw new Error(`upload incomplete: ${result.failed.error}`);
313
283
  }
314
284
  export async function cmdBackfill(args, cwd) {
315
- if (args.flags["help"] || args.flags["h"]) {
316
- out(commandUsage("backfill"));
317
- return;
318
- }
319
285
  await backfill(args, cwd);
320
286
  }
@@ -1,15 +1,13 @@
1
1
  import { readFileSync } from "node:fs";
2
- import { freshAuth } from "../../client/auth.js";
3
- import { tracehubUrl } from "../../client/tracehub.js";
2
+ import { webUrl } from "../../client/tracehub.js";
4
3
  import { UPLOAD_POLICY_ERROR } from "../../client/uploadPolicy.js";
5
4
  import { fetchContext, manualConversations } from "../../local/providers.js";
6
5
  import { mergeConversations, parseContextRef, } from "../../protocol/context.js";
7
6
  import { formatFindings, redactValue } from "../../redact/redact.js";
8
- import { flagValue } from "../args.js";
7
+ import { flagValue, prOf } from "../args.js";
9
8
  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";
9
+ import { signedInClient, redactOptions } from "../remote.js";
10
+ import { requireConsent, uploadTargetFor } from "../repo.js";
13
11
  // stdin read as a stream: a pipe can be non-blocking, which readFileSync(0)
14
12
  // answers with EAGAIN.
15
13
  async function readStdin() {
@@ -18,12 +16,6 @@ async function readStdin() {
18
16
  chunks.push(chunk);
19
17
  return Buffer.concat(chunks).toString("utf8");
20
18
  }
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
19
  // The conversations to attach: from their providers or the file, merged,
28
20
  // redacted.
29
21
  async function conversationsOf(args, allowed) {
@@ -47,13 +39,12 @@ async function conversationsOf(args, allowed) {
47
39
  return mergeConversations(lists);
48
40
  }
49
41
  async function add(args, cwd) {
50
- const pr = prOf(args);
42
+ const pr = prOf(args, true);
51
43
  const target = uploadTargetFor(cwd);
52
44
  if (!target)
53
45
  throw new Error(UPLOAD_POLICY_ERROR);
54
46
  // 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"`);
47
+ requireConsent(cwd, target);
57
48
  const redacted = redactValue(await conversationsOf(args, true), redactOptions());
58
49
  const context = redacted.value;
59
50
  if (redacted.findings.length)
@@ -65,21 +56,18 @@ async function add(args, cwd) {
65
56
  out(JSON.stringify(context, null, 2));
66
57
  return;
67
58
  }
68
- const stored = usableAuth();
69
- if (!stored)
70
- throw new Error('not signed in; run "tracehub setup"');
71
- const client = clientFor(await freshAuth(stored));
59
+ const { client } = await signedInClient();
72
60
  const result = await client.putContext(target, pr, context);
73
61
  if (result.withheld)
74
62
  warn(`tracehub withheld ${result.withheld} message(s) that look sensitive`);
75
63
  out(`attached ${context.length} conversation(s), ${count} message(s), to ${where}`);
76
- out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
64
+ out(`${webUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
77
65
  }
78
66
  // Detaches conversations from the pull request: the uploader's or, for a
79
67
  // maintainer, anyone's. Nothing is fetched or uploaded, so no permission
80
68
  // rule is needed; the API checks push access as it does for add.
81
69
  async function remove(args, cwd) {
82
- const pr = prOf(args);
70
+ const pr = prOf(args, true);
83
71
  const refs = [...new Set(args.positional.slice(2))];
84
72
  if (!refs.length)
85
73
  throw new Error("name a conversation to remove (<provider>:<id>)");
@@ -90,23 +78,16 @@ async function remove(args, cwd) {
90
78
  if (!target)
91
79
  throw new Error(UPLOAD_POLICY_ERROR);
92
80
  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));
81
+ const { client } = await signedInClient();
97
82
  const { removed } = await client.deleteContext(target, pr, refs);
98
83
  for (const ref of refs)
99
84
  if (!removed.includes(ref))
100
85
  warn(`${ref} is not attached to ${where}`);
101
86
  out(`removed ${removed.length} conversation(s) from ${where}`);
102
- out(`${tracehubUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
87
+ out(`${webUrl()}/pr/${target.owner}/${target.repo}/${pr}`);
103
88
  }
104
89
  export async function cmdContext(args, cwd) {
105
90
  const sub = args.positional[1];
106
- if (args.flags["help"] || args.flags["h"] || !sub) {
107
- out(commandUsage("context"));
108
- return;
109
- }
110
91
  if (sub === "add")
111
92
  return add(args, cwd);
112
93
  if (sub === "remove")
@@ -4,20 +4,21 @@ import { join } from "node:path";
4
4
  import { freshAuth } from "../../client/auth.js";
5
5
  import { readConsent } from "../../client/consent.js";
6
6
  import { registerConsent, registrationPending } from "../../client/registry.js";
7
- import { tracehubUrl } from "../../client/tracehub.js";
7
+ import { tracehubUrl, webUrl } from "../../client/tracehub.js";
8
8
  import { consentFile } from "../../local/paths.js";
9
9
  import { firstLine } from "../../client/errors.js";
10
10
  import { uploadMarkers } from "../../client/upload.js";
11
11
  import { UPLOAD_OWNER, UPLOAD_POLICY_ERROR, } from "../../client/uploadPolicy.js";
12
12
  import { git, pushedTraceIds, repoRoot, tracesInPushedHistory, } from "../../git/git.js";
13
13
  import { pendingMarkers, readMarkers, recordMarkers, } from "../../git/markers.js";
14
- import { interpretTrailersArgs, newTraceId, shouldSkipCommit, traceIds, } from "../../git/trailers.js";
14
+ import { interpretTrailersArgs, hooksDisabled, newTraceId, shouldSkipCommit, } from "../../git/trailers.js";
15
+ import { traceIds } from "../../protocol/trailers.js";
15
16
  import { formatContextRef, parseContextRef } from "../../protocol/context.js";
16
17
  import { formatSessionRef } from "../../protocol/sessionRef.js";
17
18
  import { ENV_CONTEXT, ENV_SESSION_ID } from "../../local/paths.js";
18
19
  import { warn } from "../io.js";
19
20
  import { BACKGROUND_BUDGET_MS, clientFor, commitCount, pushBudgetMs, ranOutOfTime, reportUpload, redactOptions, usableAuth, } from "../remote.js";
20
- import { consentFor, hooksDisabled, pushTargetFor, resolveSessions, stateDir, uploadTargetFor, } from "../repo.js";
21
+ import { consentFor, pushTargetFor, resolveSessions, stateDir, uploadTargetFor, } from "../repo.js";
21
22
  // The trailer names the commit's sessions on tracehub, so a message that
22
23
  // already carries one (amend, rebase, cherry-pick, a squash folding earlier
23
24
  // messages) keeps it, and the markers recorded under it stay with the commit.
@@ -53,7 +54,7 @@ function hookPrepareCommitMsg(args, cwd) {
53
54
  return;
54
55
  // A trailer without a marker would link to a trace nothing ever uploads.
55
56
  if (missing.length < sessions.length)
56
- git(interpretTrailersArgs(target, id, messageFile), { cwd });
57
+ git(interpretTrailersArgs(target, id, messageFile, webUrl()), { cwd });
57
58
  else
58
59
  warn("no trace attached to this commit");
59
60
  }
@@ -87,7 +88,6 @@ async function hookPrePush(args, cwd) {
87
88
  warn(UPLOAD_POLICY_ERROR);
88
89
  return;
89
90
  }
90
- const { target } = push;
91
91
  const dir = stateDir(cwd);
92
92
  const input = process.stdin.isTTY ? "" : readFileSync(0, "utf8");
93
93
  if (!input.trim()) {
@@ -116,23 +116,7 @@ async function hookPrePush(args, cwd) {
116
116
  }
117
117
  return;
118
118
  }
119
- try {
120
- const auth = await freshAuth(stored);
121
- await retryRegistration(auth.accessToken);
122
- const client = clientFor(auth, pushBudgetMs());
123
- await client.verifyPush(push);
124
- const result = await uploadMarkers(client, target, dir, cwd, repoRoot(cwd) ?? cwd, markers, redactOptions(), consentFor(cwd) === true);
125
- // A big session can take longer than a push waits. The rest goes on in
126
- // the background, so a commit whose branch is never pushed again (a
127
- // squash-merged pull request) still gets its trace.
128
- const log = ranOutOfTime(result)
129
- ? continueInBackground(cwd, dir, pushedUrl, result.skipped)
130
- : undefined;
131
- reportUpload(result, target, warn, log);
132
- }
133
- catch (err) {
134
- warn(`upload failed, left pending for the next push: ${firstLine(err)}`);
135
- }
119
+ await uploadPush(cwd, dir, push, markers, stored, pushBudgetMs(), pushedUrl);
136
120
  }
137
121
  const UPLOAD_LOG = "upload.log";
138
122
  // Starts `tracehub hook upload` for the traces of these markers, detached,
@@ -164,7 +148,6 @@ async function hookUpload(args, cwd) {
164
148
  warn(UPLOAD_POLICY_ERROR);
165
149
  return;
166
150
  }
167
- const { target } = push;
168
151
  const dir = stateDir(cwd);
169
152
  const markers = readMarkers(dir).filter((marker) => ids.includes(marker.traceId));
170
153
  if (!pendingMarkers(markers).length)
@@ -174,16 +157,7 @@ async function hookUpload(args, cwd) {
174
157
  warn("not signed in; the markers stay pending");
175
158
  return;
176
159
  }
177
- try {
178
- const auth = await freshAuth(stored);
179
- const client = clientFor(auth, BACKGROUND_BUDGET_MS);
180
- await client.verifyPush(push);
181
- const result = await uploadMarkers(client, target, dir, cwd, repoRoot(cwd) ?? cwd, markers, redactOptions(), consentFor(cwd) === true);
182
- reportUpload(result, target, warn);
183
- }
184
- catch (err) {
185
- warn(`upload failed, left pending for the next push: ${firstLine(err)}`);
186
- }
160
+ await uploadPush(cwd, dir, push, markers, stored, BACKGROUND_BUDGET_MS);
187
161
  }
188
162
  const REGISTRY_TIMEOUT_MS = 5_000;
189
163
  // Rules TraceHub has not heard of yet (setup was offline, or they are from
@@ -219,3 +193,20 @@ export async function cmdHook(args, cwd) {
219
193
  warn(`hook error ignored: ${firstLine(err)}`);
220
194
  }
221
195
  }
196
+ async function uploadPush(cwd, dir, push, markers, stored, budgetMs, pushedUrl) {
197
+ try {
198
+ const auth = await freshAuth(stored);
199
+ if (pushedUrl)
200
+ await retryRegistration(auth.accessToken);
201
+ const client = clientFor(auth, budgetMs);
202
+ await client.verifyPush(push);
203
+ const result = await uploadMarkers(client, push.target, dir, cwd, repoRoot(cwd) ?? cwd, markers, redactOptions(), true);
204
+ const log = pushedUrl && ranOutOfTime(result)
205
+ ? continueInBackground(cwd, dir, pushedUrl, result.skipped)
206
+ : undefined;
207
+ reportUpload(result, push.target, warn, log);
208
+ }
209
+ catch (err) {
210
+ warn(`upload failed, left pending for the next push: ${firstLine(err)}`);
211
+ }
212
+ }
@@ -2,7 +2,6 @@ import { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, readProviders, writeProviders, } fr
2
2
  import { PROVIDER_NAME } from "../../protocol/context.js";
3
3
  import { flagValue } from "../args.js";
4
4
  import { out } from "../io.js";
5
- import { commandUsage } from "../usage.js";
6
5
  function add(args) {
7
6
  const name = args.positional[2];
8
7
  if (!name || !PROVIDER_NAME.test(name))
@@ -41,10 +40,6 @@ function remove(args) {
41
40
  }
42
41
  export function cmdProviders(args) {
43
42
  const sub = args.positional[1];
44
- if (args.flags["help"] || args.flags["h"] || !sub) {
45
- out(commandUsage("providers"));
46
- return;
47
- }
48
43
  if (sub === "add")
49
44
  return add(args);
50
45
  if (sub === "list")
@@ -10,7 +10,6 @@ import { configDir, consentFile } from "../../local/paths.js";
10
10
  import { Reported, requireTerminal, usageError } from "../io.js";
11
11
  import { signIn } from "../signin.js";
12
12
  import { bad, bold, dim, done, plural, rows, skipped, step, Stopped, tilde, title, waiting, } from "../ui.js";
13
- import { commandUsage } from "../usage.js";
14
13
  const STEPS = 3;
15
14
  // A prompt's answer, or Stopped when the user pressed Ctrl-C or Escape.
16
15
  async function answer(prompt) {
@@ -20,10 +19,6 @@ async function answer(prompt) {
20
19
  return value;
21
20
  }
22
21
  export async function cmdSetup(args, cwd, options = {}) {
23
- if (args.flags["help"] || args.flags["h"]) {
24
- process.stdout.write(`${commandUsage("setup")}\n`);
25
- return;
26
- }
27
22
  if (args.positional.length > 1 || Object.keys(args.flags).length)
28
23
  throw usageError("setup", args);
29
24
  requireTerminal("setup", options.interactive);
@@ -12,15 +12,10 @@ import { configDir, consentFile, GIT_STATE_DIR } from "../../local/paths.js";
12
12
  import { denyFile, readDenyList } from "../../redact/deny.js";
13
13
  import { Reported, requireTerminal, usageError } from "../io.js";
14
14
  import { bold, dim, done, plural, rows, skipped, Stopped, tilde, title, waiting, } from "../ui.js";
15
- import { commandUsage } from "../usage.js";
16
15
  // Removes what setup made: the global hooks, the permission rules and the
17
16
  // sign-in. The deny list and this repository's trace state go only when the
18
17
  // user says so; other repositories keep theirs.
19
18
  export async function cmdUninstall(args, cwd, options = {}) {
20
- if (args.flags["help"] || args.flags["h"]) {
21
- process.stdout.write(`${commandUsage("uninstall")}\n`);
22
- return;
23
- }
24
19
  if (args.positional.length > 1 || Object.keys(args.flags).length)
25
20
  throw usageError("uninstall", args);
26
21
  requireTerminal("uninstall", options.interactive);