nubos-pilot 0.1.0

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

@@ -0,0 +1,116 @@
+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('./execute-phase.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [{
+      id: 'v1.0', name: 'first', phases: [
+        { number: 6, name: 'Execution', slug: 'execution', goal: 'ship', depends_on: [],
+          requirements: ['EXEC-01'], success_criteria: ['tasks commit'], status: 'planned', plans: [] },
+      ],
+    }],
+  };
+}
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+function _seedPhaseWithPlan(sandbox) {
+  const phaseDir = seedPhaseDir(sandbox, 6, 'execution', {
+    '06-01-PLAN.md': '---\nphase: 6\nplan: 01\n---\n# plan\n',
+  });
+  const tasksDir = path.join(phaseDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  const taskMd = [
+    '---',
+    'id: 06-01-T01',
+    'phase: 6',
+    'plan: "06-01"',
+    'type: auto',
+    'status: pending',
+    'tier: sonnet',
+    'owner: np-executor',
+    'wave: 1',
+    'depends_on: []',
+    'files_modified:',
+    '  - src/a.ts',
+    'autonomous: true',
+    'must_haves:',
+    '  truths: []',
+    '---',
+    '',
+    '# Task',
+  ].join('\n');
+  fs.writeFileSync(path.join(tasksDir, '06-01-T01.md'), taskMd, 'utf-8');
+  return phaseDir;
+}
+
+afterEach(cleanupAll);
+
+test('EP-1: init emits payload with waves + executor_tier=sonnet + phase_dir', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const phaseDir = _seedPhaseWithPlan(sandbox);
+  const cap = _capture();
+  subcmd.run(['init', '6'], { cwd: sandbox, stdout: cap.stub });
+  const raw = cap.get().trim();
+  assert.ok(!raw.startsWith('@file:'));
+  const p = JSON.parse(raw);
+  assert.equal(p._workflow, 'execute-phase');
+  assert.equal(p.phase, '6');
+  assert.equal(p.padded, '06');
+  assert.equal(p.phase_dir, phaseDir);
+  assert.equal(p.executor_tier, 'sonnet');
+  assert.ok(Array.isArray(p.plans));
+  assert.ok(p.plans.length >= 1);
+  assert.ok(Array.isArray(p.plans[0].waves));
+});
+
+test('EP-2: init without phase arg throws validation', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-phase-invalid-phase-arg',
+  );
+});
+
+test('EP-3: init rejects non-numeric phase', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init', 'abc'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-phase-invalid-phase-arg',
+  );
+});
+
+test('EP-4: execute-task verb emits task payload with files_modified', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  _seedPhaseWithPlan(sandbox);
+  const cap = _capture();
+  subcmd.run(['execute-task', '6', '06-01-T01'], { cwd: sandbox, stdout: cap.stub });
+  const p = JSON.parse(cap.get().trim());
+  assert.equal(p.task_id, '06-01-T01');
+  assert.deepEqual(p.files_modified, ['src/a.ts']);
+  assert.equal(p.executor_tier, 'sonnet');
+});
+
+test('EP-5: unknown verb throws', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['bogus'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-phase-unknown-verb',
+  );
+});

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

