atris 3.42.0 → 3.44.0

package/commands/caretaker.js

@@ -0,0 +1,303 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const RECEIPT_REL = path.join('.atris', 'state', 'caretaker.scan.latest.json');
+const LIST_LIMIT = '100';
+const LIST_JSON_FIELDS = ['number', 'title', 'headRefOid'].join(',');
+const DETAIL_JSON_FIELDS = [
+  'number',
+  'title',
+  'headRefOid',
+  'statusCheckRollup',
+  'reviews',
+  'latestReviews',
+  'commits',
+  'reviewDecision',
+].join(',');
+
+const FAIL_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED']);
+const FAIL_STATES = new Set(['FAILURE', 'ERROR']);
+const PASS_CONCLUSIONS = new Set(['SUCCESS', 'SKIPPED', 'NEUTRAL']);
+const PASS_STATES = new Set(['SUCCESS']);
+const PENDING_STATUSES = new Set(['QUEUED', 'IN_PROGRESS', 'PENDING', 'REQUESTED', 'WAITING', 'EXPECTED']);
+
+function runGh(args, { cwd, env } = {}) {
+  return spawnSync('gh', args, {
+    cwd: cwd || process.cwd(),
+    encoding: 'utf8',
+    env: env || process.env,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+}
+
+function printGhUnavailable() {
+  console.error('gh is missing or not signed in. install github cli and run gh auth login.');
+}
+
+function ensureGh(options = {}) {
+  const version = runGh(['--version'], options);
+  if ((version.error && version.error.code === 'ENOENT') || version.error || version.status !== 0) {
+    return false;
+  }
+  const auth = runGh(['auth', 'status'], options);
+  if ((auth.error && auth.error.code === 'ENOENT') || auth.error || auth.status !== 0) {
+    return false;
+  }
+  return true;
+}
+
+function ghFailedDetail(result, fallback) {
+  const detail = String(result.stderr || result.stdout || result.error?.message || fallback).trim();
+  return detail.split(/\r?\n/).find(Boolean) || fallback;
+}
+
+function checkName(check) {
+  if (!check || typeof check !== 'object') return '';
+  return String(check.name || check.context || '').trim();
+}
+
+function checkTime(check) {
+  const raw = check?.completedAt || check?.startedAt || check?.submittedAt || '';
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+function isFailingCheck(check) {
+  const conclusion = String(check?.conclusion || '').toUpperCase();
+  const state = String(check?.state || '').toUpperCase();
+  const status = String(check?.status || '').toUpperCase();
+  if (FAIL_CONCLUSIONS.has(conclusion) || FAIL_STATES.has(state)) return true;
+  if (status === 'COMPLETED' && conclusion && !PASS_CONCLUSIONS.has(conclusion)) return true;
+  return false;
+}
+
+function isPassingCheck(check) {
+  const conclusion = String(check?.conclusion || '').toUpperCase();
+  const state = String(check?.state || '').toUpperCase();
+  if (PASS_CONCLUSIONS.has(conclusion) || PASS_STATES.has(state)) return true;
+  return false;
+}
+
+function isPendingCheck(check) {
+  const status = String(check?.status || '').toUpperCase();
+  const state = String(check?.state || '').toUpperCase();
+  if (PENDING_STATUSES.has(status) || PENDING_STATUSES.has(state)) return true;
+  if (!check?.conclusion && !PASS_STATES.has(state) && !FAIL_STATES.has(state)) {
+    return status !== 'COMPLETED';
+  }
+  return false;
+}
+
+function latestChecks(rollup = []) {
+  const byName = new Map();
+  for (const check of Array.isArray(rollup) ? rollup : []) {
+    const name = checkName(check);
+    if (!name) continue;
+    const prev = byName.get(name);
+    if (!prev || checkTime(check) >= checkTime(prev)) byName.set(name, check);
+  }
+  return [...byName.values()];
+}
+
+function lastPushAt(pr) {
+  const commits = Array.isArray(pr?.commits) ? pr.commits : [];
+  let latest = 0;
+  let latestIso = '';
+  for (const commit of commits) {
+    const iso = commit?.committedDate || commit?.authoredDate || '';
+    const ms = Date.parse(iso);
+    if (Number.isFinite(ms) && ms >= latest) {
+      latest = ms;
+      latestIso = iso;
+    }
+  }
+  return latestIso;
+}
+
+function collectReviews(pr) {
+  const out = [];
+  for (const list of [pr?.reviews, pr?.latestReviews]) {
+    if (!Array.isArray(list)) continue;
+    for (const review of list) out.push(review);
+  }
+  return out;
+}
+
+function activeChangesRequested(pr) {
+  const pushAt = lastPushAt(pr);
+  const pushMs = Date.parse(pushAt);
+  const reviews = collectReviews(pr).filter((review) => {
+    if (String(review?.state || '').toUpperCase() !== 'CHANGES_REQUESTED') return false;
+    const submittedMs = Date.parse(review?.submittedAt || '');
+    if (!Number.isFinite(submittedMs)) return false;
+    if (!Number.isFinite(pushMs)) return true;
+    return submittedMs > pushMs;
+  });
+  return reviews;
+}
+
+function classifyPullRequest(pr) {
+  const checks = latestChecks(pr?.statusCheckRollup);
+  const failing = checks.filter(isFailingCheck);
+  if (failing.length) {
+    const name = checkName(failing[0]) || 'ci';
+    return {
+      state: 'ci-red',
+      reason: `the latest ${name} check failed`,
+    };
+  }
+
+  if (activeChangesRequested(pr).length) {
+    return {
+      state: 'changes-requested',
+      reason: 'a review asked for changes after the last push',
+    };
+  }
+
+  if (!checks.length) {
+    return {
+      state: 'waiting',
+      reason: 'no checks have reported yet',
+    };
+  }
+
+  if (checks.some(isPendingCheck)) {
+    return {
+      state: 'waiting',
+      reason: 'checks are still running',
+    };
+  }
+
+  if (checks.every(isPassingCheck)) {
+    return {
+      state: 'green-mergeable',
+      reason: 'checks passed and nothing blocks merge',
+    };
+  }
+
+  return {
+    state: 'waiting',
+    reason: 'checks or reviews are not ready to judge',
+  };
+}
+
+function formatSentence(entry) {
+  const title = String(entry.title || 'untitled').trim() || 'untitled';
+  return `pr ${entry.number} "${title}" is ${entry.state} because ${entry.reason}.`.toLowerCase();
+}
+
+function writeReceipt(root, receipt) {
+  const file = path.join(root, RECEIPT_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+  return file;
+}
+
+function listOpenPullRequestRefs(options = {}) {
+  const result = runGh([
+    'pr',
+    'list',
+    '--state',
+    'open',
+    '--limit',
+    LIST_LIMIT,
+    '--json',
+    LIST_JSON_FIELDS,
+  ], options);
+  if (result.error || result.status !== 0) {
+    throw new Error(ghFailedDetail(result, 'gh pr list failed'));
+  }
+  const raw = String(result.stdout || '').trim();
+  if (!raw) return [];
+  const parsed = JSON.parse(raw);
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+function fetchPullRequestDetail(number, options = {}) {
+  const result = runGh([
+    'pr',
+    'view',
+    String(number),
+    '--json',
+    DETAIL_JSON_FIELDS,
+  ], options);
+  if (result.error || result.status !== 0) {
+    throw new Error(ghFailedDetail(result, `gh pr view ${number} failed`));
+  }
+  const raw = String(result.stdout || '').trim();
+  if (!raw) {
+    throw new Error(`gh pr view ${number} returned empty output`);
+  }
+  return JSON.parse(raw);
+}
+
+function scanPullRequests({ cwd, env, now } = {}) {
+  const root = path.resolve(cwd || process.cwd());
+  const scannedAt = (now instanceof Date ? now : new Date()).toISOString();
+  const refs = listOpenPullRequestRefs({ cwd: root, env });
+  const prs = refs.map((ref) => {
+    const number = Number(ref.number);
+    const detail = fetchPullRequestDetail(number, { cwd: root, env });
+    const pr = {
+      ...detail,
+      number: Number(detail.number || number),
+      title: detail.title != null ? detail.title : ref.title,
+      headRefOid: detail.headRefOid || ref.headRefOid || '',
+    };
+    const classified = classifyPullRequest(pr);
+    return {
+      number: pr.number,
+      title: String(pr.title || ''),
+      state: classified.state,
+      reason: classified.reason,
+      head_sha: String(pr.headRefOid || ''),
+      scanned_at: scannedAt,
+    };
+  });
+  const receipt = { scanned_at: scannedAt, prs };
+  const receiptPath = writeReceipt(root, receipt);
+  return { root, receipt, receiptPath, prs };
+}
+
+function showCaretakerHelp() {
+  console.log('usage: atris caretaker scan');
+  console.log('classify open pull requests on origin. detection only; no fix, comment, or merge.');
+}
+
+function caretakerCommand(args = [], options = {}) {
+  const argv = Array.isArray(args) ? args.filter((arg) => arg !== '--') : [];
+  if (!argv.length || argv[0] === 'help' || argv.includes('--help') || argv.includes('-h')) {
+    showCaretakerHelp();
+    return 0;
+  }
+  if (argv[0] !== 'scan') {
+    console.error(`unknown caretaker command: ${argv[0]}`);
+    showCaretakerHelp();
+    return 1;
+  }
+
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const env = options.env || process.env;
+  if (!ensureGh({ cwd, env })) {
+    printGhUnavailable();
+    return 1;
+  }
+
+  try {
+    const { prs } = scanPullRequests({ cwd, env, now: options.now });
+    if (!prs.length) {
+      console.log('no open pull requests.');
+      return 0;
+    }
+    for (const entry of prs) console.log(formatSentence(entry));
+    return 0;
+  } catch (error) {
+    console.error(`caretaker scan failed: ${error.message || error}`);
+    return 1;
+  }
+}
+
+module.exports = { caretakerCommand };

package/commands/clean.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const escapeRegExp = require('../lib/escape-regexp');
 const { wikiMetabolismNudge } = require('../lib/wiki');
 
@@ -49,6 +50,10 @@ function cleanAtris(options = {}) {
   results.healedRefDetails = replacements;
   results.unhealableRefs = unhealable;
 
+  // 2b. Let the repo refresh and validate its own MAP.md, if it ships scripts for it
+  const mapScripts = runMapScripts(cwd, options.dryRun);
+  results.mapScripts = mapScripts;
+
   // 3. Archive old journals (>30 days)
   const archived = archiveOldJournals(atrisDir, options.dryRun);
   results.archivedJournals = archived;
@@ -127,6 +132,9 @@ function cleanAtris(options = {}) {
     console.log('✓ All MAP.md refs valid');
   }
 
+  // Repo-local map scripts
+  mapScripts.forEach(step => console.log(mapScriptLine(step)));
+
   // Archived journals
   if (archived > 0) {
     const verb = options.dryRun ? 'Would archive' : 'Archived';
@@ -185,6 +193,70 @@ function cleanAtris(options = {}) {
   return results;
 }
 
+// Repo-local MAP.md maintenance scripts, run in order when the workspace ships them.
+const MAP_SCRIPTS = [
+  {
+    file: 'refresh_map_active.py',
+    ranLabel: 'Refreshed MAP.md active files',
+    dryLabel: 'Would refresh MAP.md active files',
+    failLabel: 'MAP.md active files refresh failed',
+  },
+  {
+    file: 'validate_map.py',
+    ranLabel: 'MAP.md validation passed',
+    dryLabel: 'Would validate MAP.md',
+    failLabel: 'MAP.md validation failed',
+  },
+];
+
+/**
+ * Run the workspace's own MAP.md scripts (scripts/refresh_map_active.py, then
+ * scripts/validate_map.py) when they exist. Report-only: a failing script does
+ * not stop clean.
+ */
+function runMapScripts(cwd, dryRun = false) {
+  const steps = [];
+
+  for (const script of MAP_SCRIPTS) {
+    const scriptPath = path.join(cwd, 'scripts', script.file);
+    if (!fs.existsSync(scriptPath)) continue;
+
+    const step = { script: `scripts/${script.file}`, status: 'ok', detail: '' };
+
+    if (dryRun) {
+      step.status = 'would_run';
+      steps.push(step);
+      continue;
+    }
+
+    const proc = spawnSync('python3', [scriptPath], { cwd, encoding: 'utf8', env: process.env });
+    if (proc.error) {
+      step.status = 'skipped';
+      step.detail = proc.error.code === 'ENOENT' ? 'python3 not available' : proc.error.message;
+    } else if ((proc.status ?? 0) !== 0) {
+      step.status = 'failed';
+      step.detail = firstLine(proc.stderr) || firstLine(proc.stdout) || `exit ${proc.status}`;
+    }
+
+    steps.push(step);
+  }
+
+  return steps;
+}
+
+function firstLine(text) {
+  if (!text) return '';
+  return String(text).split('\n').map(l => l.trim()).find(l => l.length > 0) || '';
+}
+
+function mapScriptLine(step) {
+  const script = MAP_SCRIPTS.find(s => step.script.endsWith(s.file));
+  if (step.status === 'would_run') return `✓ ${script.dryLabel} (${step.script})`;
+  if (step.status === 'skipped') return `○ Skipped ${step.script} — ${step.detail}`;
+  if (step.status === 'failed') return `✗ ${script.failLabel} — ${step.detail}`;
+  return `✓ ${script.ranLabel}`;
+}
+
 function cleanResultPayload(results, options = {}, cwd = process.cwd()) {
   const manualAction = [];
   if (results.staleTasks.length > 0) manualAction.push('Delete stale tasks or finish them');
@@ -227,6 +299,10 @@ function cleanResultPayload(results, options = {}, cwd = process.cwd()) {
         items: results.deadFiles || [],
         test_only: results.testOnlyFiles || [],
       },
+      map_scripts: {
+        count: (results.mapScripts || []).length,
+        items: results.mapScripts || [],
+      },
     },
     manual_action: manualAction,
   };

package/commands/engine-watch.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_TAIL_LINES = 20;
+const DEFAULT_POLL_MS = 250;
+const MAX_TAIL_BYTES = 128 * 1024;
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code !== 'ESRCH';
+  }
+}
+
+function readReceipt(receiptPath, fsModule = fs) {
+  try {
+    const receipt = JSON.parse(fsModule.readFileSync(receiptPath, 'utf8'));
+    return receipt && typeof receipt === 'object' ? receipt : null;
+  } catch {
+    return null;
+  }
+}
+
+function receiptStartedMs(receipt, stat) {
+  const parsed = Date.parse(receipt.started_at || receipt.at || '');
+  return Number.isFinite(parsed) ? parsed : stat.mtimeMs;
+}
+
+function listWatchableReceipts(root, fsModule = fs) {
+  const runsDir = path.join(root, 'atris', 'runs');
+  let names;
+  try {
+    names = fsModule.readdirSync(runsDir).filter((name) => name.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const name of names) {
+    const receiptPath = path.join(runsDir, name);
+    const receipt = readReceipt(receiptPath, fsModule);
+    if (!receipt || !receipt.live_log) continue;
+    let stat;
+    try { stat = fsModule.statSync(receiptPath); } catch { continue; }
+    rows.push({
+      id: path.basename(name, '.json'),
+      receipt,
+      receiptPath,
+      startedMs: receiptStartedMs(receipt, stat),
+    });
+  }
+  return rows.sort((left, right) => right.startedMs - left.startedMs);
+}
+
+function resolveWatchReceipt(root, id, fsModule = fs) {
+  const rows = listWatchableReceipts(root, fsModule);
+  if (id === 'latest') return rows[0] || null;
+  const wanted = String(id || '').replace(/\.json$/, '');
+  return rows.find((row) => row.id === wanted || row.receipt.id === id) || null;
+}
+
+function liveLogPathForReceipt(root, row) {
+  const value = String(row.receipt.live_log || '');
+  return path.isAbsolute(value) ? value : path.resolve(root, value);
+}
+
+function receiptDisplayStatus(receipt, pidIsAlive = processIsAlive) {
+  const status = String(receipt.status || 'unknown').trim().toLowerCase();
+  if (status === 'running' && !pidIsAlive(Number(receipt.pid))) return 'presumed dead';
+  return status;
+}
+
+function formatAge(value, nowMs = Date.now()) {
+  const elapsedMs = Math.max(0, nowMs - Number(value || 0));
+  const seconds = Math.floor(elapsedMs / 1000);
+  if (seconds < 2) return 'now';
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+function lastLogAge(root, row, nowMs, fsModule = fs) {
+  try {
+    const logPath = liveLogPathForReceipt(root, row);
+    const stat = fsModule.statSync(logPath);
+    if (stat.size === 0) return 'none';
+    return formatAge(stat.mtimeMs, nowMs);
+  } catch {
+    return 'none';
+  }
+}
+
+function readLastLines(filePath, count = DEFAULT_TAIL_LINES, fsModule = fs) {
+  let descriptor;
+  try {
+    const stat = fsModule.statSync(filePath);
+    if (!stat.size) return [];
+    const bytes = Math.min(stat.size, MAX_TAIL_BYTES);
+    const start = stat.size - bytes;
+    const buffer = Buffer.alloc(bytes);
+    descriptor = fsModule.openSync(filePath, 'r');
+    fsModule.readSync(descriptor, buffer, 0, bytes, start);
+    const lines = buffer.toString('utf8').split(/\r?\n/);
+    if (start > 0) lines.shift();
+    if (lines[lines.length - 1] === '') lines.pop();
+    return lines.slice(-count);
+  } catch {
+    return [];
+  } finally {
+    if (descriptor !== undefined) fsModule.closeSync(descriptor);
+  }
+}
+
+function writeNewLogBytes(filePath, offset, write, fsModule = fs) {
+  let descriptor;
+  try {
+    const stat = fsModule.statSync(filePath);
+    let position = stat.size < offset ? 0 : offset;
+    if (stat.size <= position) return position;
+    descriptor = fsModule.openSync(filePath, 'r');
+    const buffer = Buffer.alloc(64 * 1024);
+    while (position < stat.size) {
+      const bytes = fsModule.readSync(descriptor, buffer, 0, Math.min(buffer.length, stat.size - position), position);
+      if (!bytes) break;
+      write(buffer.subarray(0, bytes).toString('utf8'));
+      position += bytes;
+    }
+    return position;
+  } catch {
+    return offset;
+  } finally {
+    if (descriptor !== undefined) fsModule.closeSync(descriptor);
+  }
+}
+
+function followReceipt(row, root, deps = {}) {
+  const fsModule = deps.fs || fs;
+  const pidIsAlive = deps.pidIsAlive || processIsAlive;
+  const write = deps.write || process.stdout.write.bind(process.stdout);
+  const pollMs = deps.pollMs || DEFAULT_POLL_MS;
+  const liveLogPath = liveLogPathForReceipt(root, row);
+  let offset = 0;
+  try { offset = fsModule.statSync(liveLogPath).size; } catch {}
+  return new Promise((resolve) => {
+    const interval = setInterval(() => {
+      offset = writeNewLogBytes(liveLogPath, offset, write, fsModule);
+      const receipt = readReceipt(row.receiptPath, fsModule);
+      if (!receipt || receiptDisplayStatus(receipt, pidIsAlive) !== 'running') {
+        offset = writeNewLogBytes(liveLogPath, offset, write, fsModule);
+        clearInterval(interval);
+        resolve(0);
+      }
+    }, pollMs);
+  });
+}
+
+function printRunningRoster(root, deps = {}) {
+  const fsModule = deps.fs || fs;
+  const pidIsAlive = deps.pidIsAlive || processIsAlive;
+  const log = deps.log || console.log;
+  const nowMs = deps.nowMs === undefined ? Date.now() : deps.nowMs;
+  const rows = listWatchableReceipts(root, fsModule)
+    .filter((row) => String(row.receipt.status || '').toLowerCase() === 'running');
+  if (!rows.length) {
+    log('no engine work is running.');
+    return 0;
+  }
+  for (const row of rows) {
+    const engine = String(row.receipt.engine || 'unknown');
+    const status = receiptDisplayStatus(row.receipt, pidIsAlive);
+    const started = row.receipt.started_at || row.receipt.at || 'unknown';
+    log(`${row.id}  ${engine}  ${status}  started ${started}  last log ${lastLogAge(root, row, nowMs, fsModule)}`);
+  }
+  return 0;
+}
+
+async function runEngineWatchCommand(args = [], root = process.cwd(), deps = {}) {
+  const fsModule = deps.fs || fs;
+  const pidIsAlive = deps.pidIsAlive || processIsAlive;
+  const log = deps.log || console.log;
+  const noFollow = args.includes('--no-follow');
+  const id = args.find((arg) => !String(arg).startsWith('--')) || '';
+  if (!id) return printRunningRoster(root, deps);
+
+  const row = resolveWatchReceipt(root, id, fsModule);
+  if (!row) {
+    log(`engine watch: no receipt found for ${id}`);
+    return 2;
+  }
+  const status = receiptDisplayStatus(row.receipt, pidIsAlive);
+  const engine = String(row.receipt.engine || 'unknown');
+  const started = row.receipt.started_at || row.receipt.at || 'unknown';
+  log(`${row.id}  ${engine}  ${status}  started ${started}`);
+  const liveLogPath = liveLogPathForReceipt(root, row);
+  const lines = readLastLines(liveLogPath, DEFAULT_TAIL_LINES, fsModule);
+  if (lines.length) lines.forEach((line) => log(line));
+  else log('no live output yet.');
+
+  if (noFollow || status !== 'running') return 0;
+  return followReceipt(row, root, deps);
+}
+
+module.exports = {
+  runEngineWatchCommand,
+};