nubos-pilot 0.1.0

package/lib/core.cjs

@@ -0,0 +1,165 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+class NubosPilotError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'NubosPilotError';
+    this.code = code;
+    this.details = details;
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, NubosPilotError);
+    }
+  }
+}
+
+function atomicWriteFileSync(filePath, content, encoding = 'utf-8') {
+  const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(tmp, content, encoding);
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    fs.writeFileSync(filePath, content, encoding);
+  }
+}
+
+const _heldLocks = new Set();
+let _exitHandlerRegistered = false;
+
+function _ensureExitHandler() {
+  if (_exitHandlerRegistered) return;
+  _exitHandlerRegistered = true;
+  process.on('exit', () => {
+    for (const p of _heldLocks) {
+      try { fs.unlinkSync(p); } catch {}
+    }
+  });
+}
+
+function _isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    if (err && err.code === 'EPERM') return true;
+    return true;
+  }
+}
+
+function _sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {  }
+  }
+}
+
+function withFileLock(filePath, fn, opts) {
+  const { timeoutMs = 10000, pollMs = 50, staleMs = 30000 } = opts || {};
+  try { fs.mkdirSync(path.dirname(filePath), { recursive: true }); } catch {}
+  const lockPath = `${filePath}.lock`;
+  const selfHost = os.hostname();
+  const startedAt = Date.now();
+  let lastMeta = null;
+
+  while (true) {
+    try {
+      const payload = JSON.stringify({
+        pid: process.pid,
+        hostname: selfHost,
+        acquiredAt: new Date().toISOString(),
+      });
+      fs.writeFileSync(lockPath, payload, { flag: 'wx' });
+      _ensureExitHandler();
+      _heldLocks.add(lockPath);
+      try {
+        return fn();
+      } finally {
+        _heldLocks.delete(lockPath);
+        try { fs.unlinkSync(lockPath); } catch {}
+      }
+    } catch (err) {
+      if (!err || err.code !== 'EEXIST') {
+        throw err;
+      }
+      let meta = null;
+      let stat = null;
+      try {
+        meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+      } catch {}
+      try {
+        stat = fs.statSync(lockPath);
+      } catch {}
+      if (meta) lastMeta = meta;
+      if (stat && Date.now() - stat.mtimeMs > staleMs) {
+        if (meta && meta.hostname && meta.hostname !== selfHost) {
+
+        } else if (meta && !_isPidAlive(meta.pid)) {
+          try { fs.unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new NubosPilotError(
+          'lock-timeout',
+          `Could not acquire lock on ${filePath} within ${timeoutMs}ms`,
+          { lockPath, holder: lastMeta },
+        );
+      }
+      _sleepSync(pollMs);
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new NubosPilotError(
+          'lock-timeout',
+          `Could not acquire lock on ${filePath} within ${timeoutMs}ms`,
+          { lockPath, holder: lastMeta },
+        );
+      }
+    }
+  }
+}
+
+function withFileLocks(paths, fn, opts) {
+  const sorted = [...paths].sort();
+  function acquire(idx) {
+    if (idx >= sorted.length) return fn();
+    return withFileLock(sorted[idx], () => acquire(idx + 1), opts);
+  }
+  return acquire(0);
+}
+
+function findProjectRoot(cwd = process.cwd()) {
+  let dir = path.resolve(cwd);
+  const root = path.parse(dir).root;
+  while (true) {
+    const candidate = path.join(dir, '.nubos-pilot');
+    try {
+      if (fs.statSync(candidate).isDirectory()) return dir;
+    } catch {  }
+    if (dir === root) {
+      throw new NubosPilotError(
+        'not-in-project',
+        `No .nubos-pilot/ ancestor of ${cwd}`,
+        { startedFrom: cwd },
+      );
+    }
+    dir = path.dirname(dir);
+  }
+}
+
+function projectStateDir(cwd = process.cwd()) {
+  return path.join(findProjectRoot(cwd), '.nubos-pilot');
+}
+
+module.exports = {
+  atomicWriteFileSync,
+  withFileLock,
+  withFileLocks,
+  findProjectRoot,
+  projectStateDir,
+  NubosPilotError,
+};

package/lib/core.test.cjs

@@ -0,0 +1,405 @@
+const core = require('./core.cjs');
+
+const { test, before, beforeEach, afterEach } = 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 crypto = require('node:crypto');
+
+let DEAD_PID_AVAILABLE = true;
+const DEAD_PID = 99999999;
+
+before(() => {
+  try {
+    process.kill(DEAD_PID, 0);
+    DEAD_PID_AVAILABLE = false;
+  } catch (err) {
+    DEAD_PID_AVAILABLE = err.code === 'ESRCH';
+  }
+});
+
+function mkSandbox() {
+  const dir = path.join(os.tmpdir(), 'nubos-pilot-test-' + crypto.randomBytes(8).toString('hex'));
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function rmSandbox(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+}
+
+test('NubosPilotError sets code, message, details, name and is instanceof Error', () => {
+  const e = new core.NubosPilotError('lock-timeout', 'msg', { extra: 1 });
+  assert.equal(e.code, 'lock-timeout');
+  assert.equal(e.message, 'msg');
+  assert.deepEqual(e.details, { extra: 1 });
+  assert.equal(e.name, 'NubosPilotError');
+  assert.ok(e instanceof Error);
+});
+
+test('A1 atomicWriteFileSync writes content round-trip-identical', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'a.txt');
+    const content = 'hello world ' + crypto.randomBytes(4).toString('hex');
+    core.atomicWriteFileSync(target, content);
+    const read = fs.readFileSync(target, 'utf-8');
+    assert.equal(read, content);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('A2 atomicWriteFileSync leaves no *.tmp leftover after success', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'b.txt');
+    core.atomicWriteFileSync(target, 'x');
+    const entries = fs.readdirSync(dir);
+    const tmps = entries.filter((n) => n.endsWith('.tmp'));
+    assert.deepEqual(tmps, []);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('A3 atomicWriteFileSync overwrites existing file', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'c.txt');
+    fs.writeFileSync(target, 'old');
+    core.atomicWriteFileSync(target, 'new');
+    assert.equal(fs.readFileSync(target, 'utf-8'), 'new');
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('A4 tmp filename pattern is <target>.<pid>.<12-hex>.tmp (observed via writeFileSync spy)', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'd.txt');
+    const origWrite = fs.writeFileSync;
+    const seenPaths = [];
+    fs.writeFileSync = function (p, ...rest) {
+      seenPaths.push(String(p));
+      return origWrite.apply(this, [p, ...rest]);
+    };
+    try {
+      core.atomicWriteFileSync(target, 'payload');
+    } finally {
+      fs.writeFileSync = origWrite;
+    }
+    const tmpCandidates = seenPaths.filter((p) => p !== target && p.startsWith(target + '.') && p.endsWith('.tmp'));
+    assert.ok(tmpCandidates.length >= 1, 'expected at least one tmp write call; saw: ' + JSON.stringify(seenPaths));
+    const tmp = tmpCandidates[0];
+    const suffix = tmp.slice(target.length + 1);
+    const match = /^(\d+)\.([0-9a-f]{12})\.tmp$/.exec(suffix);
+    assert.ok(match, 'tmp suffix must be <pid>.<12-hex>.tmp, got: ' + suffix);
+    assert.equal(Number(match[1]), process.pid);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('A5 two parallel atomicWriteFileSync calls to same target: no collision, final content is one of the payloads', async () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'e.txt');
+    const a = 'A'.repeat(256);
+    const b = 'B'.repeat(256);
+    await Promise.all([
+      Promise.resolve().then(() => core.atomicWriteFileSync(target, a)),
+      Promise.resolve().then(() => core.atomicWriteFileSync(target, b)),
+    ]);
+    const final = fs.readFileSync(target, 'utf-8');
+    assert.ok(final === a || final === b, 'final must equal one payload verbatim, got length ' + final.length);
+    const entries = fs.readdirSync(dir);
+    const tmps = entries.filter((n) => n.endsWith('.tmp'));
+    assert.deepEqual(tmps, [], 'no tmp leftovers after parallel writes');
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L1 withFileLock creates lockfile during fn and removes it after', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'f.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    let sawLock = false;
+    core.withFileLock(target, () => {
+      sawLock = fs.existsSync(lockPath);
+    });
+    assert.equal(sawLock, true);
+    assert.equal(fs.existsSync(lockPath), false);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L2 lockfile content is valid JSON {pid, hostname, acquiredAt ISO-8601}', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'g.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    let meta;
+    core.withFileLock(target, () => {
+      meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+    });
+    assert.equal(typeof meta.pid, 'number');
+    assert.equal(typeof meta.hostname, 'string');
+    assert.ok(/^\d{4}-/.test(meta.acquiredAt), 'acquiredAt must be ISO-8601, got ' + meta.acquiredAt);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L3 re-entrant withFileLock on same path sequences (second waits for first)', async () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'h.txt');
+    fs.writeFileSync(target, '');
+    const events = [];
+    const first = new Promise((resolve) => {
+      setImmediate(() => {
+        core.withFileLock(target, () => {
+          events.push('first-start');
+          const until = Date.now() + 80;
+          while (Date.now() < until) {  }
+          events.push('first-end');
+        }, { timeoutMs: 2000, pollMs: 10 });
+        resolve();
+      });
+    });
+    const second = new Promise((resolve) => {
+      setImmediate(() => {
+        setTimeout(() => {
+          core.withFileLock(target, () => {
+            events.push('second-start');
+            events.push('second-end');
+          }, { timeoutMs: 2000, pollMs: 10 });
+          resolve();
+        }, 10);
+      });
+    });
+    await Promise.all([first, second]);
+    assert.deepEqual(events, ['first-start', 'first-end', 'second-start', 'second-end']);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L4 lock-timeout throws NubosPilotError with code lock-timeout when held by live local pid', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'i.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      acquiredAt: new Date().toISOString(),
+    }), { flag: 'wx' });
+    try {
+      assert.throws(
+        () => core.withFileLock(target, () => {}, { timeoutMs: 200, pollMs: 20 }),
+        (err) => err instanceof core.NubosPilotError && err.code === 'lock-timeout',
+      );
+    } finally {
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L5 stale lock + dead PID + same hostname → force-acquire', (t) => {
+  if (!DEAD_PID_AVAILABLE) { t.skip('DEAD_PID unexpectedly alive on this host'); return; }
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'j.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: DEAD_PID,
+      hostname: os.hostname(),
+      acquiredAt: new Date(Date.now() - 60000).toISOString(),
+    }));
+    const past = new Date(Date.now() - 60000);
+    fs.utimesSync(lockPath, past, past);
+    let ran = false;
+    core.withFileLock(target, () => { ran = true; }, { timeoutMs: 1000, pollMs: 20, staleMs: 30000 });
+    assert.equal(ran, true);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L6 stale lock + ALIVE PID + same hostname → never force; lock-timeout', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'k.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      acquiredAt: new Date(Date.now() - 60000).toISOString(),
+    }));
+    const past = new Date(Date.now() - 60000);
+    fs.utimesSync(lockPath, past, past);
+    try {
+      assert.throws(
+        () => core.withFileLock(target, () => {}, { timeoutMs: 200, pollMs: 20, staleMs: 30000 }),
+        (err) => err instanceof core.NubosPilotError && err.code === 'lock-timeout',
+      );
+    } finally {
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L7 stale lock + REMOTE hostname → never force; lock-timeout', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'l.txt');
+    fs.writeFileSync(target, '');
+    const lockPath = target + '.lock';
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: DEAD_PID,
+      hostname: '__remote_test_host__',
+      acquiredAt: new Date(Date.now() - 60000).toISOString(),
+    }));
+    const past = new Date(Date.now() - 60000);
+    fs.utimesSync(lockPath, past, past);
+    try {
+      assert.throws(
+        () => core.withFileLock(target, () => {}, { timeoutMs: 200, pollMs: 20, staleMs: 30000 }),
+        (err) => err instanceof core.NubosPilotError && err.code === 'lock-timeout',
+      );
+    } finally {
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('L8 exit-handler registration: process.listenerCount("exit") >= 1 after first withFileLock', () => {
+  const dir = mkSandbox();
+  try {
+    const target = path.join(dir, 'm.txt');
+    fs.writeFileSync(target, '');
+    core.withFileLock(target, () => {});
+    assert.ok(process.listenerCount('exit') >= 1);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('M1 withFileLocks acquires in lexicographic sort order', () => {
+  const dir = mkSandbox();
+  try {
+    const a = path.join(dir, 'a.lock-target');
+    const z = path.join(dir, 'z.lock-target');
+    fs.writeFileSync(a, '');
+    fs.writeFileSync(z, '');
+    const origWrite = fs.writeFileSync;
+    const writes = [];
+    fs.writeFileSync = function (p, ...rest) {
+      writes.push(String(p));
+      return origWrite.apply(this, [p, ...rest]);
+    };
+    try {
+      core.withFileLocks([z, a], () => {});
+    } finally {
+      fs.writeFileSync = origWrite;
+    }
+    const lockWrites = writes.filter((p) => p.endsWith('.lock'));
+    assert.ok(lockWrites.length >= 2, 'expected ≥2 lock writes, got ' + JSON.stringify(lockWrites));
+    assert.ok(lockWrites[0].endsWith('a.lock-target.lock'), 'first lock must be sorted-first: ' + lockWrites[0]);
+    assert.ok(lockWrites[1].endsWith('z.lock-target.lock'), 'second lock must be sorted-second: ' + lockWrites[1]);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('M2 withFileLocks releases in reverse order (lockfiles disappear in reverse)', () => {
+  const dir = mkSandbox();
+  try {
+    const a = path.join(dir, 'a.lock-target');
+    const z = path.join(dir, 'z.lock-target');
+    fs.writeFileSync(a, '');
+    fs.writeFileSync(z, '');
+    const origUnlink = fs.unlinkSync;
+    const unlinks = [];
+    fs.unlinkSync = function (p, ...rest) {
+      unlinks.push(String(p));
+      return origUnlink.apply(this, [p, ...rest]);
+    };
+    try {
+      core.withFileLocks([z, a], () => {});
+    } finally {
+      fs.unlinkSync = origUnlink;
+    }
+    const lockUnlinks = unlinks.filter((p) => p.endsWith('.lock'));
+    assert.ok(lockUnlinks.length >= 2);
+    assert.ok(lockUnlinks[0].endsWith('z.lock-target.lock'), 'first unlink must be reverse-sorted: ' + lockUnlinks[0]);
+    assert.ok(lockUnlinks[1].endsWith('a.lock-target.lock'), 'second unlink must be reverse-sorted: ' + lockUnlinks[1]);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('P1 findProjectRoot returns dir whose child is .nubos-pilot/', () => {
+  const dir = mkSandbox();
+  try {
+    fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+    const root = core.findProjectRoot(dir);
+    assert.equal(fs.realpathSync(root), fs.realpathSync(dir));
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('P2 findProjectRoot walks up from nested subdir', () => {
+  const dir = mkSandbox();
+  try {
+    fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+    const nested = path.join(dir, 'a', 'b', 'c');
+    fs.mkdirSync(nested, { recursive: true });
+    const root = core.findProjectRoot(nested);
+    assert.equal(fs.realpathSync(root), fs.realpathSync(dir));
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('P3 findProjectRoot throws NubosPilotError code=not-in-project when no ancestor', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => core.findProjectRoot(dir),
+      (err) => err instanceof core.NubosPilotError && err.code === 'not-in-project',
+    );
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('P4 projectStateDir returns path.join(root, .nubos-pilot)', () => {
+  const dir = mkSandbox();
+  try {
+    fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+    const stateDir = core.projectStateDir(dir);
+    assert.equal(fs.realpathSync(stateDir), fs.realpathSync(path.join(dir, '.nubos-pilot')));
+  } finally {
+    rmSandbox(dir);
+  }
+});

package/lib/fixtures/README.md

@@ -0,0 +1 @@
+Shared fixtures for Phase 3 parser tests — each plan adds its own subdirectory.

package/lib/fixtures/phase-tree/README.md

@@ -0,0 +1 @@
+Fixtures for phase-directory tests are created in tmpdir per-test; this README exists only to keep the dir tracked.

package/lib/fixtures/plans/cycle/PLAN.md

@@ -0,0 +1,16 @@
+---
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "fixture stub"
+  artifacts: []
+  key_links: []
+---
+
+Cycle fixture: T-01 -> T-03 -> T-02 -> T-01.

package/lib/fixtures/plans/cycle/tasks/T-01.md

@@ -0,0 +1,20 @@
+---
+id: 99-01-T01
+status: pending
+tier: sonnet
+owner: np-executor
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: [T-03]
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "stub"
+  artifacts: []
+  key_links: []
+---
+
+Task T-01 body.

package/lib/fixtures/plans/cycle/tasks/T-02.md

@@ -0,0 +1,20 @@
+---
+id: 99-01-T02
+status: pending
+tier: sonnet
+owner: np-executor
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: [T-01]
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "stub"
+  artifacts: []
+  key_links: []
+---
+
+Task T-02 body.

package/lib/fixtures/plans/cycle/tasks/T-03.md

@@ -0,0 +1,20 @@
+---
+id: 99-01-T03
+status: pending
+tier: sonnet
+owner: np-executor
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: [T-02]
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "stub"
+  artifacts: []
+  key_links: []
+---
+
+Task T-03 body.

package/lib/fixtures/plans/linear/PLAN.md

@@ -0,0 +1,16 @@
+---
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "fixture stub"
+  artifacts: []
+  key_links: []
+---
+
+Linear chain fixture: T-01 -> T-02 -> T-03.

package/lib/fixtures/plans/linear/tasks/T-01.md

@@ -0,0 +1,20 @@
+---
+id: 99-01-T01
+status: pending
+tier: sonnet
+owner: np-executor
+phase: 99
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths:
+    - "stub"
+  artifacts: []
+  key_links: []
+---
+
+Task T-01 body.