afyx-engineering-kit 0.0.0-stage → 0.1.0-alpha.3

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 (208) hide show
  1. package/.afyx-source-revision +1 -0
  2. package/LICENSE +21 -0
  3. package/README.md +377 -2
  4. package/SECURITY.md +74 -0
  5. package/afyx-context/LICENSE +21 -0
  6. package/afyx-context/README.md +155 -0
  7. package/afyx-context/afyx-context.json +30 -0
  8. package/afyx-context/contracts/integration-v1.schema.json +34 -0
  9. package/afyx-context/package-lock.json +53 -0
  10. package/afyx-context/package.json +34 -0
  11. package/afyx-context/scripts/benchmark.mjs +39 -0
  12. package/afyx-context/scripts/build.mjs +15 -0
  13. package/afyx-context/scripts/comparative-benchmark.mjs +342 -0
  14. package/afyx-context/scripts/comparative-worker.mjs +74 -0
  15. package/afyx-context/scripts/graph-integration-e2e.mjs +188 -0
  16. package/afyx-context/scripts/integrated-dogfood.mjs +309 -0
  17. package/afyx-context/src/budget.js +166 -0
  18. package/afyx-context/src/cli.js +110 -0
  19. package/afyx-context/src/coordination.js +343 -0
  20. package/afyx-context/src/engine.js +198 -0
  21. package/afyx-context/src/errors.js +14 -0
  22. package/afyx-context/src/graph-integration-worker.js +70 -0
  23. package/afyx-context/src/graph-integration.js +373 -0
  24. package/afyx-context/src/graph-mcp-bridge.js +103 -0
  25. package/afyx-context/src/index.js +25 -0
  26. package/afyx-context/src/integrations.js +87 -0
  27. package/afyx-context/src/memory.js +255 -0
  28. package/afyx-context/src/storage.js +364 -0
  29. package/afyx-context/test-fixtures/coordination-worker.mjs +52 -0
  30. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +1 -0
  31. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +4 -0
  32. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +1 -0
  33. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +5 -0
  34. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +1 -0
  35. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +10 -0
  36. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +2 -0
  37. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +20 -0
  38. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +11 -0
  39. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +2 -0
  40. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +14 -0
  41. package/afyx-forge/LICENSE +55 -0
  42. package/afyx-forge/README.md +126 -0
  43. package/afyx-forge/afyx-forge.json +28 -0
  44. package/afyx-forge/bin/afyx-forge +4 -0
  45. package/afyx-forge/bin/afyx-forge.cmd +3 -0
  46. package/afyx-forge/bin/afyx-forge.js +16 -0
  47. package/afyx-forge/contracts/forge-plan-v1.schema.json +172 -0
  48. package/afyx-forge/package.json +26 -0
  49. package/afyx-forge/src/classifier.js +190 -0
  50. package/afyx-forge/src/cli.js +111 -0
  51. package/afyx-forge/src/doctor.js +105 -0
  52. package/afyx-forge/src/guidance.js +120 -0
  53. package/afyx-forge/src/index.js +273 -0
  54. package/afyx-forge/src/planning.js +107 -0
  55. package/afyx-forge/src/policy.js +109 -0
  56. package/afyx-forge/src/workflow-refiner.js +151 -0
  57. package/afyx-graph/afyx-graph.json +20 -0
  58. package/afyx-graph/engine/LICENSE +21 -0
  59. package/afyx-graph/engine/README.md +104 -0
  60. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +21 -0
  61. package/afyx-graph/engine/release/SHA256SUMS +2 -0
  62. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  63. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  64. package/afyx-graph/engine/scripts/distribution-contract.mjs +212 -0
  65. package/afyx-graph/engine/scripts/distribution-product.json +33 -0
  66. package/bin/afyx-engineering-kit.mjs +61 -0
  67. package/install.ps1 +1053 -0
  68. package/install.sh +617 -0
  69. package/package.json +66 -4
  70. package/scripts/afyx-capability-orchestrator.mjs +752 -0
  71. package/scripts/afyx-claude-integration.mjs +547 -0
  72. package/scripts/afyx-context-artifact.mjs +105 -0
  73. package/scripts/afyx-credential-broker.mjs +75 -0
  74. package/scripts/afyx-doctor.ps1 +152 -0
  75. package/scripts/afyx-doctor.sh +146 -0
  76. package/scripts/afyx-forge-artifact.mjs +183 -0
  77. package/scripts/afyx-global-routing-policy.md +12 -0
  78. package/scripts/afyx-global-routing.mjs +168 -0
  79. package/scripts/afyx-graph-artifact.mjs +178 -0
  80. package/scripts/afyx-host-adapters.mjs +543 -0
  81. package/scripts/afyx-host-bridge-lifecycle.mjs +174 -0
  82. package/scripts/afyx-host-bridge.mjs +288 -0
  83. package/scripts/afyx-integration-contracts.mjs +825 -0
  84. package/scripts/afyx-mcp-integration.mjs +528 -0
  85. package/scripts/afyx-modular-integration.mjs +361 -0
  86. package/scripts/afyx-modular-runtime.mjs +451 -0
  87. package/scripts/afyx-native-skill-host.mjs +124 -0
  88. package/scripts/afyx-npm-installer.mjs +486 -0
  89. package/scripts/afyx-project.ps1 +205 -0
  90. package/scripts/afyx-project.sh +207 -0
  91. package/scripts/afyx-provider-backup.mjs +1206 -0
  92. package/scripts/afyx-provider-integration.mjs +724 -0
  93. package/scripts/afyx-provider-inventory.mjs +147 -0
  94. package/scripts/afyx-security-auditor.mjs +224 -0
  95. package/scripts/afyx-skill-engineering.mjs +354 -0
  96. package/scripts/afyx-tool-family-routing.mjs +64 -0
  97. package/scripts/afyx-universal-runtime.mjs +530 -0
  98. package/scripts/alpha_acceptance_preflight.py +240 -0
  99. package/scripts/benchmark-graph-memory.mjs +96 -0
  100. package/scripts/benchmark_capability_orchestrator.mjs +64 -0
  101. package/scripts/build-windows-installer.ps1 +259 -0
  102. package/scripts/build_forge_synthetic_image.py +328 -0
  103. package/scripts/check-reference-staleness.py +71 -0
  104. package/scripts/components.json +254 -0
  105. package/scripts/contracts/afyx-capability-request-v1.schema.json +189 -0
  106. package/scripts/contracts/afyx-capability-result-v1.schema.json +32 -0
  107. package/scripts/dogfood_engineering_comparison.mjs +303 -0
  108. package/scripts/engineering-assurance.json +28 -0
  109. package/scripts/install-afyx-context.ps1 +142 -0
  110. package/scripts/install-afyx-context.sh +126 -0
  111. package/scripts/install-afyx-forge.ps1 +265 -0
  112. package/scripts/install-afyx-forge.sh +273 -0
  113. package/scripts/install-afyx-graph.ps1 +571 -0
  114. package/scripts/install-afyx-graph.sh +438 -0
  115. package/scripts/install-codex-usage-tracker.ps1 +172 -0
  116. package/scripts/lib/AfyxComponents.psm1 +399 -0
  117. package/scripts/lib/AfyxSkillLifecycle.psm1 +289 -0
  118. package/scripts/lib/AfyxTerminal.psm1 +838 -0
  119. package/scripts/lib/afyx-components.sh +256 -0
  120. package/scripts/lib/afyx-skill-lifecycle.sh +271 -0
  121. package/scripts/link-global-dev.ps1 +193 -0
  122. package/scripts/link-global-dev.sh +130 -0
  123. package/scripts/phase8-paired-evidence.mjs +195 -0
  124. package/scripts/phase8-representative-workload.mjs +771 -0
  125. package/scripts/phase8-session-recorder.mjs +157 -0
  126. package/scripts/phase8_event_ledger.py +248 -0
  127. package/scripts/phase8_evidence_discovery.py +189 -0
  128. package/scripts/prepare-g6-package.mjs +349 -0
  129. package/scripts/resolve-git-release-artifacts.mjs +321 -0
  130. package/scripts/stage-npm-release.mjs +94 -0
  131. package/scripts/validate-afyx-graph.py +203 -0
  132. package/scripts/validate-components.py +194 -0
  133. package/scripts/validate-engineering-assurance.py +281 -0
  134. package/scripts/verify-graph-archive.mjs +64 -0
  135. package/skills/afyx-context/SKILL.md +26 -0
  136. package/skills/afyx-engineering-expert/README.md +42 -0
  137. package/skills/afyx-engineering-expert/SKILL.md +70 -0
  138. package/skills/afyx-engineering-expert/assets/result-template.md +15 -0
  139. package/skills/afyx-engineering-expert/references/ai-ml-engineer.md +17 -0
  140. package/skills/afyx-engineering-expert/references/business-analyst.md +17 -0
  141. package/skills/afyx-engineering-expert/references/clean-code-engineer.md +26 -0
  142. package/skills/afyx-engineering-expert/references/code-reviewer.md +24 -0
  143. package/skills/afyx-engineering-expert/references/cybersecurity-devsecops.md +17 -0
  144. package/skills/afyx-engineering-expert/references/data-analyst-bi.md +24 -0
  145. package/skills/afyx-engineering-expert/references/data-engineer.md +24 -0
  146. package/skills/afyx-engineering-expert/references/database-administrator.md +17 -0
  147. package/skills/afyx-engineering-expert/references/debugging-specialist.md +24 -0
  148. package/skills/afyx-engineering-expert/references/embedded-iot-engineer.md +24 -0
  149. package/skills/afyx-engineering-expert/references/erp-technical-specialist.md +17 -0
  150. package/skills/afyx-engineering-expert/references/hardware-diagnostics-auditor.md +24 -0
  151. package/skills/afyx-engineering-expert/references/hardware-electronics-engineer.md +24 -0
  152. package/skills/afyx-engineering-expert/references/integration-engineer.md +24 -0
  153. package/skills/afyx-engineering-expert/references/legacy-modernization-engineer.md +24 -0
  154. package/skills/afyx-engineering-expert/references/llmops-prompt-engineer.md +24 -0
  155. package/skills/afyx-engineering-expert/references/network-engineer.md +24 -0
  156. package/skills/afyx-engineering-expert/references/performance-benchmark-engineer.md +24 -0
  157. package/skills/afyx-engineering-expert/references/platform-engineer.md +24 -0
  158. package/skills/afyx-engineering-expert/references/product-manager.md +17 -0
  159. package/skills/afyx-engineering-expert/references/qa-engineer.md +17 -0
  160. package/skills/afyx-engineering-expert/references/site-reliability-engineer.md +17 -0
  161. package/skills/afyx-engineering-expert/references/software-engineer.md +17 -0
  162. package/skills/afyx-engineering-expert/references/solutions-architect.md +17 -0
  163. package/skills/afyx-engineering-expert/references/specialists-index.md +33 -0
  164. package/skills/afyx-engineering-expert/references/subject-matter-expert.md +17 -0
  165. package/skills/afyx-engineering-expert/references/system-analyst.md +17 -0
  166. package/skills/afyx-engineering-expert/references/technical-project-manager.md +24 -0
  167. package/skills/afyx-engineering-expert/references/technical-writer.md +24 -0
  168. package/skills/afyx-engineering-expert/references/ui-ux-designer.md +17 -0
  169. package/skills/afyx-engineering-expert/workflows/ai-data-erp.md +20 -0
  170. package/skills/afyx-engineering-expert/workflows/debugging.md +10 -0
  171. package/skills/afyx-engineering-expert/workflows/discovery-design.md +11 -0
  172. package/skills/afyx-engineering-expert/workflows/implementation.md +12 -0
  173. package/skills/afyx-engineering-expert/workflows/incident-reliability.md +12 -0
  174. package/skills/afyx-engineering-expert/workflows/review-audit.md +13 -0
  175. package/skills/afyx-forge/SKILL.md +43 -0
  176. package/skills/afyx-forge/references/adaptive-policy.md +19 -0
  177. package/skills/efficient-coding/SKILL.md +33 -0
  178. package/skills/efficient-coding/references/investigation.md +27 -0
  179. package/skills/efficient-coding/references/token-efficiency.md +25 -0
  180. package/skills/efficient-coding/references/tool-routing.md +13 -0
  181. package/skills/odoo-engineering/SKILL.md +33 -0
  182. package/skills/odoo-engineering/references/common.md +9 -0
  183. package/skills/odoo-engineering/references/odoo-10.md +32 -0
  184. package/skills/odoo-engineering/references/odoo-11.md +26 -0
  185. package/skills/odoo-engineering/references/odoo-12.md +31 -0
  186. package/skills/odoo-engineering/references/odoo-13.md +27 -0
  187. package/skills/odoo-engineering/references/odoo-14.md +31 -0
  188. package/skills/odoo-engineering/references/odoo-15.md +34 -0
  189. package/skills/odoo-engineering/references/odoo-16.md +37 -0
  190. package/skills/odoo-engineering/references/odoo-17.md +37 -0
  191. package/skills/odoo-engineering/references/odoo-18.md +48 -0
  192. package/skills/odoo-engineering/references/odoo-19.md +43 -0
  193. package/skills/odoo-engineering/references/odoo-20.md +39 -0
  194. package/skills/odoo-engineering/references/reference-schema.md +16 -0
  195. package/skills/odoo-engineering/references/version-detection.md +13 -0
  196. package/tools/codex-usage/CodexUsage.psm1 +496 -0
  197. package/tools/codex-usage/codex-usage-doctor.ps1 +150 -0
  198. package/tools/codex-usage/codex-usage-pricing.json +25 -0
  199. package/tools/codex-usage/codex-usage-stop.ps1 +167 -0
  200. package/tools/codex-usage/codex-usage-watch.ps1 +250 -0
  201. package/tools/codex-usage/vscode-user-task.json +31 -0
  202. package/tools/windows-setup/SetupBootstrapper.cs +258 -0
  203. package/uninstall.ps1 +189 -0
  204. package/uninstall.sh +167 -0
  205. package/update.ps1 +95 -0
  206. package/update.sh +67 -0
  207. package/verify.ps1 +411 -0
  208. package/verify.sh +265 -0
@@ -0,0 +1,528 @@
1
+ #!/usr/bin/env node
2
+ /** Consent-safe Codex MCP registration through the native `codex mcp` CLI. */
3
+ import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
4
+ import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
5
+ import { spawn, spawnSync } from 'node:child_process';
6
+ import { tmpdir } from 'node:os';
7
+ import { fileURLToPath } from 'node:url';
8
+ import {
9
+ createConfigurationBackup,
10
+ updateKnownState,
11
+ rollbackConfiguration,
12
+ validateUnrelatedPreserved,
13
+ readFileBytes,
14
+ } from './afyx-provider-backup.mjs';
15
+
16
+ function argument(name, fallback = '') {
17
+ const index = process.argv.indexOf(name);
18
+ return index >= 0 ? process.argv[index + 1] : fallback;
19
+ }
20
+
21
+ function normalized(value) {
22
+ return normalize(String(value || '')).toLowerCase();
23
+ }
24
+
25
+ function inside(base, candidate) {
26
+ const rel = relative(resolve(base), resolve(candidate));
27
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
28
+ }
29
+
30
+ function assertSafePath(base, candidate) {
31
+ if (!inside(base, candidate)) throw new McpIntegrationError('CODEX_PATH_UNSAFE', `Path outside Codex configuration boundary: ${candidate}`);
32
+ const boundary = resolve(base);
33
+ let cursor = resolve(candidate);
34
+ for (;;) {
35
+ if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
36
+ throw new McpIntegrationError('CODEX_PATH_UNSAFE', `Symlinked Codex configuration path was refused: ${cursor}`);
37
+ }
38
+ if (cursor === boundary) break;
39
+ const parent = dirname(cursor);
40
+ if (parent === cursor) break;
41
+ cursor = parent;
42
+ }
43
+ }
44
+
45
+ export function classifyEntry(existing, expected) {
46
+ if (!existing) return 'MCP_NOT_CONFIGURED';
47
+ const transport = existing.transport || {};
48
+ const args = Array.isArray(transport.args) ? transport.args : [];
49
+ const expectedNode = normalized(expected.node);
50
+ const actualNode = normalized(transport.command);
51
+ const executableName = (value) => basename(value).replace(/\.exe$/i, '');
52
+ const nodeMatches = actualNode === expectedNode || executableName(actualNode) === executableName(expectedNode);
53
+ const explicitArgs = Array.isArray(expected.args);
54
+ const expectedArgs = explicitArgs ? expected.args.map(String) : [expected.entry, 'serve', '--mcp'];
55
+ const afyxShape = explicitArgs
56
+ ? transport.type === 'stdio' && args.length === expectedArgs.length
57
+ && args.every((value, index) => normalized(value) === normalized(expectedArgs[index]))
58
+ : transport.type === 'stdio' && args.length === 3
59
+ && /(?:^|[\\/])(?:lib|engine)[\\/]dist[\\/]bin[\\/]afyx-graph\.js$/i.test(String(args[0]))
60
+ && args[1] === 'serve' && args[2] === '--mcp';
61
+ if (!afyxShape) return 'MCP_BLOCKED';
62
+ if (nodeMatches && (explicitArgs || normalized(args[0]) === normalized(expected.entry))) return 'MCP_CONFIGURED';
63
+ return 'MCP_STALE_OWNED';
64
+ }
65
+
66
+ class McpIntegrationError extends Error {
67
+ constructor(reason, message) {
68
+ super(message);
69
+ this.reason = reason;
70
+ }
71
+ }
72
+
73
+ const cmdMetaCharacters = /([()\][%!^"`<>&|;, *?])/g;
74
+
75
+ function escapeCmdCommand(value) {
76
+ return String(value).replace(cmdMetaCharacters, '^$1');
77
+ }
78
+
79
+ function escapeCmdArgument(value) {
80
+ let escaped = String(value)
81
+ .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
82
+ .replace(/(?=(\\+?)?)\1$/, '$1$1');
83
+ escaped = `"${escaped}"`.replace(cmdMetaCharacters, '^$1');
84
+ // npm .cmd shims add a second cmd.exe parsing boundary.
85
+ return escaped.replace(cmdMetaCharacters, '^$1');
86
+ }
87
+
88
+ function codexRun(codex, codexHome, args, configuredTimeout) {
89
+ const isWindowsCmd = process.platform === 'win32' && extname(codex).toLowerCase() === '.cmd';
90
+ const command = isWindowsCmd ? (process.env.ComSpec || process.env.COMSPEC || 'cmd.exe') : codex;
91
+ const commandArgs = isWindowsCmd
92
+ ? ['/d', '/s', '/c', `"${[escapeCmdCommand(codex), ...args.map(escapeCmdArgument)].join(' ')}"`]
93
+ : args;
94
+ const requested = Number(configuredTimeout);
95
+ const timeout = Number.isSafeInteger(requested) && requested > 0 ? Math.min(requested, 60_000) : 15_000;
96
+ return spawnSync(command, commandArgs, {
97
+ encoding: 'utf8',
98
+ env: { ...process.env, CODEX_HOME: codexHome },
99
+ windowsHide: true,
100
+ windowsVerbatimArguments: isWindowsCmd,
101
+ timeout,
102
+ maxBuffer: 1024 * 1024,
103
+ });
104
+ }
105
+
106
+ function commandDiagnostic(result) {
107
+ return String(result.stderr || result.stdout || result.error?.message || '').trim();
108
+ }
109
+
110
+ function requireCodexSuccess(result, action) {
111
+ if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
112
+ throw new McpIntegrationError('CODEX_TIMEOUT', `${action} timed out within the bounded provider execution window.`);
113
+ }
114
+ if (result.error || result.status === null) {
115
+ throw new McpIntegrationError(
116
+ 'CODEX_LAUNCH_FAILED',
117
+ `${action} could not launch Codex CLI: ${commandDiagnostic(result) || 'unknown process launch failure'}`,
118
+ );
119
+ }
120
+ if (result.status !== 0) {
121
+ throw new McpIntegrationError(
122
+ 'MCP_REGISTRATION_FAILED',
123
+ `${action} failed with exit code ${result.status}: ${commandDiagnostic(result) || 'no diagnostic output'}`,
124
+ );
125
+ }
126
+ return result;
127
+ }
128
+
129
+ function readExisting(codex, codexHome, providerTimeoutMs, server = 'afyx_graph') {
130
+ const result = codexRun(codex, codexHome, ['mcp', 'get', server, '--json'], providerTimeoutMs);
131
+ if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
132
+ throw new McpIntegrationError('CODEX_TIMEOUT', 'Codex MCP inspection timed out within the bounded provider execution window.');
133
+ }
134
+ if (result.error || result.status === null) {
135
+ throw new McpIntegrationError(
136
+ 'CODEX_LAUNCH_FAILED',
137
+ `Codex MCP inspection could not launch: ${commandDiagnostic(result) || 'unknown process launch failure'}`,
138
+ );
139
+ }
140
+ if (result.status !== 0) {
141
+ const diagnostic = commandDiagnostic(result);
142
+ if (/not found|not configured|no mcp server named/i.test(diagnostic)) {
143
+ return { existing: null, reason: 'MCP_ENTRY_NOT_FOUND' };
144
+ }
145
+ throw new McpIntegrationError(
146
+ 'MCP_INSPECTION_FAILED',
147
+ `Codex MCP inspection failed with exit code ${result.status}: ${diagnostic || 'no diagnostic output'}`,
148
+ );
149
+ }
150
+ try {
151
+ return { existing: JSON.parse(result.stdout), reason: '' };
152
+ } catch {
153
+ throw new McpIntegrationError('MCP_INVALID_CONFIGURATION', 'Codex returned invalid MCP configuration JSON.');
154
+ }
155
+ }
156
+
157
+ function backupConfig(codexHome) {
158
+ const config = resolve(codexHome, 'config.toml');
159
+ return createConfigurationBackup({
160
+ provider: 'codex',
161
+ configPath: config,
162
+ operation: 'codex-mcp',
163
+ });
164
+ }
165
+
166
+ function restoreBackup(backup) {
167
+ if (!backup) return false;
168
+ const res = rollbackConfiguration(backup);
169
+ return Boolean(res.restored);
170
+ }
171
+
172
+ function removeBackup(backup) {
173
+ // Retain recovery backup according to universal configuration management policy.
174
+ // Backups are preserved outside the repository with retention limits.
175
+ }
176
+
177
+ function fileBytes(file) {
178
+ return existsSync(file) ? readFileSync(file) : null;
179
+ }
180
+
181
+ function sameBytes(left, right) {
182
+ if (left === null || right === null) return left === right;
183
+ return left.equals(right);
184
+ }
185
+
186
+ function markBackupState(backup) {
187
+ if (backup) updateKnownState(backup);
188
+ }
189
+
190
+ function restoreFileGuarded(file, before, expected) {
191
+ if (!sameBytes(fileBytes(file), expected)) return false;
192
+ if (before === null) rmSync(file, { force: true });
193
+ else writeFileSync(file, before);
194
+ return sameBytes(fileBytes(file), before);
195
+ }
196
+
197
+ function ownershipPath(codexHome) {
198
+ return resolve(codexHome, '.afyx-provider-ownership.json');
199
+ }
200
+
201
+ function readOwnership(codexHome) {
202
+ const file = ownershipPath(codexHome);
203
+ if (!existsSync(file)) return { file, document: { schemaVersion: 1, entries: {} } };
204
+ try {
205
+ const document = JSON.parse(readFileSync(file, 'utf8'));
206
+ if (!document || Array.isArray(document) || typeof document !== 'object') throw new Error('root is not an object');
207
+ document.entries ||= {};
208
+ return { file, document };
209
+ } catch (error) {
210
+ throw new McpIntegrationError('MCP_INVALID_OWNERSHIP', `Codex ownership marker is invalid: ${error instanceof Error ? error.message : String(error)}`);
211
+ }
212
+ }
213
+
214
+ function writeOwnership(ownership) {
215
+ mkdirSync(dirname(ownership.file), { recursive: true });
216
+ const temporary = `${ownership.file}.tmp-${process.pid}`;
217
+ try {
218
+ writeFileSync(temporary, `${JSON.stringify(ownership.document, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
219
+ renameSync(temporary, ownership.file);
220
+ } finally {
221
+ rmSync(temporary, { force: true });
222
+ }
223
+ }
224
+
225
+ export async function probeMcp(node, entry, options = {}) {
226
+ return await new Promise((resolveHandshake) => {
227
+ const probeRoot = mkdtempSync(join(tmpdir(), 'afyx-mcp-probe-'));
228
+ const probeEnv = {
229
+ ...process.env,
230
+ AFYX_GRAPH_NO_DAEMON: '1',
231
+ AFYX_GRAPH_NO_WATCH: '1',
232
+ NODE_DISABLE_COMPILE_CACHE: '1',
233
+ NO_COLOR: '1',
234
+ };
235
+ // The installer probe validates the stdio/tool contract, not any caller's
236
+ // currently selected corpus. Inheriting an external-state binding here can
237
+ // make an otherwise healthy runtime inspect or bind unrelated project
238
+ // state before provider configuration has even been consented.
239
+ delete probeEnv.AFYX_GRAPH_STATE_DIR;
240
+ delete probeEnv.NODE_COMPILE_CACHE;
241
+ const launchArgs = Array.isArray(options.args) ? options.args : [entry, 'serve', '--mcp'];
242
+ const expectedTool = options.tool || 'afyx_graph_explore';
243
+ const child = spawn(node, launchArgs, {
244
+ cwd: probeRoot,
245
+ stdio: ['pipe', 'pipe', 'pipe'],
246
+ windowsHide: true,
247
+ env: probeEnv,
248
+ });
249
+ let buffer = '';
250
+ let stderr = '';
251
+ let initialized = false;
252
+ let settled = false;
253
+ const finish = (result) => {
254
+ if (settled) return;
255
+ settled = true;
256
+ clearTimeout(timer);
257
+ child.kill();
258
+ try { rmSync(probeRoot, { recursive: true, force: true }); } catch {
259
+ child.once('close', () => {
260
+ try { rmSync(probeRoot, { recursive: true, force: true }); } catch { /* best-effort temporary cleanup */ }
261
+ });
262
+ }
263
+ resolveHandshake(result);
264
+ };
265
+ const configuredTimeout = Number.parseInt(process.env.AFYX_MCP_HANDSHAKE_TIMEOUT_MS || '', 10);
266
+ const timeoutMs = Number.isSafeInteger(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : 15_000;
267
+ const timer = setTimeout(() => finish({ ok: false, detail: 'MCP initialize/tool discovery timed out.' }), timeoutMs);
268
+ child.on('error', (error) => finish({ ok: false, detail: error.message }));
269
+ child.on('exit', (code) => finish({ ok: false, detail: `MCP process exited with ${code}: ${stderr.trim() || 'no diagnostic output'}` }));
270
+ child.stderr.on('data', (chunk) => { stderr = `${stderr}${chunk.toString('utf8')}`.slice(-2_000); });
271
+ child.stdout.on('data', (chunk) => {
272
+ buffer += chunk.toString('utf8');
273
+ for (;;) {
274
+ const newline = buffer.indexOf('\n');
275
+ if (newline < 0) break;
276
+ const line = buffer.slice(0, newline).trim();
277
+ buffer = buffer.slice(newline + 1);
278
+ if (!line) continue;
279
+ let message;
280
+ try { message = JSON.parse(line); } catch { continue; }
281
+ if (message.id === 1 && !initialized) {
282
+ initialized = true;
283
+ child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
284
+ child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })}\n`);
285
+ } else if (message.id === 2) {
286
+ const names = message.result?.tools?.map((tool) => tool.name) || [];
287
+ finish(names.includes(expectedTool)
288
+ ? { ok: true, detail: `${names.length} tools discovered.` }
289
+ : { ok: false, detail: `MCP tools/list did not expose ${expectedTool}.` });
290
+ }
291
+ }
292
+ });
293
+ child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'afyx-installer', version: '1.0.0' } } })}\n`);
294
+ });
295
+ }
296
+
297
+ export async function integrate(options) {
298
+ const server = options.server || 'afyx_graph';
299
+ const launchArgs = Array.isArray(options.args) ? options.args.map(String) : [options.entry, 'serve', '--mcp'];
300
+ const expectedTool = options.tool || 'afyx_graph_explore';
301
+ const expected = Array.isArray(options.args)
302
+ ? { node: options.node, entry: options.entry, args: launchArgs }
303
+ : { node: options.node, entry: options.entry };
304
+ const result = {
305
+ graph: existsSync(options.entry) ? 'GRAPH_INSTALLED' : 'GRAPH_NOT_INSTALLED',
306
+ cli: existsSync(options.entry) && existsSync(options.node) ? 'CLI_REACHABLE' : 'CLI_BLOCKED',
307
+ mcp: 'MCP_BLOCKED',
308
+ changed: false,
309
+ reason: '',
310
+ detail: '',
311
+ };
312
+ try {
313
+ const codexHome = resolve(options.codexHome);
314
+ assertSafePath(codexHome, resolve(codexHome, 'config.toml'));
315
+ assertSafePath(codexHome, ownershipPath(codexHome));
316
+ } catch (error) {
317
+ result.reason = error instanceof McpIntegrationError ? error.reason : 'CODEX_PATH_UNSAFE';
318
+ result.detail = error instanceof Error ? error.message : String(error);
319
+ return result;
320
+ }
321
+ if (result.cli !== 'CLI_REACHABLE') {
322
+ if (options.uninstall) {
323
+ const codexHome = resolve(options.codexHome);
324
+ if (!existsSync(codexHome) || !options.codex || !existsSync(options.codex)) {
325
+ result.mcp = 'MCP_NOT_CONFIGURED';
326
+ result.detail = 'No Codex home exists; no MCP entry to remove.';
327
+ return result;
328
+ }
329
+ try {
330
+ const inspection = readExisting(options.codex, codexHome, options.providerTimeoutMs, server);
331
+ if (!inspection.existing) {
332
+ result.mcp = 'MCP_NOT_CONFIGURED';
333
+ result.detail = 'No Codex MCP entry is configured.';
334
+ return result;
335
+ }
336
+ } catch {
337
+ result.mcp = 'MCP_NOT_CONFIGURED';
338
+ result.detail = 'No Codex MCP entry is configured.';
339
+ return result;
340
+ }
341
+ } else {
342
+ result.reason = 'MCP_RUNTIME_UNAVAILABLE';
343
+ result.detail = 'Installed MCP entry point or Node.js executable is unavailable.';
344
+ return result;
345
+ }
346
+ }
347
+ if (!options.codex || !existsSync(options.codex)) {
348
+ result.reason = 'CODEX_UNAVAILABLE';
349
+ result.detail = 'Codex CLI is unavailable; Graph runtime remains healthy.';
350
+ return result;
351
+ }
352
+ // Inspection/planning must not create provider state or invoke a provider
353
+ // against a home that does not exist yet. Only an explicitly consented
354
+ // apply may prepare the first CODEX_HOME.
355
+ if (!existsSync(options.codexHome) && !options.apply) {
356
+ result.mcp = 'MCP_NOT_CONFIGURED';
357
+ result.reason = 'MCP_ENTRY_NOT_FOUND';
358
+ result.detail = 'No Codex home exists; registration is available but was not consented.';
359
+ return result;
360
+ }
361
+ if (options.apply) mkdirSync(options.codexHome, { recursive: true });
362
+ let inspection;
363
+ try {
364
+ inspection = readExisting(options.codex, options.codexHome, options.providerTimeoutMs, server);
365
+ } catch (error) {
366
+ result.reason = error instanceof McpIntegrationError ? error.reason : 'MCP_INSPECTION_FAILED';
367
+ result.detail = `Graph runtime is installed; MCP integration failed: ${error instanceof Error ? error.message : String(error)}`;
368
+ return result;
369
+ }
370
+ let existing = inspection.existing;
371
+ result.reason = inspection.reason;
372
+ let state = classifyEntry(existing, expected);
373
+ result.mcp = state;
374
+ if (state === 'MCP_BLOCKED') {
375
+ result.reason = 'MCP_INVALID_CONFIGURATION';
376
+ result.detail = `Conflicting or unproven ${server} entry was preserved.`;
377
+ return result;
378
+ }
379
+ let ownership;
380
+ try {
381
+ ownership = readOwnership(options.codexHome);
382
+ } catch (error) {
383
+ result.reason = error instanceof McpIntegrationError ? error.reason : 'MCP_INVALID_OWNERSHIP';
384
+ result.detail = error instanceof Error ? error.message : String(error);
385
+ return result;
386
+ }
387
+ if (options.uninstall) {
388
+ if (!existing) {
389
+ result.mcp = 'MCP_NOT_CONFIGURED';
390
+ result.detail = 'No Codex MCP entry is configured.';
391
+ return result;
392
+ }
393
+ const claim = ownership.document.entries?.[server];
394
+ const claimedExpected = claim?.provider === 'codex' ? claim.expected : null;
395
+ if (!claimedExpected || classifyEntry(existing, claimedExpected) !== 'MCP_CONFIGURED') {
396
+ result.mcp = 'MCP_BLOCKED';
397
+ result.reason = 'MCP_UNOWNED_ENTRY';
398
+ result.detail = `Codex ${server} entry lacks a matching Afyx ownership marker and was preserved.`;
399
+ return result;
400
+ }
401
+ if (!options.apply) {
402
+ result.detail = 'Owned Codex MCP removal is available but was not consented.';
403
+ return result;
404
+ }
405
+ const backup = backupConfig(options.codexHome);
406
+ const markerBefore = fileBytes(ownership.file);
407
+ let markerExpected = markerBefore;
408
+ try {
409
+ requireCodexSuccess(codexRun(options.codex, options.codexHome, ['mcp', 'remove', server], options.providerTimeoutMs), 'Codex MCP removal');
410
+ markBackupState(backup);
411
+ if (readExisting(options.codex, options.codexHome, options.providerTimeoutMs, server).existing) throw new Error('Codex MCP removal did not persist.');
412
+ delete ownership.document.entries[server];
413
+ if (Object.keys(ownership.document.entries).length) writeOwnership(ownership);
414
+ else rmSync(ownership.file, { force: true });
415
+ markerExpected = fileBytes(ownership.file);
416
+ removeBackup(backup);
417
+ const afterBytes = readFileBytes(backup.configPath);
418
+ const unrelatedValidation = validateUnrelatedPreserved({
419
+ format: 'toml',
420
+ beforeBytes: backup.originalBytes,
421
+ afterBytes,
422
+ server,
423
+ });
424
+ if (!unrelatedValidation.preserved) {
425
+ throw new Error(`Codex CLI altered unrelated configuration during removal: ${unrelatedValidation.detail}`);
426
+ }
427
+ result.mcp = 'MCP_NOT_CONFIGURED';
428
+ result.changed = true;
429
+ result.reason = '';
430
+ result.detail = `Owned Codex MCP entry removed; unrelated configuration preserved.${unrelatedValidation.normalized ? ' (provider-native TOML normalization verified)' : ''}`;
431
+ return result;
432
+ } catch (error) {
433
+ const rollback = rollbackConfiguration(backup, { reason: error instanceof Error ? error.message : String(error) });
434
+ const markerRestored = restoreFileGuarded(ownership.file, markerBefore, markerExpected);
435
+ const restored = rollback.restored && markerRestored;
436
+ result.mcp = 'MCP_BLOCKED';
437
+ result.changed = !restored;
438
+ result.reason = rollback.conflict
439
+ ? 'CONCURRENT_MODIFICATION_DETECTED'
440
+ : (restored ? 'MCP_REMOVAL_FAILED' : 'ROLLBACK_INCOMPLETE');
441
+ result.detail = `Codex MCP removal failed${restored ? ' and configuration was restored' : (rollback.conflict ? '; ' + rollback.reason : '; rollback was incomplete')}: ${error instanceof Error ? error.message : String(error)}`;
442
+ return result;
443
+ }
444
+ }
445
+ if (!options.apply && state !== 'MCP_CONFIGURED') {
446
+ result.detail = 'Registration is available but was not consented.';
447
+ return result;
448
+ }
449
+ if (options.apply && state !== 'MCP_CONFIGURED') {
450
+ const preflightProbe = await probeMcp(options.node, options.entry, { args: launchArgs, tool: expectedTool });
451
+ if (!preflightProbe.ok) {
452
+ result.mcp = 'MCP_HANDSHAKE_FAILED';
453
+ result.reason = 'MCP_HANDSHAKE_FAILED';
454
+ result.detail = `MCP configuration was not changed: ${preflightProbe.detail}`;
455
+ return result;
456
+ }
457
+ const backup = backupConfig(options.codexHome);
458
+ const ownershipBefore = existsSync(ownership.file) ? readFileSync(ownership.file) : null;
459
+ let ownershipExpected = ownershipBefore;
460
+ try {
461
+ if (state === 'MCP_STALE_OWNED') {
462
+ const removed = codexRun(options.codex, options.codexHome, ['mcp', 'remove', server], options.providerTimeoutMs);
463
+ requireCodexSuccess(removed, 'Codex MCP removal');
464
+ markBackupState(backup);
465
+ }
466
+ const added = codexRun(options.codex, options.codexHome, ['mcp', 'add', server, '--', options.node, ...launchArgs], options.providerTimeoutMs);
467
+ requireCodexSuccess(added, 'Codex MCP registration');
468
+ markBackupState(backup);
469
+ inspection = readExisting(options.codex, options.codexHome, options.providerTimeoutMs, server);
470
+ existing = inspection.existing;
471
+ state = classifyEntry(existing, expected);
472
+ if (state !== 'MCP_CONFIGURED') throw new Error('Codex MCP registration did not persist the expected direct-Node entry.');
473
+ result.changed = true;
474
+ result.reason = '';
475
+ ownership.document.entries[server] = { provider: 'codex', expected };
476
+ writeOwnership(ownership);
477
+ ownershipExpected = fileBytes(ownership.file);
478
+ removeBackup(backup);
479
+ const afterBytes = readFileBytes(backup.configPath);
480
+ const unrelatedValidation = validateUnrelatedPreserved({
481
+ format: 'toml',
482
+ beforeBytes: backup.originalBytes,
483
+ afterBytes,
484
+ server,
485
+ });
486
+ if (!unrelatedValidation.preserved) {
487
+ throw new Error(`Codex CLI altered unrelated configuration during registration: ${unrelatedValidation.detail}`);
488
+ }
489
+ } catch (error) {
490
+ const rollback = rollbackConfiguration(backup, { reason: error instanceof Error ? error.message : String(error) });
491
+ const ownershipRestored = restoreFileGuarded(ownership.file, ownershipBefore, ownershipExpected);
492
+ const restored = rollback.restored && ownershipRestored;
493
+ result.mcp = 'MCP_BLOCKED';
494
+ result.changed = !restored;
495
+ result.reason = rollback.conflict
496
+ ? 'CONCURRENT_MODIFICATION_DETECTED'
497
+ : (restored
498
+ ? (error instanceof McpIntegrationError ? error.reason : 'MCP_REGISTRATION_FAILED')
499
+ : 'ROLLBACK_INCOMPLETE');
500
+ result.detail = `Graph runtime is installed; MCP registration failed${restored ? ' and configuration was restored' : (rollback.conflict ? '; ' + rollback.reason : '; rollback was incomplete')}: ${error instanceof Error ? error.message : String(error)}`;
501
+ return result;
502
+ }
503
+ }
504
+ const probe = await probeMcp(options.node, options.entry, { args: launchArgs, tool: expectedTool });
505
+ result.mcp = probe.ok ? 'MCP_REACHABLE' : 'MCP_HANDSHAKE_FAILED';
506
+ result.reason = probe.ok ? '' : 'MCP_HANDSHAKE_FAILED';
507
+ result.detail = probe.detail;
508
+ return result;
509
+ }
510
+
511
+ if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
512
+ const options = {
513
+ node: resolve(argument('--node')),
514
+ entry: resolve(argument('--entry')),
515
+ codex: argument('--codex') ? resolve(argument('--codex')) : '',
516
+ codexHome: resolve(argument('--codex-home')),
517
+ providerTimeoutMs: Number(argument('--provider-timeout-ms', '15000')),
518
+ apply: process.argv.includes('--apply'),
519
+ uninstall: process.argv.includes('--uninstall'),
520
+ };
521
+ integrate(options).then((result) => {
522
+ console.log(JSON.stringify(result));
523
+ if (result.mcp === 'MCP_BLOCKED' || result.mcp === 'MCP_HANDSHAKE_FAILED') process.exitCode = 2;
524
+ }).catch((error) => {
525
+ console.error(`[mcp-integration] ${error instanceof Error ? error.message : String(error)}`);
526
+ process.exitCode = 1;
527
+ });
528
+ }