@ascenda-one/history-import 0.1.36 → 0.1.38

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
@@ -418,13 +418,108 @@ Still open, and worth knowing before trusting a second run completely:
418
418
  ## Usage
419
419
 
420
420
  ```
421
+ ascenda-history-import participate <code> # set this machine up for an organisation's study, start to finish
421
422
  ascenda-history-import scan # human-readable inventory
422
423
  ascenda-history-import scan --json # what the app's consent surface renders
423
424
  ascenda-history-import fix-retention # dry-run; --apply to write
424
425
  ascenda-history-import import # Claude Code + Codex + Cursor + VS Code, dry run; --ship to send
426
+ ascenda-history-import import --git # also read your own commit metadata from repos your sessions ran in; off by default
425
427
  ascenda-history-import archive # the durable copy; --verify / --list / --restore <dir> / --prune
428
+ ascenda-history-import schedule install # a recurring import --ship; also: remove, status
426
429
  ```
427
430
 
431
+ ### Without the Flow app
432
+
433
+ The importer runs on its own. Pair the hooks once (`npx @ascenda-one/claude-code-hooks setup`),
434
+ turn on historical import for your account, then:
435
+
436
+ ```
437
+ ascenda-history-import import --ship
438
+ ```
439
+
440
+ `--ship` finds its pairing the way the hooks do. In order: the flags
441
+ `--installation-id`, `--token-file` and `--api-base-url`; the
442
+ `ASCENDA_TOOL_INSTALLATION_ID`, `ASCENDA_EVENT_WRITE_TOKEN(_FILE)` and
443
+ `ASCENDA_API_BASE_URL` variables; then `~/.ascenda/credentials.json` and
444
+ `~/.ascenda/tokens/`. Two paired tools and no way to choose is an error that
445
+ names both.
446
+
447
+ Event tokens last 30 days. The importer renews one with under 21 days left,
448
+ through the same endpoint and the same token file as the hooks, so there is
449
+ one token store. A token that has already expired can't be renewed; the run
450
+ stops before reading anything and prints the `pair` command. Machines with
451
+ live hooks rarely get there, because the hooks renew on their first event
452
+ after day nine.
453
+
454
+ There is no handoff file without the Flow app, and the output says so as
455
+ a normal line, not a warning.
456
+
457
+ ### A recurring import
458
+
459
+ ```
460
+ ascenda-history-import schedule install # every 14 days
461
+ ascenda-history-import schedule install --every 21d # see the retention guard
462
+ ascenda-history-import schedule status
463
+ ascenda-history-import schedule remove
464
+ ```
465
+
466
+ macOS gets a launchd agent in `~/Library/LaunchAgents`, Linux a systemd user
467
+ timer in `~/.config/systemd/user`. Windows gets the `schtasks` command printed
468
+ and nothing written. Output goes to `~/.ascenda/logs/history-import.log`.
469
+
470
+ Claude Code deletes transcripts after `cleanupPeriodDays`, 30 unless set. The
471
+ default is 14 days so one run can fail and the next still lands inside the
472
+ window. `install` refuses an interval where the retention doesn't cover two
473
+ runs (so `--every 30d`, or `21d` on the default retention) and says why. Run
474
+ `fix-retention --apply` first, or pass `--override-retention`.
475
+
476
+ ### `participate`: a study from one command
477
+
478
+ ```bash
479
+ npx -y @ascenda-one/history-import participate <code>
480
+ ```
481
+
482
+ For someone with no desktop app, on macOS, Windows or Linux. `<code>` is the
483
+ join code their organisation gave them. It runs four steps and then prints a
484
+ summary:
485
+
486
+ 1. **Agents.** Finds Claude Code, Codex CLI, Cursor, Windsurf and Gemini CLI
487
+ by their config folders or their commands on `PATH`, and runs each
488
+ adapter's own `setup --scope user`. Each adapter installs its own bundle as
489
+ the hook binary, which is why they run as separate `npx` processes, pinned
490
+ to this release.
491
+ 2. **Study.** Joins in Report mode with the first paired agent's token
492
+ (Claude Code when there is one). The question and the confirm are `join`'s
493
+ own. A join is remembered in `~/.ascenda/participation.json` and not
494
+ repeated while its window is open; `--rejoin` repeats it.
495
+ 3. **Retention.** Shows the `fix-retention` change and asks. With no
496
+ terminal and no flag, nothing changes.
497
+ 4. **Backfill.** Runs `import --ship` as the agent the join used, but only
498
+ when the join granted the history import (grant 507). The backend refuses
499
+ it otherwise. It hands the importer that agent's pairing in the
500
+ `ASCENDA_TOOL_INSTALLATION_ID`, `ASCENDA_EVENT_WRITE_TOKEN_FILE` and
501
+ `ASCENDA_API_BASE_URL` variables. Those come ahead of `credentials.json`
502
+ in the order under "Without the Flow app", so the import ships as that
503
+ agent even on a machine with several paired tools, and renews its token
504
+ the same way.
505
+
506
+ Confirms: one in the browser per agent not yet paired, and one for the
507
+ study. A pairing confirms one installation, and installations can't share a
508
+ token, because renewing one revokes the old. Getting this to a single
509
+ confirm needs the backend to let one pairing carry the study code.
510
+
511
+ A failed agent doesn't stop the rest, and every step is safe to repeat, so a
512
+ half-finished run is fixed by running it again. The exit code is 0 only when
513
+ every agent found is collecting, the study is joined and the backfill had no
514
+ failures.
515
+
516
+ From a checkout, `ASCENDA_PARTICIPATE_BUNDLE_ROOT=<repo>` runs the adapters'
517
+ built bundles in place of `npx`. Use a scratch `HOME` and `ASCENDA_HOME`
518
+ with `--local` so nothing touches your own setup.
519
+
520
+ Cursor and VS Code history is read from macOS paths today, so on Windows and
521
+ Linux the backfill covers Claude Code and Codex.
522
+
428
523
  ### Staging is scaffolding; `archive` is the copy
429
524
 
430
525
  `import` snapshots each store, extracts, and **deletes the snapshot in a