@nanobpm/urban 0.11.1 → 0.13.0

package/dist/cli.js

@@ -4,12 +4,12 @@
 //   urban check          load + validate the manifest, report issues
 //   urban gen            derive generated artifacts (migrations, worker I/O)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
-//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
 //               --port <n>, -h/--help, -v/--version.
-import { collectManifestIssues, loadManifest, runFromEnv, selectHost, } from "./runtime/index.js";
+import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
 import { createNodeGenIO, runGen } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
@@ -27,7 +27,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -42,6 +42,10 @@ function parse(argv) {
             f.version = true;
         else if (a === "--check")
             f.check = true;
+        else if (a === "--deno")
+            f.deno = true;
+        else if (a === "--")
+            continue; // tolerate a bare "--" some runners inject (not an option terminator here)
         else if (a === "--root")
             f.root = need(++i, a);
         else if (a === "--manifest")
@@ -64,11 +68,11 @@ function parse(argv) {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
-  urban dev                         run (hot-reload not yet implemented)
+  urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
 
 Global flags:
@@ -124,6 +128,11 @@ async function cmdRun(f, mount) {
     console.log(`▲ ${info.name} — surfaces on :${info.httpPort ?? "n/a"} (Ctrl-C to stop)`);
     return -1; // keep the process alive; signal handlers stop it
 }
+async function cmdDev(f) {
+    const dev = await runDev({ root: f.root, manifestPath: f.manifest, port: f.port });
+    installSignalHandlers(() => dev.stop());
+    return -1; // keep the process alive; signal handlers stop the dev server
+}
 async function cmdDeploy(f) {
     const app = await runFromEnv({
         root: f.root,
@@ -138,13 +147,16 @@ async function cmdDeploy(f) {
 async function cmdNew(f) {
     const name = f._[1];
     if (!name) {
-        console.error("usage: urban new <name> [--root <path>]");
+        console.error("usage: urban new <name> [--root <path>] [--deno]");
         return 1;
     }
     const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-    const res = await scaffold({ name, dir });
+    const res = await scaffold({ name, dir, deno: f.deno });
     console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
-    console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+    console.log(`  cd ${res.dir}`);
+    console.log(`  npm install && npm start`);
+    if (f.deno)
+        console.log(`  # or on Deno: deno task start`);
     return 0;
 }
 export async function main(argv) {
@@ -176,8 +188,7 @@ export async function main(argv) {
         case "run":
             return cmdRun(f);
         case "dev":
-            console.log("urban dev: hot-reload is not yet implemented; running once.");
-            return cmdRun(f);
+            return cmdDev(f);
         case "deploy":
             return cmdDeploy(f);
         default:

package/dist/runtime/adapters/deno.d.ts

@@ -2,5 +2,7 @@ import type { HostContext } from "../core/host.ts";
 export interface DenoHostOptions {
     cwd?: string;
     log?: HostContext["log"];
+    /** See NodeHostOptions.importNonce — appended as `?v=<nonce>` to dynamic imports. */
+    importNonce?: string;
 }
 export declare function createDenoHost(opts?: DenoHostOptions): HostContext;

package/dist/runtime/adapters/deno.js

@@ -51,10 +51,42 @@ export function createDenoHost(opts = {}) {
             const db = new DatabaseSync(abs(path));
             return wrapSqlite(db);
         },
-        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        importModule: (p) => {
+            const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+            return import(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return startDenoServer(port, handler);
         },
+        watch(onChange) {
+            const w = Deno.watchFs(cwd, { recursive: true });
+            let closed = false;
+            (async () => {
+                try {
+                    for await (const ev of w) {
+                        for (const p of ev.paths)
+                            onChange(p);
+                    }
+                }
+                catch (err) {
+                    // Deno.watchFs throws when close() is called mid-await — expected on shutdown.
+                    // Any other failure (permissions, path removed, …) silently disables hot reload,
+                    // so surface it instead of swallowing it.
+                    if (!closed)
+                        log("warn", "file watch error — hot reload may be disabled", {
+                            error: String(err),
+                        });
+                }
+            })();
+            return {
+                close: () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    w.close();
+                },
+            };
+        },
         now: () => Date.now(),
         log,
     };

package/dist/runtime/adapters/detect.d.ts

@@ -4,6 +4,8 @@ export declare function isDeno(): boolean;
 export interface SelectHostOptions {
     cwd?: string;
     log?: HostContext["log"];
+    /** Dev-only import-cache-busting nonce; forwarded to the chosen adapter. */
+    importNonce?: string;
 }
 /** Select and construct the host for the current runtime. */
 export declare function selectHost(opts?: SelectHostOptions): HostContext;

package/dist/runtime/adapters/node.d.ts

@@ -3,5 +3,11 @@ export interface NodeHostOptions {
     /** Base directory relative paths resolve against. Default process.cwd(). */
     cwd?: string;
     log?: HostContext["log"];
+    /**
+     * When set, appended as a `?v=<nonce>` query to dynamic import URLs so a changed
+     * handler/worker module is re-evaluated instead of served from the ESM cache. The
+     * dev server bumps this on every reload; production leaves it unset.
+     */
+    importNonce?: string;
 }
 export declare function createNodeHost(opts?: NodeHostOptions): HostContext;

package/dist/runtime/adapters/node.js

@@ -9,6 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { readFile, readdir, stat } from "node:fs/promises";
+import { watch as fsWatch } from "node:fs";
 import { createServer } from "node:http";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -47,10 +48,36 @@ export function createNodeHost(opts = {}) {
             const db = new DatabaseSync(abs(path));
             return wrapNodeSqlite(db);
         },
-        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        importModule: (p) => {
+            const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+            return import(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return await startNodeServer(port, handler);
         },
+        watch(onChange) {
+            const onFsEvent = (_event, filename) => {
+                if (filename)
+                    onChange(String(filename));
+            };
+            // Recursive watch is supported on macOS, Windows, and — since Node 19.1.0 — Linux.
+            // This package requires Node >=22.6, so the recursive path is available on all three;
+            // the try/catch only trips on an unusual platform, where we degrade honestly to a
+            // non-recursive root watch (and warn) rather than silently miss nested changes.
+            let w;
+            try {
+                w = fsWatch(cwd, { recursive: true }, onFsEvent);
+            }
+            catch (err) {
+                log("warn", "recursive file watch unavailable — nested changes may be missed", {
+                    error: String(err),
+                });
+                w = fsWatch(cwd, onFsEvent);
+            }
+            // A watcher error (e.g. the dir is removed) must not crash the dev server.
+            w.on("error", (err) => log("warn", "file watch error", { error: String(err) }));
+            return { close: () => w.close() };
+        },
         now: () => Date.now(),
         log,
     };

package/dist/runtime/core/host.d.ts

@@ -21,6 +21,10 @@ export interface HttpServer {
     readonly port: number;
     stop(): Promise<void>;
 }
+/** A handle to an active filesystem watch; call close() to stop watching. */
+export interface WatchHandle {
+    close(): void;
+}
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
     /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -58,6 +62,13 @@ export interface HostContext {
     importModule(path: string): Promise<Record<string, unknown>>;
     /** Start an HTTP server. Routing is done by the caller inside `handler`. */
     serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+    /**
+     * Recursively watch the app root for file changes, invoking `onChange` with the
+     * changed path (app-root-relative when the runtime reports it that way). Optional:
+     * hosts that cannot watch omit it, and callers fall back to run-once. Returns a
+     * handle whose close() stops watching.
+     */
+    watch?(onChange: (path: string) => void): WatchHandle;
     /** Current wall-clock time in ms since epoch (seam for tests). */
     now(): number;
     /** Structured log sink. */

package/dist/runtime/devserver.d.ts

@@ -0,0 +1,36 @@
+import type { HostContext } from "./core/host.ts";
+import type { UrbanApp } from "./core/runtime.ts";
+/** True when a changed path should trigger a dev reload. Pure, so it is unit-tested.
+ *  `manifestFile` (the app's configured manifest, default nano.app.json) always triggers,
+ *  so `urban dev --manifest other.json` reloads on edits to that file too. */
+export declare function shouldReload(rawPath: string, manifestFile?: string): boolean;
+export interface DevOptions {
+    root?: string;
+    manifestPath?: string;
+    port?: number;
+    /** Quiet-period after the last change before reloading, in ms. Default 150. */
+    debounceMs?: number;
+    /** Log sink (default console.log). */
+    log?: (msg: string) => void;
+}
+/** Injectable seams so the loop is testable without a live engine or filesystem. */
+export interface DevDeps {
+    makeHost(nonce: string): HostContext;
+    startApp(host: HostContext, o: {
+        manifestPath: string;
+        port?: number;
+    }): Promise<UrbanApp>;
+    regenerate(root: string, manifestFile: string): Promise<{
+        count: number;
+    }>;
+    now(): number;
+}
+export interface DevServer {
+    stop(): Promise<void>;
+}
+/**
+ * Start the dev server: gen once, start the app, then watch + hot-reload. Returns a handle
+ * whose stop() tears the watcher and the running app down. Never rejects on a reload error —
+ * a bad edit logs and leaves the previous app running.
+ */
+export declare function runDev(opts?: DevOptions, deps?: Partial<DevDeps>): Promise<DevServer>;

package/dist/runtime/devserver.js

@@ -0,0 +1,173 @@
+// `urban dev` — a hot-reload dev server. It runs the derivers once, starts the app, then
+// watches the app root and, on a relevant source change, regenerates artifacts and restarts
+// the app in-process. A per-reload import nonce busts the module cache so changed worker/
+// action handlers are re-evaluated. main.ts is NOT re-run in dev (the CLI drives the runtime
+// directly), so main.ts edits don't need a reload.
+//
+// The reload strategy is a full in-process restart: regenerate + build a fresh host, then
+// stop the old app and start the new one. Regenerating first means a bad edit (invalid
+// manifest/model) fails before the running app is torn down, so it keeps serving. It is the
+// same start path as a fresh `urban run`, so every change kind — manifest, BPMN/DMN, forms,
+// migrations/types, worker code — is picked up. A finer-grained surface remount + browser
+// live-reload can layer on later behind this same seam.
+import { runFromEnv } from "./run.js";
+import { selectHost } from "./adapters/detect.js";
+import { createNodeGenIO, runGen } from "../toolkit/index.js";
+const SOURCE_EXT = [".bpmn", ".dmn", ".form", ".ts", ".js", ".mjs", ".sql"];
+// Directories whose churn must never trigger a reload: generated output (gen writes here —
+// watching it would loop forever), dependencies, VCS, and build output.
+const IGNORE_SEGMENTS = ["nano-generated", "node_modules", ".git", "dist"];
+/** True when a changed path should trigger a dev reload. Pure, so it is unit-tested.
+ *  `manifestFile` (the app's configured manifest, default nano.app.json) always triggers,
+ *  so `urban dev --manifest other.json` reloads on edits to that file too. */
+export function shouldReload(rawPath, manifestFile = "nano.app.json") {
+    const norm = (s) => s.replace(/\\/g, "/").replace(/^\.\//, "");
+    const p = norm(rawPath);
+    if (p === "")
+        return false;
+    for (const seg of IGNORE_SEGMENTS) {
+        if (p === seg || p.startsWith(`${seg}/`) || p.includes(`/${seg}/`))
+            return false;
+    }
+    // Ignore SQLite database files and their WAL/SHM/journal sidecars — they change on every
+    // write and would otherwise wedge the server in a reload loop.
+    if (/\.(db|sqlite|sqlite3)(-wal|-shm|-journal)?$/i.test(p))
+        return false;
+    const mf = norm(manifestFile);
+    const base = p.slice(p.lastIndexOf("/") + 1);
+    if (p === mf || base === mf.slice(mf.lastIndexOf("/") + 1))
+        return true;
+    return SOURCE_EXT.some((e) => p.toLowerCase().endsWith(e));
+}
+function defaultDeps(root) {
+    return {
+        makeHost: (nonce) => selectHost({ cwd: root, importNonce: nonce }),
+        startApp: (host, o) => 
+        // The host is anchored at `root`; runFromEnv keeps its own root at "." accordingly.
+        runFromEnv({ host, manifestPath: o.manifestPath, port: o.port, handleSignals: false }),
+        regenerate: async (r, mf) => {
+            const res = await runGen({ root: r, io: createNodeGenIO(), manifestFile: mf });
+            return { count: res.artifacts.length };
+        },
+        now: () => Date.now(),
+    };
+}
+/**
+ * Start the dev server: gen once, start the app, then watch + hot-reload. Returns a handle
+ * whose stop() tears the watcher and the running app down. Never rejects on a reload error —
+ * a bad edit logs and leaves the previous app running.
+ */
+export async function runDev(opts = {}, deps) {
+    const root = opts.root ?? ".";
+    const manifestFile = opts.manifestPath ?? "nano.app.json";
+    const debounceMs = opts.debounceMs ?? 150;
+    const log = opts.log ?? ((m) => console.log(m));
+    const d = { ...defaultDeps(root), ...deps };
+    // Monotonic reload counter, mixed into the import nonce so it is unique per reload even when
+    // two reloads land in the same millisecond (d.now() can repeat).
+    let reloadSeq = 0;
+    const startCycle = async () => {
+        const host = await prepareHost();
+        const app = await d.startApp(host, { manifestPath: manifestFile, port: opts.port });
+        return { host, app };
+    };
+    // Derive artifacts and build a fresh host (with a new import nonce). This is pure/FS work
+    // that does NOT touch the running app, so it can run *before* a reload tears the old app
+    // down — most bad edits (invalid manifest/model) fail here, leaving the app serving.
+    const prepareHost = async () => {
+        const nonce = `${d.now()}-${reloadSeq++}`;
+        const { count } = await d.regenerate(root, manifestFile);
+        if (count > 0)
+            log(`  derived ${count} artifact(s)`);
+        return d.makeHost(nonce);
+    };
+    let { host, app } = await startCycle();
+    let reloading = false;
+    let queued = false;
+    let stopped = false;
+    let appRunning = true;
+    let inFlight;
+    let timer;
+    const reload = async () => {
+        try {
+            log("↻ change detected — reloading…");
+            // Regenerate + rebuild the host BEFORE stopping the running app, so a bad edit
+            // throws here and the current app keeps serving untouched.
+            const nextHost = await prepareHost();
+            if (stopped)
+                return; // shutdown began mid-prepare: leave the running app to stop()
+            await app.stop();
+            appRunning = false;
+            // Re-check after the async stop: if shutdown began while we were tearing the old
+            // app down, don't start a replacement just to have stop() immediately kill it.
+            if (stopped)
+                return;
+            app = await d.startApp(nextHost, { manifestPath: manifestFile, port: opts.port });
+            appRunning = true;
+            host = nextHost;
+            log("✔ reloaded");
+        }
+        catch (err) {
+            // Keep the dev server alive on a bad edit; the next save will retry.
+            log(`✖ reload failed: ${String(err?.message ?? err)}`);
+        }
+        finally {
+            reloading = false;
+            if (queued && !stopped) {
+                queued = false;
+                schedule();
+            }
+        }
+    };
+    // Owns the single-flight guard and `inFlight` bookkeeping: only an *actually running*
+    // reload is tracked in `inFlight`, so stop() always awaits the real in-flight reload
+    // (never an already-resolved no-op promise) before final teardown.
+    const trigger = () => {
+        if (stopped)
+            return;
+        if (reloading) {
+            queued = true; // the active reload's finally re-schedules the next cycle
+            return;
+        }
+        reloading = true;
+        inFlight = reload();
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            trigger();
+        }, debounceMs);
+    };
+    let watcher;
+    if (host.watch) {
+        watcher = host.watch((path) => {
+            if (shouldReload(path, manifestFile))
+                schedule();
+        });
+        log("▲ dev server ready — watching for changes (Ctrl-C to stop)");
+    }
+    else {
+        log("▲ dev server ready — file watching is not supported on this host; running once " +
+            "(no hot reload, Ctrl-C to stop)");
+    }
+    return {
+        async stop() {
+            // Order matters: flag first so a queued/in-flight reload won't start a new app, cancel
+            // any pending debounce, stop watching, then let any in-flight reload settle before the
+            // final teardown so we stop exactly the app that is (or ends up) current.
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            watcher?.close();
+            await inFlight?.catch(() => { });
+            if (appRunning)
+                await app.stop();
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -4,7 +4,7 @@ export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType,
 export type { ActionDecl, AppManifest, DataSource, DomainType, LlmBinding, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
@@ -25,5 +25,7 @@ export { isDeno, selectHost } from "./adapters/detect.ts";
 export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.ts";
 export type { NanoSdkClient, NanoSdkEngineOptions, NanoSdkJobWorker, NanoSdkJobWorkerConfig, } from "./engine/nanosdk.ts";
 export type { EngineSdkClient } from "./engine/sdk.ts";
-export { runFromEnv } from "./run.ts";
+export { installSignalHandlers, runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";
+export { runDev, shouldReload } from "./devserver.ts";
+export type { DevDeps, DevOptions, DevServer } from "./devserver.ts";

package/dist/runtime/index.js

@@ -18,4 +18,5 @@ export { createNodeHost } from "./adapters/node.js";
 export { createDenoHost } from "./adapters/deno.js";
 export { isDeno, selectHost } from "./adapters/detect.js";
 export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.js";
-export { runFromEnv } from "./run.js";
+export { installSignalHandlers, runFromEnv } from "./run.js";
+export { runDev, shouldReload } from "./devserver.js";

package/dist/runtime/run.d.ts

@@ -15,3 +15,4 @@ export interface RunOptions extends Partial<CreateUrbanAppOptions> {
     handleSignals?: boolean;
 }
 export declare function runFromEnv(opts?: RunOptions): Promise<UrbanApp>;
+export declare function installSignalHandlers(stop: () => Promise<void>): void;

package/dist/runtime/run.js

@@ -32,7 +32,7 @@ export async function runFromEnv(opts = {}) {
         installSignalHandlers(() => app.stop());
     return app;
 }
-function installSignalHandlers(stop) {
+export function installSignalHandlers(stop) {
     let stopping = false;
     const onSignal = () => {
         if (stopping)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -61,7 +61,7 @@
     "@nanobpm/nano-sdk": "^1.2.0",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.2.0"
+    "create-urban-app": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/cli.ts

@@ -4,7 +4,7 @@
 //   urban check          load + validate the manifest, report issues
 //   urban gen            derive generated artifacts (migrations, worker I/O)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
-//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
@@ -12,7 +12,9 @@
 
 import {
   collectManifestIssues,
+  installSignalHandlers,
   loadManifest,
+  runDev,
   runFromEnv,
   selectHost,
 } from "./runtime/index.ts";
@@ -40,13 +42,14 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
+  deno: boolean;
   help: boolean;
   version: boolean;
   _: string[];
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -57,6 +60,8 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") f.version = true;
     else if (a === "--check") f.check = true;
+    else if (a === "--deno") f.deno = true;
+    else if (a === "--") continue; // tolerate a bare "--" some runners inject (not an option terminator here)
     else if (a === "--root") f.root = need(++i, a);
     else if (a === "--manifest") f.manifest = need(++i, a);
     else if (a === "--port") {
@@ -75,11 +80,11 @@ function parse(argv: string[]): Flags {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
-  urban dev                         run (hot-reload not yet implemented)
+  urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
 
 Global flags:
@@ -136,6 +141,12 @@ async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number
   return -1; // keep the process alive; signal handlers stop it
 }
 
+async function cmdDev(f: Flags): Promise<number> {
+  const dev = await runDev({ root: f.root, manifestPath: f.manifest, port: f.port });
+  installSignalHandlers(() => dev.stop());
+  return -1; // keep the process alive; signal handlers stop the dev server
+}
+
 async function cmdDeploy(f: Flags): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -151,13 +162,15 @@ async function cmdDeploy(f: Flags): Promise<number> {
 async function cmdNew(f: Flags): Promise<number> {
   const name = f._[1];
   if (!name) {
-    console.error("usage: urban new <name> [--root <path>]");
+    console.error("usage: urban new <name> [--root <path>] [--deno]");
     return 1;
   }
   const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-  const res = await scaffold({ name, dir });
+  const res = await scaffold({ name, dir, deno: f.deno });
   console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
-  console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+  console.log(`  cd ${res.dir}`);
+  console.log(`  npm install && npm start`);
+  if (f.deno) console.log(`  # or on Deno: deno task start`);
   return 0;
 }
 
@@ -189,8 +202,7 @@ export async function main(argv: string[]): Promise<number> {
     case "run":
       return cmdRun(f);
     case "dev":
-      console.log("urban dev: hot-reload is not yet implemented; running once.");
-      return cmdRun(f);
+      return cmdDev(f);
     case "deploy":
       return cmdDeploy(f);
     default: