@archlast/cli 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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
 
@@ -14,6 +14,7 @@ The Archlast CLI is a comprehensive command-line tool for development, deploymen
   - [Data Management](#data-management)
 - [Configuration](#configuration)
 - [Environment Variables](#environment-variables)
+- [Generated Files](#generated-files)
 - [Usage Examples](#usage-examples)
 - [Troubleshooting](#troubleshooting)
 
@@ -83,7 +84,7 @@ archlast deploy --path ./my-archlast-app --server https://api.myapp.com
 
 #### `archlast dev`
 
-Start development mode with file watching. Automatically regenerates types and deploys changes to the server.
+Start development mode with file watching. Automatically regenerates types and deploys changes to the server using delta deployments.
 
 ```bash
 archlast dev [options]
@@ -95,6 +96,15 @@ Options:
   -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
@@ -115,14 +125,17 @@ archlast build --path ./my-archlast-app
 
 **What it generates:**
 
-- `_generated/server.ts` - DataModel types, QueryCtx, MutationCtx
+- `_generated/server.ts` - DataModel types, QueryCtx, MutationCtx, ActionCtx
 - `_generated/api.ts` - Client-side function references
-- `_generated/rpc.ts` - tRPC router types (if using RPC)
-- `_generated/crud/<collection>.ts` - Auto-generated CRUD handlers
+- `_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.
+One-time deployment to the server with delta detection.
 
 ```bash
 archlast deploy [options]
@@ -133,6 +146,21 @@ Options:
   --max-poll <number> Maximum polling retries (default: 30)
 ```
 
+**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.
@@ -147,9 +175,11 @@ Options:
   --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:**
@@ -161,6 +191,9 @@ 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
 ```
@@ -169,9 +202,11 @@ 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.
+Start the Archlast Docker container with health checking.
 
 ```bash
 archlast start [options]
@@ -185,6 +220,14 @@ Options:
   --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
@@ -198,6 +241,14 @@ archlast start --port 5000
 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.
@@ -234,18 +285,14 @@ Options:
   --config <path>      Path to archlast.config.js
 ```
 
-**Output example:**
-
-```
-🐳 Archlast Server Status
+**Output includes:**
 
-Container: archlast-server
-Status: running
-Health: healthy
-Uptime: 2 hours
-Port: 4000
-Image: archlast/server:latest
-```
+- Container name and state
+- Health status
+- Uptime
+- Port mappings
+- Image version
+- CPU and memory usage
 
 #### `archlast logs`
 
@@ -265,8 +312,8 @@ Options:
 **Examples:**
 
 ```bash
-# Follow logs in real-time
-archlast logs --follow
+# Follow logs in real-time (default)
+archlast logs
 
 # Show last 50 lines and exit
 archlast logs --tail 50 --no-follow
@@ -283,7 +330,8 @@ 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)
+  --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
 ```
@@ -317,7 +365,7 @@ Options:
 
 #### `archlast generate crud <collection>`
 
-Generate CRUD handlers for a collection defined in your schema.
+Generate REST CRUD handlers for a collection defined in your schema.
 
 ```bash
 archlast generate crud <collection> [options]
@@ -344,42 +392,44 @@ archlast generate crud tasks --ejected
 
 **Generated handlers (linked mode):**
 
+Creates `src/functions/tasks.ts`:
+
 ```ts
-// src/tasks.ts - Re-exports from generated code
-export {
-  listTasks,
-  getTasks,
-  createTasks,
-  updateTasks,
-  deleteTasks,
-} from "../_generated/crud/tasks";
+// 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):**
 
-```ts
-// src/tasks.ts - Full implementation
-import { query, mutation } from "../_generated/server";
+Creates standalone handlers with full implementation that you can customize:
 
-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);
+```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();
   },
 });
 
-// ... create, update, delete handlers
+// ... get, create, update, delete handlers
 ```
 
 ---
 
 ### Data Management
 
-Requires `ARCHLAST_API_KEY` environment variable for authentication.
+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`
 
@@ -389,69 +439,89 @@ Create a backup snapshot of all data.
 archlast data snapshot [options]
 
 Options:
-  --server <url>   Server URL (default: "http://localhost:4000")
-  --name <name>    Custom snapshot name
+  --server <url>       Server URL (default: "http://localhost:4000")
+  -n, --name <name>    Custom snapshot name
+  --include-sqlite     Include SQLite export (default: false)
 ```
 
 **Example:**
 
 ```bash
-export ARCHLAST_API_KEY=arch_your_api_key
 archlast data snapshot --name "pre-migration-backup"
 ```
 
-#### `archlast data list`
+**Output:**
 
-List available snapshots.
-
-```bash
-archlast data list --server http://localhost:4000
+```
+✅ Snapshot created: snapshot-2024-01-15-123456.zip
+  Records: 1234
+  Collections: 5
 ```
 
-#### `archlast data restore`
+#### `archlast data export <outputFile>`
 
-Restore from a snapshot.
+Export all data to a local file.
 
 ```bash
-archlast data restore <snapshot-name> [options]
+archlast data export <outputFile> [options]
 
 Options:
-  --server <url>   Server URL
-  --force          Skip confirmation
+  --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 export`
+#### `archlast data import <inputFile>`
 
-Export data to a local JSON file.
+Import data from a local JSON or ZIP file (auto-detects format).
 
 ```bash
-archlast data export [options]
+archlast data import <inputFile> [options]
 
 Options:
-  --server <url>       Server URL
-  --output <path>      Output file path (default: "archlast-export.json")
-  --collections <...>  Specific collections to export
+  --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 import`
+#### `archlast data restore <snapshotFile>`
 
-Import data from a local JSON file.
+Restore database from a server-side snapshot.
 
 ```bash
-archlast data import <file> [options]
+archlast data restore <snapshotFile> [options]
 
 Options:
-  --server <url>   Server URL
-  --force          Skip confirmation
-  --merge          Merge with existing data (default: replace)
+  --server <url>   Server URL (default: "http://localhost:4000")
 ```
 
-#### `archlast data delete`
+**Example:**
+
+```bash
+archlast data restore snapshot-2024-01-15-123456
+```
 
-Delete a snapshot.
+#### `archlast data delete <snapshotFile>`
+
+Delete a snapshot file (supports .json and .zip).
 
 ```bash
-archlast data delete <snapshot-name> --server http://localhost:4000
+archlast data delete <snapshotFile> [options]
+
+Options:
+  --server <url>   Server URL (default: "http://localhost:4000")
 ```
 
 ---
@@ -462,8 +532,9 @@ 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)
+3. **.env.local** (takes precedence over .env)
+4. **.env**
+5. **Defaults** (lowest priority)
 
 ### Configuration File
 
@@ -478,26 +549,22 @@ export default {
     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
@@ -509,30 +576,42 @@ export default {
 };
 ```
 
-### TypeScript Configuration
+### Default Configuration Values
 
-```ts
-// archlast.config.ts
-import type { ArchlastConfig } from "@archlast/cli";
-
-const config: ArchlastConfig = {
+```js
+{
   docker: {
     image: "archlast/server",
     tag: "latest",
+    containerName: "archlast-server",
+    volumeName: "archlast-data",
   },
   server: {
     port: 4000,
   },
-};
-
-export default config;
+  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 variables are automatically forwarded to the Docker container:
+The following environment variable prefixes are automatically forwarded to the Docker container:
 
 | Prefix | Description |
 |--------|-------------|
@@ -541,12 +620,21 @@ The following environment variables are automatically forwarded to the Docker co
 | `AWS_*` | AWS credentials |
 | `STORAGE_*` | Storage settings |
 
+Additionally, these specific variables are forwarded:
+
+- `NODE_ENV`
+- `BETTER_AUTH_SECRET`
+
 ### Key Variables
 
 ```bash
-# API Authentication
+# 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
@@ -570,6 +658,115 @@ 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
@@ -585,7 +782,7 @@ archlast dev --path ./my-app
 archlast generate crud users
 
 # 4. Check logs if issues arise
-archlast logs --follow
+archlast logs
 
 # 5. Create backup before major changes
 archlast data snapshot --name "before-feature-x"
@@ -655,15 +852,29 @@ docker --version
 docker ps  # Should not error
 ```
 
-#### "Connection refused"
+#### "Server not reachable after X retries"
 
-The server might not be running:
+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:
@@ -675,7 +886,7 @@ newgrp docker
 
 #### "Schema file not found"
 
-Ensure your schema is at `src/schema.ts`:
+Ensure your schema is at `src/schema.ts` or `src/schema/index.ts`:
 
 ```
 my-app/
@@ -685,45 +896,59 @@ my-app/
 └── archlast.config.js
 ```
 
-#### "API key not found"
+#### "Collection not found in schema"
 
-Set the API key:
+When using `generate crud`, the collection must be defined with `defineTable`:
 
-```bash
-export ARCHLAST_API_KEY=arch_your_key
+```ts
+// src/schema.ts
+import { defineTable, v } from "@archlast/server/schema";
 
-# Or add to .env file
-echo "ARCHLAST_API_KEY=arch_your_key" >> .env
+export const tasks = defineTable({
+  _id: v.id().primaryKey(),
+  text: v.string(),
+  completed: v.boolean().default(false),
+});
 ```
 
-### Debug Mode
+### Podman Support
 
-Enable verbose logging:
+Podman is experimentally supported. If you encounter issues:
 
 ```bash
-DEBUG=archlast:* archlast dev
+# Ensure DOCKER_HOST is set correctly
+export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
 ```
 
 ---
 
-## Deployment Protocol
+## Code Analysis
 
-The server receives deployments at `POST /_archlast/deploy` with payload:
+The CLI uses `ts-morph` for sophisticated TypeScript analysis:
 
-```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;
-}
+- **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) => { ... },
+});
 ```
 
 ---
@@ -731,16 +956,19 @@ interface DeployPayload {
 ## Testing
 
 ```bash
-# Run CLI tests
+# Run all CLI tests
 bun test
 
 # Run specific test
 bun test tests/cli.test.ts
+
+# Run with coverage
+bun test --coverage
 ```
 
-## Publishing (Maintainers)
+## Keywords
 
-See `docs/npm-publishing.md` for the release workflow and manual publish steps.
+archlast, cli, reactive, backend, code-generation, deployment, docker, typescript
 
 ## License
 

package/package.json

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