@nitsan-ai/ragsuite-test 0.1.3 → 0.1.4

package/README.md

@@ -1,103 +1,69 @@
 # RAGSuite test CLI (`ragsuite-test`)
 
-> **TESTING PACKAGE** — temporary name before the final `ragsuite` CLI.
-
-Two ways to run. Pick one:
-
-| | **A) Git source** | **B) Docker images only** |
-|--|-------------------|---------------------------|
-| Command | `ragsuite-test init` | `ragsuite-test init --from-images` |
-| On disk | Full monorepo clone | Tiny compose bundle only |
-| App code visible? | Yes | **No** (runs in containers) |
-| Needs | git + Node; Docker *or* native Postgres/Redis | Node + **Docker** |
-| Best for | Dev, debugging, native mode, reading code | Testers / “just run the app” |
-| Pros | Native mode; full scripts; offline rebuild from source | No source leak; faster to start; smaller disk |
-| Cons | Source on disk; larger checkout | Needs published GHCR images; Docker required; no native mode |
-
----
-
-## A) Git source (clone)
+npm-style install: **init once**, then **start / update / stop** — no `--repo-root` every time.
 
 ```bash
 npm install -g @nitsan-ai/ragsuite-test
+
+# First time only
 ragsuite-test init
-# clones https://github.com/nitsan-ai/RAGSUITE.git → ~/ragsuite-test
-# auto: docker if daemon up, else native
+# or without app source on disk:
+# ragsuite-test init --from-images
 
-ragsuite-test start --repo-root ~/ragsuite-test --detach   # docker
-# or after init --mode native:
-# ragsuite-test start --repo-root ~/ragsuite-test
+ragsuite-test start
+# API http://localhost:9090  ·  Web http://localhost:9091
 
-# API http://localhost:9090
-# Web http://localhost:9091 (docker) or :9191 (native)
-ragsuite-test stop --repo-root ~/ragsuite-test
+ragsuite-test stop
 ```
 
-### Native (no Docker) — git install only
-
-Needs Postgres `:5436` (`ragsuite_v3`) and Redis `:6382`:
-
-```bash
-ragsuite-test init --mode native
-ragsuite-test start --repo-root ~/ragsuite-test
-```
+Active install is remembered in `~/.ragsuite-test/config.json` (default app dir: `~/ragsuite-test`).
 
 ---
 
-## B) Docker images (no source on disk)
-
-**Maintainer (once):** publish images — Actions → **Publish images (GHCR)**  
-(packages: `ghcr.io/nitsan-ai/ragsuite-backend`, `…/ragsuite-frontend`)
-
-**User:**
+## Upgrade (keeps data & `.env`)
 
 ```bash
-npm install -g @nitsan-ai/ragsuite-test
-ragsuite-test init --from-images
-ragsuite-test start --repo-root ~/ragsuite-test --detach
-# pulls images — does NOT clone app source
-ragsuite-test stop --repo-root ~/ragsuite-test
+npm install -g @nitsan-ai/ragsuite-test@latest
+ragsuite-test update
+ragsuite-test start
 ```
 
-Optional pin:
+| Install type | What `update` does |
+|--------------|--------------------|
+| Git (`init`) | `git pull` in `~/ragsuite-test` |
+| Images (`init --from-images`) | `docker compose pull` + recreate containers |
 
-```bash
-# in ~/ragsuite-test/.env
-IMAGE_TAG=1.0.0
-IMAGE_REGISTRY=ghcr.io/nitsan-ai
-```
+**Never** run `docker compose down -v` or `init --force` unless you mean to wipe data.
 
-If images are private on GHCR, make packages public or `docker login ghcr.io`.
+If you already installed and run `init` again → it says **Already installed** and exits OK (does not wipe).
 
 ---
 
-## Prerequisites
+## Which first-time install?
 
-| Need | Git install | Images install |
-|------|-------------|----------------|
-| Node 18+ | Yes | Yes |
-| git | Yes | No |
-| Docker | Optional | **Required** |
-| Postgres/Redis on host | Only for `--mode native` | No (in compose) |
+| | **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” |
 
-SMTP/LLM: no init prompts. Real SMTP only in local `.env` (gitignored).
+---
 
-## Ports
+## Commands
 
-| Service | Port |
-|---------|------|
-| API | 9090 |
-| Web (Docker/images) | 9091 |
-| Web (native Expo) | 9191 |
-| Postgres | 5436 |
-| Redis | 6382 |
+| 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 |
 
