@nitsan-ai/ragsuite-test 0.1.2 → 0.1.4

package/README.md

@@ -1,86 +1,69 @@
 # RAGSuite test CLI (`ragsuite-test`)
 
-> **TESTING PACKAGE** — temporary. Final public CLI will be `ragsuite` later.
-
-**One-command public install** (GitHub repo must be public):
+npm-style install: **init once**, then **start / update / stop** — no `--repo-root` every time.
 
 ```bash
 npm install -g @nitsan-ai/ragsuite-test
-ragsuite-test init
-ragsuite-test start --repo-root ~/ragsuite-test --detach
-```
 
-That clones `https://github.com/nitsan-ai/RAGSUITE.git` into `~/ragsuite-test`, writes `.env` (no SMTP/LLM questions), and picks **Docker** if the daemon is up, otherwise **native**.
+# First time only
+ragsuite-test init
+# or without app source on disk:
+# ragsuite-test init --from-images
 
-- API: http://localhost:9090  
-- Web (Docker): http://localhost:9091  
-- Web (native): http://localhost:9191  
+ragsuite-test start
+# API http://localhost:9090  ·  Web http://localhost:9091
 
-```bash
-ragsuite-test stop --repo-root ~/ragsuite-test
+ragsuite-test stop
 ```
 
-## Prerequisites
+Active install is remembered in `~/.ragsuite-test/config.json` (default app dir: `~/ragsuite-test`).
 
-| Need | Required? | How |
-|------|-----------|-----|
-| Node.js 18+ | Yes | https://nodejs.org · `brew install node` |
-| git | Yes | `xcode-select --install` · `brew install git` |
-| Docker | No | Optional; without it init uses native (needs Postgres `:5436` + Redis `:6382`) |
+---
 
-Real SMTP belongs only in local `.env` (gitignored). Init never asks for it.
-
-## Advanced (optional)
+## Upgrade (keeps data & `.env`)
 
 ```bash
-# Force native / docker
-ragsuite-test init --mode native
-ragsuite-test init --mode docker
-
-# Custom install dir
-ragsuite-test init --install-dir ~/my-ragsuite
-
-# Existing checkout (CI / developers)
-ragsuite-test init --repo-root /path/to/RAGSUITE
+npm install -g @nitsan-ai/ragsuite-test@latest
+ragsuite-test update
+ragsuite-test start
 ```
 
-## Ports
+| Install type | What `update` does |
+|--------------|--------------------|
+| Git (`init`) | `git pull` in `~/ragsuite-test` |
+| Images (`init --from-images`) | `docker compose pull` + recreate containers |
 
-| Service | Port |
-|---------|------|
-| API | 9090 |
-| Web (Docker) | 9091 |
-| Web (native Expo) | 9191 |
-| Postgres | 5436 |
-| Redis | 6382 |
+**Never** run `docker compose down -v` or `init --force` unless you mean to wipe data.
 
-Busy ports: `ragsuite-test stop --repo-root ~/ragsuite-test` · `lsof -nP -iTCP:9090 -sTCP:LISTEN`
+If you already installed and run `init` again → it says **Already installed** and exits OK (does not wipe).
 
-## Commands
+---
 
-| Command | Behavior |
-|---------|----------|
-| `init` | Clone public repo → `.env` + config (default) |
-| `start` / `stop` | Docker or native scripts |
-| `doctor` | Health / prereq hints |
-| `logs` / `update` / `version` | As before |
+## Which first-time install?
 
-## Publish
+| | **Git source** `init` | **Images** `init --from-images` |
+|--|----------------------|----------------------------------|
+| App code on disk | Yes | No |
+| Docker | Optional (`--mode native`) | Required |
+| Best for | Dev / native | Testers / “just run it” |
 
-See [PUBLISH.md](./PUBLISH.md).
+---
 
-```bash
-cd cli && npm run prepublish:check
-# Only when approved:
-RAGSUITE_TEST_ALLOW_PUBLISH=1 npm publish --access public
-```
+## Commands
 
-## Windows
+| Command | Purpose |
+|---------|---------|
+| `init` | First-time install |
+| `start` | Start app (uses saved install path) |
+| `stop` | Stop app (volumes kept) |
+| `update` | Upgrade code/images in place |
+| `doctor` | Health / prereqs |
+| `version` | CLI version |
 
