ultra-builder-pro-cli 0.5.0

package/adapters/codex.js

@@ -0,0 +1,385 @@
+'use strict';
+
+/**
+ * Codex adapter.
+ *
+ * Codex-native mapping:
+ *   commands/*.md       -> explicit plugin skills ($ultra-builder-pro:<name>)
+ *   skills/**           -> ~/plugins/ultra-builder-pro/skills/**
+ *   agents/*.md         -> ~/.codex/agents/*.toml
+ *   hooks/*.py          -> plugin hooks with a Codex wire adapter
+ *   mcp-server          -> plugin .mcp.json (project cwd owns .ultra/state.db)
+ *   plugin marketplace  -> ~/.agents/plugins/marketplace.json
+ *
+ * Deprecated ~/.codex/prompts and ~/.codex/skills projection is intentionally
+ * not used. The plugin remains the single distribution boundary for skills,
+ * hooks, and MCP; custom agents use Codex's standalone TOML surface.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const {
+  ensureDir,
+  isManaged,
+  removeTree,
+  writeAtomic,
+} = require('./_shared/file-ops.cjs');
+const {
+  PLUGIN_NAME,
+  MANAGED_MARKER,
+  buildPlugin,
+  installAgents,
+} = require('./_shared/codex-assets.cjs');
+
+const MCP_SERVER_NAME = PLUGIN_NAME;
+const SOURCE_TAG = 'ubp';
+const MARKER_BEGIN = '# >>> ultra-builder-pro managed block — do not edit by hand';
+const MARKER_END = '# <<< ultra-builder-pro managed block';
+const RUNTIME_MANIFEST_DIR = 'ultra-builder-pro';
+const RUNTIME_MANIFEST_FILE = 'install-manifest.json';
+const HOOK_ADAPTER_RELATIVE = path.join('hooks', 'adapters', 'codex.py');
+
+function resolveTarget(ctx = {}) {
+  if (ctx.configDir) return path.resolve(ctx.configDir);
+  if (ctx.scope === 'global') {
+    return process.env.CODEX_HOME || path.join(ctx.homeDir || os.homedir(), '.codex');
+  }
+  return path.join(ctx.cwd || process.cwd(), '.codex');
+}
+
+function resolveHomeDir(ctx = {}) {
+  return path.resolve(ctx.homeDir || os.homedir());
+}
+
+function resolveRepoRoot(ctx = {}) {
+  return ctx.repoRoot || path.resolve(__dirname, '..');
+}
+
+function resolvePluginRoot(ctx = {}) {
+  return path.join(resolveHomeDir(ctx), 'plugins', PLUGIN_NAME);
+}
+
+function resolveMarketplaceFile(ctx = {}) {
+  return path.join(resolveHomeDir(ctx), '.agents', 'plugins', 'marketplace.json');
+}
+
+function runtimeManifestFile(configDir) {
+  return path.join(configDir, RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE);
+}
+
+function stripManagedBlock(text) {
+  const begin = text.indexOf(MARKER_BEGIN);
+  if (begin === -1) return text;
+  const end = text.indexOf(MARKER_END, begin);
+  if (end === -1) return text;
+  const endLine = text.indexOf('\n', end);
+  const after = endLine === -1 ? text.length : endLine + 1;
+  const leading = text.slice(0, begin).replace(/\n+$/, '\n');
+  return leading + text.slice(after);
+}
+
+function hasManagedBlock(text) {
+  return text.includes(MARKER_BEGIN);
+}
+
+function cleanupLegacyConfig(configDir) {
+  const configFile = path.join(configDir, 'config.toml');
+  let configUpdated = false;
+  if (fs.existsSync(configFile)) {
+    const existing = fs.readFileSync(configFile, 'utf8');
+    if (hasManagedBlock(existing)) {
+      const stripped = stripManagedBlock(existing);
+      if (stripped.trim()) writeAtomic(configFile, stripped);
+      else fs.unlinkSync(configFile);
+      configUpdated = true;
+    }
+  }
+
+  const removed = [];
+  for (const sub of ['skills', 'prompts']) {
+    const dir = path.join(configDir, sub);
+    if (fs.existsSync(dir) && isManaged(dir)) {
+      removeTree(dir);
+      removed.push(sub);
+    }
+  }
+  return { configUpdated, removed };
+}
+
+function loadMarketplace(file) {
+  if (!fs.existsSync(file)) {
+    return {
+      name: 'personal',
+      interface: { displayName: 'Personal' },
+      plugins: [],
+    };
+  }
+  const payload = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error(`${file} must contain a JSON object`);
+  }
+  if (typeof payload.name !== 'string' || !payload.name.trim()) {
+    throw new Error(`${file} must contain a non-empty marketplace name`);
+  }
+  if (!payload.interface || typeof payload.interface !== 'object' || Array.isArray(payload.interface)) {
+    payload.interface = { displayName: 'Personal' };
+  }
+  if (!Array.isArray(payload.plugins)) {
+    throw new Error(`${file} field plugins must be an array`);
+  }
+  return payload;
+}
+
+function marketplaceEntry() {
+  return {
+    name: PLUGIN_NAME,
+    source: { source: 'local', path: `./plugins/${PLUGIN_NAME}` },
+    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+    category: 'Developer Tools',
+  };
+}
+
+function upsertMarketplace(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 };
+}
+
+function removeMarketplaceEntry(file) {
+  if (!fs.existsSync(file)) return { file, updated: false, name: 'personal' };
+  const payload = loadMarketplace(file);
+  const next = payload.plugins.filter((plugin) => !plugin || plugin.name !== PLUGIN_NAME);
+  if (next.length === payload.plugins.length) {
+    return { file, updated: false, name: payload.name };
+  }
+  payload.plugins = next;
+  writeAtomic(file, JSON.stringify(payload, null, 2) + '\n');
+  return { file, updated: true, name: payload.name };
+}
+
+function shouldRunPluginCli(ctx = {}) {
+  if (typeof ctx.runPluginCli === 'boolean') return ctx.runPluginCli;
+  return ctx.scope === 'global' && !ctx.configDir;
+}
+
+function runPluginCli(action, marketplaceName, ctx = {}) {
+  const codexBin = ctx.codexBin || 'codex';
+  const selector = `${PLUGIN_NAME}@${marketplaceName}`;
+  const args = action === 'add'
+    ? ['plugin', 'add', selector, '--json']
+    : ['plugin', 'remove', selector];
+  const result = spawnSync(codexBin, args, { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    throw new Error(`codex plugin ${action} failed${detail ? `: ${detail}` : ''}`);
+  }
+  return { selector, stdout: result.stdout.trim() };
+}
+
+function pluginCacheRoot(configDir, marketplaceName) {
+  if (typeof marketplaceName !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(marketplaceName)) {
+    throw new Error(`invalid Codex marketplace name: ${marketplaceName}`);
+  }
+  return path.join(configDir, 'plugins', 'cache', marketplaceName, PLUGIN_NAME);
+}
+
+function listCachedHookAdapters(configDir, marketplaceName) {
+  const root = pluginCacheRoot(configDir, marketplaceName);
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(root, entry.name, HOOK_ADAPTER_RELATIVE))
+    .filter((file) => fs.existsSync(file))
+    .sort();
+}
+
+function hookForwarder(target) {
+  return `#!/usr/bin/env python3
+"""Forward a live Codex task from a retired plugin cache to the current adapter."""
+
+import runpy
+
+runpy.run_path(${JSON.stringify(path.resolve(target))}, run_name="__main__")
+`;
+}
+
+function restoreCachedHookAdapters(previousAdapters, target) {
+  const resolvedTarget = path.resolve(target);
+  if (!fs.existsSync(resolvedTarget)) {
+    throw new Error(`current Codex hook adapter is missing: ${resolvedTarget}`);
+  }
+  const restored = [];
+  for (const previous of previousAdapters) {
+    if (path.resolve(previous) === resolvedTarget || fs.existsSync(previous)) continue;
+    writeAtomic(previous, hookForwarder(resolvedTarget));
+    restored.push(previous);
+  }
+  return { target: resolvedTarget, restored };
+}
+
+function currentHookAdapter(configDir, marketplaceName, plugin) {
+  const cached = path.join(pluginCacheRoot(configDir, marketplaceName), plugin.version, HOOK_ADAPTER_RELATIVE);
+  if (fs.existsSync(cached)) return cached;
+  return path.join(plugin.root, HOOK_ADAPTER_RELATIVE);
+}
+
+function writeRuntimeManifest(configDir, data) {
+  const file = runtimeManifestFile(configDir);
+  writeAtomic(file, JSON.stringify({
+    source: SOURCE_TAG,
+    adapter: 'codex',
+    plugin: data.plugin,
+    marketplace: data.marketplace,
+    agents: data.agents,
+  }, null, 2) + '\n');
+  return file;
+}
+
+function install(ctx = {}) {
+  const configDir = resolveTarget(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const marketplaceFile = resolveMarketplaceFile(ctx);
+  ensureDir(configDir);
+
+  const legacy = cleanupLegacyConfig(configDir);
+  const plugin = buildPlugin({ repoRoot, pluginRoot });
+  const agents = installAgents({ repoRoot, configDir });
+  const marketplace = upsertMarketplace(marketplaceFile);
+  const manifestFile = writeRuntimeManifest(configDir, {
+    plugin: { root: plugin.root, version: plugin.version },
+    marketplace: { file: marketplace.file, name: marketplace.name },
+    agents: agents.installed,
+  });
+
+  let registration = null;
+  let hookCompatibility = null;
+  if (shouldRunPluginCli(ctx)) {
+    const previousAdapters = listCachedHookAdapters(configDir, marketplace.name);
+    try {
+      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`,
+        );
+      }
+      throw registrationError;
+    }
+    hookCompatibility = restoreCachedHookAdapters(
+      previousAdapters,
+      currentHookAdapter(configDir, marketplace.name, plugin),
+    );
+  }
+
+  return {
+    target: configDir,
+    plugin,
+    agents,
+    marketplace,
+    registration,
+    hookCompatibility,
+    legacy,
+    manifestFile,
+    config: { updated: legacy.configUpdated },
+  };
+}
+
+function removeManagedAgents(configDir, manifest) {
+  const agentRoot = path.join(configDir, 'agents');
+  const requested = manifest && Array.isArray(manifest.agents)
+    ? manifest.agents
+    : (fs.existsSync(agentRoot) ? fs.readdirSync(agentRoot).filter((name) => name.endsWith('.toml')) : []);
+  const removed = [];
+  for (const file of requested) {
+    const target = path.join(agentRoot, path.basename(file));
+    if (!fs.existsSync(target)) continue;
+    const contents = fs.readFileSync(target, 'utf8');
+    if (!contents.startsWith(`# ${MANAGED_MARKER}`)) continue;
+    fs.unlinkSync(target);
+    removed.push(path.basename(target));
+  }
+  return removed;
+}
+
+function readRuntimeManifest(configDir) {
+  const file = runtimeManifestFile(configDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`invalid Codex runtime manifest ${file}: ${error.message}`, { cause: error });
+  }
+}
+
+function uninstall(ctx = {}) {
+  const configDir = resolveTarget(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const marketplaceFile = resolveMarketplaceFile(ctx);
+  const manifest = readRuntimeManifest(configDir);
+  const marketplaceBefore = loadMarketplace(marketplaceFile);
+
+  const registration = shouldRunPluginCli(ctx)
+    ? runPluginCli('remove', marketplaceBefore.name, ctx)
+    : null;
+  const agents = removeManagedAgents(configDir, manifest);
+
+  let pluginRemoved = false;
+  if (fs.existsSync(pluginRoot) && fs.existsSync(path.join(pluginRoot, '.ubp-managed'))) {
+    removeTree(pluginRoot);
+    pluginRemoved = true;
+  }
+  const marketplace = removeMarketplaceEntry(marketplaceFile);
+  const legacy = cleanupLegacyConfig(configDir);
+  const manifestDir = path.join(configDir, RUNTIME_MANIFEST_DIR);
+  if (fs.existsSync(manifestDir)) removeTree(manifestDir);
+
+  return {
+    target: configDir,
+    removed: { plugin: pluginRemoved, agents },
+    marketplace,
+    registration,
+    legacy,
+    config: { updated: legacy.configUpdated },
+  };
+}
+
+module.exports = {
+  name: 'codex',
+  MCP_SERVER_NAME,
+  MARKER_BEGIN,
+  MARKER_END,
+  SOURCE_TAG,
+  resolveTarget,
+  resolveHomeDir,
+  resolvePluginRoot,
+  resolveMarketplaceFile,
+  install,
+  uninstall,
+  _internal: {
+    stripManagedBlock,
+    hasManagedBlock,
+    cleanupLegacyConfig,
+    loadMarketplace,
+    upsertMarketplace,
+    removeMarketplaceEntry,
+    runPluginCli,
+    pluginCacheRoot,
+    listCachedHookAdapters,
+    restoreCachedHookAdapters,
+  },
+};

package/adapters/gemini.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * Gemini CLI adapter — Phase 4.5 installer (extension-packaged).
+ *
+ * Target config dirs:
+ *   global: $GEMINI_CONFIG_DIR → ~/.gemini
+ *   local:  <cwd>/.gemini
+ *
+ * Layout — everything is packaged as a Gemini extension under
+ * <target>/extensions/ultra-builder-pro/:
+ *
+ *   gemini-extension.json  → extension manifest (mcpServers declared here)
+ *   commands/*.toml        → generated from commands/*.md via md-to-toml
+ *   skills/**              → Ultra-owned allowlist (Gemini reads these as prompt includes)
+ *   GEMINI.md              → canonical agent context (docs/AGENT-CONTEXT.md copy)
+ *   hooks/                 → NOT installed; Gemini has no hook surface.
+ *                            prompt-guard downgrade is described inside GEMINI.md.
+ *
+ * Scope boundaries (documented):
+ *   - Gemini has no hook event loop; runtime-enforced guards degrade to
+ *     prompt-level guidance (hooks/adapters/gemini.py explains).
+ *   - Subagent registration requires the upstream spec to settle — Phase 4.5
+ *     spike captures whatever shape lands.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  copyTree,
+  writeAtomic,
+  ensureDir,
+  removeTree,
+} = require('./_shared/file-ops.cjs');
+const { mdCommandToToml } = require('./_shared/md-to-toml.cjs');
+const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const { skillsForRuntime } = require('./_shared/runtime-assets.cjs');
+
+const EXTENSION_NAME = 'ultra-builder-pro';
+const MCP_SERVER_NAME = 'ultra-builder-pro';
+const SOURCE_TAG = 'ubp';
+
+function resolveTarget(ctx) {
+  if (ctx.configDir) return ctx.configDir;
+  if (ctx.scope === 'global') {
+    return process.env.GEMINI_CONFIG_DIR || path.join(ctx.homeDir || os.homedir(), '.gemini');
+  }
+  return path.join(ctx.cwd || process.cwd(), '.gemini');
+}
+
+function resolveExtensionRoot(ctx) {
+  return path.join(resolveTarget(ctx), 'extensions', EXTENSION_NAME);
+}
+
+function resolveRepoRoot(ctx) {
+  return ctx.repoRoot || path.resolve(__dirname, '..');
+}
+
+function loadPkgVersion(repoRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).version;
+  } catch (err) {
+    // Fall back to 0.0.0 but surface the reason — silent swallow hid a
+    // real "package.json moved" regression in a Phase 4 code review.
+    process.stderr.write(`gemini adapter: loadPkgVersion fell back to 0.0.0 (${err.message})\n`);
+    return '0.0.0';
+  }
+}
+
+function buildManifest(repoRoot, runtime) {
+  return {
+    name: EXTENSION_NAME,
+    version: loadPkgVersion(repoRoot),
+    description: 'Ultra Builder Pro — skill/MCP/CLI agent engineering system (Gemini packaging).',
+    // Sibling identification block — outside env so it cannot leak into the
+    // MCP server's child process (P2 #9). Uninstall reads manifest._ubp.source.
+    _ubp: { source: SOURCE_TAG },
+    mcpServers: {
+      [MCP_SERVER_NAME]: {
+        command: process.execPath,
+        args: [runtime.launcher],
+        _ubp: { source: SOURCE_TAG },
+      },
+    },
+    contextFileName: 'GEMINI.md',
+  };
+}
+
+function ownsExtension(extensionRoot) {
+  const manifestFile = path.join(extensionRoot, 'gemini-extension.json');
+  if (!fs.existsSync(manifestFile)) return false;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    return manifest?._ubp?.source === SOURCE_TAG;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function install(ctx) {
+  const extensionRoot = resolveExtensionRoot(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  if (fs.existsSync(extensionRoot)) {
+    const entries = fs.readdirSync(extensionRoot);
+    if (entries.length > 0 && !ownsExtension(extensionRoot)) {
+      throw new Error(`refusing to replace unmanaged Gemini extension: ${extensionRoot}`);
+    }
+    if (entries.length > 0) {
+      for (const managed of ['skills', 'commands', 'runtime', 'spec', 'templates']) {
+        removeTree(path.join(extensionRoot, managed));
+      }
+      for (const managed of ['GEMINI.md', 'gemini-extension.json']) {
+        const file = path.join(extensionRoot, managed);
+        if (fs.existsSync(file)) fs.unlinkSync(file);
+      }
+    }
+  }
+  ensureDir(extensionRoot);
+
+  const report = { target: extensionRoot, copied: {}, config: { updated: false } };
+
+  // 1. Skills — copy only the canonical Ultra-owned allowlist.
+  const skillsSrc = path.join(repoRoot, 'skills');
+  report.copied.skills = [];
+  for (const name of skillsForRuntime('gemini')) {
+    const source = path.join(skillsSrc, name);
+    if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+      throw new Error(`missing allowlisted Gemini skill: ${name}`);
+    }
+    const files = copyTree(source, path.join(extensionRoot, 'skills', name));
+    report.copied.skills.push(...files.map((file) => path.join(name, file)));
+  }
+
+  // 2. Commands — md → toml
+  const commandsSrc = path.join(repoRoot, 'commands');
+  if (fs.existsSync(commandsSrc)) {
+    const dstCommands = path.join(extensionRoot, 'commands');
+    ensureDir(dstCommands);
+    const tomlFiles = [];
+    for (const f of fs.readdirSync(commandsSrc)) {
+      if (!f.endsWith('.md')) continue;
+      const md = fs.readFileSync(path.join(commandsSrc, f), 'utf8');
+      const tomlName = f.replace(/\.md$/, '.toml');
+      writeAtomic(path.join(dstCommands, tomlName), mdCommandToToml(md));
+      tomlFiles.push(tomlName);
+    }
+    report.copied.commands = tomlFiles;
+  }
+
+  // 3. GEMINI.md — copy docs/AGENT-CONTEXT.md into the extension context file
+  const agentContext = path.join(repoRoot, 'docs', 'AGENT-CONTEXT.md');
+  if (fs.existsSync(agentContext)) {
+    const dst = path.join(extensionRoot, 'GEMINI.md');
+    fs.copyFileSync(agentContext, dst);
+    report.copied.context = 'GEMINI.md';
+  }
+
+  // 4. Manifest
+  const runtime = buildMcpRuntime(repoRoot, extensionRoot, { runtime: 'gemini' });
+  const manifest = buildManifest(repoRoot, runtime);
+  writeAtomic(
+    path.join(extensionRoot, 'gemini-extension.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
+  report.config.updated = true;
+  return report;
+}
+
+function uninstall(ctx) {
+  const extensionRoot = resolveExtensionRoot(ctx);
+  const report = { target: extensionRoot, removed: {}, config: { updated: false } };
+  if (fs.existsSync(extensionRoot)) {
+    // Manifest carries the _ubp sibling block — if tampered with, bail loud.
+    const manifestFile = path.join(extensionRoot, 'gemini-extension.json');
+    if (fs.existsSync(manifestFile)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+        if (!manifest._ubp || manifest._ubp.source !== SOURCE_TAG) {
+          throw new Error(`refusing to uninstall: ${manifestFile} was not generated by this adapter`);
+        }
+      } catch (err) {
+        if (err.message.startsWith('refusing')) throw err;
+        // malformed manifest: proceed — we still own the directory name
+      }
+    }
+    removeTree(extensionRoot);
+    report.removed.extension = true;
+    report.config.updated = true;
+  }
+  return report;
+}
+
+module.exports = {
+  name: 'gemini',
+  EXTENSION_NAME,
+  MCP_SERVER_NAME,
+  SOURCE_TAG,
+  resolveTarget,
+  resolveExtensionRoot,
+  install,
+  uninstall,
+};