@mandujs/core 0.45.0 → 0.46.0

package/src/deploy/inference/heuristic.ts

@@ -0,0 +1,182 @@
+/**
+ * Heuristic deploy intent inferer.
+ *
+ * Issue #250 — Phase 1.
+ *
+ * The rule tree below is the offline, brain-free inferer. It produces
+ * an intent for every route the manifest contains using nothing but
+ * the source code and manifest metadata gathered by `context.ts`.
+ *
+ * Design constraints:
+ *
+ *   1. **Conservative on doubt.** When a signal is ambiguous, prefer
+ *      `node`/`bun` over `edge` and `no-store` over caching. A
+ *      slightly-too-pessimistic intent is fixable with one explicit
+ *      `.deploy()` call; a too-aggressive one breaks production.
+ *
+ *   2. **Deterministic.** Same context → same intent, byte-for-byte.
+ *      The cache hashes the source so unchanged routes never re-
+ *      infer; we don't want flapping intents across runs.
+ *
+ *   3. **Reasoned.** Every result carries a `rationale` string. Plan
+ *      diff surfaces it so reviewers can audit "why edge here?".
+ *
+ *   4. **Replaceable.** The brain inferer (M4) calls into the same
+ *      shape (`InferenceResult`) so adapters never need to know which
+ *      engine produced the intent.
+ */
+
+import type { DeployIntent } from "../intent";
+import type { DependencyClass, DeployInferenceContext } from "./context";
+
+export interface InferenceResult {
+  intent: DeployIntent;
+  rationale: string;
+}
+
+/**
+ * Run the rule tree on a single route context.
+ *
+ * The rules below are checked top-to-bottom; the first match wins.
+ * Adding a new rule? Put it in priority order — the most specific /
+ * highest-confidence rule first.
+ */
+export function inferDeployIntentHeuristic(
+  ctx: DeployInferenceContext,
+): InferenceResult {
+  // ─── Metadata routes (sitemap.xml, robots.txt, llms.txt, manifest.json)
+  if (ctx.kind === "metadata") {
+    return {
+      intent: {
+        runtime: "static",
+        cache: { sMaxAge: 3600, swr: 86_400 },
+        visibility: "public",
+      },
+      rationale:
+        "metadata route — sitemap/robots/llms.txt are stable across requests; prerender + 1h s-maxage with 1d SWR.",
+    };
+  }
+
+  // ─── Page routes
+  if (ctx.kind === "page") {
+    // Static-prerenderable: no dynamic segments, OR has generateStaticParams.
+    if (!ctx.isDynamic) {
+      return {
+        intent: {
+          runtime: "static",
+          cache: { sMaxAge: 31_536_000, swr: 86_400 },
+          visibility: "public",
+        },
+        rationale: "page with no dynamic segments — prerender at build time.",
+      };
+    }
+    if (ctx.hasGenerateStaticParams) {
+      return {
+        intent: {
+          runtime: "static",
+          cache: { sMaxAge: 31_536_000, swr: 86_400 },
+          visibility: "public",
+        },
+        rationale:
+          "dynamic page exports generateStaticParams — every parameter combination prerenders at build time.",
+      };
+    }
+    // Dynamic page without static params: needs SSR. Pick edge unless
+    // the handler imports something edge can't run.
+    if (canRunOnEdge(ctx.dependencyClasses)) {
+      return {
+        intent: {
+          runtime: "edge",
+          cache: "no-store",
+          visibility: "public",
+        },
+        rationale:
+          "dynamic page (SSR) with no Node/Bun-only dependencies — edge runtime keeps latency low.",
+      };
+    }
+    return {
+      intent: {
+        runtime: pickServerRuntime(ctx.dependencyClasses),
+        cache: "no-store",
+        visibility: "public",
+      },
+      rationale: explainServerRuntime(ctx.dependencyClasses, "page"),
+    };
+  }
+
+  // ─── API routes
+  // APIs are never `static`. Pick edge when stateless, server runtime
+  // otherwise. Cache always defaults to `no-store` — caching API
+  // responses is a deliberate decision, not something we infer.
+  if (canRunOnEdge(ctx.dependencyClasses)) {
+    return {
+      intent: {
+        runtime: "edge",
+        cache: "no-store",
+        visibility: "public",
+      },
+      rationale:
+        "API route with only fetch-class dependencies — edge runtime; opt into caching with .deploy({ cache }).",
+    };
+  }
+  return {
+    intent: {
+      runtime: pickServerRuntime(ctx.dependencyClasses),
+      cache: "no-store",
+      visibility: "public",
+    },
+    rationale: explainServerRuntime(ctx.dependencyClasses, "API"),
+  };
+}
+
+// ─── Rule-tree primitives ────────────────────────────────────────────
+
+/**
+ * The classes that disqualify edge — DB drivers (open TCP sockets and
+ * ship native modules), Node-only filesystem/networking modules, Bun
+ * native primitives (sqlite/ffi/s3), AI SDKs (long-running, large
+ * payloads), and explicitly heavy native libraries (sharp/playwright).
+ */
+const NON_EDGE_CLASSES: ReadonlySet<DependencyClass> = new Set([
+  "db",
+  "node-fs",
+  "node-net",
+  "node-child",
+  "bun-native",
+  "ai-sdk",
+  "heavy",
+]);
+
+function canRunOnEdge(classes: ReadonlySet<DependencyClass>): boolean {
+  for (const cls of classes) {
+    if (NON_EDGE_CLASSES.has(cls)) return false;
+  }
+  return true;
+}
+
+/**
+ * Choose between `bun` and `node` for routes that must run on a
+ * server runtime. `bun-native` imports force `bun`; everything else
+ * defaults to `node` for maximum portability (every adapter supports
+ * Node; not every adapter supports Bun yet).
+ */
+function pickServerRuntime(classes: ReadonlySet<DependencyClass>): "node" | "bun" {
+  return classes.has("bun-native") ? "bun" : "node";
+}
+
+function explainServerRuntime(
+  classes: ReadonlySet<DependencyClass>,
+  routeLabel: string,
+): string {
+  const reasons: string[] = [];
+  if (classes.has("db")) reasons.push("imports a database driver");
+  if (classes.has("node-fs")) reasons.push("uses node:fs");
+  if (classes.has("node-net")) reasons.push("uses node:net/tls/dgram");
+  if (classes.has("node-child")) reasons.push("uses node:child_process or worker_threads");
+  if (classes.has("bun-native")) reasons.push("imports bun:* primitives");
+  if (classes.has("ai-sdk")) reasons.push("imports an AI SDK (long latency)");
+  if (classes.has("heavy")) reasons.push("imports a heavy native dependency");
+  const why = reasons.length > 0 ? reasons.join(", ") : "non-edge dependencies";
+  const runtime = pickServerRuntime(classes);
+  return `${routeLabel} ${why} — ${runtime} runtime required.`;
+}

