@fluid-app/fluid-cli-portal 0.1.0

package/templates/base/src/index.css

@@ -0,0 +1,80 @@
+@import "tailwindcss";
+@import "@fluid-app/portal-widgets/globals.css";
+@import "@fluid-app/messaging-ui/styles/messaging.css";
+@source "../node_modules/@fluid-app/**/dist/**/*.js";
+
+/*
+ * Light-mode fallback tokens (OKLCH format).
+ *
+ * The theme engine injects higher-specificity CSS via [data-theme="..."]
+ * which overrides these at runtime for both light and dark modes.
+ *
+ * Canonical variables use the --color- prefix to match the css-generator
+ * output and the widgets tailwind.config.ts color palette registration.
+ * Short-name aliases (--background, --foreground, etc.) are included for
+ * backward compatibility with shadcn/Radix components.
+ */
+
+:root {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --color-secondary: oklch(0.97 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+  --color-muted: oklch(0.97 0 0);
+  --color-muted-foreground: oklch(0.556 0 0);
+  --color-accent: oklch(0.97 0 0);
+  --color-accent-foreground: oklch(0.205 0 0);
+  --color-destructive: oklch(0.577 0.245 27.325);
+  --color-destructive-foreground: oklch(0.985 0 0);
+  --color-border: oklch(0.922 0 0);
+
+  /* Short-name aliases (match css-generator globalCSSOverride) */
+  --background: var(--color-background);
+  --foreground: var(--color-foreground);
+  --primary: var(--color-primary);
+  --primary-foreground: var(--color-primary-foreground);
+  --secondary: var(--color-secondary);
+  --secondary-foreground: var(--color-secondary-foreground);
+  --muted: var(--color-muted);
+  --muted-foreground: var(--color-muted-foreground);
+  --accent: var(--color-accent);
+  --accent-foreground: var(--color-accent-foreground);
+  --destructive: var(--color-destructive);
+  --destructive-foreground: var(--color-destructive-foreground);
+  --border: var(--color-border);
+  --input: var(--color-border);
+  --ring: var(--color-primary);
+  --radius: 0.625rem;
+
+  /* Sidebar aliases */
+  --sidebar: var(--color-muted);
+  --sidebar-foreground: var(--color-muted-foreground);
+  --sidebar-primary: var(--color-primary);
+  --sidebar-primary-foreground: var(--color-primary-foreground);
+  --sidebar-accent: var(--color-accent);
+  --sidebar-accent-foreground: var(--color-accent-foreground);
+  --sidebar-border: var(--color-border);
+  --sidebar-ring: var(--color-primary);
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+/* Hide scrollbars while preserving scroll functionality */
+@layer utilities {
+  .scrollbar-none {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  .scrollbar-none::-webkit-scrollbar {
+    display: none;
+  }
+}

package/templates/base/src/main.tsx

@@ -0,0 +1,42 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import {
+  FluidAuthProvider,
+  FluidProvider,
+  RequireAuth,
+} from "@fluid-app/portal-sdk";
+import { authConfig, fluidConfig } from "./fluid.config";
+import App from "./App";
+import "./index.css";
+
+// Find the root element
+const rootElement = document.getElementById("root");
+if (!rootElement) {
+  throw new Error("Root element not found");
+}
+
+/**
+ * App Wrapper with Authentication
+ *
+ * The provider hierarchy is:
+ * 1. FluidAuthProvider - Handles token extraction, validation, storage
+ * 2. FluidProvider - Fluid SDK context (API client, theme, QueryClientProvider)
+ * 3. RequireAuth - Only renders children when authenticated
+ *
+ * Authentication flow:
+ * 1. Parent Fluid app opens this portal with ?fluidUserToken=... in URL
+ * 2. FluidAuthProvider extracts token, validates it, stores in cookie/localStorage
+ * 3. Token is removed from URL (security)
+ * 4. RequireAuth shows loading while checking, then renders app or error
+ */
+createRoot(rootElement).render(
+  <StrictMode>
+    <FluidAuthProvider config={authConfig}>
+      <FluidProvider config={fluidConfig}>
+        <RequireAuth>
+          <App />
+        </RequireAuth>
+      </FluidProvider>
+    </FluidAuthProvider>
+  </StrictMode>,
+);

package/templates/base/src/navigation.config.ts

@@ -0,0 +1,21 @@
+/**
+ * Code-defined navigation items.
+ *
+ * Synced to the Fluid OS API on `fluid deploy` with source: "code".
+ * Position is derived from array order. Items without a slug are
+ * treated as section headers.
+ *
+ * User-created navigation items (from the admin dashboard) are not
+ * affected — only items with source: "code" are managed.
+ *
+ * IMPORTANT: Do not add import statements to this file. The Fluid CLI
+ * reads this file without resolving dependencies, so it must be
+ * self-contained static data only.
+ */
+export const navigation = [
+  {
+    label: "Dashboard",
+    slug: "dashboard",
+    icon: "home",
+  },
+];

package/templates/base/src/portal.config.ts

@@ -0,0 +1,32 @@
+/**
+ * Portal Configuration
+ *
+ * Register custom page components here. These are rendered by AppShell
+ * when a navigation item's slug matches the key in this map.
+ *
+ * Navigation structure is defined in navigation.config.ts and synced to
+ * the Fluid OS API on `fluid deploy`.
+ *
+ * QUICK START:
+ * 1. Create a new screen component in ./screens/
+ * 2. Import it below and add it to customPages
+ * 3. Add a matching entry to src/navigation.config.ts
+ */
+
+import type { ComponentType } from "react";
+import { DashboardScreen } from "./screens/Dashboard";
+// Uncomment after installing form deps (pnpm add react-hook-form zod @hookform/resolvers):
+// import { ExampleFormScreen } from "./screens/ExampleForm";
+
+/**
+ * Custom page components keyed by navigation slug.
+ *
+ * When AppShell resolves a navigation item, it checks this map first.
+ * If a matching slug is found here, the custom component is rendered
+ * instead of the default system screen or placeholder.
+ */
+export const customPages: Record<string, ComponentType> = {
+  dashboard: DashboardScreen,
+  // Add more custom screens here:
+  // "example-form": ExampleFormScreen,
+};

package/templates/base/src/screens/Dashboard.tsx

@@ -0,0 +1,133 @@
+import {
+  TextWidget,
+  ChartWidget,
+  ToDoWidget,
+  RecentActivityWidget,
+  CalendarWidget,
+} from "@fluid-app/portal-sdk";
+
+/**
+ * Sample chart data extracted as a module-level constant.
+ *
+ * The data is extracted as a constant to:
+ * 1. Keep the component cleaner
+ * 2. Allow reuse/testing if needed
+ * 3. Make it clear the data is static
+ */
+const MONTHLY_PERFORMANCE_DATA = [
+  { name: "Jan", value: 4000 },
+  { name: "Feb", value: 3000 },
+  { name: "Mar", value: 5000 },
+  { name: "Apr", value: 4500 },
+  { name: "May", value: 6000 },
+  { name: "Jun", value: 5500 },
+];
+
+/**
+ * Dashboard Screen
+ *
+ * This is the default landing screen for the portal.
+ * It demonstrates using various widgets from portal-sdk:
+ *
+ * - TextWidget: Display text content with optional title
+ * - ToDoWidget: Task list (uses useTodos hook)
+ * - RecentActivityWidget: Activity feed (uses useActivities hook)
+ * - ChartWidget: Bar, line, area, pie charts
+ * - CalendarWidget: Calendar view (uses useCalendarEvents hook)
+ *
+ * These widgets fetch data from hooks that connect to your Fluid API.
+ * In development, they show demo data. Configure fluid.config.ts
+ * to connect to your Fluid instance.
+ */
+export function DashboardScreen() {
+  return (
+    <div className="space-y-6">
+      {/* Welcome section */}
+      <TextWidget
+        titleEnabled
+        title="Welcome to Your Portal"
+        description="This is your portal dashboard. Use widgets from @fluid-app/portal-sdk to build powerful interfaces for your team."
+        padding={4}
+        borderRadius="lg"
+      />
+
+      {/* Stats row - sample static data */}
+      <div className="grid gap-6 md:grid-cols-3">
+        <div className="bg-background rounded-lg p-4 shadow-sm">
+          <p className="text-foreground text-3xl font-bold">$12,450</p>
+          <p className="text-muted-foreground mt-1 text-sm">Total Sales</p>
+        </div>
+
+        <div className="bg-background rounded-lg p-4 shadow-sm">
+          <p className="text-foreground text-3xl font-bold">24</p>
+          <p className="text-muted-foreground mt-1 text-sm">Active Orders</p>
+        </div>
+
+        <div className="bg-background rounded-lg p-4 shadow-sm">
+          <p className="text-foreground text-3xl font-bold">156</p>
+          <p className="text-muted-foreground mt-1 text-sm">Customers</p>
+        </div>
+      </div>
+
+      {/* Main content grid - Tasks and Activity */}
+      <div className="grid gap-6 lg:grid-cols-2">
+        {/* To-Do Widget - fetches tasks via useTodos hook */}
+        <ToDoWidget
+          titleEnabled
+          titleText="Tasks"
+          maxItems={5}
+          padding={4}
+          borderRadius="lg"
+        />
+
+        {/* Recent Activity Widget - fetches via useActivities hook */}
+        <RecentActivityWidget
+          titleEnabled
+          titleText="Recent Activity"
+          maxItemsToShow={5}
+          padding={4}
+          borderRadius="lg"
+        />
+      </div>
+
+      {/* Performance chart - uses extracted constant data */}
+      <ChartWidget
+        titleEnabled
+        title="Monthly Performance"
+        chartType="bar"
+        data={MONTHLY_PERFORMANCE_DATA}
+        padding={4}
+        borderRadius="lg"
+      />
+
+      {/* Calendar preview - uses useCalendarEvents hook */}
+      <CalendarWidget
+        titleEnabled
+        titleText="Upcoming Events"
+        padding={4}
+        borderRadius="lg"
+      />
+
+      {/* Getting started tips */}
+      <div className="grid gap-6 md:grid-cols-2">
+        <TextWidget
+          titleEnabled
+          title="Customize Navigation"
+          description="Edit portal.config.ts to add, remove, or reorder navigation items. Core screens (Messaging, Contacts) are built-in."
+          padding={4}
+          borderRadius="lg"
+          background={{ type: "solid", color: "muted" }}
+        />
+
+        <TextWidget
+          titleEnabled
+          title="Connect Your Data"
+          description="Configure fluid.config.ts with your Fluid API credentials. Widgets will automatically fetch real data from your account."
+          padding={4}
+          borderRadius="lg"
+          background={{ type: "solid", color: "muted" }}
+        />
+      </div>
+    </div>
+  );
+}

package/templates/base/src/screens/ExampleForm.tsx

@@ -0,0 +1,187 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck — This file requires optional dependencies (react-hook-form, zod, @hookform/resolvers).
+// Install them before removing this directive: pnpm add react-hook-form zod @hookform/resolvers
+/**
+ * Example Form Screen
+ *
+ * Demonstrates how to build forms in a portal using
+ * React Hook Form + Zod for validation.
+ *
+ * SETUP: Install form dependencies before using this screen:
+ *   pnpm add react-hook-form zod @hookform/resolvers
+ *
+ * Then uncomment the nav entry and import in portal.config.ts.
+ */
+
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+// =============================================================================
+// Zod Schema
+// Define your form validation schema here
+// =============================================================================
+
+const contactFormSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100, "Name is too long"),
+  email: z.string().email("Invalid email address"),
+  subject: z
+    .string()
+    .min(1, "Subject is required")
+    .max(200, "Subject is too long"),
+  message: z
+    .string()
+    .min(10, "Message must be at least 10 characters")
+    .max(2000, "Message is too long"),
+});
+
+type ContactFormData = z.infer<typeof contactFormSchema>;
+
+// =============================================================================
+// Example Form Screen
+// =============================================================================
+
+export function ExampleFormScreen() {
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors, isSubmitting, isSubmitSuccessful },
+  } = useForm<ContactFormData>({
+    resolver: zodResolver(contactFormSchema),
+  });
+
+  const onSubmit = async (data: ContactFormData) => {
+    // Replace with your API call, e.g.:
+    // const result = await apiClient.post("/contacts", data);
+    console.log("Form submitted:", data);
+
+    // Simulate API delay
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    reset(undefined, { keepIsSubmitSuccessful: true });
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div>
+        <h1 className="text-foreground text-2xl font-bold">Example Form</h1>
+        <p className="text-muted-foreground mt-1 text-sm">
+          Demonstrates React Hook Form + Zod validation. Replace this with your
+          own form.
+        </p>
+      </div>
+
+      {/* Form Card */}
+      <div className="border-border bg-background rounded-lg border p-6 shadow-sm">
+        {isSubmitSuccessful ? (
+          <div className="border-accent bg-accent text-accent-foreground rounded-lg border p-4 text-sm">
+            Form submitted successfully! Check the console for the data.
+          </div>
+        ) : (
+          <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+            {/* Name field */}
+            <div>
+              <label
+                htmlFor="name"
+                className="text-foreground block text-sm font-medium"
+              >
+                Name
+              </label>
+              <input
+                id="name"
+                type="text"
+                {...register("name")}
+                className="border-input bg-background text-foreground focus:border-ring focus:ring-ring mt-1 block w-full rounded-md border px-3 py-2 text-sm shadow-sm focus:ring-1 focus:outline-none"
+                placeholder="Jane Smith"
+              />
+              {errors.name && (
+                <p className="text-destructive mt-1 text-sm">
+                  {errors.name.message}
+                </p>
+              )}
+            </div>
+
+            {/* Email field */}
+            <div>
+              <label
+                htmlFor="email"
+                className="text-foreground block text-sm font-medium"
+              >
+                Email
+              </label>
+              <input
+                id="email"
+                type="email"
+                {...register("email")}
+                className="border-input bg-background text-foreground focus:border-ring focus:ring-ring mt-1 block w-full rounded-md border px-3 py-2 text-sm shadow-sm focus:ring-1 focus:outline-none"
+                placeholder="jane@example.com"
+              />
+              {errors.email && (
+                <p className="text-destructive mt-1 text-sm">
+                  {errors.email.message}
+                </p>
+              )}
+            </div>
+
+            {/* Subject field */}
+            <div>
+              <label
+                htmlFor="subject"
+                className="text-foreground block text-sm font-medium"
+              >
+                Subject
+              </label>
+              <input
+                id="subject"
+                type="text"
+                {...register("subject")}
+                className="border-input bg-background text-foreground focus:border-ring focus:ring-ring mt-1 block w-full rounded-md border px-3 py-2 text-sm shadow-sm focus:ring-1 focus:outline-none"
+                placeholder="Order inquiry"
+              />
+              {errors.subject && (
+                <p className="text-destructive mt-1 text-sm">
+                  {errors.subject.message}
+                </p>
+              )}
+            </div>
+
+            {/* Message field */}
+            <div>
+              <label
+                htmlFor="message"
+                className="text-foreground block text-sm font-medium"
+              >
+                Message
+              </label>
+              <textarea
+                id="message"
+                rows={4}
+                {...register("message")}
+                className="border-input bg-background text-foreground focus:border-ring focus:ring-ring mt-1 block w-full rounded-md border px-3 py-2 text-sm shadow-sm focus:ring-1 focus:outline-none"
+                placeholder="Tell us more..."
+              />
+              {errors.message && (
+                <p className="text-destructive mt-1 text-sm">
+                  {errors.message.message}
+                </p>
+              )}
+            </div>
+
+            {/* Submit button */}
+            <div className="flex justify-end">
+              <button
+                type="submit"
+                disabled={isSubmitting}
+                className="bg-primary text-primary-foreground hover:bg-primary/90 focus:ring-ring focus:ring-offset-background rounded-md px-4 py-2 text-sm font-medium shadow-sm focus:ring-2 focus:ring-offset-2 focus:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+              >
+                {isSubmitting ? "Submitting..." : "Submit"}
+              </button>
+            </div>
+          </form>
+        )}
+      </div>
+    </div>
+  );
+}

