@squadbase/vantage 0.0.1

package/dist/cli.js

@@ -0,0 +1,765 @@
+#!/usr/bin/env node
+import { PAGE_EXTENSIONS, scanProject, vantagePlugin, generateArtifacts, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, API_METHODS, PUBLIC_ENV_PREFIX } from './chunk-ZGDU5YLH.js';
+import './chunk-73J5ZD4C.js';
+import './chunk-B7LLBNLV.js';
+import path2 from 'path';
+import pc2 from 'picocolors';
+import fs2 from 'fs';
+import { createRequire } from 'module';
+import { loadEnv, createServer, build as build$1 } from 'vite';
+import { build as build$2 } from 'esbuild';
+import { spawn } from 'child_process';
+
+// @squadbase/vantage — generated build. Do not edit.
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "force", "verbose", "version", "h", "v"]);
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        continue;
+      }
+      const key = arg.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) {
+        flags[key] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.length > 1 && arg.startsWith("-") && !/^-\d/.test(arg)) {
+      for (const ch of arg.slice(1)) flags[ch] = true;
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+function parsePort(value, fallback) {
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isInteger(n) && n > 0 && n < 65536) return n;
+  }
+  return fallback;
+}
+function resolveRoot(flags) {
+  const raw = typeof flags.root === "string" ? flags.root : process.cwd();
+  return path2.resolve(raw);
+}
+function resolveQuickRoot(target) {
+  try {
+    const abs = path2.resolve(target);
+    const stat = fs2.statSync(abs);
+    if (stat.isDirectory()) return abs;
+    if (stat.isFile() && PAGE_EXTENSIONS.some((ext) => abs.endsWith(ext))) {
+      return path2.dirname(abs);
+    }
+  } catch {
+  }
+  return null;
+}
+var log = {
+  info: (msg) => console.log(msg),
+  step: (msg) => console.log(pc2.cyan("\u2192 ") + msg),
+  ok: (msg) => console.log(pc2.green("\u2713 ") + msg),
+  warn: (msg) => console.log(pc2.yellow("! ") + msg),
+  error: (msg) => console.error(pc2.red("\u2717 ") + msg),
+  brand: (msg) => console.log(pc2.bold(pc2.magenta("vantage ")) + msg)
+};
+function printDiagnostics(diags) {
+  for (const d of diags) {
+    const badge = d.severity === "error" ? pc2.red(pc2.bold(" ERROR ")) : pc2.yellow(pc2.bold(" WARN "));
+    console.log(`${badge} ${pc2.dim(d.code)} ${d.message}`);
+    if (d.files?.length) console.log(`        ${pc2.dim("files:")} ${d.files.join(", ")}`);
+    if (d.fix) console.log(`        ${pc2.dim("fix:")} ${d.fix}`);
+  }
+}
+function printJson(payload) {
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+function frameworkVersion() {
+  try {
+    const url = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(fs2.readFileSync(url, "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/cli/add.ts
+var PKG = "@squadbase/vantage";
+function toPascalCase(segment) {
+  const cleaned = segment.replace(/\[|\]|\./g, "").replace(/\.\.\./g, "");
+  const words = cleaned.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+  const pascal = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+  return /^[A-Za-z]/.test(pascal) ? pascal : "Page";
+}
+function pageTemplate(name) {
+  const last = name.split("/").pop() ?? name;
+  const component = last === "index" ? toPascalCase(name.split("/").slice(-2)[0] ?? "Home") : toPascalCase(last);
+  const title = last.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `import { definePage } from "${PKG}"
+
+export const page = definePage({ title: ${JSON.stringify(title)} })
+
+export default function ${component}() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">${title}</h1>
+    </main>
+  )
+}
+`;
+}
+function apiTemplate() {
+  return `import type { ApiContext } from "${PKG}/server"
+
+export async function GET({ request, params }: ApiContext) {
+  return Response.json({ ok: true, params })
+}
+`;
+}
+function resolveRegistryDir(root) {
+  try {
+    const require2 = createRequire(path2.join(root, "noop.js"));
+    const pkgJson = require2.resolve(`${PKG}/package.json`);
+    return path2.join(path2.dirname(pkgJson), "registry");
+  } catch {
+    return null;
+  }
+}
+function copyFromRegistry(root, kind, name, force) {
+  const registry = resolveRegistryDir(root);
+  if (!registry) {
+    log.error("Could not resolve the Vantage registry.");
+    return 1;
+  }
+  const sub = kind === "ui" ? "ui" : "blocks";
+  const src = path2.join(registry, sub, `${name}.tsx`);
+  if (!fs2.existsSync(src)) {
+    const available = fs2.existsSync(path2.join(registry, sub)) ? fs2.readdirSync(path2.join(registry, sub)).map((f) => f.replace(/\.tsx$/, "")) : [];
+    log.error(`Unknown ${kind} "${name}". Available: ${available.join(", ") || "(none)"}`);
+    return 1;
+  }
+  const destDir = path2.join(root, "components", kind === "ui" ? "ui" : "blocks");
+  const dest = path2.join(destDir, `${name}.tsx`);
+  if (fs2.existsSync(dest) && !force) {
+    log.error(`${path2.relative(root, dest)} already exists. Use --force to overwrite.`);
+    return 1;
+  }
+  fs2.mkdirSync(destDir, { recursive: true });
+  fs2.copyFileSync(src, dest);
+  log.ok(`Added ${path2.relative(root, dest)}`);
+  return 0;
+}
+async function add(root, args) {
+  const kind = args.positionals[1];
+  const name = args.positionals[2];
+  const force = Boolean(args.flags.force);
+  if (!kind || !name) {
+    log.error("Usage: vantage add <page|api|ui|block> <name>");
+    return 1;
+  }
+  if (kind === "page") {
+    const file = path2.join(root, name.endsWith(".tsx") ? name : `${name}.tsx`);
+    if (fs2.existsSync(file) && !force) {
+      log.error(`${path2.relative(root, file)} already exists. Use --force to overwrite.`);
+      return 1;
+    }
+    fs2.mkdirSync(path2.dirname(file), { recursive: true });
+    fs2.writeFileSync(file, pageTemplate(name));
+    log.ok(`Added page ${path2.relative(root, file)}`);
+    return 0;
+  }
+  if (kind === "api") {
+    const rel2 = name.startsWith("server/api/") ? name : path2.join("server", "api", name);
+    const file = path2.join(root, rel2.endsWith(".ts") ? rel2 : `${rel2}.ts`);
+    if (fs2.existsSync(file) && !force) {
+      log.error(`${path2.relative(root, file)} already exists. Use --force to overwrite.`);
+      return 1;
+    }
+    fs2.mkdirSync(path2.dirname(file), { recursive: true });
+    fs2.writeFileSync(file, apiTemplate());
+    log.ok(`Added API ${path2.relative(root, file)}`);
+    return 0;
+  }
+  if (kind === "ui") return copyFromRegistry(root, "ui", name, force);
+  if (kind === "block") return copyFromRegistry(root, "block", name, force);
+  log.error(`Unknown add target "${kind}". Use one of: page, api, ui, block.`);
+  return 1;
+}
+var ALLOWED_ENV_KEYS = /* @__PURE__ */ new Set(["MODE", "DEV", "PROD", "SSR", "BASE_URL", "PUBLIC_"]);
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'`\\])\/\/[^\n]*/g, "$1");
+}
+function hasDefaultExport(src) {
+  return /\bexport\s+default\b/.test(src) || /\bexport\s*\{[^}]*\bas\s+default\b[^}]*\}/.test(src) || /\bexport\s*\{[^}]*\bdefault\b[^}]*\}\s*from\b/.test(src);
+}
+function collectClientFiles(root) {
+  const out = [];
+  const skipDirs = /* @__PURE__ */ new Set(["node_modules", ".vantage", "dist", "server", "public"]);
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const abs = path2.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        walk(abs);
+      } else if (/\.(tsx?|jsx?)$/.test(entry.name)) {
+        out.push(abs);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+function rel(root, abs) {
+  return path2.relative(root, abs).split(path2.sep).join("/");
+}
+function checkForbiddenFiles(root) {
+  const diags = [];
+  let entries = [];
+  try {
+    entries = fs2.readdirSync(root);
+  } catch {
+    return diags;
+  }
+  for (const name of entries) {
+    for (const rule of FORBIDDEN_FILES) {
+      if (rule.pattern.test(name)) {
+        diags.push({
+          code: "FORBIDDEN_FILE",
+          severity: "error",
+          message: `${rule.label} file "${name}" is not allowed in a Vantage project.`,
+          files: [name],
+          fix: rule.remedy
+        });
+      }
+    }
+  }
+  return diags;
+}
+function checkRouteConflicts(model) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const page of model.pages) {
+    const list = byPath.get(page.routePath) ?? [];
+    list.push(page.file);
+    byPath.set(page.routePath, list);
+  }
+  const diags = [];
+  for (const [routePath, files] of byPath) {
+    if (files.length > 1) {
+      diags.push({
+        code: "ROUTE_CONFLICT",
+        severity: "error",
+        message: `${files.length} files resolve to ${routePath}`,
+        files,
+        fix: "Rename or remove one route file so each route is unique."
+      });
+    }
+  }
+  return diags;
+}
+function checkPageExports(root, model) {
+  const diags = [];
+  const pageFiles = [
+    ...model.pages.map((p) => p.absFile),
+    ...model.layouts.map((l) => l.absFile),
+    model.notFound && path2.join(root, model.notFound),
+    model.error && path2.join(root, model.error)
+  ].filter((x) => Boolean(x));
+  for (const abs of pageFiles) {
+    let src;
+    try {
+      src = stripComments(fs2.readFileSync(abs, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!hasDefaultExport(src)) {
+      diags.push({
+        code: "MISSING_DEFAULT_EXPORT",
+        severity: "error",
+        message: `Page module has no default export.`,
+        files: [rel(root, abs)],
+        fix: "A page/layout must `export default` a React component."
+      });
+    }
+  }
+  return diags;
+}
+function checkApiExports(root, model) {
+  const diags = [];
+  for (const api of model.apis) {
+    let src;
+    try {
+      src = stripComments(fs2.readFileSync(api.absFile, "utf8"));
+    } catch {
+      continue;
+    }
+    const exported = API_METHODS.filter(
+      (m) => new RegExp(`export\\s+(async\\s+)?(function|const|let|var)\\s+${m}\\b`).test(src) || new RegExp(`export\\s*\\{[^}]*\\b${m}\\b[^}]*\\}`).test(src)
+    );
+    if (exported.length === 0) {
+      const lower = ["get", "post", "put", "patch", "delete", "options"].filter(
+        (m) => new RegExp(`export\\s+(async\\s+)?function\\s+${m}\\b`).test(src)
+      );
+      diags.push({
+        code: "INVALID_API_EXPORT",
+        severity: "error",
+        message: `API module exports no HTTP method handler${lower.length ? ` (found lowercase "${lower.join(", ")}")` : ""}.`,
+        files: [api.file],
+        fix: `Export one of: ${API_METHODS.join(", ")} (uppercase).`
+      });
+    }
+  }
+  return diags;
+}
+function checkClientServerBoundary(root) {
+  const diags = [];
+  const importRe = /(?:import|export)[^'"]*?from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)/g;
+  for (const abs of collectClientFiles(root)) {
+    let src;
+    try {
+      src = stripComments(fs2.readFileSync(abs, "utf8"));
+    } catch {
+      continue;
+    }
+    let m;
+    importRe.lastIndex = 0;
+    while (m = importRe.exec(src)) {
+      const spec = m[1] ?? m[2];
+      if (!spec) continue;
+      const isServer = spec === "server" || spec.startsWith("server/") || /(^|\/)\.\.?\/server(\/|$)/.test(spec) || /\/server\//.test(spec);
+      if (isServer) {
+        diags.push({
+          code: "CLIENT_IMPORTS_SERVER",
+          severity: "error",
+          message: `Client module imports from server/ ("${spec}").`,
+          files: [rel(root, abs)],
+          fix: "server/ code must never be imported by the client. Move shared code to lib/."
+        });
+      }
+    }
+  }
+  return diags;
+}
+function checkPublicEnv(root) {
+  const diags = [];
+  const envRe = /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+  for (const abs of collectClientFiles(root)) {
+    let src;
+    try {
+      src = stripComments(fs2.readFileSync(abs, "utf8"));
+    } catch {
+      continue;
+    }
+    let m;
+    envRe.lastIndex = 0;
+    const bad = /* @__PURE__ */ new Set();
+    while (m = envRe.exec(src)) {
+      const key = m[1];
+      if (ALLOWED_ENV_KEYS.has(key)) continue;
+      if (key.startsWith(PUBLIC_ENV_PREFIX)) continue;
+      bad.add(key);
+    }
+    for (const key of bad) {
+      diags.push({
+        code: "PUBLIC_ENV_MISUSE",
+        severity: "warning",
+        message: `Client reads non-public env "import.meta.env.${key}".`,
+        files: [rel(root, abs)],
+        fix: `Only ${PUBLIC_ENV_PREFIX}* vars reach the client. Read secrets via ApiContext.env in server/.`
+      });
+    }
+  }
+  return diags;
+}
+function runDiagnostics(root, model) {
+  return [
+    ...checkForbiddenFiles(root),
+    ...checkRouteConflicts(model),
+    ...checkPageExports(root, model),
+    ...checkApiExports(root, model),
+    ...checkClientServerBoundary(root),
+    ...checkPublicEnv(root)
+  ];
+}
+
+// src/cli/build.ts
+var SERVER_ENTRY = `// AUTO-GENERATED by @squadbase/vantage.
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { startNodeServer } from "@squadbase/vantage/server/node"
+import { apiRoutes } from "./server-routes.gen"
+
+const clientDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../client")
+startNodeServer({ apiRoutes, clientDir })
+`;
+async function build(root, args) {
+  const model = scanProject(root);
+  const errors = runDiagnostics(root, model).filter((d) => d.severity === "error");
+  if (errors.length) {
+    printDiagnostics(errors);
+    log.error("Fix the errors above before building.");
+    return 1;
+  }
+  const mode = "production";
+  const env = { ...process.env, ...loadEnv(mode, root, "") };
+  const quiet = Boolean(args.flags.json);
+  if (!quiet) log.step("Building client\u2026");
+  await build$1({
+    configFile: false,
+    root,
+    mode,
+    plugins: [vantagePlugin({ root, env })],
+    logLevel: quiet ? "silent" : args.flags.verbose ? "info" : "warn"
+  });
+  relocateClientHtml(root);
+  if (model.hasServer) {
+    if (!quiet) log.step("Building server\u2026");
+    await buildServer(root);
+  }
+  writeDeployManifest(root, model);
+  if (!quiet) log.ok(`Build complete \u2192 ${path2.relative(process.cwd(), path2.join(root, "dist")) || "dist"}/`);
+  if (args.flags.json) {
+    process.stdout.write(
+      JSON.stringify({
+        ok: true,
+        mode: model.hasServer ? "fullstack" : "spa",
+        output: "dist",
+        pages: model.pages.length,
+        apis: model.apis.length
+      }) + "\n"
+    );
+  }
+  return 0;
+}
+function relocateClientHtml(root) {
+  const clientDir = path2.join(root, "dist", "client");
+  const nested = path2.join(clientDir, VANTAGE_DIR, "index.html");
+  const target = path2.join(clientDir, "index.html");
+  if (fs2.existsSync(nested)) {
+    fs2.mkdirSync(clientDir, { recursive: true });
+    fs2.renameSync(nested, target);
+    fs2.rmSync(path2.join(clientDir, VANTAGE_DIR), { recursive: true, force: true });
+  }
+}
+async function buildServer(root) {
+  const vantageDir = path2.join(root, VANTAGE_DIR);
+  const entry = path2.join(vantageDir, "server-entry.ts");
+  fs2.writeFileSync(entry, SERVER_ENTRY);
+  await build$2({
+    entryPoints: [entry],
+    outfile: path2.join(root, "dist", "server", "index.mjs"),
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    target: "node20",
+    logLevel: "warning",
+    banner: { js: "// @squadbase/vantage server bundle" }
+  });
+}
+function writeDeployManifest(root, model) {
+  const dist = path2.join(root, "dist");
+  fs2.mkdirSync(dist, { recursive: true });
+  const manifest = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    mode: model.hasServer ? "fullstack" : "spa",
+    client: "./client",
+    ...model.hasServer ? { server: "./server/index.mjs" } : {},
+    spaFallback: "./client/index.html",
+    runtime: "node"
+  };
+  fs2.writeFileSync(path2.join(dist, "vantage-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// src/cli/check.ts
+async function check(root, args) {
+  const model = scanProject(root);
+  const diags = runDiagnostics(root, model);
+  const errors = diags.filter((d) => d.severity === "error");
+  const warnings = diags.filter((d) => d.severity === "warning");
+  if (args.flags.json) {
+    printJson({
+      ok: errors.length === 0,
+      errorCount: errors.length,
+      warningCount: warnings.length,
+      diagnostics: diags
+    });
+    return errors.length ? 1 : 0;
+  }
+  if (diags.length === 0) {
+    log.ok("No problems found.");
+    return 0;
+  }
+  printDiagnostics(diags);
+  console.log("");
+  if (errors.length) log.error(`${errors.length} error(s), ${warnings.length} warning(s).`);
+  else log.warn(`${warnings.length} warning(s).`);
+  return errors.length ? 1 : 0;
+}
+async function dev(root, args) {
+  const model = scanProject(root);
+  const errors = runDiagnostics(root, model).filter((d) => d.severity === "error");
+  if (errors.length) {
+    printDiagnostics(errors);
+    log.error("Fix the errors above before starting the dev server.");
+    return 1;
+  }
+  const mode = "development";
+  const env = { ...process.env, ...loadEnv(mode, root, "") };
+  const port = parsePort(args.flags.port, 5173);
+  const server = await createServer({
+    configFile: false,
+    root,
+    mode,
+    plugins: [vantagePlugin({ root, env })],
+    server: { port },
+    clearScreen: false
+  });
+  await server.listen();
+  log.brand("dev server ready");
+  server.printUrls();
+  if (model.hasServer) log.info("  server/api enabled");
+  const shutdown = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  return new Promise(() => {
+  });
+}
+async function doctor(root, args) {
+  const facets = [];
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  facets.push({
+    name: "node",
+    ok: nodeMajor >= 20,
+    detail: `v${process.versions.node}${nodeMajor >= 20 ? "" : " (requires >= 20)"}`
+  });
+  const pkgPath = path2.join(root, "package.json");
+  facets.push({ name: "package.json", ok: fs2.existsSync(pkgPath), detail: fs2.existsSync(pkgPath) ? "found" : "missing" });
+  const lockfiles = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock"];
+  const lock = lockfiles.find((f) => fs2.existsSync(path2.join(root, f)) || fs2.existsSync(path2.join(root, "..", f)) || fs2.existsSync(path2.join(root, "..", "..", f)));
+  facets.push({ name: "lockfile", ok: Boolean(lock), detail: lock ?? "none found" });
+  let installedVantage = "not installed";
+  let vantageOk = false;
+  try {
+    const require2 = createRequire(path2.join(root, "noop.js"));
+    const p = require2.resolve("@squadbase/vantage/package.json");
+    installedVantage = JSON.parse(fs2.readFileSync(p, "utf8")).version;
+    vantageOk = true;
+  } catch {
+  }
+  facets.push({ name: "@squadbase/vantage", ok: vantageOk, detail: installedVantage });
+  const model = scanProject(root);
+  const errors = runDiagnostics(root, model).filter((d) => d.severity === "error");
+  facets.push({
+    name: "project",
+    ok: errors.length === 0,
+    detail: errors.length === 0 ? "no blocking errors" : `${errors.length} error(s) (run \`vantage check\`)`
+  });
+  const allOk = facets.every((f) => f.ok);
+  if (args.flags.json) {
+    printJson({ ok: allOk, cli: frameworkVersion(), facets });
+    return allOk ? 0 : 1;
+  }
+  log.brand(`doctor (cli v${frameworkVersion()})`);
+  for (const f of facets) {
+    const line = `${f.name.padEnd(22)} ${f.detail}`;
+    if (f.ok) log.ok(line);
+    else log.error(line);
+  }
+  return allOk ? 0 : 1;
+}
+async function preview(root, args) {
+  const manifestPath = path2.join(root, "dist", "vantage-manifest.json");
+  if (!fs2.existsSync(manifestPath)) {
+    log.error("No build found. Run `vantage build` first.");
+    return 1;
+  }
+  const manifest = JSON.parse(fs2.readFileSync(manifestPath, "utf8"));
+  const port = parsePort(args.flags.port, 4173);
+  if (manifest.mode === "fullstack") {
+    const serverPath = path2.join(root, "dist", "server", "index.mjs");
+    if (!fs2.existsSync(serverPath)) {
+      log.error("Server bundle missing. Re-run `vantage build`.");
+      return 1;
+    }
+    log.brand(`preview (fullstack) \u2192 http://localhost:${port}`);
+    const child = spawn(process.execPath, [serverPath], {
+      stdio: "inherit",
+      env: { ...process.env, PORT: String(port) }
+    });
+    return new Promise((resolve) => {
+      child.on("exit", (code) => resolve(code ?? 0));
+      const stop = () => child.kill("SIGINT");
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+    });
+  }
+  const { preview: vitePreview } = await import('vite');
+  const server = await vitePreview({
+    configFile: false,
+    root,
+    build: { outDir: path2.join(root, "dist", "client") },
+    preview: { port }
+  });
+  log.brand("preview (spa)");
+  server.printUrls();
+  return new Promise(() => {
+  });
+}
+async function routes(root, args) {
+  const model = scanProject(root);
+  if (args.flags.json) {
+    printJson({
+      pages: model.pages.map((p) => ({ route: p.routePath, file: p.file, dynamic: p.dynamic })),
+      layouts: model.layouts.map((l) => ({ dir: l.dir === "" ? "/" : l.dir, file: l.file })),
+      notFound: model.notFound,
+      error: model.error,
+      apis: model.apis.map((a) => ({ route: a.routePath, file: a.file, params: a.params })),
+      hasServer: model.hasServer
+    });
+    return 0;
+  }
+  console.log(pc2.bold("\nPages"));
+  if (model.pages.length === 0) console.log(pc2.dim("  (none)"));
+  for (const p of model.pages) {
+    console.log(`  ${pc2.green(p.routePath.padEnd(28))} ${pc2.dim(p.file)}`);
+  }
+  if (model.layouts.length || model.notFound || model.error) {
+    console.log(pc2.bold("\nSpecial"));
+    for (const l of model.layouts) {
+      console.log(`  ${pc2.cyan(("layout " + (l.dir === "" ? "/" : "/" + l.dir)).padEnd(28))} ${pc2.dim(l.file)}`);
+    }
+    if (model.notFound) console.log(`  ${pc2.cyan("404".padEnd(28))} ${pc2.dim(model.notFound)}`);
+    if (model.error) console.log(`  ${pc2.cyan("error".padEnd(28))} ${pc2.dim(model.error)}`);
+  }
+  if (model.hasServer) {
+    console.log(pc2.bold("\nAPI"));
+    if (model.apis.length === 0) console.log(pc2.dim("  (none)"));
+    for (const a of model.apis) {
+      console.log(`  ${pc2.yellow(a.routePath.padEnd(28))} ${pc2.dim(a.file)}`);
+    }
+  }
+  console.log("");
+  return 0;
+}
+
+// src/cli/upgrade.ts
+async function upgrade(root, args) {
+  const version = frameworkVersion();
+  const model = scanProject(root);
+  generateArtifacts({ root, model });
+  if (args.flags.json) {
+    printJson({ ok: true, version, transforms: [], regenerated: true });
+    return 0;
+  }
+  log.brand(`upgrade \u2192 v${version}`);
+  log.ok("Regenerated .vantage artifacts.");
+  log.info("No breaking code transforms required for this version.");
+  return 0;
+}
+
+// src/cli.ts
+var HELP = `${pc2.bold(pc2.magenta("vantage"))} \u2014 data dashboard framework for Squadbase
+
+${pc2.bold("Usage")}
+  vantage <command> [path] [options]
+  vantage <path>                     Quick dev shortcut (folder or entry file)
+
+${pc2.bold("Commands")}
+  dev                 Start the dev server (HMR + optional API)
+  build               Build client and optional server into dist/
+  preview             Run the production build locally
+  check               Static verification (routes, boundaries, forbidden files)
+  routes              Show page and API URL map
+  add <kind> <name>   Scaffold a page | api | ui | block
+  doctor              Environment and installation health checks
+  upgrade             Regenerate artifacts / apply migrations
+
+${pc2.bold("Options")}
+  --json              Machine-readable output (check, routes, doctor, build)
+  --port <n>          Port for dev/preview
+  --root <dir>        Project root (default: cwd)
+  --force             Overwrite when scaffolding
+  -v, --version       Print version
+  -h, --help          Print this help
+`;
+var COMMANDS = {
+  dev,
+  build,
+  preview,
+  check,
+  routes,
+  add,
+  doctor,
+  upgrade
+};
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args.positionals[0];
+  if (args.flags.version || args.flags.v) {
+    console.log(frameworkVersion());
+    return;
+  }
+  if (!command || args.flags.help || args.flags.h || command === "help") {
+    console.log(HELP);
+    return;
+  }
+  let runFn = COMMANDS[command];
+  let root;
+  if (runFn) {
+    const targetArg = command !== "add" ? args.positionals[1] : void 0;
+    if (targetArg !== void 0) {
+      const quick = resolveQuickRoot(targetArg);
+      if (!quick) {
+        log.error(`No such file or directory: "${targetArg}"`);
+        process.exitCode = 1;
+        return;
+      }
+      root = quick;
+    } else {
+      root = resolveRoot(args.flags);
+    }
+  } else {
+    const quick = resolveQuickRoot(command);
+    if (!quick) {
+      log.error(`Unknown command "${command}".`);
+      console.log(HELP);
+      process.exitCode = 1;
+      return;
+    }
+    runFn = dev;
+    root = quick;
+    log.brand(`quick dev \u2192 ${path2.relative(process.cwd(), root) || "."}`);
+  }
+  try {
+    const code = await runFn(root, args);
+    process.exitCode = code;
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    if (process.env.VANTAGE_DEBUG && err instanceof Error) console.error(err.stack);
+    process.exitCode = 1;
+  }
+}
+void main();
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map