veryfront 0.1.1228 → 0.1.1229

package/esm/cli/commands/build/command-help.js

@@ -6,7 +6,7 @@ export const buildHelp = {
     options: [
         {
             flag: "-o, --output <dir>",
-            description: "Output directory",
+            description: "Output directory (also configurable via build.outDir)",
             default: "dist",
         },
         {

package/esm/cli/commands/build/command.d.ts

@@ -1,3 +1,4 @@
+import { type VeryfrontConfig } from "../../../src/config/index.js";
 import type { BuildOptions } from "./types.js";
 /** @internal */
 export declare function runWithBundlerShutdown<T>(operation: () => Promise<T>, stopBundler?: () => Promise<void>): Promise<T>;
@@ -19,5 +20,16 @@ export declare function releaseBuildExtensions(loader: {
     teardownAll: () => Promise<void>;
 } | undefined): Promise<void>;
 export declare function formatBuildOutputPath(projectDir: string, outputDir: string): string;
+/**
+ * Decide where the build writes.
+ *
+ * `-o/--output` wins, then `build.outDir` from veryfront.config.ts, then
+ * `dist`. `build.outDir` used to be read into the config object and dropped:
+ * the build wrote (and cleared) `dist` regardless, with no warning, so the
+ * documented way to keep the framework out of a project's own `dist/` did
+ * nothing. A relative `outDir` resolves against the project directory, which
+ * is how a config file naturally reads.
+ */
+export declare function resolveBuildOutputDir(projectDir: string, explicitOutputDir: string | undefined, config: Pick<VeryfrontConfig, "build">): string;
 export declare function buildCommand(options: BuildOptions): Promise<void>;
 //# sourceMappingURL=command.d.ts.map

package/esm/cli/commands/build/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/command.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,gBAAgB;AAChB,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,GAAE,MAAM,OAAO,CAAC,IAAI,CAG9B,GACA,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,SAAS,GACvD,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwGjE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAQ/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,gBAAgB;AAChB,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,GAAE,MAAM,OAAO,CAAC,IAAI,CAG9B,GACA,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,SAAS,GACvD,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,GACrC,MAAM,CAIR;AAyCD,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4GjE"}

package/esm/cli/commands/build/command.js

@@ -1,6 +1,7 @@
-import { join, relative, resolve } from "../../../src/platform/compat/path/index.js";
+import { isAbsolute, join, relative, resolve } from "../../../src/platform/compat/path/index.js";
 import { runtime } from "../../../src/platform/index.js";
 import { getConfig } from "../../../src/config/index.js";
+import { CONFIG_INVALID } from "../../../src/errors/index.js";
 import { buildProduction } from "../../../src/build/index.js";
 import { withSpan } from "../../../src/observability/tracing/otlp-setup.js";
 import { cliLogger } from "../../utils/index.js";
@@ -62,9 +63,56 @@ export async function releaseBuildExtensions(loader) {
 export function formatBuildOutputPath(projectDir, outputDir) {
     return relative(projectDir, resolve(projectDir, outputDir)).replace(/\\/g, "/");
 }
+/**
+ * Decide where the build writes.
+ *
+ * `-o/--output` wins, then `build.outDir` from veryfront.config.ts, then
+ * `dist`. `build.outDir` used to be read into the config object and dropped:
+ * the build wrote (and cleared) `dist` regardless, with no warning, so the
+ * documented way to keep the framework out of a project's own `dist/` did
+ * nothing. A relative `outDir` resolves against the project directory, which
+ * is how a config file naturally reads.
+ */
+export function resolveBuildOutputDir(projectDir, explicitOutputDir, config) {
+    const outputDir = explicitOutputDir ?? resolveConfiguredOutputDir(projectDir, config);
+    assertOutputDirExcludesProject(projectDir, outputDir, explicitOutputDir !== undefined);
+    return outputDir;
+}
+function resolveConfiguredOutputDir(projectDir, config) {
+    const configured = config.build?.outDir;
+    if (configured === undefined || configured === "")
+        return join(projectDir, "dist");
+    return resolve(projectDir, configured);
+}
+/**
+ * Refuse an output directory that is the project directory or an ancestor of it.
+ *
+ * The build clears its output directory before writing, so an `outDir` of `.`
+ * or `..` would recursively delete the project's own source — or the workspace
+ * above it. That was unreachable while `build.outDir` was ignored; now that the
+ * config value is honored, a stale compatibility-era config could reach it.
+ * Failing loudly is the only safe answer: silently substituting `dist` would
+ * reintroduce the ignored-configuration bug this change exists to fix.
+ */
+function assertOutputDirExcludesProject(projectDir, outputDir, fromFlag) {
+    const resolvedOutput = resolve(projectDir, outputDir);
+    const relativeToOutput = relative(resolvedOutput, resolve(projectDir));
+    const containsProject = relativeToOutput === "" ||
+        (!relativeToOutput.startsWith("..") && !isAbsolute(relativeToOutput));
+    if (!containsProject)
+        return;
+    const source = fromFlag ? "-o/--output" : "build.outDir";
+    throw CONFIG_INVALID.create({
+        detail: `${source} resolves to ${resolvedOutput}, which is the project directory or contains it. ` +
+            `The build clears its output directory before writing, so this would delete the project. ` +
+            `Point the build at a directory of its own, such as dist.`,
+    });
+}
 export function buildCommand(options) {
     return withSpan("cli.command.build", async () => {
-        const outputDir = options.outputDir ?? join(options.projectDir, "dist");
+        // Placeholder until the config is loaded; every path that reports or
+        // writes the output directory runs after resolveBuildOutputDir below.
+        let outputDir = options.outputDir ?? join(options.projectDir, "dist");
         const startTime = Date.now();
         const dryRun = options.dryRun ?? false;
         let extensions;
@@ -79,12 +127,14 @@ export function buildCommand(options) {
             if (isJsonMode()) {
                 streamJsonLine({ type: "step", name: "config", status: "started" });
             }
-            else {
-                displayBuildConfig({ ...options, outputDir });
-            }
             const stats = await runWithBundlerShutdown(async () => {
                 const adapter = await runtime.get();
                 const config = await getConfig(options.projectDir, adapter);
+                // Resolved from the loaded config, so the displayed, reported and
+                // written output directory are the same one.
+                outputDir = resolveBuildOutputDir(options.projectDir, options.outputDir, config);
+                if (!isJsonMode())
+                    displayBuildConfig({ ...options, outputDir });
                 // Compose the project's extensions before anything that resolves a
                 // contract. Only server bootstrap used to do this, so the build ran
                 // with whatever one-off shims had been added and failed on the rest.

package/esm/cli/commands/demo/demo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/demo/demo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2DH,KAAK,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAsa9D,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AA+DD,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmH1E"}
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/demo/demo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2DH,KAAK,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAsZ9D,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AA+DD,wBAAsB,WAAW,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmH1E"}

package/esm/cli/commands/demo/demo.js

@@ -5,7 +5,7 @@
  */
 import { chdir, cwd, promptSync, writeStdout } from "../../../src/platform/index.js";
 import { getStdinReader, setRawMode } from "../../../src/platform/index.js";
-import { AnimatedDotMatrix, bold, brand, BRAND_TRUECOLOR, dim, error, formatDuration, HIDE_CURSOR, muted, SHOW_CURSOR, success, successBanner, typeCommand, typeLine, } from "../../ui/index.js";
+import { AnimatedDotMatrix, bold, brand, BRAND_TRUECOLOR, dim, error, formatDuration, HIDE_CURSOR, muted, SHOW_CURSOR, successBanner, typeCommand, typeLine, } from "../../ui/index.js";
 import { exitProcess, isTTY, logError } from "../../utils/index.js";
 import { createOAuthAuthorizationUrl, createOAuthState, readToken, saveToken, validateToken, } from "../../auth/index.js";
 import { canOpenBrowser, openBrowser } from "../../auth/browser.js";
@@ -21,6 +21,7 @@ import { resolveOrCreateProject } from "../../shared/project-resolution.js";
 import { getProjectTarget } from "../../shared/deployment-provenance.js";
 import { reserveProjectSlug } from "../../shared/reserve-slug.js";
 import { DEMO_STEPS } from "./steps.js";
+import { runDemoDevStep } from "./dev-step.js";
 // ANSI escape codes
 const ESC = "\x1b";
 const CLEAR_SCREEN = `${ESC}[2J`;
@@ -336,29 +337,17 @@ async function executeStepAction(step, projectName, loginMethod) {
             console.log();
             console.log(`  ${dim("Starting dev server...")}`);
             try {
-                const result = await devCommand({
-                    port: 3000,
-                    projectDir,
-                    hmr: true,
-                    demoMode: true,
+                await runDemoDevStep({
+                    start: () => devCommand({
+                        port: 3000,
+                        projectDir,
+                        hmr: true,
+                        demoMode: true,
+                    }),
+                    open: (url) => openBrowser(url),
+                    waitForStop: () => waitForEnter(),
+                    log: (line) => console.log(line),
                 });
-                await result.ready;
-                console.log(`  ${success("●")} ${brand("http://localhost:3000/")}`);
-                console.log();
-                console.log(`  ${dim("Opening browser...")}`);
-                try {
-                    await openBrowser("http://localhost:3000");
-                }
-                catch {
-                    // Ignore if browser can't be opened
-                }
-                console.log();
-                console.log(`  ${dim("Press Enter to stop the dev server and continue...")}`);
-                await waitForEnter();
-                console.log();
-                console.log(`  ${dim("Stopping dev server...")}`);
-                await result.stop();
-                await result.done;
             }
             catch (e) {
                 console.log(`  ${error("✗")} ${e instanceof Error ? e.message : String(e)}`);

package/esm/cli/commands/demo/dev-step.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The demo's dev-server step.
+ *
+ * Lives apart from `demo.ts` so the address the demo shows and opens can be
+ * tested without booting a dev server, a browser, or stdin.
+ *
+ * @module cli/commands/demo/dev-step
+ */
+import type { DevCommandResult } from "../dev/index.js";
+export interface DemoDevStepDeps {
+    /** Starts the dev server. */
+    start: () => Promise<DevCommandResult>;
+    /** Opens the demo's browser at the given URL. */
+    open: (url: string) => Promise<unknown>;
+    /** Resolves when the viewer asks for the dev server to stop. */
+    waitForStop: () => Promise<unknown>;
+    /** Writes one line of demo output. */
+    log: (line: string) => void;
+}
+/**
+ * Shows the running dev server, opens it, then stops it on request.
+ *
+ * Both the printed URL and the opened URL come from `result.port` - the port
+ * the server actually bound. `veryfront dev` asks for 3000 but falls forward
+ * when that is taken, so keying off the requested port would send the viewer to
+ * whatever process caused the collision instead of to the demo.
+ */
+export declare function runDemoDevStep(deps: DemoDevStepDeps): Promise<void>;
+//# sourceMappingURL=dev-step.d.ts.map

package/esm/cli/commands/demo/dev-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-step.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/demo/dev-step.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvC,iDAAiD;IACjD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,gEAAgE;IAChE,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,sCAAsC;IACtC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzE"}

package/esm/cli/commands/demo/dev-step.js

@@ -0,0 +1,38 @@
+/**
+ * The demo's dev-server step.
+ *
+ * Lives apart from `demo.ts` so the address the demo shows and opens can be
+ * tested without booting a dev server, a browser, or stdin.
+ *
+ * @module cli/commands/demo/dev-step
+ */
+import { brand, dim, success } from "../../ui/index.js";
+/**
+ * Shows the running dev server, opens it, then stops it on request.
+ *
+ * Both the printed URL and the opened URL come from `result.port` - the port
+ * the server actually bound. `veryfront dev` asks for 3000 but falls forward
+ * when that is taken, so keying off the requested port would send the viewer to
+ * whatever process caused the collision instead of to the demo.
+ */
+export async function runDemoDevStep(deps) {
+    const result = await deps.start();
+    await result.ready;
+    const serverUrl = `http://localhost:${result.port}`;
+    deps.log(`  ${success("●")} ${brand(`${serverUrl}/`)}`);
+    deps.log("");
+    deps.log(`  ${dim("Opening browser...")}`);
+    try {
+        await deps.open(serverUrl);
+    }
+    catch {
+        // Ignore if browser can't be opened
+    }
+    deps.log("");
+    deps.log(`  ${dim("Press Enter to stop the dev server and continue...")}`);
+    await deps.waitForStop();
+    deps.log("");
+    deps.log(`  ${dim("Stopping dev server...")}`);
+    await result.stop();
+    await result.done;
+}

package/esm/cli/commands/dev/command.d.ts

@@ -11,11 +11,24 @@ export interface DevOptions {
     open?: boolean;
     /** Demo mode: don't exit process on shutdown, resolve done promise instead */
     demoMode?: boolean;
+    /**
+     * Clear the shared on-disk ESM caches before starting. Only honoured once the
+     * requested dev port is confirmed free, because the cache directory is shared
+     * with any dev server already serving this project.
+     */
+    clearLocalCaches?: boolean;
 }
 export type DevCommandOptions = DevOptions;
 export interface DevCommandResult {
     ready: Promise<void>;
     done: Promise<void>;
+    /**
+     * The port the server actually bound, which is not always the requested one:
+     * a taken port falls forward. Embedded callers must use this rather than the
+     * port they asked for, or they will point the user at the process that caused
+     * the collision.
+     */
+    port: number;
     /** Stop the dev server programmatically (for demo mode) */
     stop: () => Promise<void>;
 }
@@ -24,5 +37,38 @@ export declare function preloadDevAuth(apiToken?: string): Promise<{
     projects: RemoteProject[];
 }>;
 export declare function createSelectedProjectPushOptions(projectDir: string, project: RemoteProject): PushOptions;
+/**
+ * Starts the dev server on the first free port at or after `requestedPort`.
+ *
+ * Port 3000 is the most contended port on a developer machine, and the docs
+ * tell readers to run a bare `veryfront dev`, so a taken port scans forward
+ * rather than killing the command. Everything downstream - the MCP port, the
+ * printed URL, the browser the demo opens - must key off the returned `port`
+ * rather than the requested one, or a fall-forward points the user at the
+ * process that caused the collision.
+ *
+ * Takes `start` as a callback so the whole scan costs one `DevServer.start()`:
+ * probing is a bare bind/release, and a failed `start()` has already registered
+ * watchers and reload subscriptions that only `stop()` releases.
+ */
+export declare function startDevServerOnFreePort<T>(requestedPort: number, start: (port: number) => Promise<T>): Promise<{
+    server: T;
+    port: number;
+}>;
+/**
+ * Clears the shared on-disk ESM caches, but only if `requestedPort` is free.
+ *
+ * The caches live under the project's `.cache` directory, which every dev
+ * server rooted at that project shares. A taken dev port is the signal that one
+ * of them is already running and still serving modules it compiled, so the
+ * clear is skipped rather than wiping that server's work out from under it -
+ * the second `veryfront dev` falls forward to a free port and starts on a cache
+ * it did not just destroy.
+ *
+ * Returns whether the clear ran. Takes `clear` and `probe` as parameters so the
+ * decision can be tested without booting a dev server, the same seam
+ * `startDevServerOnFreePort` uses.
+ */
+export declare function clearLocalCachesIfPortFree(requestedPort: number, clear?: () => Promise<void>, probe?: (port: number) => Promise<boolean>): Promise<boolean>;
 export declare function devCommand(options: DevOptions): Promise<DevCommandResult>;
 //# sourceMappingURL=command.d.ts.map

package/esm/cli/commands/dev/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI1F,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAQD,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAQvE;AAED,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,GACrB,WAAW,CAEb;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwRzE"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK1F,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAQD,wBAAsB,cAAc,CAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAQvE;AAED,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,GACrB,WAAW,CAEb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,MAAM,OAAO,CAAC,IAAI,CAAuB,EAChD,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAmB,GAC1D,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyRzE"}

package/esm/cli/commands/dev/command.js

@@ -2,12 +2,13 @@
  * Dev Command - Development server with HMR
  */
 import { compileAllMDX, watchMDX } from "../../../src/build/index.js";
-import { CONFIG_NOT_FOUND, INITIALIZATION_ERROR } from "../../../src/errors/index.js";
+import { CONFIG_NOT_FOUND, PORT_IN_USE } from "../../../src/errors/index.js";
 import { join } from "../../../src/platform/compat/path/index.js";
 import { runtime } from "../../../src/platform/index.js";
 import { getConfig } from "../../../src/config/index.js";
 import { getEnvironmentConfig } from "../../../src/config/index.js";
 import { startDevServer } from "../../../src/server/index.js";
+import { clearAllLocalCaches } from "../../../src/transforms/mdx/esm-module-loader/cache/index.js";
 import { validateProviderConfig } from "../../../src/discovery/index.js";
 import { brand, devShortcuts, dim, error as errorColor, formatDuration, warning } from "../../ui/index.js";
 import { exitProcess, isTTY, isVerbose, registerTerminationSignals } from "../../utils/index.js";
@@ -23,6 +24,7 @@ import { pullCommand } from "../pull/index.js";
 import { createStagedPushOptions, pushCommand } from "../push/index.js";
 import { createProjectSelector } from "./project-selector.js";
 import { createDevLogController } from "./log-controller.js";
+import { findAvailablePort, isPortAvailable, isPortInUseError } from "./port-fallback.js";
 function authStatus(identity) {
     return isApiKeyIdentity(identity)
         ? "Authenticated with an API key"
@@ -40,9 +42,64 @@ export async function preloadDevAuth(apiToken) {
 export function createSelectedProjectPushOptions(projectDir, project) {
     return createStagedPushOptions(project.slug, projectDir);
 }
+/**
+ * Starts the dev server on the first free port at or after `requestedPort`.
+ *
+ * Port 3000 is the most contended port on a developer machine, and the docs
+ * tell readers to run a bare `veryfront dev`, so a taken port scans forward
+ * rather than killing the command. Everything downstream - the MCP port, the
+ * printed URL, the browser the demo opens - must key off the returned `port`
+ * rather than the requested one, or a fall-forward points the user at the
+ * process that caused the collision.
+ *
+ * Takes `start` as a callback so the whole scan costs one `DevServer.start()`:
+ * probing is a bare bind/release, and a failed `start()` has already registered
+ * watchers and reload subscriptions that only `stop()` releases.
+ */
+export async function startDevServerOnFreePort(requestedPort, start) {
+    const port = await findAvailablePort(requestedPort);
+    if (port !== requestedPort) {
+        console.log();
+        console.log(`  ${warning("!")} Port ${requestedPort} is in use, using ${port} instead`);
+    }
+    try {
+        return { server: await start(port), port };
+    }
+    catch (error) {
+        // Lost the race between probing the port and binding it.
+        if (isPortInUseError(error)) {
+            throw PORT_IN_USE.create({
+                detail: `Port ${port} is already in use`,
+                cause: error,
+                context: { port },
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Clears the shared on-disk ESM caches, but only if `requestedPort` is free.
+ *
+ * The caches live under the project's `.cache` directory, which every dev
+ * server rooted at that project shares. A taken dev port is the signal that one
+ * of them is already running and still serving modules it compiled, so the
+ * clear is skipped rather than wiping that server's work out from under it -
+ * the second `veryfront dev` falls forward to a free port and starts on a cache
+ * it did not just destroy.
+ *
+ * Returns whether the clear ran. Takes `clear` and `probe` as parameters so the
+ * decision can be tested without booting a dev server, the same seam
+ * `startDevServerOnFreePort` uses.
+ */
+export async function clearLocalCachesIfPortFree(requestedPort, clear = clearAllLocalCaches, probe = isPortAvailable) {
+    if (!await probe(requestedPort))
+        return false;
+    await clear();
+    return true;
+}
 export function devCommand(options) {
     return withSpan("cli.command.dev", async () => {
-        const { port, projectDir, hmr = true, open = false, demoMode = false } = options;
+        const { port, projectDir, hmr = true, open = false, demoMode = false, clearLocalCaches = false, } = options;
         const startTime = Date.now();
         let doneResolve;
         const done = new Promise((resolve) => {
@@ -65,6 +122,8 @@ export function devCommand(options) {
         const DEFAULT_DEV_PORT = 3000;
         const finalPort = port !== DEFAULT_DEV_PORT ? port : (config?.dev?.port ?? port);
         const enableHMR = config?.dev?.hmr !== false && hmr;
+        if (clearLocalCaches)
+            await clearLocalCachesIfPortFree(finalPort);
         const env = getEnvironmentConfig();
         const isProxyMode = config?.fs?.veryfront?.proxyMode === true;
         const linkedProjectSlug = await resolveLinkedProjectSlug(projectDir, config?.projectSlug ?? config?.fs?.veryfront?.projectSlug ?? env.projectSlug);
@@ -101,29 +160,17 @@ export function devCommand(options) {
         let identity = null;
         let projects = [];
         let selectedProject = null;
-        try {
-            devServer = await startDevServer({
-                port: finalPort,
-                projectDir,
-                enableHMR,
-                enableFastRefresh: true,
-                signal: shutdownController.signal,
-            });
-        }
-        catch (error) {
-            if (error instanceof Error) {
-                const msg = error.message.toLowerCase();
-                if (msg.includes("eaddrinuse") || msg.includes("address already in use")) {
-                    throw INITIALIZATION_ERROR.create({
-                        detail: `Port ${finalPort} is already in use`,
-                        context: { port: finalPort },
-                    });
-                }
-            }
-            throw error;
-        }
+        const started = await startDevServerOnFreePort(finalPort, (port) => startDevServer({
+            port,
+            projectDir,
+            enableHMR,
+            enableFastRefresh: true,
+            signal: shutdownController.signal,
+        }));
+        devServer = started.server;
+        const boundPort = started.port;
         const DEV_MCP_PORT_OFFSET = 2;
-        const mcpPort = finalPort + DEV_MCP_PORT_OFFSET;
+        const mcpPort = boundPort + DEV_MCP_PORT_OFFSET;
         try {
             mcpServer = await createMCPServer({ httpPort: mcpPort });
         }
@@ -196,10 +243,11 @@ export function devCommand(options) {
             return {
                 ready: devServer.ready,
                 done,
+                port: boundPort,
                 stop: shutdown,
             };
         }
-        const serverUrl = `http://veryfront.me:${finalPort}`;
+        const serverUrl = `http://veryfront.me:${boundPort}`;
         const elapsed = Date.now() - startTime;
         console.log();
         console.log(`  ✓ Ready in ${formatDuration(elapsed)}`);
@@ -275,6 +323,7 @@ export function devCommand(options) {
         return {
             ready: devServer.ready,
             done,
+            port: boundPort,
             stop: shutdown,
         };
     }, {

package/esm/cli/commands/dev/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAexD,eAAO,MAAM,YAAY;;;;;;;GAOvB,CAAC;AAwBH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BtE"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAexD,eAAO,MAAM,YAAY;;;;;;;GAOvB,CAAC;AAwBH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BtE"}

package/esm/cli/commands/dev/handler.js

@@ -7,7 +7,6 @@ import { cwd, setEnv } from "../../../src/platform/index.js";
 import { createFileSystem } from "../../../src/platform/index.js";
 import { cliLogger, DEFAULT_DEV_SERVER_PORT, showHeader } from "../../utils/index.js";
 import { refreshLoggerConfig } from "../../../src/utils/index.js";
-import { clearAllLocalCaches } from "../../../src/transforms/mdx/esm-module-loader/cache/index.js";
 import { createArgParser, parseArgsOrThrow } from "../../shared/args.js";
 import { ensureCliBundlerContracts } from "../../shared/default-contracts.js";
 const getDevArgsSchema = defineSchema((v) => v.object({
@@ -54,14 +53,17 @@ export async function handleDevCommand(args) {
         setEnv("VERYFRONT_DEBUG", "1");
         refreshLoggerConfig();
     }
-    // Clear stale ESM caches to prevent module resolution issues from previous runs
-    await clearAllLocalCaches();
     const { devCommand } = await import("./index.js");
     const { done } = await devCommand({
         port: opts.port,
         projectDir,
         hmr: opts.hmr && !opts.noHmr,
         open: opts.open,
+        // Clear stale ESM caches to prevent module resolution issues from previous
+        // runs. devCommand does this only once it has resolved the dev port and
+        // found it free — the caches are shared with any dev server already running
+        // against this project.
+        clearLocalCaches: true,
     });
     // Block until the dev server shuts down.
     // Without this, main.ts reaches exitProcess(0) and terminates immediately.

package/esm/cli/commands/dev/port-fallback.d.ts

@@ -0,0 +1,22 @@
+/** How many consecutive ports to try before giving up. */
+export declare const MAX_PORT_FALLBACK_ATTEMPTS = 10;
+/** The highest port a TCP listener can bind. */
+export declare const MAX_TCP_PORT = 65535;
+/** True when `error` means "that port is taken", on either Deno or Node. */
+export declare function isPortInUseError(error: unknown): boolean;
+/** Binds `port` and releases it again, to see whether the dev server could have it. */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Returns `requestedPort`, or the first free port after it.
+ *
+ * The scan stops at `MAX_TCP_PORT`: a runtime rejects port 65536 as an invalid
+ * port rather than as an address in use, so scanning past the end of the range
+ * would let that raw error escape instead of the `PORT_IN_USE` below.
+ * `requestedPort` itself is always probed, so an out-of-range `--port` still
+ * surfaces the runtime's own complaint about the value the user passed.
+ *
+ * Throws `PORT_IN_USE` - whose suggestion names `--port` - once the whole scan
+ * range is taken.
+ */
+export declare function findAvailablePort(requestedPort: number, maxAttempts?: number, probe?: (port: number) => Promise<boolean>): Promise<number>;
+//# sourceMappingURL=port-fallback.d.ts.map

package/esm/cli/commands/dev/port-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-fallback.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/dev/port-fallback.ts"],"names":[],"mappings":"AAoBA,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,gDAAgD;AAChD,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQxD;AAED,uFAAuF;AACvF,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,MAAM,EACrB,WAAW,GAAE,MAAmC,EAChD,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAmB,GAC1D,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/esm/cli/commands/dev/port-fallback.js

@@ -0,0 +1,89 @@
+/**
+ * Dev server port selection.
+ *
+ * Port 3000 is the most contended port on a developer machine, and the
+ * getting-started docs tell readers to run a bare `veryfront dev`. Rather than
+ * hard-failing when that port is taken, scan forward for the first free one -
+ * the same fallback the login callback server already uses.
+ *
+ * The scan probes ports by binding and releasing them, rather than by retrying
+ * `startDevServer`: a failed `DevServer.start()` has already registered file
+ * watchers and reload subscriptions that only `stop()` releases, so retrying it
+ * would leak a watcher set per busy port.
+ */
+import * as dntShim from "../../../_dnt.shims.js";
+import { LOCALHOST } from "../../../src/config/index.js";
+import { PORT_IN_USE } from "../../../src/errors/index.js";
+import { isDeno } from "../../../src/platform/index.js";
+/** How many consecutive ports to try before giving up. */
+export const MAX_PORT_FALLBACK_ATTEMPTS = 10;
+/** The highest port a TCP listener can bind. */
+export const MAX_TCP_PORT = 65535;
+/** True when `error` means "that port is taken", on either Deno or Node. */
+export function isPortInUseError(error) {
+    if (!(error instanceof Error))
+        return false;
+    // Deno: name is "AddrInUse", message "Address already in use (os error 48)".
+    // Node: code is "EADDRINUSE".
+    const code = error.code ?? "";
+    const message = error.message.toLowerCase();
+    return error.name === "AddrInUse" || code === "EADDRINUSE" ||
+        message.includes("eaddrinuse") || message.includes("address already in use");
+}
+/** Binds `port` and releases it again, to see whether the dev server could have it. */
+export async function isPortAvailable(port) {
+    if (isDeno) {
+        try {
+            // @ts-ignore - Deno global
+            dntShim.Deno.listen({ hostname: LOCALHOST.IPV4, port }).close();
+            return true;
+        }
+        catch (error) {
+            if (isPortInUseError(error))
+                return false;
+            throw error;
+        }
+    }
+    const net = await import("node:net");
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref?.();
+        server.once("error", (error) => {
+            if (isPortInUseError(error))
+                resolve(false);
+            else
+                reject(error);
+        });
+        server.listen({ port, host: LOCALHOST.IPV4, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/**
+ * Returns `requestedPort`, or the first free port after it.
+ *
+ * The scan stops at `MAX_TCP_PORT`: a runtime rejects port 65536 as an invalid
+ * port rather than as an address in use, so scanning past the end of the range
+ * would let that raw error escape instead of the `PORT_IN_USE` below.
+ * `requestedPort` itself is always probed, so an out-of-range `--port` still
+ * surfaces the runtime's own complaint about the value the user passed.
+ *
+ * Throws `PORT_IN_USE` - whose suggestion names `--port` - once the whole scan
+ * range is taken.
+ */
+export async function findAvailablePort(requestedPort, maxAttempts = MAX_PORT_FALLBACK_ATTEMPTS, probe = isPortAvailable) {
+    const attempts = Math.max(1, maxAttempts);
+    let lastPort = requestedPort;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const port = requestedPort + attempt;
+        if (attempt > 0 && port > MAX_TCP_PORT)
+            break;
+        if (await probe(port))
+            return port;
+        lastPort = port;
+    }
+    throw PORT_IN_USE.create({
+        detail: `Ports ${requestedPort}-${lastPort} are all in use`,
+        context: { requestedPort, lastPort, attempts },
+    });
+}

package/esm/cli/commands/doctor/ai-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-checks.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/doctor/ai-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyDnF"}
+{"version":3,"file":"ai-checks.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/doctor/ai-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAuDnD;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA6EnF"}