@boyingliu01/xp-gate 0.15.3 → 0.15.4

package/lib/__tests__/sprint-audit.test.js

@@ -1,207 +1,207 @@
-/**
- * Tests for sprint-audit CLI command (Layer 2)
- * @test REQ-338 Sprint audit — final completeness check
- * @intent Verify sprint-audit correctly checks phase coverage, artifacts, consistency
- * @covers AC-AUDIT-01 (SKIP when no sprint-state.json)
- * @covers AC-AUDIT-02 (PASS when 6/6 completed)
- * @covers AC-AUDIT-03 (PASS_WITH_WARNINGS when 4-5/6 completed)
- * @covers AC-AUDIT-04 (FAIL when <4/6 completed)
- * @covers AC-AUDIT-05 (FAIL on state inconsistency)
- * @covers AC-AUDIT-06 (--json flag outputs JSON)
- * @covers AC-AUDIT-07 (report persisted to audit-report.json)
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { handleSprintAudit } from '../sprint-audit.js';
-
-describe('sprint-audit', () => {
-  let tmpDir;
-
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-audit-test-'));
-  });
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  function writeState(state) {
-    const stateDir = path.join(tmpDir, '.sprint-state');
-    fs.mkdirSync(stateDir, { recursive: true });
-    fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), JSON.stringify(state));
-  }
-
-  function makeState(overrides = {}) {
-    return {
-      _schema_version: 1,
-      id: 'sprint-test-audit',
-      task_description: 'Test audit feature',
-      phase: 6,
-      status: 'completed',
-      started_at: '2026-07-22T10:00:00Z',
-      phase_history: [],
-      isolation: { branch: 'sprint/test-audit', worktree_path: null },
-      outputs: {},
-      ...overrides,
-    };
-  }
-
-  function makePhaseHistory(completedPhases) {
-    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
-    return completedPhases.map((p, i) => ({
-      phase: p,
-      phase_name: phaseNames[p - 1],
-      status: 'completed',
-      started_at: `2026-07-22T10:${String(i).padStart(2, '0')}:00Z`,
-      completed_at: `2026-07-22T10:${String(i).padStart(2, '0')}:30Z`,
-      duration_seconds: 30,
-    }));
-  }
-
-  describe('handleSprintAudit()', () => {
-    it('returns 0 and shows help with --help', async () => {
-      const code = await handleSprintAudit(['--help']);
-      expect(code).toBe(0);
-    });
-
-    it('returns SKIP (exit 0) when no sprint-state.json exists', async () => {
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('No sprint-state.json'));
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS when 6/6 phases completed', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      // Check output contains PASS
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS');
-      expect(output).toContain('6/6');
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS_WITH_WARNINGS when 5/6 completed', async () => {
-      writeState(makeState({ phase: 5, phase_history: makePhaseHistory([1, 2, 3, 4, 5]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS_WITH_WARNINGS');
-      logSpy.mockRestore();
-    });
-
-    it('returns PASS_WITH_WARNINGS when 4/6 completed', async () => {
-      writeState(makeState({ phase: 4, phase_history: makePhaseHistory([1, 2, 3, 4]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('PASS_WITH_WARNINGS');
-      logSpy.mockRestore();
-    });
-
-    it('returns FAIL when <4/6 completed', async () => {
-      writeState(makeState({ phase: 3, phase_history: makePhaseHistory([1, 2, 3]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('FAIL');
-      logSpy.mockRestore();
-    });
-
-    it('returns FAIL on state inconsistency (phase vs phase_history)', async () => {
-      const history = makePhaseHistory([1, 2, 3, 4, 5, 6]);
-      writeState(makeState({ phase: 3, phase_history: history })); // phase=3 but last entry is 6
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      expect(output).toContain('State inconsistency');
-      logSpy.mockRestore();
-    });
-
-    it('outputs JSON when --json flag is set', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.verdict).toBe('PASS');
-      expect(result.coverage.completed).toBe(6);
-      logSpy.mockRestore();
-    });
-
-    it('counts skipped phases as completed in coverage', async () => {
-      const history = makePhaseHistory([1, 2, 3, 4, 5]);
-      history.push({
-        phase: 6, phase_name: 'CLOSE', status: 'skipped',
-        started_at: '2026-07-22T10:05:00Z', completed_at: '2026-07-22T10:05:00Z', duration_seconds: 0,
-      });
-      writeState(makeState({ phase: 6, phase_history: history }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.coverage.completed).toBe(6);
-      expect(result.verdict).toBe('PASS');
-      logSpy.mockRestore();
-    });
-
-    it('warns about missing summary files for completed phases', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-      // No phase-outputs directory → all summaries missing
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
-      expect(code).toBe(0);
-      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
-      const result = JSON.parse(output);
-      expect(result.warnings.length).toBeGreaterThan(0);
-      expect(result.warnings.some(w => w.includes('summary missing'))).toBe(true);
-      logSpy.mockRestore();
-    });
-
-    it('persists audit report to audit-report.json', async () => {
-      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
-
-      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-      await handleSprintAudit(['--dir', tmpDir]);
-      logSpy.mockRestore();
-
-      const reportPath = path.join(tmpDir, '.sprint-state', 'audit-report.json');
-      expect(fs.existsSync(reportPath)).toBe(true);
-      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
-      expect(report.verdict).toBe('PASS');
-      expect(report.sprint_id).toBe('sprint-test-audit');
-    });
-
-    it('handles corrupted sprint-state.json gracefully', async () => {
-      const stateDir = path.join(tmpDir, '.sprint-state');
-      fs.mkdirSync(stateDir, { recursive: true });
-      fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), 'not-valid-json');
-
-      const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-      const code = await handleSprintAudit(['--dir', tmpDir]);
-      expect(code).toBe(1);
-      expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse'));
-      errSpy.mockRestore();
-    });
-  });
-});
+/**
+ * Tests for sprint-audit CLI command (Layer 2)
+ * @test REQ-338 Sprint audit — final completeness check
+ * @intent Verify sprint-audit correctly checks phase coverage, artifacts, consistency
+ * @covers AC-AUDIT-01 (SKIP when no sprint-state.json)
+ * @covers AC-AUDIT-02 (PASS when 6/6 completed)
+ * @covers AC-AUDIT-03 (PASS_WITH_WARNINGS when 4-5/6 completed)
+ * @covers AC-AUDIT-04 (FAIL when <4/6 completed)
+ * @covers AC-AUDIT-05 (FAIL on state inconsistency)
+ * @covers AC-AUDIT-06 (--json flag outputs JSON)
+ * @covers AC-AUDIT-07 (report persisted to audit-report.json)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { handleSprintAudit } from '../sprint-audit.js';
+
+describe('sprint-audit', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sprint-audit-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeState(state) {
+    const stateDir = path.join(tmpDir, '.sprint-state');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), JSON.stringify(state));
+  }
+
+  function makeState(overrides = {}) {
+    return {
+      _schema_version: 1,
+      id: 'sprint-test-audit',
+      task_description: 'Test audit feature',
+      phase: 6,
+      status: 'completed',
+      started_at: '2026-07-22T10:00:00Z',
+      phase_history: [],
+      isolation: { branch: 'sprint/test-audit', worktree_path: null },
+      outputs: {},
+      ...overrides,
+    };
+  }
+
+  function makePhaseHistory(completedPhases) {
+    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+    return completedPhases.map((p, i) => ({
+      phase: p,
+      phase_name: phaseNames[p - 1],
+      status: 'completed',
+      started_at: `2026-07-22T10:${String(i).padStart(2, '0')}:00Z`,
+      completed_at: `2026-07-22T10:${String(i).padStart(2, '0')}:30Z`,
+      duration_seconds: 30,
+    }));
+  }
+
+  describe('handleSprintAudit()', () => {
+    it('returns 0 and shows help with --help', async () => {
+      const code = await handleSprintAudit(['--help']);
+      expect(code).toBe(0);
+    });
+
+    it('returns SKIP (exit 0) when no sprint-state.json exists', async () => {
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('No sprint-state.json'));
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS when 6/6 phases completed', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      // Check output contains PASS
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS');
+      expect(output).toContain('6/6');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 5/6 completed', async () => {
+      writeState(makeState({ phase: 5, phase_history: makePhaseHistory([1, 2, 3, 4, 5]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns PASS_WITH_WARNINGS when 4/6 completed', async () => {
+      writeState(makeState({ phase: 4, phase_history: makePhaseHistory([1, 2, 3, 4]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('PASS_WITH_WARNINGS');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL when <4/6 completed', async () => {
+      writeState(makeState({ phase: 3, phase_history: makePhaseHistory([1, 2, 3]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('FAIL');
+      logSpy.mockRestore();
+    });
+
+    it('returns FAIL on state inconsistency (phase vs phase_history)', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5, 6]);
+      writeState(makeState({ phase: 3, phase_history: history })); // phase=3 but last entry is 6
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      expect(output).toContain('State inconsistency');
+      logSpy.mockRestore();
+    });
+
+    it('outputs JSON when --json flag is set', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.verdict).toBe('PASS');
+      expect(result.coverage.completed).toBe(6);
+      logSpy.mockRestore();
+    });
+
+    it('counts skipped phases as completed in coverage', async () => {
+      const history = makePhaseHistory([1, 2, 3, 4, 5]);
+      history.push({
+        phase: 6, phase_name: 'CLOSE', status: 'skipped',
+        started_at: '2026-07-22T10:05:00Z', completed_at: '2026-07-22T10:05:00Z', duration_seconds: 0,
+      });
+      writeState(makeState({ phase: 6, phase_history: history }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.coverage.completed).toBe(6);
+      expect(result.verdict).toBe('PASS');
+      logSpy.mockRestore();
+    });
+
+    it('warns about missing summary files for completed phases', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+      // No phase-outputs directory → all summaries missing
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir, '--json']);
+      expect(code).toBe(0);
+      const output = logSpy.mock.calls.map(c => c[0]).join('\n');
+      const result = JSON.parse(output);
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings.some(w => w.includes('summary missing'))).toBe(true);
+      logSpy.mockRestore();
+    });
+
+    it('persists audit report to audit-report.json', async () => {
+      writeState(makeState({ phase_history: makePhaseHistory([1, 2, 3, 4, 5, 6]) }));
+
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      await handleSprintAudit(['--dir', tmpDir]);
+      logSpy.mockRestore();
+
+      const reportPath = path.join(tmpDir, '.sprint-state', 'audit-report.json');
+      expect(fs.existsSync(reportPath)).toBe(true);
+      const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+      expect(report.verdict).toBe('PASS');
+      expect(report.sprint_id).toBe('sprint-test-audit');
+    });
+
+    it('handles corrupted sprint-state.json gracefully', async () => {
+      const stateDir = path.join(tmpDir, '.sprint-state');
+      fs.mkdirSync(stateDir, { recursive: true });
+      fs.writeFileSync(path.join(stateDir, 'sprint-state.json'), 'not-valid-json');
+
+      const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const code = await handleSprintAudit(['--dir', tmpDir]);
+      expect(code).toBe(1);
+      expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to parse'));
+      errSpy.mockRestore();
+    });
+  });
+});

package/lib/doctor-tui.js

@@ -0,0 +1,198 @@
+/**
+ * TUI registration and installed-skills diagnostics for doctor.
+ * Extracted from doctor.js to keep file size under the large-file threshold.
+ */
+const fs = require('fs');
+const path = require('path');
+const { HOME_DIR, detectPlatform } = require('./shared-paths.js');
+
+// npm package source dir (template hooks/adapters)
+const PKG_DIR = path.dirname(__dirname);
+
+/**
+ * TUI registration path and expected plugin entry.
+ */
+const TUI_JSON_PATH = path.join(HOME_DIR, '.config', 'opencode', 'tui.json');
+const TUI_PLUGIN_ENTRY = '@boyingliu01/opencode-plugin/tui';
+
+/**
+ * Read and parse tui.json, returning { data, error }.
+ * data = parsed object on success, null on file missing, undefined on corrupt.
+ */
+function readTuiJson() {
+  if (!fs.existsSync(TUI_JSON_PATH)) return { data: null, error: null };
+  try {
+    const raw = fs.readFileSync(TUI_JSON_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    return { data, error: null };
+  } catch (e) {
+    return { data: undefined, error: `Corrupt JSON: ${e.message}` };
+  }
+}
+
+/**
+ * Check 9: TUI auto-registration in ~/.config/opencode/tui.json.
+ * @returns {number} issue count
+ */
+function diagnoseTuiRegistration(checks) {
+  const { data, error } = readTuiJson();
+
+  if (error) {
+    checks.push({ name: 'TUI registration', status: 'FAIL', detail: error });
+    return 1;
+  }
+
+  if (data === null) {
+    checks.push({ name: 'TUI registration', status: 'FAIL', detail: 'Not registered' });
+    return 1;
+  }
+
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (plugins.includes(TUI_PLUGIN_ENTRY)) {
+    checks.push({ name: 'TUI registration', status: 'PASS', detail: `${TUI_PLUGIN_ENTRY} registered` });
+    return 0;
+  }
+
+  checks.push({ name: 'TUI registration', status: 'FAIL', detail: 'Not registered' });
+  return 1;
+}
+
+/**
+ * Check 9: Installed skills vs package-bundled skills (#332).
+ * Reports WARN for each installed skill whose SKILL.md differs from the bundled version.
+ * @param {object} config
+ * @param {Array} checks
+ * @returns {number} issue count
+ */
+function diagnoseInstalledSkills(config, checks) {
+  const installedSkills = config.installedSkills || {};
+  const skillNames = Object.keys(installedSkills);
+  if (skillNames.length === 0) {
+    checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'No skills installed' });
+    return 0;
+  }
+
+  const bundledSkillsDir = path.join(PKG_DIR, 'skills');
+  if (!fs.existsSync(bundledSkillsDir)) {
+    checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'Package skills dir not found' });
+    return 0;
+  }
+
+  const platform = detectPlatform();
+  let userSkillsDir;
+  if (platform === 'qoder') {
+    userSkillsDir = path.join(HOME_DIR, '.qoder', 'skills');
+  } else if (platform === 'claude-code') {
+    userSkillsDir = path.join(HOME_DIR, '.claude', 'skills');
+  } else {
+    userSkillsDir = path.join(HOME_DIR, '.config', 'opencode', 'skills');
+  }
+
+  let issues = 0;
+  for (const name of skillNames) {
+    const bundledSkillMd = path.join(bundledSkillsDir, name, 'SKILL.md');
+    const userSkillMd = path.join(userSkillsDir, name, 'SKILL.md');
+
+    if (!fs.existsSync(bundledSkillMd)) continue;
+    if (!fs.existsSync(userSkillMd)) {
+      checks.push({ name: `Skill: ${name}`, status: 'FAIL', detail: 'Installed SKILL.md missing' });
+      issues++;
+      continue;
+    }
+
+    const bundledContent = fs.readFileSync(bundledSkillMd, 'utf8');
+    const userContent = fs.readFileSync(userSkillMd, 'utf8');
+    if (bundledContent !== userContent) {
+      checks.push({
+        name: `Skill: ${name}`,
+        status: 'WARN',
+        detail: 'Outdated — run xp-gate update-skill --all',
+      });
+      issues++;
+    } else {
+      checks.push({ name: `Skill: ${name}`, status: 'PASS', detail: 'Up to date' });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Fix TUI registration: ensure @boyingliu01/opencode-plugin/tui is in tui.json.
+ * Uses atomic write (tmp + renameSync) for JSON safety.
+ * On corrupt JSON: backup to .corrupt-{timestamp}.bak then rebuild.
+ * Idempotent: skips if already registered.
+ * @returns {boolean} Whether a fix was applied
+ */
+function fixTuiRegistration() {
+  const { data, error } = readTuiJson();
+
+  // Corrupt JSON: backup old file, rebuild from scratch
+  if (error && data === undefined) {
+    const ts = Date.now();
+    const backupPath = `${TUI_JSON_PATH}.corrupt-${ts}.bak`;
+    try {
+      fs.copyFileSync(TUI_JSON_PATH, backupPath);
+      console.log(`  ⚠ TUI config corrupted — backed up to ${backupPath}`);
+    } catch { /* non-critical */ }
+    // Rebuild fresh
+    const dir = path.dirname(TUI_JSON_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    const newConfig = { plugin: [TUI_PLUGIN_ENTRY] };
+    const tmpPath = `${TUI_JSON_PATH}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(newConfig, null, 2));
+    fs.renameSync(tmpPath, TUI_JSON_PATH);
+    console.log(`  ✓ Registered ${TUI_PLUGIN_ENTRY} in TUI (rebuilt after corrupt backup)`);
+    return true;
+  }
+
+  // File doesn't exist: create it
+  if (data === null) {
+    const dir = path.dirname(TUI_JSON_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    const newConfig = { plugin: [TUI_PLUGIN_ENTRY] };
+    const tmpPath = `${TUI_JSON_PATH}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(newConfig, null, 2));
+    fs.renameSync(tmpPath, TUI_JSON_PATH);
+    console.log(`  ✓ Created TUI config with ${TUI_PLUGIN_ENTRY}`);
+    return true;
+  }
+
+  // File exists, check if plugin already registered (idempotent)
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (plugins.includes(TUI_PLUGIN_ENTRY)) return false;
+
+  // Append plugin entry
+  data.plugin = plugins.concat([TUI_PLUGIN_ENTRY]);
+  const tmpPath = `${TUI_JSON_PATH}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpPath, TUI_JSON_PATH);
+  console.log(`  ✓ Added ${TUI_PLUGIN_ENTRY} to TUI config`);
+  return true;
+}
+
+/**
+ * Wrapper for init.js: ensure TUI is registered without console output.
+ * Returns true if the plugin is already registered or was just added.
+ */
+function ensureTuiRegistration() {
+  const { data } = readTuiJson();
+  if (data === null || data === undefined) {
+    fixTuiRegistration();
+    return;
+  }
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (!plugins.includes(TUI_PLUGIN_ENTRY)) {
+    fixTuiRegistration();
+  }
+}
+
+module.exports = {
+  TUI_JSON_PATH,
+  TUI_PLUGIN_ENTRY,
+  readTuiJson,
+  diagnoseTuiRegistration,
+  diagnoseInstalledSkills,
+  fixTuiRegistration,
+  ensureTuiRegistration,
+};