@nitsan-ai/ragsuite-test 0.1.0

package/src/commands/update.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveRepoRoot } = require('../utils/paths');
+const { readConfig } = require('../utils/config');
+const { captureCommand } = require('../utils/spawn');
+const { info, warn } = require('../utils/log');
+
+const name = 'update';
+const summary = 'Verify install path and print safe update steps';
+
+function help() {
+  return `Usage: ragsuite-test update [options]
+
+Verifies the install/repo path and prints safe update steps.
+ZIP installs: download a newer ZIP and extract to a new dir (or backup + --force).
+Checkout installs: optional git fetch + status (no reset).
+
+Never runs docker compose down -v.
+
+Options:
+  --repo-root <path>       Monorepo / install root
+`;
+}
+
+function run(ctx) {
+  const repoRoot = resolveRepoRoot({
+    cwd: ctx.cwd,
+    repoRootFlag: ctx.globals.repoRoot,
+    env: ctx.env,
+  });
+
+  const cfg = readConfig(repoRoot);
+  const source = cfg && cfg.source === 'zip' ? 'zip' : 'checkout';
+
+  info(`Install path OK: ${repoRoot}`);
+  info(`  source=${source}`);
+  info('');
+
+  if (source === 'zip') {
+    info('This install came from a ZIP. Safe update steps:');
+    info('  1. ragsuite-test stop --repo-root ' + repoRoot);
+    info('  2. Download a newer release ZIP (do not wipe Docker volumes)');
+    info('  3. Extract to a NEW directory, e.g. --install-dir ~/ragsuite-test-v2');
+    info('     or: backup this dir, then init --from-zip … --force');
+    info('  4. Copy your .env into the new install (do not commit secrets)');
+    info('  5. ragsuite-test doctor --repo-root <new-dir>');
+    info('  6. ragsuite-test start --repo-root <new-dir>');
+    info('');
+    info('Never: docker compose down -v (destroys Postgres/Chroma data).');
+    return 0;
+  }
+
+  info('Safe update steps (checkout install):');
+  info('  1. Stop the stack (ragsuite-test stop --repo-root …)');
+  info('  2. Update sources (git pull when you have remote access)');
+  info('  3. Docker: npm run rebuild or docker compose build');
+  info('  4. Native: re-run backend/scripts/setup.sh if Python deps changed');
+  info('  5. Start again (ragsuite-test start --repo-root …)');
+  info('  6. Run doctor after upgrades');
+  info('');
+
+  const gitDir = path.join(repoRoot, '.git');
+  if (!fs.existsSync(gitDir)) {
+    warn('No .git directory — skip fetch/status (ZIP or packed tree).');
+    return 0;
+  }
+
+  const remote = captureCommand('git', ['remote', '-v'], { cwd: repoRoot, env: ctx.env });
+  if (remote.status !== 0 || !String(remote.stdout || '').trim()) {
+    warn('No git remote configured — skip fetch.');
+    return 0;
+  }
+
+  info('Git remotes:');
+  info(String(remote.stdout).trimEnd());
+  info('');
+  info('Running git fetch (non-destructive)…');
+  const fetch = captureCommand('git', ['fetch', '--all', '--prune'], {
+    cwd: repoRoot,
+    env: ctx.env,
+  });
+  if (fetch.status !== 0) {
+    warn(
+      `git fetch failed (exit ${fetch.status}). Private remotes need credentials. Continuing with status only.`,
+    );
+    if (fetch.stderr) warn(String(fetch.stderr).trimEnd());
+  } else {
+    info('git fetch OK');
+  }
+
+  const status = captureCommand('git', ['status', '-sb'], { cwd: repoRoot, env: ctx.env });
+  if (status.stdout) {
+    info('');
+    info(String(status.stdout).trimEnd());
+  }
+  return 0;
+}
+
+module.exports = { name, summary, help, run };

package/src/commands/version.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const path = require('path');
+const { info } = require('../utils/log');
+
+const name = 'version';
+const summary = 'Print CLI package version';
+
+function help() {
+  return `Usage: ragsuite-test version
+
+Print @nitsan-ai/ragsuite-test version from package.json.
+`;
+}
+
+function run() {
+  const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+  const pkg = require(pkgPath);
+  info(`${pkg.name}@${pkg.version}`);
+  return 0;
+}
+
+module.exports = { name, summary, help, run };

