nubos-pilot 0.1.0

package/bin/np-tools/phase.cjs

@@ -0,0 +1,71 @@
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { parseRoadmap } = require('../../lib/roadmap.cjs');
+
+function _usage() {
+  return 'Usage:\n  np-tools.cjs phase next-decimal <base> [--raw]';
+}
+
+function _emitError(err, stderr) {
+  const code = err && err.name === 'NubosPilotError' ? err.code : 'phase-internal-error';
+  const message = (err && err.message) || String(err);
+  const details = (err && err.details) || null;
+  stderr.write(JSON.stringify({ code, message, details }) + '\n');
+}
+
+function nextDecimal(base, cwd) {
+  if (!/^[0-9]+$/.test(String(base))) {
+    throw new NubosPilotError('phase-invalid-base', 'phase next-decimal base must be a non-negative integer: ' + base, { base });
+  }
+  const baseStr = String(base);
+  let phases;
+  try {
+    phases = parseRoadmap(cwd || process.cwd()).phases;
+  } catch (err) {
+    if (err && err.code === 'roadmap-parse-error') return baseStr + '.1';
+    throw err;
+  }
+  const prefix = baseStr + '.';
+  let max = 0;
+  for (const ph of phases) {
+    const n = String(ph.number);
+    if (n.startsWith(prefix)) {
+      const suf = Number(n.slice(prefix.length));
+      if (Number.isInteger(suf) && suf > max) max = suf;
+    }
+  }
+  return baseStr + '.' + (max + 1);
+}
+
+function run(argv, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const sub = args.shift();
+  if (sub !== 'next-decimal') {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  const raw = args.includes('--raw');
+  const base = args.find((a) => !String(a).startsWith('--'));
+  if (base == null) {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  try {
+    const result = nextDecimal(base, cwd);
+    if (raw) stdout.write(result);
+    else stdout.write(result + '\n');
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, nextDecimal };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

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

@@ -0,0 +1,81 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Writable } = require('node:stream');
+
+const phaseCli = require('./phase.cjs');
+
+const _sandboxes = [];
+
+function makeSink() {
+  const chunks = [];
+  const w = new Writable({
+    write(chunk, _enc, cb) { chunks.push(chunk); cb(); },
+  });
+  w.toString = () => Buffer.concat(chunks.map((c) => Buffer.isBuffer(c) ? c : Buffer.from(String(c)))).toString('utf-8');
+  return w;
+}
+
+function makeSandboxWithRoadmap(yaml) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-phase-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'roadmap.yaml'), yaml);
+  _sandboxes.push(root);
+  return root;
+}
+
+test.afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {  }
+  }
+});
+
+test('PHASE-1: next-decimal 999 on empty roadmap → 999.1', () => {
+  const sb = makeSandboxWithRoadmap('milestones:\n  - id: v1.0\n    name: v1\n    phases: []\n');
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = phaseCli.run(['next-decimal', '999', '--raw'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 0);
+  assert.equal(stdout.toString(), '999.1');
+});
+
+test('PHASE-2: next-decimal scans existing 999.1 and 999.3 → 999.4', () => {
+  const yaml = [
+    'milestones:',
+    '  - id: backlog',
+    '    name: Backlog',
+    '    phases:',
+    '      - number: "999.1"',
+    '        name: First',
+    '        slug: first',
+    '      - number: "999.3"',
+    '        name: Third',
+    '        slug: third',
+  ].join('\n') + '\n';
+  const sb = makeSandboxWithRoadmap(yaml);
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = phaseCli.run(['next-decimal', '999', '--raw'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 0);
+  assert.equal(stdout.toString(), '999.4');
+});
+
+test('PHASE-3: invalid base rejected with phase-invalid-base', () => {
+  const sb = makeSandboxWithRoadmap('milestones: []\n');
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = phaseCli.run(['next-decimal', 'abc'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /"code":\s*"phase-invalid-base"/);
+});
+
+test('PHASE-4: unknown subcommand prints usage', () => {
+  const sb = makeSandboxWithRoadmap('milestones: []\n');
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = phaseCli.run(['unknown', '1'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /Usage:/);
+});

package/bin/np-tools/plan-diff.cjs

@@ -0,0 +1,57 @@
+const { renderTwoPartDiff, archiveRejected } = require('../../lib/plan-diff.cjs');
+
+function _usage() {
+  return [
+    'Usage:',
+    '  np-tools.cjs plan-diff <phase> <plan-id>',
+    '  np-tools.cjs plan-diff --archive-rejected <phase> <plan-id> --reason "<text>"',
+  ].join('\n');
+}
+
+function run(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : process.argv.slice(3);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stderr.write(_usage() + '\n');
+    return 1;
+  }
+  try {
+    if (args[0] === '--archive-rejected') {
+      const phase = args[1];
+      const planId = args[2];
+      let reason = '';
+      for (let i = 3; i < args.length; i++) {
+        if (args[i] === '--reason') {
+          reason = args[i + 1] == null ? '' : String(args[i + 1]);
+        }
+      }
+      if (!phase || !planId) {
+        process.stderr.write(_usage() + '\n');
+        return 1;
+      }
+      const archivePath = archiveRejected({ phase, planId, reason, cwd: process.cwd() });
+      process.stdout.write(archivePath + '\n');
+      return 0;
+    }
+    const phase = args[0];
+    const planId = args[1];
+    if (!phase || !planId) {
+      process.stderr.write(_usage() + '\n');
+      return 1;
+    }
+    const result = renderTwoPartDiff({ phase, planId, cwd: process.cwd() });
+    if (!result.hasPrior) return 0;
+    process.stdout.write(result.combined + '\n');
+    return 0;
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError') {
+      process.stderr.write(
+        JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+      );
+    } else {
+      process.stderr.write(String(err && err.stack || err) + '\n');
+    }
+    return 1;
+  }
+}
+
+module.exports = { run };

package/bin/np-tools/plan-diff.test.cjs

@@ -0,0 +1,134 @@
+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('./plan-diff.cjs');
+
+const _repos = [];
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-plan-diff-cli-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos-pilot.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+  _repos.push(root);
+  return root;
+}
+
+function seedPlanCommit(root, phase, phaseSlug, planId, body) {
+  const padded = String(phase).padStart(2, '0');
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', padded + '-' + phaseSlug);
+  fs.mkdirSync(phaseDir, { recursive: true });
+  const rel = path.join('.nubos-pilot', 'phases', padded + '-' + phaseSlug, planId + '-PLAN.md');
+  const abs = path.join(root, rel);
+  fs.writeFileSync(abs, body, 'utf-8');
+  execFileSync('git', ['-C', root, 'add', '--', rel], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', 'seed'], { stdio: 'pipe' });
+  return { abs, rel, phaseDir };
+}
+
+function planBody(tasks) {
+  const lines = ['---', 'plan: 1', 'phase: 9', '---', ''];
+  for (const t of tasks) {
+    lines.push('<task tier="' + t.tier + '" id="' + t.id + '">body</task>');
+  }
+  return lines.join('\n');
+}
+
+function captureIO() {
+  let sout = '';
+  let serr = '';
+  return {
+    stdoutWrite: (s) => { sout += s; return true; },
+    stderrWrite: (s) => { serr += s; return true; },
+    stdout: () => sout,
+    stderr: () => serr,
+  };
+}
+
+function runInRepo(root, argv) {
+  const prev = process.cwd();
+  const po = process.stdout.write;
+  const pe = process.stderr.write;
+  const cap = captureIO();
+  process.stdout.write = cap.stdoutWrite;
+  process.stderr.write = cap.stderrWrite;
+  process.chdir(root);
+  let exit;
+  try {
+    exit = subcmd.run(argv);
+  } finally {
+    process.stdout.write = po;
+    process.stderr.write = pe;
+    process.chdir(prev);
+  }
+  return { exit, stdout: cap.stdout(), stderr: cap.stderr() };
+}
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('PDCLI-1: run([phase, planId]) prints combined diff when prior exists; exits 0', () => {
+  const root = makeRepo();
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', planBody([
+    { id: '09-01-T01', tier: 'opus' },
+  ]));
+  fs.writeFileSync(abs, planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T02', tier: 'sonnet' },
+  ]), 'utf-8');
+  const result = runInRepo(root, ['09', '09-01']);
+  assert.equal(result.exit, 0);
+  assert.ok(result.stdout.includes('Semantic diff'));
+  assert.ok(result.stdout.includes('Raw git diff'));
+});
+
+test('PDCLI-2: run([phase, planId]) prints empty stdout and exits 0 when no prior in HEAD', () => {
+  const root = makeRepo();
+  const padded = '09';
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', padded + '-feature-set');
+  fs.mkdirSync(phaseDir, { recursive: true });
+  fs.writeFileSync(path.join(phaseDir, '09-01-PLAN.md'), planBody([{ id: '09-01-T01', tier: 'opus' }]), 'utf-8');
+  const result = runInRepo(root, ['09', '09-01']);
+  assert.equal(result.exit, 0);
+  assert.equal(result.stdout, '');
+});
+
+test('PDCLI-3: run([--archive-rejected, phase, planId, --reason, text]) archives + restores, exits 0', () => {
+  const root = makeRepo();
+  const priorBody = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', priorBody);
+  fs.writeFileSync(abs, planBody([{ id: '09-01-T02', tier: 'haiku' }]), 'utf-8');
+  const result = runInRepo(root, ['--archive-rejected', '09', '09-01', '--reason', 'design flaw']);
+  assert.equal(result.exit, 0);
+  const archivePath = result.stdout.trim();
+  assert.ok(fs.existsSync(archivePath));
+  const restored = fs.readFileSync(abs, 'utf-8');
+  assert.equal(restored, priorBody);
+});
+
+test('PDCLI-4: run([--archive-rejected]) with missing args exits 1 with usage on stderr', () => {
+  const root = makeRepo();
+  const result = runInRepo(root, ['--archive-rejected']);
+  assert.equal(result.exit, 1);
+  assert.ok(result.stderr.includes('Usage'));
+});
+
+test('PDCLI-5: run([]) prints usage on stderr and exits 1', () => {
+  const root = makeRepo();
+  const r1 = runInRepo(root, []);
+  assert.equal(r1.exit, 1);
+  assert.ok(r1.stderr.includes('Usage'));
+  const r2 = runInRepo(root, ['--help']);
+  assert.equal(r2.exit, 1);
+  assert.ok(r2.stderr.includes('Usage'));
+});

