@cruxgarden/cli 0.0.9 → 0.0.10

package/README.md

@@ -57,7 +57,7 @@ Start the Nursery environment:
 crux nursery start
 ```
 
-The API will be available at `http://localhost:3000` with demo data loaded.
+The App will be available at `http://localhost:8080` and the API at `http://localhost:3000` with demo data loaded.
 
 View logs:
 
@@ -77,15 +77,26 @@ All commands are scoped under `crux nursery`:
 
 ### `crux nursery start`
 
-Start the Nursery environment (PostgreSQL, Redis, Migrations, and API with demo data).
+Start the Nursery environment (App, API, PostgreSQL, Redis with demo data).
 
 ```bash
 crux nursery start
+
+# With inline environment variables
+crux nursery start API_PORT=3001 APP_PORT=8081
+
+# With options and environment variables
+crux nursery start --api-only JWT_SECRET=my-secret
 ```
 
 **Options:**
 
 - `--db-only` - Start only database services (PostgreSQL and Redis)
+- `--api-only` - Start only API services (API, PostgreSQL, Redis) without the App
+
+**Environment Variables:**
+
+You can pass environment variables directly on the command line in `KEY=VALUE` format after the command and options. These override values from your `.env` file.
 
 ### `crux nursery stop`
 
@@ -103,6 +114,11 @@ Restart the Nursery environment.
 crux nursery restart
 ```
 
+**Options:**
+
+- `--db-only` - Restart only database services (PostgreSQL and Redis)
+- `--api-only` - Restart only API services (API, PostgreSQL, Redis) without the App
+
 ### `crux nursery status`
 
 Show the status of all Nursery services.
@@ -198,6 +214,14 @@ Connect to Nursery Redis with `redis-cli`.
 crux nursery redis connect
 ```
 
+### `crux nursery api start`
+
+Start only Nursery API services (API, PostgreSQL, Redis) without the App.
+
+```bash
+crux nursery api start
+```
+
 ### `crux nursery api connect`
 
 Open a shell in the Nursery API container.
@@ -217,31 +241,81 @@ The Nursery is a production-like demo environment that:
 
 **Services:**
 
+- **App**: `http://localhost:8080` - Crux Garden Web Application
 - **API**: `http://localhost:3000` - Crux Garden API (published image with demo data)
 - **PostgreSQL**: `localhost:5432` - Database
 - **Redis**: `localhost:6379` - Cache
 
 ## Environment Variables
 
-The Nursery environment has defaults for all environment variables, so a `.env` file is optional. However, you can override any variable by creating a `.env` file in your working directory:
+The Nursery environment has defaults for all environment variables, so configuration is optional. You can override variables in two ways:
+
+### 1. Using a `.env` file
+
+Create a `.env` file in your working directory:
 
 ```bash
-# JWT (has dev default, but you should use a different one)
+# Port Mappings
+API_PORT=3000          # External API port
+APP_PORT=8080          # External App port
+POSTGRES_PORT=5432     # External PostgreSQL port
+REDIS_PORT=6379        # External Redis port
+
+# PostgreSQL Configuration
+POSTGRES_DB=cruxgarden
+POSTGRES_USER=cruxgarden
+POSTGRES_PASSWORD=cruxgarden_nursery_password
+
+# Database & Cache URLs (override to use external services)
+DATABASE_URL=postgresql://cruxgarden:cruxgarden_nursery_password@postgres:5432/cruxgarden
+REDIS_URL=redis://redis:6379
+
+# Security (has dev default, but you should use a different one)
 JWT_SECRET=your-super-secret-jwt-key-min-32-chars
 
-# AWS (defaults to "dummy" values)
+# AWS Configuration (defaults to "dummy" values)
 AWS_ACCESS_KEY_ID=your-key
 AWS_SECRET_ACCESS_KEY=your-secret
 AWS_REGION=us-east-1
 AWS_SES_FROM_EMAIL=demo@example.com
 AWS_S3_ATTACHMENTS_BUCKET=crux-garden-attachments
 
-# Optional overrides
+# Optional Configuration
+NODE_ENV=production
 CORS_ORIGIN=*
 LOG_LEVEL=info
-PORT=3000
+HOSTNAME=0.0.0.0
+DB_POOL_MIN=2
+DB_POOL_MAX=10
+DB_POOL_IDLE_TIMEOUT=30000
+DB_POOL_ACQUIRE_TIMEOUT=60000
+RATE_LIMIT_TTL=60000
+RATE_LIMIT_MAX=100
 ```
 
+### 2. Using inline environment variables
+
+Pass environment variables directly on the command line:
+
+```bash
+# Override ports
+crux nursery start API_PORT=3001 APP_PORT=8081
+
+# Override database connection
+crux nursery start DATABASE_URL=postgresql://user:pass@external-host:5432/db
+
+# Multiple variables
+crux nursery start API_PORT=3001 JWT_SECRET=my-secret AWS_REGION=us-west-2
+
+# Works with all start commands
+crux nursery api start API_PORT=4000
+crux nursery db start POSTGRES_PORT=5433
+crux nursery restart API_PORT=3001
+crux nursery reset JWT_SECRET=new-secret
+```
+
+**Note:** Inline environment variables override values from your `.env` file. You can override `DATABASE_URL` and `REDIS_URL` to connect the API to external database/cache services instead of the bundled ones.
+
 ## Common Workflows
 
 ### Demo/Trial Setup
@@ -249,10 +323,11 @@ PORT=3000
 Use the Nursery environment for demos, trials, or showcasing features:
 
 ```bash
-# First time setup - pulls image and starts with demo data
+# First time setup - pulls images and starts with demo data
 crux nursery start
 
-# View the demo at http://localhost:3000
+# View the app at http://localhost:8080
+# Or access the API directly at http://localhost:3000
 
 # Stop (keeps data for next demo)
 crux nursery stop
@@ -304,6 +379,7 @@ If you get an error about ports being in use, stop any existing services:
 
 ```bash
 # Check what's using the ports
+lsof -i :8080  # Nursery App
 lsof -i :3000  # Nursery API
 lsof -i :5432  # Nursery PostgreSQL
 lsof -i :6379  # Nursery Redis

package/bin/crux.js

@@ -37,13 +37,14 @@ const nursery = program
   .description("Manage the Nursery environment (demo/trial environment)");
 
 nursery
-  .command("start")
-  .description("Start the Nursery environment (api, postgres, redis)")
+  .command("start [env...]")
+  .description("Start the Nursery environment (app, api, postgres, redis)")
   .option("--db-only", "Start only database services (postgres, redis)")
+  .option("--api-only", "Start only API services (api, postgres, redis) without app")
   .option("--no-banner", "Hide the startup banner")
-  .action((options) => {
+  .action((envVars, options) => {
     if (!options.noBanner) showBanner();
-    startNursery(options);
+    startNursery(options, envVars);
   });
 
 nursery
@@ -52,9 +53,11 @@ nursery
   .action(stopNursery);
 
 nursery
-  .command("restart")
+  .command("restart [env...]")
   .description("Restart the Nursery environment")
-  .action(restartNursery);
+  .option("--db-only", "Restart only database services (postgres, redis)")
+  .option("--api-only", "Restart only API services (api, postgres, redis) without app")
+  .action((envVars, options) => restartNursery(options, envVars));
 
 nursery
   .command("status")
@@ -85,7 +88,7 @@ nursery
   .action(updateNursery);
 
 nursery
-  .command("reset")
+  .command("reset [env...]")
   .description("Complete fresh reset (stop, clean, pull latest image, restart)")
   .action(resetNursery);
 
@@ -95,9 +98,9 @@ const nurseryDb = nursery
   .description("Manage Nursery database services");
 
 nurseryDb
-  .command("start")
+  .command("start [env...]")
   .description("Start only Nursery database services (postgres, redis)")
-  .action(() => startNursery({ dbOnly: true }));
+  .action((envVars) => startNursery({ dbOnly: true }, envVars));
 
 nurseryDb
   .command("stop")
@@ -122,6 +125,11 @@ nurseryRedis
 // Nursery API commands
 const nurseryApi = nursery.command("api").description("Manage Nursery API");
 
+nurseryApi
+  .command("start [env...]")
+  .description("Start only Nursery API services (api, postgres, redis) without app")
+  .action((envVars) => startNursery({ apiOnly: true }, envVars));
+
 nurseryApi
   .command("connect")
   .description("Open a shell in the Nursery API container")

package/docker/docker-compose.nursery.yml

@@ -12,15 +12,15 @@ services:
     image: postgres:16-alpine
     container_name: cruxgarden-nursery-postgres
     environment:
-      POSTGRES_DB: cruxgarden
-      POSTGRES_USER: cruxgarden
-      POSTGRES_PASSWORD: cruxgarden_nursery_password
+      POSTGRES_DB: ${POSTGRES_DB:-cruxgarden}
+      POSTGRES_USER: ${POSTGRES_USER:-cruxgarden}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-cruxgarden_nursery_password}
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     volumes:
       - postgres_data_nursery:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U cruxgarden"]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-cruxgarden}"]
       interval: 5s
       timeout: 5s
       retries: 5
@@ -31,7 +31,7 @@ services:
     container_name: cruxgarden-nursery-redis
     command: redis-server --appendonly yes
     ports:
-      - "6379:6379"
+      - "${REDIS_PORT:-6379}:6379"
     volumes:
       - redis_data_nursery:/data
     healthcheck:
@@ -48,8 +48,8 @@ services:
       postgres:
         condition: service_healthy
     environment:
-      NODE_ENV: production
-      DATABASE_URL: postgresql://cruxgarden:cruxgarden_nursery_password@postgres:5432/cruxgarden
+      NODE_ENV: ${NODE_ENV:-production}
+      DATABASE_URL: ${DATABASE_URL:-postgresql://cruxgarden:cruxgarden_nursery_password@postgres:5432/cruxgarden}
     command: ["npm", "run", "migrate:nursery"]
     restart: "no"
 
@@ -64,16 +64,16 @@ services:
       redis:
         condition: service_healthy
     ports:
-      - "${PORT:-3000}:3000"
+      - "${API_PORT:-3000}:3000"
     environment:
       # Application
-      NODE_ENV: production
+      NODE_ENV: ${NODE_ENV:-production}
       PORT: 3000
-      HOSTNAME: 0.0.0.0
+      HOSTNAME: ${HOSTNAME:-0.0.0.0}
 
-      # Bundled Services
-      DATABASE_URL: postgresql://cruxgarden:cruxgarden_nursery_password@postgres:5432/cruxgarden
-      REDIS_URL: redis://redis:6379
+      # Bundled Services (can override to use external services)
+      DATABASE_URL: ${DATABASE_URL:-postgresql://cruxgarden:cruxgarden_nursery_password@postgres:5432/cruxgarden}
+      REDIS_URL: ${REDIS_URL:-redis://redis:6379}
 
       # Security
       JWT_SECRET: ${JWT_SECRET:-your-super-secret-jwt-key-min-32-chars-for-development-only}
@@ -107,6 +107,17 @@ services:
       retries: 3
       start_period: 40s
 
+  # Crux Garden App - Web Application
+  app:
+    image: ghcr.io/cruxgarden/app:latest
+    container_name: cruxgarden-nursery-app
+    restart: unless-stopped
+    depends_on:
+      api:
+        condition: service_healthy
+    ports:
+      - "${APP_PORT:-8080}:80"
+
 volumes:
   postgres_data_nursery:
   redis_data_nursery:

package/lib/commands.js

@@ -1,7 +1,7 @@
 import { execSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import readline from "readline";
 import chalk from "chalk";
 import ora from "ora";
@@ -166,35 +166,110 @@ function ensureDockerRunning() {
   }
 }
 
+function getEnvFileFlag() {
+  const envFilePath = join(process.cwd(), ".env");
+  if (existsSync(envFilePath)) {
+    return `--env-file "${envFilePath}"`;
+  }
+  return "";
+}
+
+function parseAndSetEnvVars(envArgs = []) {
+  if (!envArgs || envArgs.length === 0) return;
+
+  for (const arg of envArgs) {
+    const match = arg.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (match) {
+      const [, key, value] = match;
+      process.env[key] = value;
+      console.log(chalk.gray(`  Setting ${key}=${value}`));
+    } else {
+      console.log(chalk.yellow(`  Warning: Ignoring invalid env var format: ${arg}`));
+    }
+  }
+}
+
 // ============================================================================
 // Nursery Environment Commands
 // ============================================================================
 
-export async function startNursery(options) {
+export async function startNursery(options, envVars) {
   ensureDockerRunning();
+
+  // Parse and set environment variables from command line
+  if (envVars && envVars.length > 0) {
+    console.log(chalk.cyan("\nApplying environment variables:"));
+    parseAndSetEnvVars(envVars);
+    console.log();
+  }
+
   const spinner = ora("Starting Crux Garden Nursery environment...").start();
+  const envFileFlag = getEnvFileFlag();
+
+  // Get actual port values from environment
+  const appPort = process.env.APP_PORT || "8080";
+  const apiPort = process.env.API_PORT || "3000";
+  const postgresPort = process.env.POSTGRES_PORT || "5432";
+  const redisPort = process.env.REDIS_PORT || "6379";
 
   try {
     if (options.dbOnly) {
       spinner.text = "Starting nursery database services (postgres, redis)...";
       await runCommandAsync(
-        "docker-compose -f docker-compose.nursery.yml up -d --remove-orphans postgres redis",
+        `docker-compose ${envFileFlag} -f docker-compose.nursery.yml up -d --remove-orphans postgres redis`,
         { silent: true },
       );
       spinner.succeed("Nursery database services started!");
       console.log(
         chalk.hex(SUCCESS_GREEN)("\n✓ PostgreSQL running on:"),
-        "localhost:5432",
+        `localhost:${postgresPort}`,
+      );
+      console.log(
+        chalk.hex(SUCCESS_GREEN)("✓ Redis running on:"),
+        `localhost:${redisPort}`,
+      );
+    } else if (options.apiOnly) {
+      spinner.text =
+        "Starting nursery API services (api, postgres, redis)...";
+      await runCommandAsync(
+        `docker-compose ${envFileFlag} -f docker-compose.nursery.yml up -d --remove-orphans postgres redis migrations api`,
+        {
+          silent: true,
+        },
+      );
+
+      // Clean up the migrations container if it exists (cross-platform)
+      await runCommandAsync(
+        "docker rm cruxgarden-nursery-migrations",
+        {
+          silent: true,
+          ignoreError: true,
+        },
+      );
+
+      spinner.succeed("Crux Garden Nursery API services started!");
+      console.log(
+        chalk.hex(SUCCESS_GREEN)("\n✓ API running on:"),
+        `http://localhost:${apiPort}`,
+      );
+      console.log(
+        chalk.hex(SUCCESS_GREEN)("✓ PostgreSQL running on:"),
+        `localhost:${postgresPort}`,
       );
       console.log(
         chalk.hex(SUCCESS_GREEN)("✓ Redis running on:"),
-        "localhost:6379",
+        `localhost:${redisPort}`,
+      );
+      console.log(
+        chalk.yellow(
+          "\nℹ Nursery includes demo data for trials and showcases",
+        ),
       );
     } else {
       spinner.text =
-        "Starting nursery services (api, postgres, redis)...";
+        "Starting nursery services (app, api, postgres, redis)...";
       await runCommandAsync(
-        "docker-compose -f docker-compose.nursery.yml up -d --remove-orphans",
+        `docker-compose ${envFileFlag} -f docker-compose.nursery.yml up -d --remove-orphans`,
         {
           silent: true,
         },
@@ -211,16 +286,20 @@ export async function startNursery(options) {
 
       spinner.succeed("Crux Garden Nursery environment started!");
       console.log(
-        chalk.hex(SUCCESS_GREEN)("\n✓ API running on:"),
-        "http://localhost:3000",
+        chalk.hex(SUCCESS_GREEN)("\n✓ App running on:"),
+        `http://localhost:${appPort}`,
+      );
+      console.log(
+        chalk.hex(SUCCESS_GREEN)("✓ API running on:"),
+        `http://localhost:${apiPort}`,
       );
       console.log(
         chalk.hex(SUCCESS_GREEN)("✓ PostgreSQL running on:"),
-        "localhost:5432",
+        `localhost:${postgresPort}`,
       );
       console.log(
         chalk.hex(SUCCESS_GREEN)("✓ Redis running on:"),
-        "localhost:6379",
+        `localhost:${redisPort}`,
       );
       console.log(
         chalk.yellow(
@@ -259,7 +338,8 @@ export async function startNursery(options) {
 export async function stopNursery() {
   ensureDockerRunning();
   const spinner = ora("Stopping Crux Garden Nursery environment...").start();
-  await runCommandAsync("docker-compose -f docker-compose.nursery.yml down", {
+  const envFileFlag = getEnvFileFlag();
+  await runCommandAsync(`docker-compose ${envFileFlag} -f docker-compose.nursery.yml down`, {
     silent: true,
   });
   spinner.succeed("Crux Garden Nursery environment stopped!");
@@ -273,13 +353,16 @@ export async function stopNursery() {
 
 export async function logsNursery(options) {
   ensureDockerRunning();
+  const envFileFlag = getEnvFileFlag();
+  const envFileArgs = envFileFlag ? envFileFlag.split(" ") : [];
+
   if (options.follow) {
     console.log(
       chalk.gray("Following nursery logs (press Ctrl+C to exit)...\n"),
     );
     const child = spawn(
       "docker-compose",
-      ["-f", "docker-compose.nursery.yml", "logs", "-f"],
+      [...envFileArgs, "-f", "docker-compose.nursery.yml", "logs", "-f"],
       {
         cwd: dockerDir,
         stdio: "inherit",
@@ -291,7 +374,7 @@ export async function logsNursery(options) {
       process.exit(0);
     });
   } else {
-    runCommand("docker-compose -f docker-compose.nursery.yml logs --tail=100");
+    runCommand(`docker-compose ${envFileFlag} -f docker-compose.nursery.yml logs --tail=100`);
     console.log();
   }
 }
@@ -316,9 +399,10 @@ export async function cleanNursery() {
   const spinner = ora(
     "Cleaning up nursery (removing containers and volumes)...",
   ).start();
+  const envFileFlag = getEnvFileFlag();
 
   await runCommandAsync(
-    "docker-compose -f docker-compose.nursery.yml down -v",
+    `docker-compose ${envFileFlag} -f docker-compose.nursery.yml down -v`,
     {
       silent: true,
       ignoreError: true,
@@ -359,9 +443,10 @@ export async function purgeNursery() {
   const spinner = ora(
     "Purging nursery (removing containers, volumes, and images)...",
   ).start();
+  const envFileFlag = getEnvFileFlag();
 
   await runCommandAsync(
-    "docker-compose -f docker-compose.nursery.yml down -v --rmi all",
+    `docker-compose ${envFileFlag} -f docker-compose.nursery.yml down -v --rmi all`,
     {
       silent: true,
       ignoreError: true,
@@ -383,6 +468,7 @@ export async function updateNursery() {
   const spinner = ora(
     "Checking for latest Crux Garden API image from ghcr.io...",
   ).start();
+  const envFileFlag = getEnvFileFlag();
 
   try {
     // Get the current local image digest before pulling
@@ -394,7 +480,7 @@ export async function updateNursery() {
 
     // Pull latest images
     spinner.text = "Pulling latest images...";
-    await runCommandAsync("docker-compose -f docker-compose.nursery.yml pull", {
+    await runCommandAsync(`docker-compose ${envFileFlag} -f docker-compose.nursery.yml pull`, {
       silent: true,
     });
 
@@ -433,7 +519,7 @@ export async function updateNursery() {
   console.log();
 }
 
-export async function resetNursery() {
+export async function resetNursery(envVars) {
   ensureDockerRunning();
   console.log(
     chalk.yellow(
@@ -450,13 +536,27 @@ export async function resetNursery() {
     return;
   }
 
+  // Parse and set environment variables from command line
+  if (envVars && envVars.length > 0) {
+    console.log(chalk.cyan("\nApplying environment variables:"));
+    parseAndSetEnvVars(envVars);
+    console.log();
+  }
+
   const spinner = ora("Resetting nursery environment...").start();
+  const envFileFlag = getEnvFileFlag();
+
+  // Get actual port values from environment
+  const appPort = process.env.APP_PORT || "8080";
+  const apiPort = process.env.API_PORT || "3000";
+  const postgresPort = process.env.POSTGRES_PORT || "5432";
+  const redisPort = process.env.REDIS_PORT || "6379";
 
   try {
     // Stop and remove volumes
     spinner.text = "Stopping and removing containers/volumes...";
     await runCommandAsync(
-      "docker-compose -f docker-compose.nursery.yml down -v",
+      `docker-compose ${envFileFlag} -f docker-compose.nursery.yml down -v`,
       {
         silent: true,
         ignoreError: true,
@@ -465,14 +565,14 @@ export async function resetNursery() {
 
     // Pull latest image
     spinner.text = "Pulling latest image...";
-    await runCommandAsync("docker-compose -f docker-compose.nursery.yml pull", {
+    await runCommandAsync(`docker-compose ${envFileFlag} -f docker-compose.nursery.yml pull`, {
       silent: true,
     });
 
     // Start fresh
     spinner.text = "Starting fresh nursery environment...";
     await runCommandAsync(
-      "docker-compose -f docker-compose.nursery.yml up -d --remove-orphans",
+      `docker-compose ${envFileFlag} -f docker-compose.nursery.yml up -d --remove-orphans`,
       {
         silent: true,
       },
@@ -489,16 +589,20 @@ export async function resetNursery() {
 
     spinner.succeed("Nursery environment reset complete!");
     console.log(
-      chalk.hex(SUCCESS_GREEN)("\n✓ API running on:"),
-      "http://localhost:3000",
+      chalk.hex(SUCCESS_GREEN)("\n✓ App running on:"),
+      `http://localhost:${appPort}`,
+    );
+    console.log(
+      chalk.hex(SUCCESS_GREEN)("✓ API running on:"),
+      `http://localhost:${apiPort}`,
     );
     console.log(
       chalk.hex(SUCCESS_GREEN)("✓ PostgreSQL running on:"),
-      "localhost:5432",
+      `localhost:${postgresPort}`,
     );
     console.log(
       chalk.hex(SUCCESS_GREEN)("✓ Redis running on:"),
-      "localhost:6379",
+      `localhost:${redisPort}`,
     );
     console.log(
       chalk.yellow("\nℹ Fresh nursery with latest demo data loaded"),
@@ -510,15 +614,16 @@ export async function resetNursery() {
   }
 }
 
-export async function restartNursery() {
+export async function restartNursery(options = {}, envVars) {
   await stopNursery();
-  await startNursery({});
+  await startNursery(options, envVars);
 }
 
 export async function statusNursery() {
   ensureDockerRunning();
+  const envFileFlag = getEnvFileFlag();
   console.log(chalk.bold("\nCrux Garden Nursery Environment Status:\n"));
-  runCommand("docker-compose -f docker-compose.nursery.yml ps");
+  runCommand(`docker-compose ${envFileFlag} -f docker-compose.nursery.yml ps`);
   console.log();
 }
 
@@ -545,8 +650,9 @@ export async function connectNurseryApi() {
 export async function stopNurseryDb() {
   ensureDockerRunning();
   const spinner = ora("Stopping nursery database services...").start();
+  const envFileFlag = getEnvFileFlag();
   await runCommandAsync(
-    "docker-compose -f docker-compose.nursery.yml stop postgres redis",
+    `docker-compose ${envFileFlag} -f docker-compose.nursery.yml stop postgres redis`,
     { silent: true },
   );
   spinner.succeed("Nursery database services stopped!");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxgarden/cli",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Crux Garden CLI",
   "type": "module",
   "bin": {