@nitsan-ai/ragsuite-test 0.1.6 → 0.1.7

package/README.md

@@ -1,51 +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 + Redis :6382 (auto-started via data-only compose if Docker is available)
-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
-# stops host app + leftover Docker app containers; keeps DB volumes
 ```
 
-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`.
 
-**Data safety:** `start` may run `docker compose up -d postgres redis` only (existing volumes). It never runs `down -v`. App code always runs natively.
+> 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 |
 |------|--------|
@@ -53,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 + 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 to run the API/UI (those are native).
+| Postgres + Redis | Host brew **or** data-only compose on :5436 / :6382 |
+| Docker (optional) | Auto-start/reuse existing postgres/redis volumes |
 
 ---
 
@@ -64,17 +53,17 @@ Docker is **not** required to run the API/UI (those are native).
 
 | Command | Purpose |
 |---------|---------|
-| `init` | First-time git install (no port checks) |
-| `start` | `scripts/native-start.sh` (+ data services if needed) |
+| `init` | First-time git install |
+| `start` | Native app (+ data services if needed) |
 | `stop` | Native PIDs + leftover app containers (DB kept) |
-| `update` | `git pull` in place |
+| `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.6",
+  "version": "0.1.7",
   "private": false,
-  "description": "RAGSuite testing CLI — init once, then start/update/stop via native npm scripts.",
+  "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/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,
+};