nubos-pilot 0.1.0

package/lib/git.cjs

@@ -0,0 +1,207 @@
+const { execFileSync } = require('node:child_process');
+const { NubosPilotError } = require('./core.cjs');
+const { TASK_ID_RE } = require('./tasks.cjs');
+
+function _isFatalCheckIgnore(err) {
+
+  
+  return err && err.status !== 1;
+}
+
+function isPathIgnored(p) {
+  try {
+    execFileSync('git', ['check-ignore', '--quiet', '--', p], { stdio: 'pipe' });
+    return true; 
+  } catch (err) {
+    if (err && err.status === 1) return false; 
+    if (err && err.status === 128) {
+
+      throw err;
+    }
+    throw err;
+  }
+}
+
+function assertCommittablePaths(paths) {
+  if (!Array.isArray(paths)) {
+    throw new NubosPilotError(
+      'commit-paths-invalid',
+      'assertCommittablePaths expects an array of paths',
+      { got: typeof paths },
+    );
+  }
+  const ignored = [];
+  for (const p of paths) {
+    try {
+      execFileSync('git', ['check-ignore', '--quiet', '--', p], { stdio: 'pipe' });
+      ignored.push(p); 
+    } catch (err) {
+      if (_isFatalCheckIgnore(err)) {
+        if (err.status === 128) throw err;
+
+      }
+    }
+  }
+  if (ignored.length > 0 && ignored.length === paths.length) {
+
+    throw new NubosPilotError(
+      'commit-all-paths-gitignored',
+      `All target paths are gitignored: ${paths.join(', ')}`,
+      { paths },
+    );
+  }
+  if (ignored.length > 0) {
+
+    process.stderr.write(
+      `[nubos-pilot warn] gitignored (skipping): ${ignored.join(', ')}\n`,
+    );
+  }
+  return paths.filter((p) => !ignored.includes(p));
+}
+
+function commitTask(taskId, files, message) {
+  const committable = assertCommittablePaths(files);
+  if (committable.length === 0) {
+
+    
+
+    throw new NubosPilotError(
+      'commit-no-paths',
+      'commitTask invoked with empty file list',
+      { taskId },
+    );
+  }
+  execFileSync('git', ['add', '--', ...committable], { stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', message, '--', ...committable], { stdio: 'pipe' });
+}
+
+function findCommitByTaskId(id) {
+
+  
+
+  if (typeof id !== 'string' || !TASK_ID_RE.test(id)) {
+    throw new NubosPilotError(
+      'task-commit-not-found',
+      `Invalid task id ${id}`,
+      { id },
+    );
+  }
+
+  
+
+  
+  const out = execFileSync(
+    'git',
+    [
+      'log',
+      '--all',
+      '--grep',
+      `^task(${id}):`,
+      '-n',
+      '1',
+      '--format=%H',
+    ],
+    { encoding: 'utf-8' },
+  ).trim();
+  if (!out) {
+    throw new NubosPilotError(
+      'task-commit-not-found',
+      `No commit found for task ${id}`,
+      { id },
+    );
+  }
+  return out;
+}
+
+function revertCommit(sha) {
+
+  
+
+  execFileSync('git', ['revert', '--no-edit', sha], { stdio: 'pipe' });
+}
+
+function restoreFiles(paths) {
+  if (!Array.isArray(paths) || paths.length === 0) return;
+  execFileSync('git', ['restore', '--', ...paths], { stdio: 'pipe' });
+}
+
+function checkoutFromHead(paths, opts) {
+  if (!Array.isArray(paths) || paths.length === 0) return;
+  const cwd = opts && opts.cwd;
+  const args = cwd ? ['-C', cwd, 'checkout', 'HEAD', '--', ...paths]
+                   : ['checkout', 'HEAD', '--', ...paths];
+  execFileSync('git', args, { stdio: 'pipe' });
+}
+
+function listTaskCommits(prefix) {
+
+  
+  if (typeof prefix !== 'string' || prefix.length === 0) {
+    throw new NubosPilotError(
+      'list-task-commits-invalid',
+      'listTaskCommits requires a non-empty phase or plan id prefix',
+      { prefix },
+    );
+  }
+  const raw = execFileSync(
+    'git',
+    [
+      'log',
+      '--all',
+      '--grep',
+      `^task(${prefix}-`,
+      '--format=%H %s',
+    ],
+    { encoding: 'utf-8' },
+  );
+  const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+  return lines.map((line) => {
+    const sp = line.indexOf(' ');
+    if (sp < 0) return { sha: line, subject: '' };
+    return { sha: line.slice(0, sp), subject: line.slice(sp + 1) };
+  });
+}
+
+function gitShowSafe(ref, filepath) {
+  try {
+    return execFileSync(
+      'git',
+      ['show', ref + ':' + filepath],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+  } catch (err) {
+    if (err && err.status === 128) return null;
+    const stderr = String(err && err.stderr || '');
+    if (stderr.includes('exists on disk, but not in') || stderr.includes('does not exist in')) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function gitDiffNoColor(ref, filepath) {
+  try {
+    return execFileSync(
+      'git',
+      ['--no-pager', 'diff', '--no-color', ref, '--', filepath],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+  } catch (err) {
+    if (err && typeof err.stdout === 'string') return err.stdout;
+    if (err && err.stdout !== undefined) return String(err.stdout);
+    throw err;
+  }
+}
+
+module.exports = {
+  commitTask,
+  assertCommittablePaths,
+  revertCommit,
+  restoreFiles,
+  checkoutFromHead,
+  findCommitByTaskId,
+  isPathIgnored,
+  listTaskCommits,
+  gitShowSafe,
+  gitDiffNoColor,
+};

package/lib/git.test.cjs

@@ -0,0 +1,305 @@
+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 { execFileSync } = require('node:child_process');
+
+const git = require('./git.cjs');
+
+const _repos = [];
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-git-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos-pilot.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], {
+    stdio: 'pipe',
+  });
+  _repos.push(root);
+  return root;
+}
+
+function inRepo(root, fn) {
+  const prev = process.cwd();
+  process.chdir(root);
+  try {
+    return fn();
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+function writeFile(root, rel, body) {
+  const p = path.join(root, rel);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body == null ? '' : body, 'utf-8');
+  return rel;
+}
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('GIT-1: assertCommittablePaths returns paths unchanged when none ignored', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'a.ts', 'x');
+    writeFile(root, 'b.ts', 'y');
+    const out = git.assertCommittablePaths(['a.ts', 'b.ts']);
+    assert.deepEqual(out, ['a.ts', 'b.ts']);
+  });
+});
+
+test('GIT-2: assertCommittablePaths writes stderr warning for partial-ignored and skips ignored entries', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, '.gitignore', 'build/\n');
+    writeFile(root, 'a.ts', 'x');
+    writeFile(root, 'build/out.js', 'noise');
+
+    const original = process.stderr.write;
+    let captured = '';
+    process.stderr.write = (chunk) => {
+      captured += chunk;
+      return true;
+    };
+    let result;
+    try {
+      result = git.assertCommittablePaths(['a.ts', 'build/out.js']);
+    } finally {
+      process.stderr.write = original;
+    }
+    assert.deepEqual(result, ['a.ts']);
+    assert.match(captured, /\[nubos-pilot warn\] gitignored \(skipping\):/);
+    assert.match(captured, /build\/out\.js/);
+  });
+});
+
+test('GIT-3: assertCommittablePaths throws commit-all-paths-gitignored when every path ignored (D-25)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, '.gitignore', '.env\nsecret.txt\n');
+    writeFile(root, '.env', 'X=1');
+    writeFile(root, 'secret.txt', 'shh');
+    assert.throws(
+      () => git.assertCommittablePaths(['.env', 'secret.txt']),
+      (err) => {
+        return err.name === 'NubosPilotError'
+          && err.code === 'commit-all-paths-gitignored'
+          && Array.isArray(err.details.paths)
+          && err.details.paths.includes('.env');
+      },
+    );
+  });
+});
+
+test('GIT-4: isPathIgnored returns true for ignored, false for tracked-eligible', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, '.gitignore', 'node_modules/\n');
+    writeFile(root, 'node_modules/x.js', '');
+    writeFile(root, 'src.ts', '');
+    assert.equal(git.isPathIgnored('node_modules/x.js'), true);
+    assert.equal(git.isPathIgnored('src.ts'), false);
+  });
+});
+
+test('GIT-5: commitTask creates a single commit containing exactly the supplied paths', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'lib/git.cjs', '// stub');
+    git.commitTask('06-01-T01', ['lib/git.cjs'], 'task(06-01-T01): add git helper');
+    const log = execFileSync('git', ['log', '-n', '1', '--format=%s'], { encoding: 'utf-8' }).trim();
+    assert.equal(log, 'task(06-01-T01): add git helper');
+    const stat = execFileSync('git', ['show', '--stat', '--format=', 'HEAD'], { encoding: 'utf-8' });
+    assert.match(stat, /lib\/git\.cjs/);
+  });
+});
+
+test('GIT-6: findCommitByTaskId returns 40-char SHA for known task commit', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'a.ts', 'x');
+    git.commitTask('06-01-T01', ['a.ts'], 'task(06-01-T01): add a.ts');
+    const sha = git.findCommitByTaskId('06-01-T01');
+    assert.match(sha, /^[0-9a-f]{40}$/);
+  });
+});
+
+test('GIT-7: findCommitByTaskId throws task-commit-not-found when no commit matches', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    assert.throws(
+      () => git.findCommitByTaskId('06-01-T99'),
+      (err) => err.code === 'task-commit-not-found' && err.details.id === '06-01-T99',
+    );
+  });
+});
+
+test('GIT-8: findCommitByTaskId rejects malformed task-id BEFORE --grep embedding (regex injection guard)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    assert.throws(
+      () => git.findCommitByTaskId('invalid-id'),
+      (err) => err.code === 'task-commit-not-found',
+    );
+    assert.throws(
+      () => git.findCommitByTaskId('06-01-T01.*'),
+      (err) => err.code === 'task-commit-not-found',
+    );
+  });
+});
+
+test('GIT-9: findCommitByTaskId is anchored — body-mention of stale task-id does not produce false match (Pitfall 3)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+
+    writeFile(root, 'a.ts', 'x');
+    git.commitTask('06-01-T01', ['a.ts'], 'task(06-01-T01): real task');
+    const realSha = git.findCommitByTaskId('06-01-T01');
+
+    writeFile(root, 'b.ts', 'y');
+    execFileSync('git', ['add', '--', 'b.ts']);
+    execFileSync('git', [
+      'commit',
+      '-m',
+      'task(06-01-T02): something',
+      '-m',
+      'See also task(06-01-T01) which we extended here.',
+    ]);
+
+    const t1 = git.findCommitByTaskId('06-01-T01');
+    const t2 = git.findCommitByTaskId('06-01-T02');
+    assert.equal(t1, realSha, 'T01 must still resolve to the original commit, not the body-mention');
+    assert.notEqual(t1, t2);
+  });
+});
+
+test('GIT-10: revertCommit creates a forward revert commit (no history rewrite)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'a.ts', 'x');
+    git.commitTask('06-01-T01', ['a.ts'], 'task(06-01-T01): add a.ts');
+    const before = execFileSync('git', ['rev-list', '--count', 'HEAD'], { encoding: 'utf-8' }).trim();
+    const sha = git.findCommitByTaskId('06-01-T01');
+    git.revertCommit(sha);
+    const after = execFileSync('git', ['rev-list', '--count', 'HEAD'], { encoding: 'utf-8' }).trim();
+    assert.equal(Number(after), Number(before) + 1, 'revert must add a new commit, not rewrite history');
+
+    const stillThere = execFileSync('git', ['cat-file', '-t', sha], { encoding: 'utf-8' }).trim();
+    assert.equal(stillThere, 'commit');
+  });
+});
+
+test('GIT-11: restoreFiles resets working-tree changes for the given paths', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'a.ts', 'original');
+    git.commitTask('06-01-T01', ['a.ts'], 'task(06-01-T01): add a.ts');
+    fs.writeFileSync(path.join(root, 'a.ts'), 'mutated', 'utf-8');
+    git.restoreFiles(['a.ts']);
+    const content = fs.readFileSync(path.join(root, 'a.ts'), 'utf-8');
+    assert.equal(content, 'original');
+  });
+});
+
+test('GIT-12: listTaskCommits returns parsed array of {sha, subject} for a plan-id prefix', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'a.ts', 'x');
+    git.commitTask('06-01-T01', ['a.ts'], 'task(06-01-T01): first');
+    writeFile(root, 'b.ts', 'y');
+    git.commitTask('06-01-T02', ['b.ts'], 'task(06-01-T02): second');
+    const list = git.listTaskCommits('06-01');
+    assert.equal(list.length, 2);
+    for (const entry of list) {
+      assert.match(entry.sha, /^[0-9a-f]{40}$/);
+      assert.match(entry.subject, /^task\(06-01-T0[12]\):/);
+    }
+  });
+});
+
+function commitFile(root, rel, body, msg) {
+  writeFile(root, rel, body);
+  execFileSync('git', ['-C', root, 'add', '--', rel], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', msg], { stdio: 'pipe' });
+}
+
+test('GIT-SHOW-1: gitShowSafe returns file body for committed path', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'README.md', 'hello world\n', 'chore: add README');
+    const body = git.gitShowSafe('HEAD', 'README.md');
+    assert.equal(body, 'hello world\n');
+  });
+});
+
+test('GIT-SHOW-2: gitShowSafe returns null for non-existent path (Pitfall 5 exit-128)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'README.md', 'x\n', 'chore: seed');
+    const body = git.gitShowSafe('HEAD', 'no-such-file.md');
+    assert.equal(body, null);
+  });
+});
+
+test('GIT-SHOW-3: gitShowSafe returns null for path not yet in HEAD (uncommitted rename case)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'a.md', 'alpha\n', 'chore: seed');
+    const body = git.gitShowSafe('HEAD', '.planning/phases/09-feature-set/09-01-PLAN.md');
+    assert.equal(body, null);
+  });
+});
+
+test('GIT-SHOW-4: gitShowSafe returns null for git-repo-missing case (pragmatic extension of Pitfall 5 semantics)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'np-git-noregion-'));
+  const prev = process.cwd();
+  process.chdir(tmp);
+  try {
+    assert.equal(git.gitShowSafe('HEAD', 'any.md'), null);
+  } finally {
+    process.chdir(prev);
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('GIT-DIFF-1: gitDiffNoColor returns diff body starting with "diff --git" after mutation', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'README.md', 'original\n', 'chore: seed');
+    fs.writeFileSync(path.join(root, 'README.md'), 'modified\n', 'utf-8');
+    const diff = git.gitDiffNoColor('HEAD', 'README.md');
+    assert.ok(diff.startsWith('diff --git'), 'expected diff header at start, got: ' + diff.slice(0, 40));
+    assert.ok(diff.indexOf('-original') >= 0);
+    assert.ok(diff.indexOf('+modified') >= 0);
+  });
+});
+
+test('GIT-DIFF-2: gitDiffNoColor returns empty string when working tree matches HEAD', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'README.md', 'same\n', 'chore: seed');
+    const diff = git.gitDiffNoColor('HEAD', 'README.md');
+    assert.equal(diff, '');
+  });
+});
+
+test('GIT-DIFF-3: gitDiffNoColor output strips ANSI even with color.ui=always (Pitfall 6)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    commitFile(root, 'README.md', 'red\n', 'chore: seed');
+    execFileSync('git', ['-C', root, 'config', '--local', 'color.ui', 'always'], { stdio: 'pipe' });
+    fs.writeFileSync(path.join(root, 'README.md'), 'green\n', 'utf-8');
+    const diff = git.gitDiffNoColor('HEAD', 'README.md');
+    assert.ok(diff.length > 0);
+    assert.equal(diff.indexOf('\x1b'), -1, 'output must contain no ESC bytes');
+  });
+});