@@ -0,0 +1,124 @@
+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 { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { listPlans, parsePlan } = require('../../lib/plan.cjs');
+const { loadTaskGraph } = require('../../lib/tasks.cjs');
+const { getAgentSkills } = require('../../lib/agents.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+const PLAN_ID_RE = /^\d{2}-\d{2}$/;
+
+function _safeSkills(name, cwd) {
+  try { return getAgentSkills(name, cwd); } catch { return []; }
+}
+
+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 { tmpDir = os.tmpdir(); }
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'init-execute-plan-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function _resolvePhaseDir(n, cwd, slug) {
+  const hit = findPhaseDir(n, cwd);
+  if (hit) return hit;
+  const padded = paddedPhase(n);
+  let stateDir;
+  try { stateDir = projectStateDir(cwd); } catch { stateDir = path.join(path.resolve(cwd), '.nubos-pilot'); }
+  return path.join(stateDir, 'phases', padded + '-' + slug);
+}
+
+function _initPayload(planId, cwd) {
+  const [phaseStr, planStr] = planId.split('-');
+  const phaseNum = Number(phaseStr);
+  const phase = getPhase(phaseNum, cwd);
+  const padded = paddedPhase(phaseNum);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseNum, cwd, slug);
+  const all = listPlans(phase_dir);
+  const target = all.find((p) => path.basename(p) === `${planId}-PLAN.md`);
+  if (!target) {
+    throw new NubosPilotError(
+      'execute-plan-not-found',
+      'Plan ' + planId + ' not found in phase ' + phaseNum,
+      { planId, phase: phaseNum, searched: all },
+    );
+  }
+  const parsed = parsePlan(target);
+  const planDir = path.dirname(target);
+  const tg = loadTaskGraph(planDir);
+  return {
+    _workflow: 'execute-plan',
+    plan_id: planId,
+    phase: phaseStr,
+    padded,
+    plan_number: planStr,
+    phase_dir,
+    phase_name: phase.name,
+    plan_path: target,
+    plan_frontmatter: parsed.frontmatter,
+    tasks_dir: path.join(planDir, 'tasks'),
+    task_count: tg.tasks.length,
+    waves: tg.waves,
+    warnings: tg.warnings,
+    executor_tier: 'sonnet',
+    agent_skills: { executor: _safeSkills('np-executor', cwd) },
+  };
+}
+
+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 verb = list[0];
+
+  switch (verb) {
+    case 'init': {
+      const planId = list[1];
+      if (!planId) {
+        throw new NubosPilotError(
+          'execute-plan-missing-id',
+          'execute-plan requires a plan id (e.g. 06-01)',
+          {},
+        );
+      }
+      if (!PLAN_ID_RE.test(planId)) {
+        throw new NubosPilotError(
+          'execute-plan-invalid-id',
+          'Invalid plan id format: ' + planId + ' (expected NN-NN)',
+          { planId },
+        );
+      }
+      const payload = _initPayload(planId, cwd);
+      _emit(payload, stdout, cwd);
+      return payload;
+    }
+    default:
+      throw new NubosPilotError(
+        'execute-plan-unknown-verb',
+        'execute-plan: unknown verb: ' + String(verb),
+        { verb },
+      );
+  }
+}
+
+module.exports = { run, INLINE_THRESHOLD_BYTES };

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

@@ -0,0 +1,82 @@
+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('./execute-plan.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [{
+      id: 'v1.0', name: 'm1', phases: [
+        { number: 6, name: 'Execution', slug: 'execution', goal: 'ship', depends_on: [],
+          requirements: [], success_criteria: [], status: 'planned', plans: [] },
+      ],
+    }],
+  };
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; return true; } }, get: () => b }; }
+
+function _seedTwoPlans(sandbox) {
+  const phaseDir = seedPhaseDir(sandbox, 6, 'execution', {
+    '06-01-PLAN.md': '---\nphase: 6\nplan: 01\n---\n# p1\n',
+    '06-02-PLAN.md': '---\nphase: 6\nplan: 02\n---\n# p2\n',
+  });
+  for (const id of ['06-01', '06-02']) {
+    const tasksDir = path.join(phaseDir, 'tasks');
+  }
+
+  
+
+  return phaseDir;
+}
+
+afterEach(cleanupAll);
+
+test('XP-1: init <plan-id> emits single-plan payload', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  _seedTwoPlans(sandbox);
+  const cap = _capture();
+  subcmd.run(['init', '06-01'], { cwd: sandbox, stdout: cap.stub });
+  const p = JSON.parse(cap.get().trim());
+  assert.equal(p._workflow, 'execute-plan');
+  assert.equal(p.plan_id, '06-01');
+  assert.equal(p.phase, '06');
+  assert.equal(p.padded, '06');
+  assert.ok(p.plan_path.endsWith('06-01-PLAN.md'));
+  assert.equal(p.executor_tier, 'sonnet');
+});
+
+test('XP-2: invalid plan-id format rejected', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init', 'bogus'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-plan-invalid-id',
+  );
+});
+
+test('XP-3: unknown plan throws', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  _seedTwoPlans(sandbox);
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init', '06-99'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-plan-not-found',
+  );
+});
+
+test('XP-4: init without plan-id throws', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'execute-plan-missing-id',
+  );
+});

package/bin/np-tools/help.cjs

