ultra-builder-pro-cli 0.23.0 → 0.24.0

package/adapters/_shared/runtime-native.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MANIFEST_FILE = 'native-runtime.json';
+
+class RuntimeNativeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'RuntimeNativeError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function readManifest(runtimeRoot) {
+  const file = path.join(path.resolve(runtimeRoot), MANIFEST_FILE);
+  if (!fs.existsSync(file)) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is missing: ${file}`,
+      { path: file },
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (cause) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is invalid: ${file}`,
+      { path: file, cause: cause.message },
+    );
+  }
+  if (manifest?.schema_version !== 1
+      || typeof manifest.native_module !== 'string'
+      || !/^[0-9a-f]{64}$/i.test(manifest.native_sha256 || '')) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is incomplete: ${file}`,
+      { path: file },
+    );
+  }
+  return { file, manifest };
+}
+
+function inspectRuntimeNative(runtimeRoot, { load = true } = {}) {
+  const root = path.resolve(runtimeRoot);
+  const { file, manifest } = readManifest(root);
+  const expected = {
+    platform: process.platform,
+    arch: process.arch,
+    modules: process.versions.modules,
+  };
+  const actual = {
+    platform: manifest.platform,
+    arch: manifest.arch,
+    modules: String(manifest.modules || ''),
+  };
+  if (actual.platform !== expected.platform
+      || actual.arch !== expected.arch
+      || actual.modules !== expected.modules) {
+    throw new RuntimeNativeError(
+      'RUNTIME_ABI_MISMATCH',
+      `Ultra native runtime requires ${actual.platform}/${actual.arch} ABI ${
+        actual.modules
+      }, but the active Node is ${expected.platform}/${expected.arch} ABI ${expected.modules}`,
+      { expected: actual, actual: expected, manifest: file },
+    );
+  }
+  const nativeFile = path.resolve(root, manifest.native_module);
+  if (nativeFile !== root && !nativeFile.startsWith(`${root}${path.sep}`)) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      'Ultra native module path escapes the runtime root',
+      { path: manifest.native_module },
+    );
+  }
+  if (!fs.existsSync(nativeFile) || !fs.statSync(nativeFile).isFile()) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native SQLite driver is missing: ${nativeFile}`,
+      { path: nativeFile },
+    );
+  }
+  const digest = sha256(nativeFile);
+  if (digest !== manifest.native_sha256) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native SQLite driver digest does not match its manifest: ${nativeFile}`,
+      { path: nativeFile, expected: manifest.native_sha256, actual: digest },
+    );
+  }
+  if (load) {
+    let Database;
+    try {
+      Database = require(require.resolve('better-sqlite3', {
+        paths: [path.join(root, 'node_modules')],
+      }));
+      const db = new Database(':memory:');
+      db.prepare('SELECT 1 AS ok').get();
+      db.close();
+    } catch (cause) {
+      throw new RuntimeNativeError(
+        'RUNTIME_ABI_MISMATCH',
+        `Ultra native SQLite driver cannot load in the active Node runtime: ${cause.message}`,
+        { path: nativeFile, cause: cause.code || cause.message },
+      );
+    }
+  }
+  return {
+    status: 'healthy',
+    manifest: file,
+    platform: actual.platform,
+    arch: actual.arch,
+    modules: actual.modules,
+    native_module: nativeFile,
+    native_sha256: digest,
+  };
+}
+
+module.exports = {
+  MANIFEST_FILE,
+  RuntimeNativeError,
+  inspectRuntimeNative,
+};

package/adapters/claude.js

@@ -14,7 +14,11 @@ const {
   removeTree,
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
-const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const {
+  applyNativeDoctor,
+  buildMcpRuntime,
+  mcpCommand,
+} = require('./_shared/codex-assets.cjs');
 const { parse: parseFrontmatter, serialize: serializeFrontmatter } = require('./_shared/frontmatter.cjs');
 const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
@@ -139,83 +143,109 @@ function buildHooksManifest() {
   };
 }
 
-function install(ctx = {}) {
-  const target = resolvePluginRoot(ctx);
-  const repoRoot = resolveRepoRoot(ctx);
-  if (fs.existsSync(target)) {
-    const entries = fs.readdirSync(target);
-    if (entries.length > 0 && !isManaged(target)) {
-      throw new Error(`refusing to replace unmanaged Claude plugin: ${target}`);
-    }
-    if (entries.length > 0) removeTree(target);
-  }
-  ensureDir(target);
-
+function buildStaging(repoRoot, staging, target) {
   const report = { target, copied: {}, config: { updated: false } };
-  report.copied.commands = copyCommands(repoRoot, target);
-  report.copied.skills = copySkills(repoRoot, target, skillsForRuntime('claude'));
-  report.copied.agents = copyTree(path.join(repoRoot, 'agents'), path.join(target, 'agents'));
+  report.copied.commands = copyCommands(repoRoot, staging);
+  report.copied.skills = copySkills(repoRoot, staging, skillsForRuntime('claude'));
+  report.copied.agents = copyTree(path.join(repoRoot, 'agents'), path.join(staging, 'agents'));
 
-  ensureDir(path.join(target, 'hooks'));
+  ensureDir(path.join(staging, 'hooks'));
   report.copied.hooks = [];
   for (const name of WORKFLOW_HOOK_FILES) {
-    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(target, 'hooks', name));
+    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(staging, 'hooks', name));
     report.copied.hooks.push(name);
   }
-  writeAtomic(path.join(target, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
+  writeAtomic(path.join(staging, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
 
-  const runtime = buildMcpRuntime(repoRoot, target, { runtime: 'claude' });
-  writeAtomic(path.join(target, '.mcp.json'), JSON.stringify({
+  buildMcpRuntime(repoRoot, staging, { runtime: 'claude' });
+  const command = mcpCommand(path.join(target, 'runtime', 'launch.cjs'));
+  writeAtomic(path.join(staging, '.mcp.json'), JSON.stringify({
     mcpServers: {
       [MCP_SERVER_NAME]: {
-        command: process.execPath,
-        args: [runtime.launcher],
+        command: command.command,
+        args: command.args,
       },
     },
   }, null, 2) + '\n');
 
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
-  writeAtomic(path.join(target, '.claude-plugin', 'plugin.json'), JSON.stringify({
+  writeAtomic(path.join(staging, '.claude-plugin', 'plugin.json'), JSON.stringify({
     name: PLUGIN_NAME,
     version: pkg.version,
-    description: 'Claude Code native Ultra Builder Pro workflows, agents, hooks, and MCP task state.',
+    description: 'Claude Code native Ultra Builder Pro workflows with a persistent safety kernel.',
     author: { name: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors' },
     repository: pkg.homepage,
     license: pkg.license || 'MIT',
   }, null, 2) + '\n');
-  markManaged(target, { adapter: 'claude', plugin: PLUGIN_NAME });
+  markManaged(staging, { adapter: 'claude', plugin: PLUGIN_NAME });
   const source = provenance.packageSource(repoRoot);
-  const provenanceFile = path.join(target, PROVENANCE_FILE);
+  const provenanceFile = path.join(staging, PROVENANCE_FILE);
   report.provenance = provenance.writeProvenance({
     file: provenanceFile,
     adapter: 'claude',
     ...source,
     roots: { plugin: target },
-    assets: provenance.assetRefsForTree('plugin', target, {
+    assetRoots: { plugin: staging },
+    assets: provenance.assetRefsForTree('plugin', staging, {
       exclude: ['.ubp-managed', PROVENANCE_FILE],
     }),
     contracts: {
       plugin_manifest: { root: 'plugin', path: '.claude-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      native_runtime: { root: 'plugin', path: 'runtime/native-runtime.json' },
+      context_envelope_helper: { root: 'plugin', path: 'runtime/hook-context.cjs' },
       hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       checkpoint_hook: { root: 'plugin', path: 'hooks/workflow_checkpoint.py' },
       resume_hook: { root: 'plugin', path: 'hooks/workflow_resume.py' },
     },
   });
-  report.provenance.file = provenanceFile;
+  report.provenance.file = path.join(target, PROVENANCE_FILE);
   return report;
 }
 
+function install(ctx = {}) {
+  const target = resolvePluginRoot(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  if (fs.existsSync(target)) {
+    const entries = fs.readdirSync(target);
+    if (entries.length > 0 && !isManaged(target)) {
+      throw new Error(`refusing to replace unmanaged Claude plugin: ${target}`);
+    }
+  }
+  ensureDir(path.dirname(target));
+  const staging = fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-staging-`));
+  const backup = `${staging}-previous`;
+  let movedPrevious = false;
+  let published = false;
+  try {
+    const report = buildStaging(repoRoot, staging, target);
+    if (fs.existsSync(target)) {
+      fs.renameSync(target, backup);
+      movedPrevious = true;
+    }
+    fs.renameSync(staging, target);
+    published = true;
+    if (movedPrevious) removeTree(backup);
+    return report;
+  } catch (error) {
+    if (published && fs.existsSync(target)) removeTree(target);
+    else if (fs.existsSync(staging)) removeTree(staging);
+    if (movedPrevious && fs.existsSync(backup)) fs.renameSync(backup, target);
+    throw error;
+  }
+}
+
 function doctor(ctx = {}) {
   const repoRoot = resolveRepoRoot(ctx);
   const source = provenance.packageSource(repoRoot);
-  return provenance.inspectProvenance({
+  const report = provenance.inspectProvenance({
     file: path.join(resolvePluginRoot(ctx), PROVENANCE_FILE),
     expectedAdapter: 'claude',
     expectedPackageVersion: source.packageInfo.version,
   });
+  return applyNativeDoctor(report, path.join(resolvePluginRoot(ctx), 'runtime'));
 }
 
 function uninstall(ctx = {}) {

package/adapters/codex.js

@@ -30,6 +30,7 @@ const {
 const {
   PLUGIN_NAME,
   MANAGED_MARKER,
+  applyNativeDoctor,
   buildPlugin,
   installAgents,
 } = require('./_shared/codex-assets.cjs');
@@ -145,13 +146,18 @@ function marketplaceEntry() {
 }
 
 function upsertMarketplace(file) {
+  const payload = mergedMarketplace(file);
+  writeAtomic(file, JSON.stringify(payload, null, 2) + '\n');
+  return { file, name: payload.name, entry: marketplaceEntry() };
+}
+
+function mergedMarketplace(file) {
   const payload = loadMarketplace(file);
   const entry = marketplaceEntry();
   const index = payload.plugins.findIndex((plugin) => plugin && plugin.name === PLUGIN_NAME);
   if (index === -1) payload.plugins.push(entry);
   else payload.plugins[index] = entry;
-  writeAtomic(file, JSON.stringify(payload, null, 2) + '\n');
-  return { file, name: payload.name, entry };
+  return payload;
 }
 
 function removeMarketplaceEntry(file) {
@@ -300,6 +306,54 @@ function writeRuntimeManifest(configDir, data) {
   return file;
 }
 
+function captureFiles(files) {
+  return [...new Set(files)].map((file) => {
+    try {
+      const stat = fs.statSync(file);
+      return { file, exists: true, contents: fs.readFileSync(file), mode: stat.mode & 0o7777 };
+    } catch (error) {
+      if (error.code === 'ENOENT') return { file, exists: false };
+      throw error;
+    }
+  });
+}
+
+function restoreFiles(snapshots) {
+  for (const snapshot of snapshots) {
+    if (!snapshot.exists) {
+      try {
+        fs.unlinkSync(snapshot.file);
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      continue;
+    }
+    writeAtomic(snapshot.file, snapshot.contents);
+    fs.chmodSync(snapshot.file, snapshot.mode);
+  }
+}
+
+function publishStagedAgents(staged, configDir) {
+  const targetRoot = path.join(configDir, 'agents');
+  ensureDir(targetRoot);
+  for (const file of staged.installed) {
+    const target = path.join(targetRoot, file);
+    if (fs.existsSync(target)) {
+      const existing = fs.readFileSync(target, 'utf8');
+      if (!existing.startsWith(`# ${MANAGED_MARKER}`)) {
+        throw new Error(`refusing to overwrite unmanaged Codex agent: ${target}`);
+      }
+    }
+  }
+  for (const file of staged.installed) {
+    writeAtomic(
+      path.join(targetRoot, file),
+      fs.readFileSync(path.join(staged.root, file)),
+    );
+  }
+  return { root: targetRoot, installed: staged.installed };
+}
+
 function install(ctx = {}) {
   const configDir = resolveTarget(ctx);
   const repoRoot = resolveRepoRoot(ctx);
@@ -308,93 +362,137 @@ function install(ctx = {}) {
   ensureDir(configDir);
 
   const previousManifest = readRuntimeManifest(configDir);
-  const legacy = cleanupLegacyConfig(configDir);
-  const plugin = buildPlugin({ repoRoot, pluginRoot });
-  const agents = installAgents({ repoRoot, configDir });
-  const marketplace = upsertMarketplace(marketplaceFile);
-  const previousVersions = listKnownHookCacheVersions(
-    configDir,
-    marketplace.name,
-    previousManifest,
-  );
-
+  if (fs.existsSync(pluginRoot) && !isManaged(pluginRoot)) {
+    throw new Error(`refusing to replace unmanaged plugin directory: ${pluginRoot}`);
+  }
+  ensureDir(path.dirname(pluginRoot));
+  const stagingRoot = fs.mkdtempSync(path.join(path.dirname(pluginRoot), `.${PLUGIN_NAME}-staging-`));
+  const backupRoot = `${stagingRoot}-previous`;
+  const agentStagingConfig = fs.mkdtempSync(path.join(configDir, `.${PLUGIN_NAME}-agents-`));
+  let plugin = null;
+  let stagedAgents = null;
+  let agents = null;
+  let marketplace = null;
+  let previousVersions = [];
+  let previousAdapters = [];
+  let snapshots = [];
+  let movedPrevious = false;
+  let published = false;
   let registration = null;
   let hookCompatibility = null;
-  if (shouldRunPluginCli(ctx)) {
-    const previousAdapters = hookAdaptersForVersions(
+  let legacy = { configUpdated: false, removed: [] };
+  try {
+    plugin = buildPlugin({ repoRoot, pluginRoot: stagingRoot, publishedRoot: pluginRoot });
+    stagedAgents = installAgents({ repoRoot, configDir: agentStagingConfig });
+    const marketplacePayload = mergedMarketplace(marketplaceFile);
+    marketplace = {
+      file: marketplaceFile,
+      name: marketplacePayload.name,
+      entry: marketplaceEntry(),
+    };
+    previousVersions = listKnownHookCacheVersions(
+      configDir,
+      marketplace.name,
+      previousManifest,
+    );
+    previousAdapters = hookAdaptersForVersions(
       configDir,
       marketplace.name,
       previousVersions,
     );
-    try {
+    snapshots = captureFiles([
+      marketplaceFile,
+      runtimeManifestFile(configDir),
+      path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE),
+      ...stagedAgents.installed.map((file) => path.join(configDir, 'agents', file)),
+      ...previousAdapters,
+    ]);
+
+    if (fs.existsSync(pluginRoot)) {
+      fs.renameSync(pluginRoot, backupRoot);
+      movedPrevious = true;
+    }
+    fs.renameSync(stagingRoot, pluginRoot);
+    published = true;
+    agents = publishStagedAgents(stagedAgents, configDir);
+    writeAtomic(marketplaceFile, JSON.stringify(marketplacePayload, null, 2) + '\n');
+
+    if (shouldRunPluginCli(ctx)) {
       registration = runPluginCli('add', marketplace.name, ctx);
-    } catch (registrationError) {
-      try {
-        hookCompatibility = restoreCachedHookAdapters(
-          previousAdapters,
-          currentHookAdapter(configDir, marketplace.name, plugin),
-        );
-      } catch (recoveryError) {
-        throw new AggregateError(
-          [registrationError, recoveryError],
-          `codex plugin add and hook cache recovery both failed`,
-        );
+      hookCompatibility = restoreCachedHookAdapters(
+        previousAdapters,
+        currentHookAdapter(configDir, marketplace.name, plugin),
+      );
+    }
+    const hookCacheVersions = normalizeHookCacheVersions([
+      ...previousVersions,
+      plugin.version,
+    ]);
+    const manifestFile = writeRuntimeManifest(configDir, {
+      plugin: { root: plugin.root, version: plugin.version },
+      marketplace: { file: marketplace.file, name: marketplace.name },
+      agents: agents.installed,
+      hookCacheVersions,
+    });
+    const source = provenance.packageSource(repoRoot);
+    const provenanceFile = path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE);
+    const provenanceManifest = provenance.writeProvenance({
+      file: provenanceFile,
+      adapter: 'codex',
+      ...source,
+      roots: { plugin: pluginRoot, config: configDir },
+      assets: [
+        ...provenance.assetRefsForTree('plugin', pluginRoot, {
+          exclude: ['.ubp-managed'],
+        }),
+        ...agents.installed.map((file) => ({ root: 'config', path: path.join('agents', file) })),
+        { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+      ],
+      contracts: {
+        plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
+        mcp_registration: { root: 'plugin', path: '.mcp.json' },
+        mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+        native_runtime: { root: 'plugin', path: 'runtime/native-runtime.json' },
+        context_envelope_helper: { root: 'plugin', path: 'runtime/hook-context.cjs' },
+        hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
+        hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+        hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
+        runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+      },
+    });
+    provenanceManifest.file = provenanceFile;
+    legacy = cleanupLegacyConfig(configDir);
+    if (movedPrevious) removeTree(backupRoot);
+    removeTree(agentStagingConfig);
+    return {
+      target: configDir,
+      plugin,
+      agents,
+      marketplace,
+      registration,
+      hookCompatibility,
+      legacy,
+      manifestFile,
+      provenance: provenanceManifest,
+      config: { updated: legacy.configUpdated },
+    };
+  } catch (error) {
+    if (published && fs.existsSync(pluginRoot)) removeTree(pluginRoot);
+    else if (fs.existsSync(stagingRoot)) removeTree(stagingRoot);
+    if (movedPrevious && fs.existsSync(backupRoot)) fs.renameSync(backupRoot, pluginRoot);
+    try {
+      restoreFiles(snapshots);
+      const currentCache = marketplace && plugin
+        ? path.join(pluginCacheRoot(configDir, marketplace.name), plugin.version)
+        : null;
+      if (currentCache && !previousVersions.includes(plugin.version) && fs.existsSync(currentCache)) {
+        removeTree(currentCache);
       }
-      throw registrationError;
+    } finally {
+      if (fs.existsSync(agentStagingConfig)) removeTree(agentStagingConfig);
     }
-    hookCompatibility = restoreCachedHookAdapters(
-      previousAdapters,
-      currentHookAdapter(configDir, marketplace.name, plugin),
-    );
+    throw error;
   }
-  const hookCacheVersions = normalizeHookCacheVersions([
-    ...previousVersions,
-    plugin.version,
-  ]);
-  const manifestFile = writeRuntimeManifest(configDir, {
-    plugin: { root: plugin.root, version: plugin.version },
-    marketplace: { file: marketplace.file, name: marketplace.name },
-    agents: agents.installed,
-    hookCacheVersions,
-  });
-  const source = provenance.packageSource(repoRoot);
-  const provenanceFile = path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE);
-  const provenanceManifest = provenance.writeProvenance({
-    file: provenanceFile,
-    adapter: 'codex',
-    ...source,
-    roots: { plugin: pluginRoot, config: configDir },
-    assets: [
-      ...provenance.assetRefsForTree('plugin', pluginRoot, {
-        exclude: ['.ubp-managed'],
-      }),
-      ...agents.installed.map((file) => ({ root: 'config', path: path.join('agents', file) })),
-      { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
-    ],
-    contracts: {
-      plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
-      mcp_registration: { root: 'plugin', path: '.mcp.json' },
-      mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
-      hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
-      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
-      hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
-      runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
-    },
-  });
-  provenanceManifest.file = provenanceFile;
-
-  return {
-    target: configDir,
-    plugin,
-    agents,
-    marketplace,
-    registration,
-    hookCompatibility,
-    legacy,
-    manifestFile,
-    provenance: provenanceManifest,
-    config: { updated: legacy.configUpdated },
-  };
 }
 
 function doctor(ctx = {}) {
@@ -452,8 +550,7 @@ function doctor(ctx = {}) {
     }
   }
   report.checks.hook_targets = { status: hookTargetsOk ? 'pass' : 'fail' };
-  if (report.status !== 'missing') report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
-  return report;
+  return applyNativeDoctor(report, path.join(pluginRoot, 'runtime'));
 }
 
 function removeManagedAgents(configDir, manifest) {