@vulcan-energy/mcp-helper 0.2.5 → 0.3.1

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.
@@ -1,4 +1,5 @@
1
- // Local MCP/CLI transport for the app's exact target preparation and workers.
1
+ // Local MCP/CLI transport: verified target bundles, and the app's target workers in Chrome.
2
+ // Preparation runs in Node (preparation.mjs); Chrome is needed only to run an engine.
2
3
  import { readFile, writeFile, mkdir, realpath, open, unlink, rename } from 'node:fs/promises';
3
4
  import { homedir } from 'node:os';
4
5
  import { createHash, randomUUID } from 'node:crypto';
@@ -8,24 +9,30 @@ import { fileURLToPath } from 'node:url';
8
9
 
9
10
  const hash = bytes => createHash('sha256').update(bytes).digest('hex');
10
11
  const RELEASE_ORIGIN = 'https://usevulcan.app';
12
+ // Catalogue ids: lower-case words joined by '-' or '.' (the EPC id carries its version, 0.13.2); never '..'.
13
+ const BUNDLE_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
11
14
  // As targets.ts:modelArtifacts: not source archives or notices, and not a pinned converter
12
15
  // that is not also the runtime. The host converts with the package's own WASM.
13
16
  const isModelArtifact = (manifest, path) => !path.startsWith('source/') && !path.startsWith('notices/')
14
17
  && !([manifest.preparation?.javascript, manifest.preparation?.wasm].includes(path) && ![manifest.runtime?.javascript, manifest.runtime?.wasm].includes(path));
18
+ // Preparation reads only the pinned schema, defaults and product data (targetPreparation.ts:preparationManifest).
19
+ const isSelected = (manifest, path, preparationOnly) => preparationOnly
20
+ ? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path) || (!!manifest.runtime?.data && path.startsWith(manifest.runtime.data))
21
+ : isModelArtifact(manifest, path);
15
22
  function assertArtifactPath(path) {
16
23
  if (!path || path.includes('\\') || path.startsWith('/') || path.split('/').some(part => !part || part === '..' || part === '.')) throw new Error('Invalid target artifact path');
17
24
  }
