@nitsan-ai/ragsuite-test 0.1.0 → 0.1.1

package/src/utils/prereqs.js

@@ -22,62 +22,122 @@ function nodeMajorOk() {
 }
 
 /**
- * Check prerequisites for install mode. Returns { ok, issues[] }.
+ * How to install a missing prerequisite (shown in doctor/init).
  */
-function checkPrereqs(mode = 'docker') {
+function installHintFor(issueKey) {
+  const hints = {
+    node: 'Install Node 18+: https://nodejs.org/ or `brew install node` / `sudo apt install nodejs`',
+    docker:
+      'Docker is optional. Install Docker Desktop, OR use --mode native (Postgres :5436 + Redis :6382 on the host).',
+    'docker-compose': 'Install Docker Desktop (includes compose) or the docker compose plugin.',
+    python3: 'Install Python 3: `brew install python` / `sudo apt install python3 python3-venv`',
+    yarn: 'Optional: `corepack enable && corepack prepare yarn@stable --activate` or `npm i -g yarn`',
+    git: 'Install git: macOS `xcode-select --install` / `brew install git`; Linux `sudo apt install git`',
+    postgres:
+      'Native mode: Postgres on localhost:5436, db ragsuite_v3. Example: `brew install postgresql@15` then create DB/user.',
+    redis: 'Native mode: Redis on localhost:6382. Example: `brew install redis` then `redis-server --port 6382`.',
+  };
+  return hints[issueKey] || null;
+}
+
+/**
+ * Pick run mode when user did not pass --mode.
+ * Docker is never required — prefer native if Docker is unavailable.
+ */
+function resolvePreferredMode(flagMode) {
+  if (flagMode === 'docker' || flagMode === 'native') return flagMode;
+  if (commandExists('docker') && dockerDaemonRunning()) return 'docker';
+  return 'native';
+}
+
+/**
+ * Check prerequisites for install mode. Returns { ok, issues[], notes[], hints[] }.
+ */
+function checkPrereqs(mode = 'native', options = {}) {
+  const { needGit = false } = options;
   const issues = [];
   const notes = [];
+  const hints = [];
+
+  function pushIssue(msg, hintKey) {
+    issues.push(msg);
+    const h = installHintFor(hintKey);
+    if (h) hints.push(h);
+  }
 
   if (!nodeMajorOk()) {
-    issues.push(`Node.js 18+ required (current: ${process.version})`);
+    pushIssue(`Node.js 18+ required (current: ${process.version})`, 'node');
   } else {
     notes.push(`Node.js ${process.version}`);
   }
 
+  if (needGit) {
+    if (!commandExists('git')) {
+      pushIssue('git not found (required for --from-git)', 'git');
+    } else {
+      notes.push('git present');
+    }
+  }
+
   if (mode === 'docker') {
     if (!commandExists('docker')) {
-      issues.push('Docker CLI not found (required for docker mode)');
+      pushIssue('Docker CLI not found', 'docker');
     } else if (!dockerDaemonRunning()) {
-      issues.push('Docker daemon not running — start Docker Desktop / dockerd');
+      pushIssue('Docker daemon not running — start Docker Desktop / dockerd', 'docker');
     } 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');
+        pushIssue('docker compose plugin not available', 'docker-compose');
       } else {
         notes.push('docker compose OK');
       }
     }
   } else {
+    notes.push('Mode=native — Docker is NOT required');
     if (!commandExists('python3')) {
-      issues.push('python3 not found (required for native mode)');
+      pushIssue('python3 not found (required for native mode)', 'python3');
     } else {
       notes.push('python3 present');
     }
     if (!commandExists('yarn')) {
-      notes.push('yarn missing — native-start can still use npm/corepack in some setups');
+      notes.push('yarn missing — enable with corepack or npm i -g yarn');
+      const h = installHintFor('yarn');
+      if (h) hints.push(h);
     } else {
       notes.push('yarn present');
     }
-    notes.push('Native mode also needs Postgres :5436 and Redis :6382 reachable');
+    notes.push('Need Postgres :5436 (ragsuite_v3) and Redis :6382 on this machine');
+    hints.push(installHintFor('postgres'));
+    hints.push(installHintFor('redis'));
   }
 
   if (process.platform === 'win32') {
     notes.push('Windows: use WSL or Git Bash — start/stop spawn bash scripts');
   }
 
-  return { ok: issues.length === 0, issues, notes };
+  return {
+    ok: issues.length === 0,
+    issues,
+    notes,
+    hints: [...new Set(hints.filter(Boolean))],
+  };
 }
 
-function printPrereqs(mode) {
-  const { ok, issues, notes } = checkPrereqs(mode);
+function printPrereqs(mode, options = {}) {
+  const { ok, issues, notes, hints } = checkPrereqs(mode, options);
   info(`Prerequisites (mode=${mode}):`);
   for (const n of notes) info(`  ✓ ${n}`);
   for (const i of issues) error(`  ✗ ${i}`);
+  if (hints.length) {
+    info('');
+    info('How to get missing pieces:');
+    for (const h of hints) info(`  → ${h}`);
+  }
+  if (!ok && mode === 'docker') {
+    warn('');
+    warn('Docker is optional. Re-run with --mode native if you prefer host Postgres/Redis (no Docker).');
+  }
   return ok;
 }
 
@@ -85,6 +145,8 @@ module.exports = {
   commandExists,
   dockerDaemonRunning,
   nodeMajorOk,
+  installHintFor,
+  resolvePreferredMode,
   checkPrereqs,
   printPrereqs,
 };

package/src/utils/zip-install.js

@@ -1,213 +0,0 @@
-'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,
-};