@nitsan-ai/ragsuite-test 0.1.0 → 0.1.1

package/README.md

@@ -2,84 +2,101 @@
 
 > **TESTING PACKAGE** — `@nitsan-ai/ragsuite-test` / `ragsuite-test` is temporary.
 > **Not** the final production `@nitsan-ai/ragsuite` / `ragsuite` CLI (later release).
-> Do **not** treat this as the long-term npm identity.
 
 Wraps monorepo Docker/native scripts. Does **not** reimplement compose.
 
-Requires **Node.js 18+**.
+Requires **Node.js 18+**. **Docker is optional.** Public deploy path: **`npm` → `init --from-git`**.
 
-**Run modes (both fully supported):**
+## Prerequisites
 
-| Situation | Mode | Command |
-|-----------|------|---------|
-| You have Docker | `docker` (default) | `ragsuite-test init … --mode docker` then `start` |
-| No Docker | `native` | Need Postgres **:5436** + Redis **:6382** on the host, then `ragsuite-test init … --mode native` then `start` |
+| Need | Why | How to get it |
+|------|-----|----------------|
+| Node.js 18+ | CLI + native frontend tooling | https://nodejs.org · `brew install node` · `sudo apt install nodejs` |
+| git | `--from-git` clone | `xcode-select --install` · `brew install git` · `sudo apt install git` |
+| **SMTP** | No prompts. Real values only in **local `.env`** (gitignored) | Gmail App Password → edit `.env` |
+| LLM API key | Default in `.env.example` / `.env` — no prompt | Override in `.env` or `--llm-api-key` |
+| **Either Docker** *or* **native data stores** | Run the stack | See modes below |
 
-Docker is **not** mandatory — choose native in the wizard or pass `--mode native`.
+### Mode A — Docker (optional)
 
-**Full tester steps:** [TEST_DISTRIBUTION.md](./TEST_DISTRIBUTION.md)
+- Docker Desktop / daemon + `docker compose`
+- https://www.docker.com/products/docker-desktop/
 
-## Quick start (wizard)
+### Mode B — Native (no Docker)
 
-```bash
-bash scripts/build-release-zip.sh
-cd cli && npm pack && npm install -g ./nitsan-ai-ragsuite-test-*.tgz
+- `python3`, `yarn` (or corepack)
+- Postgres on **localhost:5436**, database `ragsuite_v3`
+- Redis on **localhost:6382**
+
+## Install (public)
 
-# Interactive:
-ragsuite-test init
+```bash
+npm install -g @nitsan-ai/ragsuite-test
 
-# Or CI / noninteractive:
 ragsuite-test init --yes \
-  --from-zip ../dist/ragsuite-server-test-1.0.0.zip \
+  --from-git \
   --install-dir ~/ragsuite-test \
-  --mode docker \
-  --llm-api-key 'your-key'
+  --mode docker
 
 ragsuite-test start --repo-root ~/ragsuite-test --detach
 # API http://localhost:9090  ·  Web http://localhost:9091
 ```
 
-`init` auto-generates `JWT_SECRET_KEY`, writes `.ragsuite-test/config.json`, checks ports **9090 / 9091 / 5436 / 6382**, and warns if SMTP is skipped (invites/email may fail).
+SMTP + LLM: **no init prompts**. JWT is auto-generated. Real SMTP belongs only in local `.env` (never commit). If `.env.example` still has placeholders, init writes smoke SMTP so the app can start — edit `.env` for real mail.
+
+No Docker:
+
+```bash
+ragsuite-test init --yes --from-git --install-dir ~/ragsuite-test --mode native
+ragsuite-test start --repo-root ~/ragsuite-test
+# API :9090 · Expo web :9191
+```
+
+Existing checkout:
 
-## Install sources
+```bash
+ragsuite-test init --yes --repo-root /path/to/RAGSUITE --mode native
+```
 
-| Method | Flag |
-|--------|------|
-| Local ZIP | `--from-zip` (recommended for private testing) |
-| Existing checkout | `--repo-root` |
-| GitHub Release | `--from-release` — not implemented yet |
+Interactive: `ragsuite-test init`
 
-Making GitHub public is **not** required for ZIP installs.
+## Ports
 
-## Config
+| Service | Port |
+|---------|------|
+| API | 9090 |
+| Web (Docker) | 9091 |
+| Web (native Expo) | 9191 |
+| Postgres | 5436 |
+| Redis | 6382 |
 
-- CLI: `<install>/.ragsuite-test/config.json`
-- Native PID/logs: `<install>/.ragsuite/native/` (Phase 4 scripts)
+```bash
+ragsuite-test stop --repo-root ~/ragsuite-test
+lsof -nP -iTCP:9090 -sTCP:LISTEN
+docker ps
+```
 
 ## Commands
 
 | Command | Behavior |
 |---------|----------|
-| `init` | Installer wizard (ZIP/checkout → .env + config) |
+| `init` | git clone or checkout → `.env` + config |
 | `start` / `stop` | `scripts/docker-*.sh` or `native-*.sh` |
-| `doctor` | `scripts/doctor.sh` |
+| `doctor` | prereqs + `scripts/doctor.sh` |
 | `logs` / `update` / `version` | As before |
 
-## Publish (testing package only — Phase 12)
+## Publish
 
-See [PUBLISH.md](./PUBLISH.md) (full runbook) and [TEST_DISTRIBUTION.md](./TEST_DISTRIBUTION.md) (tester steps + go/no-go).
+See [PUBLISH.md](./PUBLISH.md) and [TEST_DISTRIBUTION.md](./TEST_DISTRIBUTION.md).
 
 ```bash
 cd cli && npm run prepublish:check
-# Only when someone says "publish now":
-RAGSUITE_TEST_ALLOW_PUBLISH=1 npm publish --access public
-# Or: GitHub Actions → CLI publish (workflow_dispatch, NPM_TOKEN)
-# Optional app ZIP: Actions → Release app ZIP
+RAGSUITE_TEST_ALLOW_PUBLISH=1 npm publish --access public   # only when approved
 ```
 
 ## Windows
 
-Use WSL or Git Bash (`bash` scripts).
+Use WSL or Git Bash.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitsan-ai/ragsuite-test",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "RAGSuite testing CLI (ragsuite-test) — install from ZIP or --repo-root checkout. Temporary npm identity before public ragsuite release.",
   "main": "src/index.js",

package/src/commands/init.js

@@ -1,20 +1,24 @@
 'use strict';
 
-const fs = require('fs');
 const path = require('path');
 const { writeConfig, CONFIG_DIR } = require('../utils/config');
 const { ensureRagsuiteDir, resolveRepoRoot, looksLikeRepoRoot } = require('../utils/paths');
 const { assertSupportedInstall, installHint } = require('../utils/distribution');
 const {
+  DEFAULT_GIT_URL,
   defaultInstallDir,
-  extractZipToInstallDir,
-} = require('../utils/zip-install');
+  cloneGitToInstallDir,
+} = require('../utils/git-install');
 const { detectOs } = require('../utils/os-detect');
-const { printPrereqs, checkPrereqs } = require('../utils/prereqs');
-const { ask, confirm, choose } = require('../utils/prompt');
+const {
+  printPrereqs,
+  resolvePreferredMode,
+  dockerDaemonRunning,
+  commandExists,
+} = require('../utils/prereqs');
+const { ask, choose } = require('../utils/prompt');
 const {
   generateJwtSecret,
-  generateCiLlmKey,
   isPlaceholderSecret,
   writeInstallEnv,
 } = require('../utils/env-file');
@@ -22,30 +26,7 @@ const { assertPortsFree } = require('../utils/port');
 const { info, warn, error } = require('../utils/log');
 
 const name = 'init';
-const summary = 'Installer wizard: ZIP or checkout → .env + config';
-
-function help() {
-  return `Usage: ragsuite-test init [options]
-
-Interactive installer (or --yes for CI) that:
-  - detects OS / prerequisites
-  - installs from ZIP or configures a checkout
-  - writes .ragsuite-test/config.json and .env (JWT auto-generated)
-  - checks ports 9090, 9091, 5436, 6382
-
-Install sources:
-  --from-zip <path>        Extract app ZIP into --install-dir
-  --repo-root <path>       Use an existing monorepo checkout
-  --from-release <tag>     Not implemented (download ZIP manually)
-
-Options:
-  --install-dir <path>     ZIP target (default: ~/ragsuite-test)
-  --mode <docker|native>   docker = Docker stack; native = no Docker (needs host Postgres/Redis)
-  --llm-api-key <key>      CUSTOM_LLM_INTERNAL_API_KEY (--yes)
-  --force                  Overwrite non-empty install dir / existing .env
-  --yes, -y                Non-interactive (requires --from-zip or --repo-root)
-`;
-}
+const summary = 'Installer wizard: git clone or checkout → .env + config';
 
 function printSuccess(repoRoot, mode) {
   info('');
@@ -61,7 +42,7 @@ function printSuccess(repoRoot, mode) {
     info('  Web  http://localhost:9091  (Docker nginx)');
   }
   info('');
-  info('  Mode reminder: docker needs Docker; native needs host Postgres/Redis (no Docker required).');
+  info('  Docker is optional: native mode needs host Postgres :5436 + Redis :6382.');
   info('  Each install directory is one deployment / one organization.');
   info('');
   info('Next steps:');
@@ -76,23 +57,57 @@ function printSuccess(repoRoot, mode) {
   info(installHint());
 }
 
-async function resolveLlmKey(g, env, interactive) {
-  if (g.llmApiKey && !isPlaceholderSecret(g.llmApiKey)) {
-    return g.llmApiKey;
-  }
+function help() {
+  return `Usage: ragsuite-test init [options]
+
+Interactive installer (or --yes for CI) that:
+  - detects OS / prerequisites (Docker is optional)
+  - clones the public monorepo or configures an existing checkout
+  - writes .ragsuite-test/config.json and .env
+  - JWT is auto-generated; SMTP + LLM defaults come from .env.example
+  - checks ports 9090, 9091, 5436, 6382
+
+Install sources (pick one):
+  --from-git [url]         Clone public monorepo (default: ${DEFAULT_GIT_URL})
+  --repo-root <path>       Use an existing monorepo checkout
+
+Run mode (Docker is NOT required):
+  --mode native            Default when Docker is unavailable — host Postgres/Redis
+  --mode docker            Full compose stack (needs Docker Desktop / daemon)
+
+Optional overrides (defaults come from .env.example — usually not needed):
+  --llm-api-key <key>      Override CUSTOM_LLM_INTERNAL_API_KEY
+  --smtp-host / --smtp-user / --smtp-password / --email-from
+
+Options:
+  --install-dir <path>     Target for --from-git (default: ~/ragsuite-test)
+  --force                  Overwrite non-empty install dir / existing .env
+  --yes, -y                Non-interactive (requires --from-git or --repo-root)
+`;
+}
+
+function optionalSmtpOverrides(g, env) {
+  const host = g.smtpHost || env.RAGSUITE_TEST_SMTP_HOST || null;
+  const user = g.smtpUser || env.RAGSUITE_TEST_SMTP_USER || null;
+  const password = g.smtpPassword || env.RAGSUITE_TEST_SMTP_PASSWORD || null;
+  const emailFrom = g.emailFrom || env.RAGSUITE_TEST_EMAIL_FROM || null;
+  if (!host && !user && !password && !emailFrom) return null;
+  return { host, user, password, emailFrom };
+}
+
+function resolveLlmOverride(g, env) {
+  if (g.llmApiKey && !isPlaceholderSecret(g.llmApiKey)) return g.llmApiKey;
   if (env.RAGSUITE_TEST_LLM_API_KEY && !isPlaceholderSecret(env.RAGSUITE_TEST_LLM_API_KEY)) {
     return env.RAGSUITE_TEST_LLM_API_KEY;
   }
-  if (g.yes || !interactive) {
-    const key = generateCiLlmKey();
-    warn(`Using generated smoke LLM key (${key.slice(0, 18)}…). Set a real CUSTOM_LLM_INTERNAL_API_KEY for production-like tests.`);
-    return key;
-  }
-  for (;;) {
-    const key = await ask('CUSTOM_LLM_INTERNAL_API_KEY', { yesMode: false });
-    if (!isPlaceholderSecret(key)) return key;
-    error('Key required and must not start with change-me');
-  }
+  return null; // keep .env.example default
+}
+
+function countSources(fromGit, repoRootFlag) {
+  let n = 0;
+  if (fromGit !== null && fromGit !== undefined) n += 1;
+  if (repoRootFlag) n += 1;
+  return n;
 }
 
 async function run(ctx) {
@@ -101,45 +116,49 @@ async function run(ctx) {
   const interactive = Boolean(process.stdin.isTTY) && !g.yes;
 
   if (g.fromRelease) {
-    error(
-      `--from-release is not implemented. Download a ZIP (private Release asset or local file), then: ragsuite-test init --from-zip <file.zip>`,
-    );
+    error('--from-release is not supported. Use --from-git or --repo-root.');
     return 1;
   }
 
-  if (g.fromZip && g.repoRoot) {
-    error('Use either --from-zip or --repo-root, not both');
+  if (countSources(g.fromGit, g.repoRoot) > 1) {
+    error('Use only one of --from-git or --repo-root');
     return 1;
   }
 
   const osInfo = detectOs();
   info(`OS: ${osInfo.label} (${osInfo.platform})`);
 
-  let mode = g.mode || 'docker';
-  let fromZip = g.fromZip;
+  let fromGit = g.fromGit;
   let repoRootFlag = g.repoRoot;
   let installDir = g.installDir || defaultInstallDir();
+  let mode = g.mode || null;
 
   if (g.yes) {
-    if (!fromZip && !repoRootFlag) {
-      error('--yes requires --from-zip <path> or --repo-root <path>');
+    if (fromGit === null && !repoRootFlag) {
+      error('--yes requires --from-git [url] or --repo-root <path>');
       return 1;
     }
-  } else if (interactive && !fromZip && !repoRootFlag) {
+  } else if (interactive && fromGit === null && !repoRootFlag) {
     const method = await choose(
       'Install method:',
       [
-        { id: 'zip', label: 'Local ZIP file (--from-zip)' },
-        { id: 'checkout', label: 'Existing checkout (--repo-root)' },
+        {
+          id: 'git',
+          label: 'Public git clone (--from-git) — recommended',
+        },
+        {
+          id: 'checkout',
+          label: 'Existing checkout (--repo-root)',
+        },
       ],
       { defaultIndex: 0 },
     );
-    if (method.id === 'zip') {
-      fromZip = await ask('Path to app ZIP', { yesMode: false });
-      if (!fromZip) {
-        error('ZIP path required');
-        return 1;
-      }
+    if (method.id === 'git') {
+      const url = await ask('Git repository URL', {
+        defaultValue: DEFAULT_GIT_URL,
+        yesMode: false,
+      });
+      fromGit = url || DEFAULT_GIT_URL;
       installDir = await ask('Install directory', {
         defaultValue: defaultInstallDir(),
         yesMode: false,
@@ -152,63 +171,73 @@ async function run(ctx) {
       }
     }
 
+    const dockerOk = commandExists('docker') && dockerDaemonRunning();
     const modeChoice = await choose(
-      'Run mode (Docker is optional):',
+      'Run mode (Docker is optional — native works without Docker):',
       [
-        { id: 'docker', label: 'Docker — if you have Docker Desktop / daemon (default)' },
-        { id: 'native', label: 'Native — no Docker; needs Postgres :5436 + Redis :6382 on this machine' },
+        {
+          id: 'native',
+          label: 'Native — no Docker; needs Postgres :5436 + Redis :6382 on this machine',
+        },
+        {
+          id: 'docker',
+          label: dockerOk
+            ? 'Docker — full compose stack (Docker Desktop / daemon)'
+            : 'Docker — not available on this machine (install Docker Desktop first)',
+        },
       ],
       { defaultIndex: 0 },
     );
     mode = modeChoice.id;
-  } else if (!fromZip && !repoRootFlag) {
-    error('Pass --from-zip / --repo-root, or run in a TTY for the interactive wizard');
+    if (mode === 'docker' && !dockerOk) {
+      warn('Docker is not available — switching to native mode.');
+      mode = 'native';
+    }
+  } else if (fromGit === null && !repoRootFlag) {
+    error('Pass --from-git / --repo-root, or run in a TTY for the interactive wizard');
     return 1;
   }
 
-  if (!printPrereqs(mode)) {
+  if (!mode) {
+    mode = resolvePreferredMode(g.mode);
+    info(`Run mode: ${mode} (Docker is optional; pass --mode docker|native to force)`);
+  }
+
+  const needGit = fromGit !== null && fromGit !== undefined;
+  if (!printPrereqs(mode, { needGit })) {
     error('Fix prerequisites above and re-run init');
     return 1;
   }
 
   const jwtSecret = generateJwtSecret();
   info(`JWT_SECRET_KEY will be auto-generated (…${jwtSecret.slice(-8)})`);
+  info('SMTP + LLM: using defaults from .env.example (optional flags can override).');
 
-  const llmKey = await resolveLlmKey(g, ctx.env, interactive);
+  const llmKey = resolveLlmOverride(g, ctx.env);
+  const smtp = optionalSmtpOverrides(g, ctx.env);
 
-  let smtpSkipped = true;
-  if (interactive && !g.yes) {
-    const configureSmtp = await confirm('Configure SMTP now? (needed for invites/email)', {
-      defaultYes: false,
-    });
-    smtpSkipped = !configureSmtp;
-    if (!smtpSkipped) {
-      info('After init, edit SMTP_* in .env (SMTP_HOST, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM).');
+  if (ctx.env.RAGSUITE_TEST_SKIP_PORT_CHECK !== '1') {
+    try {
+      await assertPortsFree();
+    } catch (err) {
+      error(err.message);
+      return 1;
     }
-  } else {
-    warn('SMTP skipped (--yes / noninteractive). Invites/email may fail until SMTP_* is set.');
-  }
-
-  // Port checks before mutating install (clearer UX)
-  try {
-    await assertPortsFree();
-  } catch (err) {
-    error(err.message);
-    return 1;
   }
 
   let repoRoot;
   let source = 'checkout';
 
   try {
-    if (fromZip) {
-      info(`Extracting ZIP → ${path.resolve(installDir)}`);
-      const result = extractZipToInstallDir(fromZip, {
+    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,
       });
       repoRoot = result.repoRoot;
-      source = 'zip';
+      source = 'git';
       info(`Installed app at ${repoRoot}`);
     } else {
       repoRoot = resolveRepoRoot({
@@ -235,10 +264,10 @@ async function run(ctx) {
       force: g.force,
       jwtSecret,
       llmApiKey: llmKey,
-      smtpSkipped,
+      smtp,
     });
   } catch (err) {
-    if (err.code === 'ENV_EXISTS') {
+    if (err.code === 'ENV_EXISTS' || err.code === 'ENV_INCOMPLETE') {
       error(err.message);
       return 1;
     }

package/src/commands/update.js

@@ -14,8 +14,7 @@ function help() {
   return `Usage: ragsuite-test update [options]
 
 Verifies the install/repo path and prints safe update steps.
-ZIP installs: download a newer ZIP and extract to a new dir (or backup + --force).
-Checkout installs: optional git fetch + status (no reset).
+Git installs: git fetch + pull guidance (no destructive reset).
 
 Never runs docker compose down -v.
 
@@ -32,38 +31,26 @@ function run(ctx) {
   });
 
   const cfg = readConfig(repoRoot);
-  const source = cfg && cfg.source === 'zip' ? 'zip' : 'checkout';
+  const source = (cfg && cfg.source) || 'checkout';
 
   info(`Install path OK: ${repoRoot}`);
   info(`  source=${source}`);
   info('');
 
-  if (source === 'zip') {
-    info('This install came from a ZIP. Safe update steps:');
-    info('  1. ragsuite-test stop --repo-root ' + repoRoot);
-    info('  2. Download a newer release ZIP (do not wipe Docker volumes)');
-    info('  3. Extract to a NEW directory, e.g. --install-dir ~/ragsuite-test-v2');
-    info('     or: backup this dir, then init --from-zip … --force');
-    info('  4. Copy your .env into the new install (do not commit secrets)');
-    info('  5. ragsuite-test doctor --repo-root <new-dir>');
-    info('  6. ragsuite-test start --repo-root <new-dir>');
-    info('');
-    info('Never: docker compose down -v (destroys Postgres/Chroma data).');
-    return 0;
-  }
-
-  info('Safe update steps (checkout install):');
+  info('Safe update steps:');
   info('  1. Stop the stack (ragsuite-test stop --repo-root …)');
-  info('  2. Update sources (git pull when you have remote access)');
+  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 (ZIP or packed tree).');
+    warn('No .git directory — skip fetch/status. Re-init with --from-git if needed.');
     return 0;
   }
 

package/src/index.js

@@ -31,16 +31,20 @@ function globalHelp() {
     'Global options:',
     '  --help, -h              Show help',
     '  --repo-root <path>      Monorepo / install root',
-    '  --from-zip <path>       init: extract app ZIP',
-    '  --install-dir <path>    init: ZIP target (default ~/ragsuite-test)',
-    '  --from-release <tag>    init: stub (not implemented)',
-    '  --llm-api-key <key>     init: CUSTOM_LLM_INTERNAL_API_KEY (--yes)',
+    '  --from-git [url]        init: clone public monorepo',
+    '  --install-dir <path>    init: target for --from-git (default ~/ragsuite-test)',
+    '  --llm-api-key <key>     init: optional override for CUSTOM_LLM_INTERNAL_API_KEY',
+    '  --smtp-host <host>      init: optional SMTP override',
+    '  --smtp-user <user>      init: optional SMTP override',
+    '  --smtp-password <pass>  init: optional SMTP override',
+    '  --email-from <email>    init: optional SMTP override',
     '  --force                 init: overwrite non-empty install dir / .env',
     '  --yes, -y               Non-interactive',
-    '  --mode <docker|native>  Override .ragsuite-test/config.json / RAGSUITE_MODE',
+    '  --mode <docker|native>  Override config (Docker optional)',
     '  --dry-run               Print actions without running (start/stop/doctor/logs)',
     '',
     'Env: RAGSUITE_REPO_ROOT or RAGSUITE_INSTALL_DIR',
+    '     RAGSUITE_TEST_LLM_API_KEY, RAGSUITE_TEST_SMTP_* , RAGSUITE_TEST_EMAIL_FROM',
     '',
     'Run ragsuite-test <command> --help for command details.',
   );
@@ -88,7 +92,7 @@ async function main(argv = process.argv) {
     const code = typeof result?.then === 'function' ? await result : result;
     return typeof code === 'number' ? code : 0;
   } catch (err) {
-    if (err && (err.code === 'NOT_REPO_ROOT' || err.code === 'USAGE' || err.code === 'ZIP_SLIP' || err.code === 'INSTALL_DIR_NONEMPTY' || err.code === 'ZIP_INVALID' || err.code === 'ZIP_MISSING' || err.code === 'ENV_EXISTS' || err.code === 'PORT_IN_USE' || err.code === 'LLM_KEY_INVALID')) {
+    if (err && (err.code === 'NOT_REPO_ROOT' || err.code === 'USAGE' || err.code === 'INSTALL_DIR_NONEMPTY' || err.code === 'ENV_EXISTS' || err.code === 'ENV_INCOMPLETE' || err.code === 'PORT_IN_USE' || err.code === 'LLM_KEY_INVALID' || err.code === 'SMTP_REQUIRED' || err.code === 'GIT_CLONE_FAILED' || err.code === 'MISSING_GIT')) {
       error(err.message);
       return 1;
     }