@nitsan-ai/ragsuite-test 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitsan AI / RAGSuite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# RAGSuite test CLI (`ragsuite-test`)
+
+> **TESTING PACKAGE** — `@nitsan-ai/ragsuite-test` / `ragsuite-test` is temporary.
+> **Not** the final production `@nitsan-ai/ragsuite` / `ragsuite` CLI (later release).
+> Do **not** treat this as the long-term npm identity.
+
+Wraps monorepo Docker/native scripts. Does **not** reimplement compose.
+
+Requires **Node.js 18+**.
+
+**Run modes (both fully supported):**
+
+| Situation | Mode | Command |
+|-----------|------|---------|
+| You have Docker | `docker` (default) | `ragsuite-test init … --mode docker` then `start` |
+| No Docker | `native` | Need Postgres **:5436** + Redis **:6382** on the host, then `ragsuite-test init … --mode native` then `start` |
+
+Docker is **not** mandatory — choose native in the wizard or pass `--mode native`.
+
+**Full tester steps:** [TEST_DISTRIBUTION.md](./TEST_DISTRIBUTION.md)
+
+## Quick start (wizard)
+
+```bash
+bash scripts/build-release-zip.sh
+cd cli && npm pack && npm install -g ./nitsan-ai-ragsuite-test-*.tgz
+
+# Interactive:
+ragsuite-test init
+
+# Or CI / noninteractive:
+ragsuite-test init --yes \
+  --from-zip ../dist/ragsuite-server-test-1.0.0.zip \
+  --install-dir ~/ragsuite-test \
+  --mode docker \
+  --llm-api-key 'your-key'
+
+ragsuite-test start --repo-root ~/ragsuite-test --detach
+# API http://localhost:9090  ·  Web http://localhost:9091
+```
+
+`init` auto-generates `JWT_SECRET_KEY`, writes `.ragsuite-test/config.json`, checks ports **9090 / 9091 / 5436 / 6382**, and warns if SMTP is skipped (invites/email may fail).
+
+## Install sources
+
+| Method | Flag |
+|--------|------|
+| Local ZIP | `--from-zip` (recommended for private testing) |
+| Existing checkout | `--repo-root` |
+| GitHub Release | `--from-release` — not implemented yet |
+
+Making GitHub public is **not** required for ZIP installs.
+
+## Config
+
+- CLI: `<install>/.ragsuite-test/config.json`
+- Native PID/logs: `<install>/.ragsuite/native/` (Phase 4 scripts)
+
+## Commands
+
+| Command | Behavior |
+|---------|----------|
+| `init` | Installer wizard (ZIP/checkout → .env + config) |
+| `start` / `stop` | `scripts/docker-*.sh` or `native-*.sh` |
+| `doctor` | `scripts/doctor.sh` |
+| `logs` / `update` / `version` | As before |
+
+## Publish (testing package only — Phase 12)
+
+See [PUBLISH.md](./PUBLISH.md) (full runbook) and [TEST_DISTRIBUTION.md](./TEST_DISTRIBUTION.md) (tester steps + go/no-go).
+
+```bash
+cd cli && npm run prepublish:check
+# Only when someone says "publish now":
+RAGSUITE_TEST_ALLOW_PUBLISH=1 npm publish --access public
+# Or: GitHub Actions → CLI publish (workflow_dispatch, NPM_TOKEN)
+# Optional app ZIP: Actions → Release app ZIP
+```
+
+## Windows
+
+Use WSL or Git Bash (`bash` scripts).
+
+## Tests
+
+```bash
+cd cli && npm test && npm run prepublish:check
+```

