@fluid-app/fluid-cli-portal 0.1.0

package/templates/fullstack/src/server/routes/index.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import app from "../index";
+
+describe("API Routes", () => {
+  // Health check
+  it("GET /api/health returns 200", async () => {
+    const res = await app.request("/api/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ status: "ok" });
+  });
+
+  // List todos (empty)
+  it("GET /api/todos returns empty array", async () => {
+    const res = await app.request("/api/todos");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual([]);
+  });
+
+  // Create todo
+  it("POST /api/todos creates a todo", async () => {
+    const res = await app.request("/api/todos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Test todo" }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.title).toBe("Test todo");
+    expect(body.completed).toBe(false);
+    expect(body.id).toBeDefined();
+  });
+
+  // Create invalid (empty body)
+  it("POST /api/todos with empty body returns 400", async () => {
+    const res = await app.request("/api/todos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBe("Validation failed");
+    expect(body.details).toBeDefined();
+  });
+
+  // Create invalid (empty title)
+  it("POST /api/todos with empty title returns 400", async () => {
+    const res = await app.request("/api/todos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "" }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBe("Validation failed");
+  });
+
+  // Toggle todo
+  it("PATCH /api/todos/:id toggles completion", async () => {
+    // Create first
+    const createRes = await app.request("/api/todos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Toggle me" }),
+    });
+    const created = await createRes.json();
+
+    // Toggle
+    const res = await app.request(`/api/todos/${created.id}`, {
+      method: "PATCH",
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.completed).toBe(true);
+  });
+
+  // Toggle non-existent
+  it("PATCH /api/todos/999 returns 404", async () => {
+    const res = await app.request("/api/todos/999", { method: "PATCH" });
+    expect(res.status).toBe(404);
+  });
+
+  // Toggle bad ID
+  it("PATCH /api/todos/abc returns 400", async () => {
+    const res = await app.request("/api/todos/abc", { method: "PATCH" });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBe("Invalid ID");
+  });
+
+  // Delete todo
+  it("DELETE /api/todos/:id deletes a todo", async () => {
+    const createRes = await app.request("/api/todos", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: "Delete me" }),
+    });
+    const created = await createRes.json();
+
+    const res = await app.request(`/api/todos/${created.id}`, {
+      method: "DELETE",
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.success).toBe(true);
+  });
+
+  // Delete non-existent
+  it("DELETE /api/todos/999 returns 404", async () => {
+    const res = await app.request("/api/todos/999", { method: "DELETE" });
+    expect(res.status).toBe(404);
+  });
+
+  // Delete bad ID
+  it("DELETE /api/todos/abc returns 400", async () => {
+    const res = await app.request("/api/todos/abc", { method: "DELETE" });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBe("Invalid ID");
+  });
+});

package/templates/fullstack/src/server/routes/index.ts

