@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -0,0 +1,134 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { existsSync, realpathSync } from 'node:fs';
3
+ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
4
+ import { HookConstants, TrustStates } from './common/index.ts';
5
+ import type { IScriptTrust } from './common/index.ts';
6
+
7
+ /** Variables that point git at another repository or index than the one in `cwd`. */
8
+ const REDIRECTING_VARIABLES = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
9
+
10
+ /** Git mode of a symlink entry in the index. */
11
+ const SYMLINK_MODE = '120000';
12
+
13
+ /**
14
+ * A read-only `git` query in `cwd`; `undefined` when git is missing, slow or answers with an error.
15
+ * The variables that point git somewhere else are dropped, so the answer is about this checkout.
16
+ */
17
+ const gitQuery = (opts: { cwd: string; args: string[] }): string | undefined => {
18
+ const env: Record<string, string | undefined> = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
19
+
20
+ for (const name of REDIRECTING_VARIABLES) {
21
+ delete env[name];
22
+ }
23
+
24
+ const result = spawnSync('git', opts.args, {
25
+ cwd: opts.cwd,
26
+ encoding: 'utf8',
27
+ timeout: HookConstants.QUERY_TIMEOUT_MS,
28
+ env,
29
+ });
30
+
31
+ return result.status === 0 ? result.stdout.trim() : undefined;
32
+ };
33
+
34
+ const untrusted = (opts: { state: IScriptTrust['state']; reason: string }): IScriptTrust => opts;
35
+
36
+ /**
37
+ * Whether the listed script `script` (repo-relative) may skip the script checks of guard-writes: only
38
+ * while git tracks it and its worktree file, its index entry and HEAD hold the same bytes. A script an
39
+ * agent edited and then runs is therefore checked like any other; so is one that was never committed.
40
+ * The blobs are compared, not `git status`, so `--assume-unchanged` and `--skip-worktree` hide nothing.
41
+ */
42
+ export const trustOf = (opts: { root: string; script: string }): IScriptTrust => {
43
+ const path = resolve(opts.root, opts.script);
44
+
45
+ if (!existsSync(path)) {
46
+ return untrusted({ state: TrustStates.MISSING, reason: 'the file does not exist' });
47
+ }
48
+
49
+ const root = realpathSync(opts.root);
50
+ const real = realpathSync(path);
51
+
52
+ // A link could point at an untracked file that git never looks at.
53
+ if (real !== join(root, relative(resolve(opts.root), path))) {
54
+ return untrusted({
55
+ state: TrustStates.SYMLINK,
56
+ reason: 'its path goes through a symlink, which git does not follow',
57
+ });
58
+ }
59
+
60
+ const repoPath = relative(root, real).split(sep).join('/');
61
+ const entry = gitQuery({
62
+ cwd: root,
63
+ args: ['ls-files', '--stage', '--', `:(literal)${repoPath}`],
64
+ });
65
+
66
+ if (entry === undefined) {
67
+ return untrusted({
68
+ state: TrustStates.UNKNOWN,
69
+ reason: 'git could not say whether it is tracked',
70
+ });
71
+ }
72
+
73
+ if (entry === '') {
74
+ return untrusted({ state: TrustStates.UNTRACKED, reason: 'it is not tracked by git' });
75
+ }
76
+
77
+ const [mode, indexBlob, stage] = entry.split('\n')[0].split(/\s+/);
78
+
79
+ if (mode === SYMLINK_MODE) {
80
+ return untrusted({
81
+ state: TrustStates.SYMLINK,
82
+ reason: 'it is a symlink, which git does not follow',
83
+ });
84
+ }
85
+
86
+ if (stage !== '0') {
87
+ return untrusted({
88
+ state: TrustStates.MODIFIED,
89
+ reason: 'modified trusted script (it has an unresolved merge)',
90
+ });
91
+ }
92
+
93
+ const headBlob = gitQuery({
94
+ cwd: root,
95
+ args: ['rev-parse', '--verify', '--quiet', `HEAD:./${repoPath}`],
96
+ });
97
+
98
+ if (headBlob === undefined) {
99
+ return untrusted({
100
+ state: TrustStates.UNCOMMITTED,
101
+ reason: 'it is not in the last commit yet',
102
+ });
103
+ }
104
+
105
+ const workBlob = gitQuery({ cwd: root, args: ['hash-object', '--', real] });
106
+
107
+ if (workBlob === undefined) {
108
+ return untrusted({
109
+ state: TrustStates.UNKNOWN,
110
+ reason: 'git could not read the file',
111
+ });
112
+ }
113
+
114
+ if (workBlob !== headBlob || indexBlob !== headBlob) {
115
+ return untrusted({
116
+ state: TrustStates.MODIFIED,
117
+ reason: `modified trusted script (${workBlob === headBlob ? 'the index' : 'the working tree'} differs from the last commit)`,
118
+ });
119
+ }
120
+
121
+ return { state: TrustStates.TRUSTED, reason: 'tracked, and identical to the last commit' };
122
+ };
123
+
124
+ /** The listed script `target` names, if any: both resolved to absolute paths, an exact match. */
125
+ export const listedScriptOf = (opts: {
126
+ target: string;
127
+ cwd: string;
128
+ root: string;
129
+ scripts: string[];
130
+ }): string | undefined => {
131
+ const path = isAbsolute(opts.target) ? resolve(opts.target) : resolve(opts.cwd, opts.target);
132
+
133
+ return opts.scripts.find((script) => resolve(opts.root, script) === path);
134
+ };
@@ -46,6 +46,40 @@ export const buildBaseRuleHashes = (): Record<string, string> =>
46
46
  }),
