@solcreek/cli 0.3.1 → 0.3.3

package/dist/commands/dev.d.ts

@@ -0,0 +1,22 @@
+export declare const devCommand: import("citty").CommandDef<{
+    port: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    reset: {
+        type: "boolean";
+        description: string;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+    yes: {
+        type: "boolean";
+        description: string;
+        default: boolean;
+    };
+}>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.js

@@ -0,0 +1,63 @@
+import { defineCommand } from "citty";
+import { consola } from "consola";
+import { resolveConfig, formatDetectionSummary } from "@solcreek/sdk";
+import { globalArgs } from "../utils/output.js";
+import { DevServer } from "../dev/server.js";
+export const devCommand = defineCommand({
+    meta: {
+        name: "dev",
+        description: "Start local development server",
+    },
+    args: {
+        ...globalArgs,
+        port: {
+            type: "string",
+            description: "Port number (default: 3000)",
+            default: "3000",
+        },
+        reset: {
+            type: "boolean",
+            description: "Clear local data before starting",
+        },
+    },
+    async run({ args }) {
+        const cwd = process.cwd();
+        let config;
+        try {
+            config = resolveConfig(cwd);
+        }
+        catch (e) {
+            consola.error(e.message);
+            process.exit(1);
+        }
+        const port = parseInt(args.port, 10);
+        if (isNaN(port) || port < 0 || port > 65535) {
+            consola.error(`Invalid port: ${args.port}`);
+            process.exit(1);
+        }
+        consola.info(`Detected: ${formatDetectionSummary(config)}`);
+        const server = new DevServer({
+            cwd,
+            port,
+            config,
+            reset: !!args.reset,
+        });
+        // Graceful shutdown
+        const shutdown = async () => {
+            consola.info("Shutting down...");
+            await server.stop();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        try {
+            await server.start();
+        }
+        catch (e) {
+            consola.error(`Failed to start dev server: ${e.message}`);
+            await server.stop();
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=dev.js.map

package/dist/dev/dev-proxy.d.ts

@@ -0,0 +1,26 @@
+import { type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { type LocalRealtimeServer } from "./local-realtime.js";
+type ConnectServer = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+export interface DevProxyOptions {
+    /** User-facing port. */
+    port: number;
+    /** Miniflare worker URL (e.g. "http://127.0.0.1:8787"). Null if no worker. */
+    workerUrl: string | null;
+    /** Vite middleware. Null if no Vite (worker-only project). */
+    viteMiddleware: ConnectServer | null;
+    /** Local realtime server instance. */
+    realtimeServer: LocalRealtimeServer;
+    /** Project slug. */
+    projectSlug: string;
+}
+export declare class DevProxy {
+    private server;
+    private options;
+    constructor(options: DevProxyOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Get the underlying HTTP server (for Vite HMR upgrade). */
+    getServer(): Server | null;
+}
+export {};
+//# sourceMappingURL=dev-proxy.d.ts.map

package/dist/dev/dev-proxy.js

@@ -0,0 +1,134 @@
+// Dev proxy server for `creek dev`.
+//
+// Single user-facing HTTP server that routes:
+//   /__creek/config       → local config response
+//   /{slug}/**/broadcast  → realtime server (HTTP)
+//   /{slug}/**/ws         → realtime server (WebSocket upgrade)
+//   /api/*, /__creek/*    → worker (Miniflare)
+//   everything else       → Vite (HMR) or worker (if no Vite)
+import { createServer, request as httpRequest, } from "node:http";
+import { parseRealtimePath, } from "./local-realtime.js";
+export class DevProxy {
+    server = null;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        const { port, workerUrl, viteMiddleware, realtimeServer, projectSlug } = this.options;
+        this.server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+            // 1. /__creek/config → local config
+            if (url.pathname === "/__creek/config" && req.method === "GET") {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    realtimeUrl: `http://localhost:${port}`,
+                    projectSlug,
+                    wsToken: null,
+                }));
+                return;
+            }
+            // 2. Realtime broadcast: POST /{slug}/**/broadcast
+            const route = parseRealtimePath(url.pathname);
+            if (route && route.action === "/broadcast" && req.method === "POST") {
+                realtimeServer.handleBroadcast(req, res);
+                return;
+            }
+            // 3. Realtime status: GET /{slug}/**/status
+            if (route && route.action === "/status" && req.method === "GET") {
+                realtimeServer.handleStatus(req, res);
+                return;
+            }
+            // 4. API/worker routes → proxy to Miniflare
+            if (workerUrl && isWorkerRoute(url.pathname)) {
+                proxyToWorker(req, res, workerUrl);
+                return;
+            }
+            // 5. Everything else → Vite middleware or worker fallback
+            if (viteMiddleware) {
+                viteMiddleware(req, res, () => {
+                    // If Vite doesn't handle it and we have a worker, try worker
+                    if (workerUrl) {
+                        proxyToWorker(req, res, workerUrl);
+                    }
+                    else {
+                        res.writeHead(404);
+                        res.end("Not Found");
+                    }
+                });
+                return;
+            }
+            // No Vite — all traffic to worker
+            if (workerUrl) {
+                proxyToWorker(req, res, workerUrl);
+                return;
+            }
+            res.writeHead(404);
+            res.end("Not Found");
+        });
+        // WebSocket upgrade routing
+        this.server.on("upgrade", (req, socket, head) => {
+            const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+            const route = parseRealtimePath(url.pathname);
+            // Realtime WebSocket: /{slug}/**/ws
+            if (route && route.action === "/ws") {
+                realtimeServer.handleUpgrade(req, socket, head);
+                return;
+            }
+            // Vite HMR WebSocket — pass through to Vite middleware
+            if (viteMiddleware) {
+                // Vite's middleware handles WebSocket upgrades via the http server's
+                // upgrade event. We need to let Vite handle it. Vite listens on the
+                // same server's upgrade event, so we should NOT destroy the socket.
+                // The Vite server is in middleware mode and registered its own
+                // upgrade handler already. We just don't interfere.
+                return;
+            }
+            socket.destroy();
+        });
+        return new Promise((resolve, reject) => {
+            this.server.on("error", reject);
+            this.server.listen(port, "127.0.0.1", () => resolve());
+        });
+    }
+    async stop() {
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => resolve());
+                this.server = null;
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /** Get the underlying HTTP server (for Vite HMR upgrade). */
+    getServer() {
+        return this.server;
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function isWorkerRoute(pathname) {
+    return (pathname.startsWith("/api/") ||
+        pathname.startsWith("/__creek/") ||
+        pathname === "/__creek");
+}
+function proxyToWorker(req, res, workerUrl) {
+    const { hostname, port } = new URL(workerUrl);
+    const proxyReq = httpRequest({
+        hostname,
+        port,
+        path: req.url,
+        method: req.method,
+        headers: req.headers,
+    }, (proxyRes) => {
+        res.writeHead(proxyRes.statusCode ?? 200, proxyRes.headers);
+        proxyRes.pipe(res);
+    });
+    proxyReq.on("error", () => {
+        res.writeHead(502);
+        res.end("Worker unavailable");
+    });
+    req.pipe(proxyReq);
+}
+//# sourceMappingURL=dev-proxy.js.map

package/dist/dev/local-realtime.d.ts

@@ -0,0 +1,40 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { WebSocket } from "ws";
+export interface RealtimeRoute {
+    slug: string;
+    roomId: string | null;
+    action: string;
+}
+export declare function parseRealtimePath(pathname: string): RealtimeRoute | null;
+export declare function getDoName(route: RealtimeRoute): string;
+export declare class LocalRealtimeServer {
+    private httpServer;
+    private wss;
+    private rooms;
+    private port;
+    constructor(options?: {
+        port?: number;
+    });
+    start(): Promise<{
+        port: number;
+    }>;
+    stop(): Promise<void>;
+    /** Broadcast a message to all connected clients in a room. */
+    broadcast(roomKey: string, message: object): void;
+    /** Get the number of connected clients in a room. */
+    getRoomCount(roomKey: string): number;
+    /** Get the port the server is listening on. */
+    getPort(): number;
+    /** @internal — inject a mock WebSocket into a room for testing. */
+    _testAddSocket(roomKey: string, ws: WebSocket): void;
+    /** Handle WebSocket upgrade from an external HTTP server. */
+    handleUpgrade(req: IncomingMessage, socket: import("node:net").Socket, head: Buffer): void;
+    /** Handle broadcast POST from an external HTTP server. */
+    handleBroadcast(req: IncomingMessage, res: ServerResponse): void;
+    /** Handle status GET from an external HTTP server. */
+    handleStatus(req: IncomingMessage, res: ServerResponse): void;
+    private addToRoom;
+    private broadcastPeers;
+    private handleHttp;
+}
+//# sourceMappingURL=local-realtime.d.ts.map

package/dist/dev/local-realtime.js

@@ -0,0 +1,242 @@
+// Local realtime server for `creek dev`.
+//
+// Replaces the production Durable Object realtime service (rt.creek.dev)
+// with a lightweight Node.js WebSocket server. Same URL routing and
+// message format — client code works unchanged.
+import { createServer, } from "node:http";
+import { WebSocketServer, WebSocket } from "ws";
+const VALID_ACTIONS = new Set(["/broadcast", "/ws", "/status"]);
+export function parseRealtimePath(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return null;
+    const slug = parts[0];
+    // Room-scoped: /{slug}/rooms/{roomId}/{action}
+    if (parts[1] === "rooms") {
+        if (parts.length < 4)
+            return null;
+        const roomId = parts[2];
+        const action = "/" + parts[3];
+        if (!VALID_ACTIONS.has(action))
+            return null;
+        if (!roomId)
+            return null;
+        return { slug, roomId, action };
+    }
+    // Project-wide (legacy): /{slug}/{action}
+    const action = "/" + parts.slice(1).join("/");
+    if (!VALID_ACTIONS.has(action))
+        return null;
+    return { slug, roomId: null, action };
+}
+export function getDoName(route) {
+    return route.roomId ? `${route.slug}:${route.roomId}` : route.slug;
+}
+// ─── LocalRealtimeServer ──────────────────────────────────────────────────────
+export class LocalRealtimeServer {
+    httpServer = null;
+    wss = null;
+    rooms = new Map();
+    port;
+    constructor(options) {
+        this.port = options?.port ?? 0; // 0 = OS auto-assign
+    }
+    async start() {
+        this.httpServer = createServer((req, res) => this.handleHttp(req, res));
+        this.wss = new WebSocketServer({ noServer: true });
+        this.httpServer.on("upgrade", (req, socket, head) => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            const route = parseRealtimePath(url.pathname);
+            if (!route || route.action !== "/ws") {
+                socket.destroy();
+                return;
+            }
+            this.wss.handleUpgrade(req, socket, head, (ws) => {
+                const roomKey = getDoName(route);
+                this.addToRoom(roomKey, ws);
+            });
+        });
+        return new Promise((resolve, reject) => {
+            this.httpServer.on("error", reject);
+            this.httpServer.listen(this.port, "127.0.0.1", () => {
+                const addr = this.httpServer.address();
+                if (typeof addr === "object" && addr) {
+                    this.port = addr.port;
+                }
+                resolve({ port: this.port });
+            });
+        });
+    }
+    async stop() {
+        // Close all WebSocket connections
+        for (const [, room] of this.rooms) {
+            for (const ws of room) {
+                ws.close(1001, "Server shutting down");
+            }
+        }
+        this.rooms.clear();
+        // Close WebSocket server
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+        }
+        // Close HTTP server
+        return new Promise((resolve) => {
+            if (this.httpServer) {
+                this.httpServer.close(() => resolve());
+                this.httpServer = null;
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /** Broadcast a message to all connected clients in a room. */
+    broadcast(roomKey, message) {
+        const room = this.rooms.get(roomKey);
+        if (!room)
+            return;
+        const data = JSON.stringify(message);
+        for (const ws of room) {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(data);
+            }
+        }
+    }
+    /** Get the number of connected clients in a room. */
+    getRoomCount(roomKey) {
+        return this.rooms.get(roomKey)?.size ?? 0;
+    }
+    /** Get the port the server is listening on. */
+    getPort() {
+        return this.port;
+    }
+    /** @internal — inject a mock WebSocket into a room for testing. */
+    _testAddSocket(roomKey, ws) {
+        let room = this.rooms.get(roomKey);
+        if (!room) {
+            room = new Set();
+            this.rooms.set(roomKey, room);
+        }
+        room.add(ws);
+    }
+    // ─── Public handlers (for DevProxy integration) ────────────────────────────
+    /** Handle WebSocket upgrade from an external HTTP server. */
+    handleUpgrade(req, socket, head) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const route = parseRealtimePath(url.pathname);
+        if (!route || route.action !== "/ws") {
+            socket.destroy();
+            return;
+        }
+        if (!this.wss) {
+            // Lazy-init WSS if server not started standalone
+            this.wss = new WebSocketServer({ noServer: true });
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => {
+            const roomKey = getDoName(route);
+            this.addToRoom(roomKey, ws);
+        });
+    }
+    /** Handle broadcast POST from an external HTTP server. */
+    handleBroadcast(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const route = parseRealtimePath(url.pathname);
+        if (!route || route.action !== "/broadcast" || req.method !== "POST") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not Found" }));
+            return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            let event;
+            try {
+                event = JSON.parse(body);
+            }
+            catch {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid JSON" }));
+                return;
+            }
+            const roomKey = getDoName(route);
+            this.broadcast(roomKey, {
+                type: "db_changed",
+                table: event.table ?? "unknown",
+                operation: event.operation ?? "UNKNOWN",
+            });
+            const count = this.rooms.get(roomKey)?.size ?? 0;
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true, clients: count }));
+        });
+    }
+    /** Handle status GET from an external HTTP server. */
+    handleStatus(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const route = parseRealtimePath(url.pathname);
+        if (!route) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not Found" }));
+            return;
+        }
+        const roomKey = getDoName(route);
+        const count = this.rooms.get(roomKey)?.size ?? 0;
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ clients: count }));
+    }
+    // ─── Internal ───────────────────────────────────────────────────────────────
+    addToRoom(roomKey, ws) {
+        let room = this.rooms.get(roomKey);
+        if (!room) {
+            room = new Set();
+            this.rooms.set(roomKey, room);
+        }
+        room.add(ws);
+        this.broadcastPeers(roomKey);
+        ws.on("close", () => {
+            room.delete(ws);
+            if (room.size === 0)
+                this.rooms.delete(roomKey);
+            this.broadcastPeers(roomKey);
+        });
+        ws.on("error", () => {
+            room.delete(ws);
+            if (room.size === 0)
+                this.rooms.delete(roomKey);
+            this.broadcastPeers(roomKey);
+        });
+    }
+    broadcastPeers(roomKey) {
+        const count = this.rooms.get(roomKey)?.size ?? 0;
+        this.broadcast(roomKey, { type: "peers", count });
+    }
+    handleHttp(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        // Root health check
+        if (url.pathname === "/" || url.pathname === "") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ service: "creek-realtime-local", status: "ok" }));
+            return;
+        }
+        const route = parseRealtimePath(url.pathname);
+        if (!route) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not Found" }));
+            return;
+        }
+        // Delegate to public handlers
+        if (route.action === "/broadcast" && req.method === "POST") {
+            this.handleBroadcast(req, res);
+            return;
+        }
+        if (route.action === "/status" && req.method === "GET") {
+            this.handleStatus(req, res);
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not Found" }));
+    }
+}
+//# sourceMappingURL=local-realtime.js.map

