@nitsan-ai/ragsuite-test 0.1.5 → 0.1.7

package/README.md

@@ -1,48 +1,42 @@
 # RAGSuite test CLI (`ragsuite-test`)
 
-npm-style deploy: **init once**, then **start / update / stop** via host **npm scripts** — **no Docker**.
+End-user deploy: install the CLI **globally**, init once, then start/update/stop.
 
 ```bash
-npm install -g @nitsan-ai/ragsuite-test
-
-# First time only
-ragsuite-test init
-# clones → ~/ragsuite-test
-
-# Needs Postgres :5436 (db ragsuite_v3) and Redis :6382 on the host
-ragsuite-test start
-# API http://localhost:9090  ·  Web http://localhost:9191
+# Always use -g (puts ragsuite-test on your PATH)
+npm install -g @nitsan-ai/ragsuite-test@latest
 
+ragsuite-test init     # once → ~/ragsuite-test
+ragsuite-test start    # API :9090 · Web :9191
 ragsuite-test stop
 ```
 
-Same under the hood as:
+### Upgrade later (CLI + app, keeps data)
 
 ```bash
-cd ~/ragsuite-test
-npm start          # scripts/native-start.sh
-npm run stop       # scripts/native-stop.sh
+ragsuite-test update
+ragsuite-test start
 ```
 
-Active install is remembered in `~/.ragsuite-test/config.json`.
+`update` runs `npm install -g @nitsan-ai/ragsuite-test@latest` then `git pull` in the install dir. It never runs `docker compose down -v`.
 
----
+> If you run `npm i @nitsan-ai/ragsuite-test` **without** `-g`, the `ragsuite-test` command will be missing. Fix: `npm install -g @nitsan-ai/ragsuite-test@latest`.
 
-## Upgrade (keeps data & `.env`)
+Same as:
 
 ```bash
-npm install -g @nitsan-ai/ragsuite-test@latest
-ragsuite-test update    # git pull only
-ragsuite-test start
+cd ~/ragsuite-test
+npm start          # scripts/native-start.sh
+npm run stop       # scripts/native-stop.sh
 ```
 
-**Never** run `docker compose down -v` or `init --force` unless you mean to wipe data.
+Active install: `~/.ragsuite-test/config.json`.
 
-If you already installed and run `init` again → **Already installed** (exit OK).
+**Data safety:** `start` may run `docker compose up -d postgres redis` only (existing volumes). App processes run on the host.
 
 ---
 
-## Prerequisites (host)
+## Prerequisites
 
 | Tool | Notes |
 |------|--------|