-Use WSL or Git Bash.
+## Ports
 
-## Tests
+API **9090** · Web **9091** (Docker/images) · Web **9191** (native) · Postgres **5436** · Redis **6382**
 
-```bash
-cd cli && npm test && npm run prepublish:check
-```
+## Publish (maintainers)
+
+See [PUBLISH.md](./PUBLISH.md). Also publish GHCR images before `--from-images` works for others.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nitsan-ai/ragsuite-test",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
-  "description": "RAGSuite testing CLI (ragsuite-test) — public install: npm i -g && ragsuite-test init (clones GitHub). Temporary name before public ragsuite release.",
+  "description": "RAGSuite testing CLI — init once, then start/update/stop (npm-style).",
   "main": "src/index.js",
   "bin": {
     "ragsuite-test": "./bin/ragsuite-test.js"
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "src/",
+    "templates/",
     "package.json",
     "README.md",
     "LICENSE"

package/src/commands/doctor.js

@@ -2,22 +2,22 @@
 
 const path = require('path');
 const { resolveMode } = require('../utils/config');
-const { resolveRepoRoot } = require('../utils/paths');
+const { resolveRepoRoot, isImagesInstall } = require('../utils/paths');
 const { runScript } = require('../utils/spawn');
 
 const name = 'doctor';
-const summary = 'Run scripts/doctor.sh prerequisite checks';
+const summary = 'Run doctor checks (git or images install)';
 
 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.
+Git install: scripts/doctor.sh
+Images install: scripts/docker-doctor-images.sh
 
 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
+  --mode <docker|native>   Git install gate
+  --repo-root <path>
+  --dry-run
 `;
 }
 
@@ -26,12 +26,16 @@ function run(ctx) {
     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'), [], {
+  const images = isImagesInstall(repoRoot);
+  const mode = images
+    ? 'docker'
+    : resolveMode({
+        flagMode: ctx.globals.mode,
+        repoRoot,
+        env: ctx.env,
+      });
+  const script = images ? 'docker-doctor-images.sh' : 'doctor.sh';
+  return runScript(repoRoot, path.join('scripts', script), [], {
     dryRun: ctx.globals.dryRun,
     env: { ...ctx.env, RAGSUITE_MODE: mode },
   });

package/src/commands/init.js

@@ -1,14 +1,22 @@
 'use strict';
 
 const path = require('path');
-const { writeConfig, CONFIG_DIR } = require('../utils/config');
-const { ensureRagsuiteDir, resolveRepoRoot } = require('../utils/paths');
+const { writeConfig, CONFIG_DIR, readConfig } = require('../utils/config');
+const {
+  ensureRagsuiteDir,
+  resolveRepoRoot,
+  isImagesInstall,
+  looksLikeRepoRoot,
+  isDirEmptyOrMissing,
+} = require('../utils/paths');
+const { setActiveInstall } = require('../utils/global-config');
 const { assertSupportedInstall, installHint } = require('../utils/distribution');
 const {
   DEFAULT_GIT_URL,
   defaultInstallDir,
   cloneGitToInstallDir,
 } = require('../utils/git-install');
+const { materializeImagesInstall } = require('../utils/images-install');
 const { detectOs } = require('../utils/os-detect');
 const {
   printPrereqs,
@@ -20,57 +28,76 @@ const {
   writeInstallEnv,
 } = require('../utils/env-file');
 const { assertPortsFree } = require('../utils/port');
-const { info, error } = require('../utils/log');
+const { info, warn, error } = require('../utils/log');
 
 const name = 'init';
-const summary = 'One-command install: clone public GitHub repo → .env + config';
+const summary = 'First-time install (git or images). Safe if already installed.';
 
-function printSuccess(repoRoot, mode) {
+function printSuccess(repoRoot, mode, source) {
   info('');
   info('=== Install complete ===');
   info(`  Install dir : ${repoRoot}`);
+  info(`  Source      : ${source}`);
   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)');
+  if (source === 'images' || mode === 'docker') {
+    info('  Web  http://localhost:9091');
   } else {
-    info('  Web  http://localhost:9091  (Docker nginx)');
+    info('  Web  http://localhost:9191');
   }
   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('Next (no --repo-root needed):');
+  info('  ragsuite-test start');
+  info('  ragsuite-test stop');
+  info('  ragsuite-test update   # later upgrades, keeps data');
   info('');
   info(installHint());
 }
 
+function printAlreadyInstalled(repoRoot) {
+  const cfg = readConfig(repoRoot);
+  setActiveInstall(repoRoot);
+  info('');
+  info('=== Already installed ===');
+  info(`  ${repoRoot}`);
+  if (cfg) info(`  source=${cfg.source} mode=${cfg.mode}`);
+  info('');
+  info('Use:');
+  info('  ragsuite-test start     # run the app');
+  info('  ragsuite-test update    # upgrade code/images (keeps .env + data)');
+  info('  ragsuite-test stop');
+  info('');
+  info('Do NOT run init --force unless you intend to wipe and reinstall.');
+}
+
+function isInitializedInstall(dir) {
+  return looksLikeRepoRoot(dir) && Boolean(readConfig(dir));
+}
+
 function help() {
   return `Usage: ragsuite-test init [options]
 
-Simple public install (default — no questions):
-  clones ${DEFAULT_GIT_URL}
-  into ~/ragsuite-test
-  picks docker mode if Docker is running, otherwise native
-  writes .env (JWT auto; SMTP/LLM from .env.example — no prompts)
-
-  ragsuite-test init
-  ragsuite-test start --repo-root ~/ragsuite-test --detach
-
-Advanced (optional):
-  --from-git [url]         Clone this URL instead of the default
-  --repo-root <path>       Use an existing checkout (no clone)
-  --install-dir <path>     Clone target (default: ~/ragsuite-test)
-  --mode <docker|native>   Force run mode
-  --force                  Overwrite non-empty install dir / existing .env
-  --yes, -y                Same defaults; for scripts/CI
-  --llm-api-key / --smtp-* Optional overrides (usually not needed)
+First-time setup only (npm-style):
+
+  ragsuite-test init                 # git clone → ~/ragsuite-test
+  ragsuite-test init --from-images   # Docker images only (no app source)
+
+If already installed, init exits OK and tells you to start/update.
+
+Day-to-day:
+  ragsuite-test start
+  ragsuite-test update
+  ragsuite-test stop
+
+Options:
+  --from-images            Images-only install
+  --from-git [url]         Clone URL (default public repo)
+  --repo-root <path>       Point at an existing checkout
+  --install-dir <path>     Default: ~/ragsuite-test
+  --mode <docker|native>   Git install only
+  --force                  Wipe install dir and reinstall (destructive)
+  --yes, -y                Non-interactive
 `;
 }
 
@@ -91,9 +118,10 @@ function resolveLlmOverride(g, env) {
   return null;
 }
 
-function countSources(fromGit, repoRootFlag) {
+function countSources(fromGit, fromImages, repoRootFlag) {
   let n = 0;
   if (fromGit !== null && fromGit !== undefined) n += 1;
+  if (fromImages) n += 1;
   if (repoRootFlag) n += 1;
   return n;
 }
@@ -103,12 +131,12 @@ async function run(ctx) {
   const g = ctx.globals;
 
   if (g.fromRelease) {
-    error('--from-release is not supported. Use default init, --from-git, or --repo-root.');
+    error('--from-release is not supported.');
     return 1;
   }
 
-  if (countSources(g.fromGit, g.repoRoot) > 1) {
-    error('Use only one of --from-git or --repo-root');
+  if (countSources(g.fromGit, g.fromImages, g.repoRoot) > 1) {
+    error('Use only one of --from-images, --from-git, or --repo-root');
     return 1;
   }
 
@@ -116,20 +144,60 @@ async function run(ctx) {
   info(`OS: ${osInfo.label} (${osInfo.platform})`);
 
   let fromGit = g.fromGit;
+  let fromImages = Boolean(g.fromImages);
   let repoRootFlag = g.repoRoot;
-  const installDir = g.installDir || defaultInstallDir();
+  const installDir = path.resolve(g.installDir || defaultInstallDir());
+
+  // Existing configured install → friendly no-op (like other npm CLIs)
+  if (!g.force) {
+    if (repoRootFlag && isInitializedInstall(path.resolve(repoRootFlag))) {
+      printAlreadyInstalled(path.resolve(repoRootFlag));
+      return 0;
+    }
+    if (!repoRootFlag && isInitializedInstall(installDir)) {
+      printAlreadyInstalled(installDir);
+      return 0;
+    }
+  }
 
-  // Default public path: no menus, no path prompts — clone GitHub → ~/ragsuite-test
-  if (fromGit === null && !repoRootFlag) {
+  if (!fromImages && fromGit === null && !repoRootFlag) {
     fromGit = '';
-    info(`Install: clone ${DEFAULT_GIT_URL}`);
-    info(`Target:  ${path.resolve(installDir)}`);
+    info(`First-time install (git): ${DEFAULT_GIT_URL}`);
+    info(`  → ${installDir}`);
+  }
+  if (fromImages) {
+    info(`First-time install (images, no source): → ${installDir}`);
   }
 
-  const mode = g.mode || resolvePreferredMode(null);
-  info(`Run mode: ${mode} (Docker optional — pass --mode docker|native to force)`);
+  // Checkout already on disk but never inited → wire config/.env, do not re-clone
+  if (
+    !g.force &&
+    !repoRootFlag &&
+    !fromImages &&
+    looksLikeRepoRoot(installDir) &&
+    !readConfig(installDir)
+  ) {
+    info(`Found existing source at ${installDir} — finishing setup (no re-clone).`);
+    repoRootFlag = installDir;
+    fromGit = null;
+  }
+
+  if (!g.force && !isDirEmptyOrMissing(installDir) && !looksLikeRepoRoot(installDir) && !repoRootFlag) {
+    error(
+      [
+        `Directory exists but is not a RAGSuite install: ${installDir}`,
+        '  Fix leftover files, or:',
+        '    ragsuite-test init --force          # wipe & reinstall (destructive)',
+        '    ragsuite-test init --install-dir ~/ragsuite-test-2',
+      ].join('\n'),
+    );
+    return 1;
+  }
 
-  const needGit = fromGit !== null && fromGit !== undefined;
+  let mode = fromImages ? 'docker' : g.mode || resolvePreferredMode(null);
+  info(`Run mode: ${mode}`);
+
+  const needGit = !fromImages && fromGit !== null && fromGit !== undefined;
   if (!printPrereqs(mode, { needGit })) {
     error('Fix prerequisites above and re-run init');
     return 1;
@@ -137,7 +205,6 @@ async function run(ctx) {
 
   const jwtSecret = generateJwtSecret();
   info(`JWT_SECRET_KEY will be auto-generated (…${jwtSecret.slice(-8)})`);
-  info('SMTP + LLM: from .env.example into .env (no prompts).');
 
   const llmKey = resolveLlmOverride(g, ctx.env);
   const smtp = optionalSmtpOverrides(g, ctx.env);
@@ -155,22 +222,22 @@ async function run(ctx) {
   let source = 'checkout';
 
   try {
-    if (fromGit !== null && fromGit !== undefined) {
+    if (fromImages) {
+      const result = materializeImagesInstall({ installDir, force: g.force });
+      repoRoot = result.repoRoot;
+      source = 'images';
+    } else if (fromGit !== null && fromGit !== undefined) {
       const url = fromGit === '' ? DEFAULT_GIT_URL : fromGit;
-      info(`Cloning ${url} → ${path.resolve(installDir)}`);
-      const result = cloneGitToInstallDir(url, {
-        installDir,
-        force: g.force,
-      });
+      const result = cloneGitToInstallDir(url, { installDir, force: g.force });
       repoRoot = result.repoRoot;
       source = 'git';
-      info(`Installed app at ${repoRoot}`);
     } else {
       repoRoot = resolveRepoRoot({
         cwd: ctx.cwd,
         repoRootFlag,
         env: ctx.env,
       });
+      if (isImagesInstall(repoRoot)) source = 'images';
     }
   } catch (err) {
     error(err.message || String(err));
@@ -184,6 +251,7 @@ async function run(ctx) {
     repoRoot,
     installDir: repoRoot,
   });
+  setActiveInstall(repoRoot);
 
   try {
     writeInstallEnv(repoRoot, {
@@ -193,17 +261,19 @@ async function run(ctx) {
       smtp,
     });
   } catch (err) {
-    if (err.code === 'ENV_EXISTS' || err.code === 'ENV_INCOMPLETE') {
+    if (err.code === 'ENV_EXISTS') {
+      warn('.env already present — keeping it (use --force only if you want to regenerate).');
+    } else if (err.code === 'ENV_INCOMPLETE') {
       error(err.message);
       return 1;
+    } else {
+      error(err.message || String(err));
+      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);
+  info(`Config: mode=${cfg.mode} source=${cfg.source}`);
+  printSuccess(repoRoot, mode, source);
   return 0;
 }
 

package/src/commands/start.js

@@ -2,25 +2,25 @@
 
 const path = require('path');
 const { resolveMode } = require('../utils/config');
-const { resolveRepoRoot } = require('../utils/paths');
+const { resolveRepoRoot, isImagesInstall } = 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';
+const summary = 'Start stack (git scripts or images pull-only)';
 
 function help() {
-  return `Usage: ragsuite-test start [options] [-- script-args...]
+  return `Usage: ragsuite-test start [options]
 
-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).
+Git install: scripts/docker-start.sh or native-start.sh
+Images install (--from-images): scripts/docker-start-images.sh (pull, no build)
 
 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 --)
+  --mode <docker|native>   Override (git install; images always docker)
+  --repo-root <path>       Install root
+  --dry-run                Print script path and exit 0
+  --detach, -d             Detached start
 `;
 }
 
