ninja-terminals 2.3.1 → 2.3.2

package/ninja-ensure.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+  SESSION_FILE,
+  SESSION_DIR,
+  readRuntimeSession,
+  healthCheckSession,
+  writeRuntimeSession,
+  requestJson,
+} = require('./lib/runtime-session');
+
+const LOG_FILE = path.join(SESSION_DIR, 'ninja-server.log');
+const PROJECT_ROOT = __dirname;
+
+const PROBE_PORTS = [3300, 3301, 3302, 3303, 3304, 3305, 3306, 3307, 3308, 3309, 3310];
+const AUTH_WAIT_MS = 15000;
+const AUTH_POLL_MS = 500;
+
+const USAGE = `
+ninja-ensure — Start, discover, or recover a dispatch-ready Ninja Terminal runtime
+
+Usage:
+  ninja-ensure                Start/discover/recover, open browser, wait for auth
+  ninja-ensure --no-open      Start/discover/recover, don't open browser
+  ninja-ensure --allow-no-auth  Allow success without authToken (dispatch will fail)
+  ninja-ensure --dry-run      Report what would happen, no action
+  ninja-ensure --help         Show this help
+
+Dispatch-ready means:
+  - Ninja Terminal server is running and healthy
+  - Session file exists with correct URL
+  - authToken is available for CLI dispatch (ninja-dispatch, agent-send)
+
+If authToken is missing, run: ninja-login
+
+Probed ports: ${PROBE_PORTS.join(', ')}
+Also probes NINJA_PORT if set.
+
+Session file: ${SESSION_FILE}
+`;
+
+function log(msg) {
+  console.log(msg);
+}
+
+function chromeHasUrl(url) {
+  if (process.platform !== 'darwin') return false;
+  try {
+    const script = `
+      tell application "Google Chrome"
+        repeat with w in windows
+          repeat with t in tabs of w
+            if URL of t contains "${url}" then return "found"
+          end repeat
+        end repeat
+      end tell
+      return "not_found"
+    `;
+    const result = execSync(`osascript -e '${script}'`, { encoding: 'utf8', timeout: 3000 }).trim();
+    return result === 'found';
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  if (process.platform === 'darwin') {
+    if (chromeHasUrl(url)) {
+      log('Browser already has Ninja Terminal open');
+      return true;
+    }
+    try {
+      execSync(`open -a "Google Chrome" "${url}"`, { stdio: 'ignore' });
+      return true;
+    } catch {
+      try {
+        execSync(`open "${url}"`, { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+  const cmd = process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    execSync(`${cmd} "${url}"`, { stdio: 'ignore', shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getTokenFromSources(session) {
+  if (process.env.NINJA_AUTH_TOKEN) return process.env.NINJA_AUTH_TOKEN;
+  if (session?.authToken) return session.authToken;
+  const tokenPath = path.join(os.homedir(), '.ninja', 'token');
+  if (fs.existsSync(tokenPath)) {
+    return fs.readFileSync(tokenPath, 'utf8').trim();
+  }
+  return null;
+}
+
+async function waitForAuthToken(timeoutMs = AUTH_WAIT_MS, pollMs = AUTH_POLL_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const session = readRuntimeSession();
+    const token = getTokenFromSources(session);
+    if (token) return token;
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+  return null;
+}
+
+async function printTerminalStatus(session, token) {
+  if (!token) return;
+  try {
+    const res = await requestJson({
+      host: session.host || 'localhost',
+      port: session.port,
+      path: '/api/terminals',
+      token,
+    });
+    if (res.statusCode === 200 && Array.isArray(res.body)) {
+      for (const t of res.body) {
+        const parts = [`T${t.id}`, t.label || '', t.status || 'unknown'];
+        if (t.taskName) parts.push(`— ${t.taskName}`);
+        log(parts.filter(Boolean).join(' '));
+      }
+    }
+  } catch {
+    // Ignore — summary not critical
+  }
+}
+
+async function probePort(port, host = 'localhost') {
+  const session = { host, port };
+  const health = await healthCheckSession(session, 2000);
+  if (health.ok && health.response?.status === 'ok' && typeof health.response?.terminals === 'number') {
+    return { port, host, terminals: health.response.terminals };
+  }
+  return null;
+}
+
+async function probeForOrphanedServer() {
+  const portsToProbe = [...PROBE_PORTS];
+
+  if (process.env.NINJA_PORT) {
+    const envPort = parseInt(process.env.NINJA_PORT, 10);
+    if (!isNaN(envPort) && !portsToProbe.includes(envPort)) {
+      portsToProbe.unshift(envPort);
+    }
+  }
+
+  const results = await Promise.all(portsToProbe.map(port => probePort(port)));
+  const found = results.find(r => r !== null);
+  return found || null;
+}
+
+function recoverSessionFile(port, host = 'localhost') {
+  const url = `http://${host}:${port}`;
+  const session = writeRuntimeSession({
+    port,
+    url,
+    cwd: process.cwd(),
+    terminals: 4,
+    command: 'ninja-ensure',
+    recovered: true,
+    recoveredAt: new Date().toISOString(),
+    pid: null, // Don't claim a pid we don't own
+  });
+  return session;
+}
+
+async function waitForSession(timeoutMs = 20000, pollMs = 300) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const session = readRuntimeSession();
+    if (session?.port) {
+      const health = await healthCheckSession(session);
+      if (health.ok) return session;
+    }
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+  return null;
+}
+
+async function startServer() {
+  fs.mkdirSync(SESSION_DIR, { recursive: true });
+  const logStream = fs.openSync(LOG_FILE, 'a');
+
+  const child = spawn('node', ['server.js'], {
+    cwd: PROJECT_ROOT,
+    env: {
+      ...process.env,
+      NINJA_OPEN_BROWSER: 'false',
+    },
+    detached: true,
+    stdio: ['ignore', logStream, logStream],
+  });
+
+  child.unref();
+  fs.closeSync(logStream);
+
+  log(`Started server (pid ${child.pid}), waiting for ready...`);
+  log(`Logs: ${LOG_FILE}`);
+
+  const session = await waitForSession(20000);
+  if (!session) {
+    throw new Error('Server failed to start within 20 seconds. Check logs: ' + LOG_FILE);
+  }
+
+  return session;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  const noOpen = args.includes('--no-open');
+  const dryRun = args.includes('--dry-run');
+  const allowNoAuth = args.includes('--allow-no-auth');
+
+  // Step 1: Check existing session file
+  const existingSession = readRuntimeSession();
+  let session = null;
+  let action = 'none';
+
+  if (existingSession?.port) {
+    const health = await healthCheckSession(existingSession);
+    if (health.ok) {
+      session = existingSession;
+      action = 'reuse';
+    }
+  }
+
+  // Step 2: If no healthy session, probe for orphaned server
+  if (!session) {
+    log('No healthy session file. Probing for orphaned Ninja server...');
+    const orphaned = await probeForOrphanedServer();
+    if (orphaned) {
+      action = 'recover';
+      if (!dryRun) {
+        session = recoverSessionFile(orphaned.port, orphaned.host);
+        log(`Recovered orphaned runtime: http://${orphaned.host}:${orphaned.port}`);
+      } else {
+        session = { port: orphaned.port, host: orphaned.host, url: `http://${orphaned.host}:${orphaned.port}` };
+      }
+    } else {
+      action = 'start';
+    }
+  }
+
+  // Dry run reporting
+  if (dryRun) {
+    const existingToken = getTokenFromSources(existingSession);
+    if (action === 'reuse') {
+      log(`[dry-run] Would reuse existing runtime at ${existingSession.url}`);
+      log(`[dry-run] authToken present: ${!!existingToken}`);
+    } else if (action === 'recover') {
+      log(`[dry-run] Would recover orphaned runtime at ${session.url}`);
+      log(`[dry-run] Would repair session file: ${SESSION_FILE}`);
+      log(`[dry-run] authToken will be missing (browser sync required)`);
+    } else {
+      log(`[dry-run] No runtime found on probed ports`);
+      log(`[dry-run] Would start new server from ${PROJECT_ROOT}`);
+    }
+    log(`[dry-run] Would open browser: ${!noOpen}`);
+    process.exit(0);
+  }
+
+  // Step 3: Start new server if needed
+  if (action === 'start') {
+    session = await startServer();
+    log(`Server ready on ${session.url}`);
+  } else if (action === 'reuse') {
+    log(`Runtime already active: ${session.url}`);
+  }
+  // action === 'recover' already logged above
+
+  // Step 4: Open browser
+  if (!noOpen) {
+    const opened = openBrowser(session.url);
+    if (opened) {
+      log(`Opened: ${session.url}`);
+    } else {
+      log(`Browser open failed — navigate manually to ${session.url}`);
+    }
+  }
+
+  log(`Session file: ${SESSION_FILE}`);
+
+  // Step 5: Check dispatch readiness (authToken)
+  let token = getTokenFromSources(session);
+
+  if (!token && !noOpen) {
+    log('Waiting for auth token... (run ninja-login if this hangs)');
+    token = await waitForAuthToken(AUTH_WAIT_MS, AUTH_POLL_MS);
+    if (token) {
+      session = readRuntimeSession(); // Re-read with updated token
+    }
+  }
+
+  if (token) {
+    log('Dispatch ready');
+    await printTerminalStatus(session, token);
+    process.exit(0);
+  } else {
+    if (allowNoAuth) {
+      log('Warning: authToken missing. Run: ninja-login');
+      log('Runtime is running but CLI dispatch is NOT ready');
+      process.exit(0);
+    } else {
+      log('Error: authToken missing — dispatch will fail');
+      log('Open browser and login, then rerun ninja-ensure');
+      log('Or use --allow-no-auth to skip this check');
+      process.exit(1);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/ninja-gate.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const {
+  SESSION_FILE,
+  LEDGER_FILE,
+  VERIFICATION_LEDGER_FILE,
+  VISUAL_LEDGER_FILE,
+  readRuntimeSession,
+  readAuthToken,
+  healthCheckSession,
+  requestJson,
+} = require('./lib/runtime-session');
+
+const USAGE = `
+Usage:
+  ninja-gate [--since <duration|iso>] [--json]
+
+Validates Ninja Terminal evidence without relying on Claude hooks.
+
+Checks:
+  - Runtime session exists and /health passes
+  - At least one successful dispatch exists after --since
+  - pre-dispatch visual exists between --since and latest dispatch
+  - verification exists after latest dispatch
+  - post-output/final-visual exists after latest verification
+  - dispatched terminals have terminal taskStatus done/blocked/error when API is available
+
+Examples:
+  ninja-gate --since 20m
+  ninja-gate --since 2026-05-03T17:00:00.000Z --json
+`;
+
+const COMPLETE_TASK_STATES = ['done', 'blocked', 'error'];
+const POST_VISUAL_STAGES = ['post-output', 'final-visual'];
+
+function readNdjson(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    return raw.trim().split('\n').filter(Boolean).map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function parseSinceArg(value, now = Date.now()) {
+  if (!value) return new Date(now - 20 * 60 * 1000).toISOString();
+
+  const duration = String(value).trim().match(/^(\d+)(ms|s|m|h|d)$/i);
+  if (duration) {
+    const amount = Number.parseInt(duration[1], 10);
+    const unit = duration[2].toLowerCase();
+    const factors = {
+      ms: 1,
+      s: 1000,
+      m: 60 * 1000,
+      h: 60 * 60 * 1000,
+      d: 24 * 60 * 60 * 1000,
+    };
+    return new Date(now - amount * factors[unit]).toISOString();
+  }
+
+  const parsed = Date.parse(value);
+  if (!Number.isNaN(parsed)) return new Date(parsed).toISOString();
+
+  throw new Error(`Invalid --since value: ${value}`);
+}
+
+function isAfter(timestamp, afterTs) {
+  return Boolean(timestamp && timestamp > afterTs);
+}
+
+function isBetween(timestamp, startTs, endTs) {
+  return Boolean(timestamp && timestamp > startTs && timestamp < endTs);
+}
+
+function getTaskStatusTimestamp(status) {
+  return status?.updatedAt || status?.taskStatusUpdatedAt || status?.timestamp || null;
+}
+
+function evaluateEvidence({ sinceTs, dispatchEntries, verificationEntries, visualEntries, taskStatuses }) {
+  const failures = [];
+  const warnings = [];
+
+  const successfulDispatches = dispatchEntries
+    .filter(e => e.success === true && isAfter(e.timestamp, sinceTs))
+    .sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+
+  if (successfulDispatches.length === 0) {
+    failures.push(`No successful dispatch found after ${sinceTs}`);
+  }
+
+  const latestDispatch = successfulDispatches[successfulDispatches.length - 1] || null;
+  const dispatchedTerminalIds = [...new Set(successfulDispatches.map(e => String(e.terminalId)).filter(Boolean))];
+  const latestDispatchByTerminalId = new Map();
+  for (const dispatch of successfulDispatches) {
+    const terminalId = String(dispatch.terminalId);
+    const previous = latestDispatchByTerminalId.get(terminalId);
+    if (!previous || String(dispatch.timestamp).localeCompare(String(previous.timestamp)) > 0) {
+      latestDispatchByTerminalId.set(terminalId, dispatch);
+    }
+  }
+
+  let preVisual = null;
+  let latestVerification = null;
+  let postVisual = null;
+
+  if (latestDispatch) {
+    preVisual = visualEntries
+      .filter(e => e.stage === 'pre-dispatch' && isBetween(e.timestamp, sinceTs, latestDispatch.timestamp))
+      .sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)))
+      .at(-1) || null;
+
+    if (!preVisual) {
+      failures.push('Missing pre-dispatch visual entry between --since and latest dispatch');
+    }
+
+    latestVerification = verificationEntries
+      .filter(e => isAfter(e.timestamp, latestDispatch.timestamp))
+      .sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)))
+      .at(-1) || null;
+
+    if (!latestVerification) {
+      failures.push('Missing verification entry after latest dispatch');
+    }
+  }
+
+  if (latestVerification) {
+    postVisual = visualEntries
+      .filter(e => POST_VISUAL_STAGES.includes(e.stage) && isAfter(e.timestamp, latestVerification.timestamp))
+      .sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)))
+      .at(-1) || null;
+
+    if (!postVisual) {
+      failures.push('Missing post-output/final-visual entry after latest verification');
+    }
+  }
+
+  const taskStatusById = new Map();
+  for (const status of taskStatuses || []) {
+    if (status && status.id !== undefined) taskStatusById.set(String(status.id), status);
+  }
+
+  const incompleteTaskStatuses = [];
+  if (taskStatuses === null) {
+    warnings.push('Task status API unavailable; skipped semantic task status check');
+  } else {
+    for (const terminalId of dispatchedTerminalIds) {
+      const status = taskStatusById.get(String(terminalId));
+      if (!status) {
+        incompleteTaskStatuses.push({ terminalId, taskStatus: 'missing' });
+        continue;
+      }
+
+      const state = status.taskStatus || status.state || 'unknown';
+      if (!COMPLETE_TASK_STATES.includes(state)) {
+        incompleteTaskStatuses.push({ terminalId, taskStatus: state });
+        continue;
+      }
+
+      const taskUpdatedAt = getTaskStatusTimestamp(status);
+      const terminalDispatch = latestDispatchByTerminalId.get(String(terminalId)) || latestDispatch;
+      if (terminalDispatch && (!taskUpdatedAt || taskUpdatedAt <= terminalDispatch.timestamp)) {
+        incompleteTaskStatuses.push({ terminalId, taskStatus: `${state} (stale)` });
+      }
+    }
+
+    if (incompleteTaskStatuses.length > 0) {
+      failures.push(`Incomplete task status for terminal(s): ${
+        incompleteTaskStatuses.map(t => `T${t.terminalId}=${t.taskStatus}`).join(', ')
+      }`);
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    sinceTs,
+    failures,
+    warnings,
+    summary: {
+      successfulDispatches: successfulDispatches.length,
+      latestDispatch,
+      latestVerification,
+      preVisual,
+      postVisual,
+      dispatchedTerminalIds,
+      latestDispatchByTerminalId: Object.fromEntries(latestDispatchByTerminalId),
+      incompleteTaskStatuses,
+    },
+  };
+}
+
+function parseArgs(argv) {
+  const opts = {
+    since: null,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--since') {
+      opts.since = argv[++i];
+      if (!opts.since) throw new Error('--since requires a value');
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+async function fetchTaskStatuses(session, token) {
+  if (!token) return null;
+  const res = await requestJson({
+    host: session.host || 'localhost',
+    port: session.port,
+    path: '/api/terminals/task-status',
+    token,
+    timeoutMs: 3000,
+  });
+  if (res.statusCode !== 200 || !Array.isArray(res.body)) return null;
+  return res.body;
+}
+
+function printHuman(result, runtime) {
+  if (result.ok) {
+    console.log('Ninja gate: PASS');
+  } else {
+    console.log('Ninja gate: FAIL');
+  }
+
+  console.log(`Since: ${result.sinceTs}`);
+  if (runtime?.url) console.log(`Runtime: ${runtime.url}`);
+
+  const latestDispatch = result.summary.latestDispatch;
+  if (latestDispatch) {
+    console.log(`Latest dispatch: ${latestDispatch.timestamp} T${latestDispatch.terminalId}`);
+  }
+
+  const latestVerification = result.summary.latestVerification;
+  if (latestVerification) {
+    console.log(`Latest verification: ${latestVerification.timestamp} ${latestVerification.type || ''}`.trim());
+  }
+
+  if (result.summary.preVisual) {
+    console.log(`Pre visual: ${result.summary.preVisual.timestamp} ${result.summary.preVisual.stage}`);
+  }
+  if (result.summary.postVisual) {
+    console.log(`Post visual: ${result.summary.postVisual.timestamp} ${result.summary.postVisual.stage}`);
+  }
+
+  if (result.warnings.length > 0) {
+    console.log('\nWarnings:');
+    for (const warning of result.warnings) console.log(`- ${warning}`);
+  }
+
+  if (result.failures.length > 0) {
+    console.log('\nMissing evidence:');
+    for (const failure of result.failures) console.log(`- ${failure}`);
+  }
+}
+
+async function runCli(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const sinceTs = parseSinceArg(opts.since);
+  const session = readRuntimeSession();
+  const token = process.env.NINJA_AUTH_TOKEN || session?.authToken || readAuthToken();
+  const runtimeFailures = [];
+  let health = null;
+  let taskStatuses = null;
+
+  if (!session || !session.port) {
+    runtimeFailures.push(`No runtime session found at ${SESSION_FILE}`);
+  } else {
+    health = await healthCheckSession(session);
+    if (!health.ok) {
+      runtimeFailures.push(`Runtime health check failed: ${health.error}`);
+    } else {
+      taskStatuses = await fetchTaskStatuses(session, token);
+    }
+  }
+
+  const result = evaluateEvidence({
+    sinceTs,
+    dispatchEntries: readNdjson(LEDGER_FILE),
+    verificationEntries: readNdjson(VERIFICATION_LEDGER_FILE),
+    visualEntries: readNdjson(VISUAL_LEDGER_FILE),
+    taskStatuses,
+  });
+
+  result.failures.unshift(...runtimeFailures);
+  result.ok = result.failures.length === 0;
+  result.runtime = {
+    sessionFile: SESSION_FILE,
+    url: session?.url || null,
+    health: health?.ok === true ? 'ok' : 'failed',
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result, session);
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+if (require.main === module) {
+  runCli().then((code) => {
+    process.exit(code);
+  }).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  COMPLETE_TASK_STATES,
+  POST_VISUAL_STAGES,
+  evaluateEvidence,
+  getTaskStatusTimestamp,
+  parseSinceArg,
+  runCli,
+};