@nwire/cli 0.12.0 → 0.13.0

package/dist/cli.d.ts

@@ -3,7 +3,7 @@
  * `nwire` — the umbrella CLI. Built on citty: one root command, one
  * subcommand per file under `commands/`. The CLI is intentionally thin —
  * every command delegates to a small set of execution helpers
- * (`viteNode`, `spawnInteractive`) and, where needed, an in-tree
+ * (`viteRun`, `spawnInteractive`) and, where needed, an in-tree
  * RunnerSupervisor for long-lived processes.
  *
  * Adding a new command:

package/dist/cli.js

@@ -3,7 +3,7 @@
  * `nwire` — the umbrella CLI. Built on citty: one root command, one
  * subcommand per file under `commands/`. The CLI is intentionally thin —
  * every command delegates to a small set of execution helpers
- * (`viteNode`, `spawnInteractive`) and, where needed, an in-tree
+ * (`viteRun`, `spawnInteractive`) and, where needed, an in-tree
  * RunnerSupervisor for long-lived processes.
  *
  * Adding a new command:

package/dist/commands/cache.js

@@ -30,7 +30,7 @@ export const cacheCommand = defineCommand({
     },
     async run({ args }) {
         const force = !args["if-stale"];
-        const result = ensureScanFresh(process.cwd(), { force, quiet: args.quiet });
+        const result = await ensureScanFresh(process.cwd(), { force, quiet: args.quiet });
         // exit 0 when the cache is current — whether we just rebuilt it or
         // the cheap-path skipped. exit 1 only when we tried to rebuild and
         // the builder failed.

package/dist/commands/dev.d.ts

@@ -1,10 +1,23 @@
 /**
- * `nwire dev` — boots the project's wire under vite-node --watch with
- * stdio passthrough. Prints a branded banner before spawning so the
- * user sees what's about to run + the project context; the child's
- * stdout/stderr flow through unmodified afterwards.
+ * `nwire dev` — boots the project's wire + Studio on one port via the
+ * in-process Vite dev host. Prints a branded banner, then hands off to
+ * `startDevHost` which serves both surfaces without a child process.
  *
- * Also writes a state file under `.nwire/processes/` so `nwire ps`
- * sees the dev session from any other shell.
+ * For projects that declare a `scripts.dev` fallback instead of a recognized
+ * wire entry, the old child-spawn path is preserved so nothing breaks.
+ *
+ * Also writes a state file under `.nwire/processes/` so `nwire ps` sees
+ * the dev session from any other shell.
  */
-export declare const devCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const devCommand: import("citty").CommandDef<{
+    endpoint: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    port: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+}>;

package/dist/commands/dev.js

@@ -1,36 +1,68 @@
 /**
- * `nwire dev` — boots the project's wire under vite-node --watch with
- * stdio passthrough. Prints a branded banner before spawning so the
- * user sees what's about to run + the project context; the child's
- * stdout/stderr flow through unmodified afterwards.
+ * `nwire dev` — boots the project's wire + Studio on one port via the
+ * in-process Vite dev host. Prints a branded banner, then hands off to
+ * `startDevHost` which serves both surfaces without a child process.
  *
- * Also writes a state file under `.nwire/processes/` so `nwire ps`
- * sees the dev session from any other shell.
+ * For projects that declare a `scripts.dev` fallback instead of a recognized
+ * wire entry, the old child-spawn path is preserved so nothing breaks.
+ *
+ * Also writes a state file under `.nwire/processes/` so `nwire ps` sees
+ * the dev session from any other shell.
  */
 import { defineCommand } from "citty";
-import { appendFileSync, closeSync, openSync } from "node:fs";
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { palette } from "../lib/colors.js";
-/** Windows toggle — `shell:true` so `pnpm.cmd` resolves on spawn. */
-const IS_WIN = process.platform === "win32";
 import { detectProject } from "../lib/project.js";
+import { ensureWorkspaceBuilt } from "../lib/ensure-built.js";
 import { resolveDevEntry, devEntryCandidates } from "../lib/dev-entry.js";
+import { startDevHost } from "../lib/dev-host.js";
 import { ensureDir as ensureProcDir, logPath as procLogPath, removeRecord, writeRecord, } from "../lib/process-state.js";
+// ── npm-script fallback (child spawn) ───────────────────────────────────────
+// Only used when resolved.kind === "npm-script". Kept self-contained so the
+// host path above has no child-process machinery at all.
+import { appendFileSync, closeSync, openSync } from "node:fs";
+import { spawn } from "node:child_process";
+/** Windows toggle — `shell:true` so `pnpm.cmd` resolves on spawn. */
+const IS_WIN = process.platform === "win32";
+const DEFAULT_PORT = 4000;
+/**
+ * Resolve the host port: explicit `--port` wins, then `$PORT`, then the
+ * default. A non-numeric or out-of-range value is ignored (falls through to
+ * the next source) so a typo can't silently bind an ephemeral port.
+ */
+function resolvePort(flag) {
+    for (const candidate of [flag, process.env.PORT]) {
+        if (candidate === undefined || candidate === "")
+            continue;
+        const n = Number(candidate);
+        if (Number.isInteger(n) && n >= 0 && n <= 65535)
+            return n;
+    }
+    return DEFAULT_PORT;
+}
 export const devCommand = defineCommand({
     meta: {
         name: "dev",
-        description: "Boot the dev-all topology with watch mode",
+        description: "Boot the project wire with watch mode",
     },
-    async run() {
+    args: {
+        endpoint: {
+            type: "string",
+            description: "Name of the endpoint to front on the HTTP surface (multi-endpoint projects).",
+            required: false,
+        },
+        port: {
+            type: "string",
+            description: `Port for the wire + Studio host. Falls back to $PORT, then ${DEFAULT_PORT}.`,
+            required: false,
+        },
+    },
+    async run({ args }) {
         const cwd = process.cwd();
+        // Monorepo only: keep workspace `dist/` fresh so a stale `@nwire/*`
+        // doesn't crash the example wire. No-op in consumer apps.
+        ensureWorkspaceBuilt(cwd);
         const project = detectProject(cwd);
-        // Resolution covers every recognized project shape:
-        //   1. apps/dev-all/run.ts (multi-wire)
-        //   2. apps/<single>/{run,main}.ts
-        //   3. app/{main,run,index}.ts (singular small-example shape)
-        //   4. package.json scripts.dev (last resort — honors whatever the
-        //      consumer scripts already encode, e.g. vite-node app/main.ts)
         const resolved = resolveDevEntry(cwd);
         if (!resolved) {
             // eslint-disable-next-line no-console
@@ -39,12 +71,95 @@ export const devCommand = defineCommand({
                 `  looked for: ${devEntryCandidates().join(", ")}`);
             process.exit(1);
         }
-        const subtitle = resolved.kind === "vite-node" ? resolved.label : `pnpm run ${resolved.script}`;
-        const entryRel = resolved.kind === "vite-node" ? resolved.rel : `package.json scripts.${resolved.script}`;
-        // ── Banner ──────────────────────────────────────────────────────
-        // Single block before stdio passthrough takes over. The child's
-        // boot logs (runApp's "ready" banner, ports, etc.) flow through
-        // immediately after.
+        if (resolved.kind === "wire") {
+            // ── In-process one-Vite host ─────────────────────────────────────
+            // Port precedence: --port flag → $PORT env → default. Invalid values
+            // fall through to the next source so a typo never silently binds 0.
+            const port = resolvePort(args.port);
+            const id = randomUUID();
+            const startedAt = new Date().toISOString();
+            // eslint-disable-next-line no-console
+            console.log([
+                "",
+                `  ${palette.brand(palette.bold("Nwire dev"))}  ${palette.dim(project.name)}`,
+                `  ${palette.dim("entry  ")} ${resolved.rel}`,
+                `  ${palette.dim("wire   ")} ${resolved.label}`,
+                `  ${palette.dim("host   ")} http://127.0.0.1:${port}`,
+                `  ${palette.dim("mode   ")} ${palette.accent("dev-host")}`,
+                `  ${palette.dim("Ctrl+C ")} stop`,
+                "",
+            ].join("\n"));
+            ensureProcDir(cwd);
+            let currentStatus = "starting";
+            const persistRecord = (p) => {
+                const record = {
+                    id,
+                    name: `dev:${resolved.label}`,
+                    pid: process.pid,
+                    status: currentStatus,
+                    port: p ?? port,
+                    startedAt,
+                    cwd,
+                    command: `nwire dev-host ${resolved.rel}`,
+                    logPath: procLogPath(cwd, id),
+                    lastUpdated: new Date().toISOString(),
+                };
+                writeRecord(cwd, record);
+            };
+            persistRecord();
+            let host;
+            let stopping = false;
+            const stop = async () => {
+                if (stopping)
+                    return;
+                stopping = true;
+                currentStatus = "stopping";
+                persistRecord();
+                if (host) {
+                    try {
+                        await host.close();
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+                removeRecord(cwd, id);
+                // eslint-disable-next-line no-console
+                console.log(palette.dim("\nDev stopped."));
+                process.exit(0);
+            };
+            process.on("SIGINT", () => void stop());
+            process.on("SIGTERM", () => void stop());
+            try {
+                host = await startDevHost({
+                    cwd,
+                    entry: resolved.entry,
+                    port,
+                    activeEndpoint: args.endpoint || undefined,
+                });
+                currentStatus = "running";
+                persistRecord(port);
+                // eslint-disable-next-line no-console
+                console.log(`  ${palette.ok("ready")}  wire + Studio on http://127.0.0.1:${port}\n`);
+                // Park the process — the http.Server keeps the event loop alive.
+                await new Promise(() => { });
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.error(palette.err("nwire dev: host failed to start —"), err);
+                currentStatus = "crashed";
+                persistRecord();
+                removeRecord(cwd, id);
+                process.exit(1);
+            }
+            return;
+        }
+        // ── npm-script fallback (child spawn) ────────────────────────────────
+        // `resolved.kind === "npm-script"`: the project has no recognized wire
+        // entry but declares a `scripts.dev`. Honor it via spawn so `nwire dev`
+        // still works on those projects without any behavior change.
+        const subtitle = `pnpm run ${resolved.script}`;
+        const entryRel = `package.json scripts.${resolved.script}`;
         // eslint-disable-next-line no-console
         console.log([
             "",
@@ -55,22 +170,11 @@ export const devCommand = defineCommand({
             `  ${palette.dim("Ctrl+C ")} stop`,
             "",
         ].join("\n"));
-        // ── Spawn child with stdio inherited ────────────────────────────
-        // Inherit means logs go straight to the user's terminal — no ink
-        // capture, no log buffering. The trade-off: `nwire logs <id>`
-        // can't tail the live stream (only what we tee to disk). For dev
-        // sessions that's fine — the user is watching the terminal.
-        const spawnCmd = resolved.kind === "vite-node"
-            ? ["pnpm", ["exec", "vite-node", "--watch", resolved.entry]]
-            : ["pnpm", ["run", resolved.script]];
-        const child = spawn(spawnCmd[0], spawnCmd[1], {
+        const child = spawn("pnpm", ["run", resolved.script], {
             stdio: ["inherit", "pipe", "pipe"],
             cwd,
             shell: IS_WIN,
         });
-        // Tee child stdio through to BOTH the user's terminal AND the
-        // per-process log file so `nwire logs <id>` works from another
-        // shell. Direct passthrough to stdout to keep ordering intact.
         const id = randomUUID();
         const startedAt = new Date().toISOString();
         ensureProcDir(cwd);
@@ -81,15 +185,13 @@ export const devCommand = defineCommand({
         const persistRecord = () => {
             const record = {
                 id,
-                name: `dev:${subtitle}`,
+                name: `dev:${resolved.script}`,
                 pid: child.pid ?? -1,
                 status: currentStatus,
                 port,
                 startedAt,
                 cwd,
-                command: resolved.kind === "vite-node"
-                    ? `vite-node --watch ${resolved.rel}`
-                    : `pnpm run ${resolved.script} (${resolved.command})`,
+                command: `pnpm run ${resolved.script} (${resolved.command})`,
                 logPath: logFile,
                 lastUpdated: new Date().toISOString(),
             };
@@ -107,7 +209,6 @@ export const devCommand = defineCommand({
             }
             out.write(text);
             if (currentStatus !== "running" && READY_RE.test(text)) {
-                // Try to capture the port from "Local: http://...:<port>"
                 const match = /:(\d+)\b/.exec(text);
                 if (match)
                     port = Number(match[1]);
@@ -117,7 +218,6 @@ export const devCommand = defineCommand({
         };
         child.stdout?.on("data", handleStream(process.stdout));
         child.stderr?.on("data", handleStream(process.stderr));
-        // ── Shutdown ────────────────────────────────────────────────────
         let stopping = false;
         const stop = (signal) => {
             if (stopping)
@@ -134,9 +234,6 @@ export const devCommand = defineCommand({
             setTimeout(() => {
                 if (child.exitCode === null && child.signalCode === null) {
                     try {
-                        // Windows has no signal mechanism — SIGTERM and SIGKILL
-                        // collapse to the same TerminateProcess call. Skip the
-                        // explicit SIGKILL and let Node use the platform default.
                         if (IS_WIN)
                             child.kill();
                         else

package/dist/commands/ls.js

@@ -8,7 +8,7 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { palette } from "../lib/colors.js";
 import { ensureScanFresh } from "../lib/ensure-scan.js";
-import { viteNode } from "../lib/vite-node.js";
+import { execSync } from "../lib/exec.js";
 const here = dirname(fileURLToPath(import.meta.url));
 export const lsCommand = defineCommand({
     meta: {
@@ -16,13 +16,15 @@ export const lsCommand = defineCommand({
         description: "List discovered wires + actions",
     },
     async run({ rawArgs }) {
-        ensureScanFresh(process.cwd(), { quiet: true });
+        await ensureScanFresh(process.cwd(), { quiet: true });
         const builderPath = resolve(here, "..", "ls-runner.js");
         if (!existsSync(builderPath)) {
             // eslint-disable-next-line no-console
             console.error(palette.err("nwire ls:") + ` ls runner missing at ${builderPath}`);
             process.exit(1);
         }
-        process.exit(viteNode(builderPath, rawArgs));
+        // ls-runner is plain built JS that reads `.nwire/manifest.json` — plain node,
+        // no Vite needed.
+        process.exit(execSync("node", [builderPath, ...rawArgs]));
     },
 });

package/dist/commands/please.js

@@ -7,7 +7,7 @@ import { defineCommand } from "citty";
 import { resolve } from "node:path";
 import { existsSync, readdirSync } from "node:fs";
 import { palette } from "../lib/colors.js";
-import { viteNode } from "../lib/vite-node.js";
+import { viteRun } from "../lib/vite-run.js";
 function findPleaseEntry(cwd) {
     const appsDir = resolve(cwd, "apps");
     if (!existsSync(appsDir))
@@ -40,6 +40,8 @@ export const pleaseCommand = defineCommand({
             console.error(palette.err("nwire please:") + " no apps/*/run.please.ts found in this project");
             process.exit(1);
         }
-        process.exit(viteNode(pleasePath, rawArgs));
+        // The please wire runs in-process; it exits with its own code, or we exit 0.
+        await viteRun(pleasePath, rawArgs);
+        process.exit(0);
     },
 });

package/dist/commands/run.js

@@ -10,10 +10,12 @@
  * difference is `dev` adds `--watch` and reloads on change.
  */
 import { defineCommand } from "citty";
-import { basename, relative, resolve } from "node:path";
+import { basename, relative, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { palette } from "../lib/colors.js";
+const here = dirname(fileURLToPath(import.meta.url));
 /** Windows toggle — `shell:true` so `.cmd` shims like `pnpm` resolve. */
 const IS_WIN = process.platform === "win32";
 export const runCommand = defineCommand({
@@ -68,7 +70,9 @@ export const runCommand = defineCommand({
         // The child writes directly to the user's terminal. runApp() emits
         // its own banner (ports, docs, openapi paths) so the user gets
         // immediate feedback once the wire is listening.
-        const child = spawn("pnpm", ["exec", "vite-node", entry, ...passthrough], {
+        // Load the wire via the Vite-backed wire-runner (no vite-node).
+        const wireRunner = resolve(here, "..", "wire-runner.js");
+        const child = spawn("node", [wireRunner, entry, ...passthrough], {
             stdio: "inherit",
             cwd,
             shell: IS_WIN,

package/dist/commands/studio.js

@@ -7,19 +7,66 @@
  */
 import { defineCommand } from "citty";
 import { createRequire } from "node:module";
-import { resolve, dirname } from "node:path";
-import { existsSync } from "node:fs";
+import { resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
 import { palette } from "../lib/colors.js";
 import { spawnInteractive } from "../lib/exec.js";
+import { ensureWorkspaceBuilt } from "../lib/ensure-built.js";
+import { decideStudioProbe, hasExplicitPort, openBrowser, probeStudio, registerProject, resolveStudioPort, studioBaseUrl, } from "../lib/studio-probe.js";
+/** A project's display name — its `package.json` `name`, else the dir name. */
+function projectName(cwd) {
+    try {
+        const pj = resolve(cwd, "package.json");
+        if (existsSync(pj)) {
+            const parsed = JSON.parse(readFileSync(pj, "utf8"));
+            if (parsed.name)
+                return parsed.name;
+        }
+    }
+    catch {
+        // fall through to the directory name
+    }
+    return basename(cwd);
+}
 export const studioCommand = defineCommand({
     meta: {
         name: "studio",
         description: "Boot Nwire Studio (Vue + Vite UI)",
     },
     async run({ rawArgs }) {
-        // Try resolving @nwire/studio from the consumer's cwd first (so a
-        // dev-deps install in their project works), then from the CLI's own
-        // location (covers the framework workspace + `pnpm dlx` flows).
+        // ── Singleton: attach to an already-running studio ───────────────
+        // Probe the studio port. If a studio is live there, register this
+        // project with it, open the browser, and exit 0 — never bind a second
+        // server. Only on the spawn path do we ensure the workspace is built.
+        const port = resolveStudioPort(rawArgs);
+        const cwd = process.cwd();
+        const decision = decideStudioProbe(await probeStudio(port));
+        if (decision.action === "attach") {
+            await registerProject(port, cwd);
+            // Name the project we just registered (this cwd), not the host studio.
+            const label = projectName(cwd);
+            // eslint-disable-next-line no-console
+            console.log(palette.brand("nwire studio:") +
+                ` already running on :${port} — registered ${palette.bold(label)}, opening…`);
+            openBrowser(`${studioBaseUrl(port)}/projects`);
+            process.exit(0);
+        }
+        if (decision.action === "spawn-foreign") {
+            // eslint-disable-next-line no-console
+            console.log(palette.warn("nwire studio:") +
+                ` port ${port} is taken by another service — letting vite pick a free port.`);
+        }
+        // Monorepo only: keep workspace `dist/` fresh before booting so
+        // examples don't crash on stale `@nwire/*`. No-op in consumer apps.
+        ensureWorkspaceBuilt(cwd);
+        // Resolve the Studio source dir so we can find its vite binary.
+        //
+        // Resolution order:
+        //  1. Bundled inside the CLI itself (dist/studio ships the prebuilt SPA but
+        //     we need the *source* dir for vite — fall through to node_modules paths).
+        //  2. Consumer's node_modules (explicit devDep install, dev-hacking workflow).
+        //  3. CLI's own node_modules (framework workspace + `pnpm dlx` flows).
         let studioDir;
         const tryResolveFrom = (basePath) => {
             try {
@@ -33,6 +80,18 @@ export const studioCommand = defineCommand({
         studioDir =
             tryResolveFrom(resolve(process.cwd(), "package.json")) ?? tryResolveFrom(import.meta.url);
         if (!studioDir) {
+            // @nwire/studio not reachable as a package — check whether the bundled
+            // prebuilt SPA is present (the normal consumer path). When it is, the
+            // `nwire dev` host already serves Studio at `/`; `nwire studio` (the
+            // standalone Vite dev server) is only needed in the framework workspace.
+            const bundledDist = resolve(dirname(fileURLToPath(import.meta.url)), "..", "studio");
+            if (existsSync(bundledDist)) {
+                // eslint-disable-next-line no-console
+                console.log(palette.brand("nwire studio:") +
+                    " Studio is served by `nwire dev` at http://localhost:<port>/. " +
+                    "Run `nwire dev` to see the live Studio UI.");
+                process.exit(0);
+            }
             // eslint-disable-next-line no-console
             console.error(palette.err("nwire studio:") +
                 " @nwire/studio not installed. `pnpm add -D @nwire/studio` first.");
@@ -51,9 +110,17 @@ export const studioCommand = defineCommand({
                 ` vite binary missing at ${viteBin} — run \`pnpm install\` in ${studioDir}`);
             process.exit(1);
         }
-        const { done } = spawnInteractive(viteBin, rawArgs, {
+        // Deterministic port: on the normal (free-port) spawn path, pin the
+        // studio to `port` with `--strictPort` so it OWNS that port and the
+        // next `nwire studio` invocation finds + attaches to it rather than
+        // scattering onto 7778, 7779, … . Skip when the user already pinned a
+        // `--port`, or on the foreign-port fallback (let vite pick a free one).
+        const spawnArgs = decision.action === "spawn" && !hasExplicitPort(rawArgs)
+            ? [...rawArgs, "--port", String(port), "--strictPort"]
+            : rawArgs;
+        const { done } = spawnInteractive(viteBin, spawnArgs, {
             cwd: studioDir,
-            env: { NWIRE_CWD: process.cwd() },
+            env: { NWIRE_CWD: cwd },
             stoppedMessage: "Studio stopped.",
         });
         process.exit(await done);

package/dist/lib/dev-entry.d.ts

@@ -1,25 +1,24 @@
 /**
  * `resolveDevEntry` — figure out how to boot the project's dev server.
  *
- * Nwire projects come in three shapes, and `nwire dev` needs to work on all
- * of them out of the box (no `nwire.config.ts` required):
+ * Nwire projects come in two shapes, and `nwire dev` works on both out
+ * of the box (no `nwire.config.ts` required):
  *
- *   1. Multi-wire monorepo style — `apps/dev-all/run.ts` runs every app.
- *   2. Single wire under `apps/` — `apps/<name>/{run,main}.ts`.
- *   3. Single-app style — `app/{main,run,index}.ts` (the small-example shape
- *      used by hello-world / todo-app / moderation-queue).
- *   4. Fallback — `package.json` exposes a `scripts.dev` entry; we honor it.
+ *   1. Single wire under `apps/` — `apps/<name>/{run,main}.ts`.
+ *   2. Single-app style — `app/{main,run,index}.ts` (the small-example
+ *      shape used by hello-world / todo-app / moderation-queue).
+ *   3. Fallback — `package.json` exposes a `scripts.dev` entry; we honor it.
  *
  * Returns a discriminated value the caller can spawn directly. The CLI prints
  * a banner before handing off, so the kind + label flow through to the user.
  */
 export type DevEntry = {
-    readonly kind: "vite-node";
+    readonly kind: "wire";
     /** Absolute path to the .ts entry file. */
     readonly entry: string;
     /** Project-relative path of `entry`, for the banner. */
     readonly rel: string;
-    /** Subtitle shown in the banner: dev-all | <wire-name> | app. */
+    /** Subtitle shown in the banner: <wire-name> | app. */
     readonly label: string;
 } | {
     readonly kind: "npm-script";

package/dist/lib/dev-entry.js

@@ -1,14 +1,13 @@
 /**
  * `resolveDevEntry` — figure out how to boot the project's dev server.
  *
- * Nwire projects come in three shapes, and `nwire dev` needs to work on all
- * of them out of the box (no `nwire.config.ts` required):
+ * Nwire projects come in two shapes, and `nwire dev` works on both out
+ * of the box (no `nwire.config.ts` required):
  *
- *   1. Multi-wire monorepo style — `apps/dev-all/run.ts` runs every app.
- *   2. Single wire under `apps/` — `apps/<name>/{run,main}.ts`.
- *   3. Single-app style — `app/{main,run,index}.ts` (the small-example shape
- *      used by hello-world / todo-app / moderation-queue).
- *   4. Fallback — `package.json` exposes a `scripts.dev` entry; we honor it.
+ *   1. Single wire under `apps/` — `apps/<name>/{run,main}.ts`.
+ *   2. Single-app style — `app/{main,run,index}.ts` (the small-example
+ *      shape used by hello-world / todo-app / moderation-queue).
+ *   3. Fallback — `package.json` exposes a `scripts.dev` entry; we honor it.
  *
  * Returns a discriminated value the caller can spawn directly. The CLI prints
  * a banner before handing off, so the kind + label flow through to the user.
@@ -21,17 +20,9 @@ import { relative, resolve } from "node:path";
  * with a clear message listing what was tried.
  */
 export function resolveDevEntry(cwd) {
-    // 1. dev-all (multi-wire dev topology)
-    const devAll = resolve(cwd, "apps/dev-all/run.ts");
-    if (existsSync(devAll)) {
-        return { kind: "vite-node", entry: devAll, rel: relPath(cwd, devAll), label: "dev-all" };
-    }
-    // 2. Single wire under apps/ — accept run.ts OR main.ts.
+    // 1. Single wire under apps/ — accept run.ts OR main.ts.
     const appsDir = resolve(cwd, "apps");
     if (existsSync(appsDir)) {
-        // Cheap enumeration — projects rarely have more than a few entries here.
-        // We don't need detectProject (avoids the import cycle and keeps this
-        // helper focused).
         try {
             const wires = [];
             for (const ent of readdirSync(appsDir, { withFileTypes: true })) {
@@ -47,7 +38,7 @@ export function resolveDevEntry(cwd) {
                 for (const f of ["run.ts", "main.ts"]) {
                     const p = resolve(appsDir, only, f);
                     if (existsSync(p)) {
-                        return { kind: "vite-node", entry: p, rel: relPath(cwd, p), label: only };
+                        return { kind: "wire", entry: p, rel: relPath(cwd, p), label: only };
                     }
                 }
             }
@@ -56,14 +47,25 @@ export function resolveDevEntry(cwd) {
             // ignore — fall through to app/ and scripts
         }
     }
-    // 3. Single-app folder — app/main.ts, app/run.ts, app/index.ts.
+    // 2. Root entry — main.ts / run.ts at the project root (the template shape:
+    //    the file that calls `endpoint().run()` lives at the root, with an
+    //    `app/index.ts` barrel beside it). Checked BEFORE the app/ folder so the
+    //    real entry wins over a barrel that mounts nothing.
+    for (const f of ["main.ts", "run.ts"]) {
+        const p = resolve(cwd, f);
+        if (existsSync(p)) {
+            return { kind: "wire", entry: p, rel: relPath(cwd, p), label: "app" };
+        }
+    }
+    // 3. Single-app folder — app/main.ts, app/run.ts, then the app/index.ts
+    //    barrel as a last resort.
     for (const f of ["app/main.ts", "app/run.ts", "app/index.ts"]) {
         const p = resolve(cwd, f);
         if (existsSync(p)) {
-            return { kind: "vite-node", entry: p, rel: relPath(cwd, p), label: "app" };
+            return { kind: "wire", entry: p, rel: relPath(cwd, p), label: "app" };
         }
     }
-    // 4. package.json scripts.dev fallback.
+    // 3. package.json scripts.dev fallback.
     const pj = resolve(cwd, "package.json");
     if (existsSync(pj)) {
         try {
@@ -82,9 +84,10 @@ export function resolveDevEntry(cwd) {
 /** Same fallback list rendered for the "no dev entry found" error message. */
 export function devEntryCandidates() {
     return [
-        "apps/dev-all/run.ts",
         "apps/<wire>/run.ts",
         "apps/<wire>/main.ts",
+        "main.ts",
+        "run.ts",
         "app/main.ts",
         "app/run.ts",
         "app/index.ts",
@@ -92,10 +95,6 @@ export function devEntryCandidates() {
     ];
 }
 function relPath(cwd, abs) {
-    // `path.relative` already handles the cross-platform `path.sep` story
-    // (Windows backslashes vs POSIX forward slashes) and the
-    // "abs is outside cwd" case (returns a `..` chain) — no manual
-    // `startsWith(cwd + "/")` math needed.
     const rel = relative(cwd, abs);
     return rel === "" ? abs : rel;
 }