nubos-pilot 0.1.0

package/bin/np-tools/resolve-model.cjs

@@ -0,0 +1,110 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { findProjectRoot, NubosPilotError } = require('../../lib/core.cjs');
+const { loadAgent } = require('../../lib/agents.cjs');
+const { resolve: resolveAlias, MODEL_ALIAS_MAP, VALID_TIERS } = require('../../lib/model-profiles.cjs');
+
+function _readConfig(cwd) {
+  let root;
+  try {
+    root = findProjectRoot(cwd || process.cwd());
+  } catch {
+    return {};
+  }
+  const configPath = path.join(root, '.nubos-pilot', 'config.json');
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function resolveFromConfig({ agentOrTier, profileOverride, cwd, format }) {
+  const config = _readConfig(cwd);
+
+  let tier;
+  if (VALID_TIERS.includes(agentOrTier)) {
+    tier = agentOrTier;
+  } else {
+    const fm = loadAgent(agentOrTier, cwd);
+    tier = fm.tier;
+  }
+
+  const profile = profileOverride || config.model_profile || 'balanced';
+  const alias = resolveAlias(tier, profile);
+
+  let mode;
+  if (profile === 'inherit') {
+    mode = 'inherit';
+  } else if (format === 'omit' || config.resolve_model_ids === 'omit') {
+    mode = 'omit';
+  } else if (format === 'id' || config.resolve_model_ids === true) {
+    mode = 'full-id';
+  } else {
+    mode = 'alias';
+  }
+
+  let resolved;
+  if (mode === 'omit' || mode === 'inherit') {
+    resolved = '';
+  } else if (mode === 'full-id') {
+    const override = config.model_overrides
+      && config.model_overrides.tier_map
+      && config.model_overrides.tier_map[alias];
+    resolved = override || MODEL_ALIAS_MAP[alias] || '';
+  } else {
+    resolved = alias;
+  }
+
+  return { tier, profile, alias, resolved, mode };
+}
+
+function run(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : process.argv.slice(3);
+  if (args.length === 0 || args[0] === '--help') {
+    process.stderr.write(
+      'Usage: np-tools.cjs resolve-model <agent|tier> [--profile P] [--raw] [--format alias|id|omit]\n',
+    );
+    return 1;
+  }
+  const agentOrTier = args.shift();
+  let profileOverride = null;
+  let format = null;
+  while (args.length) {
+    const flag = args.shift();
+    if (flag === '--profile') {
+      profileOverride = args.shift();
+    } else if (flag === '--format') {
+      format = args.shift();
+    } else if (flag === '--raw') {
+
+    }
+  }
+  try {
+    const out = resolveFromConfig({
+      agentOrTier,
+      profileOverride,
+      cwd: process.cwd(),
+      format,
+    });
+    process.stdout.write(out.resolved + '\n');
+    return 0;
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError') {
+      process.stderr.write(
+        JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+      );
+    } else {
+      process.stderr.write(String((err && err.stack) || err) + '\n');
+    }
+    return 1;
+  }
+}
+
+module.exports = { run, resolveFromConfig };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/resolve-model.test.cjs