@@ -0,0 +1,28 @@
+const { COMMANDS } = require('./_commands.cjs');
+
+function _renderText(commands) {
+  const byCat = new Map();
+  for (const c of commands) {
+    if (!byCat.has(c.category)) byCat.set(c.category, []);
+    byCat.get(c.category).push(c);
+  }
+  const lines = [];
+  for (const [cat, items] of byCat) {
+    lines.push(cat);
+    for (const c of items) {
+      lines.push('  ' + c.name.padEnd(10) + c.description);
+    }
+    lines.push('');
+  }
+  return lines.join('\n').replace(/\n+$/, '\n');
+}
+
+function run(args) {
+  const list = Array.isArray(args) ? args : [];
+  if (list.includes('--json')) {
+    return { commands: COMMANDS.slice() };
+  }
+  return { text: _renderText(COMMANDS) };
+}
+
+module.exports = { run };

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

@@ -0,0 +1,29 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const helpCmd = require('./help.cjs');
+
+test('HELP-CMD-1: run([]) returns rendered text grouped by category with all 5 names', () => {
+  const out = helpCmd.run([]);
+  assert.ok(out && typeof out.text === 'string');
+  for (const name of ['next', 'progress', 'state', 'help', 'init']) {
+    assert.match(out.text, new RegExp('\\b' + name + '\\b'));
+  }
+});
+
+test('HELP-CMD-2: run([--json]) returns { commands: [...] } with all registered entries', () => {
+  const out = helpCmd.run(['--json']);
+  assert.ok(Array.isArray(out.commands));
+
+  
+  const names = out.commands.map((c) => c.name);
+  for (const n of ['help', 'init', 'next', 'progress', 'state']) {
+    assert.ok(names.includes(n), 'expected utility command: ' + n);
+  }
+  const planning = out.commands.filter((c) => c.category === 'Planning');
+  assert.ok(planning.length >= 8, 'expected ≥8 Planning commands, got ' + planning.length);
+  for (const c of out.commands) {
+    assert.ok(typeof c.category === 'string' && c.category.length > 0);
+    assert.ok(typeof c.description === 'string' && c.description.length > 0);
+  }
+});

package/bin/np-tools/init-dispatch.test.cjs

@@ -0,0 +1,91 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+
+const WORKFLOWS = ['ai-integration-phase', 'ui-phase', 'ui-review', 'eval-review'];
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NP_TOOLS = path.join(REPO_ROOT, 'np-tools.cjs');
+
+for (const wf of WORKFLOWS) {
+  test(`DISP-${wf}: dispatcher routes argv past the verb-gate`, () => {
+
+    
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'np-dispatch-'));
+    const res = spawnSync('node', [NP_TOOLS, 'init', wf, '99'], {
+      cwd: tmp,
+      encoding: 'utf-8',
+    });
+    fs.rmSync(tmp, { recursive: true, force: true });
+
+    assert.doesNotMatch(
+      res.stderr,
+      /^Usage: np-tools\.cjs init/m,
+      `expected no Usage error on stderr for ${wf}, got: ${res.stderr}`,
+    );
+
+    
+  });
+}
+
+const TOP_LEVEL_PHASE10_KEYS = [
+  'askuser',
+  'commit',
+  'config-get',
+  'dispatch',
+  'doctor',
+  'generate-slug',
+  'metrics',
+  'phase',
+  'plan-diff',
+  'queue',
+  'resolve-model',
+  'stats',
+  'triage',
+];
+
+test('TD-1: Phase 10 topLevelCommands routes metrics/resolve-model/plan-diff and 10 siblings', () => {
+  const np = require('../../np-tools.cjs');
+  assert.ok(np.topLevelCommands && typeof np.topLevelCommands === 'object');
+  for (const key of TOP_LEVEL_PHASE10_KEYS) {
+    const mod = np.topLevelCommands[key];
+    assert.ok(mod, `topLevelCommands[${key}] missing`);
+    assert.equal(
+      typeof mod.run,
+      'function',
+      `topLevelCommands[${key}].run must be a function`,
+    );
+  }
+});
+
+test('TD-2: Phase 10 initWorkflows exposes code-review init entry', () => {
+  const np = require('../../np-tools.cjs');
+  assert.ok(np.initWorkflows && typeof np.initWorkflows === 'object');
+  const mod = np.initWorkflows['code-review'];
+  assert.ok(mod, 'initWorkflows[code-review] missing');
+  assert.equal(typeof mod.run, 'function');
+});
+
+test('TD-3: unknown topLevelCommand still returns unknown-command envelope', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'np-dispatch-unknown-'));
+  const res = spawnSync('node', [NP_TOOLS, 'definitely-unknown-xyz'], {
+    cwd: tmp,
+    encoding: 'utf-8',
+  });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  assert.notEqual(res.status, 0);
+  assert.match(res.stderr, /"code":\s*"unknown-command"/);
+});
+
+test('TD-4: metrics now subcommand prints ISO timestamp on stdout', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'np-dispatch-metrics-'));
+  const res = spawnSync('node', [NP_TOOLS, 'metrics', 'now'], {
+    cwd: tmp,
+    encoding: 'utf-8',
+  });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  assert.equal(res.status, 0);
+  assert.match(res.stdout.trim(), /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+});

