@squadbase/vantage 0.6.2-dev2.777fe38 → 0.6.2-dev2.b5837f0

package/dist/chunk-ANZLVSEP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/query/api.ts","../src/query/hooks.ts"],"names":[],"mappings":"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","file":"chunk-ANZLVSEP.js","sourcesContent":["/**\n * The one seam for calling the API from client code. All `/api/*` requests go\n * through here so a split deployment (client on S3/CloudFront, server on Lambda)\n * can point the client at a different origin without touching page code.\n *\n * The base is read from `import.meta.env.PUBLIC_API_BASE_URL` — a `PUBLIC_`\n * prefixed var so it is inlined into the client bundle (see envPrefix in the\n * Vite plugin). It can be set in `.env` or injected at build time via\n * `vantage build --api-base-url <url>`. When unset it is empty, so requests stay\n * same-origin relative paths — identical to hand-written `fetch(\"/api/...\")`.\n */\nimport { isDraftActive } from \"../client/draft-state\"\n\n/** The configured API base URL (no trailing slash), or \"\" for same-origin. */\nexport function apiBaseUrl(): string {\n  // `import.meta.env` is typed in the generated .vantage/types, not here.\n  const env = (import.meta as { env?: Record<string, string | undefined> }).env\n  const raw = env?.PUBLIC_API_BASE_URL ?? \"\"\n  return raw.replace(/\\/+$/, \"\")\n}\n\n/**\n * Build a full API URL. Pass the path exactly as it maps to `server/api/**`,\n * including the `/api` prefix — e.g. `apiUrl(\"/api/customers\")`. With no base\n * configured this returns the relative path unchanged.\n */\nexport function apiUrl(path: string): string {\n  const rel = path.startsWith(\"/\") ? path : `/${path}`\n  return apiBaseUrl() + rel\n}\n\n/**\n * Thin `fetch` wrapper that resolves the path against the API base. Returns the\n * raw `Response` — parsing and error handling stay with the caller, matching the\n * existing `queryFn` style.\n */\nexport function apiFetch(path: string, init?: RequestInit): Promise<Response> {\n  return fetch(apiUrl(path), init)\n}\n\n/** Query-string values accepted by the API helpers. */\nexport type ApiSearch = Record<\n  string,\n  string | number | boolean | null | undefined | (string | number)[]\n>\n\n/**\n * Append a query string to an API path. `undefined`/`null` entries are dropped\n * so an unset filter leaves the URL — and the query key — unchanged. Array\n * values repeat the key, matching `URLSearchParams.getAll` on the server.\n */\nexport function apiPath(path: string, search?: ApiSearch): string {\n  if (!search) return path\n  const params = new URLSearchParams()\n  // Sorted so two calls with the same filters produce the same query key.\n  for (const key of Object.keys(search).sort()) {\n    const value = search[key]\n    if (value === undefined || value === null) continue\n    if (Array.isArray(value)) {\n      for (const item of value) params.append(key, String(item))\n    } else {\n      params.append(key, String(value))\n    }\n  }\n  const qs = params.toString()\n  if (!qs) return path\n  return path + (path.includes(\"?\") ? \"&\" : \"?\") + qs\n}\n\n/**\n * A non-2xx response from `server/api`. `message` is the server's `HttpError`\n * message when there was one; anything else surfaces as a generic status text,\n * mirroring what the server chose to disclose.\n */\nexport class ApiError extends Error {\n  /** HTTP status of the response. */\n  readonly status: number\n  /** Parsed response body, when there was one. */\n  readonly body: unknown\n  /** `x-vantage-request-id`, to correlate with the server's terminal log. */\n  readonly requestId: string | undefined\n\n  constructor(message: string, status: number, body: unknown, requestId?: string) {\n    super(message)\n    this.name = \"ApiError\"\n    this.status = status\n    this.body = body\n    this.requestId = requestId\n  }\n}\n\n/**\n * Fetch an API route and parse its JSON, throwing `ApiError` on a non-2xx.\n * This is what the API hooks call; use it directly in a loader or an event\n * handler where a hook doesn't fit.\n */\nexport async function apiJson<T = unknown>(path: string, init?: RequestInit): Promise<T> {\n  const res = await apiFetch(path, init)\n  const requestId = res.headers.get(\"x-vantage-request-id\") ?? undefined\n\n  // Read as text first: an error response may be HTML from a proxy, and a 204\n  // has no body at all — neither should throw a JSON parse error at the caller.\n  const text = await res.text()\n  let body: unknown\n  if (text) {\n    try {\n      body = JSON.parse(text)\n    } catch {\n      body = text\n    }\n  }\n\n  // While a draft is showing, an API the page calls may not exist yet. Without\n  // `server/` the dev server answers any GET with the app shell, a 200 that\n  // would otherwise pass for data; call it what it is (a missing route).\n  if (res.ok && isDraftActive() && (res.headers.get(\"content-type\") ?? \"\").includes(\"text/html\")) {\n    throw new ApiError(\"API route not found\", 404, body, requestId)\n  }\n\n  if (!res.ok) {\n    const serverMessage =\n      typeof body === \"object\" && body !== null && typeof (body as { error?: unknown }).error === \"string\"\n        ? (body as { error: string }).error\n        : undefined\n    throw new ApiError(\n      serverMessage ?? `${res.status} ${res.statusText || \"Request failed\"}`,\n      res.status,\n      body,\n      requestId,\n    )\n  }\n\n  return body as T\n}\n","/**\n * Hooks for the app's own `server/api` routes. They are `useQuery`/`useMutation`\n * with the parts every page was repeating — base URL, JSON parsing, non-2xx to\n * `ApiError`, a query key derived from the URL — moved into the framework.\n * Everything else about TanStack Query stays available through the options.\n */\nimport { useMutation, useQuery } from \"@tanstack/react-query\"\nimport type {\n  QueryKey,\n  UseMutationOptions,\n  UseMutationResult,\n  UseQueryOptions,\n  UseQueryResult,\n} from \"@tanstack/react-query\"\nimport { isDraftActive } from \"../client/draft-state\"\nimport { API_QUERY_KEY as API_KEY } from \"./client\"\nimport { apiJson, apiPath, ApiError as ApiErrorClass, type ApiError, type ApiSearch } from \"./api\"\n\n\n/** How often a query whose API route does not exist yet looks again, while a draft is showing. */\nconst MISSING_API_POLL_MS = 2000\n\n/** An API route that is not there (yet): a 404 from `server/api`, or the app shell standing in for it. */\nfunction isMissingApi(error: unknown): boolean {\n  return error instanceof ApiErrorClass && error.status === 404\n}\n\nexport interface ApiQueryOptions<TData>\n  extends Omit<UseQueryOptions<TData, ApiError>, \"queryKey\" | \"queryFn\"> {\n  /** Query-string values; `undefined` entries are omitted. */\n  search?: ApiSearch\n  /** Extra `fetch` init (headers, credentials, …). */\n  init?: RequestInit\n  /** Override the derived `[\"api\", url]` key. */\n  queryKey?: QueryKey\n}\n\n/**\n * GET an API route.\n *\n * ```tsx\n * const { data, isPending, error } = useApiQuery<Monthly>(\"/api/monthly-analysis\")\n * const filtered = useApiQuery<Row[]>(\"/api/customers\", { search: { segment } })\n * ```\n *\n * The key defaults to `[\"api\", <url with query string>]`, so changing `search`\n * refetches and `invalidateQueries({ queryKey: [\"api\"] })` clears everything.\n */\nexport function useApiQuery<TData = unknown>(\n  path: string,\n  options: ApiQueryOptions<TData> = {},\n): UseQueryResult<TData, ApiError> {\n  const { search, init, queryKey, refetchInterval, ...rest } = options\n  const url = apiPath(path, search)\n  const result = useQuery<TData, ApiError>({\n    queryKey: queryKey ?? [API_KEY, url],\n    // The signal comes from TanStack so an unmounted/refetched query aborts;\n    // a caller-supplied signal wins.\n    queryFn: ({ signal }) => apiJson<TData>(url, { ...init, signal: init?.signal ?? signal }),\n    // While a draft is showing, a route that does not exist yet is looked for\n    // again until it does; otherwise the caller's interval applies untouched.\n    refetchInterval: (query) =>\n      isDraftActive() && isMissingApi(query.state.error)\n        ? MISSING_API_POLL_MS\n        : typeof refetchInterval === \"function\"\n          ? refetchInterval(query)\n          : refetchInterval,\n    ...rest,\n  })\n  // A page written before its API is still loading as far as the page can tell:\n  // it keeps its loading state instead of drawing an error for a route the\n  // agent has not written yet.\n  if (isDraftActive() && isMissingApi(result.error)) {\n    return {\n      ...result,\n      status: \"pending\",\n      error: null,\n      isError: false,\n      isLoadingError: false,\n      isPending: true,\n      isLoading: true,\n    } as UseQueryResult<TData, ApiError>\n  }\n  return result\n}\n\nexport interface ApiMutationOptions<TData, TVariables>\n  extends Omit<UseMutationOptions<TData, ApiError, TVariables>, \"mutationFn\"> {\n  /** HTTP method (default `\"POST\"`). */\n  method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\"\n  /** Extra `fetch` init (headers, credentials, …). */\n  init?: RequestInit\n}\n\n/**\n * Write to an API route. The mutation variables are sent as the JSON body.\n *\n * ```tsx\n * const save = useApiMutation<Customer, { id: string; name: string }>(\n *   (vars) => `/api/customers/${vars.id}`,\n *   { method: \"PUT\" },\n * )\n * save.mutate({ id: \"1\", name: \"Northwind\" })\n * ```\n */\nexport function useApiMutation<TData = unknown, TVariables = void>(\n  path: string | ((variables: TVariables) => string),\n  options: ApiMutationOptions<TData, TVariables> = {},\n): UseMutationResult<TData, ApiError, TVariables> {\n  const { method = \"POST\", init, ...rest } = options\n  return useMutation<TData, ApiError, TVariables>({\n    mutationFn: (variables: TVariables) => {\n      const url = typeof path === \"function\" ? path(variables) : path\n      const hasBody = variables !== undefined && variables !== null\n      return apiJson<TData>(url, {\n        method,\n        ...init,\n        headers: hasBody\n          ? { \"content-type\": \"application/json\", ...(init?.headers as Record<string, string>) }\n          : init?.headers,\n        ...(hasBody ? { body: JSON.stringify(variables) } : {}),\n      })\n    },\n    ...rest,\n  })\n}\n"]}

