refacil-sdd-ai 5.2.2 → 5.3.0

package/bin/postinstall.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Only auto-reinstall if a previous `init` was done — indicated by selected-ides.json
+const selPath = path.join(os.homedir(), '.refacil-sdd-ai', 'selected-ides.json');
+if (!fs.existsSync(selPath)) process.exit(0);
+
+const { execFileSync } = require('child_process');
+try {
+  execFileSync(process.execPath, [path.join(__dirname, 'cli.js'), 'update'], {
+    stdio: 'inherit',
+    timeout: 120000,
+  });
+} catch (_) {
+  // Non-fatal: postinstall must never break npm install
+}

package/lib/bus/broker.js

@@ -6,13 +6,17 @@ const crypto = require('crypto');
 
 const HOME_DIR = path.join(os.homedir(), '.refacil-sdd-ai');
 const BUS_INFO_PATH = path.join(HOME_DIR, 'bus.json');
+const BUS_STARTUP_ERROR_PATH = path.join(HOME_DIR, 'bus-startup-error.json');
 const SESSIONS_PATH = path.join(HOME_DIR, 'sessions.json');
+const BUS_INFO_OWNER = 'refacil-sdd-ai';
+const BUS_INFO_SERVICE = 'refacil-bus';
 
 const PORT_CANDIDATES = [7821, 7822, 7823];
 const HOST = '127.0.0.1';
 
 const storage = require('./storage');
 const { askHasMatchingReply } = require('./askFulfillment');
