veryfront 0.1.1239 → 0.1.1241

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

@@ -1 +1 @@
-{"version":3,"file":"command-help.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/command-help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,eAAO,MAAM,SAAS,EAAE,WAoDvB,CAAC"}
+{"version":3,"file":"command-help.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/command-help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,eAAO,MAAM,SAAS,EAAE,WAwDvB,CAAC"}

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

@@ -42,6 +42,10 @@ export const buildHelp = {
             description: "Select build preset (e.g. embedded)",
         },
     ],
+    notes: [
+        "--preset embedded emits a single bundle, so of the build flags it honours only -o/--output and build.outDir. Global flags such as --json, --verbose and --quiet are unaffected.",
+        "It rejects --dry-run, --split/--no-split, --compress/--no-compress, --prefetch, --ssg/--no-ssg, --include and --exclude rather than ignoring them.",
+    ],
     examples: [
         "veryfront build",
         "veryfront build --output dist",

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

@@ -30,6 +30,8 @@ export declare function formatBuildOutputPath(projectDir: string, outputDir: str
  * 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 resolveBuildOutputDir(projectDir: string, explicitOutputDir: string | undefined, config: Pick<VeryfrontConfig, "build">, options?: {
+    clearsOutputDir?: boolean;
+}): 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":"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"}
+{"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,EACtC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,MAAM,CASR;AA4CD,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4GjE"}

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

@@ -73,9 +73,14 @@ export function formatBuildOutputPath(projectDir, outputDir) {
  * nothing. A relative `outDir` resolves against the project directory, which
  * is how a config file naturally reads.
  */
-export function resolveBuildOutputDir(projectDir, explicitOutputDir, config) {
+export function resolveBuildOutputDir(projectDir, explicitOutputDir, config, options = {}) {
     const outputDir = explicitOutputDir ?? resolveConfiguredOutputDir(projectDir, config);
-    assertOutputDirExcludesProject(projectDir, outputDir, explicitOutputDir !== undefined);
+    // The guard below exists because the caller wipes the directory first. A
+    // caller that only writes into it is not dangerous, and rejecting it would
+    // block legitimate invocations — see the embedded preset.
+    if (options.clearsOutputDir !== false) {
+        assertOutputDirExcludesProject(projectDir, outputDir, explicitOutputDir !== undefined);
+    }
     return outputDir;
 }
 function resolveConfiguredOutputDir(projectDir, config) {
@@ -87,9 +92,12 @@ function resolveConfiguredOutputDir(projectDir, config) {
 /**
  * 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
+ * The production build clears its output directory before writing
+ * (`build-setup.ts` removes it recursively), so an `outDir` of `.` or `..`
+ * would recursively delete the project's own source — or the workspace above
+ * it. This is why the check is opt-out via `clearsOutputDir`: a caller that
+ * only writes into the directory, like the embedded preset, carries no such
+ * risk and must not be blocked. 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.

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

@@ -52,5 +52,22 @@ export declare const parseBuildArgs: (args: ParsedArgs) => import("../../shared/
     exclude: import("../../../src/internal-agents/schema.js").Schema<string[] | undefined>;
     dryRun: import("../../../src/internal-agents/schema.js").Schema<boolean>;
 }>>;
+/**
+ * Refuse an embedded build that was given a flag the preset cannot honour.
+ *
+ * Reads `__explicit` from the *raw* args rather than the parsed options on
+ * purpose. The schema defaults `split`, `compress` and `prefetch` to `true`
+ * and `dryRun`, `noSplit`, `noCompress` and `noSsg` to `false`, so the parsed
+ * object cannot tell a typed flag from a default — keying off it would reject
+ * every embedded build, including a bare one.
+ *
+ * The message starts with `Invalid ` so the router maps it to exit code 2 as a
+ * usage error, matching `parseArgsOrThrow`.
+ *
+ * @param args raw parsed argv, carrying `__explicit`
+ * @param preset the lowercased `--preset` value, if any
+ * @internal
+ */
+export declare function assertEmbeddedPresetFlags(args: ParsedArgs, preset: string | undefined): void;
 export declare function handleBuildCommand(args: ParsedArgs): Promise<void>;
 //# sourceMappingURL=handler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAQ3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;GAe9B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;;;;;;;GAAiC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;GAaA,CAAC;AAE5B,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BxE"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/build/handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAO3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;GAe9B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;;;;;;;GAAiC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;GAaA,CAAC;AA6B5B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,CAYN;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCxE"}

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

@@ -1,12 +1,12 @@
 import { defineSchema, lazySchema } from "../../../src/schemas/index.js";
 import { dim } from "../../ui/index.js";
-import { join } from "../../../src/platform/compat/path/index.js";
 import { cliLogger, isVerbose, logSuccess } from "../../utils/index.js";
-import { cwd } from "../../../src/platform/index.js";
+import { cwd, runtime } from "../../../src/platform/index.js";
 import { CommonArgs, createArgParser, parseArgsOrThrow } from "../../shared/args.js";
 import { ensureCliBundlerContracts } from "../../shared/default-contracts.js";
 import { showHeader } from "../../utils/index.js";
 import { ensureBuiltinContentProcessor } from "../../shared/ensure-content-processor.js";
+import { isJsonMode, streamJsonLine } from "../../shared/json-output.js";
 /**
  * Schema factory for build command arguments
  */
@@ -42,12 +42,68 @@ export const parseBuildArgs = createArgParser(BuildArgsSchema, {
     exclude: { keys: ["exclude"], type: "array" },
     dryRun: CommonArgs.dryRun,
 }, { rejectUnknown: true });
+/**
+ * Flags the embedded preset cannot honour, in the spelling the user types.
+ *
+ * The embedded preset emits one esbuild bundle: there is nothing to split,
+ * no compression pass, no prefetch manifest and no prerender step, so
+ * `--split`, `--compress`, `--prefetch`, `--ssg`, `--include` and `--exclude`
+ * describe stages it does not have. `--dry-run` is different in kind — the
+ * preset simply never implemented it, and a flag whose whole contract is
+ * "changes nothing" writing to disk is the worst outcome of the three.
+ *
+ * Rejecting is the honest answer for all of them. Accepting a flag and
+ * dropping it, which is what this path used to do, tells the user the build
+ * ran the way they asked when it did not.
+ */
+const UNSUPPORTED_EMBEDDED_FLAGS = [
+    "dry-run",
+    "split",
+    "no-split",
+    "compress",
+    "no-compress",
+    "prefetch",
+    "ssg",
+    "no-ssg",
+    "include",
+    "exclude",
+];
+/**
+ * Refuse an embedded build that was given a flag the preset cannot honour.
+ *
+ * Reads `__explicit` from the *raw* args rather than the parsed options on
+ * purpose. The schema defaults `split`, `compress` and `prefetch` to `true`
+ * and `dryRun`, `noSplit`, `noCompress` and `noSsg` to `false`, so the parsed
+ * object cannot tell a typed flag from a default — keying off it would reject
+ * every embedded build, including a bare one.
+ *
+ * The message starts with `Invalid ` so the router maps it to exit code 2 as a
+ * usage error, matching `parseArgsOrThrow`.
+ *
+ * @param args raw parsed argv, carrying `__explicit`
+ * @param preset the lowercased `--preset` value, if any
+ * @internal
+ */
+export function assertEmbeddedPresetFlags(args, preset) {
+    if (preset !== "embedded")
+        return;
+    const explicit = args.__explicit ?? {};
+    const unsupported = UNSUPPORTED_EMBEDDED_FLAGS
+        .filter((flag) => explicit[flag] === true)
+        .map((flag) => `--${flag}`);
+    if (unsupported.length === 0)
+        return;
+    throw new Error(`Invalid build arguments: the embedded preset does not support ${unsupported.join(", ")}`);
+}
 export async function handleBuildCommand(args) {
     showHeader();
     const opts = parseArgsOrThrow(parseBuildArgs, "build", args);
+    const preset = opts.preset?.toLowerCase();
+    // Before any bundler setup, so a rejected build touches nothing and returns
+    // immediately.
+    assertEmbeddedPresetFlags(args, preset);
     await ensureCliBundlerContracts();
     const projectDir = cwd();
-    const preset = opts.preset?.toLowerCase();
     if (preset === "embedded") {
         await ensureBuiltinContentProcessor();
         await handleEmbeddedBuild(projectDir, opts.output);
@@ -69,19 +125,142 @@ export async function handleBuildCommand(args) {
         dryRun: opts.dryRun,
     });
 }
+/** The synthetic shell route `buildEmbeddedPreset` prepends to every manifest. */
+const EMBEDDED_APP_SHELL_FILE = "embedded/app.js";
+/**
+ * Total bytes of the artifacts the embedded manifest declares.
+ *
+ * The production build reports the size of what it emitted, so the embedded
+ * preset reports the same thing rather than leaving the field at zero. The
+ * manifest is the artifact list, so it cannot drift from what was written.
+ * A file the preset failed to emit is skipped: `buildEmbeddedPreset` only warns
+ * when an RSC bundle or a route fails, and a size roll-up must not turn that
+ * warning into a hard error.
+ */
+async function sumEmbeddedOutputSize(outDir, manifest) {
+    const { join } = await import("../../../src/platform/compat/path/index.js");
+    const { createFileSystem } = await import("../../../src/platform/index.js");
+    const fs = createFileSystem();
+    const files = new Set(["embedded/manifest.json"]);
+    for (const route of manifest.routes)
+        files.add(route.file);
+    for (const asset of manifest.assets)
+        files.add(asset.file);
+    let total = 0;
+    for (const file of files) {
+        try {
+            total += (await fs.stat(join(outDir, file))).size;
+        }
+        catch {
+            // Not emitted — already reported by the preset as a warning.
+        }
+    }
+    return total;
+}
+/**
+ * Run the embedded build, terminating the NDJSON stream ourselves in JSON mode.
+ *
+ * Once a `step` line has reached stdout, the router's error envelope must not
+ * also be written: it is a different, multi-line shape, so a consumer gets a
+ * partial NDJSON stream followed by something that is not NDJSON at all. The
+ * default path solves this by streaming its own `result` and calling `exit(1)`
+ * rather than rethrowing, and this matches it — including for failures in the
+ * config phase, which happen after the first `step` line is already out.
+ */
 async function handleEmbeddedBuild(projectDir, outputDir) {
+    if (!isJsonMode()) {
+        await runEmbeddedBuild(projectDir, outputDir);
+        return;
+    }
+    try {
+        await runEmbeddedBuild(projectDir, outputDir);
+    }
+    catch (error) {
+        streamJsonLine({
+            type: "result",
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        const { exit } = await import("../../../src/platform/index.js");
+        exit(1);
+    }
+}
+async function runEmbeddedBuild(projectDir, outputDir) {
     const { buildEmbeddedPreset } = await import("../../../src/build/index.js");
-    const finalOutput = outputDir ?? join(projectDir, "dist");
-    cliLogger.info("Building embedded preset...");
-    if (isVerbose()) {
-        cliLogger.info(`  ${dim("Project:")} ${projectDir}`);
-        cliLogger.info(`  ${dim("Output:")} ${finalOutput}`);
+    const { getConfig } = await import("../../../src/config/index.js");
+    const { resolveBuildOutputDir } = await import("./command.js");
+    const startTime = Date.now();
+    // Failures are terminated by the caller, which streams the error result and
+    // exits rather than letting the router print a second envelope.
+    const json = isJsonMode();
+    if (json)
+        streamJsonLine({ type: "step", name: "config", status: "started" });
+    // The config was never loaded on this path, so `build.outDir` was ignored
+    // and the preset always wrote `dist`. Resolving through the same helper the
+    // default path uses also brings its guard against an output directory that
+    // contains the project.
+    const adapter = await runtime.get();
+    const config = await getConfig(projectDir, adapter);
+    // `clearsOutputDir: false` because `buildEmbeddedPreset` only mkdir's and
+    // writes into the target; unlike the production build it never removes it.
+    // Without this, `--preset embedded -o .` — a plausible call for a preset
+    // whose whole purpose is embedding into a host project — hard-fails on a
+    // deletion hazard that does not exist on this path.
+    const finalOutput = resolveBuildOutputDir(projectDir, outputDir, config, {
+        clearsOutputDir: false,
+    });
+    if (json) {
+        streamJsonLine({ type: "step", name: "config", status: "completed" });
+        streamJsonLine({ type: "step", name: "build", status: "started" });
     }
-    await buildEmbeddedPreset({
+    else {
+        cliLogger.info("Building embedded preset...");
+        if (isVerbose()) {
+            cliLogger.info(`  ${dim("Project:")} ${projectDir}`);
+            cliLogger.info(`  ${dim("Output:")} ${finalOutput}`);
+        }
+    }
+    const { manifest } = await buildEmbeddedPreset({
         projectDir,
         outDir: finalOutput,
         runtime: "deno",
+        config,
     });
+    if (json) {
+        const elapsed = Date.now() - startTime;
+        streamJsonLine({
+            type: "step",
+            name: "build",
+            status: "completed",
+            duration_ms: elapsed,
+        });
+        // Same event and payload shape as the default build path in command.ts:
+        // one command must not answer `--json` with two different result lines.
+        streamJsonLine({
+            type: "result",
+            success: true,
+            data: {
+                // `buildEmbeddedPreset` unshifts a synthetic `/` -> `embedded/app.js`
+                // shell route on top of the discovered ones, so counting every
+                // `type: "page"` reports one more page than the project has. Measured
+                // on a two-page fixture: routes are the shell, `/about`, and `/`, so
+                // the naive count says 3.
+                pages: manifest.routes.filter((route) => route.type === "page" && route.file !== EMBEDDED_APP_SHELL_FILE).length,
+                // The default path reports 0 for a build with no splitting stage, and
+                // the embedded preset has none — which is why `--split` is rejected for
+                // it above. Reporting 1 here would answer the same field differently
+                // from the command this is supposed to match.
+                chunks: 0,
+                assets: manifest.assets.length,
+                totalSize: await sumEmbeddedOutputSize(finalOutput, manifest),
+                duration_ms: elapsed,
+                outputDir: finalOutput,
+                // `--dry-run` is rejected for this preset, so a build that got here ran.
+                dryRun: false,
+            },
+        });
+        return;
+    }
     logSuccess("Built embedded preset");
     cliLogger.info(`  ${finalOutput}\n`);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/generate/command.ts"],"names":[],"mappings":"AA4FA,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAoCf"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/generate/command.ts"],"names":[],"mappings":"AA8FA,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAqCf"}

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

@@ -5,6 +5,7 @@ import { parseExtensionManifest } from "../../../src/extensions/index.js";
 import { exists, join, readTextFile } from "../../../src/fs/index.js";
 import { generateIntegration } from "./integration-generator.js";
 import { isScaffoldType, scaffoldProjectFile } from "../../scaffold/engine.js";
+const MDX_EXTENSION_PACKAGE = "@veryfront/ext-content-mdx";
 const PROJECT_MARKERS = [
     "veryfront.config.ts",
     "veryfront.config.js",
@@ -106,4 +107,43 @@ export async function generateCommand(projectDir, type, name) {
     }
     for (const file of result.files)
         cliLogger.info(`Created ${file.path}`);
+    await warnIfMdxExtensionMissing(projectDir, result.files.map((file) => file.path));
+}
+/**
+ * Tell the user to install the MDX extension when we have just written an
+ * `.mdx` file into a project that does not declare it.
+ *
+ * The pages router scaffolds `.mdx` for `page` and `layout`. Since
+ * `@veryfront/ext-content-mdx` became an optional peer of the npm package, a
+ * project that never installed it renders those routes as an error — while
+ * this command has just reported "Created" and exited 0. The compile path
+ * already throws a typed error naming the package, but by then the developer
+ * is debugging a route they were told was fine.
+ *
+ * Best-effort: a project without a readable package.json (a Deno project, say)
+ * gets no warning rather than a false one.
+ */
+async function warnIfMdxExtensionMissing(projectDir, paths) {
+    if (!paths.some((path) => path.endsWith(".mdx")))
+        return;
+    try {
+        const raw = await readTextFile(join(projectDir, "package.json"));
+        const manifest = JSON.parse(raw);
+        const declared = [
+            manifest.dependencies,
+            manifest.devDependencies,
+            manifest.peerDependencies,
+            manifest.optionalDependencies,
+        ].some((group) => group?.[MDX_EXTENSION_PACKAGE] !== undefined);
+        if (declared)
+            return;
+        // Lockfile-aware: hard-coding `npm install` in a pnpm/yarn/bun project
+        // writes a competing package-lock.json and leaves the real lockfile stale.
+        const { detectProjectInstallTarget, formatInstallCommand } = await import("../../../src/extensions/index.js");
+        const install = formatInstallCommand(MDX_EXTENSION_PACKAGE, detectProjectInstallTarget(projectDir));
+        cliLogger.warn(`This project does not depend on ${MDX_EXTENSION_PACKAGE}, so the generated .mdx file will not render. Install it with: ${install}`);
+    }
+    catch {
+        // No readable package.json: say nothing rather than warn wrongly.
+    }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/push/command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/push/command.ts"],"names":[],"mappings":"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"}

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

@@ -425,6 +425,20 @@ function requireRemoteContent(file) {
         return file.content;
     throw new Error(`Veryfront returned invalid content for remote file "${file.path}". No files were pushed.`);
 }
+function findRemoteFilesMissingLocally(remoteFiles, localPaths, ignoreChecker) {
+    return remoteFiles
+        .map((file) => file.path)
+        .filter((path) => ignoreChecker.isSupportedExtension(path) &&
+        !ignoreChecker.isIgnored(path) &&
+        !localPaths.has(path));
+}
+function requirePreservedRemoteContent(remoteFiles, localPaths, deletePaths) {
+    for (const file of remoteFiles) {
+        if (!localPaths.has(file.path) && !deletePaths.has(file.path)) {
+            requireRemoteContent(file);
+        }
+    }
+}
 async function buildManagedRemoteSnapshot(files, ignoreChecker, includeVersion = true) {
     const snapshot = new Map();
     for (const file of files) {
@@ -645,6 +659,10 @@ export function pushCommand(options = {}) {
             };
         let remoteFilesAreBaseline = !isMainBranch && !target.branchExists;
         if (!dryRun && !isMainBranch && !target.branchId) {
+            // Branch creation is a remote mutation. Validate every inherited file
+            // that later planning or receipt generation can require before the POST.
+            for (const file of target.remoteFiles)
+                requireRemoteContent(file);
             spinner.update(`Creating branch "${branchName}"...`);
             try {
                 const preparedBranch = await ensureBranch(client, projectApiReference(config), branchName);
@@ -672,24 +690,14 @@ export function pushCommand(options = {}) {
                 throw new Error(`Failed to prepare branch "${branchName}": ${message}`);
             }
         }
-        const remoteFilesMissingLocally = target.remoteFiles
-            .map((file) => file.path)
-            .filter((path) => ignoreChecker.isSupportedExtension(path) &&
-            !ignoreChecker.isIgnored(path) &&
-            !localPaths.has(path));
+        const remoteFilesMissingLocally = findRemoteFilesMissingLocally(target.remoteFiles, localPaths, ignoreChecker);
         const toDelete = pruneRemoteMissing ? remoteFilesMissingLocally : [];
+        // Preflight: fail before any remote mutation if a preserved remote file
+        // is missing content, so the digest computations after upload/delete
+        // cannot be the first to discover it.
         const deletePaths = new Set(toDelete);
-        const preservedRemoteFiles = target.remoteFiles
-            .filter((file) => !localPaths.has(file.path) && !deletePaths.has(file.path))
-            .map((file) => {
-            if (typeof file.content !== "string") {
-                throw new Error(`Veryfront returned invalid content for preserved remote file "${file.path}".`);
-            }
-            return { path: file.path, content: file.content };
-        });
-        let pushedSourceDigest = preservedRemoteFiles.length === 0
-            ? sourceSnapshot.sourceDigest
-            : await computeSourceDigest([...ops, ...preservedRemoteFiles]);
+        requirePreservedRemoteContent(target.remoteFiles, localPaths, deletePaths);
+        let pushedSourceDigest;
         const project = outcome.kind === "planned-create" ? null : outcome.project;
         const baseline = project
             ? await readSyncTarget(projectDir, {

package/esm/cli/shared/ensure-content-processor.d.ts

@@ -1,3 +1,7 @@
+import type { ContentProcessor } from "../../src/extensions/content/index.js";
+type ContentMdxExtensionModule = {
+    MdxContentProcessor: new () => ContentProcessor;
+};
 /**
  * Start loading ext-mdx before the server accepts requests. Registration must
  * still happen after server start (bootstrap `reset()` clears the contract
@@ -13,6 +17,17 @@ export declare function prefetchBuiltinContentProcessor(): void;
  * `setupAll` to `teardownAll` to `reset()` clears the contract registry, so this
  * must run *after* the server-start (or `getConfig`) call returns. We skip
  * registration when a user-provided extension already supplied the contract.
+ *
+ * The npm distribution declares @veryfront/ext-content-mdx as an *optional
+ * peer* (see scripts/build/npm-package-metadata.ts), so a plain
+ * `npm install veryfront` does not install it. Every server start calls this,
+ * including projects with no .mdx or .md file at all, so a missing package must
+ * not be fatal here. Leaving the contract unregistered defers the report to the
+ * compile path, which throws the typed MISSING_EXTENSION_ERROR naming
+ * @veryfront/ext-content-mdx only when content is actually rendered.
+ *
+ * `load` is a test seam and defaults to the real module loader.
  */
-export declare function ensureBuiltinContentProcessor(): Promise<void>;
+export declare function ensureBuiltinContentProcessor(load?: () => Promise<ContentMdxExtensionModule>): Promise<void>;
+export {};
 //# sourceMappingURL=ensure-content-processor.d.ts.map

package/esm/cli/shared/ensure-content-processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-content-processor.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/ensure-content-processor.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAItD;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAInE"}
+{"version":3,"file":"ensure-content-processor.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/ensure-content-processor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAO9E,KAAK,yBAAyB,GAAG;IAC/B,mBAAmB,EAAE,UAAU,gBAAgB,CAAC;CACjD,CAAC;AAmCF;;;;;;GAMG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAItD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,GAAE,MAAM,OAAO,CAAC,yBAAyB,CAAwB,GACpE,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/esm/cli/shared/ensure-content-processor.js

@@ -1,9 +1,25 @@
 import { tryResolve } from "../../src/extensions/index.js";
 import { register } from "../../src/extensions/contracts.js";
-import { importFirstPartyExtensionModule } from "../../src/extensions/first-party-import.js";
+import { firstPartyExtensionSourceSpecifiers, importFirstPartyExtensionModule, isMissingFirstPartyExtensionModule, } from "../../src/extensions/first-party-import.js";
+const CONTENT_MDX_DIRECTORY = "ext-content-mdx";
+const CONTENT_MDX_PACKAGE = `@veryfront/${CONTENT_MDX_DIRECTORY}`;
+/**
+ * Specifiers a "not installed" failure is allowed to name: the npm package and
+ * the workspace source entries the loader tries first. Derived rather than
+ * written out so they stay in step with the loader, and so this module keeps
+ * naming no extension source path of its own.
+ *
+ * A load failure naming anything else — a broken transitive dependency inside
+ * an installed ext-content-mdx, say — is a real error and must not be
+ * swallowed.
+ */
+const CONTENT_MDX_SPECIFIERS = [
+    CONTENT_MDX_PACKAGE,
+    ...firstPartyExtensionSourceSpecifiers(CONTENT_MDX_DIRECTORY).map((specifier) => specifier.replace(/^(?:\.\.\/)+/, "")),
+];
 let contentMdxModulePromise;
 function loadContentMdxModule() {
-    contentMdxModulePromise ??= importFirstPartyExtensionModule("ext-content-mdx", "@veryfront/ext-content-mdx").catch((error) => {
+    contentMdxModulePromise ??= importFirstPartyExtensionModule(CONTENT_MDX_DIRECTORY, CONTENT_MDX_PACKAGE).catch((error) => {
         contentMdxModulePromise = undefined;
         throw error;
     });
@@ -28,10 +44,28 @@ export function prefetchBuiltinContentProcessor() {
  * `setupAll` to `teardownAll` to `reset()` clears the contract registry, so this
  * must run *after* the server-start (or `getConfig`) call returns. We skip
  * registration when a user-provided extension already supplied the contract.
+ *
+ * The npm distribution declares @veryfront/ext-content-mdx as an *optional
+ * peer* (see scripts/build/npm-package-metadata.ts), so a plain
+ * `npm install veryfront` does not install it. Every server start calls this,
+ * including projects with no .mdx or .md file at all, so a missing package must
+ * not be fatal here. Leaving the contract unregistered defers the report to the
+ * compile path, which throws the typed MISSING_EXTENSION_ERROR naming
+ * @veryfront/ext-content-mdx only when content is actually rendered.
+ *
+ * `load` is a test seam and defaults to the real module loader.
  */
-export async function ensureBuiltinContentProcessor() {
+export async function ensureBuiltinContentProcessor(load = loadContentMdxModule) {
     if (tryResolve("ContentProcessor"))
         return;
-    const { MdxContentProcessor } = await loadContentMdxModule();
-    register("ContentProcessor", new MdxContentProcessor());
+    let module;
+    try {
+        module = await load();
+    }
+    catch (error) {
+        if (isMissingFirstPartyExtensionModule(error, CONTENT_MDX_SPECIFIERS))
+            return;
+        throw error;
+    }
+    register("ContentProcessor", new module.MdxContentProcessor());
 }

package/esm/cli/shared/project-creation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-creation.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/project-creation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project-creation.d.ts","sourceRoot":"","sources":["../../../src/cli/shared/project-creation.ts"],"names":[],"mappings":"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"}

package/esm/cli/shared/project-creation.js

@@ -128,6 +128,7 @@ function dedupeEnvVars(envVars) {
         return true;
     });
 }
+const MDX_EXTENSION_PACKAGE = "@veryfront/ext-content-mdx";
 async function loadTemplateFiles(template) {
     const { getAiRuleTemplate, getTemplate, getTemplateConfig } = await import("../../templates/index.js");
     let files = await getTemplate(template);
@@ -150,6 +151,33 @@ async function loadTemplateFiles(template) {
         firstPartyExtensions: templateConfig?.firstPartyExtensions,
     };
 }
+/**
+ * Declare `@veryfront/ext-content-mdx` whenever the assembled project actually
+ * contains an `.mdx` file.
+ *
+ * The extension is an optional peer of the npm package — it drags
+ * `@types/mdx`, which breaks `tsc --noEmit` for every library consumer — so a
+ * project that renders MDX has to install it or those routes fail at runtime.
+ *
+ * Two ways a project ends up needing it, and the template config sees neither
+ * on its own:
+ *
+ * - A scaffolded `.mdx` file. The `minimal` starter ships `app/about/page.mdx`.
+ * - The `mdx` feature. It scaffolds no files — it sets `mdx.enabled` in the
+ *   config and tips the user to "Create .mdx files in app/ directory" — so a
+ *   user who follows that advice on any template would hit a runtime failure
+ *   with nothing in `package.json` to explain it.
+ */
+function withMdxExtension(firstPartyExtensions, files, features) {
+    const needsMdx = features.includes("mdx") ||
+        files.some((file) => file.path.endsWith(".mdx"));
+    if (!needsMdx)
+        return firstPartyExtensions;
+    const existing = firstPartyExtensions ?? [];
+    if (existing.includes(MDX_EXTENSION_PACKAGE))
+        return existing;
+    return [...existing, MDX_EXTENSION_PACKAGE];
+}
 async function assembleFeatureFiles(features, templateFiles, allEnvVars) {
     let files = templateFiles;
     const tips = [];
@@ -309,7 +337,7 @@ async function assembleScaffold(request) {
         tips: [...featureAssembly.tips, ...integrationAssembly.tips],
         packageJsonOptions: {
             dependencies: template.dependencies,
-            firstPartyExtensions: template.firstPartyExtensions,
+            firstPartyExtensions: withMdxExtension(template.firstPartyExtensions, integrationAssembly.files, request.features),
             integrations: integrationAssembly.loadedIntegrations.map((integration) => ({
                 name: integration.config.name,
                 npmDependencies: integration.config.npmDependencies,