package/dist/chunk-CKWPK4RO.js

@@ -0,0 +1,50 @@
+import { QueryClient } from '@tanstack/react-query';
+
+// @squadbase/vantage — generated build. Do not edit.
+
+var API_QUERY_KEY = "api";
+var API_REFRESH_DEBOUNCE_MS = 300;
+function refreshApiQueries(client) {
+  return client.invalidateQueries({
+    predicate: (query) => query.queryKey[0] === API_QUERY_KEY || query.state.status === "error"
+  });
+}
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 3e4,
+        retry: 1,
+        refetchOnWindowFocus: false,
+        // A dashboard talks to its own origin (or the configured API base), so
+        // the browser's offline heuristic says nothing useful about whether a
+        // request can succeed. Under the default "online" mode a failed request
+        // is *paused* rather than retried whenever that heuristic reads
+        // offline, and the page sits on its loading state forever instead of
+        // showing the error.
+        networkMode: "always"
+      },
+      mutations: {
+        networkMode: "always"
+      }
+    }
+  });
+}
+
+// src/client/draft-state.ts
+var SETTLING_MS = 1500;
+function isDraftActive() {
+  return typeof window !== "undefined" && window.__VANTAGE_DRAFT__?.active === true;
+}
+function isDraftSettling() {
+  if (isDraftActive()) return true;
+  return typeof window !== "undefined" && Date.now() < (window.__VANTAGE_DRAFT_SETTLING_UNTIL__ ?? 0);
+}
+function setDraftActive(active) {
+  if (!active && isDraftActive()) window.__VANTAGE_DRAFT_SETTLING_UNTIL__ = Date.now() + SETTLING_MS;
+  window.__VANTAGE_DRAFT__ = { active };
+}
+
+export { API_QUERY_KEY, API_REFRESH_DEBOUNCE_MS, SETTLING_MS, createQueryClient, isDraftActive, isDraftSettling, refreshApiQueries, setDraftActive };
+//# sourceMappingURL=chunk-CKWPK4RO.js.map
+//# sourceMappingURL=chunk-CKWPK4RO.js.map