package/src/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+const { parseArgv } = require('./utils/args');
+const { error, info } = require('./utils/log');
+
+const commands = {
+  init: require('./commands/init'),
+  start: require('./commands/start'),
+  stop: require('./commands/stop'),
+  doctor: require('./commands/doctor'),
+  logs: require('./commands/logs'),
+  update: require('./commands/update'),
+  version: require('./commands/version'),
+};
+
+function globalHelp() {
+  const lines = [
+    'RAGSuite test CLI (experimental)',
+    '',
+    'Usage: ragsuite-test <command> [options]',
+    '       (from cli/: node src/index.js <command> [options])',
+    '',
+    'Commands:',
+  ];
+  for (const cmd of Object.values(commands)) {
+    lines.push(`  ${cmd.name.padEnd(10)} ${cmd.summary}`);
+  }
+  lines.push(
+    '',
+    'Global options:',
+    '  --help, -h              Show help',
+    '  --repo-root <path>      Monorepo / install root',
+    '  --from-zip <path>       init: extract app ZIP',
+    '  --install-dir <path>    init: ZIP target (default ~/ragsuite-test)',
+    '  --from-release <tag>    init: stub (not implemented)',
+    '  --llm-api-key <key>     init: CUSTOM_LLM_INTERNAL_API_KEY (--yes)',
+    '  --force                 init: overwrite non-empty install dir / .env',
+    '  --yes, -y               Non-interactive',
+    '  --mode <docker|native>  Override .ragsuite-test/config.json / RAGSUITE_MODE',
+    '  --dry-run               Print actions without running (start/stop/doctor/logs)',
+    '',
+    'Env: RAGSUITE_REPO_ROOT or RAGSUITE_INSTALL_DIR',
+    '',
+    'Run ragsuite-test <command> --help for command details.',
+  );
+  return lines.join('\n');
+}
+
+async function main(argv = process.argv) {
+  let parsed;
+  try {
+    parsed = parseArgv(argv);
+  } catch (err) {
+    error(err.message || String(err));
+    return 1;
+  }
+
+  const { globals, command, commandArgs, commandHelp } = parsed;
+
+  if (!command) {
+    info(globalHelp());
+    return 0;
+  }
+
+  const cmd = commands[command];
+  if (!cmd) {
+    error(`Unknown command: ${command}`);
+    info('');
+    info(globalHelp());
+    return 1;
+  }
+
+  if (globals.help || commandHelp) {
+    info(cmd.help());
+    return 0;
+  }
+
+  const ctx = {
+    cwd: process.cwd(),
+    env: process.env,
+    globals,
+    commandArgs,
+  };
+
+  try {
+    const result = cmd.run(ctx);
+    const code = typeof result?.then === 'function' ? await result : result;
+    return typeof code === 'number' ? code : 0;
+  } catch (err) {
+    if (err && (err.code === 'NOT_REPO_ROOT' || err.code === 'USAGE' || err.code === 'ZIP_SLIP' || err.code === 'INSTALL_DIR_NONEMPTY' || err.code === 'ZIP_INVALID' || err.code === 'ZIP_MISSING' || err.code === 'ENV_EXISTS' || err.code === 'PORT_IN_USE' || err.code === 'LLM_KEY_INVALID')) {
+      error(err.message);
+      return 1;
+    }
+    error(err.message || String(err));
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  main().then((code) => {
+    process.exit(code);
+  });
+}
+
+module.exports = { main, commands, globalHelp };

package/src/utils/args.js

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * 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);
+  const globals = {
+    help: false,
+    repoRoot: null,
+    dryRun: false,
+    mode: null,
+    fromZip: null,
+    fromRelease: null,
+    installDir: null,
+    force: false,
+    yes: false,
+    llmApiKey: null,
+  };
+  const rest = [];
+  let command = null;
+
+  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;
+      }
+      continue;
+    }
+
+    if (t === '--dry-run') {
+      globals.dryRun = true;
+      continue;
+    }
+
+    if (t === '--force') {
+      globals.force = true;
+      continue;
+    }
+
+    if (t === '--yes' || t === '-y') {
+      globals.yes = true;
+      continue;
+    }
+
+    if (t === '--repo-root' || t.startsWith('--repo-root=')) {
+      const value = t.startsWith('--repo-root=')
+        ? t.slice('--repo-root='.length)
+        : tokens[++i];
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--repo-root requires a path');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.repoRoot = value;
+      continue;
+    }
+
+    if (t === '--mode' || t.startsWith('--mode=')) {
+      const value = t.startsWith('--mode=') ? t.slice('--mode='.length) : tokens[++i];
+      if (!value || String(value).startsWith('-')) {
+        const err = new Error('--mode requires docker or native');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.mode = normalizeMode(value);
+      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;
+      }
+      globals.fromZip = value;
+      continue;
+    }
+
+    if (t === '--from-release' || t.startsWith('--from-release=')) {
+      const value = t.startsWith('--from-release=')
+        ? t.slice('--from-release='.length)
+        : tokens[++i];
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--from-release requires a tag or "latest"');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.fromRelease = value;
+      continue;
+    }
+
+    if (t === '--install-dir' || t.startsWith('--install-dir=')) {
+      const value = t.startsWith('--install-dir=')
+        ? t.slice('--install-dir='.length)
+        : tokens[++i];
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--install-dir requires a path');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.installDir = value;
+      continue;
+    }
+
+    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];
+      if (!value || value.startsWith('-')) {
+        const err = new Error('--llm-api-key requires a value');
+        err.code = 'USAGE';
+        throw err;
+      }
+      globals.llmApiKey = value;
+      continue;
+    }
+
+    if (!command && !t.startsWith('-')) {
+      command = t;
+      continue;
+    }
+
+    rest.push(t);
+  }
+
+  const commandHelp = rest.includes('--help') || rest.includes('-h');
+  const commandArgs = rest.filter((a) => a !== '--help' && a !== '-h');
+
+  return { globals, command, commandArgs, commandHelp };
+}
+
+function normalizeMode(value) {
+  const m = String(value).trim().toLowerCase();
+  if (m !== 'docker' && m !== 'native') {
+    const err = new Error(`Invalid mode "${value}" (use docker or native)`);
+    err.code = 'USAGE';
+    throw err;
+  }
+  return m;
+}
+
+module.exports = { parseArgv, normalizeMode };

package/src/utils/config.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_VERSION = 1;
+const CONFIG_DIR = '.ragsuite-test';
+
+function configPath(repoRoot) {
+  return path.join(repoRoot, CONFIG_DIR, 'config.json');
+}
+
+function defaultConfig(repoRoot, mode = 'docker') {
+  const root = path.resolve(repoRoot);
+  return {
+    version: CONFIG_VERSION,
+    mode: mode === 'native' ? 'native' : 'docker',
+    source: 'checkout',
+    repoRoot: root,
+    installDir: root,
+  };
+}
+
+function readConfig(repoRoot) {
+  const file = configPath(repoRoot);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || typeof raw !== 'object') {
+      return null;
+    }
+    const source = raw.source === 'zip' ? 'zip' : 'checkout';
+    return {
+      version: Number(raw.version) || CONFIG_VERSION,
+      mode: raw.mode === 'native' ? 'native' : 'docker',
+      source,
+      repoRoot: path.resolve(String(raw.repoRoot || repoRoot)),
+      installDir: path.resolve(String(raw.installDir || raw.repoRoot || repoRoot)),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(repoRoot, partial = {}) {
+  const dir = path.join(repoRoot, CONFIG_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const existing = readConfig(repoRoot) || defaultConfig(repoRoot);
+  const source =
+    partial.source === 'zip' || partial.source === 'checkout'
+      ? partial.source
+      : existing.source || 'checkout';
+  const next = {
+    ...existing,
+    ...partial,
+    version: CONFIG_VERSION,
+    source,
+    repoRoot: path.resolve(partial.repoRoot || existing.repoRoot || repoRoot),
+    installDir: path.resolve(
+      partial.installDir || existing.installDir || partial.repoRoot || existing.repoRoot || repoRoot,
+    ),
+    mode: (partial.mode || existing.mode) === 'native' ? 'native' : 'docker',
+  };
+  fs.writeFileSync(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+/**
+ * Resolve runtime mode: CLI --mode > config > RAGSUITE_MODE > docker.
+ */
+function resolveMode({ flagMode, repoRoot, env = process.env } = {}) {
+  if (flagMode === 'docker' || flagMode === 'native') {
+    return flagMode;
+  }
+  if (repoRoot) {
+    const cfg = readConfig(repoRoot);
+    if (cfg && (cfg.mode === 'docker' || cfg.mode === 'native')) {
+      return cfg.mode;
+    }
+  }
+  const fromEnv = String(env.RAGSUITE_MODE || '')
+    .trim()
+    .toLowerCase();
+  if (fromEnv === 'native') {
+    return 'native';
+  }
+  return 'docker';
+}
+
+module.exports = {
+  CONFIG_VERSION,
+  CONFIG_DIR,
+  configPath,
+  defaultConfig,
+  readConfig,
+  writeConfig,
+  resolveMode,
+};

package/src/utils/distribution.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * 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.
+ */
+
+const MODE_LOCAL = 'local-checkout';
+const MODE_ZIP = 'zip-bundle';
+const MODE_REGISTRY = 'registry-compose';
+
+function assertSupportedInstall() {
+  // checkout + zip supported
+}
+
+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>.',
+  );
+  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.';
+}
+
+module.exports = {
+  MODE_LOCAL,
+  MODE_ZIP,
+  MODE_REGISTRY,
+  mode: MODE_ZIP,
+  assertSupportedInstall,
+  resolveComposeBundle,
+  installHint,
+};

package/src/utils/env-file.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { warn } = require('./log');
+
+function generateJwtSecret() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+function generateCiLlmKey() {
+  return `ci-test-llm-key-${crypto.randomBytes(8).toString('hex')}`;
+}
+
+function isPlaceholderSecret(value) {
+  const v = String(value || '').trim();
+  return !v || v.startsWith('change-me');
+}
+
+/**
+ * Build .env content from .env.example with overrides.
+ */
+function buildEnvFromExample(examplePath, overrides = {}) {
+  if (!fs.existsSync(examplePath)) {
+    const err = new Error(`Missing .env.example at ${examplePath}`);
+    err.code = 'ENV_EXAMPLE_MISSING';
+    throw err;
+  }
+  const raw = fs.readFileSync(examplePath, 'utf8');
+  const lines = raw.split(/\r?\n/);
+  const keysSet = new Set(Object.keys(overrides));
+  const out = [];
+  const seen = new Set();
+
+  for (const line of lines) {
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) {
+      out.push(line);
+      continue;
+    }
+    const key = m[1];
+    if (Object.prototype.hasOwnProperty.call(overrides, key)) {
+      out.push(`${key}=${overrides[key]}`);
+      seen.add(key);
+    } else {
+      out.push(line);
+    }
+  }
+
+  for (const key of keysSet) {
+    if (!seen.has(key)) {
+      out.push(`${key}=${overrides[key]}`);
+    }
+  }
+
+  return `${out.join('\n').replace(/\n+$/, '')}\n`;
+}
+
+/**
+ * Write .env. Refuse overwrite unless force.
+ * @returns {{ jwt: string, llmKey: string, smtpSkipped: boolean }}
+ */
+function writeInstallEnv(repoRoot, options = {}) {
+  const {
+    force = false,
+    jwtSecret = generateJwtSecret(),
+    llmApiKey,
+    smtpSkipped = true,
+  } = options;
+
+  const envPath = path.join(repoRoot, '.env');
+  const examplePath = path.join(repoRoot, '.env.example');
+
+  if (fs.existsSync(envPath) && !force) {
+    const err = new Error(
+      `.env already exists at ${envPath}. Pass --force to regenerate from .env.example (will overwrite).`,
+    );
+    err.code = 'ENV_EXISTS';
+    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 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('');
+  }
+
+  const content = buildEnvFromExample(examplePath, overrides);
+  fs.writeFileSync(envPath, content, 'utf8');
+  return { jwt: jwtSecret, llmKey: llmApiKey, smtpSkipped: Boolean(smtpSkipped), envPath };
+}
+
+function readEnvValue(envPath, key) {
+  if (!fs.existsSync(envPath)) return null;
+  const text = fs.readFileSync(envPath, 'utf8');
+  const re = new RegExp(`^${key}=(.*)$`, 'm');
+  const m = text.match(re);
+  return m ? m[1].trim() : null;
+}
+
+module.exports = {
+  generateJwtSecret,
+  generateCiLlmKey,
+  isPlaceholderSecret,
+  buildEnvFromExample,
+  writeInstallEnv,
+  readEnvValue,
+};

package/src/utils/log.js

@@ -0,0 +1,15 @@
+'use strict';
+
+function info(message) {
+  console.log(message);
+}
+
+function warn(message) {
+  console.error(`warn: ${message}`);
+}
+
+function error(message) {
+  console.error(`error: ${message}`);
+}
+
+module.exports = { info, warn, error };

package/src/utils/os-detect.js

@@ -0,0 +1,12 @@
+'use strict';
+
+function detectOs() {
+  const platform = process.platform;
+  let label = platform;
+  if (platform === 'darwin') label = 'macOS';
+  else if (platform === 'linux') label = 'Linux';
+  else if (platform === 'win32') label = 'Windows';
+  return { platform, label };
+}
+
+module.exports = { detectOs };