18
- export async function readVerifiedBundle(manifestPath, expectedHash) {
25
+ export async function readVerifiedBundle(manifestPath, expectedHash, { preparationOnly = false } = {}) {
19
26
  if (!/^[a-f0-9]{64}$/.test(expectedHash ?? '')) throw new Error('Supply the exact target manifest SHA-256; local bundles are never inferred or upgraded.');
20
27
  const bytes = await readFile(manifestPath);
21
28
  if (hash(bytes) !== expectedHash) throw new Error('Target manifest hash mismatch');
22
29
  const manifest = JSON.parse(bytes);
23
- if (!/^[a-z0-9-]+$/.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
30
+ if (!BUNDLE_ID.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
24
31
  const root = await realpath(dirname(manifestPath));
25
32
  const routes = new Map();
26
33
  for (const artifact of manifest.artifacts) {
27
34
  assertArtifactPath(artifact.path);
28
- if (!isModelArtifact(manifest, artifact.path)) continue;
35
+ if (!isSelected(manifest, artifact.path, preparationOnly)) continue;
29
36
  const file = await realpath(resolve(root, artifact.path));
30
37
  if (!file.startsWith(root + sep)) throw new Error('Target artifact escapes bundle directory');
31
38
  const contents = await readFile(file);
@@ -35,33 +42,18 @@ export async function readVerifiedBundle(manifestPath, expectedHash) {
35
42
  return { manifest, routes };
36
43
  }
37
44
 
38
- /** The package's own WASM, served at /app/: the glue, the binary, the version file, and the glue's relative imports. */
39
- export async function readPackageWasm(wasmDir) {
40
- if (!wasmDir) throw new Error('No WASM directory given: target preparation converts with the package\'s own WASM.');
41
- const read = name => readFile(join(wasmDir, name)).catch(() => {
42
- throw new Error(`The package WASM is incomplete: ${join(wasmDir, name)} is missing. Reinstall the package, or pass a complete WASM directory.`);
43
- });
44
- const [version, glue, binary] = await Promise.all(['wasm_version.json', 'wasm_wrapper.js', 'wasm_wrapper_bg.wasm'].map(read));
45
- const info = JSON.parse(version);
46
- // The glue and binary are checked against wasm_version.json. The wasm-bindgen-rayon snippets/ file the Free glue
47
- // imports is served unhashed: the version file has no hash for it. This catches a mismatched build; it is not a security boundary.
48
- for (const key of ['js_sha256', 'sha256']) if (!info[key]) throw new Error(`${join(wasmDir, 'wasm_version.json')} has no ${key}`);
49
- if (hash(glue) !== info.js_sha256 || hash(binary) !== info.sha256) throw new Error(`The WASM in ${wasmDir} does not match its wasm_version.json`);
50
- const routes = new Map([['/app/wasm_version.json', version], ['/app/wasm_wrapper.js', glue], ['/app/wasm_wrapper_bg.wasm', binary]]);
51
- // The same import scan deploy-mcp.sh uses to copy these files into the package.
52
- for (const [, path] of glue.toString().matchAll(/(?:from |import\()['"]\.\/([^'"]+)/g)) {
53
- assertArtifactPath(path);
54
- routes.set(`/app/${path}`, await read(path));
55
- }
56
- return routes;
45
+ async function releaseTables() {
46
+ try { return await import('./release-manifests.mjs'); }
47
+ catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
48
+ }
49
+ /** The target a saved pin runs on: the replacement of a retired pin (targets.ts RETIRED_HEM_TARGETS), else the pin. */
50
+ export async function currentBundleId(bundleId, retired) {
51
+ retired ??= (await releaseTables()).RETIRED_HEM_TARGETS;
52
+ return Object.hasOwn(retired, bundleId) ? retired[bundleId].replacement : bundleId;
57
53
  }
58
-
59
54
  async function releasePin(bundleId, pins) {
60
- if (!pins) {
61
- try { pins = (await import('./release-manifests.mjs')).RELEASE_MANIFEST_HASHES; }
62
- catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
63
- }
64
- const expected = /^[a-z0-9-]+$/.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
55
+ pins ??= (await releaseTables()).RELEASE_MANIFEST_HASHES;
56
+ const expected = BUNDLE_ID.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
65
57
  if (!expected) throw new Error(`HEM target '${bundleId}' is not supported by this version; update @vulcan-energy/mcp-helper or @vulcan-energy/analyst, whichever you are running`);
66
58
  return expected;
67
59
  }
@@ -73,7 +65,7 @@ async function writeAtomic(file, bytes) {
73
65
  }
74
66
  // The largest released artifact is ~14 MB, so five minutes per request needs only ~50 kB/s.
75
67
  const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
76
- async function fetchBytes(fetcher, bundleId, url, timeoutMs) {
68
+ async function fetchBytes(fetcher, bundleId, url, timeoutMs, root) {
77
69
  let response, bytes;
78
70
  // The signal also bounds reading the body, so a stalled transfer cannot hold the workspace lock.
79
71
  const controller = new AbortController();
@@ -82,27 +74,30 @@ async function fetchBytes(fetcher, bundleId, url, timeoutMs) {
82
74
  response = await fetcher(url, { cache: 'no-store', signal: controller.signal });
83
75
  if (response.ok) bytes = Buffer.from(await response.arrayBuffer());
84
76
  } catch (error) {
85
- if (controller.signal.aborted) throw new Error(`HEM target ${bundleId} download timed out after ${timeoutMs / 1000} s: ${url}. Check your connection and retry, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
86
- throw new Error(`Could not download HEM target ${bundleId} from ${url} (${error.cause?.message ?? error.message}). Check your connection, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
77
+ if (controller.signal.aborted) throw new Error(`HEM target ${bundleId} download timed out after ${timeoutMs / 1000} s: ${url} (cache: ${root}). Check your connection and retry, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
78
+ throw new Error(`Could not download HEM target ${bundleId} from ${url} into ${root} (${error.cause?.message ?? error.message}). This target is not in the cache yet. Check your connection, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
87
79
  } finally { clearTimeout(timer); }
88
- if (!response.ok) throw new Error(`HEM target download failed (${response.status}): ${url}`);
80
+ if (!response.ok) throw new Error(`HEM target download failed (${response.status}): ${url} (cache: ${root})`);
89
81
  return bytes;
90
82
  }
91
83
 
92
84
  /** Resolve a released bundle into a local cache, verified against the pins compiled into this helper. */
93
- export async function resolveReleaseBundle(bundleId, { cacheDir = join(homedir(), '.cache/vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS } = {}) {
85
+ // The user cache (XDG_CACHE_HOME, as other tools read it); a host whose home is read-only sets it.
86
+ export async function resolveReleaseBundle(savedBundleId, { cacheDir = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, retired, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS, preparationOnly = false } = {}) {
87
+ // A test that supplies pins supplies the retired table with them, or none.
88
+ const bundleId = await currentBundleId(savedBundleId, retired ?? (pins ? {} : undefined));
94
89
  const expected = await releasePin(bundleId, pins);
95
90
  const root = join(cacheDir, bundleId);
96
91
  const manifestPath = join(root, 'manifest.json');
97
92
  const base = `${RELEASE_ORIGIN}/hem-targets/${bundleId}/`;
98
93
  let bytes = await readFile(manifestPath).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
99
94
  if (!bytes || hash(bytes) !== expected) {
100
- bytes = await fetchBytes(fetcher, bundleId, base + 'manifest.json', timeoutMs);
95
+ bytes = await fetchBytes(fetcher, bundleId, base + 'manifest.json', timeoutMs, root);
101
96
  if (hash(bytes) !== expected) throw new Error(`HEM target manifest hash mismatch: ${bundleId}`);
102
97
  await writeAtomic(manifestPath, bytes);
103
98
  }
104
99
  const manifest = JSON.parse(bytes);
105
- const artifacts = manifest.artifacts.filter(artifact => { assertArtifactPath(artifact.path); return isModelArtifact(manifest, artifact.path); });
100
+ const artifacts = manifest.artifacts.filter(artifact => { assertArtifactPath(artifact.path); return isSelected(manifest, artifact.path, preparationOnly); });
106
101
  const missing = [];
107
102
  const realRoot = await realpath(root);
108
103
  for (const artifact of artifacts) {
@@ -122,7 +117,7 @@ export async function resolveReleaseBundle(bundleId, { cacheDir = join(homedir()
122
117
  try {
123
118
  while (next < missing.length && !failed) {
124
119
  const artifact = missing[next++];
125
- const contents = await fetchBytes(fetcher, bundleId, base + artifact.path, timeoutMs);
120
+ const contents = await fetchBytes(fetcher, bundleId, base + artifact.path, timeoutMs, root);
126
121
  if (contents.length !== artifact.bytes || hash(contents) !== artifact.sha256) throw new Error(`Corrupt HEM target artifact ${artifact.path}; retry the download`);
127
122
  await writeAtomic(join(root, artifact.path), contents);
128
123
  completed += artifact.bytes;
@@ -141,13 +136,63 @@ export function forwardPanicLines(page, write = line => process.stderr.write(`${
141
136
  page.on('console', message => { if (message.text().startsWith('[WASM] PANIC')) write(message.text()); });
142
137
  }
143
138
 
139
+ /** The verified pinned schema and defaults of a supplied or released bundle, for preparation in Node. */
140
+ export async function readPreparationBundle(options, dependencies = {}) {
141
+ const located = options.manifestPath ? { manifestPath: options.manifestPath, manifestSha256: options.manifestSha256 }
142
+ : await resolveReleaseBundle(options.targetBundleId, { cacheDir: dependencies.cacheDir, fetch: dependencies.fetch, pins: dependencies.pins, preparationOnly: true });
143
+ const { manifest, routes } = await readVerifiedBundle(located.manifestPath, located.manifestSha256, { preparationOnly: true });
144
+ return { manifest, text: artifactText(manifest, routes) };
145
+ }
146
+
147
+ /** Reads workspace files for preparation; a path that leaves the workspace is refused. */
148
+ export async function workspaceReader(workspacePath) {
149
+ const workspace = await realpath(workspacePath);
150
+ return async path => {
151
+ if (typeof path !== 'string' || path.includes('\\')) throw new Error('Invalid workspace path');
152
+ const file = await realpath(resolve(workspace, path));
153
+ if (!file.startsWith(workspace + sep)) throw new Error('Target read escapes workspace');
154
+ return readFile(file, 'utf8');
155
+ };
156
+ }
157
+
158
+ /** The verified pinned artifact text of a bundle, as the browser's TargetAssets text. */
159
+ const artifactText = (manifest, routes) => async path => {
160
+ const bytes = routes.get(`/hem-targets/${manifest.bundleId}/${path}`);
161
+ if (!bytes) throw new Error(`Missing preparation content ${path}`);
162
+ return new TextDecoder().decode(bytes);
163
+ };
164
+
165
+ /** Prepares every scenario of a saved target batch in Node with the package's own WASM; no browser. */
166
+ async function prepareJobs(options, manifest, routes, onJob, dependencies) {
167
+ const [{ prepareBatch }, loader] = await Promise.all([import('./preparation.mjs'), dependencies.loadPackageWasm ? undefined : import('./wasm-loader.mjs')]);
168
+ const wasmRemedy = options.wasmRemedy ?? 'Reinstall the package.';
169
+ const wasm = await (dependencies.loadPackageWasm ?? loader.loadPackageWasm)(options.wasmDir, wasmRemedy);
170
+ return prepareBatch({ config: options.config, manifest, text: artifactText(manifest, routes), converter: { prepare_target_scenario: wasm.prepareTargetScenario },
171
+ versionInfo: wasm.versionInfo, wasmRemedy, configName: options.configName, jobId: options.jobId, startedAt: options.startedAt, onJob });
172
+ }
173
+
174
+ /** A batch's exact source, defaults, snippet and weather bytes, read in Node; its target must be the supplied or pinned one. */
175
+ export async function snapshotTarget(options, dependencies = {}) {
176
+ const { snapshotBatchTarget } = await import('./preparation.mjs');
177
+ const snapshot = await snapshotBatchTarget(options.config, await workspaceReader(options.workspace));
178
+ const expected = options.manifestPath
179
+ ? (await readVerifiedBundle(options.manifestPath, options.manifestSha256, { preparationOnly: true })).manifest.bundleId
180
+ : (await releasePin(options.targetBundleId, dependencies.pins), options.targetBundleId);
181
+ if (snapshot.targetBundleId !== expected) throw new Error('Batch source and supplied manifest target differ');
182
+ return snapshot;
183
+ }
184
+
185
+ /** `operation: 'snapshot'` captures a batch; otherwise runs one saved target batch: under the workspace lock, prepares it in Node, then runs the jobs in Chrome. */
144
186
  export async function runTargetBrowser(options, dependencies = {}) {
187
+ if (options.operation === 'snapshot') return snapshotTarget(options, dependencies);
188
+ if (options.operation !== undefined && options.operation !== 'batch') throw new Error(`Unknown target operation '${options.operation}'`);
145
189
  // A bundle id resolves only after the workspace lock, so a long first download is reported as batch progress.
146
190
  const bundleId = options.manifestPath ? undefined : options.targetBundleId;
147
191
  let manifest, routes;
148
192
  if (options.manifestPath) ({ manifest, routes } = await readVerifiedBundle(options.manifestPath, options.manifestSha256));
149
193
  else await releasePin(bundleId, dependencies.pins);
150
- const assets = await readPackageWasm(options.wasmDir);
194
+ if (!options.config) throw new Error('Batch configuration required');
195
+ const assets = new Map();
151
196
  const runtimeRoot = options.runtimeRoot ?? dirname(fileURLToPath(import.meta.url));
152
197
  for (const name of ['host.mjs', 'python-worker.mjs', 'rust-worker.mjs']) {
153
198
  try { assets.set('/' + name, await readFile(join(runtimeRoot, name))); }
@@ -167,11 +212,6 @@ export async function runTargetBrowser(options, dependencies = {}) {
167
212
  if (!file.startsWith(workspace + sep)) throw new Error('Target file escapes workspace');
168
213
  return file;
169
214
  };
170
- const read = async path => {
171
- const file = await realpath(contained(path));
172
- if (!file.startsWith(workspace + sep)) throw new Error('Target read escapes workspace');
173
- return readFile(file, 'utf8');
174
- };
175
215
  const markers = new Map();
176
216
  const write = async (path, content) => {
177
217
  if (!path.startsWith('output/')) throw new Error('Target workers may only write workspace outputs');
@@ -196,7 +236,6 @@ export async function runTargetBrowser(options, dependencies = {}) {
196
236
  };
197
237
  let progressWrites = Promise.resolve();
198
238
  const progress = value => {
199
- if (options.operation !== 'batch') return Promise.resolve();
200
239
  // Download callbacks can overlap. Preserve ordering through the final status.
201
240
  // Status readers poll this file: write a new file and rename it over the old, so none sees it truncated.
202
241
  const file = `output/progress_${jobId}.json`;
@@ -232,6 +271,11 @@ export async function runTargetBrowser(options, dependencies = {}) {
232
271
  onProgress: (completed, total) => { void progress({ status: 'running', stage: 'download', completed, total }); } });
233
272
  ({ manifest, routes } = await readVerifiedBundle(resolved.manifestPath, resolved.manifestSha256));
234
273
  }
274
+ // ponytail: every prepared job is held in memory and served to the page at once; stream them if batches outgrow that.
275
+ const jobs = await (dependencies.prepareJobs ?? prepareJobs)({ ...options, jobId, startedAt }, manifest, routes,
276
+ // A signal during preparation stops it at the next scenario, as a signal during the run closes Chrome.
277
+ prepared => { if (interrupted) throw interrupted; return progress({ status: 'running', stage: 'prepare', completed: prepared }); }, dependencies);
278
+ assets.set('/prepared-jobs.json', Buffer.from(JSON.stringify(jobs)));
235
279
  for (const [route, bytes] of assets) routes.set(route, bytes);
236
280
  server = createServer((req, res) => {
237
281
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
@@ -251,7 +295,6 @@ export async function runTargetBrowser(options, dependencies = {}) {
251
295
  const page = await browser.newPage();
252
296
  forwardPanicLines(page);
253
297
  await page.route('**/*', route => route.request().url().startsWith(origin + '/') ? route.continue() : route.abort());
254
- await page.exposeFunction('targetCliRead', read);
255
298
  await page.exposeFunction('targetCliWrite', write);
256
299
  await page.exposeFunction('targetCliProgress', progress);
257
300
  await progress({ status: 'running', progress: 0 });
@@ -262,7 +305,7 @@ export async function runTargetBrowser(options, dependencies = {}) {
262
305
  const { run } = await import('/host.mjs');
263
306
  return { result: await run(request) };
264
307
  } catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
265
- }, { manifest, operation: options.operation, csv: options.csv, config: options.config, configName: options.configName, jobId, startedAt, wasmRemedy: options.wasmRemedy });
308
+ }, { manifest, jobsUrl: '/prepared-jobs.json', jobId });
266
309
  if (interrupted) throw interrupted;
267
310
  if ('error' in outcome) throw new Error(outcome.error);
268
311
  const { result } = outcome;