techbro 0.0.0-stage → 0.5.0

package/templates/_default/apps/frontend/src/index.css

@@ -0,0 +1,130 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "./shadcn.css"; /* vendored from the shadcn package so the CLI is not a runtime dependency */
+@import "@fontsource-variable/geist";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --font-heading: var(--font-sans);
+  --font-sans: "Geist Variable", sans-serif;
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}

package/templates/_default/apps/frontend/src/lib/config.js

@@ -0,0 +1,2 @@
+/** Display name; set VITE_APP_NAME in .env to rename the project in the UI. */
+export const appName = import.meta.env.VITE_APP_NAME || "Project Template";

package/templates/_default/apps/frontend/src/lib/utils.js

@@ -0,0 +1,6 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}

package/templates/_default/apps/frontend/src/main.jsx

@@ -0,0 +1,11 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { RouterProvider } from "react-router";
+import "./index.css";
+import { router } from "./routes.jsx";
+
+createRoot(document.getElementById("root")).render(
+  <StrictMode>
+    <RouterProvider router={router} />
+  </StrictMode>,
+);

package/templates/_default/apps/frontend/src/models/items.js

@@ -0,0 +1,24 @@
+export const MAX_ITEM_NAME_LENGTH = 200;
+
+/**
+ * Client-side validation for usability; the backend remains authoritative.
+ * @param {string} name
+ * @returns {{ok: boolean, message: string}}
+ */
+export function validateItemName(name) {
+  const trimmed = (name ?? "").trim();
+  if (!trimmed) return { ok: false, message: "Name is required." };
+  if (trimmed.length > MAX_ITEM_NAME_LENGTH) {
+    return { ok: false, message: `Name must be ${MAX_ITEM_NAME_LENGTH} characters or fewer.` };
+  }
+  return { ok: true, message: "" };
+}
+
+/**
+ * @param {string} iso UTC ISO 8601 timestamp
+ * @returns {string} Localized date/time, or the input if unparseable
+ */
+export function formatCreatedAt(iso) {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? String(iso) : date.toLocaleString();
+}

package/templates/_default/apps/frontend/src/models/items.test.js

@@ -0,0 +1,24 @@
+import { formatCreatedAt, validateItemName } from "./items";
+
+describe("validateItemName", () => {
+  it("rejects empty and whitespace-only names", () => {
+    expect(validateItemName("").ok).toBe(false);
+    expect(validateItemName("   ").ok).toBe(false);
+  });
+  it("accepts a normal name and exactly 200 chars", () => {
+    expect(validateItemName("Widget").ok).toBe(true);
+    expect(validateItemName("a".repeat(200)).ok).toBe(true);
+  });
+  it("rejects names over 200 chars", () => {
+    expect(validateItemName("a".repeat(201)).ok).toBe(false);
+  });
+});
+
+describe("formatCreatedAt", () => {
+  it("returns the input for invalid dates", () => {
+    expect(formatCreatedAt("nope")).toBe("nope");
+  });
+  it("formats valid dates", () => {
+    expect(formatCreatedAt("2026-10-08T12:00:00Z")).not.toBe("2026-10-08T12:00:00Z");
+  });
+});

package/templates/_default/apps/frontend/src/pages/ItemsPage.jsx

@@ -0,0 +1,41 @@
+import { useState } from "react";
+import ItemList from "@/components/ItemList";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { useItems } from "@/hooks/useItems";
+
+export default function ItemsPage() {
+  const { items, loading, error, create } = useItems();
+  const [name, setName] = useState("");
+
+  async function handleSubmit(event) {
+    event.preventDefault();
+    if (await create(name)) setName("");
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Items</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <form onSubmit={handleSubmit} className="flex gap-2">
+          <Input
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            placeholder="New item name"
+            aria-label="Item name"
+          />
+          <Button type="submit">Add</Button>
+        </form>
+        {error && (
+          <p role="alert" className="text-sm text-destructive">
+            {error}
+          </p>
+        )}
+        {loading ? <p className="text-sm">Loading...</p> : <ItemList items={items} />}
+      </CardContent>
+    </Card>
+  );
+}

package/templates/_default/apps/frontend/src/pages/WelcomePage.jsx