-## Publish CLI
+## Ports
 
-See [PUBLISH.md](./PUBLISH.md). Version bump then Actions → **CLI publish**.
+API **9090** · Web **9091** (Docker/images) · Web **9191** (native) · Postgres **5436** · Redis **6382**
 
-## Tests
+## Publish (maintainers)
 
-```bash
-cd cli && npm test && npm run prepublish:check
-```
+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.3",
+  "version": "0.1.4",
   "private": false,
-  "description": "RAGSuite testing CLI — init (git source) or init --from-images (pull-only, no source).",
+  "description": "RAGSuite testing CLI — init once, then start/update/stop (npm-style).",
   "main": "src/index.js",
   "bin": {
     "ragsuite-test": "./bin/ragsuite-test.js"

package/src/commands/init.js

@@ -1,12 +1,15 @@
 'use strict';
 
 const path = require('path');
-const { writeConfig, CONFIG_DIR } = require('../utils/config');
+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,
@@ -25,10 +28,10 @@ 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 = 'Install: git clone (source) or pull-only Docker images';
+const summary = 'First-time install (git or images). Safe if already installed.';
 
 function printSuccess(repoRoot, mode, source) {
   info('');
@@ -36,50 +39,65 @@ function printSuccess(repoRoot, mode, source) {
   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 (source === 'images') {
-    info('  Web  http://localhost:9091  (images / Docker nginx)');
-  } else 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:');
-  const detach = mode === 'docker' || source === 'images' ? ' --detach' : '';
-  info(`  1. ragsuite-test start --repo-root ${repoRoot}${detach}`);
-  info('  2. Open the Web URL above 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]
 
-Two install styles:
+First-time setup only (npm-style):
 
-  A) Source on disk (git) — default
-       ragsuite-test init
-       Clones ${DEFAULT_GIT_URL} → ~/ragsuite-test
-       Supports --mode docker|native
+  ragsuite-test init                 # git clone → ~/ragsuite-test
+  ragsuite-test init --from-images   # Docker images only (no app source)
 
-  B) No source (Docker images only)
-       ragsuite-test init --from-images
-       Copies a tiny compose bundle → ~/ragsuite-test
-       Pulls ghcr.io/nitsan-ai/ragsuite-backend|frontend (no git clone of app code)
+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            Pull-only images install (no monorepo source)
-  --from-git [url]         Clone this URL (default public repo)
-  --repo-root <path>       Configure an existing git checkout
-  --install-dir <path>     Target dir (default: ~/ragsuite-test)
-  --mode <docker|native>   Git install only (images install is always docker)
-  --force                  Overwrite non-empty install dir / existing .env
+  --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
-  --llm-api-key / --smtp-* Optional overrides
 `;
 }
 
@@ -113,7 +131,7 @@ async function run(ctx) {
   const g = ctx.globals;
 
   if (g.fromRelease) {
-    error('--from-release is not supported. Use init, --from-images, --from-git, or --repo-root.');
+    error('--from-release is not supported.');
     return 1;
   }
 
@@ -128,25 +146,55 @@ async function run(ctx) {
   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;
+    }
+  }
 
   if (!fromImages && fromGit === null && !repoRootFlag) {
     fromGit = '';
-    info(`Install style: git clone (source on disk)`);
-    info(`  ${DEFAULT_GIT_URL} → ${path.resolve(installDir)}`);
+    info(`First-time install (git): ${DEFAULT_GIT_URL}`);
+    info(`  → ${installDir}`);
   }
-
   if (fromImages) {
-    info('Install style: Docker images only (no app source on disk)');
-    info(`  Target: ${path.resolve(installDir)}`);
+    info(`First-time install (images, no source): → ${installDir}`);
   }
 
-  let mode;
-  if (fromImages) {
-    mode = 'docker';
-  } else {
-    mode = g.mode || resolvePreferredMode(null);
+  // 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;
   }
+
+  let mode = fromImages ? 'docker' : g.mode || resolvePreferredMode(null);
   info(`Run mode: ${mode}`);
 
   const needGit = !fromImages && fromGit !== null && fromGit !== undefined;
@@ -157,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);
@@ -176,23 +223,14 @@ async function run(ctx) {
 
   try {
     if (fromImages) {
-      const result = materializeImagesInstall({
-        installDir,
-        force: g.force,
-      });
+      const result = materializeImagesInstall({ installDir, force: g.force });
       repoRoot = result.repoRoot;
       source = 'images';
-      info(`Images bundle installed at ${repoRoot}`);
     } 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,
@@ -213,6 +251,7 @@ async function run(ctx) {
     repoRoot,
     installDir: repoRoot,
   });
+  setActiveInstall(repoRoot);
 
   try {
     writeInstallEnv(repoRoot, {
@@ -222,16 +261,18 @@ 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}`);
+  info(`Config: mode=${cfg.mode} source=${cfg.source}`);
   printSuccess(repoRoot, mode, source);
   return 0;
 }

