@squadbase/vantage 0.2.2 → 0.3.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { PAGE_EXTENSIONS, scanProject, vantagePlugin, generateArtifacts, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, API_METHODS, PUBLIC_ENV_PREFIX } from './chunk-UHZ7XSAN.js';
+import { PAGE_EXTENSIONS, scanProject, vantagePlugin, generateArtifacts, resolvePageRoot, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, SRC_DIR, SUSPICIOUS_ROUTE_DIRS, API_METHODS, PUBLIC_ENV_PREFIX, extractPageMeta } from './chunk-5UGRNXHC.js';
 import './chunk-46QI6GFC.js';
 import './chunk-B7LLBNLV.js';
 import path2 from 'path';
@@ -12,7 +12,21 @@ import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 
 // @squadbase/vantage — generated build. Do not edit.
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "force", "verbose", "version", "all", "list", "regex", "h", "v"]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "json",
+  "help",
+  "force",
+  "verbose",
+  "version",
+  "all",
+  "list",
+  "regex",
+  "pages",
+  "apis",
+  "detail",
+  "h",
+  "v"
+]);
 function parseArgs(argv) {
   const positionals = [];
   const flags = {};
@@ -61,12 +75,20 @@ function resolveRoot(flags) {
   const raw = typeof flags.root === "string" ? flags.root : process.cwd();
   return path2.resolve(raw);
 }
+var QUICK_ROOT_MAX_DEPTH = 5;
 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))) {
+      let dir = path2.dirname(abs);
+      for (let i = 0; i <= QUICK_ROOT_MAX_DEPTH; i++) {
+        if (fs2.existsSync(path2.join(dir, "package.json"))) return dir;
+        const parent = path2.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
       return path2.dirname(abs);
     }
   } catch {
@@ -305,7 +327,7 @@ function copyFromRegistry(root, kind, name, force) {
     log.error(`Unknown ${kind} "${name}". Available: ${available.join(", ") || "(none)"}`);
     return 1;
   }
-  const destDir = path2.join(root, "components", kind === "ui" ? "ui" : "blocks");
+  const destDir = path2.join(resolvePageRoot(root).abs, "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.`);
@@ -331,7 +353,8 @@ async function add(root, args) {
     return 1;
   }
   if (kind === "page") {
-    const file = path2.join(root, name.endsWith(".tsx") ? name : `${name}.tsx`);
+    const pageRoot = resolvePageRoot(root).abs;
+    const file = path2.join(pageRoot, 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;
@@ -358,10 +381,202 @@ async function add(root, args) {
   log.error(`Unknown add target "${kind}". Use one of: page, api, ui, block, skill, agents.`);
   return 1;
 }
-var ALLOWED_ENV_KEYS = /* @__PURE__ */ new Set(["MODE", "DEV", "PROD", "SSR", "BASE_URL", "PUBLIC_"]);
+
+// src/core/source.ts
 function stripComments(src) {
   return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'`\\])\/\/[^\n]*/g, "$1");
 }
+var OPENERS = { "(": ")", "[": "]", "{": "}" };
+function readBracketBody(src, openIndex) {
+  const open = src[openIndex];
+  if (!open || !OPENERS[open]) return null;
+  let depth = 0;
+  let quote = null;
+  for (let i = openIndex; i < src.length; i++) {
+    const c = src[i];
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      continue;
+    }
+    if (OPENERS[c]) depth++;
+    else if (c === ")" || c === "]" || c === "}") {
+      if (--depth === 0) return src.slice(openIndex + 1, i);
+    }
+  }
+  return null;
+}
+function splitTopLevel(body) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      continue;
+    }
+    if (OPENERS[c]) depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "," && depth === 0) {
+      parts.push(body.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(body.slice(start));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+// src/core/route-spec.ts
+function detectApiMethods(src) {
+  return 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)
+  );
+}
+function methodRegions(src) {
+  const re = new RegExp(
+    `export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+(${API_METHODS.join("|")})\\b`,
+    "g"
+  );
+  const decls = [];
+  let m;
+  while (m = re.exec(src)) decls.push({ method: m[1], index: m.index });
+  const regions = /* @__PURE__ */ new Map();
+  decls.forEach((d, i) => {
+    regions.set(d.method, src.slice(d.index, decls[i + 1]?.index ?? src.length));
+  });
+  for (const method of detectApiMethods(src)) {
+    if (!regions.has(method)) regions.set(method, src);
+  }
+  return regions;
+}
+function objectKeys(expr) {
+  const trimmed = expr.trim();
+  if (!trimmed.startsWith("{")) return void 0;
+  const body = readBracketBody(trimmed, 0);
+  if (body == null) return void 0;
+  const keys = [];
+  for (const part of splitTopLevel(body)) {
+    if (part.startsWith("...")) {
+      keys.push("\u2026");
+      continue;
+    }
+    const name = part.match(/^["'`]?([A-Za-z0-9_$]+)/);
+    if (name) keys.push(name[1]);
+  }
+  return keys.length ? keys : void 0;
+}
+function initStatus(init) {
+  const m = init?.match(/\bstatus\s*:\s*(\d{3})\b/);
+  return m ? Number(m[1]) : void 0;
+}
+function initContentType(init) {
+  const m = init?.match(/["']?content-type["']?\s*:\s*["']([^"';]+)/i);
+  return m ? m[1].trim() : void 0;
+}
+function extractResponses(region) {
+  const re = /\bnew\s+Response\s*\(|\bResponse\s*\.\s*json\s*\(|(?<![.\w$])json\s*\(/g;
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  while (m = re.exec(region)) {
+    const isJson = !m[0].startsWith("new");
+    const args = readBracketBody(region, m.index + m[0].length - 1);
+    if (args == null) continue;
+    const [payload, init] = splitTopLevel(args);
+    const contentType = isJson ? "application/json" : initContentType(init) ?? (payload?.startsWith("JSON.stringify") ? "application/json" : void 0);
+    const keys = isJson && payload ? objectKeys(payload) : void 0;
+    const spec = {
+      status: initStatus(init) ?? 200,
+      ...contentType ? { contentType } : {},
+      ...keys ? { keys } : {}
+    };
+    const key = JSON.stringify(spec);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(spec);
+  }
+  return out;
+}
+function extractErrors(region) {
+  const re = /\bHttpError\s*\(\s*(\d{3})\s*(?:,\s*(?:(["'`])((?:\\.|(?!\2)[\s\S])*)\2))?/g;
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  while (m = re.exec(region)) {
+    const message = m[3]?.replace(/\\(.)/g, "$1");
+    const spec = { status: Number(m[1]), ...message ? { message } : {} };
+    const key = JSON.stringify(spec);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(spec);
+  }
+  return out;
+}
+function extractQuery(region) {
+  const re = /searchParams\s*\.\s*(?:get|getAll|has)\s*\(\s*["'`]([^"'`]+)["'`]/g;
+  const out = /* @__PURE__ */ new Set();
+  let m;
+  while (m = re.exec(region)) out.add(m[1]);
+  return [...out];
+}
+function extractBody(region) {
+  const read = region.match(/\b(?:request|req)\s*\.\s*(json|formData|text|arrayBuffer|blob)\s*\(/);
+  if (!read) return void 0;
+  const method = read[1];
+  const format = method === "json" || method === "formData" || method === "text" ? method : "binary";
+  const destructured = region.match(
+    /(?:const|let|var)\s*(\{[\s\S]*?\})\s*=\s*(?:await\s+)?[\w.]*\.json\s*\(/
+  );
+  const keys = format === "json" && destructured ? objectKeys(destructured[1]) : void 0;
+  return { format, ...keys ? { keys } : {} };
+}
+function toParams(segments) {
+  const out = [];
+  for (const s of segments) {
+    if (s.kind === "static") continue;
+    out.push({ name: s.name, kind: s.kind });
+  }
+  return out;
+}
+function extractPageSpec(page) {
+  return { params: toParams(page.segments), ...extractPageMeta(page.absFile) };
+}
+function extractApiSpec(api) {
+  const params = toParams(api.segments);
+  let src;
+  try {
+    src = stripComments(fs2.readFileSync(api.absFile, "utf8"));
+  } catch {
+    return { params, methods: [] };
+  }
+  const regions = methodRegions(src);
+  const methods = API_METHODS.filter((m) => regions.has(m)).map((method) => {
+    const region = regions.get(method);
+    const body = extractBody(region);
+    return {
+      method,
+      query: extractQuery(region),
+      ...body ? { body } : {},
+      responses: extractResponses(region),
+      errors: extractErrors(region)
+    };
+  });
+  return { params, methods };
+}
+
+// src/core/diagnostics.ts
+var ALLOWED_ENV_KEYS = /* @__PURE__ */ new Set(["MODE", "DEV", "PROD", "SSR", "BASE_URL", "PUBLIC_"]);
 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);
 }
@@ -415,6 +630,67 @@ function checkForbiddenFiles(root) {
   }
   return diags;
 }
+function checkSrcLayout(root, model) {
+  if (model.pageDir === "") return [];
+  const diags = [];
+  let entries = [];
+  try {
+    entries = fs2.readdirSync(root);
+  } catch {
+    return diags;
+  }
+  const strayPages = entries.filter((name) => PAGE_EXTENSIONS.some((ext) => name.endsWith(ext)));
+  if (strayPages.length > 0) {
+    diags.push({
+      code: "SRC_DIR_SPLIT",
+      severity: "error",
+      message: `${strayPages.length} page module(s) sit at the project root, but ${SRC_DIR}/ exists so pages are only scanned from ${SRC_DIR}/.`,
+      files: strayPages.sort(),
+      fix: `Move them into ${SRC_DIR}/, or delete ${SRC_DIR}/ to keep a root-level layout.`
+    });
+  }
+  if (entries.includes("styles.css")) {
+    diags.push({
+      code: "SRC_DIR_SPLIT",
+      severity: "error",
+      message: `styles.css sits at the project root, but ${SRC_DIR}/ exists so the global stylesheet is read from ${SRC_DIR}/styles.css.`,
+      files: ["styles.css"],
+      fix: `Move it to ${SRC_DIR}/styles.css.`
+    });
+  }
+  if (fs2.existsSync(path2.join(root, SRC_DIR, "server"))) {
+    diags.push({
+      code: "SRC_DIR_SPLIT",
+      severity: "error",
+      message: `${SRC_DIR}/server/ is never scanned: server code lives at the project root, outside the client source tree.`,
+      files: [`${SRC_DIR}/server`],
+      fix: `Move it to server/ at the project root.`
+    });
+  }
+  return diags;
+}
+function checkSuspiciousRouteDirs(model) {
+  const byDir = /* @__PURE__ */ new Map();
+  for (const page of model.pages) {
+    const top = page.dir.split("/")[0] ?? "";
+    if (top === "" || !SUSPICIOUS_ROUTE_DIRS.has(top)) continue;
+    const hit = byDir.get(top) ?? { files: [], routes: [] };
+    hit.files.push(page.file);
+    hit.routes.push(page.routePath);
+    byDir.set(top, hit);
+  }
+  const diags = [];
+  for (const [dir, hit] of byDir) {
+    diags.push({
+      code: "SUSPICIOUS_ROUTE_DIR",
+      severity: "warning",
+      message: `${dir}/ is part of the URL: ${hit.routes.slice(0, 3).join(", ")}${hit.routes.length > 3 ? ", \u2026" : ""}`,
+      files: hit.files,
+      fix: `Directory names become route segments. Non-page modules belong in components/, hooks/ or lib/ (never scanned); if ${dir}/ really is meant to be a URL segment, ignore this warning.`
+    });
+  }
+  return diags;
+}
 function checkRouteConflicts(model) {
   const byPath = /* @__PURE__ */ new Map();
   for (const page of model.pages) {
@@ -472,9 +748,7 @@ function checkApiExports(root, model) {
     } 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)
-    );
+    const exported = detectApiMethods(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)
@@ -553,6 +827,8 @@ function checkPublicEnv(root) {
 function runDiagnostics(root, model) {
   return [
     ...checkForbiddenFiles(root),
+    ...checkSrcLayout(root, model),
+    ...checkSuspiciousRouteDirs(model),
     ...checkRouteConflicts(model),
     ...checkPageExports(root, model),
     ...checkApiExports(root, model),
@@ -941,39 +1217,110 @@ async function preview(root, args) {
   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;
+var ROUTE_COLUMN = 28;
+var LABEL_COLUMN = 9;
+function detailLine(indent, label, value) {
+  console.log(`${indent}${pc3.dim(label.padEnd(LABEL_COLUMN))}${value}`);
+}
+function formatParams(params) {
+  return params.map((p) => p.kind === "catchall" ? `*${p.name}` : `:${p.name}`).join(", ");
+}
+function formatKeys(keys) {
+  return keys?.length ? ` { ${keys.join(", ")} }` : "";
+}
+function printPageSpec(spec) {
+  const indent = "      ";
+  if (spec.title) detailLine(indent, "title", spec.title);
+  if (spec.navLabel) detailLine(indent, "nav", spec.navLabel);
+  if (spec.description) detailLine(indent, "desc", spec.description);
+  if (spec.params.length) detailLine(indent, "params", formatParams(spec.params));
+}
+function printApiMethodSpec(method, params) {
+  const indent = "        ";
+  console.log(`      ${pc3.bold(method.method)}`);
+  if (params.length) detailLine(indent, "path", formatParams(params));
+  if (method.query.length) detailLine(indent, "query", method.query.join(", "));
+  if (method.body) detailLine(indent, "body", method.body.format + formatKeys(method.body.keys));
+  for (const res of method.responses) {
+    const parts = [String(res.status), res.contentType].filter(Boolean).join(" ");
+    detailLine(indent, "response", parts + formatKeys(res.keys));
   }
+  for (const err of method.errors) {
+    detailLine(indent, "error", `${err.status}${err.message ? ` "${err.message}"` : ""}`);
+  }
+}
+function printPages(model, detail) {
   console.log(pc3.bold("\nPages"));
   if (model.pages.length === 0) console.log(pc3.dim("  (none)"));
   for (const p of model.pages) {
-    console.log(`  ${pc3.green(p.routePath.padEnd(28))} ${pc3.dim(p.file)}`);
+    console.log(`  ${pc3.green(p.routePath.padEnd(ROUTE_COLUMN))} ${pc3.dim(p.file)}`);
+    if (detail) printPageSpec(extractPageSpec(p));
   }
   if (model.layouts.length || model.notFound || model.error) {
     console.log(pc3.bold("\nSpecial"));
     for (const l of model.layouts) {
-      console.log(`  ${pc3.cyan(("layout " + (l.dir === "" ? "/" : "/" + l.dir)).padEnd(28))} ${pc3.dim(l.file)}`);
+      const label = "layout " + (l.dir === "" ? "/" : "/" + l.dir);
+      console.log(`  ${pc3.cyan(label.padEnd(ROUTE_COLUMN))} ${pc3.dim(l.file)}`);
     }
-    if (model.notFound) console.log(`  ${pc3.cyan("404".padEnd(28))} ${pc3.dim(model.notFound)}`);
-    if (model.error) console.log(`  ${pc3.cyan("error".padEnd(28))} ${pc3.dim(model.error)}`);
+    if (model.notFound) console.log(`  ${pc3.cyan("404".padEnd(ROUTE_COLUMN))} ${pc3.dim(model.notFound)}`);
+    if (model.error) console.log(`  ${pc3.cyan("error".padEnd(ROUTE_COLUMN))} ${pc3.dim(model.error)}`);
   }
-  if (model.hasServer) {
-    console.log(pc3.bold("\nAPI"));
-    if (model.apis.length === 0) console.log(pc3.dim("  (none)"));
-    for (const a of model.apis) {
-      console.log(`  ${pc3.yellow(a.routePath.padEnd(28))} ${pc3.dim(a.file)}`);
+}
+function printApis(model, detail) {
+  console.log(pc3.bold("\nAPI"));
+  if (!model.hasServer) {
+    console.log(pc3.dim("  (none \u2014 this project has no server/ directory)"));
+    return;
+  }
+  if (model.apis.length === 0) console.log(pc3.dim("  (none)"));
+  for (const a of model.apis) {
+    console.log(`  ${pc3.yellow(a.routePath.padEnd(ROUTE_COLUMN))} ${pc3.dim(a.file)}`);
+    if (!detail) continue;
+    const spec = extractApiSpec(a);
+    if (spec.methods.length === 0) console.log(`      ${pc3.dim("(no HTTP method handler exported)")}`);
+    for (const method of spec.methods) printApiMethodSpec(method, spec.params);
+  }
+}
+function pageJson(p, detail) {
+  return {
+    route: p.routePath,
+    file: p.file,
+    dynamic: p.dynamic,
+    ...detail ? { spec: extractPageSpec(p) } : {}
+  };
+}
+function apiJson(a, detail) {
+  return {
+    route: a.routePath,
+    file: a.file,
+    params: a.params,
+    ...detail ? { spec: extractApiSpec(a) } : {}
+  };
+}
+async function routes(root, args) {
+  const model = scanProject(root);
+  const onlyPages = Boolean(args.flags.pages);
+  const onlyApis = Boolean(args.flags.apis);
+  const showPages = onlyPages || !onlyApis;
+  const showApis = onlyApis || !onlyPages;
+  const detail = Boolean(args.flags.detail);
+  if (args.flags.json) {
+    const payload = {};
+    if (showPages) {
+      payload.pages = model.pages.map((p) => pageJson(p, detail));
+      payload.layouts = model.layouts.map((l) => ({ dir: l.dir === "" ? "/" : l.dir, file: l.file }));
+      payload.notFound = model.notFound;
+      payload.error = model.error;
+    }
+    if (showApis) {
+      payload.apis = model.apis.map((a) => apiJson(a, detail));
+      payload.hasServer = model.hasServer;
     }
+    printJson(payload);
+    return 0;
   }
+  if (showPages) printPages(model, detail);
+  if (showApis && (model.hasServer || onlyApis)) printApis(model, detail);
   console.log("");
   return 0;
 }
@@ -1322,7 +1669,7 @@ ${pc3.bold("Commands")}
   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
+  routes              Show page and API URL map (--pages | --apis | --detail)
   add <kind> <name>   Scaffold a page | api | ui | block | skill | agents
                       (add skill with no name lists the skills and where they sit)
   docs [name]         Show the bundled guide and component reference
@@ -1335,6 +1682,9 @@ ${pc3.bold("Options")}
   --port <n>          Port for dev/preview
   --root <dir>        Project root (default: cwd)
   --force             Overwrite when scaffolding
+  --pages             Show only page routes (routes)
+  --apis              Show only API routes (routes)
+  --detail            Add each route's static spec (routes)
   --list              List pages without showing one (docs)
   --lang <ja|en>      Documentation language (docs, search, default: ja)
   --regex             Treat the query as a regular expression (search)