nubos-pilot 0.1.0

package/bin/np-tools/queue.cjs

@@ -0,0 +1,213 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseRoadmap } = require('../../lib/roadmap.cjs');
+const { listPlans } = require('../../lib/plan.cjs');
+
+const MAX_TITLE_LEN = 80;
+const STATE_DIR_NAME = '.nubos-pilot';
+
+function _stateDir(cwd) {
+
+  
+  return path.join(path.resolve(cwd), STATE_DIR_NAME);
+}
+
+function _truncate(s) {
+  if (typeof s !== 'string') return '';
+  const noHtmlComment = s.replace(/<!--[\s\S]*?-->/g, '').trim();
+  if (noHtmlComment.length <= MAX_TITLE_LEN) return noHtmlComment;
+  return noHtmlComment.slice(0, MAX_TITLE_LEN - 1) + '…';
+}
+
+function _readFirstH1(file) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf-8'); } catch { return path.basename(file); }
+  const lines = raw.split('\n');
+  for (const line of lines) {
+    if (line.startsWith('# ')) return _truncate(line.slice(2));
+  }
+  return path.basename(file);
+}
+
+function _collectTodos(stateDir) {
+  const todosDir = path.join(stateDir, 'todos', 'pending');
+  if (!fs.existsSync(todosDir)) return [];
+  const items = [];
+  let entries;
+  try { entries = fs.readdirSync(todosDir); } catch { return []; }
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const full = path.join(todosDir, name);
+    items.push({
+      source: 'todo',
+      id: name,
+      title: _readFirstH1(full),
+      path: full,
+    });
+  }
+  return items;
+}
+
+function _safeParseRoadmap(cwd) {
+  try { return parseRoadmap(cwd); } catch { return null; }
+}
+
+function _paddedPhase(n) {
+  const s = String(n);
+  if (s.length >= 2) return s;
+  return '0' + s;
+}
+
+function _collectBacklog(roadmap) {
+  if (!roadmap || !Array.isArray(roadmap.phases)) return [];
+  const items = [];
+  for (const p of roadmap.phases) {
+    const num = Number(p.number);
+    if (!Number.isFinite(num) || num < 999) continue;
+    items.push({
+      source: 'backlog',
+      id: String(p.number),
+      title: _truncate(p.goal || p.name || String(p.number)),
+    });
+  }
+  return items;
+}
+
+function _collectUat(roadmap, cwd) {
+  if (!roadmap || !Array.isArray(roadmap.phases)) return [];
+  const items = [];
+  const phaseParentDirs = [
+    path.join(path.resolve(cwd), STATE_DIR_NAME, 'phases'),
+    path.join(path.resolve(cwd), '.planning', 'phases'),
+  ];
+  for (const p of roadmap.phases) {
+    const padded = _paddedPhase(p.number);
+    const candidateFiles = [];
+    for (const parent of phaseParentDirs) {
+      if (!fs.existsSync(parent)) continue;
+      let dirs;
+      try { dirs = fs.readdirSync(parent); } catch { continue; }
+      const match = dirs.find((d) => d.startsWith(padded + '-'));
+      if (!match) continue;
+      const phaseDir = path.join(parent, match);
+      candidateFiles.push(
+        path.join(phaseDir, padded + '-VERIFICATION.md'),
+        path.join(phaseDir, padded + '-UAT.md'),
+      );
+    }
+    for (const file of candidateFiles) {
+      if (!fs.existsSync(file)) continue;
+      let raw;
+      try { raw = fs.readFileSync(file, 'utf-8'); } catch { continue; }
+      const lines = raw.split('\n');
+      for (const line of lines) {
+        if (!/^- \[ \]/.test(line)) continue;
+        const title = _truncate(line.replace(/^- \[ \]\s*/, ''));
+        const shortKey = (title || '').slice(0, 40).replace(/\s+/g, '-') || 'item';
+        items.push({
+          source: 'uat',
+          id: padded + ':' + shortKey,
+          title,
+          file,
+        });
+      }
+    }
+  }
+  return items;
+}
+
+function _collectUnplanned(roadmap, cwd) {
+  if (!roadmap || !Array.isArray(roadmap.phases)) return [];
+  const items = [];
+  const phaseParentDirs = [
+    path.join(path.resolve(cwd), STATE_DIR_NAME, 'phases'),
+    path.join(path.resolve(cwd), '.planning', 'phases'),
+  ];
+  for (const p of roadmap.phases) {
+    const num = Number(p.number);
+    if (!Number.isFinite(num) || num >= 999) continue;
+    const padded = _paddedPhase(p.number);
+    let phaseDir = null;
+    for (const parent of phaseParentDirs) {
+      if (!fs.existsSync(parent)) continue;
+      let dirs;
+      try { dirs = fs.readdirSync(parent); } catch { continue; }
+      const match = dirs.find((d) => d.startsWith(padded + '-'));
+      if (match) { phaseDir = path.join(parent, match); break; }
+    }
+    if (!phaseDir) {
+      items.push({
+        source: 'unplanned-phase',
+        id: String(p.number),
+        title: _truncate(p.goal || p.name || String(p.number)),
+      });
+      continue;
+    }
+    const plans = listPlans(phaseDir);
+    if (plans.length === 0) {
+      items.push({
+        source: 'unplanned-phase',
+        id: String(p.number),
+        title: _truncate(p.goal || p.name || String(p.number)),
+      });
+    }
+  }
+  return items;
+}
+
+function _fallbackMdRoadmap(cwd) {
+  const candidates = [
+    path.join(path.resolve(cwd), STATE_DIR_NAME, 'ROADMAP.md'),
+    path.join(path.resolve(cwd), '.planning', 'ROADMAP.md'),
+  ];
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    let raw;
+    try { raw = fs.readFileSync(file, 'utf-8'); } catch { continue; }
+    const lines = raw.split('\n');
+    const phases = [];
+    let current = null;
+    for (const line of lines) {
+      const header = line.match(/^##\s+Phase\s+(\d+)/);
+      if (header) {
+        if (current) phases.push(current);
+        current = { number: header[1], goal: '', name: '' };
+        continue;
+      }
+      if (current && !current.goal) {
+        const g = line.match(/^\s*-\s*goal:\s*(.+)$/);
+        if (g) current.goal = g[1].trim();
+      }
+    }
+    if (current) phases.push(current);
+    if (phases.length > 0) return { phases };
+  }
+  return null;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+
+  const stateDir = _stateDir(cwd);
+  const items = [];
+
+  items.push(..._collectTodos(stateDir));
+
+  const roadmap = _safeParseRoadmap(cwd) || _fallbackMdRoadmap(cwd);
+  if (roadmap) {
+    items.push(..._collectBacklog(roadmap));
+    items.push(..._collectUat(roadmap, cwd));
+    items.push(..._collectUnplanned(roadmap, cwd));
+  }
+
+  const payload = { items };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/research-phase.cjs

@@ -0,0 +1,144 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+
+function _parsePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'research-invalid-phase-arg',
+      'research-phase requires a phase number argument',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new NubosPilotError(
+      'research-invalid-phase-arg',
+      'research-phase argument must be a non-negative integer',
+      { value: String(raw) },
+    );
+  }
+  return n;
+}
+
+function _paddedPhase(n) {
+  return String(n).padStart(2, '0');
+}
+
+function _findPhaseDir(cwd, padded) {
+
+  
+  let phasesRoot;
+  try {
+    phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  } catch (err) {
+    if (!err || err.code !== 'not-in-project') throw err;
+    phasesRoot = path.join(path.resolve(cwd), '.planning', 'phases');
+  }
+  try {
+    const entries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+    const hit = entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .find((name) => name === padded || name.startsWith(padded + '-'));
+    if (hit) return path.join(phasesRoot, hit);
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') throw err;
+  }
+
+  
+
+  return path.join(phasesRoot, padded);
+}
+
+function _readRoadmapPhase(cwd, phaseNumber) {
+  const { getPhase } = require('../../lib/roadmap.cjs');
+  try {
+    return getPhase(phaseNumber, cwd);
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError' && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'research-phase-not-found',
+        'Phase ' + phaseNumber + ' not found in roadmap',
+        { number: phaseNumber },
+      );
+    }
+    throw err;
+  }
+}
+
+function _toolsAvailable() {
+  return {
+    WebFetch: process.env.NP_TOOLS_WEBFETCH === '1',
+    Context7: process.env.NP_TOOLS_CONTEXT7 === '1',
+  };
+}
+
+function _agentSkills(cwd) {
+  try {
+    const agents = require('../../lib/agents.cjs');
+    if (typeof agents.getAgentSkills === 'function') {
+      return { researcher: agents.getAgentSkills('np-researcher', cwd) };
+    }
+  } catch (_err) {  }
+  return { researcher: null };
+}
+
+function _emit(payload, stdout, cwd) {
+  const json = JSON.stringify(payload, null, 2);
+  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD_BYTES) {
+    stdout.write(json);
+    return;
+  }
+  let tmpDir;
+  try {
+    tmpDir = path.join(projectStateDir(cwd), '.tmp');
+    fs.mkdirSync(tmpDir, { recursive: true });
+  } catch (_err) {
+    tmpDir = os.tmpdir();
+  }
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'init-research-phase-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+
+  const phase = _parsePhaseArg((args || [])[0]);
+  const padded = _paddedPhase(phase);
+  const phaseInfo = _readRoadmapPhase(cwd, phase);
+  const phase_dir = _findPhaseDir(cwd, padded);
+
+  const researchPath = path.join(phase_dir, padded + '-RESEARCH.md');
+  let has_research = false;
+  try {
+    has_research = fs.statSync(researchPath).isFile();
+  } catch (_err) { has_research = false; }
+
+  const payload = {
+    _workflow: 'research-phase',
+    phase,
+    padded,
+    phase_dir,
+    goal: phaseInfo.goal || '',
+    requirements: Array.isArray(phaseInfo.requirements)
+      ? phaseInfo.requirements.slice()
+      : [],
+    has_research,
+    tools_available: _toolsAvailable(),
+    agent_skills: _agentSkills(cwd),
+  };
+  _emit(payload, stdout, cwd);
+  return payload;
+}
+
+module.exports = { run, INLINE_THRESHOLD_BYTES, _parsePhaseArg };

