nubos-pilot 0.1.0

package/lib/frontmatter.test.cjs

@@ -0,0 +1,177 @@
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+test('FM-A1: unquoted string + boolean scalars', () => {
+  const raw = '---\nphase: 03\nautonomous: true\n---\nbody';
+  const { frontmatter, body } = extractFrontmatter(raw);
+  assert.equal(frontmatter.phase, '03');
+  assert.equal(frontmatter.autonomous, true);
+  assert.equal(body, 'body');
+});
+
+test('FM-A2: unquoted numeric scalar → number', () => {
+  const raw = '---\nwave: 1\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.equal(frontmatter.wave, 1);
+  assert.equal(typeof frontmatter.wave, 'number');
+});
+
+test('FM-A3: empty and tilde → null', () => {
+  const raw = '---\nnullable:\nanother: ~\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.equal(frontmatter.nullable, null);
+  assert.equal(frontmatter.another, null);
+});
+
+test('FM-A4: missing frontmatter block → empty object, body === raw', () => {
+  const raw = 'no frontmatter here\njust body\n';
+  const { frontmatter, body } = extractFrontmatter(raw);
+  assert.deepEqual(frontmatter, {});
+  assert.equal(body, raw);
+});
+
+test('FM-B1: double-quoted value with embedded colon', () => {
+  const raw = '---\nkey: "value: with colon"\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.equal(frontmatter.key, 'value: with colon');
+});
+
+test('FM-B2: single-quoted value', () => {
+  const raw = "---\nkey: 'single-quoted'\n---\n";
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.equal(frontmatter.key, 'single-quoted');
+});
+
+test('FM-C1: inline array parses to JS array, not literal string (RESEARCH Pitfall 2)', () => {
+  const raw = '---\ndepends_on: [T-02, T-03]\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.ok(Array.isArray(frontmatter.depends_on));
+  assert.equal(frontmatter.depends_on.length, 2);
+  assert.deepEqual(frontmatter.depends_on, ['T-02', 'T-03']);
+});
+
+test('FM-C2: empty inline array', () => {
+  const raw = '---\nempty: []\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.ok(Array.isArray(frontmatter.empty));
+  assert.equal(frontmatter.empty.length, 0);
+});
+
+test('FM-C3: quote-aware comma split inside inline array', () => {
+  const raw = '---\nquoted: ["a, b", "c"]\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.deepEqual(frontmatter.quoted, ['a, b', 'c']);
+});
+
+test('FM-D1: nested must_haves with truths + artifacts round-trips to structured JS', () => {
+  const raw = [
+    '---',
+    'must_haves:',
+    '  truths:',
+    '    - "first truth"',
+    '    - "second truth"',
+    '  artifacts:',
+    '    - path: lib/plan.cjs',
+    '      provides: "parser"',
+    '      exports: ["parsePlan", "listPlans"]',
+    '---',
+    'body',
+  ].join('\n');
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.ok(frontmatter.must_haves, 'must_haves key present');
+  assert.deepEqual(frontmatter.must_haves.truths, ['first truth', 'second truth']);
+  assert.ok(Array.isArray(frontmatter.must_haves.artifacts));
+  assert.equal(frontmatter.must_haves.artifacts.length, 1);
+  assert.equal(frontmatter.must_haves.artifacts[0].path, 'lib/plan.cjs');
+  assert.equal(frontmatter.must_haves.artifacts[0].provides, 'parser');
+  assert.deepEqual(frontmatter.must_haves.artifacts[0].exports, ['parsePlan', 'listPlans']);
+});
+
+test('FM-E1: bullet list under key → array of strings', () => {
+  const raw = '---\nfiles_modified:\n  - lib/a.cjs\n  - lib/b.cjs\n---\n';
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.deepEqual(frontmatter.files_modified, ['lib/a.cjs', 'lib/b.cjs']);
+});
+
+test('FM-F1: unclosed quoted string → NubosPilotError frontmatter-parse-error', () => {
+  const raw = '---\nkey: "unclosed\n---\n';
+  let thrown = null;
+  try {
+    extractFrontmatter(raw);
+  } catch (err) {
+    thrown = err;
+  }
+  assert.ok(thrown, 'expected throw on unclosed quote');
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'frontmatter-parse-error');
+  assert.ok(thrown.details, 'details object present');
+  assert.equal(typeof thrown.details.line, 'number');
+  assert.equal(typeof thrown.details.snippet, 'string');
+});
+
+test('FM-F2: tab indent in nested block → NubosPilotError frontmatter-parse-error', () => {
+  const raw = '---\nmust_haves:\n\ttruths:\n\t\t- "bad tabs"\n---\n';
+  let thrown = null;
+  try {
+    extractFrontmatter(raw);
+  } catch (err) {
+    thrown = err;
+  }
+  assert.ok(thrown, 'expected throw on tab-indented nested block');
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'frontmatter-parse-error');
+});
+
+test('FM-G1: nested must_haves (truths/artifacts/key_links) from a real plan parses cleanly', () => {
+
+  
+  const raw = [
+    '---',
+    'phase: 03',
+    'plan: 01',
+    'type: execute',
+    'wave: 0',
+    'depends_on: []',
+    'files_modified:',
+    '  - lib/frontmatter.cjs',
+    '  - lib/frontmatter.test.cjs',
+    'autonomous: true',
+    'requirements: [LIB-06, LIB-07]',
+    'must_haves:',
+    '  truths:',
+    '    - "lib/frontmatter.cjs exists and exports extractFrontmatter"',
+    '    - "Nested frontmatter round-trips as a structured JS object"',
+    '    - "Inline arrays parse as JS arrays"',
+    '    - "Quoted scalars containing colon parse correctly"',
+    '  artifacts:',
+    '    - path: lib/frontmatter.cjs',
+    '      provides: "hand-rolled YAML frontmatter parser"',
+    '      exports: ["extractFrontmatter"]',
+    '    - path: lib/frontmatter.test.cjs',
+    '      provides: "node:test suite"',
+    '      contains: "node:test"',
+    '  key_links:',
+    '    - from: "lib/frontmatter.cjs"',
+    '      to: "Node builtins only"',
+    '      via: "require(node:fs) / no other requires"',
+    '      pattern: "require"',
+    '---',
+    '<objective>body</objective>',
+  ].join('\n');
+  const { frontmatter } = extractFrontmatter(raw);
+  assert.equal(frontmatter.phase, '03');
+  assert.ok(Array.isArray(frontmatter.depends_on));
+  assert.equal(frontmatter.depends_on.length, 0);
+  assert.ok(Array.isArray(frontmatter.files_modified));
+  assert.equal(frontmatter.files_modified.length, 2);
+  assert.ok(Array.isArray(frontmatter.requirements));
+  assert.deepEqual(frontmatter.requirements, ['LIB-06', 'LIB-07']);
+  assert.ok(frontmatter.must_haves, 'must_haves present');
+  assert.ok(Array.isArray(frontmatter.must_haves.truths));
+  assert.ok(frontmatter.must_haves.truths.length >= 4, 'truths has ≥4 entries');
+  assert.ok(Array.isArray(frontmatter.must_haves.artifacts));
+  assert.equal(frontmatter.must_haves.artifacts[0].path, 'lib/frontmatter.cjs');
+  assert.ok(Array.isArray(frontmatter.must_haves.key_links));
+  assert.equal(frontmatter.must_haves.key_links[0].from, 'lib/frontmatter.cjs');
+});