package/src/deploy/intent.ts

@@ -0,0 +1,173 @@
+/**
+ * Deploy Intent — typed declaration of how a route should be deployed.
+ *
+ * Issue #250 — Phase 1.
+ *
+ * The schema is the contract between three parts of Mandu:
+ *
+ *   1. Inference (`packages/core/src/deploy/inference/`) — emits intents
+ *      from route source + manifest metadata. Heuristic first; OpenAI
+ *      brain is optional.
+ *
+ *   2. Cache (`.mandu/deploy.intent.json`, see `cache.ts`) — versioned,
+ *      committable file the inferer writes and adapters read. Re-using
+ *      it across runs is what makes deploys deterministic and offline-
+ *      capable (no brain call required at deploy time).
+ *
+ *   3. Adapters (`packages/cli/src/commands/deploy/adapters/*`) —
+ *      compile a manifest + intent cache into a provider-specific
+ *      config (`vercel.json`, `fly.toml`, …). Adapters never invent
+ *      defaults; missing intent for any non-static route is a hard
+ *      error so deploys can't drift silently.
+ *
+ * Schema portability: only fields every supported provider can express
+ * live in the core schema. Provider-specific fields (Fly's `vm_size`,
+ * Vercel's `memory`, …) go in `overrides` keyed by target name.
+ */
+
+import { z } from "zod";
+
+// ─── Runtime ──────────────────────────────────────────────────────────
+
+/**
+ * Deploy runtime — the execution model the route ships in.
+ *
+ *   - `static` — prerendered at build time, served from a CDN. No
+ *     server execution at request time. Only valid when the route can
+ *     be rendered to bytes ahead of time (no per-request data).
+ *   - `edge` — short-lived, V8-isolate-class environment near the
+ *     viewer. No filesystem, no native modules. Best for low-latency
+ *     transforms and stateless API.
+ *   - `node` — long-running server with full Node API. Use when the
+ *     route imports things edge can't run (DB drivers, file IO, large
+ *     dependencies).
+ *   - `bun` — long-running Bun server. Same role as `node` but with
+ *     Bun primitives (`bun:sqlite`, `Bun.s3`, etc.). Provider support
+ *     varies — Vercel `@vercel/bun` is required for this on Vercel.
+ */
+export const DeployRuntime = z.enum(["static", "edge", "node", "bun"]);
+export type DeployRuntime = z.infer<typeof DeployRuntime>;
+
+// ─── Cache ────────────────────────────────────────────────────────────
+
+/**
+ * Cache directive — compiled to provider-specific cache headers /
+ * `s-maxage` / `stale-while-revalidate` / etc.
+ *
+ * Three forms are accepted:
+ *
+ *   - `"no-store"` — never cache. Default for API routes.
+ *   - `"public"` — cache without explicit lifetimes. Use for assets.
+ *   - `{ maxAge?, sMaxAge?, swr? }` — explicit lifetimes (seconds).
+ *     `maxAge` controls the browser cache, `sMaxAge` the shared CDN
+ *     cache, `swr` the stale-while-revalidate window.
+ */
+export const DeployCacheLifetime = z.object({
+  /** Browser cache lifetime in seconds. */
+  maxAge: z.number().int().nonnegative().optional(),
+  /** Shared CDN cache lifetime in seconds. */
+  sMaxAge: z.number().int().nonnegative().optional(),
+  /** stale-while-revalidate window in seconds. */
+  swr: z.number().int().nonnegative().optional(),
+});
+export type DeployCacheLifetime = z.infer<typeof DeployCacheLifetime>;
+
+export const DeployCache = z.union([
+  z.literal("no-store"),
+  z.literal("public"),
+  DeployCacheLifetime,
+]);
+export type DeployCache = z.infer<typeof DeployCache>;
+
+// ─── Visibility ───────────────────────────────────────────────────────
+
+/**
+ * Network visibility — public reach vs internal-only. Adapters with no
+ * native private-route concept reject this when set to `"private"`.
+ */
+export const DeployVisibility = z.enum(["public", "private"]);
+export type DeployVisibility = z.infer<typeof DeployVisibility>;
+
+// ─── Target ───────────────────────────────────────────────────────────
+
+/**
+ * Per-route target override. When set, the route ships to this
+ * provider regardless of the top-level `mandu deploy --target=...`
+ * flag. Phase 3 makes this load-bearing for heterogeneous deploys
+ * ("docs to cf-pages, api to fly, admin to docker"). Phase 1 stores it
+ * but the multi-target dispatcher is not yet implemented — a non-
+ * matching `target` in Phase 1 raises an error from the adapter.
+ */
+export const DeployTarget = z.enum(["vercel", "fly", "cf-pages", "docker"]);
+export type DeployTarget = z.infer<typeof DeployTarget>;
+
+// ─── Intent ───────────────────────────────────────────────────────────
+
+/**
+ * The intent itself. Adapters MUST treat this as the single source of
+ * truth — no out-of-band defaults, no provider-specific shortcuts that
+ * bypass the schema.
+ */
+export const DeployIntent = z.object({
+  runtime: DeployRuntime,
+  cache: DeployCache.default("no-store"),
+  /** Geographic regions (provider-specific identifiers). */
+  regions: z.array(z.string().min(1)).optional(),
+  /** Lower bound on warm instances. */
+  minInstances: z.number().int().nonnegative().optional(),
+  /** Upper bound on concurrent instances. */
+  maxInstances: z.number().int().positive().optional(),
+  /** Per-request execution timeout in milliseconds. */
+  timeout: z.number().int().positive().optional(),
+  visibility: DeployVisibility.default("public"),
+  target: DeployTarget.optional(),
+  /**
+   * Provider-specific overrides keyed by adapter name. The schema
+   * accepts any shape; each adapter validates its own slice. Use
+   * sparingly — prefer pushing recurring needs into the core schema.
+   *
+   * @example { vercel: { memory: 1024 }, fly: { vm: "shared-cpu-2x" } }
+   */
+  overrides: z.record(z.string(), z.unknown()).optional(),
+});
+export type DeployIntent = z.infer<typeof DeployIntent>;
+
+/**
+ * Partial-input variant for `.deploy()` builder calls — every field
+ * stays optional at the call site so users can declare just `runtime`
+ * or just `cache`. The full `DeployIntent.parse()` step happens at the
+ * cache-write boundary, where defaults fill in.
+ */
+export const DeployIntentInput = DeployIntent.partial();
+export type DeployIntentInput = z.input<typeof DeployIntentInput>;
+
+// ─── Validation helpers ──────────────────────────────────────────────
+
+/**
+ * `runtime: "static"` requires the route to be prerenderable. A
+ * dynamic-segment page with no `generateStaticParams` cannot satisfy
+ * that — adapters should refuse to compile such intents and surface
+ * the route id in the error.
+ */
+export function isStaticIntentValidFor(
+  intent: DeployIntent,
+  route: { isDynamic: boolean; hasGenerateStaticParams: boolean; kind: string },
+): { ok: true } | { ok: false; reason: string } {
+  if (intent.runtime !== "static") return { ok: true };
+
+  if (route.kind === "api") {
+    return {
+      ok: false,
+      reason:
+        "runtime: \"static\" is not valid for an API route — APIs execute at request time. Use \"edge\", \"node\", or \"bun\".",
+    };
+  }
+  if (route.isDynamic && !route.hasGenerateStaticParams) {
+    return {
+      ok: false,
+      reason:
+        "runtime: \"static\" requires the dynamic route to export `generateStaticParams` so all parameter combinations are known at build time.",
+    };
+  }
+  return { ok: true };
+}

