ultra-builder-pro-cli 0.5.0

package/adapters/_shared/tests/settings-merge.test.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  SENTINEL_VERSION,
+  readJsonSafe,
+  withSentinelBlock,
+  removeSentinelBlock,
+  hasSentinelBlock,
+  mergeArrayField,
+} = require('../settings-merge.cjs');
+
+test('withSentinelBlock writes under the sentinel key only; user config untouched', () => {
+  const existing = { user_prop: 'keep me', hooks: [{ name: 'user-hook' }] };
+  const out = withSentinelBlock(existing, 'ultra_builder_pro', {
+    mcp: { ubp: { command: 'node' } },
+  });
+
+  assert.equal(out.user_prop, 'keep me');
+  assert.deepEqual(out.hooks, [{ name: 'user-hook' }]);
+  assert.equal(out.ultra_builder_pro.__sentinel, SENTINEL_VERSION);
+  assert.equal(out.ultra_builder_pro.__generated_by, 'ultra-builder-pro-cli');
+  assert.deepEqual(out.ultra_builder_pro.mcp.ubp, { command: 'node' });
+});
+
+test('removeSentinelBlock leaves unrelated keys intact; noop if absent', () => {
+  const with_ = { a: 1, mine: { __sentinel: 1, x: 2 } };
+  const stripped = removeSentinelBlock(with_, 'mine');
+  assert.deepEqual(stripped, { a: 1 });
+  assert.ok(!hasSentinelBlock(stripped, 'mine'));
+
+  const noop = removeSentinelBlock({ a: 1 }, 'mine');
+  assert.deepEqual(noop, { a: 1 });
+});
+
+test('mergeArrayField dedupes; readJsonSafe handles missing/empty/malformed', () => {
+  const existing = { hooks: [{ name: 'user' }, { name: 'ubp-one' }] };
+  const out = mergeArrayField(existing, 'hooks', [
+    { name: 'ubp-one' }, // dup — skipped
+    { name: 'ubp-two' },
+  ]);
+  assert.deepEqual(out.hooks, [
+    { name: 'user' },
+    { name: 'ubp-one' },
+    { name: 'ubp-two' },
+  ]);
+
+  // readJsonSafe: missing file → empty object
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-merge-'));
+  try {
+    assert.deepEqual(readJsonSafe(path.join(tmp, 'none.json')), {});
+
+    const p = path.join(tmp, 'existing.json');
+    fs.writeFileSync(p, '{"a":1}');
+    assert.deepEqual(readJsonSafe(p), { a: 1 });
+
+    // empty file treated as empty object
+    fs.writeFileSync(p, '   \n  ');
+    assert.deepEqual(readJsonSafe(p), {});
+
+    // malformed → throws
+    fs.writeFileSync(p, '{not json');
+    assert.throws(() => readJsonSafe(p), /cannot parse/);
+
+    // P2 #7 / D45: rescue mode backs up corrupt file and returns {} instead
+    // of throwing — lets `install` finish even if the user's settings.json
+    // is syntactically broken.
+    fs.writeFileSync(p, '{still not json');
+    const rescued = readJsonSafe(p, { rescue: true });
+    assert.deepEqual(rescued, {});
+    const backups = fs.readdirSync(tmp).filter((f) => f.startsWith('existing.json.bak-'));
+    assert.ok(backups.length > 0, `expected a .bak-* file in ${tmp}, saw ${fs.readdirSync(tmp).join(',')}`);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+
+  // withSentinelBlock rejects bad key
+  assert.throws(() => withSentinelBlock({}, '', {}), /non-empty string/);
+});

package/adapters/_shared/tests/validate.test.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+// Phase 4 backlog P3 #13 / D45 — configDir validator.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { validateConfigDir } = require('../validate.cjs');
+
+test('validateConfigDir: null/undefined → ok with configDir=null', () => {
+  assert.deepEqual(validateConfigDir(null), { ok: true, configDir: null });
+  assert.deepEqual(validateConfigDir(undefined), { ok: true, configDir: null });
+});
+
+test('validateConfigDir: normal path → ok', () => {
+  const out = validateConfigDir('/tmp/work');
+  assert.equal(out.ok, true);
+  assert.equal(out.configDir, '/tmp/work');
+});
+
+test('validateConfigDir: rejects NUL byte', () => {
+  const out = validateConfigDir('/tmp/foo\u0000bar');
+  assert.equal(out.ok, false);
+  assert.match(out.error, /NUL bytes/);
+});
+
+test('validateConfigDir: rejects non-string', () => {
+  assert.equal(validateConfigDir(42).ok, false);
+  assert.equal(validateConfigDir({}).ok, false);
+});

package/adapters/_shared/validate.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+// Argument-boundary validators shared by bin/install.js (and anything else
+// that accepts user-supplied paths). Keep small and pure: input → verdict.
+
+function validateConfigDir(configDir) {
+  if (configDir === undefined || configDir === null) {
+    return { ok: true, configDir: null };
+  }
+  if (typeof configDir !== 'string') {
+    return { ok: false, error: '--config-dir must be a string' };
+  }
+  if (configDir.includes('\0')) {
+    // P3 #13 / D45 — NUL bytes in a path are a classic path-traversal
+    // smuggling vector. Node's child_process layer also rejects NUL in
+    // argv, but defense-in-depth is cheap here.
+    return { ok: false, error: '--config-dir must not contain NUL bytes (path traversal)' };
+  }
+  return { ok: true, configDir };
+}
+
+module.exports = {
+  validateConfigDir,
+};

package/adapters/claude.js

@@ -0,0 +1,182 @@
+'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 {
+  copyTree,
+  ensureDir,
+  isManaged,
+  markManaged,
+  removeTree,
+  writeAtomic,
+} = require('./_shared/file-ops.cjs');
+const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const {
+  CORE_PUBLIC_SKILLS,
+  WORKFLOW_HOOK_FILES,
+  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.filter((name) => name !== 'ultra-review');
+
+function resolveTarget(ctx = {}) {
+  if (ctx.configDir) return ctx.configDir;
+  if (ctx.scope === 'global') {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(ctx.homeDir || os.homedir(), '.claude');
+  }
+  return path.join(ctx.cwd || process.cwd(), '.claude');
+}
+
+function resolvePluginRoot(ctx = {}) {
+  if (ctx.pluginRoot) return ctx.pluginRoot;
+  return path.join(resolveTarget(ctx), 'skills', PLUGIN_NAME);
+}
+
+function resolveRepoRoot(ctx = {}) {
+  return ctx.repoRoot || path.resolve(__dirname, '..');
+}
+
+function copyNamedDirectories(repoRoot, target, parent, names) {
+  const copied = [];
+  for (const name of names) {
+    const source = path.join(repoRoot, parent, name);
+    if (!fs.existsSync(source)) throw new Error(`missing allowlisted Claude asset: ${parent}/${name}`);
+    const files = copyTree(source, path.join(target, parent, name));
+    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) {
+  return {
+    type: 'command',
+    command: [
+      `python3 "\${CLAUDE_PLUGIN_ROOT}/hooks/${name}"`,
+      ...args.map((arg) => JSON.stringify(arg)),
+    ].join(' '),
+    timeout: 10,
+  };
+}
+
+function buildHooksManifest() {
+  return {
+    description: 'Ultra workflow lifecycle hooks; inactive outside projects with an active .ultra workflow.',
+    hooks: {
+      SessionStart: [
+        {
+          matcher: 'startup|resume|clear',
+          hooks: [hookCommand('health_check.py'), hookCommand('workflow_context.py')],
+        },
+        { matcher: 'compact', hooks: [hookCommand('workflow_resume.py')] },
+      ],
+      PreToolUse: [
+        { matcher: 'Edit|Write', hooks: [hookCommand('active_task_context.py')] },
+      ],
+      PreCompact: [
+        { hooks: [hookCommand('workflow_checkpoint.py')] },
+      ],
+      Stop: [
+        { hooks: [hookCommand('pre_stop_check.py')] },
+      ],
+      SubagentStart: [
+        { hooks: [hookCommand('subagent_tracker.py', 'start')] },
+      ],
+      SubagentStop: [
+        { hooks: [hookCommand('subagent_tracker.py', 'stop')] },
+      ],
+    },
+  };
+}
+
+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);
+
+  const report = { target, copied: {}, config: { updated: false } };
+  report.copied.commands = copyCommands(repoRoot, target);
+  report.copied.skills = copyNamedDirectories(repoRoot, target, 'skills', skillsForRuntime('claude'));
+  report.copied.agents = copyTree(path.join(repoRoot, 'agents'), path.join(target, 'agents'));
+
+  ensureDir(path.join(target, 'hooks'));
+  report.copied.hooks = [];
+  for (const name of WORKFLOW_HOOK_FILES) {
+    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(target, 'hooks', name));
+    report.copied.hooks.push(name);
+  }
+  writeAtomic(path.join(target, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
+
+  const runtime = buildMcpRuntime(repoRoot, target, { runtime: 'claude' });
+  writeAtomic(path.join(target, '.mcp.json'), JSON.stringify({
+    mcpServers: {
+      [MCP_SERVER_NAME]: {
+        command: process.execPath,
+        args: [runtime.launcher],
+      },
+    },
+  }, 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({
+    name: PLUGIN_NAME,
+    version: pkg.version,
+    description: 'Claude Code native Ultra Builder Pro workflows, agents, hooks, and MCP task state.',
+    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 });
+  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;
+}
+
+module.exports = {
+  name: 'claude',
+  PLUGIN_NAME,
+  SENTINEL_KEY,
+  SOURCE_TAG,
+  MCP_SERVER_NAME,
+  buildHooksManifest,
+  resolveTarget,
+  resolvePluginRoot,
+  install,
+  uninstall,
+};