@nitsan-ai/ragsuite-test 0.1.0 → 0.1.2

package/src/utils/args.js

@@ -2,8 +2,6 @@
 
 /**
  * Parse argv into global flags, command, and remaining args.
- * Globals: --help/-h, --repo-root, --dry-run, --mode,
- *          --from-zip, --from-release, --install-dir, --force, --yes
  */
 function parseArgv(argv) {
   const tokens = argv.slice(2);
@@ -12,25 +10,33 @@ function parseArgv(argv) {
     repoRoot: null,
     dryRun: false,
     mode: null,
-    fromZip: null,
+    fromGit: null,
     fromRelease: null,
     installDir: null,
     force: false,
     yes: false,
     llmApiKey: null,
+    smtpHost: null,
+    smtpUser: null,
+    smtpPassword: null,
+    emailFrom: null,
   };
   const rest = [];
   let command = null;
 
+  function takeValue(flag, t, i) {
+    const eq = `${flag}=`;
+    if (t.startsWith(eq)) return { value: t.slice(eq.length), nextI: i };
+    const value = tokens[i + 1];
+    return { value, nextI: i + 1 };
+  }
+
   for (let i = 0; i < tokens.length; i += 1) {
     const t = tokens[i];
 
     if (t === '--help' || t === '-h') {
-      if (command) {
-        rest.push(t);
-      } else {
-        globals.help = true;
-      }
+      if (command) rest.push(t);
+      else globals.help = true;
       continue;
     }
 
@@ -50,9 +56,8 @@ function parseArgv(argv) {
     }
 
     if (t === '--repo-root' || t.startsWith('--repo-root=')) {
-      const value = t.startsWith('--repo-root=')
-        ? t.slice('--repo-root='.length)
-        : tokens[++i];
+      const { value, nextI } = takeValue('--repo-root', t, i);
+      i = nextI;
       if (!value || value.startsWith('-')) {
         const err = new Error('--repo-root requires a path');
         err.code = 'USAGE';
@@ -63,7 +68,8 @@ function parseArgv(argv) {
     }
 
     if (t === '--mode' || t.startsWith('--mode=')) {
-      const value = t.startsWith('--mode=') ? t.slice('--mode='.length) : tokens[++i];
+      const { value, nextI } = takeValue('--mode', t, i);
+      i = nextI;
       if (!value || String(value).startsWith('-')) {
         const err = new Error('--mode requires docker or native');
         err.code = 'USAGE';
@@ -73,23 +79,32 @@ function parseArgv(argv) {
       continue;
     }
 
-    if (t === '--from-zip' || t.startsWith('--from-zip=')) {
-      const value = t.startsWith('--from-zip=')
-        ? t.slice('--from-zip='.length)
-        : tokens[++i];
-      if (!value || value.startsWith('-')) {
-        const err = new Error('--from-zip requires a path to a .zip file');
-        err.code = 'USAGE';
-        throw err;
+    if (t === '--from-git' || t.startsWith('--from-git=')) {
+      if (t === '--from-git') {
+        const next = tokens[i + 1];
+        if (next && !next.startsWith('-')) {
+          globals.fromGit = next;
+          i += 1;
+        } else {
+          globals.fromGit = ''; // use default URL
+        }
+      } else {
+        globals.fromGit = t.slice('--from-git='.length);
       }
-      globals.fromZip = value;
       continue;
     }
 
+    if (t === '--from-zip' || t.startsWith('--from-zip=')) {
+      const err = new Error(
+        '--from-zip was removed. Use --from-git (public deploy) or --repo-root <checkout>.',
+      );
+      err.code = 'USAGE';
+      throw err;
+    }
+
     if (t === '--from-release' || t.startsWith('--from-release=')) {
-      const value = t.startsWith('--from-release=')
-        ? t.slice('--from-release='.length)
-        : tokens[++i];
+      const { value, nextI } = takeValue('--from-release', t, i);
+      i = nextI;
       if (!value || value.startsWith('-')) {
         const err = new Error('--from-release requires a tag or "latest"');
         err.code = 'USAGE';
@@ -100,9 +115,8 @@ function parseArgv(argv) {
     }
 
     if (t === '--install-dir' || t.startsWith('--install-dir=')) {
-      const value = t.startsWith('--install-dir=')
-        ? t.slice('--install-dir='.length)
-        : tokens[++i];
+      const { value, nextI } = takeValue('--install-dir', t, i);
+      i = nextI;
       if (!value || value.startsWith('-')) {
         const err = new Error('--install-dir requires a path');
         err.code = 'USAGE';
@@ -113,9 +127,8 @@ function parseArgv(argv) {
     }
 
     if (t === '--llm-api-key' || t.startsWith('--llm-api-key=')) {
-      const value = t.startsWith('--llm-api-key=')
-        ? t.slice('--llm-api-key='.length)
-        : tokens[++i];
+      const { value, nextI } = takeValue('--llm-api-key', t, i);
+      i = nextI;
       if (!value || value.startsWith('-')) {
         const err = new Error('--llm-api-key requires a value');
         err.code = 'USAGE';
@@ -125,6 +138,54 @@ function parseArgv(argv) {
       continue;
     }
 
+    if (t === '--smtp-host' || t.startsWith('--smtp-host=')) {
+      const { value, nextI } = takeValue('--smtp-host', t, i);
+      i = nextI;
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--smtp-host requires a value');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.smtpHost = value;
+      continue;
+    }
+
+    if (t === '--smtp-user' || t.startsWith('--smtp-user=')) {
+      const { value, nextI } = takeValue('--smtp-user', t, i);
+      i = nextI;
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--smtp-user requires a value');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.smtpUser = value;
+      continue;
+    }
+
+    if (t === '--smtp-password' || t.startsWith('--smtp-password=')) {
+      const { value, nextI } = takeValue('--smtp-password', t, i);
+      i = nextI;
+      if (value === undefined || value === null || String(value).startsWith('-')) {
+        const err = new Error('--smtp-password requires a value');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.smtpPassword = value;
+      continue;
+    }
+
+    if (t === '--email-from' || t.startsWith('--email-from=')) {
+      const { value, nextI } = takeValue('--email-from', t, i);
+      i = nextI;
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--email-from requires a value');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.emailFrom = value;
+      continue;
+    }
+
     if (!command && !t.startsWith('-')) {
       command = t;
       continue;

package/src/utils/distribution.js

@@ -3,36 +3,39 @@
 /**
  * Distribution modes for the testing CLI.
  *
- * - local-checkout: --repo-root / env / walk-up (path C)
- * - zip-bundle: init --from-zip (primary for private testing)
- * Registry/GHCR compose remains stubbed.
+ * - git-clone: default `ragsuite-test init` (public GitHub)
+ * - local-checkout: --repo-root (advanced / CI)
  */
 
 const MODE_LOCAL = 'local-checkout';
-const MODE_ZIP = 'zip-bundle';
+const MODE_GIT = 'git-clone';
 const MODE_REGISTRY = 'registry-compose';
 
-function assertSupportedInstall() {
-  // checkout + zip supported
-}
+function assertSupportedInstall() {}
 
 function resolveComposeBundle() {
   const err = new Error(
-    'Registry/compose (GHCR) install is not available yet. Use: ragsuite-test init --from-zip <app.zip> or --repo-root <checkout>.',
+    'Registry/compose (GHCR) install is not available yet. Run: ragsuite-test init',
   );
   err.code = 'DIST_NOT_READY';
   throw err;
 }
 
 function installHint() {
-  return 'Supported: ragsuite-test init --from-zip <app.zip> [--install-dir ~/ragsuite-test]  OR  --repo-root <checkout>. GitHub Release download (--from-release) is not ready yet.';
+  return [
+    'Simple deploy:',
+    '  npm install -g @nitsan-ai/ragsuite-test',
+    '  ragsuite-test init',
+    '  ragsuite-test start --repo-root ~/ragsuite-test --detach',
+    'Docker is optional — init picks native automatically if Docker is not running.',
+  ].join('\n');
 }
 
 module.exports = {
   MODE_LOCAL,
-  MODE_ZIP,
+  MODE_GIT,
   MODE_REGISTRY,
-  mode: MODE_ZIP,
+  mode: MODE_GIT,
   assertSupportedInstall,
   resolveComposeBundle,
   installHint,

package/src/utils/env-file.js

@@ -3,7 +3,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const { warn } = require('./log');
+const { info, warn } = require('./log');
 
 function generateJwtSecret() {
   return crypto.randomBytes(32).toString('hex');
@@ -15,7 +15,7 @@ function generateCiLlmKey() {
 
 function isPlaceholderSecret(value) {
   const v = String(value || '').trim();
-  return !v || v.startsWith('change-me');
+  return !v || v.startsWith('change-me') || v.startsWith('your-smtp-');
 }
 
 /**
@@ -57,16 +57,84 @@ function buildEnvFromExample(examplePath, overrides = {}) {
   return `${out.join('\n').replace(/\n+$/, '')}\n`;
 }
 
+function parseEnvFile(envPath) {
+  const out = {};
+  if (!fs.existsSync(envPath)) return out;
+  for (const line of fs.readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+/**
+ * Short “how to get / fix” hints when a config value is missing or still a placeholder.
+ */
+function printConfigHints(issues) {
+  if (!issues.length) return;
+  warn('');
+  warn('Missing or placeholder configuration — how to fix:');
+  for (const issue of issues) {
+    warn(`  ✗ ${issue.title}`);
+    for (const step of issue.steps) warn(`    → ${step}`);
+  }
+  warn('');
+}
+
+function collectEnvConfigIssues(envMap) {
+  const issues = [];
+  if (isPlaceholderSecret(envMap.JWT_SECRET_KEY)) {
+    issues.push({
+      title: 'JWT_SECRET_KEY',
+      steps: [
+        'Re-run: ragsuite-test init --force … (auto-generates JWT)',
+        'Or set JWT_SECRET_KEY in .env (never commit .env)',
+      ],
+    });
+  }
+  if (isPlaceholderSecret(envMap.CUSTOM_LLM_INTERNAL_API_KEY)) {
+    issues.push({
+      title: 'CUSTOM_LLM_INTERNAL_API_KEY',
+      steps: [
+        'Edit .env and set CUSTOM_LLM_INTERNAL_API_KEY=…',
+        'Or: ragsuite-test init --force --llm-api-key YOUR_KEY',
+      ],
+    });
+  }
+  const smtpOk =
+    envMap.SMTP_HOST &&
+    envMap.SMTP_USER &&
+    envMap.SMTP_PASSWORD &&
+    !isPlaceholderSecret(envMap.SMTP_PASSWORD) &&
+    !isPlaceholderSecret(envMap.SMTP_USER) &&
+    (envMap.EMAIL_FROM || envMap.SMTP_USER);
+  if (!smtpOk) {
+    issues.push({
+      title: 'SMTP (real mail)',
+      steps: [
+        'Put real values only in .env (gitignored) — never in .env.example',
+        'Gmail: Google Account → Security → App passwords → Mail',
+        'Set SMTP_USER, SMTP_PASSWORD, EMAIL_FROM in .env, then restart',
+      ],
+    });
+  }
+  return issues;
+}
+
 /**
- * Write .env. Refuse overwrite unless force.
- * @returns {{ jwt: string, llmKey: string, smtpSkipped: boolean }}
+ * Write .env from .env.example. Never prompts.
+ * - Always regenerates JWT
+ * - Keeps LLM default from example (or generates if placeholder)
+ * - If SMTP in example is still a placeholder, writes a non-empty smoke SMTP
+ *   so the backend can start; real mail requires editing local .env
+ * - Optional flag overrides only
  */
 function writeInstallEnv(repoRoot, options = {}) {
   const {
     force = false,
     jwtSecret = generateJwtSecret(),
     llmApiKey,
-    smtpSkipped = true,
+    smtp,
   } = options;
 
   const envPath = path.join(repoRoot, '.env');
@@ -80,30 +148,62 @@ function writeInstallEnv(repoRoot, options = {}) {
     throw err;
   }
 
-  if (isPlaceholderSecret(llmApiKey)) {
-    const err = new Error('CUSTOM_LLM_INTERNAL_API_KEY must be set and must not be a change-me* placeholder');
-    err.code = 'LLM_KEY_INVALID';
-    throw err;
-  }
-
+  const example = parseEnvFile(examplePath);
   const overrides = {
     JWT_SECRET_KEY: jwtSecret,
-    CUSTOM_LLM_INTERNAL_API_KEY: llmApiKey,
   };
 
-  if (smtpSkipped) {
-    // Backend refuses to start when SMTP_PASSWORD is empty (main.py lifespan guard).
-    // Use a non-empty smoke placeholder so Docker/native can boot; real email still fails.
-    overrides.SMTP_PASSWORD = 'ci-smoke-smtp-not-for-production';
-    warn('');
-    warn('WARNING: SMTP skipped for smoke testing (placeholder SMTP_PASSWORD).');
-    warn('Backend will start, but invites, password reset, and email 2FA will FAIL until real SMTP_* is set.');
-    warn('');
+  if (llmApiKey && !isPlaceholderSecret(llmApiKey)) {
+    overrides.CUSTOM_LLM_INTERNAL_API_KEY = llmApiKey;
+  } else if (isPlaceholderSecret(example.CUSTOM_LLM_INTERNAL_API_KEY)) {
+    overrides.CUSTOM_LLM_INTERNAL_API_KEY = generateCiLlmKey();
+  }
+
+  if (smtp) {
+    if (smtp.host) overrides.SMTP_HOST = smtp.host;
+    if (smtp.user) overrides.SMTP_USER = smtp.user;
+    if (smtp.password) overrides.SMTP_PASSWORD = smtp.password;
+    if (smtp.emailFrom) overrides.EMAIL_FROM = smtp.emailFrom;
+  } else {
+    // No prompts: if template SMTP is placeholder, use smoke values so API can boot.
+    // Real Gmail credentials must live only in local .env (never commit).
+    const smtpUser = example.SMTP_USER || '';
+    const smtpPass = example.SMTP_PASSWORD || '';
+    if (isPlaceholderSecret(smtpPass) || isPlaceholderSecret(smtpUser)) {
+      overrides.SMTP_HOST = example.SMTP_HOST || 'smtp.gmail.com';
+      overrides.SMTP_PORT = example.SMTP_PORT || '587';
+      overrides.SMTP_USER = 'smoke-smtp@localhost';
+      overrides.SMTP_PASSWORD = 'ci-smoke-smtp-not-for-production';
+      overrides.SMTP_USE_TLS = example.SMTP_USE_TLS || 'true';
+      overrides.EMAIL_FROM = 'smoke-smtp@localhost';
+      warn('SMTP template was placeholder — wrote smoke SMTP into .env so the app can start.');
+      warn('For real email: edit .env (SMTP_USER / SMTP_PASSWORD / EMAIL_FROM). Never commit .env.');
+    }
   }
 
   const content = buildEnvFromExample(examplePath, overrides);
   fs.writeFileSync(envPath, content, 'utf8');
-  return { jwt: jwtSecret, llmKey: llmApiKey, smtpSkipped: Boolean(smtpSkipped), envPath };
+
+  const written = parseEnvFile(envPath);
+  if (isPlaceholderSecret(written.JWT_SECRET_KEY) || isPlaceholderSecret(written.CUSTOM_LLM_INTERNAL_API_KEY)) {
+    printConfigHints(collectEnvConfigIssues(written));
+    const err = new Error('Install .env is incomplete (see hints above).');
+    err.code = 'ENV_INCOMPLETE';
+    throw err;
+  }
+
+  // Soft hint only for smoke SMTP (do not fail init — backend can start)
+  if (written.SMTP_PASSWORD === 'ci-smoke-smtp-not-for-production') {
+    info('SMTP: smoke defaults in .env (app starts). Edit .env for real Gmail/app-password mail.');
+  } else {
+    info('SMTP + LLM loaded into .env (no interactive prompts).');
+  }
+
+  return {
+    jwt: written.JWT_SECRET_KEY,
+    llmKey: written.CUSTOM_LLM_INTERNAL_API_KEY,
+    envPath,
+  };
 }
 
 function readEnvValue(envPath, key) {
@@ -119,6 +219,9 @@ module.exports = {
   generateCiLlmKey,
   isPlaceholderSecret,
   buildEnvFromExample,
+  parseEnvFile,
+  collectEnvConfigIssues,
+  printConfigHints,
   writeInstallEnv,
   readEnvValue,
 };

package/src/utils/git-install.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { looksLikeFullBundleRoot, looksLikeRepoRoot } = require('./paths');
+
+/** Default public monorepo (when the GitHub repo is public). */
+const DEFAULT_GIT_URL = 'https://github.com/nitsan-ai/RAGSUITE.git';
+
+function defaultInstallDir() {
+  return path.join(os.homedir(), 'ragsuite-test');
+}
+
+function requireGit() {
+  const which = spawnSync('which', ['git'], { encoding: 'utf8' });
+  if (which.status !== 0) {
+    const err = new Error(
+      'git is required for --from-git. Install: macOS `xcode-select --install` or `brew install git`; Linux `sudo apt install git`',
+    );
+    err.code = 'MISSING_GIT';
+    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;
+}
+
+/**
+ * Shallow-clone a public (or authenticated) git repo into installDir.
+ * @returns {{ repoRoot: string, gitUrl: string }}
+ */
+function cloneGitToInstallDir(gitUrl, options = {}) {
+  const { installDir, force = false, depth = 1 } = options;
+  requireGit();
+
+  const url = String(gitUrl || DEFAULT_GIT_URL).trim();
+  if (!url) {
+    const err = new Error('--from-git requires a repository URL');
+    err.code = 'GIT_URL_INVALID';
+    throw err;
+  }
+
+  const target = path.resolve(installDir);
+  if (!isDirEmptyOrMissing(target)) {
+    if (!force) {
+      const err = new Error(
+        `Install directory is not empty: ${target}. Pass --force to remove and re-clone, or choose another --install-dir.`,
+      );
+      err.code = 'INSTALL_DIR_NONEMPTY';
+      throw err;
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  const args = ['clone', `--depth=${depth}`, url, target];
+  const result = spawnSync('git', args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || result.stdout || '').trim();
+    const err = new Error(
+      `git clone failed for ${url}: ${stderr || `exit ${result.status}`}. ` +
+        'Repo must be public (or you must be authenticated). Or clone manually and use init --repo-root.',
+    );
+    err.code = 'GIT_CLONE_FAILED';
+    throw err;
+  }
+
+  const repoRoot = target;
+  if (!looksLikeRepoRoot(repoRoot) && !looksLikeFullBundleRoot(repoRoot)) {
+    const err = new Error(
+      `Cloned repo at ${repoRoot} does not look like a RAGSuite monorepo (missing scripts/docker-start.sh).`,
+    );
+    err.code = 'GIT_INVALID_REPO';
+    throw err;
+  }
+
+  return { repoRoot, gitUrl: url };
+}
+
+module.exports = {
+  DEFAULT_GIT_URL,
+  defaultInstallDir,
+  requireGit,
+  cloneGitToInstallDir,
+};

package/src/utils/paths.js

@@ -91,7 +91,7 @@ function resolveRepoRoot({
   }
 
   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>',
+    'Could not find RAGSuite repo root. Pass --repo-root <path>, set RAGSUITE_REPO_ROOT, or run: ragsuite-test init --from-git',
   );
   err.code = 'NOT_REPO_ROOT';
   throw err;

package/src/utils/port.js

@@ -61,7 +61,21 @@ async function assertPortsFree(ports = DEFAULT_INSTALL_PORTS) {
   }
   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.`,
+      [
+        `Port(s) already in use: ${busy.join(', ')}.`,
+        'Free them, then retry. This CLI will not kill foreign processes.',
+        '',
+        'If a previous RAGSuite install is running:',
+        '  ragsuite-test stop --repo-root ~/ragsuite-test',
+        '  # or from a monorepo checkout: cd <checkout> && npm run down',
+        '',
+        'See what owns the ports (macOS/Linux):',
+        '  lsof -nP -iTCP:9090 -sTCP:LISTEN',
+        '  lsof -nP -iTCP:9091 -sTCP:LISTEN',
+        '  lsof -nP -iTCP:5436 -sTCP:LISTEN',
+        '  lsof -nP -iTCP:6382 -sTCP:LISTEN',
+        '  docker ps',
+      ].join('\n'),
     );
     err.code = 'PORT_IN_USE';
     throw err;