@@ -29,14 +29,22 @@ async function run(ctx) {
     cwd: ctx.cwd,
     repoRootFlag: ctx.globals.repoRoot,
   });
-  const mode = resolveMode({
-    flagMode: ctx.globals.mode,
-    repoRoot,
-    env: ctx.env,
-  });
+  const images = isImagesInstall(repoRoot);
+  const mode = images
+    ? 'docker'
+    : resolveMode({
+        flagMode: ctx.globals.mode,
+        repoRoot,
+        env: ctx.env,
+      });
+
+  let scriptName;
+  if (images) {
+    scriptName = 'docker-start-images.sh';
+  } else {
+    scriptName = mode === 'native' ? 'native-start.sh' : 'docker-start.sh';
+  }
 
-  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) {
@@ -48,7 +56,7 @@ async function run(ctx) {
     }
   }
 
-  return runScript(repoRoot, rel, forward, {
+  return runScript(repoRoot, path.join('scripts', scriptName), forward, {
     dryRun: ctx.globals.dryRun,
     env: { ...ctx.env, RAGSUITE_MODE: mode },
   });

package/src/commands/stop.js

@@ -2,22 +2,23 @@
 
 const path = require('path');
 const { resolveMode } = require('../utils/config');
-const { resolveRepoRoot } = require('../utils/paths');
+const { resolveRepoRoot, isImagesInstall } = require('../utils/paths');
 const { runScript } = require('../utils/spawn');
 
 const name = 'stop';
-const summary = 'Stop stack via docker-stop.sh or native-stop.sh';
+const summary = 'Stop stack (git scripts or images pull-only)';
 
 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).
+Git install: docker-stop.sh / native-stop.sh
+Images install: docker-stop-images.sh
+Never wipes Docker volumes.
 
 Options:
-  --mode <docker|native>   Override config / RAGSUITE_MODE
-  --repo-root <path>       Monorepo root
-  --dry-run                Print the script path and exit 0
+  --mode <docker|native>   Override (git install)
+  --repo-root <path>       Install root
+  --dry-run                Print script path and exit 0
 `;
 }
 
@@ -26,12 +27,21 @@ function run(ctx) {
     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';
+  const images = isImagesInstall(repoRoot);
+  const mode = images
+    ? 'docker'
+    : resolveMode({
+        flagMode: ctx.globals.mode,
+        repoRoot,
+        env: ctx.env,
+      });
+
+  const scriptName = images
+    ? 'docker-stop-images.sh'
+    : 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 },