@nitsan-ai/ragsuite-test 0.1.5 → 0.1.6

package/README.md

@@ -9,11 +9,12 @@ npm install -g @nitsan-ai/ragsuite-test
 ragsuite-test init
 # clones → ~/ragsuite-test
 
-# Needs Postgres :5436 (db ragsuite_v3) and Redis :6382 on the host
+# Needs Postgres :5436 + Redis :6382 (auto-started via data-only compose if Docker is available)
 ragsuite-test start
 # API http://localhost:9090  ·  Web http://localhost:9191
 
 ragsuite-test stop
+# stops host app + leftover Docker app containers; keeps DB volumes
 ```
 
 Same under the hood as:
@@ -26,6 +27,8 @@ npm run stop       # scripts/native-stop.sh
 
 Active install is remembered in `~/.ragsuite-test/config.json`.
 
+**Data safety:** `start` may run `docker compose up -d postgres redis` only (existing volumes). It never runs `down -v`. App code always runs natively.
+
 ---
 
 ## Upgrade (keeps data & `.env`)
@@ -50,10 +53,10 @@ If you already installed and run `init` again → **Already installed** (exit OK
 | Python 3 + venv | backend |
 | Yarn | Expo frontend |
 | Git | `init` clone |
-| Postgres | `localhost:5436`, database `ragsuite_v3` |
-| Redis | `localhost:6382` |
+| Postgres + Redis | Host brew **or** data-only compose (`postgres`/`redis` services) on :5436 / :6382 |
+| Docker (optional) | Only to auto-start/reuse existing postgres/redis volumes |
 
-Docker is **not** required for this CLI.
+Docker is **not** required to run the API/UI (those are native).
 
 ---
 
@@ -61,9 +64,9 @@ Docker is **not** required for this CLI.
 
 | Command | Purpose |
 |---------|---------|
-| `init` | First-time git install |
-| `start` | `scripts/native-start.sh` |
-| `stop` | `scripts/native-stop.sh` (host PIDs only) |
+| `init` | First-time git install (no port checks) |
+| `start` | `scripts/native-start.sh` (+ data services if needed) |
+| `stop` | Native PIDs + leftover app containers (DB kept) |
 | `update` | `git pull` in place |
 | `doctor` | Native prereq checks |
 | `logs` | Tail `.ragsuite/native/*.log` |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nitsan-ai/ragsuite-test",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
-  "description": "RAGSuite testing CLI — init once, then start/update/stop via native npm scripts (no Docker).",
+  "description": "RAGSuite testing CLI — init once, then start/update/stop via native npm scripts.",
   "main": "src/index.js",
   "bin": {
     "ragsuite-test": "./bin/ragsuite-test.js"

package/src/commands/init.js

@@ -17,13 +17,12 @@ const {
 } = require('../utils/git-install');
 const { detectOs } = require('../utils/os-detect');
 const { printPrereqs, resolvePreferredMode } = require('../utils/prereqs');
+const { info, warn, error } = require('../utils/log');
 const {
   generateJwtSecret,
   isPlaceholderSecret,
   writeInstallEnv,
 } = require('../utils/env-file');
-const { assertPortsFree } = require('../utils/port');
-const { info, warn, error } = require('../utils/log');
 
 const name = 'init';
 const summary = 'First-time install (git + native npm scripts). Safe if already installed.';
@@ -217,14 +216,8 @@ async function run(ctx) {
   const llmKey = resolveLlmOverride(g, ctx.env);
   const smtp = optionalSmtpOverrides(g, ctx.env);
 
-  if (ctx.env.RAGSUITE_TEST_SKIP_PORT_CHECK !== '1') {
-    try {
-      await assertPortsFree();
-    } catch (err) {
-      error(err.message);
-      return 1;
-    }
-  }
+  // Init only installs files — do not require ports free.
+  // (Postgres/Redis being "in use" is good; API busy is a start-time concern.)
 
   let repoRoot;
   let source = 'checkout';

package/src/commands/start.js

@@ -5,16 +5,19 @@ const { resolveMode } = require('../utils/config');
 const { resolveRepoRoot, assertNativeDeploy } = require('../utils/paths');
 const { runScript } = require('../utils/spawn');
 const { assertApiPortFree } = require('../utils/port');
-const { error } = require('../utils/log');
+const { error, info } = require('../utils/log');
 
 const name = 'start';
-const summary = 'Start app via npm scripts (native — no Docker)';
+const summary = 'Start app via npm scripts (native); auto-starts DB containers if needed';
 
 function help() {
   return `Usage: ragsuite-test start [options]
 
 Runs scripts/native-start.sh (same as \`npm start\` in the install dir).
-Does not use Docker — no containers, no volume risk.
+
+App runs on the host. If Postgres/Redis are down, start may bring up
+data-only compose services (postgres + redis) using existing volumes —
+never \`down -v\`. Backend/frontend Docker containers are not started.
 
 Options:
   --repo-root <path>       Override active install
@@ -42,6 +45,8 @@ async function run(ctx) {
       error(err.message);
       return 1;
     }
+  } else {
+    info('[dry-run] would run scripts/native-start.sh');
   }
 
   return runScript(repoRoot, path.join('scripts', 'native-start.sh'), [], {

package/src/commands/stop.js

@@ -7,13 +7,15 @@ const { runScript } = require('../utils/spawn');
 const { error } = require('../utils/log');
 
 const name = 'stop';
-const summary = 'Stop native app processes (does not touch Docker volumes)';
+const summary = 'Stop native app + leftover Docker app containers (keeps DB volumes)';
 
 function help() {
   return `Usage: ragsuite-test stop [options]
 
-Runs scripts/native-stop.sh (same as \`npm run stop\` in the install dir).
-Stops host processes only — never runs docker compose down.
+Runs scripts/native-stop.sh:
+  • Stops host API / Expo / chroma PIDs
+  • Stops leftover Docker backend/frontend/worker if present
+  • Leaves postgres/redis running (and never uses down -v)
 
 Options:
   --repo-root <path>       Override active install

package/src/utils/port.js

@@ -35,7 +35,17 @@ async function assertApiPortFree(env = process.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.`,
+      [
+        `API port ${port} is already in use.`,
+        'This CLI will not kill foreign processes.',
+        '',
+        'If a previous RAGSuite install is running:',
+        '  ragsuite-test stop',
+        '  # frees native PIDs + leftover Docker app containers (keeps DB volumes)',
+        '',
+        'See what owns the port:',
+        `  lsof -nP -iTCP:${port} -sTCP:LISTEN`,
+      ].join('\n'),
     );
     err.code = 'PORT_IN_USE';
     throw err;
@@ -43,11 +53,10 @@ async function assertApiPortFree(env = process.env) {
   return port;
 }
 
+/** @deprecated Prefer start-time API checks; init must not require free DB ports. */
 const DEFAULT_INSTALL_PORTS = [
   { port: 9090, label: 'API' },
-  { port: 9091, label: 'Web UI' },
-  { port: 5436, label: 'Postgres' },
-  { port: 6382, label: 'Redis' },
+  { port: 9191, label: 'Expo web' },
 ];
 
 async function assertPortsFree(ports = DEFAULT_INSTALL_PORTS) {
@@ -63,17 +72,8 @@ async function assertPortsFree(ports = DEFAULT_INSTALL_PORTS) {
     const err = new Error(
       [
         `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',
-        '  # or: npm run stop',
-        '',
-        'See what owns the ports (macOS/Linux):',
-        '  lsof -nP -iTCP:9090 -sTCP:LISTEN',
-        '  lsof -nP -iTCP:9191 -sTCP:LISTEN',
-        '  lsof -nP -iTCP:5436 -sTCP:LISTEN',
-        '  lsof -nP -iTCP:6382 -sTCP:LISTEN',
+        'Run: ragsuite-test stop',
+        'Then retry. Postgres/Redis being up is expected for native mode.',
       ].join('\n'),
     );
     err.code = 'PORT_IN_USE';