@squadbase/vantage 0.2.1 → 0.2.3

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, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, API_METHODS, PUBLIC_ENV_PREFIX, extractPageMeta } from './chunk-3QKPNWKJ.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 = {};
@@ -147,30 +161,75 @@ function resolvePackageDir(root, sub) {
 function resolveRegistryDir(root) {
   return resolvePackageDir(root, "registry");
 }
+var SKILL_FILE = "SKILL.md";
+var SKILL_SCAN_SKIP = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".vantage",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".vercel"
+]);
+var SKILL_SCAN_DEPTH = 4;
 function listBundledSkills(skillsDir) {
   try {
-    return fs2.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && fs2.existsSync(path2.join(skillsDir, e.name, "SKILL.md"))).map((e) => e.name).sort();
+    return fs2.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && fs2.existsSync(path2.join(skillsDir, e.name, SKILL_FILE))).map((e) => e.name).sort();
   } catch {
     return [];
   }
 }
-function copySkill(root, skillsDir, name, force, destDir) {
-  const src = path2.join(skillsDir, name);
-  if (!fs2.existsSync(path2.join(src, "SKILL.md"))) {
-    const available = listBundledSkills(skillsDir);
-    log.error(`Unknown skill "${name}". Available: ${available.join(", ") || "(none)"}`);
-    return 1;
-  }
-  const dest = path2.join(destDir, name);
-  const rel2 = path2.relative(root, dest);
-  const label = !rel2 ? name : rel2.startsWith("..") ? dest : rel2;
-  if (fs2.existsSync(dest) && !force) {
-    log.error(`${label} already exists. Use --force to overwrite.`);
-    return 1;
-  }
+function displayPath(root, target) {
+  const rel2 = path2.relative(root, target);
+  return !rel2 ? "." : rel2.startsWith("..") ? target : rel2;
+}
+function findPlacedSkills(root, names, skillsDir) {
+  const wanted = new Set(names);
+  const found = /* @__PURE__ */ new Map();
+  const isSource = (p) => !path2.relative(skillsDir, p).startsWith("..");
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKILL_SCAN_SKIP.has(entry.name)) continue;
+      const abs = path2.join(dir, entry.name);
+      if (wanted.has(entry.name) && fs2.existsSync(path2.join(abs, SKILL_FILE))) {
+        if (!isSource(abs)) found.set(entry.name, [...found.get(entry.name) ?? [], abs]);
+        continue;
+      }
+      if (depth < SKILL_SCAN_DEPTH) walk(abs, depth + 1);
+    }
+  };
+  walk(root, 1);
+  for (const list of found.values()) list.sort();
+  return found;
+}
+function writeSkill(root, skillsDir, name, dest, verb) {
   fs2.mkdirSync(path2.dirname(dest), { recursive: true });
-  fs2.cpSync(src, dest, { recursive: true, force: true });
-  log.ok(`Added skill ${label}/`);
+  fs2.cpSync(path2.join(skillsDir, name), dest, { recursive: true, force: true });
+  log.ok(`${verb} skill ${displayPath(root, dest)}/`);
+}
+function printSkillList(root, available, placed) {
+  const width = Math.max(...available.map((n) => n.length));
+  log.info("Bundled skills:");
+  for (const name of available) {
+    const where = placed.get(name);
+    const status = where?.length ? where.map((p) => displayPath(root, p) + "/").join(", ") : "not placed";
+    log.info(`  ${name.padEnd(width)}  ${status}`);
+  }
+  const missing = available.filter((n) => !placed.get(n)?.length);
+  if (missing.length) {
+    log.info("");
+    log.info("Place the missing ones with: vantage add skill --all [--dir <path>]");
+  }
   return 0;
 }
 function addSkill(root, name, all, force, dir) {
@@ -184,15 +243,34 @@ function addSkill(root, name, all, force, dir) {
     log.error("No skills are bundled with this version of Vantage.");
     return 1;
   }
-  const targets = all ? available : name ? [name] : [];
-  if (targets.length === 0) {
-    log.error(`Usage: vantage add skill <name>|--all. Available: ${available.join(", ")}`);
-    return 1;
-  }
+  const placed = findPlacedSkills(root, available, skillsDir);
+  if (!all && !name) return printSkillList(root, available, placed);
   const destDir = path2.resolve(root, dir ?? ".");
+  const targets = all ? available : [name];
   let failed = 0;
   for (const target of targets) {
-    if (copySkill(root, skillsDir, target, force, destDir) !== 0) failed++;
+    if (!available.includes(target)) {
+      log.error(`Unknown skill "${target}". Available: ${available.join(", ")}`);
+      failed++;
+      continue;
+    }
+    const existing = placed.get(target) ?? [];
+    if (existing.length > 0 && !force) {
+      const where = existing.map((p) => displayPath(root, p) + "/").join(", ");
+      log.info(`Skill ${target} is already placed at ${where} \u2014 skipped (--force to refresh).`);
+      continue;
+    }
+    const inDestDir = existing.filter((p) => path2.dirname(p) === destDir);
+    const refresh = dir === void 0 ? existing : inDestDir;
+    if (refresh.length > 0) {
+      for (const dest of refresh) writeSkill(root, skillsDir, target, dest, "Updated");
+      continue;
+    }
+    if (existing.length > 0) {
+      const where = existing.map((p) => displayPath(root, p) + "/").join(", ");
+      log.warn(`Skill ${target} is also placed at ${where} \u2014 left untouched.`);
+    }
+    writeSkill(root, skillsDir, target, path2.join(destDir, target), "Added");
   }
   return failed === 0 ? 0 : 1;
 }
@@ -294,10 +372,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);
 }
@@ -408,9 +678,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)
@@ -877,39 +1145,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;
 }
@@ -1258,8 +1597,9 @@ ${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
   search <query>      Find components and docs by meaning, or by regex
   doctor              Environment and installation health checks
@@ -1270,12 +1610,15 @@ ${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)
   --limit <n>         Max results (search, default: 10)
   --all               Add every bundled skill (add skill --all) | show every page (docs)
-  --dir <path>        Destination for skills (add skill, default: project root)
+  --dir <path>        Where to place skills when none is found (add skill, default: project root)
   -v, --version       Print version
   -h, --help          Print this help
 `;