+// session.js is lazy-required inside serveReadSpecApi to avoid crashing the CLI on every invocation
 
 let WebSocketServer;
 try {
@@ -27,7 +31,10 @@ function ensureHomeDir() {
 
 function writeBusInfo(port) {
   ensureHomeDir();
+  removeBusStartupError();
   const info = {
+    owner: BUS_INFO_OWNER,
+    service: BUS_INFO_SERVICE,
     port,
     pid: process.pid,
     startedAt: new Date().toISOString(),
@@ -36,6 +43,26 @@ function writeBusInfo(port) {
   return info;
 }
 
+function writeBusStartupError(err) {
+  ensureHomeDir();
+  const payload = {
+    pid: process.pid,
+    code: err && err.code ? err.code : null,
+    message: err && err.message ? err.message : String(err),
+    ts: new Date().toISOString(),
+  };
+  fs.writeFileSync(BUS_STARTUP_ERROR_PATH, JSON.stringify(payload, null, 2) + '\n');
+  return payload;
+}
+
+function removeBusStartupError() {
+  try {
+    fs.unlinkSync(BUS_STARTUP_ERROR_PATH);
+  } catch (_) {
+    // ignore
+  }
+}
+
 function removeBusInfo() {
   try {
     fs.unlinkSync(BUS_INFO_PATH);
@@ -74,6 +101,23 @@ function tryListen(server, port) {
 }
 
 async function pickPort(server) {
+  // If REFACIL_BUS_PORT is set, use it exclusively:
+  //   - "0" → bind an OS-assigned ephemeral port (port 0)
+  //   - any other numeric string → use that fixed port
+  const envPort = process.env.REFACIL_BUS_PORT;
+  if (envPort !== undefined) {
+    const portNum = parseInt(envPort, 10);
+    if (!Number.isNaN(portNum) && portNum >= 0) {
+      await tryListen(server, portNum);
+      // When port 0 is requested the OS assigns the actual port; read it back.
+      if (portNum === 0) {
+        return server.address().port;
+      }
+      return portNum;
+    }
+  }
+
+  // Default: try each candidate in order.
   for (const port of PORT_CANDIDATES) {
     try {
       await tryListen(server, port);
@@ -83,9 +127,16 @@ async function pickPort(server) {
       throw err;
     }
   }
-  throw new Error(
-    `No hay puertos disponibles (intentados: ${PORT_CANDIDATES.join(', ')})`,
+
+  // If all fixed candidates are occupied by external processes, bind an
+  // OS-assigned port instead of killing or blaming those processes.
+  await tryListen(server, 0);
+  const ephemeralPort = server.address().port;
+  process.stderr.write(
+    `[refacil-bus] All fixed port candidates (${PORT_CANDIDATES.join(', ')}) are occupied by external processes. ` +
+    `Broker started on ephemeral port ${ephemeralPort}.\n`,
   );
+  return ephemeralPort;
 }
 
 function newId() {
@@ -481,15 +532,60 @@ function onClose(state, ws) {
 }
 
 const UI_DIR = path.join(__dirname, 'ui');
+const READ_SPEC_UI_DIR = path.join(__dirname, '..', 'spec-reader', 'ui');
 const UI_MIME = {
   '.html': 'text/html; charset=utf-8',
   '.css': 'text/css; charset=utf-8',
   '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
   '.svg': 'image/svg+xml',
   '.png': 'image/png',
   '.ico': 'image/x-icon',
 };
 
+function serveReadSpecApi(sessionId, res) {
+  const { readSession, isValidSessionId } = require('../spec-reader/session');
+  if (!isValidSessionId(sessionId)) {
+    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: 'invalid session id' }));
+    return;
+  }
+  const payload = readSession(sessionId);
+  if (!payload) {
+    res.writeHead(404, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: 'session not found' }));
+    return;
+  }
+  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(payload));
+}
+
+function serveReadSpecUi(req, res) {
+  let urlPath = req.url.split('?')[0];
+  if (urlPath === '/read-spec' || urlPath === '/read-spec/') {
+    urlPath = '/read-spec/index.html';
+  }
+  const rel = urlPath.replace(/^\/read-spec\/?/, '');
+  const safePath = rel.replace(/\.\./g, '');
+  const filePath = path.join(READ_SPEC_UI_DIR, safePath || 'index.html');
+  if (!filePath.startsWith(READ_SPEC_UI_DIR)) {
+    res.writeHead(403);
+    res.end('forbidden');
+    return;
+  }
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end('not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const mime = UI_MIME[ext] || 'application/octet-stream';
+    res.writeHead(200, { 'content-type': mime });
+    res.end(data);
+  });
+}
+
 function serveUi(req, res) {
   let urlPath = req.url.split('?')[0];
   if (urlPath === '/' || urlPath === '') urlPath = '/index.html';
@@ -515,9 +611,11 @@ function serveUi(req, res) {
 
 async function start() {
   if (!WebSocketServer) {
-    throw new Error(
+    const err = new Error(
       "Dependencia 'ws' no encontrada. Instala con: npm install -g ws (o npm install ws en el paquete)",
     );
+    err.code = 'WS_MISSING';
+    throw err;
   }
 
   const state = createState();
@@ -542,6 +640,16 @@ async function start() {
 
   const server = http.createServer((req, res) => {
     if (req.method === 'GET') {
+      const urlPath = req.url.split('?')[0];
+      const apiMatch = urlPath.match(/^\/api\/read-spec\/([^/]+)$/);
+      if (apiMatch) {
+        serveReadSpecApi(apiMatch[1], res);
+        return;
+      }
+      if (urlPath === '/read-spec' || urlPath.startsWith('/read-spec/')) {
+        serveReadSpecUi(req, res);
+        return;
+      }
       serveUi(req, res);
       return;
     }
@@ -578,11 +686,18 @@ async function start() {
 
 module.exports = {
   start,
+  serveReadSpecApi,
+  serveReadSpecUi,
   BUS_INFO_PATH,
+  BUS_STARTUP_ERROR_PATH,
+  BUS_INFO_OWNER,
+  BUS_INFO_SERVICE,
   SESSIONS_PATH,
   HOME_DIR,
   PORT_CANDIDATES,
   HOST,
+  writeBusStartupError,
+  removeBusStartupError,
 };
 
 if (require.main === module) {
@@ -593,6 +708,9 @@ if (require.main === module) {
       );
     })
     .catch((err) => {
+      try {
+        writeBusStartupError(err);
+      } catch (_) {}
       process.stderr.write(`Error arrancando broker: ${err.message}\n`);
       process.exit(1);
     });

package/lib/bus/spawn.js

@@ -1,121 +1,189 @@
-const fs = require('fs');
-const path = require('path');
-const net = require('net');
-const { spawn } = require('child_process');
-const { BUS_INFO_PATH, HOST } = require('./broker');
-
-function readBusInfo() {
-  try {
-    const raw = fs.readFileSync(BUS_INFO_PATH, 'utf8');
-    return JSON.parse(raw);
-  } catch (_) {
-    return null;
-  }
-}
-
-function isProcessAlive(pid) {
-  if (!pid) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
-}
-
-function checkPort(port, timeoutMs = 500) {
-  return new Promise((resolve) => {
-    const socket = new net.Socket();
-    let done = false;
-    const finish = (ok) => {
-      if (done) return;
-      done = true;
-      try { socket.destroy(); } catch (_) {}
-      resolve(ok);
-    };
-    socket.setTimeout(timeoutMs);
-    socket.once('connect', () => finish(true));
-    socket.once('timeout', () => finish(false));
-    socket.once('error', () => finish(false));
-    socket.connect(port, HOST);
-  });
-}
-
-async function isBrokerAlive() {
-  const info = readBusInfo();
-  if (!info) return { alive: false };
-  if (!isProcessAlive(info.pid)) return { alive: false, staleInfo: info };
-  const portOk = await checkPort(info.port);
-  if (!portOk) return { alive: false, staleInfo: info };
-  return { alive: true, info };
-}
-
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-async function waitForBroker(maxMs = 3000) {
-  const start = Date.now();
-  while (Date.now() - start < maxMs) {
-    const status = await isBrokerAlive();
-    if (status.alive) return status.info;
-    await sleep(100);
-  }
-  return null;
-}
-
-function cleanStaleInfo() {
-  try {
-    fs.unlinkSync(BUS_INFO_PATH);
-  } catch (_) {}
-}
-
-async function ensureBroker(packageRoot) {
-  const status = await isBrokerAlive();
-  if (status.alive) return { info: status.info, started: false };
-
-  if (status.staleInfo) cleanStaleInfo();
-
-  const cliPath = path.join(packageRoot, 'bin', 'cli.js');
-  const child = spawn(process.execPath, [cliPath, 'bus', 'serve'], {
-    detached: true,
-    stdio: 'ignore',
-    windowsHide: true,
-  });
-  child.unref();
-
-  const info = await waitForBroker(5000);
-  if (!info) {
-    throw new Error(
-      'El broker no respondió en 5s. Verifica que la dependencia "ws" esté instalada: npm install -g ws',
-    );
-  }
-  return { info, started: true };
-}
-
-function stopBroker() {
-  const info = readBusInfo();
-  if (!info) return { stopped: false, reason: 'no-info' };
-  if (!isProcessAlive(info.pid)) {
-    cleanStaleInfo();
-    return { stopped: false, reason: 'not-alive', info };
-  }
-  try {
-    process.kill(info.pid, 'SIGTERM');
-  } catch (err) {
-    return { stopped: false, reason: err.message, info };
-  }
-  // En Windows, SIGTERM termina sin ejecutar handlers del broker, así que
-  // limpiamos el bus.json desde aquí para dejar el estado consistente.
-  cleanStaleInfo();
-  return { stopped: true, info };
-}
-
-module.exports = {
-  readBusInfo,
-  isBrokerAlive,
-  ensureBroker,
-  stopBroker,
-  waitForBroker,
-  cleanStaleInfo,
-};
+const fs = require('fs');
+const path = require('path');
+const net = require('net');
+const { spawn } = require('child_process');
+const {
+  BUS_INFO_PATH,
+  BUS_STARTUP_ERROR_PATH,
+  BUS_INFO_OWNER,
+  BUS_INFO_SERVICE,
+  HOST,
+} = require('./broker');
+
+function readBusInfo() {
+  try {
+    const raw = fs.readFileSync(BUS_INFO_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+function readStartupError() {
+  try {
+    const raw = fs.readFileSync(BUS_STARTUP_ERROR_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+}
+
+function isRefacilBrokerInfo(info) {
+  return !!(
+    info &&
+    info.owner === BUS_INFO_OWNER &&
+    info.service === BUS_INFO_SERVICE
+  );
+}
+
+function cleanStartupError() {
+  try {
+    fs.unlinkSync(BUS_STARTUP_ERROR_PATH);
+  } catch (_) {}
+}
+
+function isProcessAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+function checkPort(port, timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch (_) {}
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+    socket.connect(port, HOST);
+  });
+}
+
+async function isBrokerAlive() {
+  const info = readBusInfo();
+  if (!info) return { alive: false };
+  if (!isRefacilBrokerInfo(info)) return { alive: false, staleInfo: info };
+  if (!isProcessAlive(info.pid)) return { alive: false, staleInfo: info };
+  const portOk = await checkPort(info.port);
+  if (!portOk) return { alive: false, staleInfo: info };
+  return { alive: true, info };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function waitForBroker(maxMs = 3000) {
+  const start = Date.now();
+  while (Date.now() - start < maxMs) {
+    const status = await isBrokerAlive();
+    if (status.alive) return status.info;
+    await sleep(100);
+  }
+  return null;
+}
+
+function cleanStaleInfo() {
+  try {
+    fs.unlinkSync(BUS_INFO_PATH);
+  } catch (_) {}
+}
+
+function hasWsDependency(packageRoot) {
+  try {
+    require.resolve('ws', { paths: [packageRoot] });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function buildBrokerStartError(packageRoot, startupError) {
+  if (!hasWsDependency(packageRoot) || (startupError && startupError.code === 'WS_MISSING')) {
+    return new Error(
+      'No se pudo iniciar el broker porque falta la dependencia "ws". Instala las dependencias del paquete refacil-sdd-ai.',
+    );
+  }
+
+  if (startupError && startupError.code === 'EADDRINUSE') {
+    return new Error(
+      `No se pudo iniciar el broker porque el puerto solicitado está ocupado: ${startupError.message}`,
+    );
+  }
+
+  if (startupError && startupError.message) {
+    return new Error(`No se pudo iniciar el broker: ${startupError.message}`);
+  }
+
+  return new Error(
+    'No se pudo iniciar el broker: el proceso no publicó bus.json ni reportó una causa de arranque.',
+  );
+}
+
+async function ensureBroker(packageRoot) {
+  const status = await isBrokerAlive();
+  if (status.alive) return { info: status.info, started: false };
+
+  if (status.staleInfo) cleanStaleInfo();
+  cleanStartupError();
+
+  const cliPath = path.join(packageRoot, 'bin', 'cli.js');
+  const child = spawn(process.execPath, [cliPath, 'bus', 'serve'], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.unref();
+
+  const info = await waitForBroker(5000);
+  if (!info) {
+    throw buildBrokerStartError(packageRoot, readStartupError());
+  }
+  return { info, started: true };
+}
+
+function stopBroker() {
+  const info = readBusInfo();
+  if (!info) return { stopped: false, reason: 'no-info' };
+  if (!isRefacilBrokerInfo(info)) {
+    cleanStaleInfo();
+    return { stopped: false, reason: 'foreign-info', info };
+  }
+  if (!isProcessAlive(info.pid)) {
+    cleanStaleInfo();
+    return { stopped: false, reason: 'not-alive', info };
+  }
+  try {
+    process.kill(info.pid, 'SIGTERM');
+  } catch (err) {
+    return { stopped: false, reason: err.message, info };
+  }
+  // En Windows, SIGTERM termina sin ejecutar handlers del broker, así que
+  // limpiamos el bus.json desde aquí para dejar el estado consistente.
+  cleanStaleInfo();
+  return { stopped: true, info };
+}
+
+module.exports = {
+  readBusInfo,
+  isBrokerAlive,
+  ensureBroker,
+  stopBroker,
+  waitForBroker,
+  cleanStaleInfo,
+  readStartupError,
+  cleanStartupError,
+  isRefacilBrokerInfo,
+  buildBrokerStartError,
+};

package/lib/check-review.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Active changes directory: refacil-sdd/changes, or openspec/changes as legacy fallback.
+ * @param {string} projectRoot
+ * @returns {string|null}
+ */
+function resolveChangesDir(projectRoot) {
+  const sddChangesDir = path.join(projectRoot, 'refacil-sdd', 'changes');
+  const legacyChangesDir = path.join(projectRoot, 'openspec', 'changes');
+  if (fs.existsSync(sddChangesDir)) return sddChangesDir;
+  if (fs.existsSync(legacyChangesDir)) return legacyChangesDir;
+  return null;
+}
+
+/**
+ * @param {string} changesDir
+ * @param {string} changeName
+ * @returns {boolean}
+ */
+function changeNeedsReview(changesDir, changeName) {
+  const changePath = path.join(changesDir, changeName);
+  if (fs.existsSync(path.join(changePath, '.review-passed'))) return false;
+
+  // Only block if implementation has started (at least one task done).
+  // Pure proposals (all tasks pending) and bug fixes without tasks.md do not block push.
+  const tasksPath = path.join(changePath, 'tasks.md');
+  if (!fs.existsSync(tasksPath)) return false;
+
+  const tasksContent = fs.readFileSync(tasksPath, 'utf8');
+  const done = (tasksContent.match(/^- \[x\]/gm) || []).length;
+  return done > 0;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function listActiveChangesMissingReview(projectRoot) {
+  const changesDir = resolveChangesDir(projectRoot);
+  if (!changesDir || !fs.existsSync(changesDir)) return [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+
+  const active = entries.filter((e) => e.isDirectory() && e.name !== 'archive');
+  return active.filter((e) => changeNeedsReview(changesDir, e.name)).map((e) => e.name);
+}
+
+/**
+ * @param {string[]} names
+ * @returns {string}
+ */
+function buildReviewBlockReason(names) {
+  if (names.length === 0) return '';
+
+  const joined = names.join(', ');
+  if (names.length === 1) {
+    return (
+      `[refacil-sdd-ai] Review pending for: ${joined}. ` +
+      'Stop the push and run /refacil:review on that change before pushing code. ' +
+      'If the review passes, retry the git push. ' +
+      'If the review requires corrections, report the findings to the user and DO NOT retry the push.'
+    );
+  }
+
+  return (
+    `[refacil-sdd-ai] Multiple changes without approved review: ${joined}. ` +
+    'Stop the push and ask the user to explicitly select which change they want to push. ' +
+    'Then run /refacil:review <change-name> for that specific change and retry the push. ' +
+    'Do not run automatic review without explicit selection when there is more than one pending change.'
+  );
+}
+
+/**
+ * @param {string} command
+ * @param {string} projectRoot
+ * @returns {{ decision: 'block', reason: string }|null}
+ */
+function evaluateGitPushReview(command, projectRoot) {
+  if (!command || !/git\s+push/.test(command)) return null;
+
+  const missing = listActiveChangesMissingReview(projectRoot);
+  if (missing.length === 0) return null;
+
+  return { decision: 'block', reason: buildReviewBlockReason(missing) };
+}
+
+module.exports = {
+  resolveChangesDir,
+  changeNeedsReview,
+  listActiveChangesMissingReview,
+  buildReviewBlockReason,
+  evaluateGitPushReview,
+};