@@ -50,10 +44,8 @@ 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` |
-
-Docker is **not** required for this CLI.
+| Postgres + Redis | Host brew **or** data-only compose on :5436 / :6382 |
+| Docker (optional) | Auto-start/reuse existing postgres/redis volumes |
 
 ---
 
@@ -62,16 +54,16 @@ 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) |
-| `update` | `git pull` in place |
+| `start` | Native app (+ data services if needed) |
+| `stop` | Native PIDs + leftover app containers (DB kept) |
+| `update` | Upgrade CLI (`npm -g`) + app (`git pull`) |
 | `doctor` | Native prereq checks |
 | `logs` | Tail `.ragsuite/native/*.log` |
 | `version` | CLI version |
 
 ## Ports
 
-API **9090** · Web **9191** · Postgres **5436** · Redis **6382** · Chroma **8004** (started by native-start if needed)
+API **9090** · Web **9191** · Postgres **5436** · Redis **6382** · Chroma **8004**
 
 ## Publish (maintainers)
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@nitsan-ai/ragsuite-test",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
-  "description": "RAGSuite testing CLI — init once, then start/update/stop via native npm scripts (no Docker).",
+  "description": "RAGSuite testing CLI — npm -g install, then init/start/update/stop (keeps data).",
   "main": "src/index.js",
   "bin": {
-    "ragsuite-test": "./bin/ragsuite-test.js"
+    "ragsuite-test": "bin/ragsuite-test.js"
   },
   "files": [
     "bin/",

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/commands/update.js

@@ -5,25 +5,25 @@ const path = require('path');
 const { resolveRepoRoot, assertNativeDeploy, looksLikeGitCheckout } = require('../utils/paths');
 const { readConfig } = require('../utils/config');
 const { setActiveInstall } = require('../utils/global-config');
+const { upgradeGlobalCli } = require('../utils/cli-self-update');
 const { captureCommand } = require('../utils/spawn');
 const { info, warn, error } = require('../utils/log');
 
 const name = 'update';
-const summary = 'git pull in place — keeps .env and data (no Docker)';
+const summary = 'Upgrade CLI (npm -g) + app (git pull) — keeps .env and data';
 
 function help() {
   return `Usage: ragsuite-test update
 
-Upgrades the active git install without wiping data:
-  • git pull --ff-only in the install dir
-  • Keeps .env and any host Postgres/Redis/Chroma data
+Upgrades everything safely:
+  1. npm install -g @nitsan-ai/ragsuite-test@latest   (CLI on PATH)
+  2. git pull in the active install dir               (app source)
 
-Never runs docker compose (no volume risk).
+Keeps .env and database volumes. Never runs docker compose down -v.
 
-Typical flow after a new release:
+If you previously ran \`npm i @nitsan-ai/ragsuite-test\` without -g,
+the command disappears from PATH. Fix with:
   npm install -g @nitsan-ai/ragsuite-test@latest
-  ragsuite-test update
-  ragsuite-test start
 
 Options:
   --repo-root <path>       Override active install
@@ -31,30 +31,12 @@ Options:
 `;
 }
 
-function run(ctx) {
-  let repoRoot;
-  try {
-    repoRoot = resolveRepoRoot({
-      cwd: ctx.cwd,
-      repoRootFlag: ctx.globals.repoRoot,
-      env: ctx.env,
-    });
-    assertNativeDeploy(repoRoot);
-  } catch (err) {
-    error(err.message);
-    return 1;
-  }
-
-  setActiveInstall(repoRoot);
-  const cfg = readConfig(repoRoot);
-  const source = (cfg && cfg.source) || 'git';
-
-  info(`Updating install: ${repoRoot}`);
-  info(`  source=${source} mode=native`);
+function updateAppSource(repoRoot, env, dryRun) {
+  info(`Updating app install: ${repoRoot}`);
   info('  (.env and database data are kept)');
   info('');
 
-  if (ctx.globals.dryRun) {
+  if (dryRun) {
     info('[dry-run] would update via git pull --ff-only');
     return 0;
   }
@@ -67,24 +49,63 @@ function run(ctx) {
   info('Fetching and pulling latest from git (non-destructive)…');
   const pull = captureCommand('git', ['pull', '--ff-only'], {
     cwd: repoRoot,
-    env: ctx.env,
+    env,
   });
   if (pull.status !== 0) {
-    warn(`git pull --ff-only failed (exit ${pull.status}). Trying fetch + status…`);
+    warn(`git pull --ff-only failed (exit ${pull.status}).`);
     if (pull.stderr) warn(String(pull.stderr).trimEnd());
-    captureCommand('git', ['fetch', '--all', '--prune'], { cwd: repoRoot, env: ctx.env });
-    const st = captureCommand('git', ['status', '-sb'], { cwd: repoRoot, env: ctx.env });
+    captureCommand('git', ['fetch', '--all', '--prune'], { cwd: repoRoot, env });
+    const st = captureCommand('git', ['status', '-sb'], { cwd: repoRoot, env });
     if (st.stdout) info(String(st.stdout).trimEnd());
     error('Could not fast-forward. Fix local commits or stash, then: cd install && git pull');
     return 1;
   }
   if (pull.stdout) info(String(pull.stdout).trimEnd());
   info('git pull OK.');
+  return 0;
+}
+
+function run(ctx) {
+  info('=== Upgrade ===');
+  info('');
+
+  const cliResult = upgradeGlobalCli({
+    dryRun: ctx.globals.dryRun,
+    env: ctx.env,
+  });
+  if (cliResult.status !== 0) {
+    return cliResult.status;
+  }
+
+  info('');
+
+  let repoRoot = null;
+  try {
+    repoRoot = resolveRepoRoot({
+      cwd: ctx.cwd,
+      repoRootFlag: ctx.globals.repoRoot,
+      env: ctx.env,
+    });
+    assertNativeDeploy(repoRoot);
+  } catch (err) {
+    warn('No app install found yet — CLI was updated only.');
+    info('First time?  ragsuite-test init && ragsuite-test start');
+    return 0;
+  }
+
+  setActiveInstall(repoRoot);
+  const cfg = readConfig(repoRoot);
+  const source = (cfg && cfg.source) || 'git';
+  info(`App source=${source} mode=native`);
+  info('');
+
+  const appCode = updateAppSource(repoRoot, ctx.env, ctx.globals.dryRun);
+  if (appCode !== 0) return appCode;
+
   info('');
-  info('Restart to apply:');
+  info('Done. Apply with:');
   info('  ragsuite-test stop');
   info('  ragsuite-test start');
-  info('  # or: cd install && npm run stop && npm start');
   return 0;
 }
 

package/src/commands/version.js

@@ -2,6 +2,7 @@
 
 const path = require('path');
 const { info } = require('../utils/log');
+const { PACKAGE_NAME } = require('../utils/cli-self-update');
 
 const name = 'version';
 const summary = 'Print CLI package version';
@@ -9,7 +10,11 @@ const summary = 'Print CLI package version';
 function help() {
   return `Usage: ragsuite-test version
 
-Print @nitsan-ai/ragsuite-test version from package.json.
+Print ${PACKAGE_NAME} version from package.json.
+
+Upgrade:
+  npm install -g ${PACKAGE_NAME}@latest
+  # or: ragsuite-test update
 `;
 }
 
@@ -17,6 +22,7 @@ function run() {
   const pkgPath = path.join(__dirname, '..', '..', 'package.json');
   const pkg = require(pkgPath);
   info(`${pkg.name}@${pkg.version}`);
+  info(`Upgrade: npm install -g ${PACKAGE_NAME}@latest`);
   return 0;
 }
 

package/src/index.js

@@ -18,9 +18,16 @@ function globalHelp() {
   const lines = [
     'RAGSuite test CLI (experimental)',
     '',
+    'Install / upgrade (global — required for the ragsuite-test command):',
+    '  npm install -g @nitsan-ai/ragsuite-test@latest',
+    '',
     'Usage: ragsuite-test <command> [options]',
     '',
-    'Deploy path: git clone + native npm scripts (no Docker).',
+    'Typical flow:',
+    '  ragsuite-test init',
+    '  ragsuite-test start',
+    '  ragsuite-test update   # upgrades CLI + app (keeps data)',
+    '  ragsuite-test stop',
     '',
     'Commands:',
   ];

package/src/utils/cli-self-update.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const path = require('path');
+const { captureCommand } = require('./spawn');
+const { info, warn, error } = require('./log');
+
+const PACKAGE_NAME = '@nitsan-ai/ragsuite-test';
+
+function localCliVersion() {
+  try {
+    const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
+    return String(pkg.version || '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Upgrade the global CLI binary (npm install -g).
+ * Safe for end users; does not touch app data or Docker volumes.
+ * @returns {{ status: number, versionBefore: string, versionAfter: string|null }}
+ */
+function upgradeGlobalCli({ dryRun = false, env = process.env } = {}) {
+  const versionBefore = localCliVersion();
+  info(`Updating CLI package: npm install -g ${PACKAGE_NAME}@latest`);
+  info('  (must use -g so the ragsuite-test command stays on your PATH)');
+
+  if (dryRun) {
+    info(`[dry-run] would run: npm install -g ${PACKAGE_NAME}@latest`);
+    return { status: 0, versionBefore, versionAfter: versionBefore };
+  }
+
+  const result = captureCommand(
+    'npm',
+    ['install', '-g', `${PACKAGE_NAME}@latest`],
+    { env },
+  );
+  if (result.status !== 0) {
+    error(`CLI update failed (exit ${result.status}).`);
+    if (result.stderr) error(String(result.stderr).trimEnd());
+    if (result.stdout) warn(String(result.stdout).trimEnd());
+    error(`Fix: npm install -g ${PACKAGE_NAME}@latest`);
+    return { status: result.status || 1, versionBefore, versionAfter: null };
+  }
+  if (result.stdout) info(String(result.stdout).trimEnd());
+
+  // Re-read from the newly installed global package when possible
+  let versionAfter = null;
+  const which = captureCommand('npm', ['root', '-g'], { env });
+  if (which.status === 0 && which.stdout) {
+    const root = String(which.stdout).trim();
+    try {
+      const pkg = require(path.join(root, PACKAGE_NAME, 'package.json'));
+      versionAfter = String(pkg.version || '');
+    } catch {
+      versionAfter = null;
+    }
+  }
+
+  if (versionAfter) {
+    info(`CLI is now ${PACKAGE_NAME}@${versionAfter}`);
+  } else {
+    info(`CLI update finished. Check: ragsuite-test version`);
+  }
+  return { status: 0, versionBefore, versionAfter };
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  localCliVersion,
+  upgradeGlobalCli,
+};

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';