package/src/deploy/plan.ts

@@ -0,0 +1,178 @@
+/**
+ * Plan a deploy — compute the next `DeployIntentCache` from a
+ * manifest and the previous cache.
+ *
+ * Issue #250 — Phase 1.
+ *
+ * The plan step is pure: it takes the manifest + previous cache +
+ * inferer and returns the new cache + a diff. No filesystem writes
+ * here; that's the CLI's job. Keeping this pure makes the diff easy
+ * to render in tests and lets future surfaces (kitchen UI, MCP tool)
+ * reuse the same plan logic.
+ *
+ * Override hierarchy (highest wins):
+ *
+ *   1. **Explicit** — entry where `source === "explicit"` in the
+ *      previous cache. Never overwritten by inference. Re-keyed by
+ *      `sourceHash` only so users can hand-edit the file and have
+ *      their edits stick.
+ *   2. **Cached, source unchanged** — same `sourceHash` ⇒ reuse the
+ *      stored intent. This is the cost cap on brain calls.
+ *   3. **Inferred** — call the inferer. Default is heuristic; brain
+ *      can swap in via the `infer` parameter.
+ */
+
+import type { RoutesManifest } from "../spec/schema";
+import {
+  emptyDeployIntentCache,
+  type DeployIntentCache,
+  type DeployIntentCacheEntry,
+} from "./cache";
+import { buildDeployInferenceContext, type DeployInferenceContext } from "./inference/context";
+import {
+  inferDeployIntentHeuristic,
+  type InferenceResult,
+} from "./inference/heuristic";
+
+/**
+ * Per-route diff entry surfaced to the CLI / tests.
+ *
+ *   - `added`     — no prior entry, new intent inferred.
+ *   - `unchanged` — same source hash; entry kept verbatim.
+ *   - `changed`   — source hash differs OR explicit override updated;
+ *                   the `previous` field carries the old entry for
+ *                   diff rendering.
+ *   - `removed`   — route exists in cache but not in manifest. Pruned.
+ *   - `pinned`    — explicit entry; inference skipped.
+ */
+export type PlanDiffEntryKind =
+  | "added"
+  | "unchanged"
+  | "changed"
+  | "removed"
+  | "pinned";
+
+export interface PlanDiffEntry {
+  routeId: string;
+  pattern: string;
+  kind: PlanDiffEntryKind;
+  next?: DeployIntentCacheEntry;
+  previous?: DeployIntentCacheEntry;
+}
+
+export interface PlanResult {
+  cache: DeployIntentCache;
+  diff: PlanDiffEntry[];
+}
+
+export interface PlanDeployOptions {
+  rootDir: string;
+  manifest: RoutesManifest;
+  previous?: DeployIntentCache;
+  /**
+   * Override the inferer. Defaults to the offline heuristic. The
+   * brain inferer (M4) plugs in here without changing the plan flow.
+   */
+  infer?: (ctx: DeployInferenceContext) => Promise<InferenceResult> | InferenceResult;
+  /** Identifier written into `cache.brainModel`. Defaults to `"heuristic"`. */
+  brainModel?: string;
+  /** ISO timestamp override — primarily for test determinism. */
+  now?: () => string;
+  /** Force re-inference even when the source hash matches. */
+  reinfer?: boolean;
+}
+
+export async function planDeploy(opts: PlanDeployOptions): Promise<PlanResult> {
+  const previous = opts.previous ?? emptyDeployIntentCache();
+  const infer =
+    opts.infer ?? ((ctx: DeployInferenceContext) => inferDeployIntentHeuristic(ctx));
+  const now = opts.now ?? (() => new Date().toISOString());
+  const brainModel = opts.brainModel ?? "heuristic";
+  const reinfer = opts.reinfer === true;
+
+  const nextIntents: Record<string, DeployIntentCacheEntry> = {};
+  const diff: PlanDiffEntry[] = [];
+
+  for (const route of opts.manifest.routes) {
+    const ctx = await buildDeployInferenceContext(opts.rootDir, route);
+    const prevEntry = previous.intents[route.id];
+
+    // 1. Explicit override — never re-infer; only refresh sourceHash.
+    if (prevEntry && prevEntry.source === "explicit") {
+      const refreshed: DeployIntentCacheEntry = {
+        ...prevEntry,
+        sourceHash: ctx.sourceHash,
+      };
+      nextIntents[route.id] = refreshed;
+      diff.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        kind: "pinned",
+        next: refreshed,
+        previous: prevEntry,
+      });
+      continue;
+    }
+
+    // 2. Cached, source unchanged.
+    if (
+      !reinfer &&
+      prevEntry &&
+      prevEntry.sourceHash === ctx.sourceHash
+    ) {
+      nextIntents[route.id] = prevEntry;
+      diff.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        kind: "unchanged",
+        next: prevEntry,
+        previous: prevEntry,
+      });
+      continue;
+    }
+
+    // 3. Infer.
+    const result = await infer(ctx);
+    const entry: DeployIntentCacheEntry = {
+      intent: result.intent,
+      source: "inferred",
+      rationale: result.rationale,
+      sourceHash: ctx.sourceHash,
+      inferredAt: now(),
+    };
+    nextIntents[route.id] = entry;
+    diff.push({
+      routeId: route.id,
+      pattern: route.pattern,
+      kind: prevEntry ? "changed" : "added",
+      next: entry,
+      previous: prevEntry,
+    });
+  }
+
+  // 4. Detect removed entries (cache had them, manifest doesn't).
+  const manifestIds = new Set(opts.manifest.routes.map((r) => r.id));
+  for (const [routeId, entry] of Object.entries(previous.intents)) {
+    if (manifestIds.has(routeId)) continue;
+    diff.push({
+      routeId,
+      pattern: "(removed from manifest)",
+      kind: "removed",
+      previous: entry,
+    });
+  }
+
+  const cache: DeployIntentCache = {
+    version: 1,
+    generatedAt: now(),
+    brainModel,
+    intents: nextIntents,
+  };
+
+  return { cache, diff };
+}
+
+/** True if the diff contains any non-`unchanged` entry. */
+export function planHasChanges(diff: readonly PlanDiffEntry[]): boolean {
+  return diff.some((d) => d.kind !== "unchanged" && d.kind !== "pinned");
+}