@@ -0,0 +1,200 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const subcmd = require('./resolve-model.cjs');
+
+const _sandboxes = [];
+
+function _sandbox(config, agents) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-resolve-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  if (config !== undefined) {
+    fs.writeFileSync(
+      path.join(root, '.nubos-pilot', 'config.json'),
+      JSON.stringify(config),
+      'utf-8',
+    );
+  }
+  if (agents) {
+    fs.mkdirSync(path.join(root, 'agents'), { recursive: true });
+    for (const [name, content] of Object.entries(agents)) {
+      fs.writeFileSync(path.join(root, 'agents', name + '.md'), content, 'utf-8');
+    }
+  }
+  _sandboxes.push(root);
+  return root;
+}
+
+function _captureStdout(fn) {
+  const chunks = [];
+  const origOut = process.stdout.write.bind(process.stdout);
+  const errChunks = [];
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (c) => { chunks.push(String(c)); return true; };
+  process.stderr.write = (c) => { errChunks.push(String(c)); return true; };
+  let rc;
+  try { rc = fn(); } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { stdout: chunks.join(''), stderr: errChunks.join(''), rc };
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    const p = _sandboxes.pop();
+    try { fs.rmSync(p, { recursive: true, force: true }); } catch {  }
+  }
+});
+
+const _plannerAgent = [
+  '---',
+  'name: np-planner',
+  'description: Test planner agent for resolve-model tests.',
+  'tier: opus',
+  'tools: Read, Write, Bash',
+  'color: green',
+  '---',
+  '',
+  '# Planner (test fixture)',
+  '',
+].join('\n');
+
+test('RM-1: tier branch with empty config returns alias mode, default balanced profile', () => {
+  const cwd = _sandbox({});
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd });
+  assert.deepEqual(out, {
+    tier: 'opus',
+    profile: 'balanced',
+    alias: 'opus',
+    resolved: 'opus',
+    mode: 'alias',
+  });
+});
+
+test('RM-2: profileOverride=budget drops opus to sonnet per matrix D-01', () => {
+  const cwd = _sandbox({});
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', profileOverride: 'budget', cwd });
+  assert.equal(out.tier, 'opus');
+  assert.equal(out.profile, 'budget');
+  assert.equal(out.alias, 'sonnet');
+  assert.equal(out.resolved, 'sonnet');
+  assert.equal(out.mode, 'alias');
+});
+
+test('RM-3: resolve_model_ids=true returns full-id from MODEL_ALIAS_MAP', () => {
+  const cwd = _sandbox({ resolve_model_ids: true });
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd });
+  assert.equal(out.mode, 'full-id');
+  assert.equal(out.resolved, 'claude-opus-4-7');
+  assert.equal(out.alias, 'opus');
+});
+
+test('RM-4: resolve_model_ids="omit" returns empty string and mode=omit (Pitfall 3 string check)', () => {
+  const cwd = _sandbox({ resolve_model_ids: 'omit' });
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd });
+  assert.equal(out.mode, 'omit');
+  assert.equal(out.resolved, '');
+  assert.equal(out.alias, 'opus');
+});
+
+test('RM-5: model_profile="inherit" short-circuits to mode=inherit, alias="", resolved=""', () => {
+  const cwd = _sandbox({ model_profile: 'inherit' });
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd });
+  assert.equal(out.profile, 'inherit');
+  assert.equal(out.alias, '');
+  assert.equal(out.resolved, '');
+  assert.equal(out.mode, 'inherit');
+});
+
+test('RM-6: agent-name branch reads tier from agents/<name>.md frontmatter', () => {
+  const cwd = _sandbox({}, { 'np-planner': _plannerAgent });
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'np-planner', cwd });
+  assert.equal(out.tier, 'opus');
+  assert.equal(out.profile, 'balanced');
+  assert.equal(out.alias, 'opus');
+  assert.equal(out.resolved, 'opus');
+  assert.equal(out.mode, 'alias');
+});
+
+test('RM-7: unknown agent name propagates NubosPilotError with code=agent-not-found', () => {
+  const cwd = _sandbox({});
+  let thrown = null;
+  try { subcmd.resolveFromConfig({ agentOrTier: 'nonexistent-agent', cwd }); } catch (e) { thrown = e; }
+  assert.ok(thrown);
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'agent-not-found');
+});
+
+test('RM-8: model_overrides.tier_map beats MODEL_ALIAS_MAP in full-id mode (D-02)', () => {
+  const cwd = _sandbox({
+    resolve_model_ids: true,
+    model_overrides: { tier_map: { opus: 'custom-opus-id' } },
+  });
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd });
+  assert.equal(out.mode, 'full-id');
+  assert.equal(out.resolved, 'custom-opus-id');
+  assert.equal(out.alias, 'opus');
+});
+
+test('RM-9: run(["opus","--profile","budget"]) prints "sonnet\\n" to stdout and returns 0', () => {
+  const cwd = _sandbox({});
+  const origCwd = process.cwd();
+  process.chdir(cwd);
+  try {
+    const cap = _captureStdout(() => subcmd.run(['opus', '--profile', 'budget']));
+    assert.equal(cap.stdout, 'sonnet\n');
+    assert.equal(cap.rc, 0);
+  } finally {
+    process.chdir(origCwd);
+  }
+});
+
+test('RM-10: run(["opus","--format","omit"]) prints empty line and returns 0', () => {
+  const cwd = _sandbox({});
+  const origCwd = process.cwd();
+  process.chdir(cwd);
+  try {
+    const cap = _captureStdout(() => subcmd.run(['opus', '--format', 'omit']));
+    assert.equal(cap.stdout, '\n');
+    assert.equal(cap.rc, 0);
+  } finally {
+    process.chdir(origCwd);
+  }
+});
+
+test('RM-11: --format=id forces full-id mode regardless of config default', () => {
+  const cwd = _sandbox({});
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd, format: 'id' });
+  assert.equal(out.mode, 'full-id');
+  assert.equal(out.resolved, 'claude-opus-4-7');
+});
+
+test('RM-12: malformed config.json falls back to defaults without throwing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-resolve-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'config.json'), '{not valid json', 'utf-8');
+  _sandboxes.push(root);
+  const out = subcmd.resolveFromConfig({ agentOrTier: 'opus', cwd: root });
+  assert.equal(out.mode, 'alias');
+  assert.equal(out.resolved, 'opus');
+  assert.equal(out.profile, 'balanced');
+});
+
+test('RM-13: run() on NubosPilotError writes JSON error envelope to stderr and returns 1', () => {
+  const cwd = _sandbox({});
+  const origCwd = process.cwd();
+  process.chdir(cwd);
+  try {
+    const cap = _captureStdout(() => subcmd.run(['nonexistent-agent']));
+    assert.equal(cap.rc, 1);
+    assert.match(cap.stderr, /agent-not-found/);
+    const parsed = JSON.parse(cap.stderr.trim());
+    assert.equal(parsed.code, 'agent-not-found');
+  } finally {
+    process.chdir(origCwd);
+  }
+});

