ultra-builder-pro-cli 0.25.1 → 0.26.0

package/adapters/claude.js

@@ -1,44 +1,32 @@
 'use strict';
 
-/** Build a Claude Code native Ultra Builder Pro plugin. */
-
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const {
-  copyTree,
-  ensureDir,
-  isManaged,
+  copyHooks,
+  copySkills,
+  inspectPlugin,
   markManaged,
+  publishManagedTrees,
+  removeManaged,
+  writePluginProvenance,
+} = require('./_shared/plugin-core.cjs');
+const {
+  captureAbsent,
+  ensureDir,
+  managedMetadata,
+  pruneCreatedEmpty,
   removeTree,
   writeAtomic,
 } = require('./_shared/file-ops.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');
-const {
-  CORE_PUBLIC_SKILLS,
-  WORKFLOW_HOOK_FILES,
-  skillPolicy,
-  skillsForRuntime,
-} = require('./_shared/runtime-assets.cjs');
 
 const PLUGIN_NAME = 'ultra-builder-pro';
-const MCP_SERVER_NAME = PLUGIN_NAME;
-const SOURCE_TAG = 'ubp';
-const SENTINEL_KEY = '_ubp_manifest';
-const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
-const PROVENANCE_FILE = 'provenance.json';
 
 function resolveTarget(ctx = {}) {
-  if (ctx.configDir) return ctx.configDir;
+  if (ctx.configDir) return path.resolve(ctx.configDir);
   if (ctx.scope === 'global') {
     return process.env.CLAUDE_CONFIG_DIR || path.join(ctx.homeDir || os.homedir(), '.claude');
   }
@@ -46,332 +34,145 @@ function resolveTarget(ctx = {}) {
 }
 
 function resolvePluginRoot(ctx = {}) {
-  if (ctx.pluginRoot) return ctx.pluginRoot;
-  return path.join(resolveTarget(ctx), 'skills', PLUGIN_NAME);
+  return ctx.pluginRoot || path.join(resolveTarget(ctx), 'skills', PLUGIN_NAME);
 }
 
 function resolveRepoRoot(ctx = {}) {
   return ctx.repoRoot || path.resolve(__dirname, '..');
 }
 
-function shouldRunHostCli(ctx = {}) {
-  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
-  return ctx.scope === 'global' && !ctx.configDir;
-}
-
-function runClaudeCli(args, ctx = {}) {
-  const result = spawnSync(ctx.claudeBin || 'claude', args, {
-    encoding: 'utf8',
-    timeout: ctx.hostCliTimeoutMs || 30000,
-    killSignal: 'SIGKILL',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      CLAUDE_CONFIG_DIR: resolveTarget(ctx),
-    },
-  });
-  if (result.error) {
-    if (result.error.code === 'ETIMEDOUT') {
-      const error = new Error(`claude ${args.join(' ')} timed out`);
-      error.code = 'HOST_CLI_TIMEOUT';
-      throw error;
-    }
-    throw result.error;
-  }
-  if (result.status !== 0) {
-    const detail = (result.stderr || result.stdout || '').trim();
-    throw new Error(`claude ${args.join(' ')} failed${detail ? `: ${detail}` : ''}`);
-  }
-  return result.stdout;
-}
-
-function claudeMcpRow(output, identity) {
-  for (const rawLine of output.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (line.slice(0, identity.length) !== identity) continue;
-    if (line[identity.length] !== ':') continue;
-    return line;
-  }
-  return '';
-}
-
-function inspectClaudeHost(ctx = {}) {
-  const target = resolvePluginRoot(ctx);
-  const manifest = JSON.parse(
-    fs.readFileSync(path.join(target, '.claude-plugin', 'plugin.json'), 'utf8'),
-  );
-  const plugins = JSON.parse(runClaudeCli(['plugin', 'list', '--json'], ctx));
-  if (!Array.isArray(plugins)) throw new Error('claude plugin list --json did not return an array');
-  const plugin = plugins.find((entry) => entry?.id === `${PLUGIN_NAME}@skills-dir`);
-  const pluginOk = !!plugin
-    && plugin.enabled === true
-    && plugin.version === manifest.version
-    && path.resolve(plugin.installPath || '') === path.resolve(target);
-  const mcpOutput = pluginOk
-    ? runClaudeCli(['mcp', 'list'], ctx).replace(/\u001b\[[0-9;]*m/g, '')
-    : '';
-  const mcpLine = claudeMcpRow(
-    mcpOutput,
-    `plugin:${PLUGIN_NAME}:${MCP_SERVER_NAME}`,
-  );
-  const mcpOk = pluginOk
-    && !!plugin.mcpServers?.[MCP_SERVER_NAME]
-    && /\bConnected\b/i.test(mcpLine);
-  let detailsOk = false;
-  if (pluginOk) {
-    runClaudeCli(['plugin', 'details', `${PLUGIN_NAME}@skills-dir`], ctx);
-    detailsOk = true;
-  }
-  return { plugin, pluginOk, mcpOk, mcpOutput, detailsOk };
-}
-
-function copySkills(repoRoot, target, names) {
-  const copied = [];
-  for (const name of names) {
-    const source = path.join(repoRoot, 'skills', name);
-    if (!fs.existsSync(source)) throw new Error(`missing allowlisted Claude skill: ${name}`);
-    const files = copyTree(source, path.join(target, 'skills', name), {
-      transform(buf, rel) {
-        if (rel !== 'SKILL.md') {
-          return rel.endsWith('.md')
-            ? Buffer.from(adaptInteractionGuidance(buf.toString('utf8'), 'claude'))
-            : buf;
-        }
-        const { fm, body } = parseFrontmatter(buf.toString('utf8'));
-        if (!fm) throw new Error(`missing frontmatter in Claude skill: ${name}`);
-        let adaptedBody = adaptInteractionGuidance(body, 'claude');
-        if (name === 'ultra-review') {
-          adaptedBody = adaptedBody.replace(
-            /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
-            'Claude Code Task workers using the installed review agent definitions',
-          );
-        }
-        const policy = skillPolicy(name);
-        return Buffer.from(serializeFrontmatter({
-          name,
-          description: fm.description,
-          'user-invocable': policy.userInvocable,
-          ...(policy.userInvocable ? { 'disable-model-invocation': true } : {}),
-        }, adaptedBody));
-      },
-    });
-    copied.push(...files.map((rel) => path.join(name, rel)));
-  }
-  return copied;
-}
-
-function copyCommands(repoRoot, target) {
-  const commandRoot = path.join(target, 'commands');
-  ensureDir(commandRoot);
-  const copied = [];
-  for (const name of COMMAND_NAMES) {
-    const file = `${name}.md`;
-    const source = path.join(repoRoot, 'commands', file);
-    if (!fs.existsSync(source)) throw new Error(`missing allowlisted Claude command: ${file}`);
-    fs.copyFileSync(source, path.join(commandRoot, file));
-    copied.push(file);
-  }
-  return copied;
-}
-
-function hookCommand(name, ...args) {
+function hookCommand(name) {
   return {
     type: 'command',
-    command: [
-      `python3 "\${CLAUDE_PLUGIN_ROOT}/hooks/${name}"`,
-      ...args.map((arg) => JSON.stringify(arg)),
-    ].join(' '),
+    command: `python3 "\${CLAUDE_PLUGIN_ROOT}/hooks/${name}"`,
     timeout: 10,
   };
 }
 
 function buildHooksManifest() {
   return {
-    description: 'Ultra workflow lifecycle hooks; inactive outside projects with an active .ultra workflow.',
+    description: 'Ultra file-first context sensors and narrow effect protection.',
     hooks: {
       SessionStart: [
-        {
-          matcher: 'startup|resume|clear',
-          hooks: [hookCommand('health_check.py'), hookCommand('workflow_context.py')],
-        },
-        { matcher: 'compact', hooks: [hookCommand('workflow_resume.py')] },
+        { matcher: 'startup|resume|clear', hooks: [hookCommand('session_context.py')] },
+        { matcher: 'compact', hooks: [hookCommand('compact_context.py')] },
       ],
       PreToolUse: [
-        { matcher: 'Edit|Write', hooks: [hookCommand('active_task_context.py')] },
-      ],
-      PreCompact: [
-        { hooks: [hookCommand('workflow_checkpoint.py')] },
+        { matcher: 'Write|Edit|Grep', hooks: [hookCommand('mid_workflow_recall.py')] },
+        { matcher: 'Bash', hooks: [hookCommand('block_dangerous_commands.py')] },
       ],
-      Stop: [
-        { hooks: [hookCommand('pre_stop_check.py')] },
-      ],
-      SubagentStart: [
-        { hooks: [hookCommand('subagent_tracker.py', 'start')] },
-      ],
-      SubagentStop: [
-        { hooks: [hookCommand('subagent_tracker.py', 'stop')] },
+      PostToolUse: [
+        { matcher: 'Write|Edit', hooks: [hookCommand('post_edit_guard.py')] },
       ],
+      PreCompact: [{ hooks: [hookCommand('compact_context.py')] }],
     },
   };
 }
 
-function buildStaging(repoRoot, staging, target) {
-  const report = { target, copied: {}, config: { updated: false } };
-  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(staging, 'hooks'));
-  report.copied.hooks = [];
-  for (const name of WORKFLOW_HOOK_FILES) {
-    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(staging, 'hooks', name));
-    report.copied.hooks.push(name);
-  }
-  writeAtomic(path.join(staging, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
-
-  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: command.command,
-        args: command.args,
-      },
-    },
-  }, null, 2) + '\n');
-
+function buildStaging(repoRoot, staging, publishedRoot) {
+  const skillRoot = path.join(staging, 'skills');
+  const hookRoot = path.join(staging, 'hooks');
+  const hooks = buildHooksManifest();
+  const skills = copySkills({ runtime: 'claude', repoRoot, skillRoot });
+  copyHooks({ runtime: 'claude', repoRoot, hookRoot, hooksManifest: hooks });
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
-  writeAtomic(path.join(staging, '.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 with a persistent safety kernel.',
-    author: { name: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors' },
+    description: 'File-first Ultra Builder Pro workflows for Claude Code.',
+    author: { name: pkg.author },
     repository: pkg.homepage,
-    license: pkg.license || 'MIT',
-  }, null, 2) + '\n');
-  markManaged(staging, { adapter: 'claude', plugin: PLUGIN_NAME });
-  const source = provenance.packageSource(repoRoot);
-  const provenanceFile = path.join(staging, PROVENANCE_FILE);
-  report.provenance = provenance.writeProvenance({
-    file: provenanceFile,
-    adapter: 'claude',
-    ...source,
-    roots: { plugin: target },
-    assetRoots: { plugin: staging },
-    assets: provenance.assetRefsForTree('plugin', staging, {
-      exclude: ['.ubp-managed', PROVENANCE_FILE],
-    }),
+    license: pkg.license,
+  }, null, 2)}\n`);
+  markManaged(staging, { adapter: 'claude', plugin: PLUGIN_NAME, version: pkg.version });
+  writePluginProvenance({
+    adapter: 'claude', repoRoot, stagingRoot: staging, publishedRoot,
     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 = path.join(target, PROVENANCE_FILE);
-  return report;
+  return { skills };
 }
 
 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;
+  const pluginRoot = resolvePluginRoot(ctx);
+  const target = resolveTarget(ctx);
+  const cleanupAbsent = managedMetadata(pluginRoot)?.cleanup_absent
+    || captureAbsent(target, ['.', 'skills']);
+  ensureDir(path.dirname(pluginRoot));
+  const staging = fs.mkdtempSync(path.join(path.dirname(pluginRoot), `.${PLUGIN_NAME}-staging-`));
   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;
+    const copied = buildStaging(repoRoot, staging, pluginRoot);
+    markManaged(staging, { cleanup_absent: cleanupAbsent });
+    publishManagedTrees([{ source: staging, target: pluginRoot, label: 'Claude plugin' }]);
+    return {
+      target: pluginRoot,
+      pluginRoot,
+      skillRoot: path.join(pluginRoot, 'skills'),
+      hookRoot: path.join(pluginRoot, 'hooks'),
+      copied,
+    };
   } 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);
+    if (fs.existsSync(staging)) removeTree(staging);
+    pruneCreatedEmpty(target, cleanupAbsent);
     throw error;
   }
 }
 
+function shouldRunHostCli(ctx = {}) {
+  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
+  return ctx.scope === 'global' && !ctx.configDir;
+}
+
 function doctor(ctx = {}) {
   const repoRoot = resolveRepoRoot(ctx);
-  const source = provenance.packageSource(repoRoot);
-  const report = provenance.inspectProvenance({
-    file: path.join(resolvePluginRoot(ctx), PROVENANCE_FILE),
-    expectedAdapter: 'claude',
-    expectedPackageVersion: source.packageInfo.version,
+  const pluginRoot = resolvePluginRoot(ctx);
+  const report = inspectPlugin({
+    adapter: 'claude',
+    repoRoot,
+    pluginRoot,
+    skillRoot: path.join(pluginRoot, 'skills'),
+    hookRoot: path.join(pluginRoot, 'hooks'),
+    manifestFile: path.join(pluginRoot, '.claude-plugin', 'plugin.json'),
   });
   if (shouldRunHostCli(ctx)) {
-    try {
-      const host = inspectClaudeHost(ctx);
-      report.checks.host_plugin = {
-        status: host.pluginOk && host.detailsOk ? 'pass' : 'fail',
-      };
-      report.checks.host_mcp = { status: host.mcpOk ? 'pass' : 'fail' };
-      if (!host.pluginOk || !host.detailsOk) {
-        report.issues.push({
-          code: 'HOST_PLUGIN_NOT_DISCOVERED',
-          plugin_id: `${PLUGIN_NAME}@skills-dir`,
-        });
-      }
-      if (!host.mcpOk) {
-        report.issues.push({
-          code: 'HOST_MCP_NOT_DISCOVERED',
-          plugin_id: `${PLUGIN_NAME}@skills-dir`,
-          server: MCP_SERVER_NAME,
-        });
-      }
-    } catch (error) {
-      report.checks.host_plugin = { status: 'fail' };
-      report.checks.host_mcp = { status: 'fail' };
-      report.issues.push({
-        code: error.code === 'HOST_CLI_TIMEOUT'
-          ? 'HOST_CLI_TIMEOUT'
-          : 'HOST_CLI_INSPECTION_FAILED',
-        message: error.message,
-      });
+    const result = spawnSync(ctx.claudeBin || 'claude', ['plugin', 'list', '--json'], {
+      encoding: 'utf8', timeout: ctx.hostCliTimeoutMs || 30000,
+      env: { ...process.env, CLAUDE_CONFIG_DIR: resolveTarget(ctx) },
+    });
+    let discovered = false;
+    if (result.status === 0) {
+      try {
+        const plugins = JSON.parse(result.stdout);
+        discovered = Array.isArray(plugins) && plugins.some((entry) => (
+          entry?.id === `${PLUGIN_NAME}@skills-dir` && entry.enabled === true
+        ));
+      } catch {}
     }
+    report.checks.host_plugin = { status: discovered ? 'pass' : 'fail' };
+    if (!discovered) report.issues.push({ code: 'HOST_PLUGIN_NOT_DISCOVERED' });
+    report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
   }
-  return applyNativeDoctor(report, path.join(resolvePluginRoot(ctx), 'runtime'));
+  return report;
 }
 
 function uninstall(ctx = {}) {
-  const target = resolvePluginRoot(ctx);
-  const report = { target, removed: {}, config: { updated: false } };
-  if (fs.existsSync(target) && isManaged(target)) {
-    removeTree(target);
-    report.removed.plugin = true;
-  }
-  return report;
+  const pluginRoot = resolvePluginRoot(ctx);
+  const cleanupAbsent = managedMetadata(pluginRoot)?.cleanup_absent || [];
+  const removed = removeManaged(pluginRoot, 'Claude plugin');
+  const cleaned = pruneCreatedEmpty(resolveTarget(ctx), cleanupAbsent);
+  return { target: pluginRoot, pluginRoot, removed, cleaned };
 }
 
 module.exports = {
   name: 'claude',
   PLUGIN_NAME,
-  SENTINEL_KEY,
-  SOURCE_TAG,
-  MCP_SERVER_NAME,
   buildHooksManifest,
-  inspectClaudeHost,
   resolveTarget,
   resolvePluginRoot,
   install,
-  uninstall,
   doctor,
+  uninstall,
 };