nubos-pilot 0.1.0

package/lib/askuser.test.cjs

@@ -0,0 +1,310 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const au = require('./askuser.cjs');
+
+const RUNTIME_ENV_KEYS = [
+  'NUBOS_RUNTIME',
+  'CLAUDECODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CODEX_HOME',
+  'CODEX_VERSION',
+  'GEMINI_CLI',
+  'GEMINI_VERSION',
+  'OPENCODE',
+  'OPENCODE_VERSION',
+  'NUBOS_PILOT_REDETECT_RUNTIME',
+];
+
+function snapshotEnv() {
+  const snap = {};
+  for (const k of RUNTIME_ENV_KEYS) snap[k] = process.env[k];
+  return snap;
+}
+function restoreEnv(snap) {
+  for (const k of RUNTIME_ENV_KEYS) {
+    if (snap[k] === undefined) delete process.env[k];
+    else process.env[k] = snap[k];
+  }
+}
+function clearAllRuntimeEnv() {
+  for (const k of RUNTIME_ENV_KEYS) delete process.env[k];
+}
+function forceRedetect() {
+  process.env.NUBOS_PILOT_REDETECT_RUNTIME = '1';
+}
+
+function withEnv(mutator, fn) {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    mutator();
+    forceRedetect();
+    return fn();
+  } finally {
+    restoreEnv(snap);
+    au._setReadlineImplForTests(null);
+  }
+}
+
+test('AU-1: NUBOS_RUNTIME=claude explicit override → claude', () => {
+  withEnv(() => { process.env.NUBOS_RUNTIME = 'claude'; }, () => {
+    assert.equal(au._detectRuntime(), 'claude');
+  });
+});
+
+test('AU-2: NUBOS_RUNTIME=generic-readline beats CLAUDECODE=1 (Pitfall 4)', () => {
+  withEnv(() => {
+    process.env.NUBOS_RUNTIME = 'generic-readline';
+    process.env.CLAUDECODE = '1';
+  }, () => {
+    assert.equal(au._detectRuntime(), 'generic-readline');
+  });
+});
+
+test('AU-3: CLAUDECODE=1 → claude', () => {
+  withEnv(() => { process.env.CLAUDECODE = '1'; }, () => {
+    assert.equal(au._detectRuntime(), 'claude');
+  });
+});
+
+test('AU-4: CODEX_HOME set → codex', () => {
+  withEnv(() => { process.env.CODEX_HOME = '/foo'; }, () => {
+    assert.equal(au._detectRuntime(), 'codex');
+  });
+});
+
+test('AU-5: GEMINI_CLI set → gemini', () => {
+  withEnv(() => { process.env.GEMINI_CLI = '1'; }, () => {
+    assert.equal(au._detectRuntime(), 'gemini');
+  });
+});
+
+test('AU-6: OPENCODE_VERSION set → opencode', () => {
+  withEnv(() => { process.env.OPENCODE_VERSION = 'x'; }, () => {
+    assert.equal(au._detectRuntime(), 'opencode');
+  });
+});
+
+test('AU-7: no env vars → generic-readline', () => {
+  withEnv(() => {}, () => {
+    assert.equal(au._detectRuntime(), 'generic-readline');
+  });
+});
+
+test('AU-8: getRuntime caches — mutation without redetect flag does not change result', () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    process.env.CLAUDECODE = '1';
+    forceRedetect();
+    const first = au.getRuntime();
+    assert.equal(first, 'claude');
+    delete process.env.NUBOS_PILOT_REDETECT_RUNTIME;
+    delete process.env.CLAUDECODE;
+    process.env.CODEX_HOME = '/y';
+    const second = au.getRuntime();
+    assert.equal(second, 'claude');
+  } finally {
+    restoreEnv(snap);
+  }
+});
+
+test('AU-9: getRuntime re-detects when NUBOS_PILOT_REDETECT_RUNTIME=1', () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    process.env.CLAUDECODE = '1';
+    forceRedetect();
+    assert.equal(au.getRuntime(), 'claude');
+    delete process.env.CLAUDECODE;
+    process.env.CODEX_HOME = '/z';
+    process.env.NUBOS_PILOT_REDETECT_RUNTIME = '1';
+    assert.equal(au.getRuntime(), 'codex');
+  } finally {
+    restoreEnv(snap);
+  }
+});
+
+function captureStdout(fn) {
+  const chunks = [];
+  const orig = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk) => { chunks.push(chunk.toString()); return true; };
+  return Promise.resolve(fn()).then(
+    (val) => { process.stdout.write = orig; return { val, out: chunks.join('') }; },
+    (err) => { process.stdout.write = orig; throw err; },
+  );
+}
+function captureStderr(fn) {
+  const chunks = [];
+  const orig = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (chunk) => { chunks.push(chunk.toString()); return true; };
+  return Promise.resolve(fn()).then(
+    (val) => { process.stderr.write = orig; return { val, out: chunks.join('') }; },
+    (err) => { process.stderr.write = orig; throw err; },
+  );
+}
+
+test('AU-10: Claude branch emits askUser v1 marker-block to stdout', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    process.env.NUBOS_RUNTIME = 'claude';
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => 'chosen');
+    const { val, out } = await captureStdout(() =>
+      au.askUser({ type: 'input', question: 'Q' })
+    );
+    assert.match(out, /<!-- askUser v1 -->/);
+    assert.equal(val.source, 'askUserQuestion');
+    assert.equal(val.value, 'chosen');
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-11: marker-block inner JSON contains type, question, options, default keys', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    process.env.NUBOS_RUNTIME = 'claude';
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => '1');
+    const { out } = await captureStdout(() =>
+      au.askUser({ type: 'select', question: 'Pick', options: ['A', 'B'], default: null })
+    );
+    const match = out.match(/<!--\s*(\{[^]*?\})\s*-->/);
+    assert.ok(match, 'inner JSON comment missing');
+    const parsed = JSON.parse(match[1]);
+    assert.equal(parsed.type, 'select');
+    assert.equal(parsed.question, 'Pick');
+    assert.deepEqual(parsed.options, ['A', 'B']);
+    assert.equal('default' in parsed, true);
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-12: readline fallback select parses 1-based index', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => '2');
+    const { val } = await captureStderr(() =>
+      au.askUser({ type: 'select', question: 'P', options: ['A', 'B', 'C'] })
+    );
+    assert.equal(val.value, 'B');
+    assert.equal(val.source, 'readline');
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-13: readline fallback confirm y/n/default', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => 'y');
+    const { val: v1 } = await captureStderr(() =>
+      au.askUser({ type: 'confirm', question: 'OK?' })
+    );
+    assert.equal(v1.value, true);
+
+    au._setReadlineImplForTests(async () => 'n');
+    const { val: v2 } = await captureStderr(() =>
+      au.askUser({ type: 'confirm', question: 'OK?' })
+    );
+    assert.equal(v2.value, false);
+
+    au._setReadlineImplForTests(async () => '');
+    const { val: v3 } = await captureStderr(() =>
+      au.askUser({ type: 'confirm', question: 'OK?', default: true })
+    );
+    assert.equal(v3.value, true);
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-14: readline fallback input returns line verbatim', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => 'hello');
+    const { val } = await captureStderr(() =>
+      au.askUser({ type: 'input', question: 'Name?' })
+    );
+    assert.equal(val.value, 'hello');
+    assert.equal(val.source, 'readline');
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-15: readline multiselect parses comma-separated 1-based indices', async () => {
+  const snap = snapshotEnv();
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(async () => '1,3');
+    const { val } = await captureStderr(() =>
+      au.askUser({ type: 'multiselect', question: 'Pick', options: ['A', 'B', 'C'] })
+    );
+    assert.deepEqual(val.value, ['A', 'C']);
+    assert.equal(val.source, 'readline');
+  } finally {
+    au._setReadlineImplForTests(null);
+    restoreEnv(snap);
+  }
+});
+
+test('AU-16: no TTY, no injected impl, no default → throws askuser-no-tty', async () => {
+  const snap = snapshotEnv();
+  const origIsTTY = process.stdin.isTTY;
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(null);
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+    await assert.rejects(
+      () => au.askUser({ type: 'input', question: 'Q' }),
+      (err) => err && err.code === 'askuser-no-tty',
+    );
+  } finally {
+    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
+    restoreEnv(snap);
+  }
+});
+
+test('AU-17: no TTY with default provided → returns default', async () => {
+  const snap = snapshotEnv();
+  const origIsTTY = process.stdin.isTTY;
+  try {
+    clearAllRuntimeEnv();
+    forceRedetect();
+    au.getRuntime();
+    au._setReadlineImplForTests(null);
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+    const res = await au.askUser({ type: 'input', question: 'Q', default: 'fallback' });
+    assert.equal(res.value, 'fallback');
+    assert.equal(res.source, 'default');
+  } finally {
+    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
+    restoreEnv(snap);
+  }
+});

