@zap-js/client 0.0.2 → 0.0.4

package/README.md

@@ -1,44 +1,330 @@
-# @zap-js/client
+# @zapjs/client
 
-Client-side package for the ZapJS fullstack React framework.
+Official CLI and development tools for ZapJS - the fullstack Rust + React framework.
 
 ## Installation
 
+### Global Installation (Recommended)
+
+Install the ZapJS CLI globally to use the `zap` command anywhere:
+
+```bash
+npm install -g @zapjs/client
+```
+
+After installation, verify it works:
+
 ```bash
-npm install @zap-js/client
+zap --version
+zap --help
 ```
 
-## Usage
+### Local Project Installation
 
-```javascript
-import { router, middleware, errors, logger } from '@zap-js/client'
+For project-specific installation:
 
-// Router components and hooks
-const { Link, useRouter, useParams } = router
+```bash
+npm install --save-dev @zapjs/client
+```
+
+Then use via npm scripts in your `package.json`:
 
-// Middleware functions
-const { requireAuth, preloadData } = middleware
+```json
+{
+  "scripts": {
+    "dev": "zap dev",
+    "build": "zap build",
+    "serve": "zap serve"
+  }
+}
+```
+
+### Local Development (Contributors)
 
-// Error handling
-const { ErrorBoundary } = errors
+If you're contributing to ZapJS:
 
-// Logging
-const log = logger.create('MyApp')
+```bash
+cd packages/client
+npm install
+npm run build
+npm link
 ```
 
-## Features
+This creates a global symlink for local testing. The `zap` command will now use your local development version.
+
+## Available Commands
+
+### `zap new <name>`
+
+Create a new ZapJS project with the specified template.
+
+```bash
+zap new my-app
+zap new my-app --template fullstack
+zap new my-app --no-install --no-git
+```
+
+**Options:**
+- `-t, --template <template>` - Template to use: `basic` or `fullstack` (default: `basic`)
+- `--no-install` - Skip npm install
+- `--no-git` - Skip git initialization
+
+### `zap dev`
+
+Start the development server with hot reload for both Rust and TypeScript.
+
+```bash
+zap dev
+zap dev --port 3000 --vite-port 5173
+zap dev --release --skip-build
+```
+
+**Options:**
+- `-p, --port <port>` - API server port (default: `3000`)
+- `--vite-port <port>` - Vite dev server port (default: `5173`)
+- `--no-open` - Don't open browser automatically
+- `-l, --log-level <level>` - Log level: `debug`, `info`, `warn`, `error` (default: `info`)
+- `--release` - Build Rust in release mode (slower build, faster runtime)
+- `--skip-build` - Skip initial Rust build (use existing binary)
+- `--binary-path <path>` - Path to pre-built zap binary
+- `--codegen-binary-path <path>` - Path to pre-built zap-codegen binary
+
+**Keyboard Shortcuts (during dev):**
+- `r` - Manually trigger Rust rebuild
+- `c` - Regenerate TypeScript bindings
+- `q` - Quit dev server
+- `Ctrl+C` - Stop server
+
+### `zap build`
+
+Build your application for production.
+
+```bash
+zap build
+zap build --output ./dist --target x86_64-unknown-linux-gnu
+zap build --skip-frontend
+```
+
+**Options:**
+- `--release` - Build optimized release (default: `true`)
+- `-o, --output <dir>` - Output directory (default: `./dist`)
+- `--target <target>` - Cross-compile target (e.g., `x86_64-unknown-linux-gnu`)
+- `--skip-frontend` - Skip Vite frontend build
+- `--skip-codegen` - Skip TypeScript binding generation
+
+**Output Structure:**
+```
+dist/
+├── bin/
+│   └── zap              # Rust binary
+├── static/              # Frontend assets (if built)
+├── config.json          # Production config
+└── manifest.json        # Build metadata
+```
+
+### `zap serve`
+
+Run the production server.
+
+```bash
+zap serve
+zap serve --port 8080 --host 0.0.0.0
+zap serve --config ./custom-config.json
+```
+
+**Options:**
+- `-p, --port <port>` - Server port
+- `--host <host>` - Host to bind to (default: `0.0.0.0`)
+- `-c, --config <path>` - Path to config file
+- `-w, --workers <count>` - Number of worker threads
+
+### `zap codegen`
+
+Generate TypeScript bindings from Rust exports.
+
+```bash
+zap codegen
+zap codegen --output ./src/api
+zap codegen --input ./metadata.json
+```
+
+**Options:**
+- `-i, --input <file>` - Input metadata JSON file
+- `-o, --output <dir>` - Output directory (default: `./src/api`)
+
+### `zap routes`
+
+Scan routes directory and display/generate route tree.
+
+```bash
+zap routes
+zap routes --routes-dir ./routes --output ./src/generated
+zap routes --json
+zap routes --verbose
+```
+
+**Options:**
+- `-d, --routes-dir <dir>` - Routes directory path
+- `-o, --output <dir>` - Output directory for generated files
+- `--json` - Output routes as JSON
+- `--verbose` - Show full handler code
+
+## Project Structure
+
+A typical ZapJS project structure:
+
+```
+my-app/
+├── routes/                    # File-based routing
+│   ├── __root.tsx            # Root layout
+│   ├── index.tsx             # Home page (/)
+│   ├── about.tsx             # About page (/about)
+│   ├── posts/
+│   │   ├── [id].tsx         # Dynamic route (/posts/:id)
+│   │   └── index.tsx        # Posts index (/posts)
+│   └── api/
+│       ├── hello.ts         # API route (/api/hello)
+│       └── users.$id.ts     # Dynamic API route (/api/users/:id)
+├── server/
+│   ├── src/
+│   │   └── main.rs          # Rust server entry point
+│   └── Cargo.toml           # Rust dependencies
+├── src/
+│   └── generated/           # Auto-generated files
+│       ├── routes.tsx       # Generated route tree
+│       └── routeManifest.json
+├── package.json
+├── Cargo.toml              # Workspace Cargo.toml
+├── tsconfig.json
+└── zap.config.ts           # Optional config
+```
+
+## Configuration
+
+### `zap.config.ts` (Optional)
+
+```typescript
+import { defineConfig } from 'zap';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+    hostname: '127.0.0.1',
+  },
+  dev: {
+    apiPort: 3000,
+    clientPort: 5173,
+    watchRust: true,
+    watchTypeScript: true,
+    open: true,
+  },
+});
+```
+
+## Routing Conventions
+
+### File-Based Routing
+
+ZapJS uses Next.js-style file-based routing:
+
+- `routes/index.tsx` → `/`
+- `routes/about.tsx` → `/about`
+- `routes/posts/[id].tsx` → `/posts/:id`
+- `routes/posts/[...slug].tsx` → `/posts/*` (catch-all)
+- `routes/__root.tsx` → Root layout wrapper
+- `routes/_layout.tsx` → Layout wrapper
+
+### API Routes
+
+TypeScript files in `routes/api/` become API endpoints:
+
+```typescript
+// routes/api/users.ts
+export const GET = async () => {
+  return { users: [] };
+};
+
+export const POST = async ({ request }: { request: Request }) => {
+  const body = await request.json();
+  return { created: body };
+};
+```
+
+**Supported Methods:** `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`
+
+### Dynamic Routes
+
+Use `[param]` or `$param` syntax for dynamic segments:
+
+```typescript
+// routes/api/users.$id.ts or routes/api/users/[id].ts
+export const GET = async ({ params }: { params: { id: string } }) => {
+  return { id: params.id };
+};
+```
+
+## Troubleshooting
+
+### `zap` command not found
+
+After installing globally, if `zap` is not found:
+
+1. Check npm global bin directory is in PATH:
+   ```bash
+   npm config get prefix
+   ```
+
+2. Add npm global bin to your PATH:
+   ```bash
+   # Add to ~/.bashrc or ~/.zshrc
+   export PATH="$(npm config get prefix)/bin:$PATH"
+   ```
+
+3. Verify installation:
+   ```bash
+   which zap
+   zap --version
+   ```
+
+### Development server won't start
+
+1. Ensure Rust is installed:
+   ```bash
+   rustc --version
+   cargo --version
+   ```
+
+2. Clean and rebuild:
+   ```bash
+   cargo clean
+   npm run build
+   zap dev
+   ```
+
+3. Check port availability:
+   ```bash
+   lsof -i :3000  # Check if port 3000 is in use
+   ```
+
+### TypeScript bindings not generating
+
+1. Ensure `zap-codegen` binary exists:
+   ```bash
+   cargo build --release --bin zap-codegen
+   ```
 
-- **File-based routing** with automatic route generation
-- **Nested layouts** with `_layout.tsx` files
-- **Route-level middleware** for auth and data preloading
-- **Zero-config development** with hot module reload
-- **TypeScript support** out of the box
-- **Production optimizations** built-in
+2. Manually run codegen:
+   ```bash
+   zap codegen
+   ```
 
-## Documentation
+## Links
 
-Full documentation available at [https://github.com/saint0x/zapjs](https://github.com/saint0x/zapjs)
+- [Documentation](https://github.com/yourusername/zapjs)
+- [Examples](https://github.com/yourusername/zapjs/tree/main/examples)
+- [Discord Community](https://discord.gg/zapjs)
+- [GitHub Issues](https://github.com/yourusername/zapjs/issues)
 
 ## License
 
-MIT
+MIT

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,11 @@
+export interface BuildOptions {
+    release?: boolean;
+    output?: string;
+    target?: string;
+    skipFrontend?: boolean;
+    skipCodegen?: boolean;
+}
+/**
+ * Build for production
+ */
+export declare function buildCommand(options: BuildOptions): Promise<void>;