@@ -0,0 +1,109 @@
+import { Hono } from "hono";
+import { eq, sql } from "drizzle-orm";
+import { db } from "../db/index";
+import { todos } from "../db/schema";
+import { createTodoSchema, todoIdSchema } from "./schemas";
+
+export const apiRoutes = new Hono();
+
+// GET /api/todos — List all todos
+apiRoutes.get("/todos", async (c) => {
+  try {
+    const allTodos = await db.select().from(todos).all();
+    return c.json(allTodos);
+  } catch (error) {
+    console.error(error);
+    return c.json({ error: "Internal server error" }, 500);
+  }
+});
+
+// POST /api/todos — Create a new todo
+apiRoutes.post("/todos", async (c) => {
+  try {
+    const body = await c.req.json();
+    const result = createTodoSchema.safeParse(body);
+
+    if (!result.success) {
+      return c.json(
+        {
+          error: "Validation failed",
+          details: result.error.flatten().fieldErrors,
+        },
+        400,
+      );
+    }
+
+    const newTodo = await db
+      .insert(todos)
+      .values({ title: result.data.title })
+      .returning()
+      .get();
+    return c.json(newTodo, 201);
+  } catch (error) {
+    console.error(error);
+    return c.json({ error: "Internal server error" }, 500);
+  }
+});
+
+// PATCH /api/todos/:id — Toggle a todo's completion status
+apiRoutes.patch("/todos/:id", async (c) => {
+  try {
+    const idResult = todoIdSchema.safeParse(c.req.param("id"));
+
+    if (!idResult.success) {
+      return c.json({ error: "Invalid ID" }, 400);
+    }
+
+    const id = idResult.data;
+    const existing = await db
+      .select()
+      .from(todos)
+      .where(eq(todos.id, id))
+      .get();
+
+    if (!existing) {
+      return c.json({ error: "Todo not found" }, 404);
+    }
+
+    const updated = await db
+      .update(todos)
+      .set({
+        completed: !existing.completed,
+        updatedAt: sql`(current_timestamp)`,
+      })
+      .where(eq(todos.id, id))
+      .returning()
+      .get();
+    return c.json(updated);
+  } catch (error) {
+    console.error(error);
+    return c.json({ error: "Internal server error" }, 500);
+  }
+});
+
+// DELETE /api/todos/:id — Delete a todo
+apiRoutes.delete("/todos/:id", async (c) => {
+  try {
+    const idResult = todoIdSchema.safeParse(c.req.param("id"));
+
+    if (!idResult.success) {
+      return c.json({ error: "Invalid ID" }, 400);
+    }
+
+    const id = idResult.data;
+    const deleted = await db
+      .delete(todos)
+      .where(eq(todos.id, id))
+      .returning()
+      .get();
+
+    if (!deleted) {
+      return c.json({ error: "Todo not found" }, 404);
+    }
+
+    return c.json({ success: true });
+  } catch (error) {
+    console.error(error);
+    return c.json({ error: "Internal server error" }, 500);
+  }
+});

package/templates/fullstack/src/server/routes/schemas.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const createTodoSchema = z.object({
+  title: z.string().min(1).max(500),
+});
+
+export const todoIdSchema = z.coerce.number().int().positive();

package/templates/fullstack/src/test/setup.ts

@@ -0,0 +1,9 @@
+process.env.DATABASE_URL = "file:test.db";
+
+import { beforeEach } from "vitest";
+import { db } from "../server/db/index";
+import { todos } from "../server/db/schema";
+
+beforeEach(async () => {
+  await db.delete(todos);
+});

package/templates/fullstack/vite.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import devServer from "@hono/vite-dev-server";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    devServer({
+      entry: "src/server/index.ts",
+      // Only send /api/* requests to Hono — let Vite handle everything else
+      // (static assets, SPA fallback, HMR, etc.)
+      exclude: [/^\/(?!api\/).*/, /^\/$/],
+      injectClientScript: false,
+    }),
+  ],
+  build: {
+    target: "esnext",
+    outDir: "dist/public",
+    chunkSizeWarningLimit: 600,
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (
+            id.includes("node_modules/react-dom") ||
+            id.includes("node_modules/react/") ||
+            id.includes("node_modules/scheduler")
+          ) {
+            return "vendor";
+          }
+          if (id.includes("node_modules/@tanstack/react-query")) {
+            return "query";
+          }
+        },
+      },
+    },
+  },
+});

package/templates/fullstack/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    setupFiles: ["src/test/setup.ts"],
+  },
+});

package/templates/starter/.env.example

@@ -0,0 +1 @@
+VITE_API_URL=https://api.fluid.app

package/templates/starter/README.md.template