package/lib/install/agents-md.cjs

@@ -0,0 +1,77 @@
+const { extractFrontmatter } = require('../frontmatter.cjs');
+const { NubosPilotError } = require('../core.cjs');
+
+const DEFAULT_RUNTIME = 'codex';
+
+const FRONTMATTER_RE = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/;
+const PERMISSION_MODE_LINE_RE = /^[ \t]*permissionMode[ \t]*:.*(?:\r?\n|$)/m;
+
+function _stripPermissionMode(frontmatterBody) {
+  return frontmatterBody.replace(PERMISSION_MODE_LINE_RE, '');
+}
+
+function _resolveNotice(runtime) {
+  const { getAdapter } = require('../runtime/index.cjs');
+  const adapter = getAdapter(runtime);
+  if (typeof adapter.runtimeNotice !== 'string' || adapter.runtimeNotice.length === 0) {
+    throw new NubosPilotError(
+      'agents-md-missing-notice',
+      'Adapter for ' + runtime + ' has no runtimeNotice export',
+      { runtime },
+    );
+  }
+  return adapter.runtimeNotice;
+}
+
+function generateAgentsMd(claudeMdContent, runtime) {
+  if (typeof claudeMdContent !== 'string') {
+    throw new NubosPilotError(
+      'agents-md-invalid-input',
+      'generateAgentsMd expects a string',
+      { got: typeof claudeMdContent },
+    );
+  }
+
+  const rt = runtime || DEFAULT_RUNTIME;
+  const runtimeNotice = _resolveNotice(rt);
+
+  try {
+    extractFrontmatter(claudeMdContent);
+  } catch (err) {
+    throw new NubosPilotError(
+      'agents-md-invalid-input',
+      'generateAgentsMd could not parse frontmatter',
+      { cause: err && err.code ? err.code : String(err) },
+    );
+  }
+
+  const fmMatch = claudeMdContent.match(FRONTMATTER_RE);
+
+  if (fmMatch) {
+    const openDelim = fmMatch[1];
+    const innerYaml = fmMatch[2];
+    const closeDelim = fmMatch[3];
+    const body = claudeMdContent.slice(fmMatch[0].length);
+
+    const stripped = _stripPermissionMode(innerYaml);
+    const trimmedInner = stripped.replace(/(?:\r?\n)+$/, '');
+
+    let rebuilt;
+    if (trimmedInner.trim() === '') {
+      rebuilt = '';
+    } else {
+      rebuilt = openDelim + trimmedInner + closeDelim;
+    }
+
+    const separator = rebuilt.length === 0
+      ? ''
+      : (rebuilt.endsWith('\n') ? '' : '\n');
+    const bodyPrefix = body.startsWith('\n') ? '' : '\n';
+    return rebuilt + separator + runtimeNotice + '\n' + bodyPrefix + body;
+  }
+
+  const bodyPrefix = claudeMdContent.startsWith('\n') ? '' : '\n';
+  return runtimeNotice + '\n' + bodyPrefix + claudeMdContent;
+}
+
+module.exports = { generateAgentsMd };

