@squadbase/vantage 0.0.1 → 0.1.1

package/docs/en/build-and-deploy.md

@@ -0,0 +1,280 @@
+# Build & deploy
+
+> What's in dist/ and vantage-manifest.json. Same-origin serving, and splitting the client and server across origins (S3+CloudFront ⇄ Lambda, etc.).
+
+`vantage build` emits the production artifacts into `dist/`. From there, serving splits into two shapes:
+serve the client and server together from the **same origin**, or **split** them — the client on static
+hosting (S3+CloudFront / Cloudflare Pages) and the server on a separate origin (Lambda / a container).
+For the split shape, Vantage provides an **API base URL switch** and **CORS**.
+
+## Build output
+
+```bash
+vantage build   # → dist/
+```
+
+```text
+dist/
+├── client/                Client (index.html + hashed assets, code-split per route)
+├── server/index.mjs       Only when server/ exists (esbuild / node20 / ESM bundle)
+└── vantage-manifest.json  Deploy contract
+```
+
+`vantage-manifest.json` is the one contract the host reads. Its fields:
+
+| Field | Meaning |
+|---|---|
+| `schemaVersion` | Manifest schema version (currently `1`) |
+| `mode` | `"spa"` (client only) / `"fullstack"` (has server). Derived from `server/` |
+| `client` | Relative path to the client output (`"./client"`) |
+| `server` | Relative path to the server bundle (`"./server/index.mjs"`). Fullstack only |
+| `spaFallback` | HTML for the SPA fallback (`"./client/index.html"`) |
+| `runtime` | Server runtime (`"node"`) |
+
+> [!NOTE]
+> `mode` is decided automatically by the presence of a `server/` directory: no `server/` → `spa`
+> (client only); with it → `fullstack`. The same derivation is used by `vantage check` and
+> `vantage routes`.
+
+## Preview locally
+
+Before deploying, run the production build locally to verify it.
+
+```bash
+vantage preview
+```
+
+`vantage preview` reads `mode` from `vantage-manifest.json`: `fullstack` starts the Node server
+(default `:4173`), `spa` serves a static preview.
+
+## Two deployment shapes
+
+### Same origin
+
+One Node process serves both the client and `/api`. Minimal setup, and no CORS needed.
+
+### Split client & server
+
+Client on S3+CloudFront etc., server on Lambda / a container. Needs the API base URL switch
+and CORS.
+
+## Deploy to a single origin
+
+The simplest shape. Place all of `dist/` on a host that runs Node (a container / VM) and start the
+generated server. One process serves both static assets and `/api/*`, so there is nothing to switch
+and no CORS to configure.
+
+```bash
+# on the host where dist/ lives
+PORT=8080 node dist/server/index.mjs
+```
+
+The server listens on `PORT` (or `3000` if unset). The client calls relative `/api/...` paths on the
+same origin.
+
+> [!NOTE]
+> `spa` mode (no `server/`) has no server to start. Upload `dist/client/` to any static host and fall
+> back unknown paths to `index.html` (see the SPA fallback settings below).
+
+## Split the client and server (S3+CloudFront ⇄ Lambda)
+
+Here the client lives on CDN static hosting and the server on a separate origin. A common pairing is
+"`dist/client` on S3+CloudFront, `dist/server/index.mjs` on Lambda / a container". Because the
+origins differ, two things are required.
+
+### 1. Switch the API base URL
+
+Client API calls go through `apiFetch` / `apiUrl` from `@squadbase/vantage/query`. This is the one
+seam that calls `/api`, and it's where the base URL is swapped.
+
+```tsx
+import { apiFetch, useQuery } from "@squadbase/vantage/query";
+
+useQuery({
+  queryKey: ["monthly-analysis"],
+  // Keep the path as it maps in server/api (include /api)
+  queryFn: () => apiFetch("/api/monthly-analysis").then((r) => r.json()),
+});
+```
+
+The base URL is read from `PUBLIC_API_BASE_URL`. **Unset means empty**, so requests stay same-origin
+relative paths (`/api/monthly-analysis`). Set it and the value is prepended
+(`https://api.example.com/api/monthly-analysis`). Two ways to set it:
+
+**(a) Override via env** — put it in `.env` or a CI environment variable. Because of the `PUBLIC_`
+prefix it is inlined into the client bundle.
+
+```bash
+# .env (or a CI env var)
+PUBLIC_API_BASE_URL=https://api.example.com
+```
+
+**(b) Specify at build time** — pass `--api-base-url` to `vantage build`.
+
+```bash
+vantage build --api-base-url https://api.example.com
+```
+
+> [!NOTE]
+> `--api-base-url` **takes precedence** over `PUBLIC_API_BASE_URL` from `.env`. You can keep a base
+> value in `.env` and override per environment with the flag.
+
+> [!TIP]
+> Pass the path to `apiUrl("/api/...")` with the **`/api` prefix included**, matching how it maps under
+> `server/api/**`. The base URL represents the origin (or up to a prefix); the path is concatenated
+> as-is.
+
+### 2. Allow CORS
+
+Once the client and server are on different origins, the browser requires CORS. Setting `CORS_ORIGIN`
+on the server enables CORS on `/api` (including the preflight `OPTIONS` response). **Unset means CORS
+is off**, leaving same-origin serving unchanged.
+
+```bash
+# environment variables on the server (Lambda / container)
+CORS_ORIGIN=https://app.example.com          # a single origin
+# CORS_ORIGIN=https://a.example.com,https://b.example.com   # comma-separated for several
+# CORS_ORIGIN=*                              # allow all (not usable with credentials)
+CORS_CREDENTIALS=true                        # only if you allow cookies / credentials
+```
+
+| Variable | Role |
+|---|---|
+| `CORS_ORIGIN` | Allowed origin(s): `*` / a single value / comma-separated. Unset → CORS off |
+| `CORS_CREDENTIALS` | When `true`, allow credentials (cookies, etc.). Not used with `*` |
+
+The allowed methods are set automatically to the ones Vantage APIs can use
+(`GET,POST,PUT,PATCH,DELETE,OPTIONS`). This behavior is **shared** by the dev server and the
+production Node server, so you can verify CORS during development.
+
+### 3. Put the client on static hosting
+
+Upload `dist/client/` to S3 (+ CloudFront) or Cloudflare Pages. As an SPA, unknown paths must fall
+back to `spaFallback` (`index.html`).
+
+- **S3 + CloudFront**: use a CloudFront "custom error response" to rewrite `403` / `404` to
+  `/index.html` with status `200`.
+- **S3 static website hosting**: set the error document to `index.html`.
+- **Cloudflare Pages**: SPA fallback is on by default.
+
+### 4. Put the server on Lambda / a container
+
+`dist/server/index.mjs` is a Node HTTP server that listens on `PORT` (the manifest's `runtime` is
+`"node"`). It runs anywhere a Node process runs.
+
+- **Container (Cloud Run / ECS·Fargate / Render / Fly, etc.)**: use `node dist/server/index.mjs` as
+  the start command and pass `PORT`.
+- **AWS Lambda**: since it is a listening Node server, a container image + AWS Lambda Web Adapter (or
+  another "run an HTTP server on Lambda" approach) is a good fit.
+- Pass secrets (DB credentials, API keys) as **server environment variables**. They are only readable
+  via `ApiContext.env` and never reach the client.
+
+> [!WARNING]
+> The production Node server snapshots `process.env` **once at startup** (dev re-reads it per request).
+> Restart the server after changing environment variables.
+
+## Deploy to AWS Lambda (a concrete walkthrough)
+
+The generated `dist/server/index.mjs` is a Node HTTP server that **listens** on `PORT`. Lambda, on the
+other hand, invokes a handler per event, so the natural way to run a listening server there is to put
+the [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) (LWA) in front of it.
+LWA proxies Function URL / API Gateway events to the HTTP server running locally. No Vantage code
+changes are needed.
+
+### 1. Run it as a container image (recommended)
+
+esbuild bundles into a **single file** `dist/server/index.mjs`, so you don't need to carry
+`node_modules`.
+
+```dockerfile
+# Dockerfile
+FROM public.ecr.aws/docker/library/node:20-slim
+
+# Bundle the Lambda Web Adapter as an extension (bump the version as needed)
+COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter
+
+WORKDIR /var/task
+# Copy all of dist/ (the server resolves ../client, so keep the layout)
+COPY dist ./dist
+
+# Keep LWA and the Node server on the same port (LWA defaults to 8080)
+ENV PORT=8080
+CMD ["node", "dist/server/index.mjs"]
+```
+
+```bash
+vantage build                                   # produce dist/
+docker build -t vantage-api .
+
+# Log in to ECR and push (<acct> / <region> are yours)
+aws ecr get-login-password --region ap-northeast-1 \
+  | docker login --username AWS --password-stdin <acct>.dkr.ecr.ap-northeast-1.amazonaws.com
+docker tag vantage-api <acct>.dkr.ecr.ap-northeast-1.amazonaws.com/vantage-api:latest
+docker push <acct>.dkr.ecr.ap-northeast-1.amazonaws.com/vantage-api:latest
+```
+
+Create a Lambda function from this image and enable a **Function URL** to get an HTTPS endpoint. Use
+it as the `/api/*` origin in CloudFront, or point the client's `PUBLIC_API_BASE_URL` at it directly.
+
+> [!TIP]
+> **Running from a zip**
+> You can also run from a zip instead of a container. Since the output is bundled, zip
+> `dist/server/index.mjs` (and `dist/client` if you want), attach LWA as a **Lambda layer**, set
+> `AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap` and `PORT=8080`, and use the Node.js 20.x runtime.
+
+### 2. Set the Lambda environment variables
+
+Pass server config and secrets as Lambda environment variables (they never reach the client).
+
+| Variable | Example | Purpose |
+|---|---|---|
+| `CORS_ORIGIN` | `https://d111111abcdef8.cloudfront.net` | Allow the client's origin |
+| `CORS_CREDENTIALS` | `true` | Only if you use cookies / credentials |
+| `SECRET_*`, etc. | `sk_live_xxx` | Secrets read via `ApiContext.env` |
+
+`PORT` is already set in the Dockerfile (matching LWA's default 8080).
+
+> [!NOTE]
+> A Function URL has its own CORS settings, but configuring CORS **both** there and in the app
+> (`CORS_ORIGIN`) **conflicts**. Consolidate on Vantage's `CORS_ORIGIN` and leave the Function URL's
+> CORS empty for a clearer setup.
+
+### 3. Point the client at Lambda
+
+At client build time, set `PUBLIC_API_BASE_URL` to the Lambda (or the CloudFront in front of it)
+origin.
+
+```bash
+vantage build --api-base-url https://d111111abcdef8.cloudfront.net
+```
+
+`apiUrl("/api/monthly-analysis")` then calls that origin with `/api/monthly-analysis` appended.
+
+> [!WARNING]
+> Lambda starts the process on a cold start and reads `process.env` at that moment. After changing
+> environment variables, deploy a new version to apply them (running environments are not updated
+> retroactively).
+
+## Production environment variables at a glance
+
+The boundary is the prefix (see also [Environment variables](environment-variables)).
+
+| Kind | Set where | When it applies | Example |
+|---|---|---|---|
+| Public client value | Build time (`.env` / `--api-base-url`) | Baked into the build | `PUBLIC_API_BASE_URL` |
+| Server config | Server environment variable | Read at startup | `PORT`, `CORS_ORIGIN`, `CORS_CREDENTIALS` |
+| Secret | Server environment variable | Read at startup (`ApiContext.env`) | `SECRET_API_KEY`, etc. |
+
+## Pre-deploy checklist
+
+- [ ] `vantage check` passes with no errors
+- [ ] `vantage build` (with `--api-base-url` for a split setup, or `PUBLIC_API_BASE_URL` in `.env`)
+- [ ] `vantage preview` verifies it locally
+- [ ] For a split setup, set `CORS_ORIGIN` (the client's origin) on the server
+- [ ] Configure SPA fallback (unknown paths → `index.html`) on the static host
+- [ ] Keep secrets in server environment variables only (never expose to the client)
+
+## What to read next
+
+- [CLI reference](cli-reference) — every command, including the `build` flags
+- [Environment variables](environment-variables) — the public / secret boundary

package/docs/en/cli-reference.md

@@ -0,0 +1,311 @@
+# CLI reference
+
+> Every vantage command. dev, build, preview, check, routes, add, docs, search, doctor, upgrade.
+
+`vantage` is the only CLI an app author uses. Run it from the project root unless noted.
+
+## Commands
+
+| Command | Role |
+|---|---|
+| `vantage dev` | Dev server (HMR + optional API). Default `:5173` |
+| `vantage build` | Build client + optional server → `dist/` |
+| `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
+| `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
+| `vantage routes` | Print the page + API URL map |
+| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite) |
+| `vantage docs [name]` | Show the bundled guide and component reference |
+| `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
+| `vantage doctor` | Diagnose environment / installation health |
+| `vantage upgrade` | Regenerate artifacts and sync a placed `AGENTS.md` from the canonical copy |
+
+## Quick mode (pass a path directly)
+
+Instead of `cd`-ing in before running a command, you can pass a **project path directly**. When the
+first argument isn't a known command but points at a filesystem path, Vantage starts `dev` with that
+path as the root (printing `quick dev → <path>`).
+
+```bash
+vantage ./demo             # folder → run dev inside it
+vantage ./demo/index.tsx   # page file → use its parent folder as the root
+```
+
+Path resolution rules:
+
+| Path you pass | Root that's used |
+|---|---|
+| A directory | the directory itself |
+| A `.tsx` / `.jsx` page file | its parent directory |
+| A missing path / anything else | none (`Unknown command` error) |
+
+Every root-scoped command except `add`, `docs` and `search` may also take a trailing path positional. You can spell out
+`dev`, or pass the same path to `build` / `check` / `routes`, etc.
+
+```bash
+vantage dev ./demo             # explicit quick dev
+vantage build ./demo           # build ./demo
+vantage check ./demo/index.tsx # a file argument still checks its parent directory
+```
+
+> [!NOTE]
+> `add`, `docs` and `search` use their positionals for their own arguments (`add page dashboard`,
+> `docs button`, `search date picker`) rather than a path, so they are excluded from this shortcut.
+
+## `vantage docs` — read the docs from the CLI
+
+The content of this site is **bundled into the package**, so `vantage docs` prints it as plain
+Markdown. No network and no browser, which makes it the fastest way for a coding agent to check
+props.
+
+```bash
+vantage docs                    # list every page (guide + components)
+vantage docs button             # show one page (short name → ui/button)
+vantage docs parts/data-table   # full slugs work too
+vantage docs --all              # concatenate every page
+```
+
+| Flag | Meaning |
+|---|---|
+| `--list` | List page names only (no body) |
+| `--all` | Concatenate every page |
+| `--json` | Machine-readable (`{ slug, title, description, section, content }`) |
+| `--lang <ja\|en>` | Language (default `ja`) |
+
+With no argument, `vantage docs` lists **slugs and descriptions** by section — the left column is what
+you pass back in.
+
+```text
+$ vantage docs --lang en
+
+Guide
+  index                       A config-free React dashboard framework. You only write index.tsx.
+  getting-started             From install to running your first Vantage app.
+  routing                     Dropping a file creates a route. Conventions for pages, layouts, dynamic params, and 404/error.
+  …
+
+@squadbase/vantage/ui
+  ui/accordion                A stack of headings that open and close. One at a time by default.
+  ui/alert                    An in-page notice that flags something while the content is still shown.
+  ui/badge                    A small label for counts, states and tags.
+  …
+
+vantage docs <name>   show one page      --json   machine-readable
+vantage docs --all    show every page    --lang   ja | en
+```
+
+Pass a name and the page prints **as Markdown** (headings and quotes are coloured on a TTY, plain when
+piped). Prop tables stay readable as Markdown tables.
+
+````text
+$ vantage docs button --lang en
+
+# Button
+
+> The button, with six variants and eight sizes.
+
+The component you'll reach for most. `variant` carries the meaning, `size` the scale.
+
+```tsx
+import { Button, buttonVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| …` | `"default"` | Look and meaning. |
+| `size` | `"default" \| "xs" \| "sm" \| …` | `"default"` | Height and padding. The `icon` sizes are square. |
+| `render` | `ReactElement` |  | Render as a different element (Radix's `asChild`). |
+…
+````
+
+Names resolve from their **short form**: `vantage docs button` finds `ui/button`, and
+`vantage docs data-table` finds `parts/data-table`. An ambiguous or unknown name prints candidates and
+exits 1.
+
+```text
+$ vantage docs sele
+✗ No page named "sele". Did you mean: ui/select, parts/multi-select, parts/searchable-select?
+```
+
+`--json` is one page, machine-readable; `content` holds the whole Markdown body.
+
+```json
+{
+  "slug": "ui/badge",
+  "lang": "en",
+  "title": "Badge",
+  "description": "A small label for counts, states and tags.",
+  "section": "components/ui",
+  "sectionTitle": "@squadbase/vantage/ui",
+  "content": "# Badge\n\n> A small label for counts, states and tags.\n\nA small label to sit beside…"
+}
+```
+
+Links in the body are slugs, so `[DataTable](parts/data-table)` opens with
+`vantage docs parts/data-table`.
+
+> [!NOTE]
+> What ships is the MDX converted to plain Markdown. Live previews are a site-only feature; the CLI
+> gives you the prop tables, code samples, and callouts.
+
+## `vantage search` — find it without knowing its name
+
+`vantage docs <name>` assumes you **know the name**. When you're coming from what you want to build —
+"I need a UI for picking a date range" — use `vantage search`. It indexes the same bundled docs
+(the guide plus every `ui` / `parts` / `markdown` component), and every result is a name you can hand
+straight to `vantage docs <name>`.
+
+```bash
+vantage search date range filter --lang en   # natural language (quotes are optional)
+vantage search "pagination" --lang en
+vantage search "enable[A-Z]\w+" --regex      # sweep prop names with a regular expression
+vantage search chart --limit 3 --json        # machine-readable
+```
+
+| Flag | Meaning |
+|---|---|
+| `--regex` | Treat the query as a regular expression (case-insensitive) |
+| `--limit <n>` | Results to show (default `10`) |
+| `--json` | Machine-readable output |
+| `--lang <ja\|en>` | Language (default `ja`) |
+
+The default mode is **BM25 full-text search**. Names, titles and descriptions weigh more than body
+prose, and each hit shows the **passage that matched**. Japanese is segmented at script boundaries
+(kanji / katakana / hiragana), so a whole sentence works as a query.
+
+```text
+$ vantage search date range picker --lang en --limit 3
+
+  parts/date-range-picker  DateRangePicker · @squadbase/vantage/components
+                           > A date-range picker with presets.
+  ui/calendar              Calendar · @squadbase/vantage/ui
+                           [`DateRangePicker`](parts/date-range-picker) gets you there faster than using this
+  components               Components · Components
+                           | [`DateRangePicker`](parts/date-range-picker) | Date range with presets |
+```
+
+The left column is the slug to hand to `vantage docs <name>`, the right one is the title and where it
+is imported from, and below each is the matching passage. The real output also prints a
+`11 results for "…"  en · bm25` header and a footer with what `--limit` hid (elided above). **The count
+is how many pages matched at least one term**, so the tail is mostly irrelevant — read the first few
+and raise `--limit` only if they miss.
+
+`--json` is the same result set, machine-readable. `score` is the BM25 score and `command` is ready to
+run (below: `vantage search pagination --lang en --limit 1 --json`).
+
+```json
+{
+  "query": "pagination",
+  "mode": "bm25",
+  "lang": "en",
+  "count": 4,
+  "results": [
+    {
+      "slug": "parts/data-table",
+      "title": "DataTable",
+      "description": "The TanStack Table–backed table: sorting, search, pagination, selection.",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "command": "vantage docs parts/data-table",
+      "score": 5.404,
+      "snippet": "> The TanStack Table–backed table: sorting, search, pagination, selection."
+    }
+  ]
+}
+```
+
+`--regex` scans names, titles, descriptions and bodies, and prints matching lines **with line
+numbers** — the mode to reach for when checking how a prop is spelled across pages.
+
+```text
+$ vantage search "enable(Sorting|Filtering)" --regex --lang en
+
+  parts/data-table  DataTable  4 matches
+      30  | `enableSorting` | `boolean` | Sort by clicking a header. |
+      31  | `enableFiltering` | `boolean` | Put a search box in the toolbar. |
+      50  <DataTable columns={columns} data={data} enableSorting enableFiltering>
+```
+
+Only the first 3 lines of a page are printed, but the `4 matches` count is exact. A page that matched
+on its name, title or description alone is marked `name match` and prints no body lines. Finding
+nothing is not an error (exit code 0, `"count": 0` with `--json`); only an invalid regular expression
+exits 1.
+
+> [!NOTE]
+> The index is built at run time (tens of milliseconds, reading the bundled docs included). Nothing
+> prebuilt ships alongside the docs, so search results can never drift from the documentation.
+>
+> **This page is part of the corpus too.** Run the queries above verbatim and this CLI reference — which
+> contains them as examples — shows up among the hits; the sample output above leaves that row out.
+
+## `--json`
+
+`check` / `routes` / `doctor` / `build` / `upgrade` / `docs` / `search` accept `--json`, useful for CI and agent
+automation.
+
+```bash
+vantage check --json
+```
+
+```json
+{
+  "code": "ROUTE_CONFLICT",
+  "severity": "error",
+  "message": "2 files resolve to /sales",
+  "files": ["sales.tsx", "sales/index.tsx"],
+  "fix": "Rename or remove one route file so each route is unique."
+}
+```
+
+> [!NOTE]
+> `build --json` prints a **compact single line**. Other commands' `--json` is pretty-printed with
+> 2-space indentation.
+
+## `build --api-base-url`
+
+`vantage build` accepts `--api-base-url` to set the base URL the client uses to call `/api`. Use it
+when deploying the client and server on different origins.
+
+```bash
+vantage build --api-base-url https://api.example.com
+```
+
+The flag takes precedence over `PUBLIC_API_BASE_URL` from `.env`. Unset means empty (same-origin
+relative paths). See [Build & deploy](build-and-deploy) for details.
+
+## Static diagnostics (`check`)
+
+`vantage check` detects these six diagnostics (five errors, one warning).
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `FORBIDDEN_FILE` | error | A forbidden config file exists at the root |
+| `ROUTE_CONFLICT` | error | Two files resolve to the same route |
+| `MISSING_DEFAULT_EXPORT` | error | A page has no default export |
+| `INVALID_API_EXPORT` | error | An API exports no valid HTTP method |
+| `CLIENT_IMPORTS_SERVER` | error | Client code imports from `server/` |
+| `PUBLIC_ENV_MISUSE` | warning | Client reads a non-`PUBLIC_` env variable |
+
+None of them import or run your code — the checks are purely static.
+
+## Build output
+
+Inside `dist/`:
+
+```text
+dist/
+├── client/                Client (index.html + hashed assets)
+├── server/index.mjs       Only when server/ exists
+└── vantage-manifest.json  Deploy contract (mode: "spa" | "fullstack")
+```
+
+`vantage preview` reads the `mode` in `vantage-manifest.json` to decide between starting a Node
+server or serving a static preview. Deployment is covered in detail in
+[Build & deploy](build-and-deploy).
+
+## Done
+
+That's the end of the app-author guide. Start from the smallest `index.tsx` and add pages, APIs, and
+UI as you need them.
+
+To hand those procedures to an AI agent, place the bundled [Agents and Skills](agent-skills)
+with `vantage add skill`, and place the app map `AGENTS.md` with `vantage add agents`.