package/src/commands/update.js

@@ -2,86 +2,119 @@
 
 const fs = require('fs');
 const path = require('path');
-const { resolveRepoRoot } = require('../utils/paths');
+const { resolveRepoRoot, isImagesInstall, looksLikeGitCheckout } = require('../utils/paths');
 const { readConfig } = require('../utils/config');
-const { captureCommand } = require('../utils/spawn');
-const { info, warn } = require('../utils/log');
+const { setActiveInstall } = require('../utils/global-config');
+const { captureCommand, runScript } = require('../utils/spawn');
+const { info, warn, error } = require('../utils/log');
 
 const name = 'update';
-const summary = 'Verify install path and print safe update steps';
+const summary = 'Update app in place (git pull or image pull) — keeps data & .env';
 
 function help() {
-  return `Usage: ragsuite-test update [options]
+  return `Usage: ragsuite-test update
 
-Verifies the install/repo path and prints safe update steps.
-Git installs: git fetch + pull guidance (no destructive reset).
+Upgrades the active install without wiping data:
+  • Git install  → git pull (keeps .env + Docker volumes)
+  • Images install → docker compose pull (keeps .env + volumes)
 
 Never runs docker compose down -v.
 
+Typical flow after a new release:
+  npm install -g @nitsan-ai/ragsuite-test@latest
+  ragsuite-test update
+  ragsuite-test start
+
 Options:
-  --repo-root <path>       Monorepo / install root
+  --repo-root <path>       Override active install
+  --dry-run                Print actions only
 `;
 }
 
 function run(ctx) {
-  const repoRoot = resolveRepoRoot({
-    cwd: ctx.cwd,
-    repoRootFlag: ctx.globals.repoRoot,
-    env: ctx.env,
-  });
+  let repoRoot;
+  try {
+    repoRoot = resolveRepoRoot({
+      cwd: ctx.cwd,
+      repoRootFlag: ctx.globals.repoRoot,
+      env: ctx.env,
+    });
+  } catch (err) {
+    error(err.message);
+    return 1;
+  }
 
+  setActiveInstall(repoRoot);
   const cfg = readConfig(repoRoot);
-  const source = (cfg && cfg.source) || 'checkout';
+  const source = (cfg && cfg.source) || (isImagesInstall(repoRoot) ? 'images' : 'git');
+  const images = source === 'images' || isImagesInstall(repoRoot);
 
-  info(`Install path OK: ${repoRoot}`);
+  info(`Updating install: ${repoRoot}`);
   info(`  source=${source}`);
+  info('  (.env and Docker volumes are kept — never wiped)');
   info('');
 
-  info('Safe update steps:');
-  info('  1. Stop the stack (ragsuite-test stop --repo-root …)');
-  info('  2. Update sources (git pull)');
-  info('  3. Docker: npm run rebuild or docker compose build');
-  info('  4. Native: re-run backend/scripts/setup.sh if Python deps changed');
-  info('  5. Start again (ragsuite-test start --repo-root …)');
-  info('  6. Run doctor after upgrades');
-  info('');
-  info('Never: docker compose down -v (destroys Postgres/Chroma data).');
-  info('');
-
-  const gitDir = path.join(repoRoot, '.git');
-  if (!fs.existsSync(gitDir)) {
-    warn('No .git directory — skip fetch/status. Re-init with --from-git if needed.');
+  if (ctx.globals.dryRun) {
+    info(`[dry-run] would update ${images ? 'images (compose pull)' : 'git (pull)'}`);
     return 0;
   }
 
-  const remote = captureCommand('git', ['remote', '-v'], { cwd: repoRoot, env: ctx.env });
-  if (remote.status !== 0 || !String(remote.stdout || '').trim()) {
-    warn('No git remote configured — skip fetch.');
-    return 0;
+  if (images) {
+    info('Pulling newer Docker images…');
+    const pull = captureCommand(
+      'docker',
+      ['compose', '-f', 'docker-compose.yml', 'pull'],
+      { cwd: repoRoot, env: ctx.env },
+    );
+    if (pull.status !== 0) {
+      error(`Image pull failed (exit ${pull.status}).`);
+      if (pull.stderr) error(String(pull.stderr).trimEnd());
+      error('Publish GHCR images / check IMAGE_TAG in .env, then retry.');
+      return 1;
+    }
+    info('Images pulled.');
+    info('');
+    info('Apply update:');
+    info('  ragsuite-test stop');
+    info('  ragsuite-test start');
+    info('(or: ragsuite-test start — compose recreate with new images)');
+    // Recreate containers with new images without wiping volumes
+    info('');
+    info('Recreating containers with new images (volumes preserved)…');
+    return runScript(repoRoot, path.join('scripts', 'docker-start-images.sh'), ['--detach'], {
+      dryRun: false,
+      env: { ...ctx.env, RAGSUITE_MODE: 'docker' },
+    });
   }
 
-  info('Git remotes:');
-  info(String(remote.stdout).trimEnd());
-  info('');
-  info('Running git fetch (non-destructive)…');
-  const fetch = captureCommand('git', ['fetch', '--all', '--prune'], {
+  // Git / checkout install
+  if (!looksLikeGitCheckout(repoRoot) && !fs.existsSync(path.join(repoRoot, '.git'))) {
+    error('This install has no .git directory. Re-run: ragsuite-test init --force');
+    return 1;
+  }
+
+  info('Fetching and pulling latest from git (non-destructive)…');
+  const pull = captureCommand('git', ['pull', '--ff-only'], {
     cwd: repoRoot,
     env: ctx.env,
   });
-  if (fetch.status !== 0) {
-    warn(
-      `git fetch failed (exit ${fetch.status}). Private remotes need credentials. Continuing with status only.`,
-    );
-    if (fetch.stderr) warn(String(fetch.stderr).trimEnd());
-  } else {
-    info('git fetch OK');
-  }
-
-  const status = captureCommand('git', ['status', '-sb'], { cwd: repoRoot, env: ctx.env });
-  if (status.stdout) {
-    info('');
-    info(String(status.stdout).trimEnd());
+  if (pull.status !== 0) {
+    warn(`git pull --ff-only failed (exit ${pull.status}). Trying fetch + 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 });
+    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.');
+  info('');
+  info('Restart to apply:');
+  info('  ragsuite-test stop');
+  info('  ragsuite-test start');
+  info('');
+  info('Never: docker compose down -v  (would delete Postgres/Chroma data)');
   return 0;
 }
 

