nubos-pilot 0.1.0

package/bin/np-tools/ui-review.cjs

@@ -0,0 +1,108 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { detect } = require('../../lib/runtime/index.cjs');
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'ui-review-invalid-arg',
+      'ui-review requires a phase number argument',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const s = String(raw);
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new NubosPilotError(
+      'ui-review-invalid-arg',
+      'Invalid phase number: ' + s,
+      { value: s },
+    );
+  }
+  return s;
+}
+
+function _resolvePhaseDir(phaseArg, cwd, slug) {
+  const hit = findPhaseDir(phaseArg, cwd);
+  if (hit) return hit;
+  const padded = paddedPhase(phaseArg);
+  return path.join(path.resolve(cwd), '.nubos-pilot', 'phases', padded + '-' + slug);
+}
+
+function _buildPayload(phaseArg, cwd) {
+  let phase;
+  try {
+    phase = getPhase(phaseArg, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'ui-review-not-found',
+        'Phase ' + phaseArg + ' not found in roadmap',
+        { number: phaseArg },
+      );
+    }
+    throw err;
+  }
+
+  const padded = paddedPhase(phaseArg);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const ui_review_path = path.join(phase_dir, padded + '-UI-REVIEW.md');
+  const summary_path = path.join(phase_dir, padded + '-SUMMARY.md');
+  const summary_present = fs.existsSync(summary_path);
+  const ui_spec_path = path.join(phase_dir, padded + '-UI-SPEC.md');
+  const has_ui_spec = fs.existsSync(ui_spec_path);
+  const { runtime } = detect({ cwd });
+
+  return {
+    _workflow: 'ui-review',
+    phase: phaseArg,
+    padded,
+    phase_dir,
+    ui_review_path,
+    summary_present,
+    summary_path,
+    ui_spec_path,
+    has_ui_spec,
+    agents: { ui_auditor: 'np-ui-auditor' },
+    runtime,
+  };
+}
+
+function _emitError(err, stderr) {
+  if (err && err.name === 'NubosPilotError') {
+    stderr.write(
+      JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+    );
+  } else {
+    stderr.write(String((err && err.stack) || err) + '\n');
+  }
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const list = Array.isArray(args) ? args : [];
+
+  if (list[0] == null || list[0] === '') {
+    stderr.write('Usage: np-tools.cjs init ui-review <phase>\n');
+    return 1;
+  }
+
+  try {
+    const phaseArg = _validatePhaseArg(list[0]);
+    const payload = _buildPayload(phaseArg, cwd);
+    stdout.write(JSON.stringify(payload, null, 2));
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, _buildPayload };

package/bin/np-tools/ui-review.test.cjs

@@ -0,0 +1,120 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, seedRoadmapYaml, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./ui-review.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          {
+            number: 9,
+            name: 'Feature Set',
+            slug: 'feature-set',
+            goal: 'Ship advanced workflows',
+            depends_on: [],
+            requirements: ['R-03'],
+            success_criteria: ['UI review produced'],
+            status: 'pending',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _capture() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('UIR-1: no SUMMARY.md → summary_present=false, has_ui_spec=false', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const dir = seedPhaseDir(sandbox, 9, 'feature-set', {});
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.phase, '9');
+  assert.equal(payload.padded, '09');
+  assert.equal(payload.phase_dir, dir);
+  assert.equal(payload.ui_review_path, path.join(dir, '09-UI-REVIEW.md'));
+  assert.equal(payload.summary_present, false);
+  assert.equal(payload.has_ui_spec, false);
+});
+
+test('UIR-2: SUMMARY.md present flips summary_present true and sets summary_path', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const dir = seedPhaseDir(sandbox, 9, 'feature-set', {
+    '09-SUMMARY.md': '# summary\n',
+  });
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.summary_present, true);
+  assert.equal(payload.summary_path, path.join(dir, '09-SUMMARY.md'));
+});
+
+test('UIR-3: UI-SPEC present flips has_ui_spec true', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {
+    '09-SUMMARY.md': '# summary\n',
+    '09-UI-SPEC.md': '# ui\n',
+  });
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.has_ui_spec, true);
+});
+
+test('UIR-4: agents.ui_auditor declared', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {});
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.deepEqual(payload.agents, { ui_auditor: 'np-ui-auditor' });
+});
+
+test('UIR-5: runtime populated via detect()', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {});
+  fs.writeFileSync(
+    path.join(sandbox, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ runtime: 'gemini' }),
+    'utf-8',
+  );
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.runtime, 'gemini');
+});
+
+test('UIR-6: missing phase returns ui-review-not-found', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _capture();
+  let errBuf = '';
+  const code = subcmd.run(['99'], {
+    cwd: sandbox, stdout: cap.stub,
+    stderr: { write: (s) => { errBuf += s; return true; } },
+  });
+  assert.equal(code, 1);
+  const parsed = JSON.parse(errBuf.trim());
+  assert.equal(parsed.code, 'ui-review-not-found');
+});

