@archlast/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,149 +1,747 @@
-# Archlast CLI
-
-CLI tool for Archlast development and deployment.
-
+# @archlast/cli
+
+The Archlast CLI is a comprehensive command-line tool for development, deployment, and Docker lifecycle management of Archlast applications. It handles code generation, hot deployment, container management, and data operations.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands Reference](#commands-reference)
+  - [Development Commands](#development-commands)
+  - [Docker Management](#docker-management)
+  - [Code Generation](#code-generation)
+  - [Data Management](#data-management)
+- [Configuration](#configuration)
+- [Environment Variables](#environment-variables)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+
+## Requirements
+
+- **Node.js 18+** or **Bun 1.0+**
+- **Docker Desktop** or **Docker Engine** (for container management)
+- An Archlast project with schema and function definitions
+
 ## Installation
 
-### npm (recommended for users)
+### Global Installation (Recommended)
 
 ```bash
 npm install -g @archlast/cli
+
+# Or with bun
+bun add -g @archlast/cli
+```
+
+### Local Installation
+
+```bash
+npm install -D @archlast/cli
+
+# Run via npx
+npx archlast <command>
+```
+
+### Verify Installation
+
+```bash
+archlast --version
+archlast --help
+```
+
+## Quick Start
+
+### 1. Start the Server
+
+```bash
+# Pull and start the Docker container
+archlast start
+
+# Check status
+archlast status
+```
+
+### 2. Development Mode
+
+```bash
+# Watch for changes and auto-deploy
+archlast dev --path ./my-archlast-app
+```
+
+### 3. Production Deployment
+
+```bash
+archlast deploy --path ./my-archlast-app --server https://api.myapp.com
+```
+
+---
+
+## Commands Reference
+
+### Development Commands
+
+#### `archlast dev`
+
+Start development mode with file watching. Automatically regenerates types and deploys changes to the server.
+
+```bash
+archlast dev [options]
+
+Options:
+  --path <path>       Path to archlast folder (default: ".")
+  --server <url>      Server URL for code upload (default: "http://localhost:4000")
+  --max-poll <number> Maximum server polling retries (default: 30)
+  -p, --port <port>   Server port (default: 3001)
+```
+
+**Example:**
+
+```bash
+# Watch current directory
+archlast dev
+
+# Watch specific project with custom server
+archlast dev --path ./apps/api --server http://localhost:5000
+```
+
+#### `archlast build`
+
+Generate types without deploying. Useful for CI/CD pipelines or type checking.
+
+```bash
+archlast build --path ./my-archlast-app
+```
+
+**What it generates:**
+
+- `_generated/server.ts` - DataModel types, QueryCtx, MutationCtx
+- `_generated/api.ts` - Client-side function references
+- `_generated/rpc.ts` - tRPC router types (if using RPC)
+- `_generated/crud/<collection>.ts` - Auto-generated CRUD handlers
+
+#### `archlast deploy`
+
+One-time deployment to the server.
+
+```bash
+archlast deploy [options]
+
+Options:
+  --path <path>       Path to archlast folder (default: ".")
+  --server <url>      Server URL (default: "http://localhost:4000")
+  --max-poll <number> Maximum polling retries (default: 30)
+```
+
+#### `archlast pull`
+
+Pull schema or files from the server, or pull Docker images.
+
+```bash
+archlast pull [options]
+
+Options:
+  --path <path>         Local path (default: ".")
+  --server <url>        Server URL (default: "http://localhost:4000")
+  --files <files...>    Files to pull (default: ["src/schema.ts"])
+  --force               Overwrite without prompt
+  --diff                Show diff only
+  --merge               Attempt merge
+  --docker              Pull Docker image instead of schema
+  --image <image>       Docker image name
+  --tag <tag>           Docker image tag
+```
+
+**Examples:**
+
+```bash
+# Pull schema from server
+archlast pull --server http://localhost:4000
+
+# Pull and show diff only
+archlast pull --diff
+
+# Pull specific Docker image
+archlast pull --docker --image archlast/server --tag v1.2.0
+```
+
+---
+
+### Docker Management
+
+#### `archlast start`
+
+Start the Archlast Docker container.
+
+```bash
+archlast start [options]
+
+Options:
+  --path <path>        Path to project root (default: ".")
+  --port <port>        Host port to expose
+  --image <image>      Docker image name
+  --tag <tag>          Docker image tag
+  --container <name>   Docker container name
+  --config <path>      Path to archlast.config.js
+```
+
+**Example:**
+
+```bash
+# Start with defaults
+archlast start
+
+# Start on custom port
+archlast start --port 5000
+
+# Start specific version
+archlast start --image archlast/server --tag v1.2.0
+```
+
+#### `archlast stop`
+
+Stop the running container.
+
+```bash
+archlast stop [options]
+
+Options:
+  --path <path>        Path to project root
+  --container <name>   Docker container name
+  --config <path>      Path to archlast.config.js
+```
+
+#### `archlast restart`
+
+Restart the container with optional new configuration.
+
+```bash
+archlast restart [options]
+
+# All options from 'start' are available
+```
+
+#### `archlast status`
+
+Show container status and health information.
+
+```bash
+archlast status [options]
+
+Options:
+  --path <path>        Path to project root
+  --container <name>   Docker container name
+  --config <path>      Path to archlast.config.js
+```
+
+**Output example:**
+
+```
+🐳 Archlast Server Status
+
+Container: archlast-server
+Status: running
+Health: healthy
+Uptime: 2 hours
+Port: 4000
+Image: archlast/server:latest
+```
+
+#### `archlast logs`
+
+Stream container logs in real-time.
+
+```bash
+archlast logs [options]
+
+Options:
+  --path <path>        Path to project root
+  --container <name>   Docker container name
+  --tail <lines>       Number of log lines to show (default: 100)
+  --no-follow          Do not follow logs (exit after showing)
+  --config <path>      Path to archlast.config.js
+```
+
+**Examples:**
+
+```bash
+# Follow logs in real-time
+archlast logs --follow
+
+# Show last 50 lines and exit
+archlast logs --tail 50 --no-follow
+```
+
+#### `archlast upgrade`
+
+Pull a new Docker image and restart the container.
+
+```bash
+archlast upgrade [options]
+
+Options:
+  --path <path>        Path to project root
+  --port <port>        Host port to expose
+  --image <image>      Docker image name
+  --tag <tag>          Docker image tag (or --version)
+  --container <name>   Docker container name
+  --config <path>      Path to archlast.config.js
+```
+
+**Example:**
+
+```bash
+# Upgrade to latest
+archlast upgrade
+
+# Upgrade to specific version
+archlast upgrade --tag v1.3.0
+```
+
+#### `archlast config`
+
+Show resolved Docker configuration.
+
+```bash
+archlast config [options]
+
+Options:
+  --path <path>        Path to project root
+  --config <path>      Path to archlast.config.js
+  --json               Output config as JSON
+```
+
+---
+
+### Code Generation
+
+#### `archlast generate crud <collection>`
+
+Generate CRUD handlers for a collection defined in your schema.
+
+```bash
+archlast generate crud <collection> [options]
+
+Options:
+  --path <path>   Path to archlast folder (default: ".")
+  --force         Overwrite existing files
+  --linked        Create linked re-export file (default: true)
+  --ejected       Create standalone handlers (not linked to _generated)
+```
+
+**Example:**
+
+```bash
+# Generate CRUD for tasks collection
+archlast generate crud tasks
+
+# Force overwrite existing
+archlast generate crud tasks --force
+
+# Generate standalone (ejected) handlers
+archlast generate crud tasks --ejected
+```
+
+**Generated handlers (linked mode):**
+
+```ts
+// src/tasks.ts - Re-exports from generated code
+export {
+  listTasks,
+  getTasks,
+  createTasks,
+  updateTasks,
+  deleteTasks,
+} from "../_generated/crud/tasks";
+```
+
+**Generated handlers (ejected mode):**
+
+```ts
+// src/tasks.ts - Full implementation
+import { query, mutation } from "../_generated/server";
+
+export const listTasks = query(async (ctx) => {
+  return ctx.db.query("tasks").findMany();
+});
+
+export const getTasks = query({
+  args: { id: v.string().zodSchema },
+  handler: async (ctx, args) => {
+    return ctx.db.get("tasks", args.id);
+  },
+});
+
+// ... create, update, delete handlers
+```
+
+---
+
+### Data Management
+
+Requires `ARCHLAST_API_KEY` environment variable for authentication.
+
+#### `archlast data snapshot`
+
+Create a backup snapshot of all data.
+
+```bash
+archlast data snapshot [options]
+
+Options:
+  --server <url>   Server URL (default: "http://localhost:4000")
+  --name <name>    Custom snapshot name
+```
+
+**Example:**
+
+```bash
+export ARCHLAST_API_KEY=arch_your_api_key
+archlast data snapshot --name "pre-migration-backup"
+```
+
+#### `archlast data list`
+
+List available snapshots.
+
+```bash
+archlast data list --server http://localhost:4000
+```
+
+#### `archlast data restore`
+
+Restore from a snapshot.
+
+```bash
+archlast data restore <snapshot-name> [options]
+
+Options:
+  --server <url>   Server URL
+  --force          Skip confirmation
+```
+
+#### `archlast data export`
+
+Export data to a local JSON file.
+
+```bash
+archlast data export [options]
+
+Options:
+  --server <url>       Server URL
+  --output <path>      Output file path (default: "archlast-export.json")
+  --collections <...>  Specific collections to export
+```
+
+#### `archlast data import`
+
+Import data from a local JSON file.
+
+```bash
+archlast data import <file> [options]
+
+Options:
+  --server <url>   Server URL
+  --force          Skip confirmation
+  --merge          Merge with existing data (default: replace)
+```
+
+#### `archlast data delete`
+
+Delete a snapshot.
+
+```bash
+archlast data delete <snapshot-name> --server http://localhost:4000
+```
+
+---
+
+## Configuration
+
+The CLI reads configuration in this priority order:
+
+1. **CLI flags** (highest priority)
+2. **archlast.config.js** or **archlast.config.ts**
+3. **.env** or **.env.local**
+4. **Defaults** (lowest priority)
+
+### Configuration File
+
+Create `archlast.config.js` in your project root:
+
+```js
+// archlast.config.js
+export default {
+  // Docker configuration
+  docker: {
+    image: "archlast/server",
+    tag: "latest",
+    containerName: "archlast-server",
+    volumeName: "archlast-data",
+    network: "archlast-network",
+  },
+
+  // Server settings
+  server: {
+    port: 4000,
+    host: "0.0.0.0",
+  },
+
+  // Paths configuration
+  paths: {
+    config: ".archlast/config",
+    deploy: ".archlast-deploy",
+    data: "./data",
+  },
+
+  // CORS settings
+  cors: {
+    origins: ["http://localhost:3000", "https://myapp.com"],
+    credentials: true,
+  },
+
+  // Environment variables to forward to container
+  env: {
+    ARCHLAST_DASHBOARD_PORT: "4001",
+    ARCHLAST_STORE_PORT: "7001",
+    NODE_ENV: "production",
+  },
+};
+```
+
+### TypeScript Configuration
+
+```ts
+// archlast.config.ts
+import type { ArchlastConfig } from "@archlast/cli";
+
+const config: ArchlastConfig = {
+  docker: {
+    image: "archlast/server",
+    tag: "latest",
+  },
+  server: {
+    port: 4000,
+  },
+};
+
+export default config;
+```
+
+---
+
+## Environment Variables
+
+The following environment variables are automatically forwarded to the Docker container:
+
+| Prefix | Description |
+|--------|-------------|
+| `ARCHLAST_*` | All Archlast configuration |
+| `S3_*` | S3 storage configuration |
+| `AWS_*` | AWS credentials |
+| `STORAGE_*` | Storage settings |
+
+### Key Variables
+
+```bash
+# API Authentication
+ARCHLAST_API_KEY=arch_your_api_key
+
+# Server Configuration
+ARCHLAST_PORT=4000
+ARCHLAST_ALLOWED_ORIGINS=http://localhost:3000,https://myapp.com
+ARCHLAST_CORS_ALLOW_CREDENTIALS=true
+
+# Database
+ARCHLAST_DB_ROOT=./data
+
+# Storage
+STORAGE_ROOT=./storage
+S3_ENABLED=false
+S3_BUCKET=my-bucket
+S3_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your_key
+AWS_SECRET_ACCESS_KEY=your_secret
+
+# Document Store
+ARCHLAST_STORE_HOST=127.0.0.1
+ARCHLAST_STORE_PORT=7001
+```
+
+---
+
+## Usage Examples
+
+### Complete Development Workflow
+
+```bash
+# 1. Initialize and start server
+archlast start
+
+# 2. Start development with hot reload
+archlast dev --path ./my-app
+
+# 3. Generate CRUD for new collection
+archlast generate crud users
+
+# 4. Check logs if issues arise
+archlast logs --follow
+
+# 5. Create backup before major changes
+archlast data snapshot --name "before-feature-x"
+
+# 6. Deploy to production
+archlast deploy --server https://api.production.com
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy Archlast
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install CLI
+        run: npm install -g @archlast/cli
+
+      - name: Build types
+        run: archlast build --path ./archlast
+
+      - name: Deploy
+        run: archlast deploy --path ./archlast --server ${{ secrets.API_URL }}
+        env:
+          ARCHLAST_API_KEY: ${{ secrets.ARCHLAST_API_KEY }}
+```
+
+### Multi-Environment Setup
+
+```bash
+# Development
+archlast dev --server http://localhost:4000
+
+# Staging
+archlast deploy --server https://api.staging.myapp.com
+
+# Production
+archlast deploy --server https://api.myapp.com
 ```
 
-### Local development (repo)
-
-```bash
-bun install
-bun run build
-```
-
-## Usage
-
-### Development Mode
-
-Watch for file changes and auto-generate types:
-
-```bash
-bun run archlast:dev
-# or
-bun archlast dev
-```
-
-Options:
-
-- `--path <path>` - Path to archlast folder (default: `./archlast`)
-- `--port <port>` - Server port (default: `3001`)
-- `--server <url>` - Server URL for code upload (default: `http://localhost:3001`)
-
-### Deploy Mode
-
-One-time deployment:
-
-```bash
-bun run archlast:deploy
-# or
-bun archlast deploy
-```
-
-Options:
-
-- `--path <path>` - Path to archlast folder (default: `./archlast`)
-- `--server <url>` - Server URL for code upload (default: `http://localhost:3001`)
-
-## Features
-
-- 📁 **File Watching**: Monitors `archlast/src/` folder for changes
-- 🔍 **Code Analysis**: Detects functions (query, mutation, action) and schema changes
-- 🎯 **Type Generation**: Auto-generates client-side TypeScript types to `_generated/`
-- 🔄 **Diff Detection**: Shows added, modified, and removed functions
-- ⚡ **Fast Rebuilds**: Only regenerates on actual changes
-- 🌐 **HTTP Upload**: Uploads code to server via `/_archlast/deploy` endpoint
-
-## How It Works
-
-1. Watches all `.ts` files in the `archlast/src/` folder
-2. Analyzes exports to find `query`, `mutation`, and `action` functions
-3. Detects schema changes in `src/schema.ts`
-4. Generates type definitions in `archlast/_generated/api.ts`
-5. **Uploads code to server via HTTP** (POST to `/_archlast/deploy`)
-6. Shows a diff of changes in the console
-
-## Project Structure
-
-```
-archlast/
-├── src/              # Your function definitions
-│   ├── schema.ts     # Database schema
-│   ├── tasks.ts      # Function exports
-│   └── ...
-├── _generated/       # Auto-generated by CLI
-│   ├── api.ts        # Type-safe API object
-│   ├── index.ts      # Barrel export
-│   └── server.ts     # Server types (manual)
-├── package.json
-└── tsconfig.json
-```
-
-Run `bun run dev` from the archlast folder to start development mode.
-
-Similar to Convex's `npx convex dev` workflow.
-
-## Server Endpoint
-
-The server receives deployments at `POST /_archlast/deploy` with payload:
-
-```typescript
-{
-  functions: Array<{
-    name: string;
-    type: 'query' | 'mutation' | 'action';
-    filePath: string;
-    code: string;
-  }>;
-  schema: {
-    filePath: string;
-    code: string;
-  } | null;
-  timestamp: number;
-}
-```
-
-Server responds with:
-
-```typescript
-{
-    success: boolean;
-    message: string;
-    functions: number;
-    schema: boolean;
-}
-```
-
-Similar to Convex's `npx convex dev` workflow.
-
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Docker not found"
+
+Ensure Docker is installed and running:
+
+```bash
+docker --version
+docker ps  # Should not error
+```
+
+#### "Connection refused"
+
+The server might not be running:
+
+```bash
+archlast status
+archlast start
+```
+
+#### "Permission denied" (Linux)
+
+For Docker socket access:
+
+```bash
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+#### "Schema file not found"
+
+Ensure your schema is at `src/schema.ts`:
+
+```
+my-app/
+├── src/
+│   ├── schema.ts      # Required
+│   └── functions/
+└── archlast.config.js
+```
+
+#### "API key not found"
+
+Set the API key:
+
+```bash
+export ARCHLAST_API_KEY=arch_your_key
+
+# Or add to .env file
+echo "ARCHLAST_API_KEY=arch_your_key" >> .env
+```
+
+### Debug Mode
+
+Enable verbose logging:
+
+```bash
+DEBUG=archlast:* archlast dev
+```
+
+---
+
+## Deployment Protocol
+
+The server receives deployments at `POST /_archlast/deploy` with payload:
+
+```typescript
+interface DeployPayload {
+  functions: Array<{
+    name: string;
+    type: "query" | "mutation" | "action" | "http" | "webhook" | "rpc";
+    filePath: string;
+    code: string;
+  }>;
+  schema: {
+    filePath: string;
+    code: string;
+  } | null;
+  timestamp: number;
+}
+```
+
+---
+
 ## Testing
-
-Run the test suite:
-
-```bash
-bun test
-```
-
-Run with coverage:
-
-```bash
-bun test --coverage
-```
-
-The test suite includes:
-
-- **Unit tests**: Individual module testing (analyzer, generator, uploader, watcher, DI generator)
-- **Integration tests**: Command orchestration (dev, deploy)
-- **CLI tests**: Entry point and command parsing
-- **Fixtures**: Comprehensive test data for malformed exports, complex handlers, schema variations, and mock manifests
-
-Coverage target: 90%+ lines/branches/functions
-
-## Publishing (maintainers)
+
+```bash
+# Run CLI tests
+bun test
+
+# Run specific test
+bun test tests/cli.test.ts
+```
+
+## Publishing (Maintainers)
 
 See `docs/npm-publishing.md` for the release workflow and manual publish steps.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@archlast/cli",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Archlast CLI for development and deployment",
     "type": "module",
     "main": "dist/index.js",