@nanobpm/urban 0.12.0 → 0.14.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";
@@ -72,7 +72,7 @@ Usage:
   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:
@@ -128,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,
@@ -183,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,18 +62,29 @@ 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. */
     log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
     jobKey: string;
     jobType: string;
     processInstanceKey?: string;
     elementId?: string;
-    variables: Record<string, unknown>;
+    variables: In;
 }
 export type JobHandler = (job: EngineJob) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 /** A registered worker subscription. */

package/dist/runtime/core/modules/workers.d.ts

@@ -6,8 +6,23 @@ import { type DecisionEvaluator } from "./llm.ts";
  *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
  *  "is not a function" / `JSON.parse` error. */
 export declare function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator;
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (job: EngineJob, app: AppApi) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (job: EngineJob<In>, app: AppApi) => Promise<Out | void> | Out | void;
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)

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.12.0",
+  "version": "0.14.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.3.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";
@@ -82,7 +84,7 @@ Usage:
   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:
@@ -139,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,
@@ -194,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:

package/src/runtime/adapters/deno.ts

@@ -18,12 +18,16 @@ interface DenoHttpServer {
   finished: Promise<void>;
   shutdown(): Promise<void>;
 }
+interface DenoFsWatcher extends AsyncIterable<{ kind: string; paths: string[] }> {
+  close(): void;
+}
 interface DenoGlobal {
   env: { get(name: string): string | undefined };
   cwd(): string;
   readTextFile(path: string): Promise<string>;
   readDir(path: string): AsyncIterable<{ name: string; isFile: boolean }>;
   stat(path: string): Promise<unknown>;
+  watchFs(paths: string | string[], options?: { recursive?: boolean }): DenoFsWatcher;
   serve(
     opts: { port: number; onListen?: (a: { port: number }) => void },
     handler: (req: Request) => Response | Promise<Response>,
@@ -34,6 +38,8 @@ declare const Deno: DenoGlobal;
 export interface DenoHostOptions {
   cwd?: string;
   log?: HostContext["log"];
+  /** See NodeHostOptions.importNonce — appended as `?v=<nonce>` to dynamic imports. */
+  importNonce?: string;
 }
 
 export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
@@ -75,10 +81,39 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
       const db = new DatabaseSync(abs(path));
       return wrapSqlite(db);
     },
-    importModule: (p) => import(pathToFileURL(abs(p)).href) as Promise<Record<string, unknown>>,
+    importModule: (p) => {
+      const href =
+        pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      return import(href) as Promise<Record<string, unknown>>;
+    },
     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/src/runtime/adapters/detect.ts

@@ -14,6 +14,8 @@ export 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. */