@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -1,41 +1,13 @@
1
- import { askWithPrompt } from '../create/names.ts';
2
- import { menusAvailable, promptMultiselect } from '../ui/index.ts';
1
+ import { ProjectNames } from '../create/names.ts';
2
+ import { TerminalCapability, TerminalPrompt } from '../ui/index.ts';
3
3
  import type { IAgentQuestion, TAgentResolution } from './common/index.ts';
4
4
  import { AgentConstants } from './common/index.ts';
5
- import { resolveAgents } from './resolve.ts';
6
- import { agentIds, readAgentTable } from './table.ts';
5
+ import { AgentSelection } from './resolve.ts';
6
+ import { AgentTable } from './table.ts';
7
7
 
8
8
  const listOf = (opts: { agents: string[] }): string =>
9
9
  opts.agents.length === 0 ? AgentConstants.NONE : opts.agents.join(', ');
10
10
 
11
- /**
12
- * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
13
- * choice stored on this machine when there is one, else it takes what was detected.
14
- */
15
- export const renderAgentsQuestion = (question: IAgentQuestion): string => {
16
- const enter =
17
- question.stored === undefined
18
- ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
19
- : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
20
-
21
- return [
22
- `Which coding agents do you use in this project? (comma-separated; ${enter})`,
23
- ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
24
- ...(question.stored === undefined
25
- ? []
26
- : [` chosen before: ${listOf({ agents: question.stored })}`]),
27
- ` available: ${[...agentIds(), AgentConstants.NONE].join(', ')}`,
28
- ].join('\n');
29
- };
30
-
31
- const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
32
- process.stdout.write(`${renderAgentsQuestion(question)}\n`);
33
-
34
- return askWithPrompt({ question: 'Agents' });
35
- };
36
-
37
- type TResolveAgentsInput = Omit<Parameters<typeof resolveAgents>[0], 'ask'>;
38
-
39
11
  const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefined => {
40
12
  const notes = [
41
13
  ...(opts.question.detected.includes(opts.id) ? ['detected'] : []),
@@ -48,11 +20,11 @@ const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefi
48
20
  /**
49
21
  * The checkbox menu: what this machine chose before is ticked, else what was detected. The first
50
22
  * pass of the resolution only learns whether it has to ask; the answer then goes back in as a list,
51
- * so the order in which sources are tried stays in `resolveAgents`.
23
+ * so the order in which sources are tried stays in `AgentSelection.resolve`.
52
24
  */
53
25
  const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentResolution> => {
54
26
  const questions: IAgentQuestion[] = [];
55
- const first = resolveAgents({
27
+ const first = AgentSelection.resolve({
56
28
  ...opts,
57
29
  ask: (question) => {
58
30
  questions.push(question);
@@ -66,9 +38,9 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
66
38
  return first;
67
39
  }
68
40
 
69
- const picked = await promptMultiselect({
41
+ const picked = await TerminalPrompt.promptMultiselect({
70
42
  message: 'Which coding agents do you use in this project?',
71
- choices: readAgentTable().map((entry) => ({
43
+ choices: AgentTable.read().map((entry) => ({
72
44
  value: entry.id,
73
45
  label: entry.name,
74
46
  hint: hintOf({ id: entry.id, question }),
@@ -76,7 +48,7 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
76
48
  initial: question.stored ?? question.detected,
77
49
  });
78
50
 
79
- return resolveAgents({
51
+ return AgentSelection.resolve({
80
52
  ...opts,
81
53
  ask: () => {
82
54
  if (picked === null) {
@@ -88,8 +60,39 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
88
60
  });
89
61
  };
90
62
 
91
- /** Menus in a terminal that can draw them, the plain question everywhere else. */
92
- export const resolveAgentsInTerminal = (opts: TResolveAgentsInput): Promise<TAgentResolution> =>
93
- menusAvailable()
94
- ? resolveAgentsWithMenu(opts)
95
- : Promise.resolve(resolveAgents({ ...opts, ask: askAgentsInTerminal }));
63
+ export class AgentsPrompt {
64
+ private static askAgentsInTerminal(question: IAgentQuestion): string | null {
65
+ process.stdout.write(`${AgentsPrompt.renderQuestion(question)}\n`);
66
+
67
+ return ProjectNames.askWithPrompt({ question: 'Agents' });
68
+ }
69
+
70
+ /**
71
+ * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
72
+ * choice stored on this machine when there is one, else it takes what was detected.
73
+ */
74
+ static renderQuestion(question: IAgentQuestion): string {
75
+ const enter =
76
+ question.stored === undefined
77
+ ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
78
+ : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
79
+
80
+ return [
81
+ `Which coding agents do you use in this project? (comma-separated; ${enter})`,
82
+ ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
83
+ ...(question.stored === undefined
84
+ ? []
85
+ : [` chosen before: ${listOf({ agents: question.stored })}`]),
86
+ ` available: ${[...AgentTable.agentIds(), AgentConstants.NONE].join(', ')}`,
87
+ ].join('\n');
88
+ }
89
+
90
+ /** Menus in a terminal that can draw them, the plain question everywhere else. */
91
+ static resolveInTerminal(opts: TResolveAgentsInput): Promise<TAgentResolution> {
92
+ return TerminalCapability.menusAvailable()
93
+ ? resolveAgentsWithMenu(opts)
94
+ : Promise.resolve(AgentSelection.resolve({ ...opts, ask: AgentsPrompt.askAgentsInTerminal }));
95
+ }
96
+ }
97
+
98
+ type TResolveAgentsInput = Omit<Parameters<typeof AgentSelection.resolve>[0], 'ask'>;
@@ -9,232 +9,238 @@ const SERVER_NAME = 'atlas';
9
9
 
10
10
  type TMergeResult = { ok: true; changed: boolean; text: string } | { ok: false; reason: string };
11
11
 
12
- /**
13
- * The atlas server as a per-machine file starts it: the project's own `vulcan` by absolute path with
14
- * an absolute `--root`, so it does not matter which directory the agent launches the server from.
15
- */
16
- export const atlasServerEntry = (opts: { root: string }): { command: string; args: string[] } => ({
17
- command: 'bun',
18
- args: [
19
- join(opts.root, 'node_modules', '.bin', 'vulcan'),
20
- 'x',
21
- 'atlas',
22
- 'mcp',
23
- '--root',
24
- opts.root,
25
- ],
26
- });
27
-
28
- /**
29
- * The atlas server as the root `.mcp.json` starts it: the same for every developer, so it is relative.
30
- * Claude Code, omp and Copilot CLI launch a project server from the project root.
31
- */
32
- export const canonicalAtlasEntry = (): { command: string; args: string[] } => ({
33
- command: 'bun',
34
- args: ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
35
- });
36
-
37
- /**
38
- * Whether an `atlas` entry is the one sync writes, for whatever place: `bun <root>/node_modules/.bin/vulcan
39
- * x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing, or the relative
40
- * entry of the root `.mcp.json`. Anything else is the user's. A project that moved is recognised this way
41
- * and rewritten.
42
- */
43
- const isOwnEntry = (opts: { entry: unknown }): boolean => {
44
- const { entry } = opts;
45
-
46
- if (!RecordValue.isRecord(entry) || entry.command !== 'bun' || !Array.isArray(entry.args)) {
47
- return false;
12
+ export class McpConfig {
13
+ /**
14
+ * Whether an `atlas` entry is the one sync writes, for whatever place: `bun <root>/node_modules/.bin/vulcan
15
+ * x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing, or the relative
16
+ * entry of the root `.mcp.json`. Anything else is the user's. A project that moved is recognised this way
17
+ * and rewritten.
18
+ */
19
+ private static isOwnEntry(opts: { entry: unknown }): boolean {
20
+ const { entry } = opts;
21
+
22
+ if (!RecordValue.isRecord(entry) || entry.command !== 'bun' || !Array.isArray(entry.args)) {
23
+ return false;
24
+ }
25
+
26
+ if (JSON.stringify(entry) === JSON.stringify(McpConfig.canonicalAtlasEntry())) {
27
+ return true;
28
+ }
29
+
30
+ const keys = Object.keys(entry).filter((key) => key !== 'type');
31
+ const [bin, ...rest] = entry.args;
32
+ const root = rest[4];
33
+
34
+ return (
35
+ keys.length === 2 &&
36
+ (entry.type === undefined || entry.type === 'stdio') &&
37
+ entry.args.length === 6 &&
38
+ rest.slice(0, 4).join(' ') === 'x atlas mcp --root' &&
39
+ typeof root === 'string' &&
40
+ bin === join(root, 'node_modules', '.bin', 'vulcan')
41
+ );
48
42
  }
49
43
 
50
- if (JSON.stringify(entry) === JSON.stringify(canonicalAtlasEntry())) {
51
- return true;
44
+ private static codexBlock(opts: { root: string }): string {
45
+ const { command, args } = McpConfig.atlasServerEntry({ root: opts.root });
46
+
47
+ return [
48
+ CODEX_BLOCK_START,
49
+ CODEX_TABLE,
50
+ `command = ${JSON.stringify(command)}`,
51
+ `args = [${args.map((arg) => JSON.stringify(arg)).join(', ')}]`,
52
+ CODEX_BLOCK_END,
53
+ '',
54
+ ].join('\n');
52
55
  }
53
56
 
54
- const keys = Object.keys(entry).filter((key) => key !== 'type');
55
- const [bin, ...rest] = entry.args;
56
- const root = rest[4];
57
-
58
- return (
59
- keys.length === 2 &&
60
- (entry.type === undefined || entry.type === 'stdio') &&
61
- entry.args.length === 6 &&
62
- rest.slice(0, 4).join(' ') === 'x atlas mcp --root' &&
63
- typeof root === 'string' &&
64
- bin === join(root, 'node_modules', '.bin', 'vulcan')
65
- );
66
- };
67
-
68
- /**
69
- * Sets the `atlas` server in a JSON file's server map and nothing else: the user's keys, servers and
70
- * order stay, an `atlas` entry sync wrote for another place is rewritten for this one, and any other
71
- * `atlas` entry is the user's and is left as it is.
72
- */
73
- export const mergeMcpServers = (opts: {
74
- text: string | undefined;
75
- key: string;
76
- entry: Record<string, unknown>;
77
- }): TMergeResult => {
78
- let document: Record<string, unknown> = {};
79
-
80
- if (opts.text !== undefined) {
81
- let parsed: unknown;
57
+ /**
58
+ * The atlas server as a per-machine file starts it: the project's own `vulcan` by absolute path with
59
+ * an absolute `--root`, so it does not matter which directory the agent launches the server from.
60
+ */
61
+ static atlasServerEntry(opts: { root: string }): { command: string; args: string[] } {
62
+ return {
63
+ command: 'bun',
64
+ args: [
65
+ join(opts.root, 'node_modules', '.bin', 'vulcan'),
66
+ 'x',
67
+ 'atlas',
68
+ 'mcp',
69
+ '--root',
70
+ opts.root,
71
+ ],
72
+ };
73
+ }
82
74
 
83
- try {
84
- parsed = JSON.parse(opts.text);
85
- } catch {
86
- return { ok: false, reason: 'not valid JSON' };
75
+ /**
76
+ * The atlas server as the root `.mcp.json` starts it: the same for every developer, so it is relative.
77
+ * Claude Code, omp and Copilot CLI launch a project server from the project root.
78
+ */
79
+ static canonicalAtlasEntry(): { command: string; args: string[] } {
80
+ return {
81
+ command: 'bun',
82
+ args: ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
83
+ };
84
+ }
85
+
86
+ /**
87
+ * Sets the `atlas` server in a JSON file's server map and nothing else: the user's keys, servers and
88
+ * order stay, an `atlas` entry sync wrote for another place is rewritten for this one, and any other
89
+ * `atlas` entry is the user's and is left as it is.
90
+ */
91
+ static mergeServers(opts: {
92
+ text: string | undefined;
93
+ key: string;
94
+ entry: Record<string, unknown>;
95
+ }): TMergeResult {
96
+ let document: Record<string, unknown> = {};
97
+
98
+ if (opts.text !== undefined) {
99
+ let parsed: unknown;
100
+
101
+ try {
102
+ parsed = JSON.parse(opts.text);
103
+ } catch {
104
+ return { ok: false, reason: 'not valid JSON' };
105
+ }
106
+
107
+ if (!RecordValue.isRecord(parsed)) {
108
+ return { ok: false, reason: 'not a JSON object' };
109
+ }
110
+
111
+ document = parsed;
87
112
  }
88
113
 
89
- if (!RecordValue.isRecord(parsed)) {
90
- return { ok: false, reason: 'not a JSON object' };
114
+ const servers = document[opts.key] ?? {};
115
+
116
+ if (!RecordValue.isRecord(servers)) {
117
+ return { ok: false, reason: `${opts.key} is not an object` };
91
118
  }
92
119
 
93
- document = parsed;
94
- }
120
+ const existing = servers[SERVER_NAME];
95
121
 
96
- const servers = document[opts.key] ?? {};
122
+ if (Object.hasOwn(servers, SERVER_NAME) && !McpConfig.isOwnEntry({ entry: existing })) {
123
+ return { ok: true, changed: false, text: opts.text ?? '' };
124
+ }
97
125
 
98
- if (!RecordValue.isRecord(servers)) {
99
- return { ok: false, reason: `${opts.key} is not an object` };
100
- }
126
+ if (
127
+ Object.hasOwn(servers, SERVER_NAME) &&
128
+ JSON.stringify(existing) === JSON.stringify(opts.entry)
129
+ ) {
130
+ return { ok: true, changed: false, text: opts.text ?? '' };
131
+ }
101
132
 
102
- const existing = servers[SERVER_NAME];
133
+ const text = `${JSON.stringify(
134
+ { ...document, [opts.key]: { ...servers, [SERVER_NAME]: opts.entry } },
135
+ null,
136
+ 2,
137
+ )}\n`;
103
138
 
104
- if (Object.hasOwn(servers, SERVER_NAME) && !isOwnEntry({ entry: existing })) {
105
- return { ok: true, changed: false, text: opts.text ?? '' };
139
+ return { ok: true, changed: true, text };
106
140
  }
107
141
 
108
- if (
109
- Object.hasOwn(servers, SERVER_NAME) &&
110
- JSON.stringify(existing) === JSON.stringify(opts.entry)
111
- ) {
112
- return { ok: true, changed: false, text: opts.text ?? '' };
113
- }
142
+ /**
143
+ * The atlas entry as a marker-delimited block of `.codex/config.toml`: no TOML writer is needed, and
144
+ * a later sync replaces only what sits between the markers.
145
+ */
146
+ static mergeCodexToml(opts: { text: string | undefined; root: string }): TMergeResult {
147
+ const block = McpConfig.codexBlock({ root: opts.root });
114
148
 
115
- const text = `${JSON.stringify(
116
- { ...document, [opts.key]: { ...servers, [SERVER_NAME]: opts.entry } },
117
- null,
118
- 2,
119
- )}\n`;
120
-
121
- return { ok: true, changed: true, text };
122
- };
123
-
124
- const codexBlock = (opts: { root: string }): string => {
125
- const { command, args } = atlasServerEntry({ root: opts.root });
126
-
127
- return [
128
- CODEX_BLOCK_START,
129
- CODEX_TABLE,
130
- `command = ${JSON.stringify(command)}`,
131
- `args = [${args.map((arg) => JSON.stringify(arg)).join(', ')}]`,
132
- CODEX_BLOCK_END,
133
- '',
134
- ].join('\n');
135
- };
136
-
137
- /**
138
- * The atlas entry as a marker-delimited block of `.codex/config.toml`: no TOML writer is needed, and
139
- * a later sync replaces only what sits between the markers.
140
- */
141
- export const mergeCodexToml = (opts: { text: string | undefined; root: string }): TMergeResult => {
142
- const block = codexBlock({ root: opts.root });
143
-
144
- if (opts.text === undefined || opts.text === '') {
145
- return { ok: true, changed: true, text: block };
146
- }
149
+ if (opts.text === undefined || opts.text === '') {
150
+ return { ok: true, changed: true, text: block };
151
+ }
147
152
 
148
- const start = opts.text.indexOf(CODEX_BLOCK_START);
149
- const end = opts.text.indexOf(CODEX_BLOCK_END);
153
+ const start = opts.text.indexOf(CODEX_BLOCK_START);
154
+ const end = opts.text.indexOf(CODEX_BLOCK_END);
150
155
 
151
- if (start !== -1 && end > start) {
152
- const after = end + CODEX_BLOCK_END.length;
153
- const rest = opts.text.slice(after).replace(/^\n/, '');
154
- const text = `${opts.text.slice(0, start)}${block}${rest}`;
156
+ if (start !== -1 && end > start) {
157
+ const after = end + CODEX_BLOCK_END.length;
158
+ const rest = opts.text.slice(after).replace(/^\n/, '');
159
+ const text = `${opts.text.slice(0, start)}${block}${rest}`;
155
160
 
156
- return { ok: true, changed: text !== opts.text, text };
157
- }
161
+ return { ok: true, changed: text !== opts.text, text };
162
+ }
163
+
164
+ if (opts.text.includes(CODEX_TABLE)) {
165
+ return {
166
+ ok: false,
167
+ reason: 'a [mcp_servers.atlas] table is already there outside the vulcan markers',
168
+ };
169
+ }
158
170
 
159
- if (opts.text.includes(CODEX_TABLE)) {
160
171
  return {
161
- ok: false,
162
- reason: 'a [mcp_servers.atlas] table is already there outside the vulcan markers',
172
+ ok: true,
173
+ changed: true,
174
+ text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${block}`,
163
175
  };
164
176
  }
165
177
 
166
- return {
167
- ok: true,
168
- changed: true,
169
- text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${block}`,
170
- };
171
- };
178
+ /**
179
+ * Takes sync's own atlas entry out of a JSON server map. The file is deleted (`text` undefined) when
180
+ * nothing else is left in it; an entry of another shape is the user's and is reported, not removed.
181
+ */
182
+ static removeEntry(opts: { text: string; key: string }): TRemoveResult {
183
+ let document: unknown;
172
184
 
173
- type TRemoveResult =
174
- | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
175
- | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
176
- | { ok: false; reason: string };
185
+ try {
186
+ document = JSON.parse(opts.text);
187
+ } catch {
188
+ return { ok: false, reason: 'not valid JSON - left untouched' };
189
+ }
177
190
 
178
- /**
179
- * Takes sync's own atlas entry out of a JSON server map. The file is deleted (`text` undefined) when
180
- * nothing else is left in it; an entry of another shape is the user's and is reported, not removed.
181
- */
182
- export const removeMcpEntry = (opts: { text: string; key: string }): TRemoveResult => {
183
- let document: unknown;
184
-
185
- try {
186
- document = JSON.parse(opts.text);
187
- } catch {
188
- return { ok: false, reason: 'not valid JSON - left untouched' };
189
- }
191
+ if (!RecordValue.isRecord(document)) {
192
+ return { ok: false, reason: 'not a JSON object - left untouched' };
193
+ }
190
194
 
191
- if (!RecordValue.isRecord(document)) {
192
- return { ok: false, reason: 'not a JSON object - left untouched' };
193
- }
195
+ const servers = document[opts.key];
194
196
 
195
- const servers = document[opts.key];
197
+ if (!RecordValue.isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
198
+ return { ok: true, outcome: RemoveOutcomes.ABSENT };
199
+ }
196
200
 
197
- if (!RecordValue.isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
198
- return { ok: true, outcome: RemoveOutcomes.ABSENT };
199
- }
201
+ if (!McpConfig.isOwnEntry({ entry: servers[SERVER_NAME] })) {
202
+ return { ok: false, reason: 'the atlas entry is not the one sync wrote - left alone' };
203
+ }
200
204
 
201
- if (!isOwnEntry({ entry: servers[SERVER_NAME] })) {
202
- return { ok: false, reason: 'the atlas entry is not the one sync wrote - left alone' };
203
- }
205
+ const otherServers = Object.fromEntries(
206
+ Object.entries(servers).filter(([name]) => name !== SERVER_NAME),
207
+ );
208
+ const otherKeys = Object.fromEntries(
209
+ Object.entries(document).filter(([key]) => key !== opts.key),
210
+ );
211
+ const remaining =
212
+ Object.keys(otherServers).length === 0
213
+ ? otherKeys
214
+ : { ...document, [opts.key]: otherServers };
215
+ const onlyEmptyInputs = Object.entries(remaining).every(
216
+ ([key, value]) => key === 'inputs' && Array.isArray(value) && value.length === 0,
217
+ );
204
218
 
205
- const otherServers = Object.fromEntries(
206
- Object.entries(servers).filter(([name]) => name !== SERVER_NAME),
207
- );
208
- const otherKeys = Object.fromEntries(
209
- Object.entries(document).filter(([key]) => key !== opts.key),
210
- );
211
- const remaining =
212
- Object.keys(otherServers).length === 0 ? otherKeys : { ...document, [opts.key]: otherServers };
213
- const onlyEmptyInputs = Object.entries(remaining).every(
214
- ([key, value]) => key === 'inputs' && Array.isArray(value) && value.length === 0,
215
- );
216
-
217
- return {
218
- ok: true,
219
- outcome: RemoveOutcomes.REMOVED,
220
- text: onlyEmptyInputs ? undefined : `${JSON.stringify(remaining, null, 2)}\n`,
221
- };
222
- };
223
-
224
- /** Takes the marker block out of `.codex/config.toml`; `text` is undefined when nothing else is left. */
225
- export const removeCodexBlock = (opts: {
226
- text: string;
227
- }): { changed: boolean; text: string | undefined } => {
228
- const start = opts.text.indexOf(CODEX_BLOCK_START);
229
- const end = opts.text.indexOf(CODEX_BLOCK_END);
230
-
231
- if (start === -1 || end < start) {
232
- return { changed: false, text: opts.text };
219
+ return {
220
+ ok: true,
221
+ outcome: RemoveOutcomes.REMOVED,
222
+ text: onlyEmptyInputs ? undefined : `${JSON.stringify(remaining, null, 2)}\n`,
223
+ };
233
224
  }
234
225
 
235
- const before = opts.text.slice(0, start).replace(/\n+$/, '\n');
236
- const after = opts.text.slice(end + CODEX_BLOCK_END.length).replace(/^\n+/, '');
237
- const text = `${before}${before !== '' && after !== '' ? '\n' : ''}${after}`;
226
+ /** Takes the marker block out of `.codex/config.toml`; `text` is undefined when nothing else is left. */
227
+ static removeCodexBlock(opts: { text: string }): { changed: boolean; text: string | undefined } {
228
+ const start = opts.text.indexOf(CODEX_BLOCK_START);
229
+ const end = opts.text.indexOf(CODEX_BLOCK_END);
230
+
231
+ if (start === -1 || end < start) {
232
+ return { changed: false, text: opts.text };
233
+ }
234
+
235
+ const before = opts.text.slice(0, start).replace(/\n+$/, '\n');
236
+ const after = opts.text.slice(end + CODEX_BLOCK_END.length).replace(/^\n+/, '');
237
+ const text = `${before}${before !== '' && after !== '' ? '\n' : ''}${after}`;
238
238
 
239
- return { changed: true, text: text.trim() === '' ? undefined : text };
240
- };
239
+ return { changed: true, text: text.trim() === '' ? undefined : text };
240
+ }
241
+ }
242
+
243
+ type TRemoveResult =
244
+ | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
245
+ | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
246
+ | { ok: false; reason: string };