@archlast/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,149 +1,975 @@
-# 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 analysis, type 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)
+- [Generated Files](#generated-files)
+- [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 using delta deployments.
+
+```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)
+```
+
+**What happens:**
+
+1. Polls server to ensure it's reachable
+2. Analyzes code for functions, HTTP routes, RPC procedures, and injectables
+3. Generates types in `_generated/` directory
+4. Computes delta (added/modified/removed files) against server manifest
+5. Uploads only changed files (delta deployment)
+6. Watches `src/**/*.ts` for changes and repeats
+
+**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, ActionCtx
+- `_generated/api.ts` - Client-side function references
+- `_generated/rpc.ts` - RPC procedure types
+- `_generated/trpc-router.ts` - tRPC router with AppRouter type
+- `_generated/crud/<collection>.ts` - Auto-generated REST CRUD handlers
+- `_generated/di.ts` - Dependency injection provider registrations (if injectables detected)
+- `_generated/index.ts` - Barrel exports
+
+#### `archlast deploy`
+
+One-time deployment to the server with delta detection.
+
+```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)
 ```
 
-### 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.
-
+**Deployment Protocol:**
+
+The CLI computes a delta by comparing local file hashes against the server's manifest (`GET /_archlast/deploy/manifest`), then sends only changed files to `POST /_archlast/deploy`.
+
+```typescript
+interface DeltaUploadPayload {
+  timestamp: number;
+  changes: {
+    added: Array<{ filePath: string; code: string }>;
+    modified: Array<{ filePath: string; code: string }>;
+    removed: string[];
+  };
+}
+```
+
+#### `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
+  --smart               Enable smart pull with change detection
+  --docker              Pull Docker image instead of schema
+  --image <image>       Docker image name
+  --tag <tag>           Docker image tag
+  --version <version>   Docker image version (alias for --tag)
+```
+
+**Examples:**
+
+```bash
+# Pull schema from server
+archlast pull --server http://localhost:4000
+
+# Pull and show diff only
+archlast pull --diff
+
+# Smart pull with change detection
+archlast pull --smart
+
+# Pull specific Docker image
+archlast pull --docker --image archlast/server --tag v1.2.0
+```
+
+---
+
+### Docker Management
+
+All Docker commands support configuration via `archlast.config.js` or CLI flags.
+
+#### `archlast start`
+
+Start the Archlast Docker container with health checking.
+
+```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
+```
+
+**What happens:**
+
+1. Loads configuration (CLI flags → config file → .env → defaults)
+2. Generates Docker Compose file at `.archlast/config/docker-compose.yml`
+3. Starts the container via Docker Compose
+4. Waits for health check at `/health` (60 second timeout)
+5. Displays API and Dashboard URLs
+
+**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
+```
+
+**Output:**
+
+```
+API:       http://localhost:4000
+Dashboard: http://localhost:4000/_admin
+Compose:   .archlast/config/docker-compose.yml
+```
+
+#### `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 includes:**
+
+- Container name and state
+- Health status
+- Uptime
+- Port mappings
+- Image version
+- CPU and memory usage
+
+#### `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 (default)
+archlast logs
+
+# 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
+  --version <version>  Docker image version (alias for --tag)
+  --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 REST 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):**
+
+Creates `src/functions/tasks.ts`:
+
+```ts
+// Auto-generated CRUD re-export for "tasks"
+// This file links to the auto-generated handlers in _generated/crud
+export * from "../_generated/crud/tasks";
+```
+
+**Generated handlers (ejected mode):**
+
+Creates standalone handlers with full implementation that you can customize:
+
+```ts
+// Auto-generated CRUD handlers for "tasks"
+import { http } from "../_generated/server";
+import type { DataModel } from "../_generated/server";
+
+export const listTasks = http.get({
+  path: "/tasks",
+  auth: "public",
+  handler: async (ctx) => {
+    return ctx.db.query("tasks").findMany();
+  },
+});
+
+// ... get, create, update, delete handlers
+```
+
+---
+
+### Data Management
+
+All data commands require a Better-Auth API key for authentication. API keys use the `arch_` prefix and can be created via the dashboard or Better-Auth API.
+
+```bash
+# Set API key before running data commands
+export ARCHLAST_API_KEY=arch_your_api_key
+```
+
+#### `archlast data snapshot`
+
+Create a backup snapshot of all data.
+
+```bash
+archlast data snapshot [options]
+
+Options:
+  --server <url>       Server URL (default: "http://localhost:4000")
+  -n, --name <name>    Custom snapshot name
+  --include-sqlite     Include SQLite export (default: false)
+```
+
+**Example:**
+
+```bash
+archlast data snapshot --name "pre-migration-backup"
+```
+
+**Output:**
+
+```
+✅ Snapshot created: snapshot-2024-01-15-123456.zip
+  Records: 1234
+  Collections: 5
+```
+
+#### `archlast data export <outputFile>`
+
+Export all data to a local file.
+
+```bash
+archlast data export <outputFile> [options]
+
+Options:
+  --server <url>         Server URL (default: "http://localhost:4000")
+  -f, --format <format>  Export format: zip or json (default: "zip")
+```
+
+**Example:**
+
+```bash
+archlast data export backup.zip
+archlast data export backup.json --format json
+```
+
+#### `archlast data import <inputFile>`
+
+Import data from a local JSON or ZIP file (auto-detects format).
+
+```bash
+archlast data import <inputFile> [options]
+
+Options:
+  --server <url>             Server URL (default: "http://localhost:4000")
+  -s, --strategy <strategy>  Import strategy: replace or merge (default: "merge")
+```
+
+**Example:**
+
+```bash
+archlast data import backup.json --strategy merge
+archlast data import backup.zip
+```
+
+#### `archlast data restore <snapshotFile>`
+
+Restore database from a server-side snapshot.
+
+```bash
+archlast data restore <snapshotFile> [options]
+
+Options:
+  --server <url>   Server URL (default: "http://localhost:4000")
+```
+
+**Example:**
+
+```bash
+archlast data restore snapshot-2024-01-15-123456
+```
+
+#### `archlast data delete <snapshotFile>`
+
+Delete a snapshot file (supports .json and .zip).
+
+```bash
+archlast data delete <snapshotFile> [options]
+
+Options:
+  --server <url>   Server URL (default: "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.local** (takes precedence over .env)
+4. **.env**
+5. **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",
+  },
+
+  // Server settings
+  server: {
+    port: 4000,
+  },
+
+  // Paths configuration
+  paths: {
+    config: ".archlast/config",
+    deploy: ".archlast-deploy",
+  },
+
+  // CORS settings
+  cors: {
+    origins: ["http://localhost:3000", "https://myapp.com"],
+  },
+
+  // Environment variables to forward to container
+  env: {
+    ARCHLAST_DASHBOARD_PORT: "4001",
+    ARCHLAST_STORE_PORT: "7001",
+    NODE_ENV: "production",
+  },
+};
+```
+
+### Default Configuration Values
+
+```js
+{
+  docker: {
+    image: "archlast/server",
+    tag: "latest",
+    containerName: "archlast-server",
+    volumeName: "archlast-data",
+  },
+  server: {
+    port: 4000,
+  },
+  paths: {
+    config: ".archlast/config",
+    deploy: ".archlast-deploy",
+  },
+  cors: {
+    origins: ["http://localhost:3000"],
+  },
+  env: {
+    NODE_ENV: "development",
+    ARCHLAST_LOG_LEVEL: "info",
+    ARCHLAST_DB_ROOT: "/data",
+    STORAGE_ROOT: "/data/storage",
+    ARCHLAST_DASHBOARD_PORT: "4001",
+    ARCHLAST_STORE_PORT: "7001",
+  },
+}
+```
+
+---
+
+## Environment Variables
+
+The following environment variable prefixes are automatically forwarded to the Docker container:
+
+| Prefix | Description |
+|--------|-------------|
+| `ARCHLAST_*` | All Archlast configuration |
+| `S3_*` | S3 storage configuration |
+| `AWS_*` | AWS credentials |
+| `STORAGE_*` | Storage settings |
+
+Additionally, these specific variables are forwarded:
+
+- `NODE_ENV`
+- `BETTER_AUTH_SECRET`
+
+### Key Variables
+
+```bash
+# API Authentication (Better-Auth API key with arch_ prefix)
+ARCHLAST_API_KEY=arch_your_api_key
+
+# Better-Auth Configuration
+BETTER_AUTH_SECRET=your-32-char-secret-for-production
+APP_URL=http://localhost:4000
+
+# 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
+```
+
+---
+
+## Generated Files
+
+When you run `archlast dev` or `archlast build`, the CLI generates the following files:
+
+### `_generated/server.ts`
+
+Contains server-side type definitions:
+
+```ts
+// DataModel with all collection types
+export type DataModel = {
+  tasks: {
+    _id: string;
+    _collection: "tasks";
+    text: string;
+    completed: boolean;
+    // ... fields from schema
+  };
+  // ... other collections
+};
+
+// Context types for functions
+export type QueryCtx = { db: DatabaseReader; auth: AuthContext; ... };
+export type MutationCtx = { db: DatabaseWriter; auth: AuthContext; ... };
+export type ActionCtx = { ... };
+
+// Function builders
+export const query: QueryBuilder;
+export const mutation: MutationBuilder;
+export const action: ActionBuilder;
+export const http: HttpBuilder;
+```
+
+### `_generated/api.ts`
+
+Contains client-side function references:
+
+```ts
+export const api = {
+  tasks: {
+    list: createFunctionReference<{}, Task[]>("tasks.list"),
+    get: createFunctionReference<{ id: string }, Task>("tasks.get"),
+    create: createFunctionReference<CreateTaskArgs, Task>("tasks.create"),
+    // ...
+  },
+  // ... other modules
+};
+```
+
+### `_generated/rpc.ts`
+
+Contains RPC procedure types:
+
+```ts
+export type RpcProcedures = {
+  "getUser": { args: { id: string }; result: User };
+  // ... procedures defined with rpc.query/rpc.mutation
+};
+```
+
+### `_generated/trpc-router.ts`
+
+Contains tRPC router definition:
+
+```ts
+import { initTRPC } from "@trpc/server";
+
+const t = initTRPC.create();
+export const appRouter = t.router({
+  getUser: t.procedure.input(...).query(...),
+  // ...
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+### `_generated/crud/<collection>.ts`
+
+Auto-generated REST CRUD handlers for each collection:
+
+```ts
+export const listTasks = http.get({ path: "/tasks", ... });
+export const getTasks = http.get({ path: "/tasks/:id", ... });
+export const createTasks = http.post({ path: "/tasks", ... });
+export const updateTasks = http.patch({ path: "/tasks/:id", ... });
+export const deleteTasks = http.delete({ path: "/tasks/:id", ... });
+```
+
+### `_generated/di.ts`
+
+Dependency injection registrations (if `@injectable()` decorators detected):
+
+```ts
+import { Container } from "@archlast/server/di/container";
+
+export const providers = [
+  { provide: "EmailService", useClass: ResendEmailService, scope: "transient" },
+  // ...
+];
+
+export function registerProviders(container: Container): void {
+  for (const provider of providers) {
+    container.register(provider);
+  }
+}
+```
+
+---
+
+## 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
+
+# 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
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Docker not found"
+
+Ensure Docker is installed and running:
+
+```bash
+docker --version
+docker ps  # Should not error
+```
+
+#### "Server not reachable after X retries"
+
+The server might not be running or is not healthy:
+
+```bash
+archlast status
+archlast start
+archlast logs  # Check for errors
+```
+
+#### "Authentication failed" / "API key not found"
+
+Set the API key with the correct `arch_` prefix:
+
+```bash
+export ARCHLAST_API_KEY=arch_your_key
+
+# Or add to .env.local file
+echo "ARCHLAST_API_KEY=arch_your_key" >> .env.local
+```
+
+API keys can be created via the admin dashboard at `/_archlast/admin/api-keys` or through the Better-Auth API.
+
+#### "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` or `src/schema/index.ts`:
+
+```
+my-app/
+├── src/
+│   ├── schema.ts      # Required
+│   └── functions/
+└── archlast.config.js
+```
+
+#### "Collection not found in schema"
+
+When using `generate crud`, the collection must be defined with `defineTable`:
+
+```ts
+// src/schema.ts
+import { defineTable, v } from "@archlast/server/schema";
+
+export const tasks = defineTable({
+  _id: v.id().primaryKey(),
+  text: v.string(),
+  completed: v.boolean().default(false),
+});
+```
+
+### Podman Support
+
+Podman is experimentally supported. If you encounter issues:
+
+```bash
+# Ensure DOCKER_HOST is set correctly
+export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
+```
+
+---
+
+## Code Analysis
+
+The CLI uses `ts-morph` for sophisticated TypeScript analysis:
+
+- **Functions**: Detects `query()`, `mutation()`, `action()` exports
+- **HTTP Routes**: Detects `http.get()`, `http.post()`, `http.put()`, `http.delete()`, `http.patch()`
+- **RPC Procedures**: Detects `rpc.query()`, `rpc.mutation()`
+- **Injectables**: Detects `@injectable()` decorated classes
+- **Schema**: Parses `defineTable()` definitions
+
+### Supported Function Patterns
+
+```ts
+// Arrow function handler
+export const listTasks = query(async (ctx) => { ... });
+
+// Object with handler
+export const createTask = mutation({
+  args: { text: v.string().zodSchema },
+  handler: async (ctx, args) => { ... },
+});
+
+// With auth mode
+export const publicQuery = query({
+  auth: "public",  // "required" | "optional" | "public"
+  handler: async (ctx) => { ... },
+});
+```
+
+---
+
 ## 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)
-
-See `docs/npm-publishing.md` for the release workflow and manual publish steps.
+
+```bash
+# Run all CLI tests
+bun test
+
+# Run specific test
+bun test tests/cli.test.ts
+
+# Run with coverage
+bun test --coverage
+```
+
+## Keywords
+
+archlast, cli, reactive, backend, code-generation, deployment, docker, typescript
+
+## License
+
+MIT

package/package.json

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