package/bin/ragsuite-test.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+
+const major = Number(String(process.versions.node).split('.')[0]);
+if (!Number.isFinite(major) || major < 18) {
+  console.error(
+    `RAGSuite test CLI requires Node.js 18 or newer. Current: ${process.version}`,
+  );
+  process.exit(1);
+}
+
+const { main } = require('../src/index.js');
+
+main()
+  .then((code) => {
+    process.exit(typeof code === 'number' ? code : 0);
+  })
+  .catch((err) => {
+    console.error(err && err.message ? err.message : String(err));
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nitsan-ai/ragsuite-test",
+  "version": "0.1.0",
+  "private": false,
+  "description": "RAGSuite testing CLI (ragsuite-test) — install from ZIP or --repo-root checkout. Temporary npm identity before public ragsuite release.",
+  "main": "src/index.js",
+  "bin": {
+    "ragsuite-test": "./bin/ragsuite-test.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/smoke.js",
+    "test:pack": "node test/pack-assert.js",
+    "prepublish:check": "node scripts/prepublish-check.js",
+    "prepublishOnly": "node scripts/require-publish-allow.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const path = require('path');
+const { resolveMode } = require('../utils/config');
+const { resolveRepoRoot } = require('../utils/paths');
+const { runScript } = require('../utils/spawn');
+
+const name = 'doctor';
+const summary = 'Run scripts/doctor.sh prerequisite checks';
+
+function help() {
+  return `Usage: ragsuite-test doctor [options]
+
+Runs scripts/doctor.sh. Mode selects which checklist gates the exit code
+(RAGSUITE_MODE / config / --mode). Both mode sections are still printed.
+
+Options:
+  --mode <docker|native>   Gate exit on this mode (default: docker)
+  --repo-root <path>       Monorepo root
+  --dry-run                Print the script path and exit 0
+`;
+}
+
+function run(ctx) {
+  const repoRoot = resolveRepoRoot({
+    cwd: ctx.cwd,
+    repoRootFlag: ctx.globals.repoRoot,
+  });
+  const mode = resolveMode({
+    flagMode: ctx.globals.mode,
+    repoRoot,
+    env: ctx.env,
+  });
+  return runScript(repoRoot, path.join('scripts', 'doctor.sh'), [], {
+    dryRun: ctx.globals.dryRun,
+    env: { ...ctx.env, RAGSUITE_MODE: mode },
+  });
+}
+
+module.exports = { name, summary, help, run };

package/src/commands/init.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { writeConfig, CONFIG_DIR } = require('../utils/config');
+const { ensureRagsuiteDir, resolveRepoRoot, looksLikeRepoRoot } = require('../utils/paths');
+const { assertSupportedInstall, installHint } = require('../utils/distribution');
+const {
+  defaultInstallDir,
+  extractZipToInstallDir,
+} = require('../utils/zip-install');
+const { detectOs } = require('../utils/os-detect');
+const { printPrereqs, checkPrereqs } = require('../utils/prereqs');
+const { ask, confirm, choose } = require('../utils/prompt');
+const {
+  generateJwtSecret,
+  generateCiLlmKey,
+  isPlaceholderSecret,
+  writeInstallEnv,
+} = require('../utils/env-file');
+const { assertPortsFree } = require('../utils/port');
+const { info, warn, error } = require('../utils/log');
+
+const name = 'init';
+const summary = 'Installer wizard: ZIP or checkout → .env + config';
+
+function help() {
+  return `Usage: ragsuite-test init [options]
+
+Interactive installer (or --yes for CI) that:
+  - detects OS / prerequisites
+  - installs from ZIP or configures a checkout
+  - writes .ragsuite-test/config.json and .env (JWT auto-generated)
+  - checks ports 9090, 9091, 5436, 6382
+
+Install sources:
+  --from-zip <path>        Extract app ZIP into --install-dir
+  --repo-root <path>       Use an existing monorepo checkout
+  --from-release <tag>     Not implemented (download ZIP manually)
+
+Options:
+  --install-dir <path>     ZIP target (default: ~/ragsuite-test)
+  --mode <docker|native>   docker = Docker stack; native = no Docker (needs host Postgres/Redis)
+  --llm-api-key <key>      CUSTOM_LLM_INTERNAL_API_KEY (--yes)
+  --force                  Overwrite non-empty install dir / existing .env
+  --yes, -y                Non-interactive (requires --from-zip or --repo-root)
+`;
+}
+
+function printSuccess(repoRoot, mode) {
+  info('');
+  info('=== Install complete ===');
+  info(`  Install dir : ${repoRoot}`);
+  info(`  Mode        : ${mode}`);
+  info(`  Config      : ${path.join(repoRoot, CONFIG_DIR, 'config.json')}`);
+  info('');
+  info('  API  http://localhost:9090');
+  if (mode === 'native') {
+    info('  Web  http://localhost:9191  (Expo web — native mode)');
+  } else {
+    info('  Web  http://localhost:9091  (Docker nginx)');
+  }
+  info('');
+  info('  Mode reminder: docker needs Docker; native needs host Postgres/Redis (no Docker required).');
+  info('  Each install directory is one deployment / one organization.');
+  info('');
+  info('Next steps:');
+  info(`  1. ragsuite-test start --repo-root ${repoRoot}${mode === 'docker' ? ' --detach' : ''}`);
+  if (mode === 'native') {
+    info('  2. Open http://localhost:9191 and bootstrap the first admin');
+  } else {
+    info('  2. Open http://localhost:9091 and bootstrap the first admin');
+  }
+  info(`  3. ragsuite-test doctor --repo-root ${repoRoot}`);
+  info('');
+  info(installHint());
+}
+
+async function resolveLlmKey(g, env, interactive) {
+  if (g.llmApiKey && !isPlaceholderSecret(g.llmApiKey)) {
+    return g.llmApiKey;
+  }
+  if (env.RAGSUITE_TEST_LLM_API_KEY && !isPlaceholderSecret(env.RAGSUITE_TEST_LLM_API_KEY)) {
+    return env.RAGSUITE_TEST_LLM_API_KEY;
+  }
+  if (g.yes || !interactive) {
+    const key = generateCiLlmKey();
+    warn(`Using generated smoke LLM key (${key.slice(0, 18)}…). Set a real CUSTOM_LLM_INTERNAL_API_KEY for production-like tests.`);
+    return key;
+  }
+  for (;;) {
+    const key = await ask('CUSTOM_LLM_INTERNAL_API_KEY', { yesMode: false });
+    if (!isPlaceholderSecret(key)) return key;
+    error('Key required and must not start with change-me');
+  }
+}
+
+async function run(ctx) {
+  assertSupportedInstall();
+  const g = ctx.globals;
+  const interactive = Boolean(process.stdin.isTTY) && !g.yes;
+
+  if (g.fromRelease) {
+    error(
+      `--from-release is not implemented. Download a ZIP (private Release asset or local file), then: ragsuite-test init --from-zip <file.zip>`,
+    );
+    return 1;
+  }
+
+  if (g.fromZip && g.repoRoot) {
+    error('Use either --from-zip or --repo-root, not both');
+    return 1;
+  }
+
+  const osInfo = detectOs();
+  info(`OS: ${osInfo.label} (${osInfo.platform})`);
+
+  let mode = g.mode || 'docker';
+  let fromZip = g.fromZip;
+  let repoRootFlag = g.repoRoot;
+  let installDir = g.installDir || defaultInstallDir();
+
+  if (g.yes) {
+    if (!fromZip && !repoRootFlag) {
+      error('--yes requires --from-zip <path> or --repo-root <path>');
+      return 1;
+    }
+  } else if (interactive && !fromZip && !repoRootFlag) {
+    const method = await choose(
+      'Install method:',
+      [
+        { id: 'zip', label: 'Local ZIP file (--from-zip)' },
+        { id: 'checkout', label: 'Existing checkout (--repo-root)' },
+      ],
+      { defaultIndex: 0 },
+    );
+    if (method.id === 'zip') {
+      fromZip = await ask('Path to app ZIP', { yesMode: false });
+      if (!fromZip) {
+        error('ZIP path required');
+        return 1;
+      }
+      installDir = await ask('Install directory', {
+        defaultValue: defaultInstallDir(),
+        yesMode: false,
+      });
+    } else {
+      repoRootFlag = await ask('Path to existing RAGSUITE checkout', { yesMode: false });
+      if (!repoRootFlag || !looksLikeRepoRoot(path.resolve(repoRootFlag))) {
+        error('Not a valid checkout (need scripts/docker-start.sh)');
+        return 1;
+      }
+    }
+
+    const modeChoice = await choose(
+      'Run mode (Docker is optional):',
+      [
+        { id: 'docker', label: 'Docker — if you have Docker Desktop / daemon (default)' },
+        { id: 'native', label: 'Native — no Docker; needs Postgres :5436 + Redis :6382 on this machine' },
+      ],
+      { defaultIndex: 0 },
+    );
+    mode = modeChoice.id;
+  } else if (!fromZip && !repoRootFlag) {
+    error('Pass --from-zip / --repo-root, or run in a TTY for the interactive wizard');
+    return 1;
+  }
+
+  if (!printPrereqs(mode)) {
+    error('Fix prerequisites above and re-run init');
+    return 1;
+  }
+
+  const jwtSecret = generateJwtSecret();
+  info(`JWT_SECRET_KEY will be auto-generated (…${jwtSecret.slice(-8)})`);
+
+  const llmKey = await resolveLlmKey(g, ctx.env, interactive);
+
+  let smtpSkipped = true;
+  if (interactive && !g.yes) {
+    const configureSmtp = await confirm('Configure SMTP now? (needed for invites/email)', {
+      defaultYes: false,
+    });
+    smtpSkipped = !configureSmtp;
+    if (!smtpSkipped) {
+      info('After init, edit SMTP_* in .env (SMTP_HOST, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM).');
+    }
+  } else {
+    warn('SMTP skipped (--yes / noninteractive). Invites/email may fail until SMTP_* is set.');
+  }
+
+  // Port checks before mutating install (clearer UX)
+  try {
+    await assertPortsFree();
+  } catch (err) {
+    error(err.message);
+    return 1;
+  }
+
+  let repoRoot;
+  let source = 'checkout';
+
+  try {
+    if (fromZip) {
+      info(`Extracting ZIP → ${path.resolve(installDir)}`);
+      const result = extractZipToInstallDir(fromZip, {
+        installDir,
+        force: g.force,
+      });
+      repoRoot = result.repoRoot;
+      source = 'zip';
+      info(`Installed app at ${repoRoot}`);
+    } else {
+      repoRoot = resolveRepoRoot({
+        cwd: ctx.cwd,
+        repoRootFlag,
+        env: ctx.env,
+      });
+    }
+  } catch (err) {
+    error(err.message || String(err));
+    return 1;
+  }
+
+  ensureRagsuiteDir(repoRoot);
+  const cfg = writeConfig(repoRoot, {
+    mode,
+    source,
+    repoRoot,
+    installDir: repoRoot,
+  });
+
+  try {
+    writeInstallEnv(repoRoot, {
+      force: g.force,
+      jwtSecret,
+      llmApiKey: llmKey,
+      smtpSkipped,
+    });
+  } catch (err) {
+    if (err.code === 'ENV_EXISTS') {
+      error(err.message);
+      return 1;
+    }
+    error(err.message || String(err));
+    return 1;
+  }
+
+  info(`Wrote ${path.join(repoRoot, CONFIG_DIR, 'config.json')}`);
+  info(`  mode=${cfg.mode} source=${cfg.source}`);
+  printSuccess(repoRoot, mode);
+  return 0;
+}
+
+module.exports = { name, summary, help, run };

package/src/commands/logs.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveMode } = require('../utils/config');
+const { resolveRepoRoot, nativeLogDir } = require('../utils/paths');
+const { runCommand } = require('../utils/spawn');
+const { error, info } = require('../utils/log');
+
+const name = 'logs';
+const summary = 'Follow Docker compose or native process logs';
+
+function help() {
+  return `Usage: ragsuite-test logs [options]
+
+Docker mode: docker compose logs -f (same as root npm run logs).
+Native mode: tail -f .ragsuite/native/*.log when present.
+
+Options:
+  --mode <docker|native>   Override config / RAGSUITE_MODE
+  --repo-root <path>       Monorepo root
+  --dry-run                Print the command and exit 0
+`;
+}
+
+function run(ctx) {
+  const repoRoot = resolveRepoRoot({
+    cwd: ctx.cwd,
+    repoRootFlag: ctx.globals.repoRoot,
+  });
+  const mode = resolveMode({
+    flagMode: ctx.globals.mode,
+    repoRoot,
+    env: ctx.env,
+  });
+
+  if (mode === 'native') {
+    const dir = nativeLogDir(repoRoot);
+    let logs = [];
+    if (fs.existsSync(dir)) {
+      logs = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.log'))
+        .map((f) => path.join(dir, f));
+    }
+    if (logs.length === 0) {
+      error(
+        `No native log files under ${dir}. Start with mode=native first, or use --mode docker.`,
+      );
+      return 1;
+    }
+    info(`Following ${logs.length} native log file(s)…`);
+    return runCommand('tail', ['-f', ...logs], {
+      cwd: repoRoot,
+      dryRun: ctx.globals.dryRun,
+      env: ctx.env,
+    });
+  }
+
+  return runCommand('docker', ['compose', 'logs', '-f'], {
+    cwd: repoRoot,
+    dryRun: ctx.globals.dryRun,
+    env: ctx.env,
+  });
+}
+
+module.exports = { name, summary, help, run };

package/src/commands/start.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const path = require('path');
+const { resolveMode } = require('../utils/config');
+const { resolveRepoRoot } = require('../utils/paths');
+const { runScript } = require('../utils/spawn');
+const { assertApiPortFree } = require('../utils/port');
+const { error } = require('../utils/log');
+
+const name = 'start';
+const summary = 'Start stack via docker-start.sh or native-start.sh';
+
+function help() {
+  return `Usage: ragsuite-test start [options] [-- script-args...]
+
+Calls scripts/docker-start.sh (mode=docker) or scripts/native-start.sh (mode=native).
+Does not reimplement compose logic. Extra args after -- are forwarded (e.g. --detach).
+
+Options:
+  --mode <docker|native>   Override config / RAGSUITE_MODE
+  --repo-root <path>       Monorepo root
+  --dry-run                Print the script path and exit 0
+  --detach, -d             Forwarded to docker-start.sh (also accepted without --)
+`;
+}
+
+async function run(ctx) {
+  const repoRoot = resolveRepoRoot({
+    cwd: ctx.cwd,
+    repoRootFlag: ctx.globals.repoRoot,
+  });
+  const mode = resolveMode({
+    flagMode: ctx.globals.mode,
+    repoRoot,
+    env: ctx.env,
+  });
+
+  const scriptName = mode === 'native' ? 'native-start.sh' : 'docker-start.sh';
+  const rel = path.join('scripts', scriptName);
+  const forward = normalizeStartArgs(ctx.commandArgs);
+
+  if (!ctx.globals.dryRun) {
+    try {
+      await assertApiPortFree(ctx.env);
+    } catch (err) {
+      error(err.message);
+      return 1;
+    }
+  }
+
+  return runScript(repoRoot, rel, forward, {
+    dryRun: ctx.globals.dryRun,
+    env: { ...ctx.env, RAGSUITE_MODE: mode },
+  });
+}
+
+function normalizeStartArgs(args) {
+  const out = [];
+  for (const a of args) {
+    if (a === '--detach' || a === '-d') {
+      out.push('--detach');
+      continue;
+    }
+    if (a === '--') continue;
+    out.push(a);
+  }
+  return out;
+}
+
+module.exports = { name, summary, help, run };

package/src/commands/stop.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const path = require('path');
+const { resolveMode } = require('../utils/config');
+const { resolveRepoRoot } = require('../utils/paths');
+const { runScript } = require('../utils/spawn');
+
+const name = 'stop';
+const summary = 'Stop stack via docker-stop.sh or native-stop.sh';
+
+function help() {
+  return `Usage: ragsuite-test stop [options]
+
+Calls scripts/docker-stop.sh or scripts/native-stop.sh based on mode.
+Never wipes Docker volumes (same as docker-stop.sh).
+
+Options:
+  --mode <docker|native>   Override config / RAGSUITE_MODE
+  --repo-root <path>       Monorepo root
+  --dry-run                Print the script path and exit 0
+`;
+}
+
+function run(ctx) {
+  const repoRoot = resolveRepoRoot({
+    cwd: ctx.cwd,
+    repoRootFlag: ctx.globals.repoRoot,
+  });
+  const mode = resolveMode({
+    flagMode: ctx.globals.mode,
+    repoRoot,
+    env: ctx.env,
+  });
+  const scriptName = mode === 'native' ? 'native-stop.sh' : 'docker-stop.sh';
+  return runScript(repoRoot, path.join('scripts', scriptName), [], {
+    dryRun: ctx.globals.dryRun,
+    env: { ...ctx.env, RAGSUITE_MODE: mode },
+  });
+}
+
+module.exports = { name, summary, help, run };