package/templates/base/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/base/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src"]
+}

package/templates/fullstack/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.env
+.env.*
+!.env.example
+.git
+*.db
+*.db-journal
+*.db-wal

package/templates/fullstack/.env.example

@@ -0,0 +1,15 @@
+# ─── Development ─────────────────────────────────────────────────────────────
+VITE_API_URL=https://api.fluid.app
+DATABASE_URL=file:local.db
+DATABASE_AUTH_TOKEN=
+
+# Allowed CORS origin (defaults to http://localhost:5173 in development)
+ALLOWED_ORIGIN=
+
+# ─── Deployment (used by `fluid deploy`) ─────────────────────────────────────
+# Fluid company API key (required for deploy/destroy)
+FLUID_COMPANY_API_KEY=
+
+# Get your API token at: https://app.turso.tech/api-tokens
+TURSO_API_TOKEN=
+TURSO_ORG=

package/templates/fullstack/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_URL: file:test.db
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm db:push
+      - run: pnpm test

package/templates/fullstack/.github/workflows/deploy.yml

@@ -0,0 +1,54 @@
+name: Deploy
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build & Validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+  deploy:
+    name: Deploy to Cloud Run
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          credentials_json: ${{ secrets.GCP_SA_JSON }}
+
+      - name: Set up Cloud SDK
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Get service name
+        id: meta
+        run: echo "service=$(jq -r .name package.json | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g' | sed 's/^-\|-$//g')" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy to Cloud Run
+        run: |
+          gcloud run deploy ${{ steps.meta.outputs.service }} \
+            --source . \
+            --region ${{ vars.CLOUD_RUN_REGION || 'us-central1' }} \
+            --project ${{ vars.GCP_PROJECT }} \
+            --allow-unauthenticated \
+            --set-env-vars="DATABASE_URL=${{ secrets.DATABASE_URL }},DATABASE_AUTH_TOKEN=${{ secrets.DATABASE_AUTH_TOKEN }},NODE_ENV=production"