package/bin/np-tools/plan-milestone-gaps.cjs

@@ -0,0 +1,115 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const YAML = require('yaml');
+
+const { scanVerifications, parseAuditFile } = require('../../lib/gaps.cjs');
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+
+function _parseFlags(args) {
+  const flags = { from: null, insertAfter: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--from') {
+      flags.from = args[++i];
+    } else if (a === '--insert-after') {
+      const raw = args[++i];
+      const n = Number(raw);
+      if (raw == null || !Number.isInteger(n)) {
+        throw new NubosPilotError(
+          'invalid-insert-after',
+          '--insert-after requires an integer phase number',
+          { value: raw == null ? '' : String(raw) },
+        );
+      }
+      flags.insertAfter = n;
+    }
+  }
+  return flags;
+}
+
+function _readMilestoneId(cwd) {
+
+  
+  try {
+    const { readState } = require('../../lib/state.cjs');
+    const st = readState(cwd);
+    if (st && st.frontmatter && st.frontmatter.milestone) {
+      return String(st.frontmatter.milestone);
+    }
+  } catch (_err) {  }
+  let stateDir;
+  try { stateDir = projectStateDir(cwd); } catch (_err) {
+    stateDir = path.join(path.resolve(cwd), '.nubos-pilot');
+  }
+  const yamlPath = path.join(stateDir, 'roadmap.yaml');
+  const raw = fs.readFileSync(yamlPath, 'utf-8');
+  const doc = YAML.parse(raw);
+  if (!doc || !Array.isArray(doc.milestones) || doc.milestones.length === 0) {
+    throw new NubosPilotError(
+      'gaps-no-milestone',
+      'roadmap.yaml has no milestones',
+      { path: yamlPath },
+    );
+  }
+  return String(doc.milestones[0].id);
+}
+
+function _agentSkills() {
+  try {
+    const agents = require('../../lib/agents.cjs');
+    if (typeof agents.getAgentSkills === 'function') {
+      return { planner: agents.getAgentSkills('np-planner') };
+    }
+  } catch (_err) {  }
+  return { planner: 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-plan-milestone-gaps-' + 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 flags = _parseFlags(args || []);
+  const milestoneId = _readMilestoneId(cwd);
+  const mode = flags.from ? 'from-file' : 'scan';
+  const gaps = flags.from
+    ? parseAuditFile(flags.from, cwd)
+    : scanVerifications(milestoneId, cwd);
+  const payload = {
+    _workflow: 'plan-milestone-gaps',
+    milestoneId,
+    mode,
+    gaps,
+    insertAfter: flags.insertAfter,
+    agent_skills: _agentSkills(),
+  };
+  _emit(payload, stdout, cwd);
+  return payload;
+}
+
+module.exports = { run, _parseFlags, INLINE_THRESHOLD_BYTES };

package/bin/np-tools/plan-milestone-gaps.test.cjs

@@ -0,0 +1,122 @@
+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('./plan-milestone-gaps.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          { number: 1, name: 'One', slug: 'one', goal: '', depends_on: [], requirements: [], success_criteria: [], status: 'done', plans: [] },
+          { number: 7, name: 'Seven', slug: 'seven', goal: '', depends_on: [6], requirements: [], success_criteria: [], status: 'done', plans: [] },
+        ],
+      },
+    ],
+  };
+}
+
+function _captureStdout() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('CMD-1: no flags → JSON payload with mode=scan', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  subcmd.run([], { cwd: sandbox, stdout: cap.stub });
+  const raw = cap.get().trim();
+  assert.ok(!raw.startsWith('@file:'), 'small payload emitted inline');
+  const payload = JSON.parse(raw);
+  assert.equal(payload.milestoneId, 'v1.0');
+  assert.equal(payload.mode, 'scan');
+  assert.ok(Array.isArray(payload.gaps));
+  assert.equal(payload.insertAfter, null);
+  assert.ok('agent_skills' in payload);
+});
+
+test('CMD-2: --from audit-file → mode=from-file, gaps populated', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const auditPath = path.join(sandbox, 'audit.md');
+  fs.copyFileSync(
+    path.join(__dirname, '..', '..', 'tests', 'fixtures', 'gaps', 'audit-from-file.md'),
+    auditPath,
+  );
+  const cap = _captureStdout();
+  subcmd.run(['--from', auditPath], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.mode, 'from-file');
+  assert.equal(payload.gaps.length, 2);
+  for (const g of payload.gaps) assert.equal(g.source_phase, 7);
+});
+
+test('CMD-3: --from /etc/passwd → throws gaps-invalid-audit-path', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['--from', '/etc/passwd'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'gaps-invalid-audit-path',
+  );
+});
+
+test('CMD-4: --insert-after 7 → payload.insertAfter === 7', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  subcmd.run(['--insert-after', '7'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.insertAfter, 7);
+});
+
+test('CMD-5: --insert-after abc → throws invalid-insert-after', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['--insert-after', 'abc'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'invalid-insert-after',
+  );
+});
+
+test('CMD-6: oversized payload emits @file:<tmp> pointer', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+
+  
+  const big = Array.from({ length: 2000 }, (_, i) =>
+    '- [ ] checkbox item number ' + i + ' with filler padding to grow bytes',
+  ).join('\n');
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': big });
+  const cap = _captureStdout();
+  subcmd.run([], { 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.mode, 'scan');
+  assert.ok(payload.gaps.length >= 2000);
+  fs.unlinkSync(tmpPath);
+});
+
+test('CMD-7: milestoneId defaults to first milestone when STATE.md absent', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  subcmd.run([], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.milestoneId, 'v1.0');
+});