package/dist/chunk-CKWPK4RO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/query/client.ts","../src/client/draft-state.ts"],"names":[],"mappings":";;;;AAGO,IAAM,aAAA,GAAgB;AAOtB,IAAM,uBAAA,GAA0B;AAOhC,SAAS,kBAAkB,MAAA,EAAoC;AACpE,EAAA,OAAO,OAAO,iBAAA,CAAkB;AAAA,IAC9B,SAAA,EAAW,CAAC,KAAA,KAAU,KAAA,CAAM,QAAA,CAAS,CAAC,CAAA,KAAM,aAAA,IAAiB,KAAA,CAAM,KAAA,CAAM,MAAA,KAAW;AAAA,GACrF,CAAA;AACH;AAOO,SAAS,iBAAA,GAAiC;AAC/C,EAAA,OAAO,IAAI,WAAA,CAAY;AAAA,IACrB,cAAA,EAAgB;AAAA,MACd,OAAA,EAAS;AAAA,QACP,SAAA,EAAW,GAAA;AAAA,QACX,KAAA,EAAO,CAAA;AAAA,QACP,oBAAA,EAAsB,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAOtB,WAAA,EAAa;AAAA,OACf;AAAA,MACA,SAAA,EAAW;AAAA,QACT,WAAA,EAAa;AAAA;AACf;AACF,GACD,CAAA;AACH;;;AC3BO,IAAM,WAAA,GAAc;AAEpB,SAAS,aAAA,GAAyB;AACvC,EAAA,OAAO,OAAO,MAAA,KAAW,WAAA,IAAe,MAAA,CAAO,mBAAmB,MAAA,KAAW,IAAA;AAC/E;AAOO,SAAS,eAAA,GAA2B;AACzC,EAAA,IAAI,aAAA,IAAiB,OAAO,IAAA;AAC5B,EAAA,OAAO,OAAO,MAAA,KAAW,WAAA,IAAe,KAAK,GAAA,EAAI,IAAK,OAAO,gCAAA,IAAoC,CAAA,CAAA;AACnG;AAEO,SAAS,eAAe,MAAA,EAAuB;AACpD,EAAA,IAAI,CAAC,UAAU,aAAA,EAAc,SAAU,gCAAA,GAAmC,IAAA,CAAK,KAAI,GAAI,WAAA;AACvF,EAAA,MAAA,CAAO,iBAAA,GAAoB,EAAE,MAAA,EAAO;AACtC","file":"chunk-CKWPK4RO.js","sourcesContent":["import { QueryClient } from \"@tanstack/react-query\"\n\n/** Query-key namespace of `useApiQuery`, so `invalidateQueries({ queryKey: [\"api\"] })` works. */\nexport const API_QUERY_KEY = \"api\"\n\n/**\n * Debounce for the api-change refetch. The changed `paths` cannot be mapped to\n * query keys reliably (custom `queryKey`s, dynamic segments), so every burst of\n * changes is coalesced into a single refetch of all API/errored queries.\n */\nexport const API_REFRESH_DEBOUNCE_MS = 300\n\n/**\n * An API module came, went or changed on the dev server: refetch the active API\n * queries, plus any query that is in an error state (a custom `queryKey` that\n * failed because the route did not exist yet still recovers).\n */\nexport function refreshApiQueries(client: QueryClient): Promise<void> {\n  return client.invalidateQueries({\n    predicate: (query) => query.queryKey[0] === API_QUERY_KEY || query.state.status === \"error\",\n  })\n}\n\n/**\n * Create the QueryClient with Vantage defaults. Individual queries may override\n * these, but replacing the QueryClient wholesale is intentionally not exposed —\n * Squadbase relies on a single managed client for auth, logging and telemetry.\n */\nexport function createQueryClient(): QueryClient {\n  return new QueryClient({\n    defaultOptions: {\n      queries: {\n        staleTime: 30_000,\n        retry: 1,\n        refetchOnWindowFocus: false,\n        // A dashboard talks to its own origin (or the configured API base), so\n        // the browser's offline heuristic says nothing useful about whether a\n        // request can succeed. Under the default \"online\" mode a failed request\n        // is *paused* rather than retried whenever that heuristic reads\n        // offline, and the page sits on its loading state forever instead of\n        // showing the error.\n        networkMode: \"always\",\n      },\n      mutations: {\n        networkMode: \"always\",\n      },\n    },\n  })\n}\n","/**\n * Whether the preview is currently showing a draft. The server announces it\n * (`vantage:draft-state`); until the first announcement `window.__VANTAGE_DRAFT__`\n * does not exist at all, which is how an app without the draft layer behaves.\n *\n * Kept free of React and of module state: `client/` and `query/` are separate\n * published entries, so the one thing they share is this global.\n */\nexport interface DraftWindowState {\n  active: boolean\n}\n\ndeclare global {\n  interface Window {\n    __VANTAGE_DRAFT__?: DraftWindowState\n    /** Until when (ms epoch) a draft that just ended still counts for failures (see `isDraftSettling`). */\n    __VANTAGE_DRAFT_SETTLING_UNTIL__?: number\n  }\n}\n\n/** How long after a draft ends a failure is still taken to be the draft's. */\nexport const SETTLING_MS = 1500\n\nexport function isDraftActive(): boolean {\n  return typeof window !== \"undefined\" && window.__VANTAGE_DRAFT__?.active === true\n}\n\n/**\n * A draft is showing, or ended a moment ago. The server announces the end before\n * the version it fell back to reaches the page, and a failing draft drawn once\n * more in that gap must still be held back, not shown as an error page.\n */\nexport function isDraftSettling(): boolean {\n  if (isDraftActive()) return true\n  return typeof window !== \"undefined\" && Date.now() < (window.__VANTAGE_DRAFT_SETTLING_UNTIL__ ?? 0)\n}\n\nexport function setDraftActive(active: boolean): void {\n  if (!active && isDraftActive()) window.__VANTAGE_DRAFT_SETTLING_UNTIL__ = Date.now() + SETTLING_MS\n  window.__VANTAGE_DRAFT__ = { active }\n}\n"]}