47
47
  );
48
48
 
49
+ /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config. */
50
+ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
51
+ const { commands } = opts.config.guard.writes;
52
+ const { askPush } = opts.config.guard.git;
53
+ const block = {
54
+ ...(commands.length === 0
55
+ ? {}
56
+ : {
57
+ writes: {
58
+ commands: commands.map((command) => ({
59
+ rule: command.rule,
60
+ what: command.what,
61
+ pattern: command.pattern,
62
+ ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
63
+ })),
64
+ },
65
+ }),
66
+ ...(askPush.length === 0 ? {} : { git: { askPush } }),
67
+ };
68
+
69
+ return Object.keys(block).length === 0 ? {} : { guard: block };
70
+ };
71
+
72
+ /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
73
+ const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
74
+ const keys = opts.config.atlas.index?.keys ?? [];
75
+ const block = {
76
+ ...(keys.length === 0 ? {} : { index: { keys } }),
77
+ ...(opts.config.atlas.prebuilt === false ? { prebuilt: false } : {}),
78
+ };
79
+
80
+ return Object.keys(block).length === 0 ? {} : { atlas: block };
81
+ };
82
+
49
83
  /**
50
84
  * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
51
85
  * key order, so the committed file is byte-stable and a stale one shows as a diff.
@@ -82,6 +116,10 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
82
116
  rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
83
117
  // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
84
118
  ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
119
+ // The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
120
+ ...atlasBlockOf({ config }),
121
+ // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
122
+ ...guardBlockOf({ config }),
85
123
  // The remote-host guard reads its policy here; a project without the key has no guard.
86
124
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
87
125
  };
@@ -1,12 +1,16 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
+ import { BASE_DIRECTORY } from '../common/index.ts';
3
4
  import {
4
5
  AgentConstants,
6
+ AgentGuardKinds,
5
7
  AgentRenderers,
6
8
  AgentScopes,
7
9
  atlasServerEntry,
8
10
  canonicalAtlasEntry,
11
+ mergeCodexHooks,
9
12
  mergeCodexToml,
13
+ mergeGuardHook,
10
14
  mergeMcpServers,
11
15
  readAgentTable,
12
16
  } from '../agents/index.ts';
@@ -138,24 +142,138 @@ const planSharedMcp = (opts: { root: string }): ISyncAction[] => {
138
142
  ];
139
143
  };
140
144
 
141
- /** The MCP files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
145
+ /**
146
+ * The guard extension of an agent that takes one (omp, pi): the shipped template, copied into the folder the
147
+ * agent loads extensions from. A file that does not start with sync's marker is the user's own, and a file
148
+ * git tracks belongs to the project: both are left alone and the line says so.
149
+ */
150
+ const planGuardExtension = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
151
+ if (opts.entry.guards === null) {
152
+ return [];
153
+ }
154
+
155
+ const path = join(opts.root, opts.entry.guards.path);
156
+ const text = readFileSync(join(BASE_DIRECTORY, AgentConstants.GUARD_EXTENSION_TEMPLATE), 'utf8');
157
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
158
+
159
+ if (before === text) {
160
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
161
+ }
162
+
163
+ if (before !== undefined && !before.startsWith(AgentConstants.GUARD_EXTENSION_MARKER)) {
164
+ return [
165
+ {
166
+ path,
167
+ status: SyncStatuses.SKIPPED,
168
+ note: `a file of your own is there - left alone; copy node_modules/@venizia/vulcan/base/${AgentConstants.GUARD_EXTENSION_TEMPLATE} over it to add the guards`,
169
+ apply: NO_CHANGE,
170
+ },
171
+ ];
172
+ }
173
+
174
+ if (before !== undefined && isTracked({ root: opts.root, path: opts.entry.guards.path })) {
175
+ return [
176
+ {
177
+ path,
178
+ status: SyncStatuses.SKIPPED,
179
+ note: 'tracked by git - left alone; copy the shipped extension over it to update the guards',
180
+ apply: NO_CHANGE,
181
+ },
182
+ ];
183
+ }
184
+
185
+ return [
186
+ {
187
+ path,
188
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
189
+ apply: () => {
190
+ mkdirSync(dirname(path), { recursive: true });
191
+ writeFileSync(path, text);
192
+ },
193
+ },
194
+ ];
195
+ };
196
+
197
+ /**
198
+ * The guard hook in an agent's hooks file (Antigravity): one entry under a key of VULCAN's own, merged into
199
+ * what is there, every other hook left as written. A file that is not JSON, or that git tracks, is left alone.
200
+ */
201
+ const planGuardHooksJson = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
202
+ if (opts.entry.guards === null) {
203
+ return [];
204
+ }
205
+
206
+ const path = join(opts.root, opts.entry.guards.path);
207
+ const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
208
+ const merged =
209
+ opts.entry.guards.kind === AgentGuardKinds.CODEX_HOOKS
210
+ ? mergeCodexHooks({ text })
211
+ : mergeGuardHook({ text });
212
+
213
+ if (!merged.ok) {
214
+ return [
215
+ {
216
+ path,
217
+ status: SyncStatuses.SKIPPED,
218
+ note: `${merged.reason} - left untouched; fix it, then re-run sync`,
219
+ apply: NO_CHANGE,
220
+ },
221
+ ];
222
+ }
223
+
224
+ if (!merged.changed) {
225
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
226
+ }
227
+
228
+ if (text !== undefined && isTracked({ root: opts.root, path: opts.entry.guards.path })) {
229
+ return [
230
+ {
231
+ path,
232
+ status: SyncStatuses.SKIPPED,
233
+ note: 'tracked by git - left alone; add the VULCAN guard hook by hand (see the hooks reference)',
234
+ apply: NO_CHANGE,
235
+ },
236
+ ];
237
+ }
238
+
239
+ return [
240
+ {
241
+ path,
242
+ status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
243
+ apply: () => {
244
+ mkdirSync(dirname(path), { recursive: true });
245
+ writeFileSync(path, merged.text);
246
+ },
247
+ },
248
+ ];
249
+ };
250
+
251
+ const planAgentGuards = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] =>
252
+ opts.entry.guards?.kind === AgentGuardKinds.HOOKS_JSON ||
253
+ opts.entry.guards?.kind === AgentGuardKinds.CODEX_HOOKS
254
+ ? planGuardHooksJson(opts)
255
+ : planGuardExtension(opts);
256
+
257
+ /** The MCP files and guard files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
142
258
  export const planAgentFiles = (opts: { root: string; agents: string[] }): ISyncAction[] => {
143
259
  let sharedPlanned = false;
144
260
 
145
261
  return readAgentTable()
146
262
  .filter((entry) => opts.agents.includes(entry.id))
147
263
  .flatMap((entry) => {
264
+ const guards = planAgentGuards({ root: opts.root, entry });
265
+
148
266
  if (entry.mcp.scope === AgentScopes.PROJECT) {
149
- return planAgentMcp({ root: opts.root, entry });
267
+ return [...planAgentMcp({ root: opts.root, entry }), ...guards];
150
268
  }
151
269
 
152
270
  if (sharedPlanned) {
153
- return [];
271
+ return guards;
154
272
  }
155
273
 
156
274
  sharedPlanned = true;
157
275
 
158
- return planSharedMcp({ root: opts.root });
276
+ return [...planSharedMcp({ root: opts.root }), ...guards];
159
277
  });
160
278
  };
161
279
 
@@ -8,13 +8,17 @@ import {
8
8
  rmSync,
9
9
  writeFileSync,
10
10
  } from 'node:fs';
11
- import { dirname, join } from 'node:path';
11
+ import { basename, dirname, join } from 'node:path';
12
12
  import {
13
13
  AgentConstants,
14
+ AgentGuardKinds,
14
15
  AgentRenderers,
15
16
  AgentScopes,
16
17
  readAgentTable,
18
+ RemoveOutcomes,
17
19
  removeCodexBlock,
20
+ removeCodexHooks,
21
+ removeGuardHook,
18
22
  removeMcpEntry,
19
23
  } from '../agents/index.ts';
20
24
  import type { TAgentEntry } from '../agents/index.ts';
@@ -27,7 +31,7 @@ import { isSettingsObject, removeManagedSettings } from './settings.ts';
27
31
  const NO_CHANGE = (): void => {};
28
32
  const CLAUDE_SKILLS = join(SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
29
33
  /** Parents sync may delete once empty: its own agent folders, never `.agents` or the project. */