@@ -0,0 +1,218 @@
+# {{projectName}}
+
+A custom Fluid portal built with [@fluid-app/portal-sdk](https://github.com/fluidcommerce/portal-sdk).
+
+This is the **Starter** template - includes a dashboard with multiple widgets plus all core screens.
+
+## What's Included
+
+### Core Screens (Built-in)
+- **Messages** - Conversation management (MessagingScreen)
+- **Contacts** - Contact directory (ContactsScreen)
+
+### Custom Screens
+- **Dashboard** - Overview screen demonstrating:
+  - TextWidget - Welcome message and tips
+  - ToDoWidget - Task list (uses `useTodos` hook)
+  - RecentActivityWidget - Activity feed (uses `useActivities` hook)
+  - ChartWidget - Performance visualization
+  - CalendarWidget - Event calendar (uses `useCalendarEvents` hook)
+
+## Getting Started
+
+### Development
+
+Start the development server:
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) in your browser.
+
+### Building for Production
+
+```bash
+pnpm build
+```
+
+The output will be in the `dist/` folder.
+
+### Preview Production Build
+
+```bash
+pnpm preview
+```
+
+## Project Structure
+
+```
+src/
+├── main.tsx              # App entry with FluidProvider setup
+├── App.tsx               # Main app with screen routing
+├── index.css             # Global styles (Tailwind CSS)
+├── fluid.config.ts       # API and auth configuration
+├── portal.config.ts      # Navigation and screen registration
+├── navigation/
+│   └── index.tsx         # Sidebar navigation component
+└── screens/
+    └── Dashboard.tsx     # Dashboard with multiple widgets
+```
+
+## Customization
+
+### Modify Navigation
+
+Edit `src/portal.config.ts` to add, remove, or reorder navigation items:
+
+```typescript
+navigation: [
+  // Your custom screens
+  { id: "dashboard", label: "Dashboard", icon: "LayoutDashboard", screen: "custom:dashboard" },
+
+  // Built-in core screens
+  { id: "messaging", label: "Messages", icon: "MessageSquare", screen: "core:messaging" },
+  // ...
+],
+```
+
+### Add Custom Screens
+
+1. Create a screen component in `src/screens/`:
+
+```tsx
+// src/screens/Orders.tsx
+import { TableWidget, TextWidget } from "@fluid-app/portal-sdk";
+
+export function OrdersScreen() {
+  return (
+    <div className="space-y-6">
+      <TextWidget title="Orders" titleEnabled padding={4} borderRadius="lg" />
+      {/* Add more widgets */}
+    </div>
+  );
+}
+```
+
+2. Register in `portal.config.ts`:
+
+```typescript
+import { OrdersScreen } from "./screens/Orders";
+
+customScreens: {
+  dashboard: DashboardScreen,
+  orders: OrdersScreen,  // Add here
+},
+```
+
+3. Add to navigation:
+
+```typescript
+{ id: "orders", label: "Orders", icon: "ShoppingCart", screen: "custom:orders" },
+```
+
+### Connect to Fluid API
+
+Edit `src/fluid.config.ts` to configure your API connection:
+
+```typescript
+export const fluidConfig: FluidSDKConfig = {
+  baseUrl: import.meta.env.VITE_API_URL ?? "https://api.fluid.app",
+  getAuthToken: () => getStoredToken() ?? null,
+};
+```
+
+## Available Widgets
+
+Import from `@fluid-app/portal-sdk`:
+
+| Widget | Description |
+|--------|-------------|
+| `TextWidget` | Text content with optional title |
+| `ChartWidget` | Bar, line, area, pie charts |
+| `TableWidget` | Data tables with columns |
+| `ListWidget` | Lists with icons and actions |
+| `ToDoWidget` | Task list (uses `useTodos`) |
+| `RecentActivityWidget` | Activity feed (uses `useActivities`) |
+| `CalendarWidget` | Calendar view (uses `useCalendarEvents`) |
+| `CatchUpWidget` | Catch-up items |
+| `AlertWidget` | Info, warning, error alerts |
+| `ImageWidget` | Images with sizing options |
+| `VideoWidget` | Embedded video players |
+| `CarouselWidget` | Image/content carousel |
+| `ContainerWidget` | Layout containers |
+| `SpacerWidget` | Vertical spacing |
+
+## Building Forms
+
+For data-entry screens (order forms, customer intake, settings), we recommend [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) for validation.
+
+### Install form dependencies
+
+```bash
+pnpm add react-hook-form zod @hookform/resolvers
+```
+
+### Example
+
+```tsx
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.string().email("Invalid email"),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function MyFormScreen() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = async (data: FormData) => {
+    // Call your API here
+    console.log(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("name")} placeholder="Name" />
+      {errors.name && <p>{errors.name.message}</p>}
+
+      <input {...register("email")} placeholder="Email" />
+      {errors.email && <p>{errors.email.message}</p>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Submitting..." : "Submit"}
+      </button>
+    </form>
+  );
+}
+```
+
+### Starter example
+
+A complete form example is included at `src/screens/ExampleForm.tsx`. To enable it:
+
+1. Install the form dependencies above
+2. Uncomment the import and nav entry in `src/portal.config.ts`
+
+## Styling
+
+This project uses [Tailwind CSS v4](https://tailwindcss.com/).
+
+Edit `src/index.css` to customize the theme or add global styles.
+
+## Learn More
+
+- [Fluid Commerce Documentation](https://docs.fluidcommerce.com)
+- [portal-sdk GitHub](https://github.com/fluidcommerce/portal-sdk)
+- [Vite Documentation](https://vite.dev)
+- [React Documentation](https://react.dev)

package/templates/starter/package.json.template

@@ -0,0 +1,40 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fluid-app/portal-sdk": "{{sdkVersion}}",
+    "@fortawesome/fontawesome-svg-core": "^6.7.2",
+    "@fortawesome/pro-regular-svg-icons": "^6.7.2",
+    "@fortawesome/react-fontawesome": "^0.2.2",
+    "@tanstack/react-query": "^5.90.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.55.0",
+    "@hookform/resolvers": "^4.1.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.4.1",
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

package/templates/starter/src/fluid.config.ts.template

@@ -0,0 +1,69 @@
+import type { FluidSDKConfig, FluidAuthConfig } from "@fluid-app/portal-sdk";
+import { getStoredToken } from "@fluid-app/portal-sdk";
+
+/**
+ * Fluid SDK Configuration
+ *
+ * This file contains the configuration for connecting to your Fluid Commerce account.
+ * Authentication is handled by FluidAuthProvider, which automatically:
+ * - Extracts tokens from URL parameters (passed by parent Fluid app)
+ * - Stores tokens in cookies and localStorage
+ * - Validates token expiration
+ */
+
+/**
+ * Authentication configuration
+ *
+ * Pattern: safety-satisfies-over-type-annotation
+ * Using `satisfies FluidAuthConfig` validates the object shape against the type
+ * WITHOUT widening the inferred types. This means:
+ *   - TypeScript checks that all required properties are present
+ *   - TypeScript checks that property types are compatible
+ *   - The actual inferred types remain as specific as possible
+ *
+ * Compare to type annotation (`const authConfig: FluidAuthConfig = {...}`):
+ * - Type annotation widens types to match the interface exactly
+ * - `satisfies` preserves literal types while validating structure
+ */
+export const authConfig = {
+  /**
+   * Enable dev-mode auth bypass for local development.
+   * This lets you run the portal without a real JWT token.
+   * Only active in Vite dev mode (pnpm dev) - automatically disabled in production builds.
+   */
+  devBypass: true,
+
+  // Auth failure defaults: SDK automatically redirects to https://auth.fluid.app
+  // with a redirect_url back to the current page. To customize:
+  //   onAuthFailure: () => { window.location.href = "/custom-login"; },
+  //   authUrl: "https://custom-auth.example.com",
+} satisfies FluidAuthConfig;
+
+/**
+ * API client configuration
+ *
+ * Pattern: safety-satisfies-over-type-annotation
+ * See authConfig above for explanation of the `satisfies` pattern.
+ *
+ * This config is passed to FluidProvider to configure the API client.
+ * The callbacks (getAuthToken, onAuthError) are called by the SDK
+ * when making API requests.
+ */
+export const fluidConfig = {
+  /**
+   * Base URL for the Fluid API
+   * Change this to your Fluid instance URL if self-hosted
+   */
+  baseUrl: import.meta.env.VITE_API_URL ?? "https://api.fluid.app",
+
+  /**
+   * Returns the authentication token for API requests
+   * This reads from the token stored by FluidAuthProvider
+   */
+  getAuthToken: () => {
+    return getStoredToken() ?? null;
+  },
+
+  // 401 errors default: SDK automatically redirects to https://auth.fluid.app
+  // To customize: onAuthError: () => { clearTokens(); window.location.reload(); },
+} satisfies FluidSDKConfig;

package/templates/starter/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    // Target modern browsers for smaller bundles
+    target: "esnext",
+  },
+});