synabun 2.0.10 → 2.2.0

package/lib/mcp-dist.js

@@ -0,0 +1,176 @@
+// What "the MCP server is built" means, in one place: mcp-server/dist/index.js and every module it imports by a
+// relative path, transitively, are on disk. mcp-server/dist/ is build output that git ignores, yet a checkout can
+// hold a tracked dist/index.js whose newer imports were never committed (they are ignored too): a server started
+// from it fails to load /mcp. postinstall.js and setup.js build when this says no; the Neural Interface's restore,
+// onboarding status and build route, the install details, the release and the packaged app's checks ask it too.
+//
+// The imports are read from the code itself, never from a comment or a string: a light tokenizer skips comments,
+// strings, template literals and regular expressions, so a word "import" in a text cannot ask for a module that is
+// not loaded (a packaged app has no compiler: a false "missing" there would stop it). Only plain fs and path:
+// postinstall.js and setup.js import this on any Node.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const MAX_MODULES = 5000;
+const MAX_MODULE_BYTES = 8 * 1024 * 1024;
+const CODE_EXT = /\.(?:m?js|cjs)$/i;
+// After one of these a `/` starts a regular expression, after anything else it divides.
+const REGEX_AFTER_PUNCT = new Set(['(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+const REGEX_AFTER_WORD = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await']);
+
+/**
+ * The tokens of a module that matter for its imports: words, punctuation and string literals (their values), with
+ * comments, template literal text and regular expressions left out.
+ * @returns {{ t: 'word'|'punct'|'string', v: string }[]}
+ */
+export function codeTokens(text) {
+  const src = String(text ?? '');
+  const out = [];
+  const frames = [];   // one per open `${` of a template literal: the brace depth that closes it
+  let depth = 0;
+  let i = 0;
+  const last = () => out[out.length - 1];
+  const regexAllowed = () => {
+    const p = last();
+    if (!p) return true;
+    if (p.t === 'punct') return REGEX_AFTER_PUNCT.has(p.v);
+    if (p.t === 'word') return REGEX_AFTER_WORD.has(p.v);
+    return false;
+  };
+  const template = () => {
+    // From just after a backtick (or a closing `}` of a `${`): to the closing backtick or the next `${`.
+    while (i < src.length) {
+      const c = src[i];
+      if (c === '\\') { i += 2; continue; }
+      if (c === '`') { i += 1; out.push({ t: 'string', v: '' }); return; }
+      if (c === '$' && src[i + 1] === '{') { i += 2; frames.push(depth); depth += 1; return; }
+      i += 1;
+    }
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); i = nl < 0 ? src.length : nl; continue; }
+    if (c === '/' && src[i + 1] === '*') { const end = src.indexOf('*/', i + 2); i = end < 0 ? src.length : end + 2; continue; }
+    if (c === '\'' || c === '"') {
+      let j = i + 1; let v = '';
+      while (j < src.length && src[j] !== c && src[j] !== '\n') { if (src[j] === '\\') { v += src[j + 1] ?? ''; j += 2; continue; } v += src[j]; j += 1; }
+      out.push({ t: 'string', v });
+      i = j + 1;
+      continue;
+    }
+    if (c === '`') { i += 1; template(); continue; }
+    if (c === '/' && regexAllowed()) {
+      let j = i + 1; let inClass = false;
+      while (j < src.length && src[j] !== '\n') {
+        const d = src[j];
+        if (d === '\\') { j += 2; continue; }
+        if (d === '[') inClass = true;
+        else if (d === ']') inClass = false;
+        else if (d === '/' && !inClass) break;
+        j += 1;
+      }
+      i = j + 1;
+      while (i < src.length && /[a-z]/i.test(src[i])) i += 1;
+      out.push({ t: 'punct', v: ')' });   // a value, as far as a following `/` is concerned
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(c)) {
+      let j = i + 1;
+      while (j < src.length && /[\w$]/.test(src[j])) j += 1;
+      out.push({ t: 'word', v: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (/\s/.test(c)) { i += 1; continue; }
+    if (/[0-9]/.test(c)) { let j = i + 1; while (j < src.length && /[\w.]/.test(src[j])) j += 1; out.push({ t: 'word', v: src.slice(i, j) }); i = j; continue; }
+    if (c === '{') depth += 1;
+    if (c === '}') {
+      if (frames.length && depth - 1 === frames[frames.length - 1]) { depth -= 1; frames.pop(); i += 1; template(); continue; }
+      depth = Math.max(0, depth - 1);
+    }
+    out.push({ t: 'punct', v: c });
+    i += 1;
+  }
+  return out;
+}
+
+/** The module specifiers a module loads: static imports, `export … from`, side-effect imports, `import('…')`. */
+export function importSpecifiers(text) {
+  const tokens = codeTokens(text);
+  const found = [];
+  const at = (k) => tokens[k] || { t: 'end', v: '' };
+  for (let k = 0; k < tokens.length; k++) {
+    const tok = tokens[k];
+    if (tok.t !== 'word' || (tok.v !== 'import' && tok.v !== 'export')) continue;
+    if (k > 0 && at(k - 1).t === 'punct' && at(k - 1).v === '.') continue;   // obj.import
+    const next = at(k + 1);
+    if (tok.v === 'import') {
+      if (next.t === 'punct' && next.v === '.') continue;   // import.meta
+      if (next.t === 'punct' && next.v === '(') { if (at(k + 2).t === 'string' && at(k + 3).v === ')') found.push(at(k + 2).v); continue; }
+      if (next.t === 'string') { found.push(next.v); continue; }
+    }
+    // import a, { b as c } from '…'; import * as d from '…'; export { e } from '…'; export * from '…'
+    let j = k + 1;
+    while (j < tokens.length) {
+      const x = at(j);
+      if (x.t === 'word' && x.v === 'from') break;
+      if (x.t === 'word' || (x.t === 'punct' && (x.v === ',' || x.v === '{' || x.v === '}' || x.v === '*'))) { j += 1; continue; }
+      j = -1;
+      break;
+    }
+    if (j > k + 1 && at(j).v === 'from' && at(j + 1).t === 'string') {
+      if (tok.v === 'export' && !(next.v === '*' || next.v === '{')) continue;
+      found.push(at(j + 1).v);
+    }
+  }
+  return found;
+}
+
+const posix = (p) => p.split(sep).join('/');
+
+/**
+ * Every module dist/index.js needs that is not on disk (or cannot be read), as paths from the package root.
+ * Modules inside mcp-server/dist are followed; one outside it (the package's lib/) is only looked for.
+ * @param {string} packageRoot
+ * @param {{ exists?: (p: string) => boolean, readText?: (p: string) => string, entry?: string }} [o]
+ * @returns {{ complete: boolean, missing: string[], checked: number }}
+ */
+export function mcpDistMissing(packageRoot, { exists = existsSync, readText = null, entry = 'index.js' } = {}) {
+  const root = resolve(packageRoot);
+  const dist = join(root, 'mcp-server', 'dist');
+  const read = readText || ((p) => {
+    const st = statSync(p);
+    if (!st.isFile()) throw new Error('not a regular file');
+    if (st.size > MAX_MODULE_BYTES) return null;
+    return readFileSync(p, 'utf8');
+  });
+  const missing = new Set();
+  const seen = new Set();
+  const queue = [join(dist, entry)];
+  let checked = 0;
+  while (queue.length && checked < MAX_MODULES) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!exists(file)) { missing.add(posix(relative(root, file))); continue; }
+    const inside = file.startsWith(dist + sep);
+    if (!inside || !CODE_EXT.test(file)) continue;
+    let text;
+    try { text = read(file); } catch { missing.add(posix(relative(root, file))); continue; }
+    checked += 1;
+    if (text === null) continue;   // too large to read here: present, not followed
+    for (const spec of importSpecifiers(text)) {
+      if (!spec.startsWith('./') && !spec.startsWith('../')) continue;
+      const target = resolve(dirname(file), spec.split(/[?#]/)[0]);
+      if (!seen.has(target)) queue.push(target);
+    }
+  }
+  const list = [...missing].sort();
+  return { complete: list.length === 0, missing: list, checked };
+}
+
+/** Whether the MCP server is built: dist/index.js and everything it imports are there. */
+export function mcpDistBuilt(packageRoot, options) {
+  return mcpDistMissing(packageRoot, options).complete;
+}

package/lib/release-npm-ci.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/** Shared CI identity, OIDC-only publication and exact-byte handoff contract. */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { appendFile, lstat, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hashFile } from './virustotal.mjs';
+import { publishNpm, runNpm, verifyPacked } from './release-publish.mjs';
+
+export const REPOSITORY = 'danilokhury/Synabun';
+export const WORKFLOW = '.github/workflows/publish.yml';
+export const PUBLISH_NPM = '11.21.0'; // Verified OIDC-compatible CLI; builder stays 10.9.3.
+export const stableVersion = value => typeof value === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value);
+export const exactCommit = value => typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
+export const requestId = value => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+export const runTitle = ({ version, commit, request }) => `npm ${version} ${commit} ${request}`;
+export const artifactName = (id, attempt) => `npm-publication-${id}-${attempt}`;
+const numberId = value => /^\d+$/.test(String(value)) && Number.isSafeInteger(Number(value)) && Number(value) > 0;
+
+export function validateIdentity({ env, event, pkg, head, main }) {
+  if (env.GITHUB_REPOSITORY !== REPOSITORY || pkg.name !== 'synabun' || !stableVersion(pkg.version)
+      || pkg.repository?.url !== `git+https://github.com/${REPOSITORY}.git`) throw new Error('Unexpected npm package/repository identity');
+  if (!exactCommit(head) || head !== main || !numberId(env.GITHUB_RUN_ID) || !numberId(env.GITHUB_RUN_ATTEMPT)) throw new Error('Release commit must be the current main tip; require exact run identity');
+  let request = null;
+  if (env.GITHUB_EVENT_NAME === 'workflow_dispatch') {
+    if (env.GITHUB_REF !== 'refs/heads/main' || env.GITHUB_SHA !== head || event.inputs?.commit !== head
+        || event.inputs?.version !== pkg.version || !requestId(event.inputs?.request_id)) throw new Error('Invalid dispatch ref/commit/version/request identity');
+    request = event.inputs.request_id;
+  } else if (env.GITHUB_EVENT_NAME === 'release') {
+    const tag = event.release?.tag_name;
+    if (event.action !== 'published' || event.release?.draft !== false || event.release?.prerelease !== false
+        || !new RegExp(`^v?\\.?${pkg.version.replaceAll('.', '\\.')}$`).test(tag || '')
+        || env.GITHUB_REF !== `refs/tags/${tag}` || env.GITHUB_SHA !== head) throw new Error('Invalid stable release event/tag');
+  } else throw new Error('Only main workflow_dispatch or stable release.published can publish');
+  if (env.GITHUB_WORKFLOW_REF !== `${REPOSITORY}/${WORKFLOW}@${env.GITHUB_REF}`) throw new Error('Unexpected publisher workflow identity');
+  return { repository: REPOSITORY, workflow: WORKFLOW, event: env.GITHUB_EVENT_NAME,
+    version: pkg.version, commit: head, request, run_id: Number(env.GITHUB_RUN_ID), run_attempt: Number(env.GITHUB_RUN_ATTEMPT) };
+}
+
+export function oidcEnvironment(env, { cli, userconfig, globalconfig, cache }) {
+  if (env.RUNNER_ENVIRONMENT !== 'github-hosted' || !env.ACTIONS_ID_TOKEN_REQUEST_URL || !env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) throw new Error('GitHub-hosted OIDC runner and id-token: write are required');
+  // Modern npm tries OIDC first. Remove legacy credentials anyway: no silent token fallback.
+  const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !/^(NPM|NPM_TOKEN|NODE_AUTH_TOKEN)$/i.test(key) && !/^npm_config_/i.test(key)));
+  return { ...clean, npm_execpath: cli, NPM_CONFIG_USERCONFIG: userconfig, NPM_CONFIG_GLOBALCONFIG: globalconfig,
+    NPM_CONFIG_CACHE: cache, NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org/', NPM_CONFIG_UPDATE_NOTIFIER: 'false' };
+}
+
+export function verifyToolchain(node, npm) {
+  if (node.replace(/^v/, '') !== '22.19.0' || npm.trim() !== PUBLISH_NPM) throw new Error(`Publication requires Node 22.19.0 and isolated npm ${PUBLISH_NPM}; builder npm is unchanged`);
+}
+
+export async function registryVersion(version, { fetchImpl = fetch, allowMissing = false } = {}) {
+  if (!stableVersion(version)) throw new Error('Invalid registry version');
+  const response = await fetchImpl(`https://registry.npmjs.org/synabun/${version}`, { signal: AbortSignal.timeout(30000) });
+  if (response.status === 404 && allowMissing) return null;
+  if (!response.ok) throw new Error(`npm registry lookup failed (${response.status})`);
+  const pkg = await response.json();
+  if (pkg?.name !== 'synabun' || pkg.version !== version || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(pkg.dist?.integrity || '')) throw new Error('npm registry identity/integrity is unverified');
+  return pkg.dist.integrity;
+}
+
+export async function sha512(path) {
+  const hash = createHash('sha512');
+  for await (const bytes of createReadStream(path)) hash.update(bytes);
+  return `sha512-${hash.digest('base64')}`;
+}
+export const bundleFiles = version => ['npm-virustotal.json', 'npm-virustotal.md', `synabun-${version}.tgz`];
+
+export async function publicationReceipt({ out, identity, registry = registryVersion }) {
+  const packed = await verifyPacked({ out });
+  if (packed.tarball !== join(out, `synabun-${identity.version}.tgz`)) throw new Error('npm receipt version mismatch');
+  const integrity = await sha512(packed.tarball);
+  if (await registry(identity.version) !== integrity) throw new Error('npm registry SHA512 differs from scanned tarball');
+  const files = {};
+  for (const name of bundleFiles(identity.version)) files[name] = { sha256: await hashFile(join(out, name)), size: (await lstat(join(out, name))).size };
+  const receipt = { schema: 1, ...identity, integrity, files };
+  await writeFile(join(out, 'npm-publication.json'), JSON.stringify(receipt, null, 2) + '\n');
+  return receipt;
+}
+
+export async function verifyPublication({ out, expected, registry = registryVersion, strictFiles = true }) {
+  const receipt = JSON.parse(await readFile(join(out, 'npm-publication.json'), 'utf8'));
+  if (receipt.schema !== 1 || receipt.repository !== REPOSITORY || receipt.workflow !== WORKFLOW
+      || !stableVersion(receipt.version) || !exactCommit(receipt.commit) || !numberId(receipt.run_id)
+      || !numberId(receipt.run_attempt) || !['workflow_dispatch', 'release'].includes(receipt.event)
+      || (receipt.event === 'workflow_dispatch' && !requestId(receipt.request))) throw new Error('Unknown or invalid npm publication receipt');
+  for (const [key, value] of Object.entries(expected)) if (receipt[key] !== value) throw new Error(`npm publication identity mismatch: ${key}`);
+  const names = bundleFiles(expected.version);
+  if (JSON.stringify(Object.keys(receipt.files || {}).sort()) !== JSON.stringify([...names].sort())
+      || (strictFiles && JSON.stringify((await readdir(out)).sort()) !== JSON.stringify([...names, 'npm-publication.json'].sort()))) throw new Error('Unexpected npm artifact file set');
+  for (const name of [...names, 'npm-publication.json']) {
+    const info = await lstat(join(out, name));
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('npm artifact must contain regular files only');
+    if (name !== 'npm-publication.json' && (info.size !== receipt.files[name].size || await hashFile(join(out, name)) !== receipt.files[name].sha256)) throw new Error(`npm artifact integrity mismatch: ${name}`);
+  }
+  const packed = await verifyPacked({ out });
+  if (packed.tarball !== join(out, `synabun-${expected.version}.tgz`) || await sha512(packed.tarball) !== receipt.integrity
+      || await registry(expected.version) !== receipt.integrity) throw new Error('npm publication version/registry integrity mismatch');
+  // Read only the packed manifest; never extract arbitrary paths into the checkout.
+  const tar = spawnSync('tar', ['-xOf', packed.tarball, 'package/package.json'], { encoding: 'utf8', maxBuffer: 1024 * 1024, timeout: 30000 });
+  if (tar.status !== 0) throw new Error('Cannot inspect npm tarball manifest');
+  const pkg = JSON.parse(tar.stdout);
+  if (pkg.name !== 'synabun' || pkg.version !== expected.version || pkg.repository?.url !== `git+https://github.com/${REPOSITORY}.git`) throw new Error('Packed npm manifest identity mismatch');
+  return receipt;
+}
+
+function git(...args) {
+  const result = spawnSync('git', args, { encoding: 'utf8', timeout: 120000 });
+  if (result.status !== 0) throw new Error('Cannot verify current main commit');
+  return result.stdout.trim();
+}
+async function ciIdentity() {
+  git('fetch', '--no-tags', '--depth=1', 'origin', 'main');
+  return validateIdentity({ env: process.env, event: JSON.parse(await readFile(process.env.GITHUB_EVENT_PATH, 'utf8')),
+    pkg: JSON.parse(await readFile('package.json', 'utf8')), head: git('rev-parse', 'HEAD'), main: git('rev-parse', 'FETCH_HEAD') });
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const stage = process.argv[2], identity = await ciIdentity(), out = join(process.env.RUNNER_TEMP, 'npm-release');
+    if (stage === 'identity') {
+      const published = await registryVersion(identity.version, { allowMissing: true });
+      if (published && identity.event === 'workflow_dispatch') throw new Error('Version already published: recover the original successful run artifacts; never repack an existing version');
+      await appendFile(process.env.GITHUB_OUTPUT, `published=${!!published}\n`);
+    } else if (stage === 'publish') {
+      try { await lstat('.npmrc'); throw new Error('Project .npmrc is forbidden in the publishing checkout'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const base = process.env.RUNNER_TEMP;
+      const userconfig = join(base, 'npm-oidc-userconfig'), globalconfig = join(base, 'npm-oidc-globalconfig');
+      await writeFile(userconfig, ''); await writeFile(globalconfig, '');
+      const env = oidcEnvironment(process.env, { cli: join(base, 'npm-oidc-cli/node_modules/npm/bin/npm-cli.js'), userconfig, globalconfig, cache: join(base, 'npm-oidc-cache') });
+      const run = (args, options) => runNpm(args, { ...options, env });
+      verifyToolchain(process.version, run(['--version'], { capture: true }));
+      await publishNpm({ cwd: process.cwd(), out, run, publishPacked: true, provenance: true });
+      await publicationReceipt({ out, identity });
+    } else throw new Error('Use identity or publish');
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/lib/release-publish.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/** The only documented npm publication path: check, pack, scan, publish the same tgz. */
+import { spawnSync } from 'node:child_process';
+import { access, chmod, mkdir, mkdtemp, readFile, copyFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { approved, credentials, evidenceDigest, hashFile } from './virustotal.mjs';
+import { scanRelease } from './release-scan.mjs';
+
+export function runNpm(args, { cwd, env = process.env, capture = false } = {}) {
+  // npm_execpath works with npm.cmd on Windows without shell argument interpolation.
+  const npm = env.npm_execpath;
+  if (!npm && process.platform === 'win32') throw new Error('On Windows run npm run release:publish so npm_execpath is available');
+  const command = npm ? process.execPath : 'npm';
+  const result = spawnSync(command, npm ? [npm, ...args] : args, { cwd, env, encoding: 'utf8', stdio: capture ? 'pipe' : 'inherit', timeout: 1800000, maxBuffer: 8 * 1024 * 1024 });
+  // Never replay npm's captured output (it may contain authentication diagnostics).
+  if (result.error || result.status !== 0) throw new Error(`npm ${args[0]} failed; publication stopped`);
+  return result.stdout;
+}
+export async function verifyPacked({ out, now = Date.now() }) {
+  const report = JSON.parse(await readFile(join(out, 'npm-virustotal.json'), 'utf8'));
+  if (report.schema !== 1 || !report.approved || report.items?.length !== 1 || !approved(report.items)) throw new Error('npm scan report is not approved');
+  const item = report.items[0];
+  if (item.kind !== 'file' || basename(item.name) !== item.name || !/^synabun-.*\.tgz$/.test(item.name)) throw new Error('Invalid npm scan subject');
+  const { evidence_digest, review, ...evidence } = item;
+  if (evidenceDigest(evidence) !== evidence_digest) throw new Error('npm report evidence digest mismatch');
+  const at = Date.parse(item.analysis_date);
+  if (!Number.isFinite(at) || at > now + 300000 || now - at > 7 * 86400000 || item.analysis_status !== 'completed' || item.supported_engines < 10) throw new Error('npm scan report stale, unfinished or inconclusive');
+  if (item.status === 'detections') {
+    const { applyReviews } = await import('./virustotal.mjs');
+    if (!approved(applyReviews([{ ...item, review: null }], [{ ...review, name: item.name, sha256: item.sha256, evidence_digest }], now))) throw new Error('npm detection review required');
+  }
+  const tarball = join(out, item.name);
+  if (await hashFile(tarball) !== item.sha256) throw new Error('npm tarball SHA-256 mismatch; repack and scan');
+  return { tarball, sha256: item.sha256 };
+}
+export async function publishNpm({ cwd, out, reviewFile, provenance = false, packOnly = false, publishPacked = false, run = runNpm, scan = scanRelease }) {
+  credentials(); // Before installs or registry mutations.
+  const rel = relative(resolve(cwd), resolve(out));
+  if (!rel || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\'))) throw new Error('Release output must be outside the checkout to keep reports/tarballs out of npm packages');
+  const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+  if (pkg.name !== 'synabun' || pkg.scripts?.prepublishOnly?.includes('refuse-publish-from-dev') || !pkg.scripts?.prepublishOnly?.includes('release-publish.mjs guard')) throw new Error('Publish from a fresh prepared Clean clone with npm run release:publish; Dev publication is refused');
+  await mkdir(out, { recursive: true });
+  if (!publishPacked) {
+    run(['run', 'deps:check'], { cwd });
+    run(['ci', '--ignore-scripts'], { cwd });
+    // Preserve Clean's entire install/build/file/pack chain. npm publish TGZ skips it.
+    run(['run', 'prepublishOnly'], { cwd, env: { ...process.env, SYNABUN_RELEASE_PACK: '1' } });
+    run(['run', 'prepack'], { cwd });
+    for (const file of ['mcp-server/dist/index.js', 'NOTICE', 'THIRD-PARTY-LICENSES.md']) await access(join(cwd, file));
+    const staging = await mkdtemp(join(tmpdir(), 'synabun-npm-pack-'));
+    try {
+      const packed = JSON.parse(run(['pack', '--ignore-scripts', '--json', '--pack-destination', staging], { cwd, capture: true }));
+      const name = packed?.[0]?.filename;
+      if (packed.length !== 1 || !name || basename(name) !== name || name !== `synabun-${pkg.version}.tgz`) throw new Error('npm pack returned an unexpected tarball');
+      const tarball = join(out, name);
+      await rm(tarball, { force: true });
+      await copyFile(join(staging, name), tarball);
+      await chmod(tarball, 0o444);
+      await scan({ files: [tarball], out, prefix: 'npm-virustotal', reviewFile });
+    } finally { await rm(staging, { recursive: true, force: true }); }
+  }
+  const packed = await verifyPacked({ out });
+  if (basename(packed.tarball) !== `synabun-${pkg.version}.tgz`) throw new Error('npm tarball version mismatch');
+  if (!packOnly) {
+    run(['publish', packed.tarball, '--ignore-scripts', '--access', 'public', '--tag', 'latest', ...(provenance ? ['--provenance'] : [])], { cwd });
+    if (await hashFile(packed.tarball) !== packed.sha256) throw new Error('npm tarball changed during publication; inspect registry immediately');
+  }
+  return packed;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    if (process.argv[2] === 'guard') {
+      if (process.env.SYNABUN_RELEASE_PACK !== '1') throw new Error('Direct npm publish is disabled: use npm run release:publish -- --out /absolute/release/folder (packs, scans and publishes the exact tgz).');
+    } else {
+      const args = process.argv.slice(2); let out, reviewFile, provenance = false, packOnly = false, publishPacked = false;
+      while (args.length) {
+        const arg = args.shift();
+        if (arg === '--out') out = args.shift();
+        else if (arg === '--review') reviewFile = args.shift();
+        else if (arg === '--provenance') provenance = true;
+        else if (arg === '--pack-only') packOnly = true;
+        else if (arg === '--publish-packed') publishPacked = true;
+        else throw new Error(`Unknown option: ${arg}`);
+      }
+      if (!out || (packOnly && publishPacked)) throw new Error('Use --out DIR; --pack-only and --publish-packed are mutually exclusive');
+      await publishNpm({ cwd: dirname(dirname(fileURLToPath(import.meta.url))), out: resolve(out), reviewFile, provenance, packOnly, publishPacked });
+    }
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/lib/release-scan.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/** Shared required scan stage; failures still write auditable reports. */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { applyReviews, credentials, hashFile, reports, VirusTotal } from './virustotal.mjs';
+
+export async function scanRelease({ files = [], urls = [], out, prefix = 'virustotal', reviewFile, client = new VirusTotal(), now = Date.now() }) {
+  if (!files.length && !urls.length) throw new Error('No scan subjects supplied');
+  const items = [];
+  for (const file of files) {
+    const path = typeof file === 'string' ? file : file.path;
+    const expected = typeof file === 'string' ? undefined : file.sha256;
+    // Missing/mismatched local bytes are hard errors, never reviewable detections.
+    const sha256 = await hashFile(path);
+    if (expected && sha256 !== expected) throw new Error(`SHA-256 mismatch: ${basename(path)}`);
+    try { items.push(await client.file(path, sha256)); }
+    catch (error) { items.push({ kind: 'file', name: basename(path), sha256, status: 'error', analysis_status: 'unavailable', error: error.message }); }
+  }
+  for (const url of urls) {
+    try { items.push(await client.url(url)); }
+    catch (error) { items.push({ kind: 'url', name: url, status: 'error', analysis_status: 'unavailable', error: error.message }); }
+  }
+  const reviews = reviewFile ? JSON.parse(await readFile(reviewFile, 'utf8')) : [];
+  const result = reports(applyReviews(items, reviews, now));
+  await mkdir(out, { recursive: true });
+  await writeFile(resolve(out, `${prefix}.json`), result.json);
+  await writeFile(resolve(out, `${prefix}.md`), result.markdown);
+  if (!result.report.approved) throw new Error(`VirusTotal gate blocked; inspect ${prefix}.json/.md. Retry failures/inconclusive scans; detections require a hash- and evidence-specific review (docs/release-pipeline.md).`);
+  return result;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    credentials();
+    const files = []; const urls = []; let out, reviewFile, prefix = 'virustotal';
+    const args = process.argv.slice(2);
+    while (args.length) {
+      const arg = args.shift();
+      if (arg === '--out') out = args.shift();
+      else if (arg === '--prefix') prefix = args.shift();
+      else if (arg === '--review') reviewFile = args.shift();
+      else if (arg === '--url') urls.push(args.shift());
+      else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+      else files.push(arg);
+    }
+    if (!out) throw new Error('Usage: node lib/release-scan.mjs --out DIR [--review FILE] [--url https://synabun.ai/] [FILE ...]');
+    if (!['virustotal', 'npm-virustotal'].includes(prefix)) throw new Error('Use prefix virustotal or npm-virustotal');
+    await scanRelease({ files, urls, out, prefix, reviewFile });
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/lib/server-crash-record.js

@@ -0,0 +1,123 @@
+/**
+ * SynaBun — the record of a crash the supervisor recovered from
+ *
+ * When the server crashes after it was up, its supervisor (lib/server-supervisor.js)
+ * starts it again and leaves this record for the server it starts:
+ * DATA_HOME/data/server-crash.json. That server shows it to the owner's pages
+ * (GET /api/system/crash-notice, neural-interface/lib/crash-notice-api.js) until
+ * it is dismissed; a dismissal removes it, so it stays gone in every tab and
+ * window, and the next crash writes a new one, with a new id, which shows again.
+ *
+ * One writer at a time: the supervisor writes the record only while no server
+ * runs (between a crash and the next start) and removes it when it ends without
+ * a running server after all (the crash-loop guard gave up, the server it
+ * started again never came up: the app's stopped page says what happened then);
+ * the server removes it, while it runs, when the owner dismisses it. Nothing is
+ * written for a stop, a restart, an update or a start that failed.
+ *
+ * Never throws. `fs` can be handed in (tests).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const CRASH_RECORD_NAME = 'server-crash.json';
+export const CRASH_RECORD_VERSION = 1;
+
+const NODE_FS = Object.freeze({ mkdirSync, readFileSync, renameSync, rmSync, writeFileSync });
+const ID = /^[0-9a-f]{16}$/;
+const HEX = /^0x[0-9A-F]{8}$/;
+const SIGNAL = /^SIG[A-Z0-9]{1,10}$/;
+const KIND = /^[a-z][a-z-]{0,23}$/;
+
+/** Where the record is: beside the supervisor record and the server's logs. */
+export function crashRecordPath(dataHome) {
+  return join(dataHome, 'data', CRASH_RECORD_NAME);
+}
+
+/** A record, checked field by field (what a page is shown comes from here only); null when it is not one. */
+export function normalizeCrashRecord(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.v !== CRASH_RECORD_VERSION || typeof raw.id !== 'string' || !ID.test(raw.id)) return null;
+  const at = Number(raw.at);
+  if (!Number.isFinite(at) || at <= 0) return null;
+  const firstAt = Number(raw.firstAt);
+  const exit = raw.exit && typeof raw.exit === 'object' && !Array.isArray(raw.exit) ? raw.exit : {};
+  const uptimeMs = Number(raw.uptimeMs);
+  return {
+    v: CRASH_RECORD_VERSION,
+    id: raw.id,
+    at,
+    firstAt: Number.isFinite(firstAt) && firstAt > 0 && firstAt <= at ? firstAt : at,
+    count: Number.isInteger(raw.count) && raw.count > 0 ? Math.min(raw.count, 999) : 1,
+    exit: {
+      ...(Number.isInteger(exit.code) ? { code: exit.code } : {}),
+      ...(typeof exit.hex === 'string' && HEX.test(exit.hex) ? { hex: exit.hex } : {}),
+      ...(typeof exit.signal === 'string' && SIGNAL.test(exit.signal) ? { signal: exit.signal } : {}),
+      kind: typeof exit.kind === 'string' && KIND.test(exit.kind) ? exit.kind : 'exit',
+    },
+    ...(raw.uptimeMs !== undefined && raw.uptimeMs !== null && Number.isFinite(uptimeMs) && uptimeMs >= 0 ? { uptimeMs: Math.round(uptimeMs) } : {}),
+  };
+}
+
+/** The record in the data home, or null. */
+export function readCrashRecord(dataHome, { fs = NODE_FS } = {}) {
+  try {
+    return normalizeCrashRecord(JSON.parse(fs.readFileSync(crashRecordPath(dataHome), 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The supervisor's side: the server crashed after it was up and is being started
+ * again. `exit` is lib/server-exit.js describeExit's answer. A record the owner
+ * has not dismissed yet is counted on (`count` + 1, its `firstAt` kept); the id
+ * is always new. Written whole (a temporary file renamed over it). Returns the
+ * record written, or null.
+ */
+export function writeCrashRecord(dataHome, { exit = {}, at = Date.now(), uptimeMs = null, pid = process.pid } = {}, {
+  fs = NODE_FS, newId = () => randomBytes(8).toString('hex'),
+} = {}) {
+  const path = crashRecordPath(dataHome);
+  const before = readCrashRecord(dataHome, { fs });
+  const record = normalizeCrashRecord({
+    v: CRASH_RECORD_VERSION,
+    id: newId(),
+    at,
+    firstAt: before ? before.firstAt : at,
+    count: before ? before.count + 1 : 1,
+    exit: { code: exit?.code, hex: exit?.hex, signal: exit?.signal, kind: exit?.kind },
+    uptimeMs,
+  });
+  if (!record) return null;
+  const temp = `${path}.${pid}.tmp`;
+  try {
+    fs.mkdirSync(dirname(path), { recursive: true });
+    fs.writeFileSync(temp, `${JSON.stringify(record)}\n`);
+    fs.renameSync(temp, path);
+    return record;
+  } catch {
+    try { fs.rmSync(temp, { force: true }); } catch {}
+    return null;
+  }
+}
+
+/**
+ * Remove the record: only the one named `id` when an id is given (a page that
+ * dismisses an older crash leaves a newer one in place), else whatever is there.
+ * Returns true when no record of that id is left.
+ */
+export function clearCrashRecord(dataHome, { id = null, fs = NODE_FS } = {}) {
+  if (id !== null) {
+    const current = readCrashRecord(dataHome, { fs });
+    if (!current || current.id !== id) return !current;
+  }
+  try {
+    fs.rmSync(crashRecordPath(dataHome), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}