package/lib/checkpoint.cjs

@@ -0,0 +1,135 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  withFileLocks,
+  withFileLock,
+  atomicWriteFileSync,
+  projectStateDir,
+  NubosPilotError,
+} = require('./core.cjs');
+const { parseState, serializeState } = require('./state.cjs');
+
+const CHECKPOINT_SCHEMA_VERSION = 1;
+
+function checkpointPath(taskId, cwd = process.cwd()) {
+  return path.join(projectStateDir(cwd), 'checkpoints', `${taskId}.json`);
+}
+
+function _statePath(cwd) {
+  return path.join(projectStateDir(cwd), 'STATE.md');
+}
+
+function _nowIso() {
+  return new Date().toISOString();
+}
+
+function startTask(task, cwd = process.cwd()) {
+  if (!task || typeof task.id !== 'string' || task.id.length === 0) {
+    throw new NubosPilotError(
+      'checkpoint-invalid-task',
+      'startTask requires a task object with non-empty .id',
+      { task },
+    );
+  }
+  const cpPath = checkpointPath(task.id, cwd);
+  const statePath = _statePath(cwd);
+  fs.mkdirSync(path.dirname(cpPath), { recursive: true });
+
+  
+
+  return withFileLocks([statePath, cpPath], () => {
+    const cp = {
+      schema_version: CHECKPOINT_SCHEMA_VERSION,
+      task_id: task.id,
+      phase: task.phase == null ? null : task.phase,
+      plan: task.plan == null ? null : task.plan,
+      wave: task.wave == null ? null : task.wave,
+      status: 'in-progress',
+      started_at: _nowIso(),
+      last_update: _nowIso(),
+      files_touched: [],
+      resume_hint: null,
+    };
+    atomicWriteFileSync(cpPath, JSON.stringify(cp, null, 2));
+
+    
+
+    const current = parseState(fs.readFileSync(statePath, 'utf-8'));
+    current.frontmatter.current_task = task.id;
+    if (task.plan != null) current.frontmatter.current_plan = task.plan;
+    if (task.phase != null) current.frontmatter.current_phase = task.phase;
+    atomicWriteFileSync(statePath, serializeState(current));
+    return cp;
+  });
+}
+
+function readCheckpoint(taskId, cwd = process.cwd()) {
+  const p = checkpointPath(taskId, cwd);
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function writeCheckpoint(taskId, partial, cwd = process.cwd()) {
+  if (typeof taskId !== 'string' || taskId.length === 0) {
+    throw new NubosPilotError(
+      'checkpoint-invalid-task-id',
+      'writeCheckpoint requires a non-empty taskId',
+      { taskId },
+    );
+  }
+  const cpPath = checkpointPath(taskId, cwd);
+  fs.mkdirSync(path.dirname(cpPath), { recursive: true });
+  return withFileLock(cpPath, () => {
+    let existing = {};
+    try {
+      existing = JSON.parse(fs.readFileSync(cpPath, 'utf-8'));
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') throw err;
+    }
+    const merged = {
+      ...existing,
+      ...(partial || {}),
+      schema_version: CHECKPOINT_SCHEMA_VERSION, 
+      last_update: _nowIso(),
+    };
+    atomicWriteFileSync(cpPath, JSON.stringify(merged, null, 2));
+    return merged;
+  });
+}
+
+function deleteCheckpoint(taskId, cwd = process.cwd()) {
+  const p = checkpointPath(taskId, cwd);
+  try {
+    fs.unlinkSync(p);
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') throw err;
+  }
+}
+
+function listCheckpoints(cwd = process.cwd()) {
+  const dir = path.join(projectStateDir(cwd), 'checkpoints');
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => path.join(dir, f))
+      .sort();
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+module.exports = {
+  CHECKPOINT_SCHEMA_VERSION,
+  checkpointPath,
+  startTask,
+  writeCheckpoint,
+  readCheckpoint,
+  deleteCheckpoint,
+  listCheckpoints,
+};

package/lib/checkpoint.test.cjs

@@ -0,0 +1,184 @@
+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 checkpoint = require('./checkpoint.cjs');
+const { readState } = require('./state.cjs');
+
+const MIN_STATE = `---
+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
+---
+
+# Project State
+`;
+
+const _sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-cp-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), MIN_STATE, 'utf-8');
+  _sandboxes.push(root);
+  return root;
+}
+
+after(() => {
+  while (_sandboxes.length) {
+    const r = _sandboxes.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('CP-1: exports CHECKPOINT_SCHEMA_VERSION = 1 + the documented 6 functions', () => {
+  assert.equal(checkpoint.CHECKPOINT_SCHEMA_VERSION, 1);
+  for (const fn of [
+    'startTask',
+    'writeCheckpoint',
+    'readCheckpoint',
+    'deleteCheckpoint',
+    'listCheckpoints',
+    'checkpointPath',
+  ]) {
+    assert.equal(typeof checkpoint[fn], 'function', `missing export: ${fn}`);
+  }
+});
+
+test('CP-2: checkpointPath resolves to .nubos-pilot/checkpoints/<id>.json', () => {
+  const root = makeSandbox();
+  const p = checkpoint.checkpointPath('06-01-T01', root);
+  assert.equal(p, path.join(root, '.nubos-pilot', 'checkpoints', '06-01-T01.json'));
+});
+
+test('CP-3: startTask writes checkpoint file with D-07 schema fields', () => {
+  const root = makeSandbox();
+  const cp = checkpoint.startTask({ id: '06-01-T01', phase: 6, plan: '06-01', wave: 1 }, root);
+  const onDisk = JSON.parse(fs.readFileSync(checkpoint.checkpointPath('06-01-T01', root), 'utf-8'));
+  assert.equal(onDisk.schema_version, 1);
+  assert.equal(onDisk.task_id, '06-01-T01');
+  assert.equal(onDisk.phase, 6);
+  assert.equal(onDisk.plan, '06-01');
+  assert.equal(onDisk.wave, 1);
+  assert.equal(onDisk.status, 'in-progress');
+  assert.match(onDisk.started_at, /^\d{4}-\d{2}-\d{2}T/);
+  assert.deepEqual(onDisk.files_touched, []);
+  assert.equal(onDisk.resume_hint, null);
+
+  assert.equal(cp.task_id, onDisk.task_id);
+});
+
+test('CP-4: startTask updates STATE.md current_task/current_plan/current_phase atomically with checkpoint (D-08)', () => {
+  const root = makeSandbox();
+  checkpoint.startTask({ id: '06-01-T02', phase: 6, plan: '06-01', wave: 1 }, root);
+  const state = readState(root);
+  assert.equal(state.frontmatter.current_task, '06-01-T02');
+  assert.equal(state.frontmatter.current_plan, '06-01');
+  assert.equal(state.frontmatter.current_phase, 6);
+});
+
+test('CP-5: startTask creates checkpoints/ directory if missing', () => {
+  const root = makeSandbox();
+
+  assert.equal(fs.existsSync(path.join(root, '.nubos-pilot', 'checkpoints')), false);
+  checkpoint.startTask({ id: '06-01-T03', phase: 6, plan: '06-01', wave: 1 }, root);
+  assert.equal(fs.existsSync(path.join(root, '.nubos-pilot', 'checkpoints')), true);
+});
+
+test('CP-6: readCheckpoint returns parsed JSON for an existing checkpoint', () => {
+  const root = makeSandbox();
+  checkpoint.startTask({ id: '06-01-T04', phase: 6, plan: '06-01', wave: 1 }, root);
+  const cp = checkpoint.readCheckpoint('06-01-T04', root);
+  assert.equal(cp.task_id, '06-01-T04');
+  assert.equal(cp.schema_version, 1);
+});
+
+test('CP-7: readCheckpoint returns null for nonexistent task (ENOENT graceful)', () => {
+  const root = makeSandbox();
+  assert.equal(checkpoint.readCheckpoint('06-01-T99', root), null);
+});
+
+test('CP-8: writeCheckpoint merges partial patch and bumps last_update', async () => {
+  const root = makeSandbox();
+  checkpoint.startTask({ id: '06-01-T05', phase: 6, plan: '06-01', wave: 1 }, root);
+  const before = checkpoint.readCheckpoint('06-01-T05', root);
+
+  await new Promise((r) => setTimeout(r, 5));
+  checkpoint.writeCheckpoint('06-01-T05', {
+    files_touched: ['lib/git.cjs'],
+    resume_hint: 'continue from line 42',
+  }, root);
+  const after = checkpoint.readCheckpoint('06-01-T05', root);
+  assert.deepEqual(after.files_touched, ['lib/git.cjs']);
+  assert.equal(after.resume_hint, 'continue from line 42');
+  assert.equal(after.task_id, '06-01-T05'); 
+  assert.equal(after.schema_version, 1);    
+  assert.notEqual(after.last_update, before.last_update);
+});
+
+test('CP-9: writeCheckpoint on missing checkpoint creates a new one with schema_version=1', () => {
+  const root = makeSandbox();
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'checkpoints'), { recursive: true });
+  checkpoint.writeCheckpoint('06-01-T06', { task_id: '06-01-T06', status: 'in-progress' }, root);
+  const cp = checkpoint.readCheckpoint('06-01-T06', root);
+  assert.equal(cp.schema_version, 1);
+  assert.equal(cp.task_id, '06-01-T06');
+});
+
+test('CP-10: deleteCheckpoint removes file', () => {
+  const root = makeSandbox();
+  checkpoint.startTask({ id: '06-01-T07', phase: 6, plan: '06-01', wave: 1 }, root);
+  checkpoint.deleteCheckpoint('06-01-T07', root);
+  assert.equal(checkpoint.readCheckpoint('06-01-T07', root), null);
+});
+
+test('CP-11: deleteCheckpoint on nonexistent file is a graceful no-op (ENOENT swallowed)', () => {
+  const root = makeSandbox();
+  assert.doesNotThrow(() => checkpoint.deleteCheckpoint('06-01-T99', root));
+});
+
+test('CP-12: listCheckpoints returns sorted absolute paths; empty on missing dir', () => {
+  const root = makeSandbox();
+  assert.deepEqual(checkpoint.listCheckpoints(root), []);
+  checkpoint.startTask({ id: '06-01-T09', phase: 6, plan: '06-01', wave: 1 }, root);
+  checkpoint.startTask({ id: '06-01-T08', phase: 6, plan: '06-01', wave: 1 }, root);
+  const list = checkpoint.listCheckpoints(root);
+  assert.equal(list.length, 2);
+
+  assert.ok(list[0].endsWith('06-01-T08.json'));
+  assert.ok(list[1].endsWith('06-01-T09.json'));
+});
+
+test('CP-13: startTask serializes concurrent writes — final STATE matches one of the writers, no torn JSON', async () => {
+  const root = makeSandbox();
+
+  
+  await Promise.all([
+    Promise.resolve().then(() => checkpoint.startTask({ id: '06-01-T20', phase: 6, plan: '06-01', wave: 1 }, root)),
+    Promise.resolve().then(() => checkpoint.startTask({ id: '06-01-T21', phase: 6, plan: '06-01', wave: 1 }, root)),
+  ]);
+  const state = readState(root);
+
+  assert.ok(['06-01-T20', '06-01-T21'].includes(state.frontmatter.current_task));
+
+  const cp20 = checkpoint.readCheckpoint('06-01-T20', root);
+  const cp21 = checkpoint.readCheckpoint('06-01-T21', root);
+  assert.equal(cp20.task_id, '06-01-T20');
+  assert.equal(cp21.task_id, '06-01-T21');
+});