@autoview/cli 0.1.0

package/template/CLAUDE.md

@@ -0,0 +1,140 @@
+# Frontend Generation Guide
+
+> Sourced from
+> [`samchon/shopping/packages/frontend/CLAUDE.md`](https://github.com/samchon/shopping/blob/master/packages/frontend/CLAUDE.md).
+>
+> AutoBE bundles this guide into every generated project so that a coding
+> agent (e.g. Codex CLI, Claude Code, Cursor) can produce a Next.js + shadcn/ui
+> frontend on top of the AutoBE-generated SDK without further instruction.
+
+## Goal
+This project should produce a frontend that understands the SDK well.
+
+Do not let raw SDK shapes take over the UI.
+
+- Keep SDK-specific code in an adapter layer.
+- Let the UI depend on normalized domain models and hooks.
+
+## Stack
+Use a fixed base unless the user explicitly wants something else.
+
+- Use `TypeScript + Next.js + shadcn/ui` unless the user approves another stack.
+- Use environment variables for the API host.
+- Default API host: `http://127.0.0.1:37001`.
+- Add libraries only when they solve a real problem.
+
+## Start
+Before designing screens, make the SDK surface clear.
+
+- Scaffold the app.
+- Install the SDK.
+- Read `../api/src/**/*.ts` files carefully — the SDK was generated by AutoBE
+  and lives under `src/api/` in this same archive.
+- Read the comments too.
+- Treat code, types, and comments as the source of truth.
+- Map the main APIs, DTOs, and constraints before designing the UI.
+
+## Account Guidance
+If the AutoBE backend exposes seed/operator accounts, document them in
+`wiki/` and reuse them anywhere the login flow is introduced. When the
+backend has no fixed accounts, expose membership signup as the first-class
+entry point.
+
+## Design
+The code structure should keep replacement cost low if the SDK changes later.
+
+- Keep SDK code in a dedicated adapter layer (`src/lib/api/`).
+- Do not spread SDK types across screens and components.
+- Explain any non-default choice for routing, state, fetching, styling, forms,
+  testing, or browser automation.
+
+## Product
+Read the SDK broadly.
+
+Do not turn every endpoint into a feature. Prefer a clear product over full
+endpoint coverage.
+
+- Do not force every API into the UI.
+- Leave out APIs that are redundant, diagnostic, cluttering, or harmful to the
+  main flow.
+- Note intentional omissions in `wiki/`.
+- Do not invent features the SDK does not support.
+- Handle loading, empty, error, retry, and invalidation states.
+- Finish the main user flows before adding secondary controls.
+
+## Visual Style
+The default direction is a simple prototype-first UI.
+
+It is only a default. If the user gives a different direction, or if the
+existing product style is already clear, follow that instead.
+
+- The UI must work well on mobile, tablet, and desktop.
+- Start from real UI parts such as lists, tables, forms, detail views,
+  dialogs, and pagination.
+- Keep the layout readable and content-first.
+- Avoid decorative choices that hurt clarity or usability.
+
+## Workflow
+Docs and helper commands should follow the code instead of drifting away from
+it.
+
+- Keep `wiki/` aligned with the code.
+- Update docs when architecture, package choices, user flows, or omissions
+  change.
+- If a useful project command does not exist yet, create it before relying on
+  it.
+
+## Testing
+Testing should prove that the rendered product still works.
+
+For frontend-only work, keep the test program focused on the frontend itself.
+Do not boot the backend, judge backend health, or let CI drift into server
+checks.
+
+The SDK already supports simulation through the connection object. When
+`simulate: true` is set, the SDK returns simulated responses instead of
+calling the real backend. For frontend tests, treat this as API mocking at
+the SDK boundary.
+
+```ts
+const connection: IConnection = {
+  host: "http://127.0.0.1:...",
+  simulate: true,
+};
+```
+
+- If the repo does not have a suitable test stack yet, add one.
+- Keep a browser-first test program for the main user flows.
+- Prefer Playwright for end-to-end and UI review work unless the user wants
+  something else.
+- Do not add backend health, startup, or server-state checks to the frontend
+  test program or its GitHub Actions workflow.
+- If integration testing is needed, keep it as a separate test program.
+- Keep local test commands and GitHub Actions aligned when the test setup
+  changes.
+
+## UI Review
+UI work is not done when the code compiles.
+
+It is done after the flow has been used and checked.
+
+- Run the flow yourself.
+- Prefer direct browser interaction.
+- Install browser automation before falling back.
+- Check the UI at mobile, tablet, and desktop sizes.
+- Verify that controls cause observable changes.
+- Verify that search, sort, pagination, page size, toggles, dialogs, and forms
+  actually work when present.
+- Do one final pass for layout and copy before calling the work done.
+- Fall back to screenshots or raw API checks only when browser automation is
+  not available.
+
+## Done
+Done means the product works, not just that files were written.
+
+- The app starts.
+- Core flows work.
+- The UI is coherent.
+- The docs match the code.
+- The tests match the code.
+- If an SDK feature makes the product worse, simplify it or leave it out.

package/template/Dockerfile

@@ -0,0 +1,31 @@
+# Next.js standalone build optimized for the in-house Sandbox platform.
+# - Multi-stage so the runtime layer carries only `.next/standalone/` and
+#   `public/`, not the full `node_modules/`.
+# - Listens on the port supplied by `PORT` (defaults to 3000) so the sandbox
+#   ingress can route to it.
+# - The build expects `output: "standalone"` in `next.config.mjs`. The
+#   `PROMPT.md` instructs the coding agent to set that flag.
+
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci --no-audit --no-fund
+
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME=0.0.0.0
+COPY --from=build /app/public ./public
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:${PORT}/api/health || exit 1
+CMD ["node", "server.js"]

package/template/PROMPT.md

@@ -0,0 +1,80 @@
+# Frontend Generation — Master Prompt
+
+> Paste this entire file into Codex CLI (or any coding agent) as the opening
+> message. The agent will read the SDK, follow `frontend/CLAUDE.md`, and
+> produce a runnable Next.js + shadcn/ui application.
+
+You are building a frontend application on top of a TypeScript SDK that
+AutoBE has just generated. Your job is to produce a product, not a catalog.
+
+## Inputs in this archive
+
+- `frontend/CLAUDE.md` — your operating manual. Follow it strictly.
+- `frontend/SANDBOX.md` — deployment constraints for the in-house Sandbox
+  platform. **Mandatory** if the operator plans to deploy this app.
+- `frontend/Dockerfile` — keep this file. The Sandbox build pipeline expects
+  it as-is (Next.js standalone, node 20-alpine, healthcheck on `/api/health`).
+- `src/api/**` — the SDK that AutoBE generated. Read every file, including
+  the JSDoc comments, before you write a single UI component.
+- `docs/openapi.json` — the OpenAPI document the SDK was generated from. Use
+  it only as a cross-reference; the SDK is the source of truth.
+
+## Task
+
+1. **Study** the SDK. Build a mental map of the resources, actors (e.g.
+   customer, seller, administrator, guest), and end-to-end user journeys
+   the SDK supports. Write your findings into `frontend/wiki/sdk-map.md`.
+2. **Plan the product**, not the endpoint catalog. Decide which screens
+   exist (e.g. Catalog, Cart, Order detail, Admin sales) and what each
+   screen does. Each screen typically composes several SDK calls into one
+   coherent flow. Record the plan in `frontend/wiki/product-plan.md`,
+   including intentional omissions.
+3. **Scaffold** a Next.js 15 + shadcn/ui project inside `frontend/`. Wire
+   the SDK through an adapter layer (`frontend/src/lib/api/`). Use
+   `simulate: true` on the SDK connection by default so the app stays
+   browsable without a live backend. **Set `output: "standalone"`** in
+   `next.config.mjs` — the Sandbox Dockerfile depends on this. **Add the
+   healthcheck route** `app/api/health/route.ts` that returns
+   `Response.json({ status: "ok" })` for `GET`.
+4. **Implement** the planned screens. Use shadcn/ui primitives (Button,
+   Card, Table, Dialog, Sheet, Tabs, Form, Select, Pagination, ...) and
+   Tailwind utilities. Components must work on mobile, tablet, and desktop.
+   Handle loading, empty, error, retry, and invalidation states.
+5. **Verify**. Run the dev server, click through every main flow yourself,
+   and capture screenshots into `frontend/wiki/screenshots/`. If a flow is
+   awkward because the SDK is awkward, note it in
+   `frontend/wiki/sdk-feedback.md` — this feedback is the whole reason the
+   frontend exists.
+
+## Quality bar
+
+- The app boots cleanly with `npm run dev`.
+- The home page is a real landing surface, not a list of API endpoints.
+- Every navigation entry leads to a screen that does something useful.
+- Forms validate on the client and surface server errors gracefully.
+- Lists support pagination, sort, and any filters the SDK exposes.
+- `npm run lint` and `npm run typecheck` both pass.
+- `docker build .` succeeds, and `docker run -p 3000:3000 <image>` exposes
+  `GET /api/health` returning `200 { status: "ok" }`. The Sandbox build
+  pipeline runs the same `docker build` so this is the deploy gate.
+- `README.md` declares the Sandbox spec (Port, Healthcheck, Dockerfile,
+  Env vars) exactly as `frontend/SANDBOX.md` requires.
+
+## Deployment target
+
+This app deploys to the in-house Sandbox platform via Slack
+`/sandbox-server-infra-setup`. **Do not** generate `vercel.json`,
+`netlify.toml`, or any other public-PaaS config — the operator runs the
+Slack command on a private GitHub repo and Sandbox handles the rest.
+`frontend/SANDBOX.md` lists the exact artifacts the platform expects.
+
+## What "done" looks like
+
+A non-technical user can open the dev server URL, log in (or use the
+`simulate: true` default), browse the main resources, perform the primary
+CRUD or transactional flows, and form a real opinion about whether the API
+underneath is well-designed. If they cannot — if the UI exposes the API's
+awkwardness — that is valuable signal, not a failure. Write it down in
+`frontend/wiki/sdk-feedback.md`.
+
+Start by reading `frontend/CLAUDE.md` in full, then read `src/api/`.

package/template/SANDBOX.md

@@ -0,0 +1,70 @@
+# Sandbox Deployment Guide
+
+This frontend is generated to deploy on the in-house **Sandbox platform**.
+Vercel and other public PaaS are **out of scope** — do not introduce them.
+
+## Required artifacts in the repo
+
+The coding agent must produce all of the following at the **repo root** of
+the frontend project. The sandbox `/sandbox-server-infra-setup` command
+reads these to provision the service.
+
+| Path                | Contents                                                                 |
+| ------------------- | ------------------------------------------------------------------------ |
+| `Dockerfile`        | Multi-stage Next.js standalone build. The template ships one — keep it. |
+| `next.config.mjs`   | Must include `output: "standalone"`.                                     |
+| `app/api/health/route.ts` | `GET` returning `200 { status: "ok" }` — wired into the Docker `HEALTHCHECK`. |
+| `README.md`         | Lists port, healthcheck path, Dockerfile spec, and env vars (below).     |
+
+## README spec — required sections
+
+The sandbox setup reads these from the README:
+
+```markdown
+## Sandbox
+
+- Port: 3000
+- Healthcheck: `GET /api/health`
+- Dockerfile: ./Dockerfile (Next.js standalone, node 20-alpine)
+- Env vars (Secret Manager):
+  - `NEXT_PUBLIC_API_HOST`        — AutoBE backend base URL inside sandbox
+  - `MONGO_URL`                   — autowired by sandbox; do not set manually
+  - (anything else this project introduces)
+```
+
+## Repo layout — required
+
+- **Private repo**, not internal.
+- `dev` environment ↔ `develop` branch.
+- `prod` environment ↔ `main` branch (requires Platform + Security review).
+- If the frontend lives in a sub-folder of a monorepo, the agent must
+  document that path so the sandbox setup picks the right `Dockerfile`.
+
+## Deploy procedure (operator)
+
+1. Push the repo (private). Verify `develop` branch exists.
+2. In Slack `#platform-team`, run `/sandbox-server-infra-setup`.
+3. Select the repo, environment (`dev` first), and enter the reason for
+   the request.
+4. Secret Manager is auto-wired; set values according to the env var list
+   in the README before promoting to `prod`.
+5. For `prod` rollout, request Platform + Security review.
+
+## What the coding agent should NOT do
+
+- Do not generate `vercel.json`, `netlify.toml`, or any other public PaaS
+  config.
+- Do not embed secrets in source. Reference them through `process.env.*`
+  and document them in the README's Sandbox section.
+- Do not change the Dockerfile's `PORT` / `HOSTNAME` / `EXPOSE 3000`
+  without also updating the README.
+- Do not remove the `/api/health` route — the Dockerfile `HEALTHCHECK`
+  depends on it.
+
+## Why this exists
+
+The internal Sandbox platform replaces hand-rolled Kubernetes wiring
+(yml + Dockerfile + chart + secrets) with a single Slack command that
+provisions everything in 5–10 minutes from a standardized template. The
+template assumes the four artifacts above. Missing any one of them turns
+a 5-minute deploy back into a half-day infra ticket.

package/template/app/api/health/route.ts

@@ -0,0 +1,10 @@
+// Sandbox HEALTHCHECK endpoint. The Dockerfile invokes
+// `GET /api/health` every 30s — return `{ status: "ok" }` so the container
+// is marked healthy in the sandbox dashboard. Do not remove or rename.
+
+export const dynamic = "force-static";
+export const revalidate = false;
+
+export function GET(): Response {
+  return Response.json({ status: "ok" });
+}

package/template/app/globals.css

@@ -0,0 +1,97 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+ * SpaceX theme — pure black, white, near-zero radius, industrial.
+ * Dark IS the default (SpaceX has no light mode), so the values live in
+ * `:root`; `.dark` mirrors them. Monochrome on purpose: color is reserved
+ * for status (success/warning/destructive) so state reads instantly against
+ * the black. Every Resource* component reads these tokens — re-skinning the
+ * whole generated app is a single edit here.
+ */
+@layer base {
+  :root {
+    --background: 0 0% 0%;
+    --foreground: 0 0% 100%;
+
+    --card: 0 0% 5%;
+    --card-foreground: 0 0% 100%;
+    --popover: 0 0% 5%;
+    --popover-foreground: 0 0% 100%;
+
+    /* Brand: white-on-black CTA, SpaceX "ORDER NOW" style. */
+    --primary: 0 0% 100%;
+    --primary-foreground: 0 0% 0%;
+
+    --secondary: 0 0% 12%;
+    --secondary-foreground: 0 0% 100%;
+    --muted: 0 0% 11%;
+    --muted-foreground: 0 0% 60%;
+
+    /* Accent = subtle lift on hover / active nav, still monochrome. */
+    --accent: 0 0% 14%;
+    --accent-foreground: 0 0% 100%;
+
+    /* Semantic status colors — the only color in the system. */
+    --success: 145 63% 45%;
+    --success-foreground: 0 0% 0%;
+    --warning: 38 92% 55%;
+    --warning-foreground: 0 0% 0%;
+    --destructive: 0 72% 52%;
+    --destructive-foreground: 0 0% 100%;
+
+    --border: 0 0% 16%;
+    --input: 0 0% 18%;
+    --ring: 0 0% 80%;
+
+    --radius: 0.125rem;
+  }
+
+  .dark {
+    --background: 0 0% 0%;
+    --foreground: 0 0% 100%;
+
+    --card: 0 0% 5%;
+    --card-foreground: 0 0% 100%;
+    --popover: 0 0% 5%;
+    --popover-foreground: 0 0% 100%;
+
+    --primary: 0 0% 100%;
+    --primary-foreground: 0 0% 0%;
+
+    --secondary: 0 0% 12%;
+    --secondary-foreground: 0 0% 100%;
+    --muted: 0 0% 11%;
+    --muted-foreground: 0 0% 60%;
+
+    --accent: 0 0% 14%;
+    --accent-foreground: 0 0% 100%;
+
+    --success: 145 63% 45%;
+    --success-foreground: 0 0% 0%;
+    --warning: 38 92% 55%;
+    --warning-foreground: 0 0% 0%;
+    --destructive: 0 72% 52%;
+    --destructive-foreground: 0 0% 100%;
+
+    --border: 0 0% 16%;
+    --input: 0 0% 18%;
+    --ring: 0 0% 80%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: "tnum" 1, "calt" 1;
+    -webkit-font-smoothing: antialiased;
+  }
+  /* Headings carry the industrial, wide-tracked SpaceX voice. */
+  h1, h2 {
+    @apply uppercase tracking-wide;
+  }
+}

package/template/app/layout.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { Archivo } from "next/font/google";
+import "./globals.css";
+
+// Archivo — a grotesque with the industrial, slightly condensed character of
+// SpaceX's D-DIN. Carries the whole UI; headings go uppercase + tracked in CSS.
+const archivo = Archivo({
+  subsets: ["latin"],
+  variable: "--font-sans",
+  display: "swap",
+});
+
+export const metadata: Metadata = {
+  title: "AutoBE Frontend",
+  description: "Generated by the AutoView agent on top of an AutoBE SDK.",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className={`dark ${archivo.variable}`} suppressHydrationWarning>
+      <body className="min-h-screen bg-background font-sans antialiased">
+        {children}
+      </body>
+    </html>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,19 @@
+// Placeholder landing page. The AutoView agent (or a coding agent following
+// `frontend/PROMPT.md`) replaces this file with the real entry point based
+// on the SDK's actor flow — e.g. a storefront for shopping APIs, a
+// dashboard for admin APIs, etc.
+
+export default function HomePage() {
+  return (
+    <main className="container mx-auto py-16">
+      <h1 className="text-3xl font-bold tracking-tight">AutoBE Frontend</h1>
+      <p className="mt-3 text-muted-foreground">
+        This app has not been customized yet. Follow{" "}
+        <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-sm">
+          frontend/PROMPT.md
+        </code>{" "}
+        to scaffold the product on top of the generated SDK.
+      </p>
+    </main>
+  );
+}

package/template/components/AppShell.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { Home } from "lucide-react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import * as React from "react";
+
+import { ResourceIcon } from "@/components/auto/ResourceIcon";
+import { cn } from "@/lib/utils";
+import { APP_NAME, NAV, type NavItem } from "@/src/lib/nav";
+
+/**
+ * Application chrome shared by every generated page: a persistent left sidebar
+ * with the resource navigation (grouped) and a slim top header. Turns the
+ * generated pages from bare centered columns into a real admin product. Static
+ * and swagger-agnostic — the nav itself is generated into `@/src/lib/nav`.
+ */
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+  const groups = groupNav(NAV);
+
+  const isActive = (href: string) =>
+    pathname === href || pathname.startsWith(`${href}/`);
+
+  return (
+    <div className="min-h-screen bg-muted/20">
+      <div className="flex">
+        <aside className="sticky top-0 hidden h-screen w-60 shrink-0 flex-col border-r bg-background md:flex">
+          <Link
+            href="/"
+            className="flex h-14 items-center gap-2.5 border-b px-5"
+          >
+            <span className="flex h-6 w-6 items-center justify-center rounded bg-primary text-xs font-bold text-primary-foreground">
+              {APP_NAME.charAt(0).toUpperCase()}
+            </span>
+            <span className="truncate text-sm font-semibold tracking-tight">
+              {APP_NAME}
+            </span>
+          </Link>
+          <nav className="flex-1 space-y-5 overflow-y-auto p-3">
+            <Link href="/" className={navLinkClass(pathname === "/")}>
+              <Home className="h-4 w-4 shrink-0 opacity-70" />
+              <span className="truncate">Home</span>
+            </Link>
+            {groups.map(([group, items]) => (
+              <div key={group}>
+                <p className="mb-1 px-3 text-[11px] font-medium uppercase tracking-wider text-muted-foreground">
+                  {group}
+                </p>
+                <div className="space-y-0.5">
+                  {items.map((item) => (
+                    <Link
+                      key={item.href}
+                      href={item.href}
+                      className={navLinkClass(isActive(item.href))}
+                    >
+                      <ResourceIcon
+                        name={item.href}
+                        className="h-4 w-4 shrink-0 opacity-70"
+                      />
+                      <span className="truncate">{item.title}</span>
+                    </Link>
+                  ))}
+                </div>
+              </div>
+            ))}
+          </nav>
+          <div className="border-t px-4 py-3 text-[11px] text-muted-foreground">
+            Generated by AutoView
+          </div>
+        </aside>
+
+        <div className="flex min-w-0 flex-1 flex-col">
+          <header className="sticky top-0 z-10 flex h-14 items-center gap-3 border-b bg-background/80 px-5 backdrop-blur md:px-8">
+            <Link href="/" className="text-sm font-semibold md:hidden">
+              {APP_NAME}
+            </Link>
+            <nav className="flex gap-1 overflow-x-auto md:hidden">
+              {NAV.slice(0, 6).map((item) => (
+                <Link
+                  key={item.href}
+                  href={item.href}
+                  className="whitespace-nowrap rounded px-2 py-1 text-xs text-muted-foreground hover:bg-muted"
+                >
+                  {item.title}
+                </Link>
+              ))}
+            </nav>
+          </header>
+          <main className="min-w-0 flex-1">{children}</main>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function navLinkClass(active: boolean): string {
+  return cn(
+    "flex items-center gap-2.5 rounded-md px-3 py-1.5 text-sm font-medium transition-colors",
+    active
+      ? "bg-muted text-foreground"
+      : "text-muted-foreground hover:bg-muted/60 hover:text-foreground",
+  );
+}
+
+function groupNav(items: NavItem[]): Array<[string, NavItem[]]> {
+  const map = new Map<string, NavItem[]>();
+  for (const item of items) {
+    const bucket = map.get(item.group) ?? [];
+    bucket.push(item);
+    map.set(item.group, bucket);
+  }
+  return [...map.entries()];
+}