@ascenda-one/history-import 0.1.37 → 0.1.39

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,124 @@ 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. The first agent that needs pairing sends
492
+ your code along with its pairing, so one visit to the link pairs the agent
493
+ and joins the study. The page shows the organisation, the window and what
494
+ you'd share, and declining it refuses both. A pairing that carries a join is
495
+ confirmed from its link only, so no typed code is printed for it. A join is
496
+ remembered in `~/.ascenda/participation.json` and not repeated while its
497
+ window is open; `--rejoin` repeats it.
498
+ 3. **Retention.** Shows the `fix-retention` change and asks. With no
499
+ terminal and no flag, nothing changes.
500
+ 4. **Backfill.** Runs `import --ship` as the agent the join used, but only
501
+ when the join granted the history import (grant 507). The backend refuses
502
+ it otherwise. It hands the importer that agent's pairing in the
503
+ `ASCENDA_TOOL_INSTALLATION_ID`, `ASCENDA_EVENT_WRITE_TOKEN_FILE` and
504
+ `ASCENDA_API_BASE_URL` variables. Those come ahead of `credentials.json`
505
+ in the order under "Without the Flow app", so the import ships as that
506
+ agent even on a machine with several paired tools, and renews its token
507
+ the same way.
508
+
509
+ Confirms: one in the browser per agent not yet paired, and nothing extra for
510
+ the study. Installations can't share a token, because renewing one revokes the
511
+ old, so each agent still needs its own pairing. The join belongs to you, not
512
+ to an installation, so only the first pairing carries the code. One agent
513
+ takes one confirm. Three take three. A re-run on a paired machine takes none.
514
+
515
+ If the server doesn't answer a pairing with a `studyJoin` (an older one, or
516
+ the local dev server started with `pairingCarriesJoin: false`), the code
517
+ isn't carried. The agents pair as usual and the study is joined afterwards
518
+ with `join`'s own question and one more confirm. That's decided from the
519
+ response, not from a version. The count printed up front assumes the server
520
+ carries the code, and the join step says when it didn't. Without a terminal
521
+ the code isn't attached at all, and the join step declines as before.
522
+
523
+ A code the server refuses when the pairing is created (not found, nothing
524
+ live, wrong mode) doesn't stop the pairing. The agent pairs without the study
525
+ and the summary gives the reason.
526
+
527
+ A failed agent doesn't stop the rest, and every step is safe to repeat, so a
528
+ half-finished run is fixed by running it again. The exit code is 0 only when
529
+ every agent found is collecting, the study is joined and the backfill had no
530
+ failures.
531
+
532
+ From a checkout, `ASCENDA_PARTICIPATE_BUNDLE_ROOT=<repo>` runs the adapters'
533
+ built bundles in place of `npx`. Use a scratch `HOME` and `ASCENDA_HOME`
534
+ with `--local` so nothing touches your own setup.
535
+
536
+ Cursor and VS Code history is read from macOS paths today, so on Windows and
537
+ Linux the backfill covers Claude Code and Codex.
538
+
428
539
  ### Staging is scaffolding; `archive` is the copy
429
540
 
430
541
  `import` snapshots each store, extracts, and **deletes the snapshot in a