@nitsan-ai/ragsuite-test 0.1.0

package/src/utils/paths.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { readConfig, CONFIG_DIR } = require('./config');
+
+function looksLikeRepoRoot(dir) {
+  const start = path.join(dir, 'scripts', 'docker-start.sh');
+  const pkg = path.join(dir, 'package.json');
+  return fs.existsSync(start) && fs.existsSync(pkg);
+}
+
+function looksLikeFullBundleRoot(dir) {
+  if (!looksLikeRepoRoot(dir)) return false;
+  const compose = path.join(dir, 'docker-compose.yml');
+  return fs.existsSync(compose);
+}
+
+function walkUpForRepoRoot(startDir) {
+  let current = path.resolve(startDir);
+  for (;;) {
+    if (looksLikeRepoRoot(current)) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function envRepoRoot(env = process.env) {
+  const candidates = [env.RAGSUITE_REPO_ROOT, env.RAGSUITE_INSTALL_DIR];
+  for (const raw of candidates) {
+    if (!raw || !String(raw).trim()) continue;
+    const root = path.resolve(String(raw).trim());
+    if (looksLikeRepoRoot(root)) {
+      return root;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve monorepo root:
+ * --repo-root → RAGSUITE_REPO_ROOT / RAGSUITE_INSTALL_DIR → walk-up / config.
+ */
+function resolveRepoRoot({
+  cwd = process.cwd(),
+  repoRootFlag,
+  searchConfig = true,
+  env = process.env,
+} = {}) {
+  if (repoRootFlag) {
+    const root = path.resolve(repoRootFlag);
+    if (!looksLikeRepoRoot(root)) {
+      const err = new Error(
+        `Not a RAGSuite repo root (missing scripts/docker-start.sh): ${root}`,
+      );
+      err.code = 'NOT_REPO_ROOT';
+      throw err;
+    }
+    return root;
+  }
+
+  const fromEnv = envRepoRoot(env);
+  if (fromEnv) {
+    return fromEnv;
+  }
+
+  if (searchConfig) {
+    const walked = walkUpForRepoRoot(cwd);
+    if (walked) {
+      const cfg = readConfig(walked);
+      if (cfg) {
+        for (const key of ['repoRoot', 'installDir']) {
+          const candidate = cfg[key];
+          if (candidate && looksLikeRepoRoot(candidate)) {
+            return path.resolve(candidate);
+          }
+        }
+      }
+      return walked;
+    }
+  }
+
+  const walked = walkUpForRepoRoot(cwd);
+  if (walked) {
+    return walked;
+  }
+
+  const err = new Error(
+    'Could not find RAGSuite repo root. Pass --repo-root <path>, set RAGSUITE_REPO_ROOT, or run: ragsuite-test init --from-zip <app.zip>',
+  );
+  err.code = 'NOT_REPO_ROOT';
+  throw err;
+}
+
+function scriptPath(repoRoot, name) {
+  return path.join(repoRoot, 'scripts', name);
+}
+
+function ensureRagsuiteDir(repoRoot) {
+  const dir = path.join(repoRoot, CONFIG_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Native PID/logs stay under .ragsuite/native (Phase 4 scripts). */
+function nativeLogDir(repoRoot) {
+  return path.join(repoRoot, '.ragsuite', 'native');
+}
+
+module.exports = {
+  looksLikeRepoRoot,
+  looksLikeFullBundleRoot,
+  walkUpForRepoRoot,
+  envRepoRoot,
+  resolveRepoRoot,
+  scriptPath,
+  ensureRagsuiteDir,
+  nativeLogDir,
+};

package/src/utils/port.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const net = require('net');
+
+function apiPort(env = process.env) {
+  const n = Number(env.API_PORT || 9090);
+  return Number.isFinite(n) && n > 0 ? n : 9090;
+}
+
+/**
+ * Return true if something accepts TCP connections on host:port.
+ */
+function isPortInUse(port, host = '127.0.0.1', timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    const done = (inUse) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(inUse);
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+    socket.connect(port, host);
+  });
+}
+
+async function assertApiPortFree(env = process.env) {
+  const port = apiPort(env);
+  const busy = await isPortInUse(port);
+  if (busy) {
+    const err = new Error(
+      `API port ${port} is already in use. Stop the other process (e.g. npm run down or npm run stop:native) and retry. This CLI will not kill foreign processes.`,
+    );
+    err.code = 'PORT_IN_USE';
+    throw err;
+  }
+  return port;
+}
+
+const DEFAULT_INSTALL_PORTS = [
+  { port: 9090, label: 'API' },
+  { port: 9091, label: 'Web UI' },
+  { port: 5436, label: 'Postgres' },
+  { port: 6382, label: 'Redis' },
+];
+
+async function assertPortsFree(ports = DEFAULT_INSTALL_PORTS) {
+  const busy = [];
+  for (const item of ports) {
+    const p = typeof item === 'number' ? item : item.port;
+    const label = typeof item === 'number' ? `port ${item}` : item.label;
+    if (await isPortInUse(p)) {
+      busy.push(`${label} :${p}`);
+    }
+  }
+  if (busy.length) {
+    const err = new Error(
+      `Port(s) already in use: ${busy.join(', ')}. Free them (ragsuite-test stop / npm run down) and retry. This CLI will not kill foreign processes.`,
+    );
+    err.code = 'PORT_IN_USE';
+    throw err;
+  }
+}
+
+module.exports = {
+  apiPort,
+  isPortInUse,
+  assertApiPortFree,
+  assertPortsFree,
+  DEFAULT_INSTALL_PORTS,
+};

package/src/utils/prereqs.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const { info, warn, error } = require('./log');
+
+function commandExists(cmd) {
+  const r = spawnSync('which', [cmd], { encoding: 'utf8' });
+  return r.status === 0;
+}
+
+function dockerDaemonRunning() {
+  const r = spawnSync('docker', ['info'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return r.status === 0;
+}
+
+function nodeMajorOk() {
+  const major = Number(String(process.versions.node).split('.')[0]);
+  return Number.isFinite(major) && major >= 18;
+}
+
+/**
+ * Check prerequisites for install mode. Returns { ok, issues[] }.
+ */
+function checkPrereqs(mode = 'docker') {
+  const issues = [];
+  const notes = [];
+
+  if (!nodeMajorOk()) {
+    issues.push(`Node.js 18+ required (current: ${process.version})`);
+  } else {
+    notes.push(`Node.js ${process.version}`);
+  }
+
+  if (mode === 'docker') {
+    if (!commandExists('docker')) {
+      issues.push('Docker CLI not found (required for docker mode)');
+    } else if (!dockerDaemonRunning()) {
+      issues.push('Docker daemon not running — start Docker Desktop / dockerd');
+    } else {
+      notes.push('Docker CLI + daemon OK');
+    }
+    if (!commandExists('docker')) {
+      /* already noted */
+    } else {
+      const compose = spawnSync('docker', ['compose', 'version'], { encoding: 'utf8' });
+      if (compose.status !== 0) {
+        issues.push('docker compose plugin not available');
+      } else {
+        notes.push('docker compose OK');
+      }
+    }
+  } else {
+    if (!commandExists('python3')) {
+      issues.push('python3 not found (required for native mode)');
+    } else {
+      notes.push('python3 present');
+    }
+    if (!commandExists('yarn')) {
+      notes.push('yarn missing — native-start can still use npm/corepack in some setups');
+    } else {
+      notes.push('yarn present');
+    }
+    notes.push('Native mode also needs Postgres :5436 and Redis :6382 reachable');
+  }
+
+  if (process.platform === 'win32') {
+    notes.push('Windows: use WSL or Git Bash — start/stop spawn bash scripts');
+  }
+
+  return { ok: issues.length === 0, issues, notes };
+}
+
+function printPrereqs(mode) {
+  const { ok, issues, notes } = checkPrereqs(mode);
+  info(`Prerequisites (mode=${mode}):`);
+  for (const n of notes) info(`  ✓ ${n}`);
+  for (const i of issues) error(`  ✗ ${i}`);
+  return ok;
+}
+
+module.exports = {
+  commandExists,
+  dockerDaemonRunning,
+  nodeMajorOk,
+  checkPrereqs,
+  printPrereqs,
+};

package/src/utils/prompt.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const readline = require('readline');
+
+function createInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function ask(question, options = {}) {
+  const { defaultValue = '', yesMode = false } = options;
+  if (yesMode) {
+    return Promise.resolve(defaultValue);
+  }
+  const rl = createInterface();
+  const suffix = defaultValue !== '' && defaultValue != null ? ` [${defaultValue}]` : '';
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.close();
+      const trimmed = String(answer || '').trim();
+      resolve(trimmed === '' ? defaultValue : trimmed);
+    });
+  });
+}
+
+async function confirm(question, options = {}) {
+  const { defaultYes = false, yesMode = false } = options;
+  if (yesMode) return defaultYes;
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  const answer = await ask(`${question} (${hint})`, { yesMode: false });
+  if (!answer) return defaultYes;
+  return /^(y|yes)$/i.test(answer);
+}
+
+async function choose(question, choices, options = {}) {
+  const { defaultIndex = 0, yesMode = false } = options;
+  if (yesMode) {
+    return choices[defaultIndex];
+  }
+  console.log(question);
+  choices.forEach((c, i) => {
+    console.log(`  ${i + 1}) ${c.label}`);
+  });
+  const answer = await ask('Choice', {
+    defaultValue: String(defaultIndex + 1),
+    yesMode: false,
+  });
+  const n = Number(answer);
+  if (!Number.isFinite(n) || n < 1 || n > choices.length) {
+    return choices[defaultIndex];
+  }
+  return choices[n - 1];
+}
+
+module.exports = { ask, confirm, choose };

package/src/utils/spawn.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const { info } = require('./log');
+
+/**
+ * Run a repo script with inherited stdio. dry-run prints and returns 0.
+ * @returns {number} exit code
+ */
+function runScript(repoRoot, relPath, args = [], options = {}) {
+  const { dryRun = false, env = process.env, shell = false } = options;
+  const abs = path.isAbsolute(relPath) ? relPath : path.join(repoRoot, relPath);
+  const display = [abs, ...args].join(' ');
+
+  if (dryRun) {
+    info(`[dry-run] ${display}`);
+    return 0;
+  }
+
+  const result = spawnSync('bash', [abs, ...args], {
+    cwd: repoRoot,
+    env: { ...env },
+    stdio: 'inherit',
+    shell,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+/**
+ * Run an arbitrary command (e.g. docker compose, git, tail).
+ * @returns {number} exit code
+ */
+function runCommand(cmd, args, options = {}) {
+  const { cwd = process.cwd(), dryRun = false, env = process.env } = options;
+  const display = [cmd, ...args].join(' ');
+
+  if (dryRun) {
+    info(`[dry-run] ${display}`);
+    return 0;
+  }
+
+  const result = spawnSync(cmd, args, {
+    cwd,
+    env: { ...env },
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+/**
+ * Capture stdout/stderr (for git status, etc.).
+ */
+function captureCommand(cmd, args, options = {}) {
+  const { cwd = process.cwd(), env = process.env } = options;
+  const result = spawnSync(cmd, args, {
+    cwd,
+    env: { ...env },
+    encoding: 'utf8',
+  });
+  return {
+    status: typeof result.status === 'number' ? result.status : 1,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error || null,
+  };
+}
+
+module.exports = { runScript, runCommand, captureCommand };

package/src/utils/zip-install.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { looksLikeFullBundleRoot } = require('./paths');
+
+function defaultInstallDir() {
+  return path.join(os.homedir(), 'ragsuite-test');
+}
+
+function requireUnzip() {
+  const which = spawnSync('which', ['unzip'], { encoding: 'utf8' });
+  if (which.status !== 0) {
+    const err = new Error('unzip is required for --from-zip (install unzip / use macOS or Linux)');
+    err.code = 'MISSING_UNZIP';
+    throw err;
+  }
+}
+
+/**
+ * List zip entries; reject zip-slip (absolute paths, .. segments).
+ * @returns {string[]}
+ */
+function listZipEntries(zipPath) {
+  requireUnzip();
+  const opts = { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 };
+  const result = spawnSync('unzip', ['-Z1', zipPath], opts);
+  if (result.status === 0) {
+    return String(result.stdout || '')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+  }
+  const alt = spawnSync('unzip', ['-l', zipPath], opts);
+  if (alt.status !== 0) {
+    const err = new Error(
+      `Failed to list zip: ${zipPath} (${(result.stderr || alt.stderr || result.error || '').toString().trim() || 'unzip -Z1/-l failed'})`,
+    );
+    err.code = 'ZIP_LIST';
+    throw err;
+  }
+  return parseUnzipL(alt.stdout);
+}
+
+function parseUnzipL(stdout) {
+  const lines = String(stdout || '').split('\n');
+  const entries = [];
+  for (const line of lines) {
+    // typical: "  Length  Date  Time  Name" then data lines ending with name
+    const m = line.match(/^\s*\d+\s+\d{2}-\d{2}-\d{4}\s+\d{2}:\d{2}\s+(.+)$/);
+    if (m) entries.push(m[1].trim());
+  }
+  return entries.filter(Boolean);
+}
+
+function assertNoZipSlip(entries) {
+  for (const entry of entries) {
+    const normalized = entry.replace(/\\/g, '/');
+    if (normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized)) {
+      const err = new Error(`Refusing zip with absolute path entry: ${entry}`);
+      err.code = 'ZIP_SLIP';
+      throw err;
+    }
+    const parts = normalized.split('/');
+    if (parts.some((p) => p === '..')) {
+      const err = new Error(`Refusing zip with path traversal entry: ${entry}`);
+      err.code = 'ZIP_SLIP';
+      throw err;
+    }
+  }
+}
+
+function isDirEmptyOrMissing(dir) {
+  if (!fs.existsSync(dir)) return true;
+  const items = fs.readdirSync(dir).filter((n) => n !== '.DS_Store');
+  return items.length === 0;
+}
+
+function findBundleRoot(extractRoot) {
+  if (looksLikeFullBundleRoot(extractRoot)) {
+    return extractRoot;
+  }
+  const kids = fs
+    .readdirSync(extractRoot)
+    .map((n) => path.join(extractRoot, n))
+    .filter((p) => fs.statSync(p).isDirectory());
+  if (kids.length === 1 && looksLikeFullBundleRoot(kids[0])) {
+    return kids[0];
+  }
+  for (const kid of kids) {
+    if (looksLikeFullBundleRoot(kid)) return kid;
+  }
+  const err = new Error(
+    'ZIP does not contain a RAGSuite monorepo root (need package.json, scripts/docker-start.sh, docker-compose.yml)',
+  );
+  err.code = 'ZIP_INVALID';
+  throw err;
+}
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const name of fs.readdirSync(src)) {
+    const from = path.join(src, name);
+    const to = path.join(dest, name);
+    const st = fs.statSync(from);
+    if (st.isDirectory()) {
+      copyDirRecursive(from, to);
+    } else {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function rmRecursive(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Extract zip safely into installDir.
+ * @returns {{ installDir: string, repoRoot: string }}
+ */
+function extractZipToInstallDir(zipPath, options = {}) {
+  const absZip = path.resolve(zipPath);
+  if (!fs.existsSync(absZip)) {
+    const err = new Error(`ZIP not found: ${absZip}`);
+    err.code = 'ZIP_MISSING';
+    throw err;
+  }
+
+  const installDir = path.resolve(options.installDir || defaultInstallDir());
+  const force = Boolean(options.force);
+
+  if (!isDirEmptyOrMissing(installDir) && !force) {
+    const err = new Error(
+      `Install dir is not empty: ${installDir}. Pass --force to overwrite, or choose another --install-dir.`,
+    );
+    err.code = 'INSTALL_DIR_NONEMPTY';
+    throw err;
+  }
+
+  const entries = listZipEntries(absZip);
+  if (entries.length === 0) {
+    const err = new Error('ZIP is empty');
+    err.code = 'ZIP_EMPTY';
+    throw err;
+  }
+  assertNoZipSlip(entries);
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ragsuite-zip-'));
+  try {
+    requireUnzip();
+    const unzip = spawnSync('unzip', ['-q', '-o', absZip, '-d', tmp], {
+      encoding: 'utf8',
+    });
+    if (unzip.status !== 0) {
+      const err = new Error(`unzip failed: ${unzip.stderr || unzip.stdout || 'unknown'}`);
+      err.code = 'ZIP_EXTRACT';
+      throw err;
+    }
+
+    const bundleRoot = findBundleRoot(tmp);
+
+    if (force && fs.existsSync(installDir)) {
+      rmRecursive(installDir);
+    }
+    fs.mkdirSync(path.dirname(installDir), { recursive: true });
+    if (fs.existsSync(installDir) && isDirEmptyOrMissing(installDir)) {
+      rmRecursive(installDir);
+    }
+    // Move/copy bundle into installDir
+    try {
+      fs.renameSync(bundleRoot, installDir);
+    } catch {
+      copyDirRecursive(bundleRoot, installDir);
+      if (bundleRoot !== tmp) {
+        rmRecursive(bundleRoot);
+      }
+    }
+  } catch (err) {
+    try {
+      rmRecursive(tmp);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+
+  // tmp may still have empty wrapper dirs
+  try {
+    if (fs.existsSync(tmp)) rmRecursive(tmp);
+  } catch {
+    /* ignore */
+  }
+
+  if (!looksLikeFullBundleRoot(installDir)) {
+    const err = new Error(`Extracted install is not a valid bundle: ${installDir}`);
+    err.code = 'ZIP_INVALID';
+    throw err;
+  }
+
+  return { installDir, repoRoot: installDir };
+}
+
+module.exports = {
+  defaultInstallDir,
+  listZipEntries,
+  assertNoZipSlip,
+  extractZipToInstallDir,
+  findBundleRoot,
+  isDirEmptyOrMissing,
+};