package/dist/cli/commands/build.js

@@ -0,0 +1,282 @@
+import { execSync } from 'child_process';
+import { join, resolve } from 'path';
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, rmSync, writeFileSync } from 'fs';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Build for production
+ */
+export async function buildCommand(options) {
+    const outputDir = resolve(options.output || './dist');
+    const startTime = Date.now();
+    try {
+        cliLogger.header('ZapJS Production Build');
+        // Step 1: Generate TypeScript bindings first (needed for type checking)
+        if (!options.skipCodegen) {
+            await runCodegen();
+        }
+        // Step 2: TypeScript type checking (optional but recommended)
+        await typeCheck();
+        // Clean output directory
+        if (existsSync(outputDir)) {
+            cliLogger.spinner('clean', 'Cleaning output directory...');
+            rmSync(outputDir, { recursive: true, force: true });
+            cliLogger.succeedSpinner('clean', 'Output directory cleaned');
+        }
+        // Step 3: Build frontend first (if not skipped)
+        // Vite will create the dist/ directory and populate it
+        let staticDir = null;
+        if (!options.skipFrontend) {
+            staticDir = await buildFrontend(outputDir);
+        }
+        // Step 4: Create bin directory and build Rust binary
+        // This happens AFTER frontend build so Vite doesn't overwrite it
+        mkdirSync(join(outputDir, 'bin'), { recursive: true });
+        await buildRust(outputDir, options);
+        // Step 5: Create production config
+        await createProductionConfig(outputDir, staticDir);
+        // Step 6: Create build manifest
+        const manifest = createBuildManifest(outputDir, staticDir);
+        writeFileSync(join(outputDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        // Summary
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+        const binSize = getBinarySize(join(outputDir, 'bin', 'zap'));
+        cliLogger.newline();
+        cliLogger.success(`Build complete in ${elapsed}s`);
+        cliLogger.newline();
+        cliLogger.keyValue('Directory', outputDir);
+        cliLogger.keyValue('Binary', binSize);
+        if (staticDir) {
+            cliLogger.keyValue('Static', join(outputDir, 'static'));
+        }
+        cliLogger.newline();
+        cliLogger.command(`cd ${outputDir} && ./bin/zap`, 'Run in production');
+        cliLogger.newline();
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            cliLogger.error('Build failed', error);
+        }
+        process.exit(1);
+    }
+}
+async function buildRust(outputDir, options) {
+    cliLogger.spinner('rust', 'Building Rust backend (release mode)...');
+    const args = ['build', '--release', '--bin', 'zap'];
+    if (options.target) {
+        args.push('--target', options.target);
+    }
+    try {
+        execSync(`cargo ${args.join(' ')}`, {
+            cwd: process.cwd(),
+            stdio: 'inherit', // Show cargo output
+        });
+        const targetDir = options.target
+            ? join('target', options.target, 'release')
+            : join('target', 'release');
+        // Get the default Rust target for this platform
+        let defaultTarget = '';
+        try {
+            defaultTarget = execSync('rustc -vV | grep host | cut -d: -f2', {
+                stdio: 'pipe',
+                encoding: 'utf-8'
+            }).trim();
+        }
+        catch {
+            // Fallback targets based on platform
+            if (process.platform === 'darwin' && process.arch === 'arm64') {
+                defaultTarget = 'aarch64-apple-darwin';
+            }
+            else if (process.platform === 'darwin') {
+                defaultTarget = 'x86_64-apple-darwin';
+            }
+            else if (process.platform === 'linux') {
+                defaultTarget = 'x86_64-unknown-linux-gnu';
+            }
+        }
+        const platformTargetDir = defaultTarget
+            ? join('target', defaultTarget, 'release')
+            : targetDir;
+        // Try multiple locations for the binary (workspace vs local)
+        const possibleBinaryPaths = [
+            // Workspace target with platform-specific dir
+            join(process.cwd(), '..', platformTargetDir, 'zap'),
+            join(process.cwd(), '..', '..', platformTargetDir, 'zap'),
+            // Workspace target standard
+            join(process.cwd(), '..', targetDir, 'zap'),
+            join(process.cwd(), '..', '..', targetDir, 'zap'),
+            // Local target with platform-specific dir
+            join(process.cwd(), platformTargetDir, 'zap'),
+            // Local target standard
+            join(process.cwd(), targetDir, 'zap'),
+        ];
+        let srcBinary = null;
+        for (const path of possibleBinaryPaths) {
+            if (existsSync(path)) {
+                srcBinary = path;
+                break;
+            }
+        }
+        if (!srcBinary) {
+            throw new Error(`Binary not found. Checked:\n${possibleBinaryPaths.join('\n')}`);
+        }
+        const destBinary = join(outputDir, 'bin', 'zap');
+        copyFileSync(srcBinary, destBinary);
+        execSync(`chmod +x "${destBinary}"`, { stdio: 'pipe' });
+        cliLogger.succeedSpinner('rust', 'Rust backend built (release + LTO)');
+    }
+    catch (error) {
+        cliLogger.failSpinner('rust', 'Rust build failed');
+        throw error;
+    }
+}
+async function buildFrontend(outputDir) {
+    const viteConfig = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']
+        .find(f => existsSync(join(process.cwd(), f)));
+    if (!viteConfig) {
+        cliLogger.info('No Vite config found, skipping frontend build');
+        return null;
+    }
+    cliLogger.spinner('vite', 'Building frontend (Vite)...');
+    try {
+        // Build to a temporary directory to avoid conflicts
+        const tempDist = join(process.cwd(), '.dist-temp');
+        // Clean temp directory if it exists
+        if (existsSync(tempDist)) {
+            rmSync(tempDist, { recursive: true, force: true });
+        }
+        execSync(`npx vite build --outDir ${tempDist}`, {
+            cwd: process.cwd(),
+            stdio: 'pipe',
+        });
+        const staticDir = join(outputDir, 'static');
+        if (existsSync(tempDist)) {
+            copyDirectory(tempDist, staticDir);
+            // Clean up temp directory
+            rmSync(tempDist, { recursive: true, force: true });
+            cliLogger.succeedSpinner('vite', 'Frontend built and bundled');
+            return staticDir;
+        }
+        else {
+            cliLogger.warn('Vite build completed but no output found');
+            return null;
+        }
+    }
+    catch (error) {
+        cliLogger.failSpinner('vite', 'Frontend build failed');
+        cliLogger.warn('Continuing without frontend');
+        return null;
+    }
+}
+async function typeCheck() {
+    // Check if tsconfig exists
+    const tsconfigPath = join(process.cwd(), 'tsconfig.json');
+    if (!existsSync(tsconfigPath)) {
+        return; // Skip if no tsconfig
+    }
+    cliLogger.spinner('typecheck', 'Type checking TypeScript...');
+    try {
+        execSync('npx tsc --noEmit', {
+            cwd: process.cwd(),
+            stdio: 'pipe',
+        });
+        cliLogger.succeedSpinner('typecheck', 'TypeScript types OK');
+    }
+    catch (error) {
+        cliLogger.warn('TypeScript type check failed (continuing build)');
+        // Don't fail the build, just warn
+    }
+}
+async function runCodegen() {
+    const projectDir = process.cwd();
+    // Find codegen binary using same logic as codegen command
+    const possiblePaths = [
+        join(projectDir, 'bin', 'zap-codegen'),
+        join(projectDir, '../../target/release/zap-codegen'),
+        join(projectDir, '../../target/aarch64-apple-darwin/release/zap-codegen'),
+        join(projectDir, '../../target/x86_64-unknown-linux-gnu/release/zap-codegen'),
+        join(projectDir, 'target/release/zap-codegen'),
+    ];
+    let codegenBinary = null;
+    for (const path of possiblePaths) {
+        if (existsSync(path)) {
+            codegenBinary = path;
+            break;
+        }
+    }
+    // Try global zap-codegen as fallback
+    if (!codegenBinary) {
+        try {
+            execSync('which zap-codegen', { stdio: 'pipe' });
+            codegenBinary = 'zap-codegen';
+        }
+        catch {
+            cliLogger.info('Codegen skipped (binary not found)');
+            return;
+        }
+    }
+    cliLogger.spinner('codegen', 'Generating TypeScript bindings...');
+    try {
+        execSync(`"${codegenBinary}" --output-dir ./src/api`, {
+            cwd: process.cwd(),
+            stdio: 'pipe',
+        });
+        cliLogger.succeedSpinner('codegen', 'TypeScript bindings generated');
+    }
+    catch (error) {
+        cliLogger.warn('Codegen failed (continuing build)');
+    }
+}
+async function createProductionConfig(outputDir, staticDir) {
+    const config = {
+        server: {
+            host: '0.0.0.0',
+            port: 3000,
+        },
+        static: staticDir ? {
+            prefix: '/',
+            directory: './static',
+        } : null,
+        logging: {
+            level: 'info',
+            format: 'json',
+        },
+    };
+    writeFileSync(join(outputDir, 'config.json'), JSON.stringify(config, null, 2));
+}
+function createBuildManifest(outputDir, staticDir) {
+    return {
+        version: '1.0.0',
+        buildTime: new Date().toISOString(),
+        rustBinary: './bin/zap',
+        staticDir: staticDir ? './static' : null,
+        env: 'production',
+    };
+}
+function copyDirectory(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirectory(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+function getBinarySize(path) {
+    try {
+        const stats = statSync(path);
+        const bytes = stats.size;
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/cli/commands/codegen.d.ts

@@ -0,0 +1,8 @@
+export interface CodegenOptions {
+    input?: string;
+    output?: string;
+}
+/**
+ * Generate TypeScript bindings from Rust exports
+ */
+export declare function codegenCommand(options: CodegenOptions): Promise<void>;