nubos-pilot 0.1.0

package/bin/check-workflows.cjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BARE_ASKUSER_RE = /AskUserQuestion/;
+const DIRECT_READ_RE = /(cat\s+\.nubos-pilot|readFileSync\s*\(\s*['"][^'"]*\.nubos-pilot|\bRead\s*\(\s*['"][^'"]*\.nubos-pilot)/;
+
+const BARE_READLINE_RE = /readline\.createInterface/;
+
+const ALLOW_RE = /\$?\(?\s*node\s+np-tools\.cjs\s+\w+/;
+
+const SPAWN_SITE_RE = /(Task\s*\(|Spawn\s+agent=)/;
+const METRICS_RECORD_RE = /np-tools\.cjs\s+metrics\s+record\b/;
+const METRICS_COVERAGE_WINDOW = 30;
+
+const INSTALL_SCRIPT = 'bin/install.js';
+const LIB_INSTALL_DIR = 'lib/install/';
+const INSTALLER_SCAN_PATHS = [INSTALL_SCRIPT, LIB_INSTALL_DIR];
+
+function _walk(dir, acc, opts) {
+  const extFilter = (opts && opts.ext) || ['.md'];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return acc;
+    throw err;
+  }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) _walk(abs, acc, opts);
+    else if (e.isFile() && extFilter.some((x) => e.name.endsWith(x))) acc.push(abs);
+  }
+  return acc;
+}
+
+function _scanFiles(files) {
+  const out = [];
+  for (const file of files) {
+    const raw = fs.readFileSync(file, 'utf-8');
+    const isCode = file.endsWith('.js') || file.endsWith('.cjs') || file.endsWith('.mjs');
+    const lines = raw.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (ALLOW_RE.test(line)) continue;
+      if (BARE_ASKUSER_RE.test(line)) {
+        out.push({ file, line: i + 1, pattern: 'AskUserQuestion' });
+      }
+      if (!isCode && DIRECT_READ_RE.test(line)) {
+        out.push({ file, line: i + 1, pattern: 'direct-read .nubos-pilot' });
+      }
+      if (isCode && BARE_READLINE_RE.test(line)) {
+        out.push({ file, line: i + 1, pattern: 'readline.createInterface' });
+      }
+    }
+  }
+  return out;
+}
+
+function _scanMetricsCoverage(files) {
+  const warnings = [];
+  const FENCE_RE = /^```/;
+  const BASH_FENCE_RE = /^```(\s*$|\s*(bash|sh|shell|zsh)\b)/i;
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const raw = fs.readFileSync(file, 'utf-8');
+    const lines = raw.split(/\r?\n/);
+
+    
+
+    let inAnyFence = false;
+    let inBashFence = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (FENCE_RE.test(line)) {
+        if (inAnyFence) {
+          inAnyFence = false;
+          inBashFence = false;
+        } else {
+          inAnyFence = true;
+          inBashFence = BASH_FENCE_RE.test(line);
+        }
+        continue;
+      }
+      if (!inBashFence) continue;
+      if (!SPAWN_SITE_RE.test(line)) continue;
+      const windowEnd = Math.min(lines.length, i + 1 + METRICS_COVERAGE_WINDOW);
+      const windowBody = lines.slice(i, windowEnd).join('\n');
+      if (!METRICS_RECORD_RE.test(windowBody)) {
+        warnings.push({
+          file,
+          line: i + 1,
+          pattern: 'workflow-missing-metrics',
+          message:
+            'Task/Spawn site without `np-tools.cjs metrics record` within ' +
+            METRICS_COVERAGE_WINDOW +
+            ' lines (D-06).',
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
+function _scan(dir) {
+  return _scanFiles(_walk(dir, [], { ext: ['.md'] }));
+}
+
+function _scanInstallerSurface(cwd) {
+  const root = cwd || process.cwd();
+  const files = [];
+  for (const rel of INSTALLER_SCAN_PATHS) {
+    const abs = path.resolve(root, rel);
+    let st;
+    try { st = fs.statSync(abs); } catch { continue; }
+    if (st.isFile()) files.push(abs);
+    else if (st.isDirectory()) _walk(abs, files, { ext: ['.js', '.cjs', '.mjs'] });
+  }
+  return _scanFiles(files);
+}
+
+function checkWorkflows(dir) {
+  const target = dir || 'nubos-pilot/workflows';
+  const violations = [];
+  const warnings = [];
+  let workflowFiles = [];
+  try {
+    const st = fs.statSync(target);
+    if (st.isDirectory()) {
+      workflowFiles = _walk(target, [], { ext: ['.md'] });
+      violations.push(..._scanFiles(workflowFiles));
+      warnings.push(..._scanMetricsCoverage(workflowFiles));
+    }
+  } catch {  }
+  violations.push(..._scanInstallerSurface());
+  return { violations, warnings, exitCode: violations.length ? 1 : 0 };
+}
+
+function main() {
+  const dir = process.argv[2] || 'nubos-pilot/workflows';
+  const { violations, warnings, exitCode } = checkWorkflows(dir);
+  if (violations.length) {
+    process.stderr.write('check-workflows: ' + violations.length + ' violation(s)\n');
+    for (const v of violations) {
+      process.stderr.write('  ' + v.file + ':' + v.line + ' -> ' + v.pattern + '\n');
+    }
+  }
+  if (warnings && warnings.length) {
+    process.stderr.write('check-workflows: ' + warnings.length + ' warning(s)\n');
+    for (const w of warnings) {
+      process.stderr.write('  ' + w.file + ':' + w.line + ' -> ' + w.pattern + '\n');
+    }
+  }
+  process.exit(exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkWorkflows,
+  _scan,
+  _scanFiles,
+  _scanInstallerSurface,
+  _scanMetricsCoverage,
+  INSTALL_SCRIPT,
+  LIB_INSTALL_DIR,
+  INSTALLER_SCAN_PATHS,
+  SPAWN_SITE_RE,
+  METRICS_RECORD_RE,
+  METRICS_COVERAGE_WINDOW,
+};

package/bin/check-workflows.test.cjs

@@ -0,0 +1,208 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const cw = require('./check-workflows.cjs');
+
+test('CW-8: SCAN_PATHS includes bin/install.js and lib/install/ (Phase 7 extension)', () => {
+  const source = fs.readFileSync(path.resolve(__dirname, 'check-workflows.cjs'), 'utf8');
+  assert.match(source, /bin\/install\.js/);
+  assert.match(source, /lib\/install/);
+  assert.deepEqual(cw.INSTALLER_SCAN_PATHS, ['bin/install.js', 'lib/install/']);
+});
+
+function mkTmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'cw-test-'));
+}
+
+function seed(root, files) {
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body, 'utf-8');
+  }
+}
+
+test('CW-1: absent directory returns empty violations + exitCode 0 (skip-on-absent)', () => {
+  const tmp = mkTmp();
+  try {
+    const res = cw.checkWorkflows(path.join(tmp, 'does/not/exist'));
+    assert.deepEqual(res.violations, []);
+    assert.equal(res.exitCode, 0);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-2: empty directory returns empty violations + exitCode 0', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    fs.mkdirSync(dir, { recursive: true });
+    const res = cw.checkWorkflows(dir);
+    assert.deepEqual(res.violations, []);
+    assert.equal(res.exitCode, 0);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-3: bare AskUserQuestion outside gateway → violation + exitCode 1', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, { 'bad.md': 'Please call AskUserQuestion directly here.\n' });
+    const res = cw.checkWorkflows(dir);
+    assert.equal(res.exitCode, 1);
+    assert.equal(res.violations.length, 1);
+    assert.match(res.violations[0].pattern, /AskUserQuestion/);
+    assert.ok(res.violations[0].file.endsWith('bad.md'));
+    assert.equal(typeof res.violations[0].line, 'number');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-4: direct cat .nubos-pilot read triggers violation', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, { 'read.md': '```bash\ncat .nubos-pilot/STATE.md\n```\n' });
+    const res = cw.checkWorkflows(dir);
+    assert.equal(res.exitCode, 1);
+    assert.ok(res.violations.length >= 1);
+    assert.ok(res.violations.some((v) => /nubos-pilot/.test(v.pattern) || /cat/.test(v.pattern)));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-5: single-call gateway through np-tools.cjs init does NOT violate', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, {
+      'ok.md': '```bash\nINIT=$(node np-tools.cjs init phase-op 3)\n```\n',
+    });
+    const res = cw.checkWorkflows(dir);
+    assert.deepEqual(res.violations, []);
+    assert.equal(res.exitCode, 0);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-6: CLI main reads argv[2]; violations exit 1 and write to stderr', () => {
+  const { spawnSync } = require('node:child_process');
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, { 'bad.md': 'note: AskUserQuestion here\n' });
+    const res = spawnSync(process.execPath, [path.join(__dirname, 'check-workflows.cjs'), dir], {
+      encoding: 'utf-8',
+    });
+    assert.equal(res.status, 1);
+    assert.match(res.stderr, /violation/i);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-7: recursion detects violation in nested workflow .md file', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, { 'sub/deep.md': 'uses AskUserQuestion improperly\n' });
+    const res = cw.checkWorkflows(dir);
+    assert.equal(res.exitCode, 1);
+    assert.ok(res.violations.some((v) => v.file.includes(path.join('sub', 'deep.md'))));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-M-1: Task spawn paired with `metrics record` inside bash block → no warning', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, {
+      'good.md':
+        '```bash\n' +
+        'MODEL=$(node np-tools.cjs resolve-model planner --profile balanced)\n' +
+        '# Spawn agent=np-planner tier=opus model=$MODEL\n' +
+        'node np-tools.cjs metrics record --agent np-planner --phase 09 \\\n' +
+        '  --tier opus --resolved-model "$MODEL" --started "$START" --ended "$END"\n' +
+        '```\n',
+    });
+    const res = cw.checkWorkflows(dir);
+    assert.equal(res.exitCode, 0);
+    assert.deepEqual(res.violations, []);
+    assert.deepEqual(res.warnings, []);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-M-2: Task spawn without `metrics record` → warning, exit code still 0', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, {
+      'bad.md':
+        '```bash\n' +
+        'MODEL=$(node np-tools.cjs resolve-model planner)\n' +
+        'Task({ subagent_type: "np-planner", model: "$MODEL" })\n' +
+        'echo done\n' +
+        '```\n',
+    });
+    const res = cw.checkWorkflows(dir);
+
+    assert.deepEqual(res.violations, []);
+    assert.equal(res.exitCode, 0);
+    assert.equal(res.warnings.length, 1);
+    assert.equal(res.warnings[0].pattern, 'workflow-missing-metrics');
+    assert.ok(res.warnings[0].file.endsWith('bad.md'));
+    assert.equal(typeof res.warnings[0].line, 'number');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-M-3: workflow with no Task/Spawn sites → no warning', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, {
+      'docs-only.md':
+        '# Pure documentation workflow\n\n' +
+        'No bash, no Task, no Spawn. Just prose.\n',
+    });
+    const res = cw.checkWorkflows(dir);
+    assert.equal(res.exitCode, 0);
+    assert.deepEqual(res.violations, []);
+    assert.deepEqual(res.warnings, []);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('CW-M-4: Spawn agent= reference in a markdown table (prose) → NOT flagged', () => {
+  const tmp = mkTmp();
+  try {
+    const dir = path.join(tmp, 'workflows');
+    seed(dir, {
+      'table.md':
+        '# Naming conventions\n\n' +
+        '| Legacy token | Canonical token |\n' +
+        '| ------------ | --------------- |\n' +
+        '| Task(…)      | Spawn agent=…   |\n',
+    });
+    const res = cw.checkWorkflows(dir);
+    assert.deepEqual(res.warnings, []);
+    assert.equal(res.exitCode, 0);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});