@ascenda-one/history-import 0.1.37 → 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 +95 -0
- package/dist/cli.js +1723 -459
- package/dist/cli.js.map +1 -1
- package/dist/credentials.js +144 -0
- package/dist/credentials.js.map +1 -0
- package/dist/extractors/claudeCode.js +25 -27
- package/dist/extractors/claudeCode.js.map +1 -1
- package/dist/extractors/git.js +262 -7
- package/dist/extractors/git.js.map +1 -1
- package/dist/participate.js +645 -0
- package/dist/participate.js.map +1 -0
- package/dist/schedule.js +239 -0
- package/dist/schedule.js.map +1 -0
- package/dist/ship.js +23 -19
- package/dist/ship.js.map +1 -1
- package/package.json +1 -1
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
|