package/bin/np-tools/undo-task.cjs

@@ -0,0 +1,31 @@
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { TASK_ID_RE } = require('../../lib/tasks.cjs');
+const { undoTask } = require('../../lib/undo.cjs');
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const taskId = list[0];
+  if (!taskId) {
+    throw new NubosPilotError(
+      'undo-task-missing-id',
+      'undo-task requires a task id (e.g. 06-01-T01)',
+      {},
+    );
+  }
+  if (!TASK_ID_RE.test(taskId)) {
+    throw new NubosPilotError(
+      'undo-task-invalid-id',
+      'Invalid task id format: ' + taskId,
+      { taskId },
+    );
+  }
+  const result = undoTask(taskId, cwd);
+  const payload = { ok: true, task_id: result.task_id, reverted_sha: result.reverted_sha };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/undo-task.test.cjs

@@ -0,0 +1,117 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+const subcmd = require('./undo-task.cjs');
+const git = require('../../lib/git.cjs');
+
+const _repos = [];
+
+function makeRepoWithTask(taskId, file) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-utask-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'init'], { stdio: 'pipe' });
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: 6
+current_plan: "06-01"
+current_task: null
+last_updated: "2026-04-15T00:00:00Z"
+progress:
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
+session:
+  stopped_at: null
+  resume_file: null
+  last_activity: null
+---
+
+# State
+`, 'utf-8');
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', '06-demo');
+  const tasksDir = path.join(phaseDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, taskId + '.md'), [
+    '---',
+    `id: ${taskId}`,
+    'phase: 6',
+    'plan: "06-01"',
+    'type: auto',
+    'status: done',
+    'tier: sonnet',
+    'owner: np-executor',
+    'wave: 1',
+    'depends_on: []',
+    'files_modified:',
+    `  - ${file}`,
+    'autonomous: true',
+    'must_haves:',
+    '  truths: []',
+    '---',
+    '',
+    '# Task',
+  ].join('\n'), 'utf-8');
+
+  const abs = path.join(root, file);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, 'data\n', 'utf-8');
+  const prev = process.cwd();
+  process.chdir(root);
+  try {
+    git.commitTask(taskId, [file], 'task(' + taskId + '): demo');
+  } finally {
+    process.chdir(prev);
+  }
+  _repos.push(root);
+  return root;
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; } }, get: () => b }; }
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('UT-1: undo-task missing id', () => {
+  assert.throws(
+    () => subcmd.run([], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'undo-task-missing-id',
+  );
+});
+
+test('UT-2: undo-task invalid id', () => {
+  assert.throws(
+    () => subcmd.run(['bad/id'], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'undo-task-invalid-id',
+  );
+});
+
+test('UT-3: undo-task reverts and emits payload', () => {
+  const root = makeRepoWithTask('06-01-T01', 'src/u.ts');
+  const prev = process.cwd();
+  process.chdir(root);
+  const cap = _capture();
+  try {
+    subcmd.run(['06-01-T01'], { cwd: root, stdout: cap.stub });
+  } finally {
+    process.chdir(prev);
+  }
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.ok, true);
+  assert.equal(payload.task_id, '06-01-T01');
+  assert.ok(/^[0-9a-f]{40}$/.test(payload.reverted_sha));
+});

package/bin/np-tools/undo.cjs

@@ -0,0 +1,43 @@
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { undoPhase, undoPlan } = require('../../lib/undo.cjs');
+
+const PLAN_RE = /^\d{2}-\d{2}$/;
+const PHASE_RE = /^\d+(\.\d+)?$/;
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const arg = list[0];
+  if (!arg) {
+    throw new NubosPilotError(
+      'undo-missing-arg',
+      'undo requires a phase number or plan id',
+      {},
+    );
+  }
+  let result;
+  if (PLAN_RE.test(arg)) {
+    result = undoPlan(arg, cwd);
+  } else if (PHASE_RE.test(arg)) {
+    result = undoPhase(arg, cwd);
+  } else {
+    throw new NubosPilotError(
+      'undo-invalid-arg',
+      'undo arg must be a phase number (e.g. 6) or plan id (e.g. 06-01), got: ' + arg,
+      { arg },
+    );
+  }
+  const payload = {
+    ok: true,
+    target: arg,
+    reverted: result.reverted,
+    pending_count: result.pending_count,
+  };
+  if (result.message) payload.message = result.message;
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/undo.test.cjs

@@ -0,0 +1,120 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+const subcmd = require('./undo.cjs');
+const git = require('../../lib/git.cjs');
+
+const _repos = [];
+
+function makeRepoBase() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-undo-cli-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'init'], { stdio: 'pipe' });
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: null
+current_plan: null
+current_task: null
+last_updated: "2026-04-15T00:00:00Z"
+progress:
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
+session:
+  stopped_at: null
+  resume_file: null
+  last_activity: null
+---
+
+# State
+`, 'utf-8');
+  _repos.push(root);
+  return root;
+}
+
+function seedAndCommit(root, planId, taskId, file) {
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', planId.slice(0, 2) + '-demo');
+  const tasksDir = path.join(phaseDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, taskId + '.md'), [
+    '---',
+    `id: ${taskId}`, `phase: ${Number(planId.slice(0, 2))}`, `plan: "${planId}"`,
+    'type: auto', 'status: done', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified:', `  - ${file}`, 'autonomous: true',
+    'must_haves:', '  truths: []', '---', '', '# Task',
+  ].join('\n'), 'utf-8');
+  const abs = path.join(root, file);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, 'data\n', 'utf-8');
+  const prev = process.cwd();
+  process.chdir(root);
+  try { git.commitTask(taskId, [file], 'task(' + taskId + '): demo'); }
+  finally { process.chdir(prev); }
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; } }, get: () => b }; }
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('UN-CLI-1: undo missing arg', () => {
+  assert.throws(
+    () => subcmd.run([], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'undo-missing-arg',
+  );
+});
+
+test('UN-CLI-2: undo invalid arg shape (T-06-18 injection guard)', () => {
+  assert.throws(
+    () => subcmd.run(['6; rm -rf /'], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'undo-invalid-arg',
+  );
+});
+
+test('UN-CLI-3: undo plan reverts all task commits of the plan', () => {
+  const root = makeRepoBase();
+  seedAndCommit(root, '06-01', '06-01-T01', 'src/x.ts');
+  seedAndCommit(root, '06-01', '06-01-T02', 'src/y.ts');
+  const prev = process.cwd();
+  process.chdir(root);
+  const cap = _capture();
+  try {
+    subcmd.run(['06-01'], { cwd: root, stdout: cap.stub });
+  } finally {
+    process.chdir(prev);
+  }
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.ok, true);
+  assert.equal(payload.target, '06-01');
+  assert.equal(payload.reverted.length, 2);
+});
+
+test('UN-CLI-4: undo phase emits nothing-to-revert when no commits match', () => {
+  const root = makeRepoBase();
+  const prev = process.cwd();
+  process.chdir(root);
+  const cap = _capture();
+  try {
+    subcmd.run(['7'], { cwd: root, stdout: cap.stub });
+  } finally {
+    process.chdir(prev);
+  }
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.message, 'nothing to revert');
+  assert.equal(payload.reverted.length, 0);
+});