package/bin/np-tools/research-phase.test.cjs

@@ -0,0 +1,154 @@
+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('./research-phase.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          {
+            number: 3,
+            name: 'Three',
+            slug: 'three',
+            goal: 'Goal of phase 3',
+            depends_on: [],
+            requirements: ['R-1', 'R-2'],
+            success_criteria: ['SC-1'],
+            status: 'pending',
+            plans: [],
+          },
+          {
+            number: 5,
+            name: 'Five',
+            slug: 'five-planning',
+            goal: 'Goal of phase 5',
+            depends_on: [4],
+            requirements: ['PLAN-03'],
+            success_criteria: [],
+            status: 'pending',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _captureStdout() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+function _clearEnv() {
+  delete process.env.NP_TOOLS_WEBFETCH;
+  delete process.env.NP_TOOLS_CONTEXT7;
+}
+
+afterEach(() => {
+  _clearEnv();
+  cleanupAll();
+});
+
+test('RP-1: run(["3"]) on phase 3 returns payload with all required keys', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'three', {});
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.phase, 3);
+  assert.equal(payload.padded, '03');
+  assert.ok(payload.phase_dir.endsWith(path.join('phases', '03-three')));
+  assert.equal(payload.goal, 'Goal of phase 3');
+  assert.deepEqual(payload.requirements, ['R-1', 'R-2']);
+  assert.equal(payload.has_research, false);
+  assert.equal(typeof payload.tools_available, 'object');
+  assert.equal(typeof payload.tools_available.WebFetch, 'boolean');
+  assert.equal(typeof payload.tools_available.Context7, 'boolean');
+  assert.ok('agent_skills' in payload);
+});
+
+test('RP-2: has_research=true iff {phase_dir}/{padded}-RESEARCH.md exists', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'three', { '03-RESEARCH.md': '# Research stub\n' });
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.has_research, true);
+});
+
+test('RP-3: tools_available defaults to {false,false} when env vars absent', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 5, 'five-planning', {});
+  _clearEnv();
+  const cap = _captureStdout();
+  subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.tools_available.WebFetch, false);
+  assert.equal(payload.tools_available.Context7, false);
+});
+
+test('RP-4: NP_TOOLS_WEBFETCH=1 and NP_TOOLS_CONTEXT7=1 flip both booleans', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 5, 'five-planning', {});
+  process.env.NP_TOOLS_WEBFETCH = '1';
+  process.env.NP_TOOLS_CONTEXT7 = '1';
+  const cap = _captureStdout();
+  subcmd.run(['5'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.tools_available.WebFetch, true);
+  assert.equal(payload.tools_available.Context7, true);
+});
+
+test('RP-5: missing phase number throws research-phase-not-found', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['99'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'research-phase-not-found',
+  );
+});
+
+test('RP-6: non-integer arg throws research-invalid-phase-arg', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['bad'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'research-invalid-phase-arg',
+  );
+});
+
+test('RP-7: oversized payload emits @file: pointer', () => {
+  const sandbox = makeSandbox();
+
+  const big = _baseRoadmap();
+  const huge = Array.from({ length: 2000 }, (_, i) => 'REQ-' + i + '-very-long-requirement-identifier-padded');
+  big.milestones[0].phases[0].requirements = huge;
+  seedRoadmapYaml(sandbox, big);
+  seedPhaseDir(sandbox, 3, 'three', {});
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const out = cap.get().trim();
+  assert.ok(out.startsWith('@file:'), 'large payload produced @file: pointer');
+  const tmpPath = out.slice('@file:'.length);
+  const body = fs.readFileSync(tmpPath, 'utf-8');
+  const payload = JSON.parse(body);
+  assert.equal(payload.phase, 3);
+  assert.ok(payload.requirements.length >= 2000);
+  fs.unlinkSync(tmpPath);
+});