package/bin/np-tools/metrics.cjs

@@ -0,0 +1,97 @@
+const fs = require('node:fs');
+const { appendRecord, buildRecord } = require('../../lib/metrics.cjs');
+
+function _usage() {
+  return [
+    'Usage:',
+    '  np-tools.cjs metrics record --agent X --tier haiku|sonnet|opus --resolved-model M \\',
+    '                              --phase P --plan PL --task T \\',
+    '                              --started ISO --ended ISO \\',
+    '                              --tokens-in N --tokens-out M \\',
+    '                              --status ok|error|timeout --runtime claude|codex|gemini|opencode \\',
+    '                              [--retry-count N] [--error-code C --error-message MSG]',
+    '  np-tools.cjs metrics record --json @file:/path/to/record.json',
+    '  np-tools.cjs metrics now | start-timestamp | end-timestamp',
+  ].join('\n');
+}
+
+function _parseArgs(argv) {
+  const out = { retry_count: 0, tokens_in: null, tokens_out: null, error: null };
+  let errorCode = null;
+  let errorMessage = null;
+  let jsonPtr = null;
+  let i = 0;
+  while (i < argv.length) {
+    const flag = argv[i++];
+    const val = argv[i++];
+    switch (flag) {
+      case '--agent':          out.agent = val; break;
+      case '--tier':           out.tier = val; break;
+      case '--resolved-model': out.resolved_model = val; break;
+      case '--phase':          out.phase = val; break;
+      case '--plan':           out.plan = val; break;
+      case '--task':           out.task = val; break;
+      case '--started':        out.started_at = val; break;
+      case '--ended':          out.ended_at = val; break;
+      case '--tokens-in':      out.tokens_in = parseInt(val, 10); break;
+      case '--tokens-out':     out.tokens_out = parseInt(val, 10); break;
+      case '--retry-count':    out.retry_count = parseInt(val, 10); break;
+      case '--status':         out.status = val; break;
+      case '--runtime':        out.runtime = val; break;
+      case '--error-code':     errorCode = val; break;
+      case '--error-message':  errorMessage = val; break;
+      case '--json':           jsonPtr = val; break;
+      default: break;
+    }
+  }
+  if (errorCode || errorMessage) {
+    out.error = { code: errorCode || 'unknown', message: errorMessage || '' };
+  }
+  return { parsed: out, jsonPtr };
+}
+
+function _readJsonPtr(ptr) {
+  const prefix = '@file:';
+  const filePath = ptr.startsWith(prefix) ? ptr.slice(prefix.length) : ptr;
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+function run(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : process.argv.slice(3);
+  const sub = args.shift();
+
+  if (sub === 'now' || sub === 'start-timestamp' || sub === 'end-timestamp') {
+    process.stdout.write(new Date().toISOString() + '\n');
+    return 0;
+  }
+
+  if (sub === 'record') {
+    try {
+      const { parsed, jsonPtr } = _parseArgs(args);
+      const input = jsonPtr ? _readJsonPtr(jsonPtr) : parsed;
+      const record = buildRecord(input);
+      const file = appendRecord(record, { cwd: process.cwd() });
+      process.stdout.write(file + '\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;
+    }
+  }
+
+  process.stderr.write(_usage() + '\n');
+  return 1;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}