30
- const OWN_FOLDERS = new Set(['.cursor', '.codex', '.pi', '.vscode', '.claude']);
34
+ const OWN_FOLDERS = new Set(['.cursor', '.codex', '.pi', '.omp', '.vscode', '.claude']);
31
35
 
32
36
  const isSymlink = (opts: { path: string }): boolean =>
33
37
  lstatSync(opts.path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
@@ -99,7 +103,7 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
99
103
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
100
104
  }
101
105
 
102
- if (removed.outcome === 'absent') {
106
+ if (removed.outcome === RemoveOutcomes.ABSENT) {
103
107
  return [];
104
108
  }
105
109
 
@@ -126,6 +130,115 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
126
130
  ];
127
131
  };
128
132
 
133
+ /** VULCAN's entry taken out of a hooks file; the file goes when nothing else is in it. */
134
+ const planGuardHookRemoval = (opts: {
135
+ root: string;
136
+ path: string;
137
+ relative: string;
138
+ kind: string;
139
+ }): ISyncAction[] => {
140
+ if (!existsSync(opts.path)) {
141
+ return [];
142
+ }
143
+
144
+ const text = readFileSync(opts.path, 'utf8');
145
+ const removed =
146
+ opts.kind === AgentGuardKinds.CODEX_HOOKS
147
+ ? removeCodexHooks({ text })
148
+ : removeGuardHook({ text });
149
+ const folder = dirname(opts.path);
150
+ const parent = OWN_FOLDERS.has(basename(folder)) ? folder : undefined;
151
+
152
+ if (!removed.ok) {
153
+ return [
154
+ { path: opts.path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE },
155
+ ];
156
+ }
157
+
158
+ if (removed.outcome === RemoveOutcomes.ABSENT) {
159
+ return [];
160
+ }
161
+
162
+ if (isTracked({ root: opts.root, path: opts.relative })) {
163
+ return [
164
+ {
165
+ path: opts.path,
166
+ status: SyncStatuses.SKIPPED,
167
+ note: 'tracked by git - left alone',
168
+ apply: NO_CHANGE,
169
+ },
170
+ ];
171
+ }
172
+
173
+ return removed.text === undefined
174
+ ? [removeFile({ path: opts.path, parent })]
175
+ : [
176
+ {
177
+ path: opts.path,
178
+ status: SyncStatuses.REPLACED,
179
+ note: 'the VULCAN guard hook taken out',
180
+ apply: () => writeFileSync(opts.path, removed.text ?? ''),
181
+ },
182
+ ];
183
+ };
184
+
185
+ /** The guard extension sync wrote, taken back with its folders once they are empty; a file of the user's stays. */
186
+ const planGuardsRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
187
+ if (opts.entry.guards === null) {
188
+ return [];
189
+ }
190
+
191
+ const path = join(opts.root, opts.entry.guards.path);
192
+
193
+ if (
194
+ opts.entry.guards.kind === AgentGuardKinds.HOOKS_JSON ||
195
+ opts.entry.guards.kind === AgentGuardKinds.CODEX_HOOKS
196
+ ) {
197
+ return planGuardHookRemoval({
198
+ root: opts.root,
199
+ path,
200
+ relative: opts.entry.guards.path,
201
+ kind: opts.entry.guards.kind,
202
+ });
203
+ }
204
+
205
+ if (
206
+ !existsSync(path) ||
207
+ !readFileSync(path, 'utf8').startsWith(AgentConstants.GUARD_EXTENSION_MARKER)
208
+ ) {
209
+ return [];
210
+ }
211
+
212
+ if (isTracked({ root: opts.root, path: opts.entry.guards.path })) {
213
+ return [
214
+ { path, status: SyncStatuses.SKIPPED, note: 'tracked by git - left alone', apply: NO_CHANGE },
215
+ ];
216
+ }
217
+
218
+ return [
219
+ {
220
+ path,
221
+ status: SyncStatuses.REMOVED,
222
+ apply: () => {
223
+ rmSync(path, { force: true });
224
+
225
+ // The folders the file sat in, innermost first, up to and including the agent's own folder.
226
+ let directory = dirname(path);
227
+
228
+ while (directory.startsWith(`${opts.root}/`)) {
229
+ removeIfEmpty({ path: directory });
230
+
231
+ if (OWN_FOLDERS.has(basename(directory))) {
232
+ break;
233
+ }
234
+
235
+ directory = dirname(directory);
236
+ }
237
+ },
238
+ },
239
+ ];
240
+ };
241
+
129
242
  const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