package/lib/install/backup.cjs

@@ -0,0 +1,70 @@
+const fs = require('node:fs');
+const { NubosPilotError } = require('../core.cjs');
+
+const MAX_NUMBERED_BACKUPS = 99;
+
+function _refuseSymlink(filePath) {
+  let st;
+  try {
+    st = fs.lstatSync(filePath);
+  } catch (err) {
+    throw new NubosPilotError(
+      'backup-source-missing',
+      'Cannot stat file to back up: ' + (err && err.message),
+      { filePath },
+    );
+  }
+  if (st.isSymbolicLink()) {
+    throw new NubosPilotError(
+      'backup-refuses-symlink',
+      'Refusing to back up a symlink (would dereference target): ' + filePath,
+      { filePath },
+    );
+  }
+}
+
+function backupFile(filePath) {
+  _refuseSymlink(filePath);
+  const base = filePath + '.bak';
+  if (!fs.existsSync(base)) {
+    try {
+      fs.renameSync(filePath, base);
+    } catch (err) {
+      throw new NubosPilotError(
+        'backup-rename-failed',
+        'Cannot rename to .bak: ' + (err && err.message),
+        { filePath, target: base },
+      );
+    }
+    return base;
+  }
+  for (let n = 1; n <= MAX_NUMBERED_BACKUPS; n++) {
+    const candidate = `${filePath}.bak.${n}`;
+    if (!fs.existsSync(candidate)) {
+      try {
+        fs.renameSync(filePath, candidate);
+      } catch (err) {
+        throw new NubosPilotError(
+          'backup-rename-failed',
+          'Cannot rename to ' + candidate + ': ' + (err && err.message),
+          { filePath, target: candidate },
+        );
+      }
+      return candidate;
+    }
+  }
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const fallback = `${filePath}.bak.orphan-${ts}`;
+  try {
+    fs.renameSync(filePath, fallback);
+  } catch (err) {
+    throw new NubosPilotError(
+      'backup-rename-failed',
+      'Cannot rename to orphan backup: ' + (err && err.message),
+      { filePath, target: fallback },
+    );
+  }
+  return fallback;
+}
+
+module.exports = { backupFile, MAX_NUMBERED_BACKUPS };