package/src/runtime/server.ts

@@ -1638,17 +1638,38 @@ async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean
   }
 }
 
+/**
+ * Issue #251 — public 폴더의 자산을 root URL로도 서빙하기 위한 화이트리스트.
+ *
+ * `mandu build --static` 은 `public/*` 을 dist 루트로 평탄화하므로 prod 에서는
+ * `/images/foo.webp` 가 동작한다. dev 에서는 평탄화가 없어서 같은 URL 이 404
+ * 였다 — 작성자는 `/public/...` (dev OK, prod 도 vercel rewrite 로 OK) 또는
+ * `/...` (dev 깨짐, prod OK) 중 하나를 골라야 했다. 이제 dev 도 자산 확장자가
+ * 있는 경로에 한해 `public/<path>` 를 fallback 으로 시도한다.
+ *
+ * 자산 확장자만 fallback 하므로 `/api/foo` 같은 라우트가 가려질 위험은 없다.
+ * 파일이 없으면 `{ handled: false }` 를 반환해 라우터가 정상 매칭하도록 한다.
+ */
+const PUBLIC_FLAT_ASSET_EXTENSIONS = new Set<string>([
+  ".webp", ".avif", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico",
+  ".pdf", ".zip", ".mp4", ".webm", ".mp3", ".wav",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".css", ".js", ".map",
+]);
+
 /**
  * 정적 파일 서빙
  * - /.mandu/client/* : 클라이언트 번들 (Island hydration)
  * - /public/* : 정적 에셋 (이미지, CSS 등)
  * - /favicon.ico : 파비콘
+ * - /<asset>.<ext> : public/<asset>.<ext> fallback (issue #251)
  *
  * 보안: Path traversal 공격 방지를 위해 모든 경로를 검증합니다.
  */
 async function serveStaticFile(pathname: string, settings: ServerRegistrySettings, request?: Request): Promise<StaticFileResult> {
   let filePath: string | null = null;
   let isBundleFile = false;
+  let isPublicFlatFallback = false;
   let allowedBaseDir: string;
   let relativePath: string;
 
@@ -1678,6 +1699,12 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
   ) {
     relativePath = path.basename(pathname);
     allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  }
+  // 5. Public flat fallback (#251) — `mandu build --static` 의 평탄화와 dev 패리티
+  else if (PUBLIC_FLAT_ASSET_EXTENSIONS.has(path.extname(pathname).toLowerCase())) {
+    relativePath = pathname.slice(1);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+    isPublicFlatFallback = true;
   } else {
     return { handled: false }; // 정적 파일이 아님
   }
@@ -1717,6 +1744,9 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
     const exists = await file.exists();
 
     if (!exists) {
+      // #251 — flat fallback 은 라우트와 path 충돌이 가능하므로 미존재 시
+      // 404 대신 라우터로 흘려보낸다 (e.g. `/foo.json` 라우트가 가려지지 않도록).
+      if (isPublicFlatFallback) return { handled: false };
       return { handled: true, response: createStaticErrorResponse(404) };
     }