ultra-builder-pro-cli 0.5.3 → 0.7.0

package/ultra-tools/commands/system.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const doctor = require('../../mcp-server/lib/doctor.cjs');
+
+const USAGE = `ultra-tools system doctor [--repair]\n`;
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+async function dispatchDoctor(args) {
+  const unknown = args.filter((arg) => !['--repair', '-h', '--help'].includes(arg));
+  if (args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (unknown.length > 0) {
+    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: `unknown system doctor flag: ${unknown[0]}` } });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  const dbPath = path.join(rootDir, '.ultra', 'state.db');
+  if (!fs.existsSync(dbPath)) {
+    emit({ ok: false, error: { code: 'STATE_DB_MISSING', message: `.ultra/state.db not found under ${rootDir}` } });
+    return 2;
+  }
+  const db = openStateDb(dbPath);
+  try {
+    const data = await doctor.runDoctor(db, { rootDir, repair: args.includes('--repair') });
+    emit({ ok: true, data });
+    return data.status === 'healthy' ? 0 : 2;
+  } catch (error) {
+    emit({ ok: false, error: { code: error.code || 'STATE_DB_ERROR', message: error.message } });
+    return 2;
+  } finally {
+    closeStateDb(db);
+  }
+}
+
+async function dispatch(args) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === '-h' || verb === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (verb !== 'doctor') {
+    emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown system verb: ${verb}` } });
+    return 1;
+  }
+  return dispatchDoctor(rest);
+}
+
+module.exports = { USAGE, dispatch, dispatchDoctor };

package/ultra-tools/system-command.test.cjs

@@ -0,0 +1,53 @@
+'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 { spawnSync } = require('node:child_process');
+
+const { initStateDb, closeStateDb } = require('../mcp-server/lib/state-db.cjs');
+
+const CLI = path.join(__dirname, 'cli.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-system-cli-'));
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  closeStateDb(db);
+  return rootDir;
+}
+
+function invoke(rootDir, args) {
+  return spawnSync(process.execPath, [CLI, 'system', ...args], {
+    cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+test('system doctor provides a read-only JSON health envelope', () => {
+  const rootDir = fixture();
+  try {
+    const result = invoke(rootDir, ['doctor']);
+    assert.equal(result.status, 0, result.stderr);
+    const envelope = JSON.parse(result.stdout.trim().split('\n').at(-1));
+    assert.equal(envelope.ok, true);
+    assert.equal(envelope.data.status, 'healthy');
+    assert.equal(envelope.data.repair_performed, false);
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('system doctor --repair creates a backup before recovery', () => {
+  const rootDir = fixture();
+  try {
+    const result = invoke(rootDir, ['doctor', '--repair']);
+    assert.equal(result.status, 0, result.stderr);
+    const envelope = JSON.parse(result.stdout.trim().split('\n').at(-1));
+    assert.equal(envelope.ok, true);
+    assert.equal(envelope.data.repair_performed, true);
+    assert.ok(fs.existsSync(envelope.data.backup_path));
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

package/adapters/_shared/md-to-toml.cjs

@@ -1,54 +0,0 @@
-'use strict';
-
-// Convert a thin-shell command .md file to a Gemini custom-command TOML.
-// Gemini commands live in `~/.gemini/commands/<name>.toml` with shape:
-//
-//   description = "…"
-//   prompt = """
-//   <command body>
-//   """
-//
-// Only the description (from frontmatter) and the body text cross over.
-// Frontmatter keys like `workflow-ref` are inlined into the prompt so the
-// agent still sees the skill reference.
-
-const { parse: parseFrontmatter } = require('./frontmatter.cjs');
-
-function escapeTomlLiteral(str) {
-  // Gemini accepts """multi-line""" literals. Escape any triple-quote to be safe.
-  return String(str).replace(/"""/g, '\\"\\"\\"');
-}
-
-function buildPromptSection(fm, body) {
-  const lines = [];
-  if (fm && fm['workflow-ref']) {
-    lines.push(`[ultra-builder-pro] workflow reference: ${fm['workflow-ref']}`);
-  }
-  if (fm && Array.isArray(fm.mcp_tools_required) && fm.mcp_tools_required.length > 0) {
-    lines.push(`[ultra-builder-pro] MCP tools required: ${fm.mcp_tools_required.join(', ')}`);
-  }
-  if (fm && fm.cli_fallback) {
-    lines.push(`[ultra-builder-pro] CLI fallback: ultra-tools ${fm.cli_fallback}`);
-  }
-  if (lines.length > 0) lines.push('');
-  lines.push(body.trimEnd());
-  return lines.join('\n');
-}
-
-function mdCommandToToml(mdText) {
-  if (typeof mdText !== 'string') throw new TypeError('mdCommandToToml: expects string');
-  const { fm, body } = parseFrontmatter(mdText);
-  const description = (fm && fm.description) || 'Ultra Builder Pro command';
-  const prompt = buildPromptSection(fm, body);
-
-  const tomlLines = [
-    `description = ${JSON.stringify(description)}`,
-    'prompt = """',
-    escapeTomlLiteral(prompt),
-    '"""',
-    '',
-  ];
-  return tomlLines.join('\n');
-}
-
-module.exports = { mdCommandToToml };

package/adapters/_shared/rtk-detect.cjs

@@ -1,86 +0,0 @@
-'use strict';
-
-// Phase 6.1 — RTK soft dependency.
-//
-// RTK (Rust Token Killer) is an external CLI proxy the user installs
-// separately. We never hard-require it: installation continues even when
-// rtk is missing, we just print an install hint. This mirrors PLAN Phase
-// 6.1: "无 rtk → 提示安装 + 跳过（不硬依赖）".
-//
-// Tests inject a PATH override so we can exercise the happy/missing paths
-// without touching the real rtk binary on the machine.
-
-const { execFileSync } = require('node:child_process');
-
-const INSTALL_HINT =
-  'rtk not found. RTK is a token-saving proxy that rewrites Bash/git/npm\n' +
-  '  commands transparently. Install: https://github.com/rcrocky/rtk\n' +
-  '  (or run `cargo install rtk`). Continuing without RTK.';
-
-function envWithPath(pathOverride) {
-  if (!pathOverride) return process.env;
-  // Isolate rtk lookup to pathOverride + minimal system dirs (so shebangs
-  // like `/usr/bin/env bash` still resolve). Tests use this to cut off the
-  // real rtk binary on the developer's machine.
-  return { ...process.env, PATH: `${pathOverride}:/usr/bin:/bin` };
-}
-
-function detectRtk({ pathOverride = null, timeoutMs = 3000 } = {}) {
-  try {
-    const stdout = execFileSync('rtk', ['--version'], {
-      env: envWithPath(pathOverride),
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: timeoutMs,
-    });
-    return { available: true, version: stdout.toString().trim() };
-  } catch (err) {
-    return {
-      available: false,
-      reason: err && err.code === 'ENOENT' ? 'binary not on PATH' : (err && err.message) || 'unknown',
-    };
-  }
-}
-
-function initRtk({ pathOverride = null, scope = 'global', timeoutMs = 10000 } = {}) {
-  const args = ['init'];
-  if (scope === 'global') args.push('-g');
-  try {
-    const stdout = execFileSync('rtk', args, {
-      env: envWithPath(pathOverride),
-      stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: timeoutMs,
-    });
-    return { ok: true, stdout: stdout.toString() };
-  } catch (err) {
-    return { ok: false, error: (err && err.message) || 'unknown' };
-  }
-}
-
-// High-level entry: detect + optionally init, never throws.
-// Caller passes {skip:true} to honor --skip-rtk flag.
-function installHook({ skip = false, pathOverride = null, scope = 'global' } = {}) {
-  if (skip) return { skipped: true };
-  const detection = detectRtk({ pathOverride });
-  if (!detection.available) {
-    return {
-      available: false,
-      initialized: false,
-      reason: detection.reason,
-      hint: INSTALL_HINT,
-    };
-  }
-  const initResult = initRtk({ pathOverride, scope });
-  return {
-    available: true,
-    initialized: initResult.ok,
-    version: detection.version,
-    init_error: initResult.ok ? undefined : initResult.error,
-  };
-}
-
-module.exports = {
-  detectRtk,
-  initRtk,
-  installHook,
-  INSTALL_HINT,
-};

package/adapters/_shared/tests/md-to-toml.test.cjs

@@ -1,48 +0,0 @@
-'use strict';
-
-const { test } = require('node:test');
-const assert = require('node:assert/strict');
-
-const { mdCommandToToml } = require('../md-to-toml.cjs');
-
-test('mdCommandToToml extracts description from frontmatter', () => {
-  const md = [
-    '---',
-    'description: Initialize project',
-    'workflow-ref: "@skills/ultra-init/SKILL.md"',
-    '---',
-    '',
-    '# /ultra-init',
-    'body content here',
-  ].join('\n');
-
-  const toml = mdCommandToToml(md);
-  assert.match(toml, /description = "Initialize project"/);
-  assert.match(toml, /prompt = """/);
-  assert.match(toml, /body content here/);
-  assert.match(toml, /workflow reference: @skills\/ultra-init\/SKILL\.md/);
-});
-
-test('mdCommandToToml includes mcp_tools_required and cli_fallback when present', () => {
-  const md = [
-    '---',
-    'description: plan tasks',
-    'mcp_tools_required:',
-    '  - task.create',
-    '  - ask.question',
-    'cli_fallback: "task create"',
-    '---',
-    'body',
-  ].join('\n');
-
-  const toml = mdCommandToToml(md);
-  assert.match(toml, /MCP tools required: task\.create, ask\.question/);
-  assert.match(toml, /CLI fallback: ultra-tools task create/);
-});
-
-test('mdCommandToToml defaults description when frontmatter absent', () => {
-  const md = '# plain markdown, no frontmatter';
-  const toml = mdCommandToToml(md);
-  assert.match(toml, /description = "Ultra Builder Pro command"/);
-  assert.match(toml, /plain markdown, no frontmatter/);
-});

package/adapters/_shared/tests/rtk-detect.test.cjs

@@ -1,116 +0,0 @@
-'use strict';
-
-// Phase 6.1 — RTK soft dependency:
-//   • detectRtk(opts): locates the `rtk` binary via PATH; returns false
-//     (never throws) when missing or on any exec error.
-//   • initRtk(opts): runs `rtk init -g`; only call after detectRtk() true.
-
-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 rtk = require('../rtk-detect.cjs');
-
-function mkEmptyBinDir() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-rtk-empty-bin-'));
-}
-
-function mkFakeBinDir({ succeed = true } = {}) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-rtk-fake-bin-'));
-  const script = succeed
-    ? '#!/usr/bin/env bash\nif [ "$1" = "--version" ]; then echo "rtk 1.2.3"; exit 0; fi\nif [ "$1" = "init" ]; then echo "init ok"; exit 0; fi\nexit 0\n'
-    : '#!/usr/bin/env bash\nexit 42\n';
-  const target = path.join(dir, 'rtk');
-  fs.writeFileSync(target, script);
-  fs.chmodSync(target, 0o755);
-  return dir;
-}
-
-test('detectRtk returns true when rtk --version succeeds', () => {
-  const binDir = mkFakeBinDir({ succeed: true });
-  try {
-    const result = rtk.detectRtk({ pathOverride: binDir });
-    assert.equal(result.available, true);
-    assert.match(result.version, /rtk/i);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('detectRtk returns false when rtk missing from PATH (no throw)', () => {
-  const binDir = mkEmptyBinDir();
-  try {
-    const result = rtk.detectRtk({ pathOverride: binDir });
-    assert.equal(result.available, false);
-    assert.ok(result.reason);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('detectRtk returns false when rtk exits non-zero (no throw)', () => {
-  const binDir = mkFakeBinDir({ succeed: false });
-  try {
-    const result = rtk.detectRtk({ pathOverride: binDir });
-    assert.equal(result.available, false);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('initRtk runs rtk init -g and returns success', () => {
-  const binDir = mkFakeBinDir({ succeed: true });
-  try {
-    const result = rtk.initRtk({ pathOverride: binDir, scope: 'global' });
-    assert.equal(result.ok, true);
-    assert.match(result.stdout, /init ok/);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('initRtk reports failure when binary is missing (does not throw)', () => {
-  const binDir = mkEmptyBinDir();
-  try {
-    const result = rtk.initRtk({ pathOverride: binDir, scope: 'global' });
-    assert.equal(result.ok, false);
-    assert.ok(result.error);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('installHook: skip=true short-circuits with a skipped=true record', () => {
-  const binDir = mkEmptyBinDir();
-  try {
-    const result = rtk.installHook({ skip: true, pathOverride: binDir });
-    assert.equal(result.skipped, true);
-    assert.equal(result.available, undefined);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('installHook: missing rtk → returns {available:false} with install hint', () => {
-  const binDir = mkEmptyBinDir();
-  try {
-    const result = rtk.installHook({ skip: false, pathOverride: binDir });
-    assert.equal(result.available, false);
-    assert.ok(result.hint, 'should surface an install hint');
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});
-
-test('installHook: present rtk → runs init and returns {available:true, initialized:true}', () => {
-  const binDir = mkFakeBinDir({ succeed: true });
-  try {
-    const result = rtk.installHook({ skip: false, pathOverride: binDir, scope: 'global' });
-    assert.equal(result.available, true);
-    assert.equal(result.initialized, true);
-  } finally {
-    fs.rmSync(binDir, { recursive: true, force: true });
-  }
-});

package/adapters/gemini.js

@@ -1,204 +0,0 @@
-'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,
-};