docks-kit 0.22.25 → 0.23.0

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.
Files changed (77) hide show
  1. package/AGENTS.md +35 -81
  2. package/README.md +31 -58
  3. package/cli/docs/command-guards.md +231 -197
  4. package/cli/docs/flags.md +25 -55
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +5 -5
  7. package/cli/docs/omp-models.md +249 -48
  8. package/cli/docs/overview.md +4 -12
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +10 -57
  11. package/cli/docs/toolchain.md +9 -78
  12. package/cli/src/argv.ts +0 -8
  13. package/cli/src/argvValidate.ts +2 -46
  14. package/cli/src/commands/docs.ts +2 -14
  15. package/cli/src/commands/harnesses.ts +6 -9
  16. package/cli/src/commands/sync.ts +5 -99
  17. package/cli/src/commands/toolchain.ts +4 -12
  18. package/cli/src/engine-native/DESIGN.md +67 -88
  19. package/cli/src/engine-native/deps.ts +6 -86
  20. package/cli/src/engine-native/engineCtx.ts +7 -76
  21. package/cli/src/engine-native/exec.ts +1 -18
  22. package/cli/src/engine-native/harnesses.ts +6 -6
  23. package/cli/src/engine-native/index.ts +4 -6
  24. package/cli/src/engine-native/jq.ts +4 -37
  25. package/cli/src/engine-native/modes.ts +3 -132
  26. package/cli/src/engine-native/ompRemovals.ts +14 -0
  27. package/cli/src/engine-native/os/darwin.ts +0 -4
  28. package/cli/src/engine-native/os/index.ts +1 -2
  29. package/cli/src/engine-native/os/linux.ts +0 -3
  30. package/cli/src/engine-native/os/posix.ts +2 -46
  31. package/cli/src/engine-native/os/types.ts +1 -32
  32. package/cli/src/engine-native/os/windows.ts +0 -49
  33. package/cli/src/engine-native/parseArgs.ts +11 -124
  34. package/cli/src/engine-native/parseHelp.ts +5 -40
  35. package/cli/src/engine-native/scratch.ts +1 -1
  36. package/cli/src/engine-native/services.ts +1 -2
  37. package/cli/src/engine-native/sharedTypes.d.ts +0 -40
  38. package/cli/src/engine-native/skillsSync.ts +1 -1
  39. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  40. package/cli/src/engine-native/syncDispatch.ts +10 -57
  41. package/cli/src/engine-native/toolchain.ts +5 -40
  42. package/cli/src/engine.ts +0 -75
  43. package/cli/src/generated/sotPayload.ts +14 -41
  44. package/cli/src/main.ts +7 -19
  45. package/cli/src/manifests.ts +1 -93
  46. package/cli/src/payload.ts +2 -8
  47. package/cli/tsconfig.json +1 -3
  48. package/package.json +3 -5
  49. package/cli/docs/models.md +0 -58
  50. package/cli/docs/modifiers.md +0 -52
  51. package/cli/docs/plugins.md +0 -70
  52. package/cli/src/commands/model.ts +0 -68
  53. package/cli/src/commands/models.ts +0 -75
  54. package/cli/src/commands/plugins.ts +0 -35
  55. package/cli/src/commands/status.ts +0 -206
  56. package/cli/src/efforts.ts +0 -89
  57. package/cli/src/engine-native/claudeLsp.ts +0 -301
  58. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  59. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  60. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  61. package/cli/src/engine-native/claudeRetired.ts +0 -165
  62. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  63. package/cli/src/engine-native/claudeSettings.ts +0 -201
  64. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  65. package/cli/src/engine-native/claudeSync.ts +0 -312
  66. package/cli/src/engine-native/codexConfig.ts +0 -214
  67. package/cli/src/engine-native/codexHooks.ts +0 -91
  68. package/cli/src/engine-native/codexPaths.ts +0 -14
  69. package/cli/src/engine-native/codexPlugins.ts +0 -315
  70. package/cli/src/engine-native/codexStatus.ts +0 -25
  71. package/cli/src/engine-native/codexSync.ts +0 -314
  72. package/cli/src/engine-native/codexToml.ts +0 -303
  73. package/cli/src/engine-native/liveModels.ts +0 -264
  74. package/cli/src/engine-native/models.ts +0 -101
  75. package/cli/src/engine-native/parseModifiers.ts +0 -225
  76. package/cli/src/engine-native/settings.ts +0 -42
  77. package/cli/src/engine-native/tomlLines.ts +0 -92