package/dist/{chunk-QI3XQKHS.js → chunk-GNXCX4WE.js}

@@ -20,6 +20,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "no-strict-port",
   "overlay",
   "no-overlay",
+  "draft-preview",
   "h",
   "v"
 ]);
@@ -114,6 +115,12 @@ function resolveHmrOverlay(flags) {
   if (flags.overlay) return true;
   return !flags["no-overlay"];
 }
+function resolveDraftPreview(flags) {
+  const flag = flags["draft-preview"];
+  if (flag === true || flag === "true" || flag === "1") return true;
+  if (flag !== void 0) return false;
+  return process.env.VANTAGE_DRAFT_PREVIEW === "1";
+}
 function reportPortInUse(err, port, strictPort) {
   if (!strictPort || !(err instanceof Error) || !/already in use/.test(err.message)) return false;
   log.error(`Port ${port} is already in use.`);
@@ -173,6 +180,6 @@ function frameworkVersion() {
   }
 }
 
-export { applyApiBaseUrlFlag, frameworkVersion, log, parseArgs, printDiagnostics, printJson, reportPortInUse, resolveHmrOverlay, resolveHostOptions, resolvePortOptions, resolveQuickRoot, resolveRoot };
-//# sourceMappingURL=chunk-QI3XQKHS.js.map
-//# sourceMappingURL=chunk-QI3XQKHS.js.map
+export { applyApiBaseUrlFlag, frameworkVersion, log, parseArgs, printDiagnostics, printJson, reportPortInUse, resolveDraftPreview, resolveHmrOverlay, resolveHostOptions, resolvePortOptions, resolveQuickRoot, resolveRoot };
+//# sourceMappingURL=chunk-GNXCX4WE.js.map
+//# sourceMappingURL=chunk-GNXCX4WE.js.map