package/bin/np-tools/unpark.cjs

@@ -0,0 +1,48 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+const { TASK_ID_RE, setTaskStatus } = require('../../lib/tasks.cjs');
+
+function _findPlanDirForTask(taskId, cwd) {
+  const phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const padded = taskId.slice(0, 2);
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!(e.name === padded || e.name.startsWith(padded + '-'))) continue;
+    const candidate = path.join(phasesRoot, e.name, 'tasks', taskId + '.md');
+    if (fs.existsSync(candidate)) return path.join(phasesRoot, e.name);
+  }
+  return null;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const taskId = list[0];
+  if (!taskId) {
+    throw new NubosPilotError('unpark-missing-task-id', 'unpark requires a task id', {});
+  }
+  if (!TASK_ID_RE.test(taskId)) {
+    throw new NubosPilotError('unpark-invalid-task-id', 'Invalid task id: ' + taskId, { taskId });
+  }
+  const planDir = _findPlanDirForTask(taskId, cwd);
+  if (!planDir) {
+    throw new NubosPilotError('task-not-found', 'No task file found for id ' + taskId, { taskId });
+  }
+  setTaskStatus(taskId, 'pending', planDir);
+  const payload = { ok: true, task_id: taskId, status: 'pending' };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/unpark.test.cjs

@@ -0,0 +1,50 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const subcmd = require('./unpark.cjs');
+
+const _roots = [];
+
+function makeRoot(taskId) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-unpark-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  const tasksDir = path.join(root, '.nubos-pilot', 'phases', '06-demo', 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, taskId + '.md'), [
+    '---', `id: ${taskId}`, 'phase: 6', 'plan: "06-01"', 'type: auto',
+    'status: parked', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified: []', 'autonomous: true',
+    'must_haves:', '  truths: []', '---', '', '# T',
+  ].join('\n'), 'utf-8');
+  _roots.push(root);
+  return root;
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; } }, get: () => b }; }
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('UP-1: unpark missing id', () => {
+  assert.throws(
+    () => subcmd.run([], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'unpark-missing-task-id',
+  );
+});
+
+test('UP-2: unpark flips status to pending', () => {
+  const root = makeRoot('06-01-T03');
+  const cap = _capture();
+  subcmd.run(['06-01-T03'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.status, 'pending');
+  const tf = path.join(root, '.nubos-pilot', 'phases', '06-demo', 'tasks', '06-01-T03.md');
+  assert.match(fs.readFileSync(tf, 'utf-8'), /^status: pending$/m);
+});