@@ -0,0 +1,156 @@
+import { Link } from "react-router";
+import StatusBadge from "@/components/StatusBadge";
+import StepList from "@/components/StepList";
+import { buttonVariants } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { useBackendStatus } from "@/hooks/useBackendStatus";
+import { appName } from "@/lib/config";
+
+const STEPS = [
+  {
+    label: "Create the table",
+    path: "database/migrations/{sqlite,postgres}/20261008120000_create_items.sql",
+    description: "One migration per database engine defines the items table.",
+  },
+  {
+    label: "Model the data",
+    path: "apps/backend/src/models/item.rs",
+    description: "The Item struct and the SQL queries that read and write it.",
+  },
+  {
+    label: "Handle requests",
+    path: "apps/backend/src/controllers/items.rs + apps/backend/src/routes.rs",
+    description: "Controllers validate input and call the model; routes.rs maps URLs to them.",
+  },
+  {
+    label: "Call the API",
+    path: "apps/frontend/src/api/items.js",
+    description: "Small functions that wrap fetch for the items endpoints.",
+  },
+  {
+    label: "Coordinate state",
+    path: "apps/frontend/src/hooks/useItems.js",
+    description: "A hook that loads items, creates them, and tracks loading and errors.",
+  },
+  {
+    label: "Show it",
+    path: "apps/frontend/src/pages/ItemsPage.jsx + src/components/ItemList.jsx",
+    description: "The page uses the hook; ItemList only renders what it is given.",
+  },
+];
+
+const STACK = [
+  "React + Vite",
+  "Tailwind + shadcn/ui",
+  "Rust Axum + SQLx",
+  "SQLite / PostgreSQL",
+  "Vitest",
+  "ESLint / Prettier",
+];
+
+const NEXT_STEPS = [
+  ["README.md", "the engineering convention this project follows"],
+  ["docs/getting-started.md", "setup and first run"],
+  ["scripts/check", "runs the full set of checks before you open a PR"],
+  ["docs/api/README.md", "the REST API reference"],
+];
+
+function StatusRow({ label, result }) {
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center justify-between text-sm">
+        <code>{label}</code>
+        <StatusBadge state={result.state} />
+      </div>
+      {result.state !== "pending" && (
+        <pre className="overflow-x-auto rounded-md bg-muted p-2 text-xs">
+          {result.state === "ok" ? JSON.stringify(result.body, null, 2) : result.message}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+export default function WelcomePage() {
+  const { health, ready, unreachable } = useBackendStatus();
+
+  return (
+    <div className="space-y-6">
+      <header className="space-y-1">
+        <h1 className="text-2xl font-semibold">{appName}</h1>
+        <p className="text-muted-foreground">
+          A full-stack starter with a working example feature to copy from.
+        </p>
+      </header>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Backend status</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <StatusRow label="GET /health" result={health} />
+          <StatusRow label="GET /ready" result={ready} />
+          {unreachable && (
+            <p className="text-sm text-muted-foreground">
+              Start the backend with <code>cargo run -p backend</code> in another terminal.
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Follow the sample feature</CardTitle>
+          <CardDescription>
+            Items are traced from the database to the screen. Read the files in this order.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <StepList steps={STEPS} />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Stack</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <ul className="grid grid-cols-2 gap-2 text-sm sm:grid-cols-3">
+            {STACK.map((name) => (
+              <li key={name} className="rounded-md border px-3 py-2">
+                {name}
+              </li>
+            ))}
+          </ul>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Try it</CardTitle>
+          <CardDescription>Add an item and see it saved through the API.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Link to="/items" className={buttonVariants()}>
+            Open the Items page
+          </Link>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Next steps</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <ul className="space-y-2 text-sm">
+            {NEXT_STEPS.map(([file, text]) => (
+              <li key={file}>
+                <code>{file}</code> <span className="text-muted-foreground">: {text}</span>
+              </li>
+            ))}
+          </ul>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/templates/_default/apps/frontend/src/pages/WelcomePage.test.jsx

@@ -0,0 +1,55 @@
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router";
+import WelcomePage from "./WelcomePage";
+
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), { status });
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("WelcomePage", () => {
+  it("renders the sample feature steps", () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => new Promise(() => {})),
+    );
+    render(
+      <MemoryRouter>
+        <WelcomePage />
+      </MemoryRouter>,
+    );
+    expect(screen.getByText("Follow the sample feature")).toBeInTheDocument();
+    expect(screen.getByText("apps/backend/src/models/item.rs")).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem").length).toBeGreaterThanOrEqual(6);
+  });
+
+  it("shows ok status with the raw JSON", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((url) => Promise.resolve(json(url === "/health" ? { status: "ok" } : { db: "up" }))),
+    );
+    render(
+      <MemoryRouter>
+        <WelcomePage />
+      </MemoryRouter>,
+    );
+    expect(await screen.findAllByText("OK")).toHaveLength(2);
+    expect(screen.getByText(/"status": "ok"/)).toBeInTheDocument();
+    expect(screen.queryByText(/cargo run -p backend/)).not.toBeInTheDocument();
+  });
+
+  it("shows a hint when the backend is unreachable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => Promise.reject(new TypeError("Failed to fetch"))),
+    );
+    render(
+      <MemoryRouter>
+        <WelcomePage />
+      </MemoryRouter>,
+    );
+    expect(await screen.findAllByText("Failed")).toHaveLength(2);
+    expect(screen.getByText("cargo run -p backend")).toBeInTheDocument();
+  });
+});

package/templates/_default/apps/frontend/src/routes.jsx

@@ -0,0 +1,17 @@
+import { createBrowserRouter } from "react-router";
+import App from "@/App";
+import ItemsPage from "@/pages/ItemsPage";
+import WelcomePage from "@/pages/WelcomePage";
+
+export const routes = [
+  {
+    path: "/",
+    element: <App />,
+    children: [
+      { index: true, element: <WelcomePage /> },
+      { path: "items", element: <ItemsPage /> },
+    ],
+  },
+];
+
+export const router = createBrowserRouter(routes);