package/dist/chunk-GNXCX4WE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/util.ts"],"names":[],"mappings":"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","file":"chunk-GNXCX4WE.js","sourcesContent":["import fs from \"node:fs\"\nimport path from \"node:path\"\nimport pc from \"picocolors\"\nimport { PAGE_EXTENSIONS } from \"../core/constants\"\nimport type { Diagnostic } from \"../core/types\"\n\n/** Parsed CLI arguments. */\nexport interface ParsedArgs {\n  positionals: string[]\n  flags: Record<string, string | boolean>\n}\n\n/** Flags that never take a value, so they don't swallow the next token. */\nconst BOOLEAN_FLAGS = new Set([\n  \"json\",\n  \"help\",\n  \"force\",\n  \"verbose\",\n  \"version\",\n  \"all\",\n  \"list\",\n  \"regex\",\n  \"pages\",\n  \"apis\",\n  \"detail\",\n  \"strict-port\",\n  \"no-strict-port\",\n  \"overlay\",\n  \"no-overlay\",\n  \"draft-preview\",\n  \"h\",\n  \"v\",\n])\n\n/**\n * Flags whose value is optional: bare `--host` means `true` (all interfaces),\n * `--host 0.0.0.0` / `--host=::` carry the address. The next token is taken as\n * the value only when it does not look like another flag, so `--host --port 3000`\n * still reads as two flags. Write `--host=<addr>` when the following token could\n * be mistaken for the value (e.g. a positional).\n */\nconst OPTIONAL_VALUE_FLAGS = new Set([\"host\"])\n\n/** Minimal argv parser: `--json`, `--port 3000`, `--port=3000`, `-v`, positionals. */\nexport function parseArgs(argv: string[]): ParsedArgs {\n  const positionals: string[] = []\n  const flags: Record<string, string | boolean> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]!\n    if (arg.startsWith(\"--\")) {\n      const eq = arg.indexOf(\"=\")\n      if (eq !== -1) {\n        flags[arg.slice(2, eq)] = arg.slice(eq + 1)\n        continue\n      }\n      const key = arg.slice(2)\n      if (BOOLEAN_FLAGS.has(key)) {\n        flags[key] = true\n        continue\n      }\n      const next = argv[i + 1]\n      if (OPTIONAL_VALUE_FLAGS.has(key)) {\n        if (next !== undefined && !next.startsWith(\"-\")) {\n          flags[key] = next\n          i++\n        } else {\n          flags[key] = true\n        }\n        continue\n      }\n      if (next !== undefined && !next.startsWith(\"-\")) {\n        flags[key] = next\n        i++\n      } else {\n        flags[key] = true\n      }\n    } else if (arg.length > 1 && arg.startsWith(\"-\") && !/^-\\d/.test(arg)) {\n      // Single-dash short flags, e.g. `-v`, `-h` (each char is a boolean).\n      for (const ch of arg.slice(1)) flags[ch] = true\n    } else {\n      positionals.push(arg)\n    }\n  }\n  return { positionals, flags }\n}\n\n/**\n * Apply a `--api-base-url <url>` flag by setting `process.env.PUBLIC_API_BASE_URL`\n * so Vite inlines it into the client bundle (via envPrefix). Setting it on\n * process.env gives the flag precedence over any `.env` file value. No-op when\n * the flag is absent, leaving any `.env` value in effect.\n */\nexport function applyApiBaseUrlFlag(args: ParsedArgs): void {\n  const value = args.flags[\"api-base-url\"]\n  if (typeof value === \"string\" && value.length) {\n    process.env.PUBLIC_API_BASE_URL = value\n  }\n}\n\n/** A resolved `--port`, or the reason it could not be resolved. */\nexport type PortResolution =\n  | { ok: true; port: number; strictPort: boolean }\n  | { ok: false; error: string }\n\n/**\n * Resolve `--port` / `--strict-port` / `--no-strict-port` into Vite's server\n * options.\n *\n * An explicit `--port` is strict by default: writing `--port 3000` means the\n * port is a contract with something outside this process — a reverse proxy, a\n * container port mapping, an OAuth redirect URI — so binding 3001 instead is a\n * silent failure, not a recovery (a supervisor that only checks \"is anything\n * listening on 3000\" will happily report a server that nobody can reach).\n * Without the flag the default is merely \"some free port\", so Vite keeps\n * walking to the next one as it always has, and running two projects at once\n * needs no ceremony. `--strict-port` / `--no-strict-port` override either way.\n *\n * A bad value is an error rather than a silent fallback, for the same reason:\n * a typo'd `--port` that quietly became 5173 is exactly the failure strictness\n * exists to prevent.\n */\nexport function resolvePortOptions(\n  flags: Record<string, string | boolean>,\n  fallback: number,\n): PortResolution {\n  const raw = flags.port\n  let port = fallback\n  if (raw !== undefined) {\n    if (typeof raw !== \"string\") return { ok: false, error: \"--port needs a number, e.g. --port 3000\" }\n    const n = Number(raw)\n    if (!Number.isInteger(n) || n < 1 || n > 65535) {\n      return { ok: false, error: `Invalid --port \"${raw}\" — use an integer between 1 and 65535.` }\n    }\n    port = n\n  }\n  const strictPort = flags[\"no-strict-port\"]\n    ? false\n    : Boolean(flags[\"strict-port\"]) || raw !== undefined\n  return { ok: true, port, strictPort }\n}\n\n/** Environment variable read for `allowedHosts` when the flag is absent. */\nexport const ALLOWED_HOSTS_ENV = \"VANTAGE_ALLOWED_HOSTS\"\n\n/** Resolved `--host` / `--allowed-hosts`, or the reason they could not be resolved. */\nexport type HostResolution =\n  | { ok: true; options: { host?: string | true; allowedHosts?: string[] | true } }\n  | { ok: false; error: string }\n\n/**\n * Resolve `--host [addr]` and `--allowed-hosts <list|true>` (falling back to\n * `VANTAGE_ALLOWED_HOSTS`) into the subset of Vite's server options they map to.\n *\n * Only the keys that were actually set are returned, so spreading the result\n * into `server` / `preview` leaves Vite's defaults untouched when neither is\n * given — the default behaviour must not change for anyone who never asked.\n *\n * `allowedHosts` exists because Vite rejects (403) any request whose `Host`\n * is not localhost or the bound address. A reverse proxy in front of the dev\n * server — a sandbox preview proxy, a tunnel, a container network — presents\n * its own hostname, so that hostname must be listed (or the check disabled\n * with the literal `true`). The env form is for supervisors that start the\n * server and know the hostname; an explicit flag still wins over it.\n */\nexport function resolveHostOptions(\n  flags: Record<string, string | boolean>,\n  env: NodeJS.ProcessEnv = process.env,\n): HostResolution {\n  const options: { host?: string | true; allowedHosts?: string[] | true } = {}\n\n  const host = flags.host\n  // bare `--host` and `--host=` both mean \"every interface\"\n  if (host === true || host === \"\") options.host = true\n  else if (typeof host === \"string\") options.host = host\n\n  const flag = flags[\"allowed-hosts\"]\n  if (flag === true) {\n    return {\n      ok: false,\n      error: `--allowed-hosts needs a comma-separated list of hostnames, or \"true\" to allow any`,\n    }\n  }\n  const raw = typeof flag === \"string\" ? flag : env[ALLOWED_HOSTS_ENV]\n  const allowedHosts = parseAllowedHosts(raw)\n  if (allowedHosts !== undefined) options.allowedHosts = allowedHosts\n\n  return { ok: true, options }\n}\n\n/** `\"a,b\"` → `[\"a\",\"b\"]`, the literal `true` → `true`, unset/blank → undefined (Vite default). */\nfunction parseAllowedHosts(raw: string | undefined): string[] | true | undefined {\n  if (raw === undefined) return undefined\n  const trimmed = raw.trim()\n  if (trimmed === \"\") return undefined\n  if (trimmed === \"true\") return true\n  const hosts = trimmed\n    .split(\",\")\n    .map((h) => h.trim())\n    .filter((h) => h.length > 0)\n  return hosts.length ? hosts : undefined\n}\n\n/**\n * Resolve `--overlay` / `--no-overlay` into Vite's `server.hmr.overlay`.\n *\n * The overlay stays on by default — it is the fastest way for a human to see a\n * runtime error. `--no-overlay` is for the cases where a full-screen error card\n * is in the way rather than helpful: screenshots and demos, and agent-driven\n * sessions where the error already arrives in the terminal through console\n * forwarding and the overlay only obscures the page being inspected.\n */\nexport function resolveHmrOverlay(flags: Record<string, string | boolean>): boolean {\n  if (flags.overlay) return true\n  return !flags[\"no-overlay\"]\n}\n\n/**\n * Whether `dev` accepts unfinished files (`--draft-preview` or\n * `VANTAGE_DRAFT_PREVIEW=1`). Off by default: the endpoint it opens is only for\n * a supervisor (the Squadbase sandbox) that streams an agent's half-written\n * files into the preview, and a plain dev server should not have it.\n */\nexport function resolveDraftPreview(flags: Record<string, string | boolean>): boolean {\n  const flag = flags[\"draft-preview\"]\n  if (flag === true || flag === \"true\" || flag === \"1\") return true\n  if (flag !== undefined) return false\n  return process.env.VANTAGE_DRAFT_PREVIEW === \"1\"\n}\n\n/**\n * Report a strict bind that lost the port, in the one shape dev and preview\n * share. Returns false when `err` is anything else, so the caller rethrows.\n * Vite throws a plain Error (no `code`) for this, hence the message match — a\n * reworded Vite message degrades to the generic handler, not to a wrong one.\n */\nexport function reportPortInUse(err: unknown, port: number, strictPort: boolean): boolean {\n  if (!strictPort || !(err instanceof Error) || !/already in use/.test(err.message)) return false\n  log.error(`Port ${port} is already in use.`)\n  log.info(\"  free that port, pass a different --port, or --no-strict-port to take the next one\")\n  return true\n}\n\n/** Resolve the project root, honoring `--root`, defaulting to cwd. */\nexport function resolveRoot(flags: Record<string, string | boolean>): string {\n  const raw = typeof flags.root === \"string\" ? flags.root : process.cwd()\n  return path.resolve(raw)\n}\n\n/** How far up from a page file to look for the package root. */\nconst QUICK_ROOT_MAX_DEPTH = 5\n\n/**\n * Resolve a positional path to a quick-run project root.\n * A directory → itself; a page file (.tsx/.jsx) → its project; else null.\n */\nexport function resolveQuickRoot(target: string): string | null {\n  try {\n    const abs = path.resolve(target)\n    const stat = fs.statSync(abs)\n    if (stat.isDirectory()) return abs\n    if (stat.isFile() && PAGE_EXTENSIONS.some((ext) => abs.endsWith(ext))) {\n      // Walk up to the nearest package.json so `vantage ./demo/src/index.tsx`\n      // starts in ./demo — the directory holding the page is not the project\n      // root once pages live under src/ (or in any nested route directory).\n      let dir = path.dirname(abs)\n      for (let i = 0; i <= QUICK_ROOT_MAX_DEPTH; i++) {\n        if (fs.existsSync(path.join(dir, \"package.json\"))) return dir\n        const parent = path.dirname(dir)\n        if (parent === dir) break\n        dir = parent\n      }\n      return path.dirname(abs)\n    }\n  } catch {\n    // statSync throws when the path does not exist → null (not a quick target)\n  }\n  return null\n}\n\nexport const log = {\n  info: (msg: string) => console.log(msg),\n  step: (msg: string) => console.log(pc.cyan(\"→ \") + msg),\n  ok: (msg: string) => console.log(pc.green(\"✓ \") + msg),\n  warn: (msg: string) => console.log(pc.yellow(\"! \") + msg),\n  error: (msg: string) => console.error(pc.red(\"✗ \") + msg),\n  brand: (msg: string) => console.log(pc.bold(pc.magenta(\"vantage \")) + msg),\n}\n\n/** Print diagnostics as human-readable text. */\nexport function printDiagnostics(diags: Diagnostic[]): void {\n  for (const d of diags) {\n    const badge =\n      d.severity === \"error\" ? pc.red(pc.bold(\" ERROR \")) : pc.yellow(pc.bold(\" WARN \"))\n    console.log(`${badge} ${pc.dim(d.code)} ${d.message}`)\n    if (d.files?.length) console.log(`        ${pc.dim(\"files:\")} ${d.files.join(\", \")}`)\n    if (d.fix) console.log(`        ${pc.dim(\"fix:\")} ${d.fix}`)\n  }\n}\n\n/** Emit a JSON payload to stdout (for agent consumption). */\nexport function printJson(payload: unknown): void {\n  process.stdout.write(JSON.stringify(payload, null, 2) + \"\\n\")\n}\n\n/** Read the vantage package version. */\nexport function frameworkVersion(): string {\n  try {\n    // dist/cli.js (and shared chunks) live in dist/, so package.json is one up.\n    const url = new URL(\"../package.json\", import.meta.url)\n    const pkg = JSON.parse(fs.readFileSync(url, \"utf8\")) as { version: string }\n    return pkg.version\n  } catch {\n    return \"0.0.0\"\n  }\n}\n\nexport function fileExists(p: string): boolean {\n  try {\n    return fs.existsSync(p)\n  } catch {\n    return false\n  }\n}\n"]}