130
243
  if (opts.entry.mcp.scope !== AgentScopes.PROJECT) {
131
244
  return [];
@@ -167,7 +280,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
167
280
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
168
281
  }
169
282
 
170
- if (removed.outcome === 'absent') {
283
+ if (removed.outcome === RemoveOutcomes.ABSENT) {
171
284
  return [];
172
285
  }
173
286
 
@@ -276,6 +389,7 @@ export const planAgentRemoval = (opts: {
276
389
  }
277
390
 
278
391
  actions.push(...planMcpRemoval({ root: opts.root, entry }));
392
+ actions.push(...planGuardsRemoval({ root: opts.root, entry }));
279
393
 
280
394
  if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
281
395
  sharedDone = true;
@@ -0,0 +1,48 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { dirname, join } from 'node:path';
3
+ import { ProjectLayout } from '../common/index.ts';
4
+ import { projectTmpOf } from '../hooks/project-tmp.ts';
5
+ import { SyncStatuses } from './common/index.ts';
6
+ import type { ISyncAction } from './common/index.ts';
7
+
8
+ /** Beside the other personal files of the developer, gitignored with them. */
9
+ export const CLAUDE_LAUNCH_FILE = `${ProjectLayout.LOCAL_DIRECTORY}/claude.launch.settings.json`;
10
+
11
+ /**
12
+ * What `claude --settings <this file>` adds to a session: `TMPDIR` and `CLAUDE_CODE_TMPDIR` in the project.
13
+ * Claude Code applies an `env` block given this way (and the variables in the launch environment, and the
14
+ * user settings file), but not the same block in the project's own settings, so this is the route that
15
+ * moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
16
+ * to one checkout of one developer.
17
+ */
18
+ export const renderClaudeLaunch = (opts: { root: string }): string => {
19
+ const folder = projectTmpOf({ root: opts.root });
20
+
21
+ return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
22
+ };
23
+
24
+ /** The launch file when it is missing or written for another folder; nothing to do when it is current. */
25
+ export const planClaudeLaunch = (opts: { root: string }): ISyncAction[] => {
26
+ const path = join(opts.root, CLAUDE_LAUNCH_FILE);
27
+ const text = renderClaudeLaunch({ root: opts.root });
28
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
29
+
30
+ if (before === text) {
31
+ return [];
32
+ }
33
+
34
+ return [
35
+ {
36
+ path,
37
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
38
+ note:
39
+ before === undefined
40
+ ? 'the Claude Code launch file is missing'
41
+ : 'the Claude Code launch file names another folder',
42
+ apply: () => {
43
+ mkdirSync(dirname(path), { recursive: true });
44
+ writeFileSync(path, text);
45
+ },
46
+ },
47
+ ];
48
+ };
package/src/sync/index.ts CHANGED
@@ -4,6 +4,7 @@ export * from './planner.ts';
4
4
  export * from './prune.ts';
5
5
  export * from './settings.ts';
6
6
  export * from './local-choice.ts';
7
+ export * from './claude-launch.ts';
7
8
  export * from './agent-files.ts';
8
9
  export * from './atlas-block.ts';
9
10
  export * from './exclude.ts';
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { LOCAL_AGENTS_FILE, renderLocalChoice } from '../agents/index.ts';
4
4
  import { ProjectLayout } from '../common/index.ts';
5
+ import { planClaudeLaunch } from './claude-launch.ts';
5
6
  import { SyncStatuses } from './common/index.ts';
6
7
  import type { ISyncAction } from './common/index.ts';
7
8
 
@@ -71,6 +72,7 @@ export const planLocalWorkspace = (opts: { root: string }): ISyncAction[] => {
71
72
 
72
73
  return [
73
74
  ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
75
+ ...planClaudeLaunch({ root: opts.root }),
74
76
  {
75
77
  path: directory,
76
78
  status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,