package/bin/np-tools/reset-slice.cjs

@@ -0,0 +1,17 @@
+const { resetSlice } = require('../../lib/undo.cjs');
+
+function run(_args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const result = resetSlice(cwd);
+  const payload = {
+    ok: true,
+    task_id: result.task_id,
+    restored_paths: result.restored_paths,
+  };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/reset-slice.test.cjs

@@ -0,0 +1,96 @@
+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('./reset-slice.cjs');
+const cp = require('../../lib/checkpoint.cjs');
+
+const _repos = [];
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-rs-'));
+  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');
+  _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('RS-1: reset-slice with no current_task → undo-dirty-tree', () => {
+  const root = makeRepo();
+  assert.throws(
+    () => subcmd.run([], { cwd: root, stdout: _capture().stub }),
+    (err) => err && err.code === 'undo-dirty-tree',
+  );
+});
+
+test('RS-2: reset-slice restores files and emits payload', () => {
+  const root = makeRepo();
+
+  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, '06-01-T05.md'), [
+    '---', 'id: 06-01-T05', 'phase: 6', 'plan: "06-01"', 'type: auto',
+    'status: in-progress', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified:', '  - src/r.ts',
+    'autonomous: true', 'must_haves:', '  truths: []', '---', '', '# T',
+  ].join('\n'), 'utf-8');
+
+  fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'src', 'r.ts'), 'baseline\n', 'utf-8');
+  const prev = process.cwd();
+  process.chdir(root);
+  try {
+    execFileSync('git', ['add', 'src/r.ts'], { stdio: 'pipe' });
+    execFileSync('git', ['commit', '-q', '-m', 'baseline'], { stdio: 'pipe' });
+    cp.startTask({ id: '06-01-T05', phase: 6, plan: '06-01', wave: 1 }, root);
+    cp.writeCheckpoint('06-01-T05', { files_touched: ['src/r.ts'] }, root);
+    fs.writeFileSync(path.join(root, 'src', 'r.ts'), 'dirty\n', 'utf-8');
+    const cap = _capture();
+    subcmd.run([], { cwd: root, stdout: cap.stub });
+    const payload = JSON.parse(cap.get());
+    assert.equal(payload.ok, true);
+    assert.equal(payload.task_id, '06-01-T05');
+    assert.deepEqual(payload.restored_paths, ['src/r.ts']);
+    assert.equal(fs.readFileSync(path.join(root, 'src', 'r.ts'), 'utf-8'), 'baseline\n');
+  } finally {
+    process.chdir(prev);
+  }
+});