package/src/index.js

@@ -42,8 +42,9 @@ function globalHelp() {
     '  --force                 init: overwrite non-empty install dir / .env',
     '  --yes, -y               Non-interactive (same defaults as plain init)',
     '  --mode <docker|native>  Override config (Docker optional)',
-    '  --dry-run               Print actions without running (start/stop/doctor/logs)',
+    '  --dry-run               Print actions without running (start/stop/doctor/logs/update)',
     '',
+    'Active install: ~/.ragsuite-test/config.json (set by init; used by start/update/stop)',
     'Env: RAGSUITE_REPO_ROOT or RAGSUITE_INSTALL_DIR',
     '     RAGSUITE_TEST_LLM_API_KEY, RAGSUITE_TEST_SMTP_* , RAGSUITE_TEST_EMAIL_FROM',
     '',

package/src/utils/distribution.js

@@ -25,10 +25,10 @@ function resolveComposeBundle() {
 
 function installHint() {
   return [
-    'Choose an install style:',
-    '  Source on disk:  ragsuite-test init',
-    '  No source:       ragsuite-test init --from-images',
-    'Then:              ragsuite-test start --repo-root ~/ragsuite-test --detach',
+    'Day-to-day:',
+    '  ragsuite-test start',
+    '  ragsuite-test update',
+    '  ragsuite-test stop',
   ].join('\n');
 }
 

package/src/utils/git-install.js

@@ -1,18 +1,17 @@
 'use strict';
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { looksLikeFullBundleRoot, looksLikeRepoRoot } = require('./paths');
+const {
+  defaultInstallDir,
+  looksLikeFullBundleRoot,
+  looksLikeRepoRoot,
+} = require('./paths');
 
 /** Default public monorepo (when the GitHub repo is public). */
 const DEFAULT_GIT_URL = 'https://github.com/nitsan-ai/RAGSUITE.git';
 
-function defaultInstallDir() {
-  return path.join(os.homedir(), 'ragsuite-test');
-}
-
 function requireGit() {
   const which = spawnSync('which', ['git'], { encoding: 'utf8' });
   if (which.status !== 0) {
@@ -49,7 +48,13 @@ function cloneGitToInstallDir(gitUrl, options = {}) {
   if (!isDirEmptyOrMissing(target)) {
     if (!force) {
       const err = new Error(
-        `Install directory is not empty: ${target}. Pass --force to remove and re-clone, or choose another --install-dir.`,
+        [
+          `Install directory is not empty: ${target}`,
+          '  If already installed:  ragsuite-test start',
+          '  To upgrade in place:   ragsuite-test update',
+          '  To wipe & reinstall:   ragsuite-test init --force',
+          '  Or use another path:   ragsuite-test init --install-dir <path>',
+        ].join('\n'),
       );
       err.code = 'INSTALL_DIR_NONEMPTY';
       throw err;

package/src/utils/global-config.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/** User-level CLI state (not inside the app install). Like other npm CLIs. */
+function globalConfigDir() {
+  return path.join(os.homedir(), '.ragsuite-test');
+}
+
+function globalConfigPath() {
+  return path.join(globalConfigDir(), 'config.json');
+}
+
+function readGlobalConfig() {
+  const file = globalConfigPath();
+  if (!fs.existsSync(file)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    return {
+      installDir: raw.installDir ? path.resolve(String(raw.installDir)) : null,
+      updatedAt: raw.updatedAt || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeGlobalConfig(partial = {}) {
+  const dir = globalConfigDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const existing = readGlobalConfig() || {};
+  const next = {
+    ...existing,
+    ...partial,
+    updatedAt: new Date().toISOString(),
+  };
+  if (next.installDir) next.installDir = path.resolve(String(next.installDir));
+  fs.writeFileSync(globalConfigPath(), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+function setActiveInstall(installDir) {
+  return writeGlobalConfig({ installDir: path.resolve(installDir) });
+}
+
+function getActiveInstall() {
+  const g = readGlobalConfig();
+  return g && g.installDir ? g.installDir : null;
+}
+
+module.exports = {
+  globalConfigDir,
+  globalConfigPath,
+  readGlobalConfig,
+  writeGlobalConfig,
+  setActiveInstall,
+  getActiveInstall,
+};

package/src/utils/images-install.js

@@ -38,7 +38,13 @@ function materializeImagesInstall(options = {}) {
   if (!isDirEmptyOrMissing(target)) {
     if (!force) {
       const err = new Error(
-        `Install directory is not empty: ${target}. Pass --force to replace, or choose another --install-dir.`,
+        [
+          `Install directory is not empty: ${target}`,
+          '  If already installed:  ragsuite-test start',
+          '  To upgrade in place:   ragsuite-test update',
+          '  To wipe & reinstall:   ragsuite-test init --from-images --force',
+          '  Or use another path:   ragsuite-test init --from-images --install-dir <path>',
+        ].join('\n'),
       );
       err.code = 'INSTALL_DIR_NONEMPTY';
       throw err;

package/src/utils/paths.js

@@ -1,8 +1,15 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { readConfig, CONFIG_DIR } = require('./config');
+const { getActiveInstall, setActiveInstall } = require('./global-config');
+
+/** Default app install dir (npm-CLI style home install). */
+function defaultInstallDir() {
+  return path.join(os.homedir(), 'ragsuite-test');
+}
 
 function looksLikeGitCheckout(dir) {
   const start = path.join(dir, 'scripts', 'docker-start.sh');
@@ -23,7 +30,6 @@ function looksLikeImagesInstall(dir) {
       /* fall through */
     }
   }
-  // Before config is written, or force-detect by scripts present without docker-start.sh
   return !fs.existsSync(path.join(dir, 'scripts', 'docker-start.sh'));
 }
 
@@ -33,36 +39,32 @@ function looksLikeRepoRoot(dir) {
 
 function looksLikeFullBundleRoot(dir) {
   if (!looksLikeGitCheckout(dir)) return false;
-  const compose = path.join(dir, 'docker-compose.yml');
-  return fs.existsSync(compose);
+  return fs.existsSync(path.join(dir, 'docker-compose.yml'));
 }
 
 function walkUpForRepoRoot(startDir) {
   let current = path.resolve(startDir);
   for (;;) {
-    if (looksLikeRepoRoot(current)) {
-      return current;
-    }
+    if (looksLikeRepoRoot(current)) return current;
     const parent = path.dirname(current);
-    if (parent === current) {
-      return null;
-    }
+    if (parent === current) return null;
     current = parent;
   }
 }
 
 function envRepoRoot(env = process.env) {
-  const candidates = [env.RAGSUITE_REPO_ROOT, env.RAGSUITE_INSTALL_DIR];
-  for (const raw of candidates) {
+  for (const raw of [env.RAGSUITE_REPO_ROOT, env.RAGSUITE_INSTALL_DIR]) {
     if (!raw || !String(raw).trim()) continue;
     const root = path.resolve(String(raw).trim());
-    if (looksLikeRepoRoot(root)) {
-      return root;
-    }
+    if (looksLikeRepoRoot(root)) return root;
   }
   return null;
 }
 
+/**
+ * Resolve install root (npm-CLI style):
+ * --repo-root → env → cwd walk-up → ~/.ragsuite-test active install → ~/ragsuite-test
+ */
 function resolveRepoRoot({
   cwd = process.cwd(),
   repoRootFlag,
@@ -73,16 +75,18 @@ function resolveRepoRoot({
     const root = path.resolve(repoRootFlag);
     if (!looksLikeRepoRoot(root)) {
       const err = new Error(
-        `Not a RAGSuite install root: ${root} (need git checkout or images install)`,
+        `Not a RAGSuite install: ${root}. Run: ragsuite-test init`,
       );
       err.code = 'NOT_REPO_ROOT';
       throw err;
     }
+    setActiveInstall(root);
     return root;
   }
 
   const fromEnv = envRepoRoot(env);
   if (fromEnv) {
+    setActiveInstall(fromEnv);
     return fromEnv;
   }
 
@@ -94,21 +98,41 @@ function resolveRepoRoot({
         for (const key of ['repoRoot', 'installDir']) {
           const candidate = cfg[key];
           if (candidate && looksLikeRepoRoot(candidate)) {
-            return path.resolve(candidate);
+            const resolved = path.resolve(candidate);
+            setActiveInstall(resolved);
+            return resolved;
           }
         }
       }
+      setActiveInstall(walked);
       return walked;
     }
   }
 
   const walked = walkUpForRepoRoot(cwd);
   if (walked) {
+    setActiveInstall(walked);
     return walked;
   }
 
+  const active = getActiveInstall();
+  if (active && looksLikeRepoRoot(active)) {
+    return active;
+  }
+
+  const fallback = defaultInstallDir();
+  if (looksLikeRepoRoot(fallback)) {
+    setActiveInstall(fallback);
+    return fallback;
+  }
+
   const err = new Error(
-    'Could not find RAGSuite install. Run: ragsuite-test init   OR   ragsuite-test init --from-images',
+    [
+      'No RAGSuite install found.',
+      '  First time:  ragsuite-test init',
+      '  Or images:   ragsuite-test init --from-images',
+      '  Then:        ragsuite-test start',
+    ].join('\n'),
   );
   err.code = 'NOT_REPO_ROOT';
   throw err;
@@ -134,7 +158,13 @@ function isImagesInstall(repoRoot) {
   return looksLikeImagesInstall(repoRoot) && !looksLikeGitCheckout(repoRoot);
 }
 
+function isDirEmptyOrMissing(dir) {
+  if (!fs.existsSync(dir)) return true;
+  return fs.readdirSync(dir).filter((n) => n !== '.DS_Store').length === 0;
+}
+
 module.exports = {
+  defaultInstallDir,
   looksLikeRepoRoot,
   looksLikeGitCheckout,
   looksLikeImagesInstall,
@@ -146,4 +176,5 @@ module.exports = {
   ensureRagsuiteDir,
   nativeLogDir,
   isImagesInstall,
+  isDirEmptyOrMissing,
 };

package/src/utils/port.js

@@ -66,7 +66,7 @@ async function assertPortsFree(ports = DEFAULT_INSTALL_PORTS) {
         'Free them, then retry. This CLI will not kill foreign processes.',
         '',
         'If a previous RAGSuite install is running:',
-        '  ragsuite-test stop --repo-root ~/ragsuite-test',
+        '  ragsuite-test stop',
         '  # or from a monorepo checkout: cd <checkout> && npm run down',
         '',
         'See what owns the ports (macOS/Linux):',