package/lib/gaps.cjs

@@ -0,0 +1,197 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { NubosPilotError, findProjectRoot } = require('./core.cjs');
+const { addPhase, insertPhaseAfter, parseRoadmap } = require('./roadmap.cjs');
+
+const MAX_AUDIT_BYTES = 1024 * 1024;
+
+function _projectRoot(cwd) {
+  try {
+    return findProjectRoot(cwd);
+  } catch (err) {
+    if (err && err.code === 'not-in-project') return path.resolve(cwd);
+    throw err;
+  }
+}
+
+function _phasesDir(cwd) {
+  const root = _projectRoot(cwd);
+
+  const primary = path.join(root, '.nubos-pilot', 'phases');
+  if (fs.existsSync(primary)) return primary;
+  return path.join(root, '.planning', 'phases');
+}
+
+function _parseDirNumber(name) {
+  const m = name.match(/^(\d+(?:\.\d+)?)-/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : null;
+}
+
+function scanVerifications(_milestoneId, cwd = process.cwd()) {
+  const dir = _phasesDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir).sort();
+  const gaps = [];
+  for (const entry of entries) {
+    const sourcePhase = _parseDirNumber(entry);
+    if (sourcePhase == null) continue;
+
+    
+    const pad = entry.split('-')[0];
+    const candidates = [
+      path.join(dir, entry, pad + '-VERIFICATION.md'),
+      path.join(dir, entry, 'VERIFICATION.md'),
+    ];
+    const verPath = candidates.find((p) => fs.existsSync(p));
+    if (!verPath) continue;
+    const body = fs.readFileSync(verPath, 'utf-8');
+    for (const m of body.matchAll(/^## Gap:\s*(.+)$/gm)) {
+      gaps.push({
+        source_phase: sourcePhase,
+        gap_type: 'explicit',
+        description: m[1].trim(),
+        severity: 'major',
+      });
+    }
+    for (const m of body.matchAll(/^- \[ \]\s*(.+)$/gm)) {
+      gaps.push({
+        source_phase: sourcePhase,
+        gap_type: 'unchecked-box',
+        description: m[1].trim(),
+        severity: 'minor',
+      });
+    }
+    for (const m of body.matchAll(/^(.*(?:❌|FAIL).*)$/gm)) {
+      gaps.push({
+        source_phase: sourcePhase,
+        gap_type: 'fail-marker',
+        description: m[1].trim(),
+        severity: 'critical',
+      });
+    }
+  }
+  return gaps;
+}
+
+function parseAuditFile(filepath, cwd = process.cwd()) {
+  const root = _projectRoot(cwd);
+  const resolved = path.resolve(cwd, filepath);
+
+  
+
+  const inside = resolved === root || resolved.startsWith(root + path.sep);
+  if (!inside) {
+    throw new NubosPilotError(
+      'gaps-invalid-audit-path',
+      'audit file must be inside the project root',
+      { path: filepath, resolved, projectRoot: root },
+    );
+  }
+  let stat;
+  try { stat = fs.statSync(resolved); } catch (err) {
+    throw new NubosPilotError(
+      'gaps-audit-not-found',
+      'audit file not found',
+      { path: resolved, cause: err && err.code },
+    );
+  }
+  if (stat.size > MAX_AUDIT_BYTES) {
+    throw new NubosPilotError(
+      'gaps-audit-too-large',
+      'audit file exceeds ' + MAX_AUDIT_BYTES + ' byte cap',
+      { path: resolved, size: stat.size },
+    );
+  }
+  const body = fs.readFileSync(resolved, 'utf-8');
+
+  const sections = body.split(/^## Gap:\s*/gm).slice(1);
+  const gaps = [];
+  for (const section of sections) {
+    const [titleLine, ...rest] = section.split('\n');
+    const title = titleLine.trim();
+    const m = rest.join('\n').match(/\*\*Source phase:\*\*\s*(\d+(?:\.\d+)?)/m);
+    if (!m) {
+      throw new NubosPilotError(
+        'gaps-missing-source-phase',
+        '## Gap: section missing "**Source phase:** N" line',
+        { path: resolved, gapTitle: title },
+      );
+    }
+    gaps.push({
+      source_phase: Number(m[1]),
+      gap_type: 'explicit',
+      description: title,
+      severity: 'major',
+    });
+  }
+  return gaps;
+}
+
+function _currentMilestoneId(cwd) {
+  try {
+    const { readState } = require('./state.cjs');
+    const st = readState(cwd);
+    if (st && st.frontmatter && st.frontmatter.milestone) {
+      return String(st.frontmatter.milestone);
+    }
+  } catch (_err) {
+
+  }
+  const YAML = require('yaml');
+  const { projectStateDir } = require('./core.cjs');
+  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 — cannot resolve current milestone',
+      { path: yamlPath },
+    );
+  }
+  return String(doc.milestones[0].id);
+}
+
+function gapsToPhases(gaps, opts, cwd = process.cwd()) {
+  const options = opts || {};
+  if (!gaps || gaps.length === 0) return [];
+  const groups = new Map();
+  for (const g of gaps) {
+    if (!groups.has(g.source_phase)) groups.set(g.source_phase, []);
+    groups.get(g.source_phase).push(g);
+  }
+  const created = [];
+  for (const [source, list] of groups) {
+    const phaseDef = {
+      slug: 'gap-fix-phase-' + String(source).replace(/\./g, '-'),
+      name: 'Gap fix for phase ' + source,
+      goal: 'Close ' + list.length + ' gap(s) identified in Phase ' + source + ' VERIFICATION.md / audit',
+      depends_on: [source], 
+      requirements: [],
+      success_criteria: [],
+      status: 'pending',
+      plans: [],
+    };
+    const result = options.insertAfter != null
+      ? insertPhaseAfter(options.insertAfter, phaseDef, cwd)
+      : addPhase(_currentMilestoneId(cwd), phaseDef, cwd);
+    created.push(result);
+  }
+  return created;
+}
+
+module.exports = {
+  scanVerifications,
+  parseAuditFile,
+  gapsToPhases,
+
+  _currentMilestoneId,
+};
+
+void parseRoadmap;

