@ascenda-one/claude-code-hooks 0.1.14 → 0.1.15

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
@@ -53,14 +53,61 @@ If you want the deterministic hooks without the skill or MCP server, the
53
53
  published package runs with no clone and no build:
54
54
 
55
55
  ```bash
56
- npx @ascenda-one/claude-code-hooks --help
56
+ npx @ascenda-one/claude-code-hooks setup
57
57
  ```
58
58
 
59
- Then wire the events yourself — see [Register hooks manually](#register-hooks-manually).
59
+ This pairs (printing a 6-digit code to confirm in the Ascenda app), installs a
60
+ self-contained hook bundle to `~/.ascenda/bin`, writes
61
+ `~/.ascenda/credentials.json`, and registers the hooks in this project's
62
+ `.claude/settings.local.json`. Restart Claude Code and events flow — no shell
63
+ exports, no settings file to hand-edit.
60
64
 
61
- ### Pair first (both routes)
65
+ ```bash
66
+ npx @ascenda-one/claude-code-hooks status # exits non-zero if anything is unwired
67
+ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
68
+ ```
69
+
70
+ | Option | |
71
+ | --- | --- |
72
+ | `--api-base-url <url>` | ingest host (default `https://api.ascenda.one`) |
73
+ | `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
74
+ | `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
75
+ | `--scope project\|user` | register in this project (default) or in `~/.claude/settings.json` |
76
+ | `--project-dir <path>` | project root for `--scope project` (default cwd) |
77
+ | `--dry-run` | print what would change, write nothing |
78
+
79
+ From a clone, `./scripts/setup-local.sh` builds the workspace, starts the dev
80
+ server detached, and runs the same `setup --local` — no backend, no phone, no
81
+ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
82
+ [TESTING.md](../TESTING.md).
83
+
84
+ #### What setup writes
85
+
86
+ | Path | |
87
+ | --- | --- |
88
+ | `~/.ascenda/bin/ascenda-claude-hook` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
89
+ | `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` |
90
+ | `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
91
+ | `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
92
+
93
+ Registration is idempotent and marker-keyed: re-running replaces our entries
94
+ rather than appending, hooks belonging to anyone else are left alone, and the
95
+ file is backed up to `.ascenda-backup` before the first write. Settings that
96
+ are not valid JSON abort the run rather than being overwritten.
97
+
98
+ Hooks then need **no environment at all**: the command pins the absolute path
99
+ of the Node that ran setup, and configuration comes from the credentials file.
100
+ Claude Code spawns hooks with whatever environment it was launched from, so
101
+ anything depending on shell exports stops working the moment the editor is
102
+ opened from a launcher rather than a terminal. The variables below still
103
+ override the file when set.
104
+
105
+ `status` also flags hook entries pointing at a binary that no longer exists —
106
+ those fail silently on every event otherwise.
107
+
108
+ ### Pairing by hand (if you skip `setup`)
62
109
 
63
- Neither route sends anything until this machine is paired:
110
+ `setup` pairs for you. To pair this machine directly instead:
64
111
 
65
112
  ```bash
66
113
  npx -y @ascenda-one/claude-code-hooks pair
@@ -79,10 +126,11 @@ Code. The token itself is never copied around — every CLI tool reads it from
79
126
  the file `pair` wrote. (The editor extension's pairing cannot be reused here:
80
127
  its token lives in the editor's private secret storage.)
81
128
 
82
- > **This variable is required, not optional.** Without it every hook
83
- > invocation exits with `Missing ASCENDA_TOOL_INSTALLATION_ID`. The adapter
84
- > refuses to guess rather than silently mint a second, unpaired identity that
85
- > would fragment your telemetry across two installations.
129
+ > **On this route the variable is required.** Without it — and without the
130
+ > `~/.ascenda/credentials.json` that `setup` writes — every hook invocation
131
+ > exits saying so. The adapter refuses to guess rather than silently mint a
132
+ > second, unpaired identity that would fragment your telemetry across two
133
+ > installations.
86
134
 
87
135
  On a Dev backend with no phone, [pairing-sim](../ascenda-pairing-sim/) stands in
88
136
  for the app: