@stacksolo/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,19 @@
 # @stacksolo/cli
 
-Command-line tool for deploying GCP infrastructure. Designed for solo developers who want to ship fast without managing complex cloud configurations.
+A command-line tool for deploying apps to Google Cloud. Designed for solo developers who want to ship fast without managing complex cloud configurations.
+
+## What does it do?
+
+StackSolo takes your code and a simple config file, then handles all the cloud setup for you:
+- Creates Cloud Functions for your backend
+- Sets up load balancers to route traffic
+- Hosts your frontend on Cloud Storage
+- Manages databases and caches
+- Handles all the networking automatically
+
+You focus on writing code. StackSolo handles the infrastructure.
+
+---
 
 ## Installation
 
@@ -10,38 +23,205 @@ npm install -g @stacksolo/cli
 
 ## Prerequisites
 
-- Node.js 18+
-- [Terraform CLI](https://developer.hashicorp.com/terraform/install) installed
-- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+Before using StackSolo, you need:
+
+1. **Node.js 18 or newer**
+   ```bash
+   node --version  # Should show v18.x.x or higher
+   ```
+
+2. **Terraform CLI** - This is the tool that actually creates cloud resources
+   ```bash
+   # macOS
+   brew install terraform
+
+   # Or download from: https://developer.hashicorp.com/terraform/install
+   ```
+
+3. **Google Cloud CLI** - For authenticating with GCP
+   ```bash
+   # macOS
+   brew install google-cloud-sdk
+
+   # Or download from: https://cloud.google.com/sdk/docs/install
+   ```
+
+4. **Authenticate with Google Cloud**
+   ```bash
+   gcloud auth login
+   gcloud auth application-default login
+   ```
+
+---
 
 ## Quick Start
 
+### Step 1: Initialize a new project
+
 ```bash
-# Initialize a new project
 stacksolo init
+```
+
+This creates a `.stacksolo/stacksolo.config.json` file with your project settings.
 
-# Deploy infrastructure
+### Step 2: Add your code
+
+Create a function at `functions/api/index.ts`:
+
+```typescript
+import * as functions from '@google-cloud/functions-framework';
+
+functions.http('api', (req, res) => {
+  res.json({ message: 'Hello from StackSolo!' });
+});
+```
+
+### Step 3: Deploy to GCP
+
+```bash
 stacksolo deploy
+```
+
+That's it! Your API is now live on Google Cloud.
+
+---
+
+## Commands
+
+### `stacksolo init`
+
+Creates a new StackSolo project in the current directory.
+
+**What it does:**
+1. Asks you some questions about your project
+2. Creates a `.stacksolo/stacksolo.config.json` file
+3. Registers the project in your global registry
+
+**Example:**
+```bash
+cd my-project
+stacksolo init
+```
+
+---
+
+### `stacksolo deploy`
+
+Deploys your infrastructure to Google Cloud.
+
+**What it does:**
+1. Reads your config file
+2. Generates Terraform code
+3. Runs Terraform to create resources
+4. Shows you the URLs when done
+
+**Example:**
+```bash
+stacksolo deploy
+```
+
+**Flags:**
+- `--dry-run` - Show what would be deployed without actually deploying
+
+---
+
+### `stacksolo destroy`
+
+Deletes all resources created by StackSolo.
+
+**What it does:**
+1. Runs Terraform destroy
+2. Removes all cloud resources
+3. Cleans up local state
+
+**Example:**
+```bash
+stacksolo destroy
+```
+
+**Warning:** This permanently deletes your infrastructure. Any data stored in databases or storage buckets will be lost.
+
+---
+
+### `stacksolo status`
 
-# Check status
+Shows the current state of your deployment.
+
+**What it does:**
+1. Reads the Terraform state
+2. Shows what resources exist
+3. Shows URLs for your services
+
+**Example:**
+```bash
 stacksolo status
 ```
 
-## Commands
+---
+
+### `stacksolo list`
+
+Lists all StackSolo projects on your computer.
+
+**What it does:**
+1. Reads from your global registry (`~/.stacksolo/registry.db`)
+2. Shows project names and paths
+
+**Example:**
+```bash
+# List all projects
+stacksolo list
+
+# Show details for a specific project
+stacksolo list my-app
+```
+
+---
+
+### `stacksolo dev`
+
+Starts a local development environment using Kubernetes.
+
+**What it does:**
+1. Generates Kubernetes manifests from your config
+2. Starts a local K8s cluster (using Docker Desktop or minikube)
+3. Runs Firebase emulators for Firestore, Auth, and Pub/Sub
+4. Sets up port forwarding so you can access your services
+
+**Example:**
+```bash
+stacksolo dev
+```
+
+**Flags:**
+- `--no-emulators` - Skip starting Firebase emulators
+- `--health` - Check the health of running services
+- `--ports` - Show port forwarding status
+- `--restart [service]` - Restart a specific service or all services
+- `--service-names` - List available service names
+
+---
+
+### `stacksolo scaffold`
+
+Generates starter code and local dev files from your config.
 
-| Command | Description |
-|---------|-------------|
-| `stacksolo init` | Initialize a new StackSolo project with GCP setup |
-| `stacksolo deploy` | Deploy infrastructure using CDKTF/Terraform |
-| `stacksolo destroy` | Tear down deployed infrastructure |
-| `stacksolo status` | Show deployment status |
-| `stacksolo list` | List all registered projects |
-| `stacksolo dev` | Start local K8s development environment |
-| `stacksolo scaffold` | Generate local dev environment from config |
+**What it does:**
+1. Creates function/container boilerplate
+2. Generates `.env.local` with environment variables
+3. Creates `lib/env.ts` for type-safe env access
+4. Sets up Kubernetes manifests for local dev
+
+**Example:**
+```bash
+stacksolo scaffold
+```
+
+---
 
 ## Project Configuration
 
-StackSolo uses a JSON configuration file at `.stacksolo/stacksolo.config.json`:
+StackSolo uses a JSON config file at `.stacksolo/stacksolo.config.json`. Here's a simple example:
 
 ```json
 {
@@ -50,47 +230,75 @@ StackSolo uses a JSON configuration file at `.stacksolo/stacksolo.config.json`:
     "gcpProjectId": "my-gcp-project",
     "region": "us-central1"
   },
-  "networks": {
-    "main": {
-      "functions": {
-        "api": {
-          "runtime": "nodejs20",
-          "entryPoint": "api",
-          "sourceDir": "functions/api"
-        }
-      }
+  "networks": [{
+    "name": "main",
+    "functions": [{
+      "name": "api",
+      "runtime": "nodejs20",
+      "entryPoint": "api"
+    }],
+    "loadBalancer": {
+      "name": "gateway",
+      "routes": [
+        { "path": "/*", "functionName": "api" }
+      ]
     }
-  }
+  }]
 }
 ```
 
+### What each part means:
+
+- **project.name** - A name for your project (used in resource naming)
+- **project.gcpProjectId** - Your Google Cloud project ID
+- **project.region** - Where to deploy (e.g., `us-central1`, `europe-west1`)
+- **networks** - Groups of related resources
+- **functions** - Serverless functions (your backend code)
+- **loadBalancer** - Routes traffic to your functions
+
+For detailed config options, see the [GCP CDKTF Plugin docs](../plugins/gcp-cdktf/README.md).
+
+---
+
 ## Supported Resources
 
-- **Cloud Functions (Gen2)** - Serverless functions with automatic scaling
-- **Cloud Run** - Containerized applications
-- **Cloud Storage** - Object storage buckets
-- **Pub/Sub** - Message queuing
-- **VPC Networks** - Private networking with connectors
-- **Load Balancers** - Global HTTP(S) load balancing
-- **Firestore** - NoSQL database
+StackSolo can create these Google Cloud resources:
+
+| Resource | What it's for |
+|----------|---------------|
+| **Cloud Functions (Gen2)** | Serverless backend code that scales automatically |
+| **Cloud Run** | Containerized apps with more control than Functions |
+| **Cloud Storage** | File storage (also hosts static websites) |
+| **Pub/Sub** | Message queues for async processing |
+| **VPC Networks** | Private networking between your services |
+| **Load Balancers** | Route traffic to multiple backends |
+| **Firestore** | NoSQL database |
+
+---
 
 ## Local Development
 
-StackSolo includes a local Kubernetes development environment:
+StackSolo includes a local Kubernetes environment that mirrors production:
 
 ```bash
-# Start local dev with emulators
 stacksolo dev
 ```
 
 This creates a local K8s cluster with:
-- Firebase emulators (Firestore, Auth, Pub/Sub)
-- Hot-reloading for your functions
-- Service mesh for inter-service calls
+- **Firebase emulators** - Fake versions of Firestore, Auth, and Pub/Sub
+- **Hot-reloading** - Your code updates automatically when you save
+- **Service mesh** - Services can call each other just like in production
+- **Environment variables** - Same env vars as production
+
+### Why Kubernetes locally?
+
+Using K8s locally means your dev environment works exactly like production. No more "it works on my machine" problems.
+
+---
 
 ## Runtime Package
 
-For environment detection and service-to-service calls in your functions:
+When writing your function code, use the `@stacksolo/runtime` package for environment detection and service calls:
 
 ```bash
 npm install @stacksolo/runtime
@@ -99,33 +307,85 @@ npm install @stacksolo/runtime
 ```typescript
 import { env, firestore, services } from '@stacksolo/runtime';
 
-// Environment detection
+// Check if running locally or in production
 if (env.isLocal) {
   console.log('Running with emulators');
 }
 
-// Auto-configured Firestore client
+// Auto-configured Firestore client (uses emulator locally)
 const db = firestore();
+const users = await db.collection('users').get();
 
-// Call other services
+// Call another service in your stack
 const response = await services.call('api', '/users');
 ```
 
-## Global Registry
+See the [Runtime package docs](../runtime/README.md) for more details.
 
-StackSolo maintains a registry of all your projects at `~/.stacksolo/registry.db`:
+---
+
+## Global Project Registry
+
+StackSolo keeps track of all your projects in a local database at `~/.stacksolo/registry.db`. This lets you:
+
+- Switch between projects easily
+- See all your StackSolo projects in one place
+- Access project info from any directory
 
 ```bash
 # List all projects
 stacksolo list
 
-# Register current project
+# Register the current directory as a project
 stacksolo register
 
-# View project details
+# View details about a specific project
 stacksolo list my-app
 ```
 
+---
+
+## Typical Workflow
+
+Here's how most developers use StackSolo:
+
+1. **Start a new project:**
+   ```bash
+   mkdir my-app && cd my-app
+   stacksolo init
+   ```
+
+2. **Write your code:**
+   ```bash
+   # Create your function
+   mkdir -p functions/api
+   # ... write code ...
+   ```
+
+3. **Develop locally:**
+   ```bash
+   stacksolo scaffold  # Generate boilerplate
+   stacksolo dev       # Start local environment
+   ```
+
+4. **Deploy to production:**
+   ```bash
+   stacksolo deploy
+   ```
+
+5. **Check status:**
+   ```bash
+   stacksolo status
+   ```
+
+6. **Make changes and redeploy:**
+   ```bash
+   # ... edit code ...
+   stacksolo deploy
+   ```
+
+---
+
 ## Links
 
 - [Documentation](https://stacksolo.dev)