@@ -1,383 +0,0 @@
1
- /**
2
- * EngineNative `sync claude` retired-artifact pruning. The SoT no longer
3
- * ships the inventoried rules and artifacts, so this pass force-prunes them
4
- * from existing installations without `--reconcile`. Message strings and
5
- * prune semantics are part of the contract.
6
- */
7
- import { createHash } from "node:crypto";
8
- import { copyFileSync, existsSync, readFileSync, renameSync, rmdirSync, rmSync } from "node:fs";
9
- import { replaceFile } from "./atomicWrite";
10
- import type { ClaudeRuntimeState } from "./claudeSync";
11
- import { RETIRED_PERMISSION_RULES } from "./claudeRetired";
12
- import { p } from "./exec";
13
- import type { Ctx } from "./index";
14
- import { isObject, jqStringify, parseJson, type Json } from "./jq";
15
- import { lstat } from "./skillsLinks";
16
-
17
- const REMOVED_MANIFEST = {
18
- hooks: ["disable-claudeai-connectors.sh"],
19
- files: ["alert_bubble.mp3"],
20
- settingsKeys: [
21
- "showTurnDuration",
22
- "advisorModel",
23
- "env.CLAUDE_CODE_SUBAGENT_MODEL",
24
- "env.ANTHROPIC_DEFAULT_OPUS_MODEL",
25
- "env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE",
26
- "env.CLAUDE_CODE_DISABLE_1M_CONTEXT",
27
- "env.CLAUDE_CODE_FORK_SUBAGENT",
28
- "env.CLAUDE_CODE_EFFORT_LEVEL",
29
- "enabledPlugins.effect-kit@docks",
30
- "enabledPlugins.session-relay@docks",
31
- ],
32
- permissionRules: {
33
- allow: ["Write(./)", "Bash(rtk *)", ...RETIRED_PERMISSION_RULES.allow],
34
- deny: [
35
- "Write(**/.env)",
36
- "Write(**/.env.local)",
37
- "Write(**/secrets/**)",
38
- ...RETIRED_PERMISSION_RULES.deny,
39
- ],
40
- ask: [...RETIRED_PERMISSION_RULES.ask],
41
- },
42
- claudeJsonKeys: [] as Array<string>,
43
- /** Home-relative artifacts the kit installed outside ~/.claude. */
44
- homeFiles: [".local/bin/effect-solutions", ".local/bin/session-relay"],
45
- runtimeReady: {
46
- hooks: ["notify.sh"],
47
- files: ["statusline.sh", "fetch-usage.sh"],
48
- },
49
- };
50
-
51
- /**
52
- * Hook handler commands that the kit shipped in SoT/.claude/settings.json and
53
- * then retired. The pass removes only these handlers, so user handlers on the
54
- * same events stay. The Stop pass runs only after the Bun runtime cutover.
55
- */
56
- const RETIRED_HOOK_COMMANDS = {
57
- PreToolUse: ["$HOME/.claude/hooks/rtk-rewrite.sh", "rtk hook claude"],
58
- Stop: [
59
- "bash $HOME/.claude/fetch-usage.sh",
60
- "ffplay -nodisp -autoexit ~/.claude/alert_bubble.mp3",
61
- "ffplay -nodisp -autoexit https://raw.githubusercontent.com/DocksDocks/public/main/alert_bubble.mp3",
62
- ],
63
- } as const;
64
-
65
- type RetiredHookEvent = keyof typeof RETIRED_HOOK_COMMANDS;
66
-
67
- /**
68
- * SHA-256 of every version of the runtime-ready artifacts that the kit
69
- * shipped, keyed by the path under ~/.claude. A copy with another hash is the
70
- * user's file, so the prune keeps it as `<path>.bak`.
71
- */
72
- const LEGACY_ARTIFACT_HASHES: Readonly<Record<string, ReadonlyArray<string>>> = {
73
- "statusline.sh": [
74
- "292df944d7f28bacde854105891a270fbbe1a114172d0000d8d2c4366097c18d",
75
- "3a3ec8911c3916a1ba1fdf8ac5a8c4d8231ecc7dcd1f7355c7787603b9734efe",
76
- "8189f5fb83dfbbf864737a4613062912c0120659f01f56f61b0a3ed7ed69949c",
77
- "8dd0d6db2fcb9cec042756f9d14e09ee0214041b9d85fa5e26b8c99a06b65cd9",
78
- "b97abaf97874c7bc0b6052eb8f14f73bccff20c3b79f7d6b2ff79137daef360d",
79
- "baec096cbcf70245613a9ea10fe7cbdb50b16d02106b3cb6a0861a783b2de97c",
80
- "c7233f4006f603ee5431d02daf896a58167d20461171f9a1a329f8127ced4835",
81
- ],
82
- "fetch-usage.sh": [
83
- "304f5a17d9c4356ed7f3eedf7f38766b8e8e7fce91a80a6efbad0b8a6b43654d",
84
- "35531c6941d2e203f385baf6db9a9a17f57471ceadf91c6ee252b2f1aee0b456",
85
- "9b8fcac8bc3a45d505c58ca48013f4949a3a3d1cf5064872871286c2a81196f9",
86
- "ceaa5b5241edf639ca873439e1f1013b7e0d902a23d2bf831317e064a3ccab46",
87
- ],
88
- "hooks/notify.sh": [
89
- "2beb02119bd9bad3045341e12022fb7234b53b02c08908e4a9949968980f6e69",
90
- "90261530799aaf978949572521d2a73105a4104a47c86132a3815c26f0078216",
91
- ],
92
- };
93
-
94
- /** What retireArtifact did with one path. `suffix` names the backup, such as `.bak.1`. */
95
- type ArtifactRetirement =
96
- | { readonly kind: "absent" }
97
- | { readonly kind: "removed" }
98
- | { readonly kind: "preserved"; readonly suffix: string };
99
-
100
- /**
101
- * The first unoccupied backup suffix for `path`: `.bak`, then `.bak.1`,
102
- * `.bak.2`, and so on. The check uses lstat, so a dangling symlink occupies
103
- * its name.
104
- */
105
- function freeBackupSuffix(path: string): string {
106
- let suffix = ".bak";
107
- for (let n = 1; lstat(`${path}${suffix}`) !== undefined; n++) suffix = `.bak.${n}`;
108
- return suffix;
109
- }
110
-
111
- /**
112
- * Retire one artifact. A path in LEGACY_ARTIFACT_HASHES is removed only when
113
- * its content matches a shipped version. Other content moves to the first
114
- * unoccupied backup name, so an earlier backup stays. A path without hashes
115
- * has a kit-only name and is removed. The presence check uses lstat, so a
116
- * dangling symlink is removed too.
117
- */
118
- function retireArtifact(
119
- ctx: Ctx,
120
- path: string,
121
- shipped: ReadonlyArray<string> | undefined,
122
- ): ArtifactRetirement {
123
- const stats = lstat(path);
124
- if (stats === undefined) return { kind: "absent" };
125
- const owned =
126
- shipped === undefined ||
127
- (stats.isFile() &&
128
- shipped.includes(createHash("sha256").update(readFileSync(path)).digest("hex")));
129
- if (owned) {
130
- if (ctx.dryRun) ctx.services.logger.echo(`[dry-run] rm ${path}`);
131
- else rmSync(path, { force: true });
132
- return { kind: "removed" };
133
- }
134
- const suffix = freeBackupSuffix(path);
135
- if (ctx.dryRun) ctx.services.logger.echo(`[dry-run] mv ${path} ${path}${suffix}`);
136
- else renameSync(path, `${path}${suffix}`);
137
- return { kind: "preserved", suffix };
138
- }
139
-
140
- /**
141
- * Copy settings.json to settings.json.bak once per sync, just before the
142
- * first write of the removals pass. When an earlier pass of the same sync
143
- * already wrote the backup, the copy never runs, so that backup keeps the
144
- * original bytes.
145
- */
146
- function settingsBackup(file: string, alreadyBackedUp: boolean): () => void {
147
- let done = alreadyBackedUp;
148
- return () => {
149
- if (done) return;
150
- copyFileSync(file, `${file}.bak`);
151
- done = true;
152
- };
153
- }
154
-
155
- /**
156
- * claude::_prune_json_keys — present-count; deletes when !dryRun. The pass
157
- * calls `beforeWrite` just before it writes the file.
158
- */
159
- function pruneJsonKeys(
160
- ctx: Ctx,
161
- file: string,
162
- keys: Array<string>,
163
- beforeWrite: () => void,
164
- ): number {
165
- if (keys.length === 0 || !existsSync(file)) return 0;
166
- const doc = parseJson(readFileSync(file, "utf8"));
167
- if (doc === undefined) return 0;
168
-
169
- const hasPath = (root: Json, path: Array<string>): boolean => {
170
- let cur: Json = root;
171
- for (const seg of path.slice(0, -1)) {
172
- if (!isObject(cur) || cur[seg] === undefined) return false;
173
- cur = cur[seg]!;
174
- }
175
- return isObject(cur) && Object.prototype.hasOwnProperty.call(cur, path[path.length - 1]!);
176
- };
177
- const presentKeys = keys.filter((k) => hasPath(doc, k.split(".")));
178
- if (presentKeys.length === 0) return 0;
179
-
180
- if (!ctx.dryRun) {
181
- for (const k of presentKeys) {
182
- const path = k.split(".");
183
- let cur: Json = doc;
184
- for (const seg of path.slice(0, -1)) {
185
- if (!isObject(cur)) break;
186
- cur = cur[seg]!;
187
- }
188
- if (isObject(cur)) delete cur[path[path.length - 1]!];
189
- }
190
- beforeWrite();
191
- replaceFile(file, jqStringify(doc));
192
- }
193
- return presentKeys.length;
194
- }
195
-
196
- function prunePermissionRules(
197
- ctx: Ctx,
198
- file: string,
199
- rules: Readonly<Record<"allow" | "deny" | "ask", ReadonlyArray<string>>>,
200
- beforeWrite: () => void,
201
- ): number {
202
- if (!existsSync(file)) return 0;
203
- const doc = parseJson(readFileSync(file, "utf8"));
204
- if (doc === undefined || !isObject(doc) || !isObject(doc["permissions"])) return 0;
205
- const permissions = doc["permissions"];
206
- let present = 0;
207
- for (const key of ["allow", "deny", "ask"] as const) {
208
- const values = permissions[key];
209
- if (!Array.isArray(values)) continue;
210
- const removed = new Set(rules[key]);
211
- present += rules[key].filter((rule) => values.includes(rule)).length;
212
- if (!ctx.dryRun)
213
- permissions[key] = values.filter((value) => typeof value !== "string" || !removed.has(value));
214
- }
215
- if (present > 0 && !ctx.dryRun) {
216
- beforeWrite();
217
- replaceFile(file, jqStringify(doc));
218
- }
219
- return present;
220
- }
221
-
222
- /**
223
- * Remove the retired kit handlers from the named hook events. A group that
224
- * loses all its handlers is dropped, and an event with no groups left is
225
- * dropped. A null or non-array event value is dropped too. The pass calls
226
- * `beforeWrite` just before it writes the file. Returns the count of removed
227
- * entries.
228
- */
229
- function pruneRetiredHookHandlers(
230
- ctx: Ctx,
231
- file: string,
232
- events: ReadonlyArray<RetiredHookEvent>,
233
- beforeWrite: () => void,
234
- ): number {
235
- if (!existsSync(file)) return 0;
236
- const doc = parseJson(readFileSync(file, "utf8"));
237
- if (doc === undefined || !isObject(doc) || !isObject(doc["hooks"])) return 0;
238
- const hooks = doc["hooks"];
239
- let removed = 0;
240
- for (const event of events) {
241
- const groups = hooks[event];
242
- if (groups === undefined) continue;
243
- if (!Array.isArray(groups)) {
244
- delete hooks[event];
245
- removed++;
246
- continue;
247
- }
248
- const retired: ReadonlyArray<string> = RETIRED_HOOK_COMMANDS[event];
249
- let removedFromEvent = 0;
250
- const kept: Array<Json> = [];
251
- for (const group of groups) {
252
- if (!isObject(group) || !Array.isArray(group["hooks"])) {
253
- kept.push(group);
254
- continue;
255
- }
256
- const handlers = group["hooks"].filter(
257
- (handler) =>
258
- !isObject(handler) ||
259
- handler["type"] !== "command" ||
260
- typeof handler["command"] !== "string" ||
261
- !retired.includes(handler["command"]),
262
- );
263
- const count = group["hooks"].length - handlers.length;
264
- removedFromEvent += count;
265
- if (count === 0) kept.push(group);
266
- else if (handlers.length > 0) kept.push({ ...group, hooks: handlers });
267
- }
268
- if (removedFromEvent === 0) continue;
269
- removed += removedFromEvent;
270
- if (kept.length > 0) hooks[event] = kept;
271
- else delete hooks[event];
272
- }
273
- if (removed > 0 && !ctx.dryRun) {
274
- beforeWrite();
275
- replaceFile(file, jqStringify(doc));
276
- }
277
- return removed;
278
- }
279
-
280
- /**
281
- * Prune retired artifacts, settings keys, permission rules, and hook handlers.
282
- * `settingsBackedUp` is true when an earlier pass of this sync already copied
283
- * settings.json to settings.json.bak. The pass then keeps that backup.
284
- */
285
- export function syncRemovals(
286
- ctx: Ctx,
287
- claudeDir: string,
288
- runtime: ClaudeRuntimeState,
289
- settingsBackedUp: boolean,
290
- ): void {
291
- const { change, echo } = ctx.services.logger;
292
- const ready = runtime.kind === "ready";
293
- let hooksRemoved = 0;
294
- let filesRemoved = 0;
295
- const preserved: Array<string> = [];
296
- const hooks = [...REMOVED_MANIFEST.hooks, ...(ready ? REMOVED_MANIFEST.runtimeReady.hooks : [])];
297
- const files = [...REMOVED_MANIFEST.files, ...(ready ? REMOVED_MANIFEST.runtimeReady.files : [])];
298
- const settingsKeys = REMOVED_MANIFEST.settingsKeys.filter(
299
- (key) => key !== "advisorModel" || ctx.claudeAdvisor === "",
300
- );
301
- const hookEvents: Array<RetiredHookEvent> = ready ? ["PreToolUse", "Stop"] : ["PreToolUse"];
302
-
303
- for (const name of hooks) {
304
- const label = `hooks/${name}`;
305
- const result = retireArtifact(ctx, p(claudeDir, "hooks", name), LEGACY_ARTIFACT_HASHES[label]);
306
- if (result.kind === "removed") hooksRemoved++;
307
- else if (result.kind === "preserved") preserved.push(`${label}${result.suffix}`);
308
- }
309
- if (!ctx.dryRun && hooksRemoved > 0) {
310
- try {
311
- rmdirSync(p(claudeDir, "hooks"));
312
- } catch {
313
- // Preserve a non-empty user hooks directory.
314
- }
315
- }
316
-
317
- const filePaths = [
318
- ...files.map((rel) => ({
319
- path: p(claudeDir, rel),
320
- label: rel,
321
- shipped: LEGACY_ARTIFACT_HASHES[rel],
322
- })),
323
- ...REMOVED_MANIFEST.homeFiles.map((rel) => ({
324
- path: p(ctx.home, rel),
325
- label: `~/${rel}`,
326
- shipped: undefined,
327
- })),
328
- ];
329
- for (const { path, label, shipped } of filePaths) {
330
- const result = retireArtifact(ctx, path, shipped);
331
- if (result.kind === "removed") filesRemoved++;
332
- else if (result.kind === "preserved") preserved.push(`${label}${result.suffix}`);
333
- }
334
-
335
- const settingsPath = p(claudeDir, "settings.json");
336
- const backup = settingsBackup(settingsPath, settingsBackedUp);
337
- const skeys = pruneJsonKeys(ctx, settingsPath, settingsKeys, backup);
338
- const permissionRules = prunePermissionRules(
339
- ctx,
340
- settingsPath,
341
- REMOVED_MANIFEST.permissionRules,
342
- backup,
343
- );
344
- const hookHandlers = pruneRetiredHookHandlers(ctx, settingsPath, hookEvents, backup);
345
- const cjkeys = pruneJsonKeys(
346
- ctx,
347
- p(ctx.home, ".claude.json"),
348
- REMOVED_MANIFEST.claudeJsonKeys,
349
- () => {},
350
- );
351
-
352
- if (ctx.dryRun) {
353
- if (skeys > 0)
354
- echo(`[dry-run] del ${skeys} stale key(s) from ${p(claudeDir, "settings.json")}`);
355
- if (permissionRules > 0) {
356
- echo(
357
- `[dry-run] del ${permissionRules} stale permission rule(s) from ${p(claudeDir, "settings.json")}`,
358
- );
359
- }
360
- if (hookHandlers > 0) {
361
- echo(
362
- `[dry-run] del ${hookHandlers} retired hook handler(s) from ${p(claudeDir, "settings.json")}`,
363
- );
364
- }
365
- if (cjkeys > 0)
366
- echo(`[dry-run] del ${cjkeys} stale key(s) from ${p(ctx.home, ".claude.json")}`);
367
- return;
368
- }
369
-
370
- const artifacts = hooksRemoved + filesRemoved + preserved.length;
371
- if (artifacts + skeys + permissionRules + hookHandlers + cjkeys > 0) {
372
- const permissionSummary = permissionRules > 0 ? `, permission rules: ${permissionRules}` : "";
373
- const handlerSummary = hookHandlers > 0 ? `, retired hook handlers: ${hookHandlers}` : "";
374
- const preservedSummary =
375
- preserved.length > 0
376
- ? `, preserved as backup: ${preserved.length} (${preserved.join(", ")})`
377
- : "";
378
- change(
379
- `Pruned stale artifacts (hooks: ${hooksRemoved}, files: ${filesRemoved}, settings keys: ${skeys}, claude.json keys: ${cjkeys}${permissionSummary}${handlerSummary}${preservedSummary})`,
380
- );
381
- ctx.nextStepTriggers.claudeRestart = true;
382
- }
383
- }
@@ -1,165 +0,0 @@
1
- /** Kit-owned permission rules the SoT no longer ships.
2
- *
3
- * `mergeSettings` unions the deployed arrays with the SoT arrays, so dropping a
4
- * rule from `SoT/.claude/settings.json` never removes it from a file an earlier
5
- * sync already wrote. `claudeRemovals.ts syncRemovals` force-prunes this exact-string
6
- * inventory on every host so the retirement reaches existing installations
7
- * without `--reconcile`.
8
- *
9
- * `allow` holds the shell pre-approvals retired in favour of Claude Code's own
10
- * read-only command analysis and the auto-mode classifier, plus `WebFetch`.
11
- * `deny` holds the malformed single-backslash spellings superseded by their
12
- * escaped `\\)` forms; Claude Code refuses to parse the old text.
13
- *
14
- * Exact strings only. A user-authored rule outside this list survives the prune.
15
- */
16
- export const RETIRED_PERMISSION_RULES = {
17
- allow: [
18
- "Bash(git *)",
19
- "Bash(git add *)",
20
- "Bash(git commit *)",
21
- "Bash(git status *)",
22
- "Bash(git diff *)",
23
- "Bash(git log *)",
24
- "Bash(git branch *)",
25
- "Bash(git checkout *)",
26
- "Bash(git switch *)",
27
- "Bash(git stash *)",
28
- "Bash(git fetch *)",
29
- "Bash(git pull *)",
30
- "Bash(git tag *)",
31
- "Bash(git show *)",
32
- "Bash(git blame *)",
33
- "Bash(git worktree *)",
34
- "Bash(gh *)",
35
- "Bash(pnpm *)",
36
- "Bash(npm *)",
37
- "Bash(npx *)",
38
- "Bash(node *)",
39
- "Bash(docker *)",
40
- "Bash(docker-compose *)",
41
- "Bash(ls *)",
42
- "Bash(cat *)",
43
- "Bash(find *)",
44
- "Bash(grep *)",
45
- "Bash(head *)",
46
- "Bash(tail *)",
47
- "Bash(wc *)",
48
- "Bash(sort *)",
49
- "Bash(uniq *)",
50
- "Bash(diff *)",
51
- "Bash(which *)",
52
- "Bash(pwd *)",
53
- "Bash(date *)",
54
- "Bash(mkdir *)",
55
- "Bash(basename *)",
56
- "Bash(dirname *)",
57
- "Bash(realpath *)",
58
- "Bash(jq *)",
59
- "Bash(curl *)",
60
- "Bash(tree *)",
61
- "Bash(sed *)",
62
- "Bash(awk *)",
63
- "Bash(cut *)",
64
- "Bash(tr *)",
65
- "Bash(tee *)",
66
- "Bash(echo *)",
67
- "Bash(printf *)",
68
- "Bash(env *)",
69
- "Bash(printenv *)",
70
- "Bash(uname *)",
71
- "Bash(file *)",
72
- "Bash(stat *)",
73
- "Bash(du *)",
74
- "Bash(id *)",
75
- "Bash(whoami *)",
76
- "Bash(php *)",
77
- "Bash(composer *)",
78
- "Bash(python3 *)",
79
- "Bash(python *)",
80
- "Bash(pip *)",
81
- "Bash(pip3 *)",
82
- "PowerShell(git *)",
83
- "PowerShell(git add *)",
84
- "PowerShell(git commit *)",
85
- "PowerShell(git status *)",
86
- "PowerShell(git diff *)",
87
- "PowerShell(git log *)",
88
- "PowerShell(git branch *)",
89
- "PowerShell(git checkout *)",
90
- "PowerShell(git switch *)",
91
- "PowerShell(git stash *)",
92
- "PowerShell(git fetch *)",
93
- "PowerShell(git pull *)",
94
- "PowerShell(git tag *)",
95
- "PowerShell(git show *)",
96
- "PowerShell(git blame *)",
97
- "PowerShell(git worktree *)",
98
- "PowerShell(gh *)",
99
- "PowerShell(pnpm *)",
100
- "PowerShell(npm *)",
101
- "PowerShell(npx *)",
102
- "PowerShell(node *)",
103
- "PowerShell(docker *)",
104
- "PowerShell(docker-compose *)",
105
- "PowerShell(ls *)",
106
- "PowerShell(cat *)",
107
- "PowerShell(find *)",
108
- "PowerShell(grep *)",
109
- "PowerShell(head *)",
110
- "PowerShell(tail *)",
111
- "PowerShell(wc *)",
112
- "PowerShell(sort *)",
113
- "PowerShell(uniq *)",
114
- "PowerShell(diff *)",
115
- "PowerShell(which *)",
116
- "PowerShell(pwd *)",
117
- "PowerShell(date *)",
118
- "PowerShell(mkdir *)",
119
- "PowerShell(basename *)",
120
- "PowerShell(dirname *)",
121
- "PowerShell(realpath *)",
122
- "PowerShell(jq *)",
123
- "PowerShell(curl *)",
124
- "PowerShell(tree *)",
125
- "PowerShell(sed *)",
126
- "PowerShell(awk *)",
127
- "PowerShell(cut *)",
128
- "PowerShell(tr *)",
129
- "PowerShell(tee *)",
130
- "PowerShell(echo *)",
131
- "PowerShell(printf *)",
132
- "PowerShell(env *)",
133
- "PowerShell(printenv *)",
134
- "PowerShell(uname *)",
135
- "PowerShell(file *)",
136
- "PowerShell(stat *)",
137
- "PowerShell(du *)",
138
- "PowerShell(id *)",
139
- "PowerShell(whoami *)",
140
- "PowerShell(php *)",
141
- "PowerShell(composer *)",
142
- "PowerShell(python3 *)",
143
- "PowerShell(python *)",
144
- "PowerShell(pip *)",
145
- "PowerShell(pip3 *)",
146
- "WebFetch",
147
- ],
148
- deny: [
149
- "PowerShell(Remove-Item *-Recurse* \\)",
150
- "PowerShell(Remove-Item *-Recurse* *:\\)",
151
- "PowerShell(del *-Recurse* \\)",
152
- "PowerShell(del *-Recurse* *:\\)",
153
- "PowerShell(erase *-Recurse* \\)",
154
- "PowerShell(erase *-Recurse* *:\\)",
155
- "PowerShell(rd *-Recurse* \\)",
156
- "PowerShell(rd *-Recurse* *:\\)",
157
- "PowerShell(ri *-Recurse* \\)",
158
- "PowerShell(ri *-Recurse* *:\\)",
159
- "PowerShell(rm *-Recurse* \\)",
160
- "PowerShell(rm *-Recurse* *:\\)",
161
- "PowerShell(rmdir *-Recurse* \\)",
162
- "PowerShell(rmdir *-Recurse* *:\\)",
163
- ],
164
- ask: [],
165
- } as const satisfies Readonly<Record<"allow" | "deny" | "ask", ReadonlyArray<string>>>;
@@ -1,157 +0,0 @@
1
- import { p } from "./exec";
2
- import { isObject, parseJson, type Json } from "./jq";
3
- import { hostOs, type HostOs } from "./os";
4
-
5
- const BUN_SENTINEL = "__DOCKS_KIT_BUN__";
6
- const SESSION_START_SENTINEL = "__DOCKS_KIT_SESSION_START__";
7
- const NOTIFY_SENTINEL = "__DOCKS_KIT_NOTIFY__";
8
- const STATUSLINE_SENTINEL = "__DOCKS_KIT_STATUSLINE__";
9
-
10
- export interface ClaudeRuntimePaths {
11
- readonly bun: string;
12
- readonly statusline: string;
13
- readonly sessionStart: string;
14
- readonly notify: string;
15
- }
16
-
17
- export function claudeRuntimePaths(claudeDir: string, bun: string): ClaudeRuntimePaths {
18
- return {
19
- bun,
20
- statusline: p(claudeDir, "bin", "statusline.mjs"),
21
- sessionStart: p(claudeDir, "bin", "session-start.mjs"),
22
- notify: p(claudeDir, "bin", "notify.mjs"),
23
- };
24
- }
25
-
26
- function cloneJson(value: Json): Json {
27
- const cloned = parseJson(JSON.stringify(value));
28
- if (cloned === undefined) throw new Error("Claude settings template cannot be serialized");
29
- return cloned;
30
- }
31
-
32
- function countString(value: Json, expected: string): number {
33
- if (value === expected) return 1;
34
- if (Array.isArray(value))
35
- return value.reduce<number>((total, item) => total + countString(item, expected), 0);
36
- if (!isObject(value)) return 0;
37
- return Object.values(value).reduce<number>(
38
- (total, item) => total + countString(item, expected),
39
- 0,
40
- );
41
- }
42
-
43
- function hooksObject(template: Json): { [key: string]: Json } {
44
- if (!isObject(template) || !isObject(template["hooks"]))
45
- throw new Error("Claude settings hooks object is missing");
46
- return template["hooks"];
47
- }
48
-
49
- function commandHandler(
50
- template: Json,
51
- event: "SessionStart" | "Notification",
52
- ): { [key: string]: Json } {
53
- const entries = hooksObject(template)[event];
54
- if (!Array.isArray(entries) || entries.length !== 1 || !isObject(entries[0])) {
55
- throw new Error(`${event} sentinel location is invalid`);
56
- }
57
- const handlers = entries[0]["hooks"];
58
- if (!Array.isArray(handlers) || handlers.length !== 1 || !isObject(handlers[0])) {
59
- throw new Error(`${event} sentinel handler is invalid`);
60
- }
61
- return handlers[0];
62
- }
63
-
64
- function oneArg(handler: { [key: string]: Json }, sentinel: string, event: string): void {
65
- const args = handler["args"];
66
- if (!Array.isArray(args) || args.length !== 1 || args[0] !== sentinel) {
67
- throw new Error(`${event} argument sentinel location is invalid`);
68
- }
69
- }
70
-
71
- function validateTemplate(template: Json): void {
72
- const sessionStart = commandHandler(template, "SessionStart");
73
- const notification = commandHandler(template, "Notification");
74
- if (sessionStart["command"] !== BUN_SENTINEL)
75
- throw new Error("SessionStart Bun sentinel location is invalid");
76
- if (notification["command"] !== BUN_SENTINEL)
77
- throw new Error("Notification Bun sentinel location is invalid");
78
- oneArg(sessionStart, SESSION_START_SENTINEL, "SessionStart");
79
- oneArg(notification, NOTIFY_SENTINEL, "Notification");
80
-
81
- const hooks = hooksObject(template);
82
- if (hooks["Stop"] !== undefined)
83
- throw new Error("hooks.Stop must be absent from the Claude settings template");
84
- if (
85
- !isObject(template) ||
86
- !isObject(template["statusLine"]) ||
87
- template["statusLine"]["command"] !== STATUSLINE_SENTINEL
88
- ) {
89
- throw new Error("Statusline sentinel location is invalid");
90
- }
91
- const counts: ReadonlyArray<[string, string, number]> = [
92
- ["Bun", BUN_SENTINEL, 2],
93
- ["SessionStart", SESSION_START_SENTINEL, 1],
94
- ["notify", NOTIFY_SENTINEL, 1],
95
- ["statusline", STATUSLINE_SENTINEL, 1],
96
- ];
97
- for (const [label, sentinel, expected] of counts) {
98
- if (countString(template, sentinel) !== expected)
99
- throw new Error(`${label} sentinel residue/cardinality is invalid`);
100
- }
101
- }
102
-
103
- export function statusLineCommand(runtime: ClaudeRuntimePaths, host: HostOs = hostOs()): string {
104
- return host.statusLineCommand(runtime.bun, runtime.statusline);
105
- }
106
-
107
- export function materializeClaudeSettings(
108
- template: Json,
109
- runtime: ClaudeRuntimePaths | undefined,
110
- host: HostOs = hostOs(),
111
- ): Json {
112
- validateTemplate(template);
113
- const result = cloneJson(template);
114
- const hooks = hooksObject(result);
115
- const failureGroups = hooks["PostToolUseFailure"];
116
- if (Array.isArray(failureGroups)) {
117
- for (const group of failureGroups) {
118
- if (!isObject(group) || !Array.isArray(group["hooks"])) continue;
119
- for (const handler of group["hooks"]) {
120
- if (
121
- isObject(handler) &&
122
- handler["type"] === "command" &&
123
- typeof handler["command"] === "string"
124
- ) {
125
- handler["command"] = host.failureHookCommand(handler["command"]);
126
- }
127
- }
128
- }
129
- }
130
- if (runtime === undefined) {
131
- delete hooks["SessionStart"];
132
- delete hooks["Notification"];
133
- if (!isObject(result)) throw new Error("Claude settings template must be an object");
134
- delete result["statusLine"];
135
- } else {
136
- const sessionStart = commandHandler(result, "SessionStart");
137
- sessionStart["command"] = runtime.bun;
138
- sessionStart["args"] = [runtime.sessionStart];
139
- const notification = commandHandler(result, "Notification");
140
- notification["command"] = runtime.bun;
141
- notification["args"] = [runtime.notify];
142
- if (!isObject(result) || !isObject(result["statusLine"]))
143
- throw new Error("Claude statusLine object is missing");
144
- result["statusLine"]["command"] = statusLineCommand(runtime, host);
145
- }
146
-
147
- for (const sentinel of [
148
- BUN_SENTINEL,
149
- SESSION_START_SENTINEL,
150
- NOTIFY_SENTINEL,
151
- STATUSLINE_SENTINEL,
152
- ]) {
153
- if (countString(result, sentinel) !== 0)
154
- throw new Error(`Claude settings sentinel residue: ${sentinel}`);
155
- }
156
- return result;
157
- }