nubos-pilot 0.6.2 → 0.6.3

package/bin/np-tools/thread-resume.test.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+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 mod = require('./thread-resume.cjs');
+
+function mkSandbox(fmLines, body) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-tr-'));
+  const p = path.join(dir, 'thread.md');
+  const content = '---\n' + fmLines.join('\n') + '\n---\n' + (body || '# body\n');
+  fs.writeFileSync(p, content);
+  return { dir, p };
+}
+
+function captureStdout() {
+  const chunks = [];
+  return {
+    stream: { write: (c) => { chunks.push(c); } },
+    read: () => chunks.join(''),
+  };
+}
+
+test('TR-1: OPEN bumps to IN_PROGRESS', () => {
+  assert.equal(mod._bumpStatus('OPEN'), 'IN_PROGRESS');
+});
+
+test('TR-2: IN_PROGRESS stays IN_PROGRESS', () => {
+  assert.equal(mod._bumpStatus('IN_PROGRESS'), 'IN_PROGRESS');
+});
+
+test('TR-3: RESOLVED stays RESOLVED (monotonic)', () => {
+  assert.equal(mod._bumpStatus('RESOLVED'), 'RESOLVED');
+});
+
+test('TR-4: run() bumps OPEN and writes last_resumed', () => {
+  const { dir, p } = mkSandbox([
+    'slug: foo',
+    'status: OPEN',
+    'created: 2026-04-01',
+    'last_resumed: 2026-04-01',
+  ], '# Thread: foo\n');
+  try {
+    const cap = captureStdout();
+    const rc = mod.run([p, '--today', '2026-04-22'], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    const written = fs.readFileSync(p, 'utf-8');
+    assert.match(written, /status: IN_PROGRESS/);
+    assert.match(written, /last_resumed: 2026-04-22/);
+    const out = JSON.parse(cap.read());
+    assert.equal(out.status, 'IN_PROGRESS');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('TR-5: RESOLVED stays RESOLVED across resume', () => {
+  const { dir, p } = mkSandbox([
+    'slug: bar',
+    'status: RESOLVED',
+    'created: 2026-04-01',
+    'last_resumed: 2026-04-10',
+  ], '# body\n');
+  try {
+    const cap = captureStdout();
+    mod.run([p, '--today', '2026-04-22'], { cwd: dir, stdout: cap.stream });
+    const written = fs.readFileSync(p, 'utf-8');
+    assert.match(written, /status: RESOLVED/);
+    assert.match(written, /last_resumed: 2026-04-22/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('TR-6: stable field ordering (slug, status, created, last_resumed)', () => {
+  const { dir, p } = mkSandbox([
+    'last_resumed: 2026-04-01',
+    'created: 2026-04-01',
+    'status: OPEN',
+    'slug: baz',
+  ], '# body\n');
+  try {
+    const cap = captureStdout();
+    mod.run([p, '--today', '2026-04-22'], { cwd: dir, stdout: cap.stream });
+    const written = fs.readFileSync(p, 'utf-8');
+    const fmBlock = written.split('---')[1];
+    const idxSlug = fmBlock.indexOf('slug:');
+    const idxStatus = fmBlock.indexOf('status:');
+    const idxCreated = fmBlock.indexOf('created:');
+    const idxLast = fmBlock.indexOf('last_resumed:');
+    assert.ok(idxSlug < idxStatus && idxStatus < idxCreated && idxCreated < idxLast);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('TR-7: missing path throws', () => {
+  assert.throws(
+    () => mod.run([], { cwd: '/tmp', stdout: { write: () => {} } }),
+    (err) => err.code === 'thread-resume-missing-path',
+  );
+});
+
+test('TR-8: nonexistent file throws read-error', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-tr-'));
+  try {
+    assert.throws(
+      () => mod.run([path.join(dir, 'nope.md')], { cwd: dir, stdout: { write: () => {} } }),
+      (err) => err.code === 'thread-resume-read-error',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('TR-9: default today is current ISO date', () => {
+  const { dir, p } = mkSandbox([
+    'slug: x',
+    'status: OPEN',
+    'created: 2026-04-01',
+    'last_resumed: 2026-04-01',
+  ], '');
+  try {
+    const cap = captureStdout();
+    mod.run([p], { cwd: dir, stdout: cap.stream });
+    const out = JSON.parse(cap.read());
+    assert.match(out.last_resumed, /^\d{4}-\d{2}-\d{2}$/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/bin/np-tools/workspace-scan.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { scan } = require('../../lib/workspace-scan.cjs');
+
+function _parseArgs(args) {
+  const out = { batchSize: 1000, summary: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--batch-size' || a === '-b') {
+      const n = Number(args[++i]);
+      if (!Number.isFinite(n) || n <= 0) {
+        throw new NubosPilotError('workspace-scan-invalid-batch-size',
+          '--batch-size must be a positive integer', { raw: args[i] });
+      }
+      out.batchSize = n;
+      continue;
+    }
+    if (a === '--summary' || a === '-s') { out.summary = true; continue; }
+  }
+  return out;
+}
+
+function _projectSummary(r) {
+  const readmeHead = r.docs && r.docs['README.md']
+    ? r.docs['README.md'].content.split('\n').slice(0, 20).join('\n')
+    : null;
+  return {
+    file_count: r.stats.file_count,
+    langs: r.language_distribution,
+    manifests: Object.keys(r.manifests),
+    docs: Object.keys(r.docs),
+    readme_head: readmeHead,
+    git: r.git,
+  };
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(args || []);
+  const result = scan({ cwd, batchSize: parsed.batchSize });
+  const payload = parsed.summary ? _projectSummary(result) : result;
+  stdout.write(JSON.stringify(payload));
+  return 0;
+}
+
+module.exports = { run, _parseArgs, _projectSummary };

package/bin/np-tools/workspace-scan.test.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+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 mod = require('./workspace-scan.cjs');
+
+function mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-ws-'));
+  fs.writeFileSync(path.join(dir, 'README.md'), '# Test\n\nLine 1\nLine 2\n');
+  fs.writeFileSync(path.join(dir, 'index.js'), 'console.log("hi");\n');
+  fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"x"}\n');
+  return dir;
+}
+
+function captureStdout() {
+  const chunks = [];
+  return {
+    stream: { write: (c) => { chunks.push(c); } },
+    read: () => chunks.join(''),
+  };
+}
+
+test('WS-1: default run emits full scan result JSON', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run([], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    const out = JSON.parse(cap.read());
+    assert.ok(out.stats);
+    assert.ok(out.language_distribution);
+    assert.equal(typeof out.stats.file_count, 'number');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('WS-2: --summary emits the new-project shape', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['--summary'], { cwd: dir, stdout: cap.stream });
+    assert.equal(rc, 0);
+    const out = JSON.parse(cap.read());
+    assert.ok('file_count' in out);
+    assert.ok('langs' in out);
+    assert.ok('manifests' in out);
+    assert.ok('docs' in out);
+    assert.ok('readme_head' in out);
+    assert.ok('git' in out);
+    assert.match(out.readme_head, /^# Test/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('WS-3: --batch-size accepts positive integer', () => {
+  assert.deepEqual(mod._parseArgs(['--batch-size', '500']), { batchSize: 500, summary: false });
+});
+
+test('WS-4: --batch-size rejects non-positive', () => {
+  assert.throws(
+    () => mod._parseArgs(['--batch-size', '0']),
+    (err) => err.code === 'workspace-scan-invalid-batch-size',
+  );
+});
+
+test('WS-5: --batch-size rejects NaN', () => {
+  assert.throws(
+    () => mod._parseArgs(['--batch-size', 'ten']),
+    (err) => err.code === 'workspace-scan-invalid-batch-size',
+  );
+});

package/lib/config-defaults.cjs

@@ -1,8 +1,14 @@
 'use strict';
 
+const DEFAULT_RESEARCH_TOOLS = Object.freeze({
+  WebFetch: true,
+  Context7: true,
+});
+
 const DEFAULT_WORKFLOW = Object.freeze({
   commit_docs: true,
   commit_artifacts: true,
+  research_tools: DEFAULT_RESEARCH_TOOLS,
 });
 
 const DEFAULT_AGENTS = Object.freeze({
@@ -25,13 +31,14 @@ function buildInstallConfig(answers) {
     mcp: !!a.mcp,
     model_profile: a.model_profile || DEFAULT_MODEL_PROFILE,
     response_language: a.response_language || DEFAULT_RESPONSE_LANGUAGE,
-    workflow: { ...DEFAULT_WORKFLOW },
+    workflow: { ...DEFAULT_WORKFLOW, research_tools: { ...DEFAULT_RESEARCH_TOOLS } },
     agents: { ...DEFAULT_AGENTS },
   };
 }
 
 module.exports = {
   DEFAULT_WORKFLOW,
+  DEFAULT_RESEARCH_TOOLS,
   DEFAULT_AGENTS,
   DEFAULT_MODEL_PROFILE,
   DEFAULT_SCOPE,

package/lib/roadmap-render.cjs

@@ -11,21 +11,11 @@ const {
 const GENERATED_HEADER = '<!-- Generated from roadmap.yaml — do not edit by hand -->';
 
 function _yamlPath(cwd) {
-  try {
-    return path.join(projectStateDir(cwd), 'roadmap.yaml');
-  } catch (err) {
-    if (!err || err.code !== 'not-in-project') throw err;
-    return path.join(path.resolve(cwd), '.planning', 'roadmap.yaml');
-  }
+  return path.join(projectStateDir(cwd), 'roadmap.yaml');
 }
 
 function _mdPath(cwd) {
-  try {
-    return path.join(projectStateDir(cwd), 'ROADMAP.md');
-  } catch (err) {
-    if (!err || err.code !== 'not-in-project') throw err;
-    return path.join(path.resolve(cwd), '.planning', 'ROADMAP.md');
-  }
+  return path.join(projectStateDir(cwd), 'ROADMAP.md');
 }
 
 function _readYaml(p) {

package/lib/roadmap.cjs

@@ -10,12 +10,7 @@ const {
 const { renderMarkdown } = require('./roadmap-render.cjs');
 
 function roadmapPath(cwd) {
-  try {
-    return path.join(projectStateDir(cwd), 'roadmap.yaml');
-  } catch (err) {
-    if (!err || err.code !== 'not-in-project') throw err;
-    return path.join(path.resolve(cwd), '.planning', 'roadmap.yaml');
-  }
+  return path.join(projectStateDir(cwd), 'roadmap.yaml');
 }
 
 function _readRaw(p) {
@@ -159,12 +154,7 @@ const _MAX_ROADMAP_BYTES = 1024 * 1024;
 const _SLUG_RE = /^[a-z0-9-]+$/;
 
 function _mdPath(cwd) {
-  try {
-    return path.join(projectStateDir(cwd), 'ROADMAP.md');
-  } catch (err) {
-    if (!err || err.code !== 'not-in-project') throw err;
-    return path.join(path.resolve(cwd), '.planning', 'ROADMAP.md');
-  }
+  return path.join(projectStateDir(cwd), 'ROADMAP.md');
 }
 
 function _mutate(cwd, fn) {

package/np-tools.cjs

@@ -51,6 +51,14 @@ const topLevelCommands = {
   'detect-runtime': require('./bin/np-tools/detect-runtime.cjs'),
   'template-path':  require('./bin/np-tools/template-path.cjs'),
   'update-phase-meta': require('./bin/np-tools/update-phase-meta.cjs'),
+  'phase-meta':     require('./bin/np-tools/phase-meta.cjs'),
+  'state-dir':      require('./bin/np-tools/state-dir.cjs'),
+  'render-template': require('./bin/np-tools/render-template.cjs'),
+  'thread-resume':  require('./bin/np-tools/thread-resume.cjs'),
+  'state-incr':     require('./bin/np-tools/state-incr.cjs'),
+  'session-aggregate':     require('./bin/np-tools/session-aggregate.cjs'),
+  'session-pointer-write': require('./bin/np-tools/session-pointer-write.cjs'),
+  'workspace-scan': require('./bin/np-tools/workspace-scan.cjs'),
 };
 
 const THRESHOLD = 16 * 1024;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "AI-driven planning and execution tool for code projects",
   "homepage": "https://github.com/Nubos-AI/nubos-pilot",
   "repository": {

package/templates/claude/payload/README.md

@@ -7,5 +7,3 @@ Subdirectories (populated in Phase 8 and onwards):
 - `agents/` — agent `.md` files
 - `hooks/` — hook scripts
 - `templates/` — scaffolding templates
-
-See `.planning/phases/07-install-npx-flow/07-RESEARCH.md` §Recommended Project Structure for the full layout.

package/workflows/add-todo.md

@@ -131,7 +131,7 @@ reads of the project state directory from this workflow would bypass
 the lock and are explicitly forbidden by the check-workflows lint.
 
 ```bash
-node -e "require('./lib/state.cjs').mutateState(function (doc) { doc.frontmatter.pending_todos = (doc.frontmatter.pending_todos || 0) + 1; return doc; });"
+node .nubos-pilot/bin/np-tools.cjs state-incr pending_todos > /dev/null
 ```
 
 The mutator increments the `pending_todos` counter on the STATE.md

package/workflows/discuss-phase.md

@@ -340,14 +340,7 @@ CONTEXT_PATH=$(echo "$INIT" | node -e 'let d="";process.stdin.on("data",c=>d+=c)
 mkdir -p "$MILESTONE_DIR"
 mkdir -p "$MILESTONE_DIR/slices"
 
-TPL_PATH=$(node .nubos-pilot/bin/np-tools.cjs template-path milestone/CONTEXT)
-node -e '
-  const { render } = require("./lib/template.cjs");
-  const fs = require("node:fs");
-  const tpl = fs.readFileSync(process.argv[1], "utf-8");
-  const vars = JSON.parse(process.argv[2]);
-  process.stdout.write(render(tpl, vars));
-' "$TPL_PATH" "$VARS_JSON" > "$CONTEXT_PATH"
+node .nubos-pilot/bin/np-tools.cjs render-template milestone/CONTEXT --vars "$VARS_JSON" > "$CONTEXT_PATH"
 ```
 
 `$VARS_JSON` is the JSON-serialised accumulator from Steps 2–5 (keys map to
@@ -379,13 +372,8 @@ SC_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
 SC_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-sc-extractor --profile balanced)
 
 REQS_PATH=".nubos-pilot/REQUIREMENTS.md"
-[[ -f "$REQS_PATH" ]] || REQS_PATH=".planning/REQUIREMENTS.md"
 
-EXISTING_SC_JSON=$(node -e '
-  const r = require("./lib/roadmap.cjs");
-  const p = r.getPhase(process.argv[1]);
-  process.stdout.write(JSON.stringify(p.success_criteria || []));
-' "$PHASE")
+EXISTING_SC_JSON=$(node .nubos-pilot/bin/np-tools.cjs phase-meta "$PHASE" --field success_criteria)
 
 # Spawn agent=np-sc-extractor tier=haiku model=$SC_MODEL milestone=$PHASE
 #   input: milestone=$PHASE, milestone_id=$MILESTONE_ID, milestone_dir=$MILESTONE_DIR,
@@ -406,11 +394,7 @@ node .nubos-pilot/bin/np-tools.cjs metrics record \
 After the spawn, sanity-check that `success_criteria` is non-empty:
 
 ```bash
-SC_COUNT=$(node -e '
-  const r = require("./lib/roadmap.cjs");
-  const p = r.getPhase(process.argv[1]);
-  process.stdout.write(String((p.success_criteria || []).length));
-' "$PHASE")
+SC_COUNT=$(node .nubos-pilot/bin/np-tools.cjs phase-meta "$PHASE" --field success_criteria --length)
 if [[ "$SC_COUNT" -lt 1 ]]; then
   echo "ERROR: np-sc-extractor produced no success_criteria for $MILESTONE_ID — refusing to continue." >&2
   exit 1

package/workflows/new-project.md

@@ -75,20 +75,7 @@ still has `_TBD` placeholders.
 Probe the workspace for context before asking anything:
 
 ```bash
-SCAN=$(node -e '
-  const { scan } = require("./lib/workspace-scan.cjs");
-  const r = scan({ cwd: process.cwd(), batchSize: 1000 });
-  process.stdout.write(JSON.stringify({
-    file_count: r.stats.file_count,
-    langs: r.language_distribution,
-    manifests: Object.keys(r.manifests),
-    docs: Object.keys(r.docs),
-    readme_head: r.docs["README.md"]
-      ? r.docs["README.md"].content.split("\\n").slice(0, 20).join("\\n")
-      : null,
-    git: r.git,
-  }));
-')
+SCAN=$(node .nubos-pilot/bin/np-tools.cjs workspace-scan --summary --batch-size 1000)
 ```
 
 Show findings to the user and offer pre-filled suggestions:

package/workflows/note.md

@@ -74,7 +74,7 @@ sidesteps that resolver and hardcodes `HOME + /.nubos-pilot/notes`.
 if [[ "$SCOPE" == "global" ]]; then
   NOTES_DIR="$HOME/.nubos-pilot/notes"
 else
-  NOTES_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()) + '/notes')")
+  NOTES_DIR=$(node .nubos-pilot/bin/np-tools.cjs state-dir --subdir notes)
 fi
 mkdir -p "$NOTES_DIR"
 DATE=$(date +%Y-%m-%d)

package/workflows/session-report.md

@@ -40,7 +40,7 @@ for arg in "$@"; do
   esac
 done
 
-STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+STATE_DIR=$(node .nubos-pilot/bin/np-tools.cjs state-dir)
 REPORTS_DIR="${STATE_DIR}/reports"
 POINTER="${REPORTS_DIR}/.last-session"
 mkdir -p "$REPORTS_DIR"
@@ -80,21 +80,11 @@ between "read pointer" and "write new pointer" (T-10-06-02 / Pitfall
 longer hit `lock-timeout` from `lib/core.cjs.NubosPilotError`.
 
 ```bash
-REPORT_JSON=$(node -e '
-  const fs = require("node:fs");
-  const { withFileLock } = require("./lib/core.cjs");
-  const { aggregateSession } = require("./lib/metrics-aggregate.cjs");
-  const pointer = process.argv[1];
-  const override = process.argv[2] || "";
-  const done = withFileLock(pointer, async () => {
-    let since = override || "";
-    if (!override && fs.existsSync(pointer)) {
-      since = fs.readFileSync(pointer, "utf-8").trim();
-    }
-    return aggregateSession(since || null, { cwd: process.cwd() });
-  }, { timeoutMs: 10000 });
-  Promise.resolve(done).then((r) => process.stdout.write(JSON.stringify(r)));
-' "$POINTER" "$SINCE_OVERRIDE")
+if [[ -n "$SINCE_OVERRIDE" ]]; then
+  REPORT_JSON=$(node .nubos-pilot/bin/np-tools.cjs session-aggregate --since "$SINCE_OVERRIDE")
+else
+  REPORT_JSON=$(node .nubos-pilot/bin/np-tools.cjs session-aggregate)
+fi
 ```
 
 The `aggregateSession` helper returns
@@ -150,14 +140,7 @@ and "update pointer" leaves the pointer STALE — the next run
 re-covers the missing period (safe-by-default).
 
 ```bash
-node -e '
-  const { withFileLock, atomicWriteFileSync } = require("./lib/core.cjs");
-  withFileLock(
-    process.argv[1],
-    () => atomicWriteFileSync(process.argv[1], process.argv[2]),
-    { timeoutMs: 10000 }
-  );
-' "$POINTER" "$NOW_ISO"
+node .nubos-pilot/bin/np-tools.cjs session-pointer-write "$NOW_ISO" > /dev/null
 ```
 
 Using `atomicWriteFileSync` ensures the pointer update is crash-safe

package/workflows/thread.md

@@ -35,7 +35,7 @@ if [[ -z "$SLUG" ]]; then
   echo "Error: argument produced no slug-safe characters." >&2
   exit 1
 fi
-STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+STATE_DIR=$(node .nubos-pilot/bin/np-tools.cjs state-dir)
 THREADS_DIR="${STATE_DIR}/threads"
 THREAD_PATH="${THREADS_DIR}/${SLUG}.md"
 TODAY=$(date +%Y-%m-%d)
@@ -119,35 +119,11 @@ order.
 
 ```bash
 if [[ "$MODE" == "resume" ]]; then
-  node -e "
-    const fs = require('node:fs');
-    const { extractFrontmatter } = require('./lib/frontmatter.cjs');
-    const { atomicWriteFileSync } = require('./lib/core.cjs');
-    const p = process.argv[1];
-    const today = process.argv[2];
-    const raw = fs.readFileSync(p, 'utf-8');
-    const { frontmatter, body } = extractFrontmatter(raw);
-    const next = Object.assign({}, frontmatter);
-    const cur = String(next.status || 'OPEN');
-    if (cur === 'OPEN') next.status = 'IN_PROGRESS';
-    next.last_resumed = today;
-    const order = ['slug', 'status', 'created', 'last_resumed'];
-    const seen = new Set();
-    const lines = ['---'];
-    for (const k of order) {
-      if (k in next) { lines.push(k + ': ' + next[k]); seen.add(k); }
-    }
-    for (const k of Object.keys(next)) {
-      if (!seen.has(k)) lines.push(k + ': ' + next[k]);
-    }
-    lines.push('---');
-    const out = lines.join('\n') + '\n' + body;
-    atomicWriteFileSync(p, out);
-  " "$THREAD_PATH" "$TODAY"
+  node .nubos-pilot/bin/np-tools.cjs thread-resume "$THREAD_PATH" --today "$TODAY" > /dev/null
   echo "Thread resumed: $THREAD_PATH"
   echo ""
   echo "--- thread content ---"
-  node -e "process.stdout.write(require('node:fs').readFileSync(process.argv[1], 'utf-8'))" "$THREAD_PATH"
+  cat "$THREAD_PATH"
 fi
 ```