package/lib/gaps.test.cjs

@@ -0,0 +1,200 @@
+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 gaps = require('./gaps.cjs');
+const roadmap = require('./roadmap.cjs');
+
+const FIXTURE_VERIFICATION = fs.readFileSync(
+  path.join(__dirname, '..', 'tests', 'fixtures', 'gaps', 'verification-sample.md'),
+  'utf-8',
+);
+const FIXTURE_AUDIT = fs.readFileSync(
+  path.join(__dirname, '..', 'tests', 'fixtures', 'gaps', 'audit-from-file.md'),
+  'utf-8',
+);
+
+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: [] },
+          { number: 8, name: 'Eight', slug: 'eight', goal: '', depends_on: [7], requirements: [], success_criteria: [], status: 'pending', plans: [] },
+        ],
+      },
+    ],
+  };
+}
+
+afterEach(cleanupAll);
+
+test('GAP-1: scanVerifications returns gap objects with required shape', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': FIXTURE_VERIFICATION });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  assert.ok(Array.isArray(result));
+  assert.ok(result.length > 0);
+  for (const g of result) {
+    assert.equal(typeof g.source_phase, 'number');
+    assert.equal(typeof g.gap_type, 'string');
+    assert.equal(typeof g.description, 'string');
+    assert.ok(['critical', 'major', 'minor'].includes(g.severity));
+  }
+});
+
+test('GAP-2: explicit ## Gap: heading produces gap_type=explicit', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': FIXTURE_VERIFICATION });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  const explicit = result.filter((g) => g.gap_type === 'explicit');
+  assert.ok(explicit.length >= 1);
+  assert.ok(explicit[0].description.toLowerCase().includes('jwt'));
+});
+
+test('GAP-3: unchecked checkbox line produces gap_type=unchecked-box', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': FIXTURE_VERIFICATION });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  const boxes = result.filter((g) => g.gap_type === 'unchecked-box');
+  assert.equal(boxes.length, 2);
+});
+
+test('GAP-4: ❌ or FAIL marker produces gap_type=fail-marker', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': FIXTURE_VERIFICATION });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  const fails = result.filter((g) => g.gap_type === 'fail-marker');
+  assert.ok(fails.length >= 2);
+});
+
+test('GAP-5: source_phase extracted from directory name NN-slug (semantic, not positional)', () => {
+
+  
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', { '03-VERIFICATION.md': '## Gap: from three\n' });
+  seedPhaseDir(sandbox, 7, 'bar', { '07-VERIFICATION.md': '## Gap: from seven\n' });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  const three = result.find((g) => /three/.test(g.description));
+  const seven = result.find((g) => /seven/.test(g.description));
+  assert.equal(three.source_phase, 3);
+  assert.equal(seven.source_phase, 7);
+});
+
+test('GAP-6: VERIFICATION.md with no gap signals returns empty array', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'foo', {
+    '03-VERIFICATION.md': '# Verification\n\nAll checks passed.\n- [x] Done\n',
+  });
+  const result = gaps.scanVerifications('v1.0', sandbox);
+  assert.deepEqual(result, []);
+});
+
+test('GAP-7: parseAuditFile rejects paths outside project root (ASVS V12)', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  assert.throws(
+    () => gaps.parseAuditFile('/etc/passwd', sandbox),
+    (err) => err.name === 'NubosPilotError' && err.code === 'gaps-invalid-audit-path',
+  );
+});
+
+test('GAP-8: parseAuditFile parses ## Gap: sections and reads Source phase line', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const auditPath = path.join(sandbox, 'audit.md');
+  fs.writeFileSync(auditPath, FIXTURE_AUDIT);
+  const result = gaps.parseAuditFile(auditPath, sandbox);
+  assert.equal(result.length, 2);
+  for (const g of result) {
+    assert.equal(g.source_phase, 7);
+    assert.equal(g.gap_type, 'explicit');
+  }
+});
+
+test('GAP-9: parseAuditFile throws gaps-missing-source-phase when line missing', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const auditPath = path.join(sandbox, 'bad-audit.md');
+  fs.writeFileSync(auditPath, '# Audit\n\n## Gap: missing source info\n\nNo source phase here.\n');
+  assert.throws(
+    () => gaps.parseAuditFile(auditPath, sandbox),
+    (err) => err.name === 'NubosPilotError' && err.code === 'gaps-missing-source-phase',
+  );
+});
+
+test('GAP-10: gapsToPhases({insertAfter: null}) appends via addPhase; depends_on=[source]', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const result = gaps.gapsToPhases(
+    [{ source_phase: 7, gap_type: 'explicit', description: 'x', severity: 'major' }],
+    { insertAfter: null },
+    sandbox,
+  );
+  assert.equal(result.length, 1);
+
+  const ms = roadmap.parseRoadmap(sandbox);
+  const added = ms.phases.find((p) => p.number === '9');
+  assert.ok(added, 'new phase appended at number 9');
+  assert.ok(added.depends_on && added.depends_on.includes('7'));
+});
+
+test('GAP-11: gapsToPhases({insertAfter: 7}) uses insertPhaseAfter; phase 8 depends_on untouched', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  gaps.gapsToPhases(
+    [{ source_phase: 7, gap_type: 'explicit', description: 'x', severity: 'major' }],
+    { insertAfter: 7 },
+    sandbox,
+  );
+  const parsed = roadmap.parseRoadmap(sandbox);
+  const decimal = parsed.phases.find((p) => p.number === '7.1');
+  const eight = parsed.phases.find((p) => p.number === '8');
+  assert.ok(decimal, 'decimal phase 7.1 exists');
+  assert.ok(eight.depends_on && eight.depends_on.includes('7'), 'phase 8 depends_on still [7]');
+});
+
+test('GAP-12: Pitfall 5 — semantic source_phase, NOT positional insertAfter, drives depends_on', () => {
+
+  
+
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  gaps.gapsToPhases(
+    [{ source_phase: 7, gap_type: 'explicit', description: 'semantic test', severity: 'major' }],
+    { insertAfter: 8 },
+    sandbox,
+  );
+  const parsed = roadmap.parseRoadmap(sandbox);
+
+  const created = parsed.phases.find((p) => p.number === '8.1');
+  assert.ok(created, 'decimal 8.1 created');
+
+  assert.ok(
+    created.depends_on && created.depends_on.includes('7'),
+    'depends_on includes semantic source 7, not positional base 8',
+  );
+});
+
+test('GAP-13: empty gaps array returns [] and performs no roadmap mutation', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const yamlPath = path.join(sandbox, '.nubos-pilot', 'roadmap.yaml');
+  const before = fs.readFileSync(yamlPath, 'utf-8');
+  const result = gaps.gapsToPhases([], { insertAfter: null }, sandbox);
+  assert.deepEqual(result, []);
+  const after = fs.readFileSync(yamlPath, 'utf-8');
+  assert.equal(before, after, 'roadmap.yaml untouched for empty gaps');
+});