package/bin/np-tools/resume-work.cjs

@@ -0,0 +1,76 @@
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { readState } = require('../../lib/state.cjs');
+const { readCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
+const { TASK_ID_RE } = require('../../lib/tasks.cjs');
+
+function _safeReadState(cwd) {
+  try { return readState(cwd); } catch { return null; }
+}
+
+function _validateCheckpointSchema(cp) {
+
+  
+  if (!cp || typeof cp !== 'object') return false;
+  if (cp.schema_version !== 1) return false;
+  if (typeof cp.task_id !== 'string' || !TASK_ID_RE.test(cp.task_id)) return false;
+  return true;
+}
+
+function run(_args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+
+  const state = _safeReadState(cwd);
+  const currentTask = state && state.frontmatter ? state.frontmatter.current_task : null;
+  const cpFiles = listCheckpoints(cwd);
+
+  let payload;
+  if (currentTask && cpFiles.length > 0) {
+    const cp = readCheckpoint(currentTask, cwd);
+    if (cp && _validateCheckpointSchema(cp) && cp.status !== 'done') {
+      payload = {
+        _workflow: 'resume-work',
+        status: 'resume',
+        task_id: currentTask,
+        checkpoint: cp,
+      };
+    } else if (cp && !_validateCheckpointSchema(cp)) {
+      throw new NubosPilotError(
+        'checkpoint-schema-mismatch',
+        'Checkpoint file schema invalid for task ' + currentTask,
+        { task: currentTask },
+      );
+    } else {
+
+      const orphanIds = cpFiles.map((f) => path.basename(f, '.json'));
+      payload = {
+        _workflow: 'resume-work',
+        status: 'orphan',
+        checkpoint_ids: orphanIds,
+        current_task: currentTask,
+      };
+    }
+  } else if (cpFiles.length > 0) {
+    const orphanIds = cpFiles.map((f) => path.basename(f, '.json'));
+    payload = {
+      _workflow: 'resume-work',
+      status: 'orphan',
+      checkpoint_ids: orphanIds,
+      current_task: currentTask,
+    };
+  } else {
+    payload = {
+      _workflow: 'resume-work',
+      status: 'clean',
+      message: 'no active work',
+    };
+  }
+
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

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

@@ -0,0 +1,91 @@
+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 subcmd = require('./resume-work.cjs');
+const { startTask } = require('../../lib/checkpoint.cjs');
+
+const _roots = [];
+
+function makeRoot(currentTask) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-rw-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  const ct = currentTask == null ? 'null' : currentTask;
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: 6
+current_plan: "06-01"
+current_task: ${ct}
+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
+---
+
+# State
+`, 'utf-8');
+  _roots.push(root);
+  return root;
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; return true; } }, get: () => b }; }
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('RW-1: clean when no state, no checkpoints', () => {
+  const root = makeRoot(null);
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.status, 'clean');
+});
+
+test('RW-2: resume when current_task matches an in-progress checkpoint', () => {
+  const root = makeRoot('06-01-T01');
+  startTask({ id: '06-01-T01', phase: 6, plan: '06-01', wave: 1 }, root);
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.status, 'resume');
+  assert.equal(p.task_id, '06-01-T01');
+  assert.equal(p.checkpoint.status, 'in-progress');
+});
+
+test('RW-3: orphan when checkpoint files exist but no matching STATE.current_task', () => {
+  const root = makeRoot(null);
+  startTask({ id: '06-01-T05', phase: 6, plan: '06-01', wave: 1 }, root);
+
+  const statePath = path.join(root, '.nubos-pilot', 'STATE.md');
+  const body = fs.readFileSync(statePath, 'utf-8').replace(/current_task:.*/, 'current_task: null');
+  fs.writeFileSync(statePath, body, 'utf-8');
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.status, 'orphan');
+  assert.ok(p.checkpoint_ids.includes('06-01-T05'));
+});
+
+test('RW-4: malformed checkpoint → checkpoint-schema-mismatch (T-06-12)', () => {
+  const root = makeRoot('06-01-T09');
+  const cpDir = path.join(root, '.nubos-pilot', 'checkpoints');
+  fs.mkdirSync(cpDir, { recursive: true });
+  fs.writeFileSync(path.join(cpDir, '06-01-T09.json'), JSON.stringify({ schema_version: 99, task_id: '06-01-T09' }), 'utf-8');
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run([], { cwd: root, stdout: cap.stub }),
+    (err) => err && err.code === 'checkpoint-schema-mismatch',
+  );
+});

package/bin/np-tools/skip.cjs

@@ -0,0 +1,48 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+const { TASK_ID_RE, setTaskStatus } = require('../../lib/tasks.cjs');
+
+function _findPlanDirForTask(taskId, cwd) {
+  const phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const padded = taskId.slice(0, 2);
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!(e.name === padded || e.name.startsWith(padded + '-'))) continue;
+    const candidate = path.join(phasesRoot, e.name, 'tasks', taskId + '.md');
+    if (fs.existsSync(candidate)) return path.join(phasesRoot, e.name);
+  }
+  return null;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const taskId = list[0];
+  if (!taskId) {
+    throw new NubosPilotError('skip-missing-task-id', 'skip requires a task id', {});
+  }
+  if (!TASK_ID_RE.test(taskId)) {
+    throw new NubosPilotError('skip-invalid-task-id', 'Invalid task id: ' + taskId, { taskId });
+  }
+  const planDir = _findPlanDirForTask(taskId, cwd);
+  if (!planDir) {
+    throw new NubosPilotError('task-not-found', 'No task file found for id ' + taskId, { taskId });
+  }
+  setTaskStatus(taskId, 'skipped', planDir);
+  const payload = { ok: true, task_id: taskId, status: 'skipped' };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/skip.test.cjs

@@ -0,0 +1,66 @@
+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 subcmd = require('./skip.cjs');
+
+const _roots = [];
+
+function makeRoot(taskId) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-skip-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', '06-demo');
+  const tasksDir = path.join(phaseDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, taskId + '.md'), [
+    '---', `id: ${taskId}`, 'phase: 6', 'plan: "06-01"', 'type: auto',
+    'status: pending', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified: []', 'autonomous: true',
+    'must_haves:', '  truths: []', '---', '', '# T',
+  ].join('\n'), 'utf-8');
+  _roots.push(root);
+  return root;
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; } }, get: () => b }; }
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('SK-1: skip missing id', () => {
+  assert.throws(
+    () => subcmd.run([], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'skip-missing-task-id',
+  );
+});
+
+test('SK-2: skip invalid id', () => {
+  assert.throws(
+    () => subcmd.run(['nope'], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'skip-invalid-task-id',
+  );
+});
+
+test('SK-3: skip flips status to skipped', () => {
+  const root = makeRoot('06-01-T01');
+  const cap = _capture();
+  subcmd.run(['06-01-T01'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.status, 'skipped');
+  const tf = path.join(root, '.nubos-pilot', 'phases', '06-demo', 'tasks', '06-01-T01.md');
+  assert.match(fs.readFileSync(tf, 'utf-8'), /^status: skipped$/m);
+});
+
+test('SK-4: skip unknown task → task-not-found', () => {
+  const root = makeRoot('06-01-T01');
+  assert.throws(
+    () => subcmd.run(['06-01-T99'], { cwd: root, stdout: _capture().stub }),
+    (err) => err && err.code === 'task-not-found',
+  );
+});

package/bin/np-tools/slug.cjs

@@ -0,0 +1,34 @@
+const { phaseSlug } = require('../../lib/phase.cjs');
+
+const MAX_SLUG_LENGTH = 128;
+
+function _usage() {
+  return 'Usage:\n  np-tools.cjs generate-slug "<text>" [--raw]';
+}
+
+function run(argv, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  if (args.length === 0) {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  const raw = args.includes('--raw');
+  const text = args.find((a) => !String(a).startsWith('--'));
+  if (text == null || String(text).length === 0) {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  const slug = phaseSlug(String(text)).slice(0, MAX_SLUG_LENGTH);
+  if (raw) stdout.write(slug);
+  else stdout.write(slug + '\n');
+  return 0;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/slug.test.cjs

@@ -0,0 +1,46 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Writable } = require('node:stream');
+
+const slugCli = require('./slug.cjs');
+
+function makeSink() {
+  const chunks = [];
+  const w = new Writable({
+    write(chunk, _enc, cb) { chunks.push(chunk); cb(); },
+  });
+  w.toString = () => Buffer.concat(chunks.map((c) => Buffer.isBuffer(c) ? c : Buffer.from(String(c)))).toString('utf-8');
+  return w;
+}
+
+test('SLUG-1: happy path slugifies a phrase', () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = slugCli.run(['Hello World Test', '--raw'], { stdout, stderr });
+  assert.equal(code, 0);
+  assert.equal(stdout.toString(), 'hello-world-test');
+});
+
+test('SLUG-2: missing text prints usage', () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = slugCli.run([], { stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /Usage:/);
+});
+
+test('SLUG-3: non-raw output has trailing newline', () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = slugCli.run(['Fix deploy key auth'], { stdout, stderr });
+  assert.equal(code, 0);
+  assert.equal(stdout.toString(), 'fix-deploy-key-auth\n');
+});
+
+test('SLUG-4: collapses repeated separators + strips leading/trailing', () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = slugCli.run(['  --FOO  BAR!!!  ', '--raw'], { stdout, stderr });
+  assert.equal(code, 0);
+  assert.equal(stdout.toString(), 'foo-bar');
+});

package/bin/np-tools/state.cjs

@@ -0,0 +1,16 @@
+const { readState } = require('../../lib/state.cjs');
+
+function run(_args, cwd) {
+  const useCwd = cwd || process.cwd();
+  try {
+    const s = readState(useCwd);
+    return s.frontmatter;
+  } catch (err) {
+
+    const code = err && err.code ? String(err.code) : 'state-not-found';
+    const message = err && err.message ? err.message : 'STATE.md not readable';
+    return { error: { code, message, details: err && err.details ? err.details : null } };
+  }
+}
+
+module.exports = { run };