package/dist/dev/ports.d.ts

@@ -0,0 +1,5 @@
+/** Check if a port is available on localhost. */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/** Find an available port, starting from the preferred port. */
+export declare function findAvailablePort(preferred?: number): Promise<number>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/dev/ports.js

@@ -0,0 +1,34 @@
+// Port allocation utilities for `creek dev`.
+import { createServer } from "node:net";
+/** Check if a port is available on localhost. */
+export function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/** Find an available port, starting from the preferred port. */
+export async function findAvailablePort(preferred = 3000) {
+    if (await isPortAvailable(preferred))
+        return preferred;
+    // Try a few ports around the preferred one
+    for (let offset = 1; offset <= 10; offset++) {
+        const port = preferred + offset;
+        if (await isPortAvailable(port))
+            return port;
+    }
+    // Fall back to OS-assigned port
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+//# sourceMappingURL=ports.js.map

package/dist/dev/server.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedConfig } from "@solcreek/sdk";
+export interface DevServerOptions {
+    cwd: string;
+    port: number;
+    config: ResolvedConfig;
+    reset: boolean;
+}
+export declare class DevServer {
+    private options;
+    private realtimeServer;
+    private workerRunner;
+    private viteBridge;
+    private proxy;
+    constructor(options: DevServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/dev/server.js

@@ -0,0 +1,143 @@
+// DevServer orchestrator for `creek dev`.
+//
+// Manages the lifecycle of all subsystems:
+//   1. LocalRealtimeServer — WebSocket broadcast
+//   2. WorkerRunner — Miniflare with D1/KV/R2
+//   3. ViteBridge — Client-side HMR
+//   4. DevProxy — User-facing HTTP server
+import { existsSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { consola } from "consola";
+import { LocalRealtimeServer } from "./local-realtime.js";
+import { WorkerRunner } from "./worker-runner.js";
+import { ViteBridge } from "./vite-bridge.js";
+import { DevProxy } from "./dev-proxy.js";
+import { findAvailablePort } from "./ports.js";
+export class DevServer {
+    options;
+    realtimeServer = null;
+    workerRunner = null;
+    viteBridge = null;
+    proxy = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        const { cwd, port, config, reset } = this.options;
+        const persistDir = join(cwd, ".creek", "dev");
+        const startTime = Date.now();
+        // 1. Handle --reset
+        if (reset && existsSync(persistDir)) {
+            rmSync(persistDir, { recursive: true, force: true });
+            consola.info("Cleared local data");
+        }
+        // Create persistence directory
+        mkdirSync(persistDir, { recursive: true });
+        // 2. Start realtime server
+        this.realtimeServer = new LocalRealtimeServer({ port: 0 });
+        await this.realtimeServer.start();
+        // 3. Start worker (if project has a worker entry)
+        let workerUrl = null;
+        if (config.workerEntry) {
+            this.workerRunner = new WorkerRunner({
+                entryPoint: config.workerEntry,
+                cwd,
+                bindings: config.bindings,
+                persistDir,
+                realtimeUrl: `http://127.0.0.1:${this.realtimeServer.getPort()}`,
+                projectSlug: config.projectName,
+                vars: config.vars,
+                onRebuild: (ms) => {
+                    consola.info(`Worker rebuilt in ${ms}ms`);
+                },
+            });
+            const { port: workerPort } = await this.workerRunner.start();
+            workerUrl = `http://127.0.0.1:${workerPort}`;
+        }
+        // 4. Start Vite (if project has a frontend framework)
+        let viteMiddleware = null;
+        const hasFramework = config.framework !== null;
+        if (hasFramework) {
+            this.viteBridge = new ViteBridge({ cwd });
+            try {
+                await this.viteBridge.start();
+                viteMiddleware = this.viteBridge.middlewares;
+            }
+            catch (e) {
+                if (e.message?.includes("Vite is not installed")) {
+                    consola.warn(e.message);
+                    this.viteBridge = null;
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        // 5. Resolve port (auto-find if occupied)
+        const actualPort = await findAvailablePort(port);
+        if (actualPort !== port) {
+            consola.warn(`Port ${port} is in use, using ${actualPort} instead`);
+        }
+        // 6. Start proxy
+        this.proxy = new DevProxy({
+            port: actualPort,
+            workerUrl,
+            viteMiddleware,
+            realtimeServer: this.realtimeServer,
+            projectSlug: config.projectName,
+        });
+        await this.proxy.start();
+        // 7. Wire Vite's HMR to the proxy's HTTP server
+        if (this.viteBridge && this.proxy.getServer()) {
+            const httpServer = this.proxy.getServer();
+            // Vite's middleware mode needs to handle upgrade events
+            // from our proxy server for HMR WebSocket
+            const viteWss = this.viteBridge.viteServer?.ws;
+            if (viteWss) {
+                httpServer.on("upgrade", (req, socket, head) => {
+                    // Only handle Vite's HMR paths
+                    if (req.url?.startsWith("/__vite") ||
+                        req.url?.startsWith("/@vite")) {
+                        viteWss.handleUpgrade(req, socket, head);
+                    }
+                });
+            }
+        }
+        // 8. Print status
+        const elapsed = Date.now() - startTime;
+        const bindings = config.bindings
+            .filter((b) => ["d1", "kv", "r2", "ai"].includes(b.type))
+            .map((b) => b.type.toUpperCase());
+        const bindingStr = bindings.length > 0 ? ` (${bindings.join(", ")})` : "";
+        console.log("");
+        consola.success(`creek dev\n`);
+        consola.info(`App:       http://localhost:${actualPort}`);
+        if (config.workerEntry) {
+            consola.info(`Worker:    ${config.workerEntry}${bindingStr}`);
+        }
+        consola.info(`Realtime:  ws://localhost:${actualPort}`);
+        consola.info(`Data:      .creek/dev/`);
+        console.log("");
+        consola.success(`Ready in ${elapsed}ms`);
+    }
+    async stop() {
+        // Stop in reverse order
+        if (this.proxy) {
+            await this.proxy.stop();
+            this.proxy = null;
+        }
+        if (this.viteBridge) {
+            await this.viteBridge.stop();
+            this.viteBridge = null;
+        }
+        if (this.workerRunner) {
+            await this.workerRunner.stop();
+            this.workerRunner = null;
+        }
+        if (this.realtimeServer) {
+            await this.realtimeServer.stop();
+            this.realtimeServer = null;
+        }
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/dev/vite-bridge.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+type ConnectMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+export declare class ViteBridge {
+    private viteServer;
+    private cwd;
+    constructor(options: {
+        cwd: string;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Vite's Connect middleware stack — plug into the proxy server. */
+    get middlewares(): ConnectMiddleware;
+}
+export {};
+//# sourceMappingURL=vite-bridge.d.ts.map

package/dist/dev/vite-bridge.js

@@ -0,0 +1,42 @@
+// Vite dev server integration for `creek dev`.
+//
+// Uses Vite's middleware mode — no separate HTTP server.
+// HMR WebSocket is handled through Vite's own middleware.
+export class ViteBridge {
+    viteServer = null; // ViteDevServer — dynamically imported
+    cwd;
+    constructor(options) {
+        this.cwd = options.cwd;
+    }
+    async start() {
+        let vite;
+        try {
+            vite = await import("vite");
+        }
+        catch {
+            throw new Error("[creek dev] Vite is not installed. Run `npm install -D vite` to enable client-side HMR.");
+        }
+        this.viteServer = await vite.createServer({
+            root: this.cwd,
+            server: {
+                middlewareMode: true,
+                hmr: true,
+            },
+            appType: "spa",
+        });
+    }
+    async stop() {
+        if (this.viteServer) {
+            await this.viteServer.close();
+            this.viteServer = null;
+        }
+    }
+    /** Vite's Connect middleware stack — plug into the proxy server. */
+    get middlewares() {
+        if (!this.viteServer) {
+            throw new Error("ViteBridge not started");
+        }
+        return this.viteServer.middlewares;
+    }
+}
+//# sourceMappingURL=vite-bridge.js.map

package/dist/dev/worker-runner.d.ts

@@ -0,0 +1,61 @@
+import type { BindingDeclaration } from "@solcreek/sdk";
+export interface WorkerRunnerOptions {
+    /** User's worker entry point (e.g. "worker/index.ts"). */
+    entryPoint: string;
+    /** Project root directory. */
+    cwd: string;
+    /** Declared bindings from creek.toml / wrangler config. */
+    bindings: BindingDeclaration[];
+    /** Persistence directory for D1/KV/R2 data. */
+    persistDir: string;
+    /** Local realtime server URL (e.g. "http://localhost:8788"). */
+    realtimeUrl: string;
+    /** Project slug (e.g. "realtime-todos"). */
+    projectSlug: string;
+    /** User-defined environment variables from config. */
+    vars?: Record<string, string>;
+    /** Whether the project has client assets (Worker + SPA hybrid). */
+    hasClientAssets?: boolean;
+    /** Callback when worker is rebuilt. */
+    onRebuild?: (durationMs: number) => void;
+    /**
+     * Additional node module resolution paths for esbuild.
+     * @internal — used by tests to resolve `creek` from monorepo.
+     */
+    nodePaths?: string[];
+}
+export declare class WorkerRunner {
+    private mf;
+    private esbuildCtx;
+    private options;
+    private mfOptions;
+    private port;
+    constructor(options: WorkerRunnerOptions);
+    start(): Promise<{
+        port: number;
+    }>;
+    stop(): Promise<void>;
+    /** Get the URL the worker is running on. */
+    getUrl(): string;
+    /** Get the port the worker is running on. */
+    getPort(): number;
+    /** Dispatch a fetch request to the worker (via Miniflare). */
+    dispatchFetch(input: string, init?: RequestInit): Promise<Response>;
+    private buildMiniflareOptions;
+    private get esbuildOptions();
+    private bundle;
+    private startWatching;
+}
+/**
+ * Build Miniflare options from bindings — extracted for testing.
+ * @internal
+ */
+export declare function buildMiniflareBindingOptions(bindings: BindingDeclaration[]): {
+    hasD1: boolean;
+    hasKV: boolean;
+    hasR2: boolean;
+    d1BindingName: string;
+    kvBindingName: string;
+    r2BindingName: string;
+};
+//# sourceMappingURL=worker-runner.d.ts.map

package/dist/dev/worker-runner.js

@@ -0,0 +1,203 @@
+// Worker execution for `creek dev` — bundles user code and runs it via Miniflare.
+//
+// Uses esbuild watch mode for hot reload and Miniflare for D1/KV/R2 simulation.
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { context } from "esbuild";
+import { Miniflare } from "miniflare";
+import { generateWorkerWrapper } from "../utils/worker-bundle.js";
+const NODE_BUILTINS = [
+    "node:async_hooks",
+    "node:stream",
+    "node:stream/web",
+    "node:buffer",
+    "node:util",
+    "node:events",
+    "node:crypto",
+    "node:path",
+    "node:url",
+    "node:string_decoder",
+    "node:diagnostics_channel",
+    "node:process",
+    "node:fs",
+    "node:os",
+    "node:child_process",
+    "node:http",
+    "node:https",
+    "node:net",
+    "node:tls",
+    "node:zlib",
+    "node:perf_hooks",
+    "node:worker_threads",
+];
+export class WorkerRunner {
+    mf = null;
+    esbuildCtx = null;
+    options;
+    mfOptions = {};
+    port = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        const { cwd, entryPoint, persistDir } = this.options;
+        // 1. Generate worker wrapper
+        const wrapperDir = join(cwd, ".creek", "dev");
+        mkdirSync(wrapperDir, { recursive: true });
+        const entryAbsolute = resolve(cwd, entryPoint);
+        const wrapper = generateWorkerWrapper(entryAbsolute, wrapperDir, {
+            hasClientAssets: this.options.hasClientAssets,
+        });
+        const wrapperPath = join(wrapperDir, "__worker_entry.js");
+        writeFileSync(wrapperPath, wrapper);
+        // 2. Initial bundle with esbuild
+        const bundledScript = await this.bundle(wrapperPath);
+        // 3. Start Miniflare
+        this.mfOptions = this.buildMiniflareOptions(bundledScript, persistDir);
+        this.mf = new Miniflare(this.mfOptions);
+        // Wait for Miniflare to be ready and get the port
+        const readyUrl = await this.mf.ready;
+        // mf.ready returns a URL object
+        this.port = readyUrl.port ? parseInt(String(readyUrl.port), 10) : 8787;
+        // 4. Start esbuild watch mode for hot reload
+        await this.startWatching(wrapperPath);
+        return { port: this.port };
+    }
+    async stop() {
+        if (this.esbuildCtx) {
+            await this.esbuildCtx.dispose();
+            this.esbuildCtx = null;
+        }
+        if (this.mf) {
+            await this.mf.dispose();
+            this.mf = null;
+        }
+    }
+    /** Get the URL the worker is running on. */
+    getUrl() {
+        return `http://127.0.0.1:${this.port}`;
+    }
+    /** Get the port the worker is running on. */
+    getPort() {
+        return this.port;
+    }
+    /** Dispatch a fetch request to the worker (via Miniflare). */
+    async dispatchFetch(input, init) {
+        if (!this.mf)
+            throw new Error("WorkerRunner not started");
+        return this.mf.dispatchFetch(input, init);
+    }
+    // ─── Internal ───────────────────────────────────────────────────────────────
+    buildMiniflareOptions(script, persistDir) {
+        const { bindings, projectSlug, realtimeUrl, vars } = this.options;
+        const hasD1 = bindings.some((b) => b.type === "d1");
+        const hasKV = bindings.some((b) => b.type === "kv");
+        const hasR2 = bindings.some((b) => b.type === "r2");
+        const d1BindingName = bindings.find((b) => b.type === "d1")?.name ?? "DB";
+        const kvBindingName = bindings.find((b) => b.type === "kv")?.name ?? "KV";
+        const r2BindingName = bindings.find((b) => b.type === "r2")?.name ?? "STORAGE";
+        const opts = {
+            modules: true,
+            script,
+            compatibilityDate: "2024-12-01",
+            compatibilityFlags: ["nodejs_compat"],
+            // Environment variables
+            bindings: {
+                CREEK_PROJECT_SLUG: projectSlug,
+                CREEK_REALTIME_URL: realtimeUrl,
+                // CREEK_REALTIME_SECRET intentionally omitted (dev mode = no auth)
+                ...vars,
+            },
+        };
+        // D1 — SQLite-backed
+        if (hasD1) {
+            opts.d1Databases = { [d1BindingName]: "creek-dev-db" };
+            opts.d1Persist = persistDir ? join(persistDir, "d1") : false;
+        }
+        // KV
+        if (hasKV) {
+            opts.kvNamespaces = { [kvBindingName]: "creek-dev-kv" };
+            opts.kvPersist = persistDir ? join(persistDir, "kv") : false;
+        }
+        // R2
+        if (hasR2) {
+            opts.r2Buckets = { [r2BindingName]: "creek-dev-r2" };
+            opts.r2Persist = persistDir ? join(persistDir, "r2") : false;
+        }
+        return opts;
+    }
+    get esbuildOptions() {
+        return {
+            absWorkingDir: this.options.cwd,
+            bundle: true,
+            format: "esm",
+            platform: "neutral",
+            target: "es2022",
+            write: false,
+            minify: false,
+            external: NODE_BUILTINS,
+            conditions: ["workerd", "worker", "import"],
+            mainFields: ["module", "main"],
+            logLevel: "warning",
+            ...(this.options.nodePaths?.length
+                ? { nodePaths: this.options.nodePaths }
+                : {}),
+        };
+    }
+    async bundle(entryPoint) {
+        const result = await import("esbuild").then((esbuild) => esbuild.build({
+            entryPoints: [entryPoint],
+            ...this.esbuildOptions,
+        }));
+        if (result.errors.length > 0) {
+            throw new Error(`esbuild: ${result.errors.map((e) => e.text).join(", ")}`);
+        }
+        return result.outputFiles[0].text;
+    }
+    async startWatching(entryPoint) {
+        this.esbuildCtx = await context({
+            entryPoints: [entryPoint],
+            ...this.esbuildOptions,
+            plugins: [
+                {
+                    name: "creek-hot-reload",
+                    setup: (build) => {
+                        build.onEnd(async (result) => {
+                            if (result.errors.length > 0 || !result.outputFiles?.length) {
+                                return;
+                            }
+                            const start = Date.now();
+                            const newScript = result.outputFiles[0].text;
+                            try {
+                                await this.mf?.setOptions({
+                                    ...this.mfOptions,
+                                    script: newScript,
+                                });
+                                this.options.onRebuild?.(Date.now() - start);
+                            }
+                            catch {
+                                // Reload failed — keep running with old version
+                            }
+                        });
+                    },
+                },
+            ],
+        });
+        await this.esbuildCtx.watch();
+    }
+}
+/**
+ * Build Miniflare options from bindings — extracted for testing.
+ * @internal
+ */
+export function buildMiniflareBindingOptions(bindings) {
+    return {
+        hasD1: bindings.some((b) => b.type === "d1"),
+        hasKV: bindings.some((b) => b.type === "kv"),
+        hasR2: bindings.some((b) => b.type === "r2"),
+        d1BindingName: bindings.find((b) => b.type === "d1")?.name ?? "DB",
+        kvBindingName: bindings.find((b) => b.type === "kv")?.name ?? "KV",
+        r2BindingName: bindings.find((b) => b.type === "r2")?.name ?? "STORAGE",
+    };
+}
+//# sourceMappingURL=worker-runner.js.map

package/dist/index.js

@@ -3,6 +3,7 @@ import { defineCommand, runMain } from "citty";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
 import { loginCommand } from "./commands/login.js";
 import { whoamiCommand } from "./commands/whoami.js";
 import { initCommand } from "./commands/init.js";
@@ -13,15 +14,28 @@ import { domainsCommand } from "./commands/domains.js";
 import { projectsCommand } from "./commands/projects.js";
 import { deploymentsCommand } from "./commands/deployments.js";
 import { statusCommand } from "./commands/status.js";
+import { devCommand } from "./commands/dev.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const cliPkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+// Read version from the "creek" facade package (what users install),
+// falling back to CLI's own version if not available.
+let version = cliPkg.version;
+try {
+    const require = createRequire(import.meta.url);
+    const facadePkg = require("creek/package.json");
+    version = facadePkg.version;
+}
+catch {
+    // Running outside facade (e.g. workspace dev) — use CLI version
+}
 const main = defineCommand({
     meta: {
         name: "creek",
-        version: pkg.version,
+        version,
         description: "Deploy full-stack apps to the edge",
     },
     subCommands: {
+        dev: devCommand,
         deploy: deployCommand,
         status: statusCommand,
         projects: projectsCommand,

package/dist/utils/worker-bundle.js

@@ -23,7 +23,7 @@ export function generateWorkerWrapper(entryPoint, wrapperDir, options) {
     // - Fall back to the worker handler for API routes
     // - SPA fallback: serve index.html for extensionless paths
     if (hasAssets) {
-        return `import { _setEnv, _setCtx, generateWsToken } from "creek";
+        return `import { _runRequest, generateWsToken } from "creek";
 import userModule from "${importPath}";
 
 const handler = userModule.default ?? userModule;
@@ -39,81 +39,80 @@ function hasExtension(pathname) {
 
 export default {
   async fetch(request, env, ctx) {
-    _setEnv(env);
-    _setCtx(ctx);
-    const url = new URL(request.url);
+    return _runRequest(env, ctx, async () => {
+      const url = new URL(request.url);
 
-    // /__creek/config — auto-discovery for CreekRoom WebSocket
-    if (url.pathname === "/__creek/config" && request.method === "GET") {
-      const wsToken = await generateWsToken();
-      return new Response(JSON.stringify({
-        realtimeUrl: env.CREEK_REALTIME_URL || null,
-        projectSlug: env.CREEK_PROJECT_SLUG || null,
-        wsToken,
-      }), { headers: { "Content-Type": "application/json" } });
-    }
-
-    // API routes → always go to the worker handler
-    if (isApiPath(url.pathname)) {
-      if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
-      if (typeof handler === "function") return handler(request, env, ctx);
-    }
+      // /__creek/config — auto-discovery for CreekRoom WebSocket
+      if (url.pathname === "/__creek/config" && request.method === "GET") {
+        const wsToken = await generateWsToken();
+        return new Response(JSON.stringify({
+          realtimeUrl: env.CREEK_REALTIME_URL || null,
+          projectSlug: env.CREEK_PROJECT_SLUG || null,
+          wsToken,
+        }), { headers: { "Content-Type": "application/json" } });
+      }
 
-    // Static assets → try WfP Static Assets API
-    if (env.ASSETS) {
-      try {
-        const assetResponse = await env.ASSETS.fetch(request);
-        if (assetResponse.status !== 404) return assetResponse;
-      } catch {}
+      // API routes → always go to the worker handler
+      if (isApiPath(url.pathname)) {
+        if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
+        if (typeof handler === "function") return handler(request, env, ctx);
+      }
 
-      // SPA fallback: extensionless paths → index.html
-      if (!hasExtension(url.pathname)) {
+      // Static assets → try WfP Static Assets API
+      if (env.ASSETS) {
         try {
-          const indexReq = new Request(new URL("/index.html", request.url), request);
-          const indexResponse = await env.ASSETS.fetch(indexReq);
-          if (indexResponse.status !== 404) {
-            return new Response(indexResponse.body, {
-              status: 200,
-              headers: indexResponse.headers,
-            });
-          }
+          const assetResponse = await env.ASSETS.fetch(request);
+          if (assetResponse.status !== 404) return assetResponse;
         } catch {}
+
+        // SPA fallback: extensionless paths → index.html
+        if (!hasExtension(url.pathname)) {
+          try {
+            const indexReq = new Request(new URL("/index.html", request.url), request);
+            const indexResponse = await env.ASSETS.fetch(indexReq);
+            if (indexResponse.status !== 404) {
+              return new Response(indexResponse.body, {
+                status: 200,
+                headers: indexResponse.headers,
+              });
+            }
+          } catch {}
+        }
       }
-    }
 
-    // Fallback: pass to worker handler
-    if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
-    if (typeof handler === "function") return handler(request, env, ctx);
-    return new Response("Not Found", { status: 404 });
+      // Fallback: pass to worker handler
+      if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
+      if (typeof handler === "function") return handler(request, env, ctx);
+      return new Response("Not Found", { status: 404 });
+    });
   },
 };
 `;
     }
     // Pure Worker (no client assets)
-    return `import { _setEnv, _setCtx, generateWsToken } from "creek";
+    return `import { _runRequest, generateWsToken } from "creek";
 import userModule from "${importPath}";
 
 const handler = userModule.default ?? userModule;
 
 export default {
   async fetch(request, env, ctx) {
-    _setEnv(env);
-    _setCtx(ctx);
-
-    // /__creek/config — auto-discovery for CreekRoom WebSocket
-    const url = new URL(request.url);
-    if (url.pathname === "/__creek/config" && request.method === "GET") {
-      const wsToken = await generateWsToken();
-      return new Response(JSON.stringify({
-        realtimeUrl: env.CREEK_REALTIME_URL || null,
-        projectSlug: env.CREEK_PROJECT_SLUG || null,
-        wsToken,
-      }), { headers: { "Content-Type": "application/json" } });
-    }
+    return _runRequest(env, ctx, async () => {
+      // /__creek/config — auto-discovery for CreekRoom WebSocket
+      const url = new URL(request.url);
+      if (url.pathname === "/__creek/config" && request.method === "GET") {
+        const wsToken = await generateWsToken();
+        return new Response(JSON.stringify({
+          realtimeUrl: env.CREEK_REALTIME_URL || null,
+          projectSlug: env.CREEK_PROJECT_SLUG || null,
+          wsToken,
+        }), { headers: { "Content-Type": "application/json" } });
+      }
 
-    if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
-    if (typeof handler === "function") return handler(request, env, ctx);
-    throw new Error("[creek] Worker must export default a fetch handler, Hono app, or { fetch() } object.");
+      if (typeof handler.fetch === "function") return handler.fetch(request, env, ctx);
+      if (typeof handler === "function") return handler(request, env, ctx);
+      throw new Error("[creek] Worker must export default a fetch handler, Hono app, or { fetch() } object.");
+    });
   },
 };
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solcreek/cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "CLI for the Creek deployment platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,12 @@
     "!dist/**/*.map",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
   "keywords": [
     "creek",
     "cli",
@@ -26,11 +32,13 @@
     "directory": "packages/cli"
   },
   "dependencies": {
+    "@solcreek/sdk": "workspace:*",
     "citty": "^0.1.6",
     "consola": "^3.4.2",
     "esbuild": "^0.25.0",
+    "miniflare": "^4.20260317.3",
     "smol-toml": "^1.3.1",
-    "@solcreek/sdk": "0.1.0-alpha.3"
+    "ws": "^8.20.0"
   },
   "optionalDependencies": {
     "@solcreek/adapter-creek": "*"
@@ -40,16 +48,12 @@
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.19.15",
     "@types/react-dom": "^19",
+    "@types/ws": "^8.18.1",
     "hono": "^4.7.4",
     "jsdom": "^29.0.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "typescript": "^5.8.2"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "typescript": "^5.8.2",
+    "vite": "^6.3.5"
   }
-}
+}