create-bluecopa-react-app 1.0.44 → 1.0.45

package/README.md

@@ -2,26 +2,31 @@
 
 ## A CLI Tool for Bluecopa React Applications
 
-A command-line interface for bootstrapping modern React applications with Bluecopa integration, featuring opinionated best practices and pre-configured tooling.
+A command-line interface for scaffolding a Bluecopa microfrontend (MFE) React
+application, pre-wired for the Bluecopa platform: `@bluecopa/react` data hooks,
+single-spa + Module Federation mounting, the Dream Light design system on
+Tailwind CSS v4, AG Grid tables and ECharts charts.
+
+> The generated app is a **single-spa / Module Federation microfrontend** that
+> mounts inside the Bluecopa shell (it also runs standalone for local dev). It is
+> not a plain React Router SPA.
 
 ## Table of Contents
 
-- [Version](#version)
 - [Installation](#installation)
 - [Requirements](#requirements)
-- [Configuration](#configuration)
-- [Features](#features)
 - [Usage](#usage)
-- [API Documentation](#api-documentation)
-- [Examples](#examples)
+- [CLI Options](#cli-options)
+- [Interactive Prompts](#interactive-prompts)
+- [Features](#features)
+- [Generated App](#generated-app)
+  - [Tech Stack](#tech-stack)
+  - [Project Structure](#project-structure)
+  - [Scripts](#scripts)
 - [Development](#development)
-- [Contributing](#contributing)
+- [Monorepo Integration](#monorepo-integration)
 - [License](#license)
 
-## Version
-
-Current version: 1.0.5
-
 ## Installation
 
 ```bash
@@ -30,142 +35,159 @@ npm install -g create-bluecopa-react-app
 pnpm add -g create-bluecopa-react-app
 ```
 
-## Requirements
-
-- Node.js >= 18.0.0
-- npm >= 9.0.0 or pnpm >= 8.0.0
-
-## Configuration
-
-The CLI uses environment variables for configuration:
+Or run without installing:
 
 ```bash
-# Optional configuration
-export BLUECOPA_BOILERPLATE_REGISTRY=https://registry.npmjs.org
+npx create-bluecopa-react-app my-dashboard
 ```
 
-## Features
+## Requirements
 
-- 🚀 **Modern React Stack**: React 18, TypeScript, React Router v7, Vite 6
-- 🌐 **Microfrontend Support**: Single-spa compatible with module federation
-- 📊 **Data Visualization**: Recharts integration for charts and analytics
-- 🎨 **UI Components**: shadcn/ui components built on Radix UI primitives
-- 📡 **Bluecopa React Components**: Pre-configured [`@bluecopa/react`](packages/react:1) package with hooks (includes TanStack Query integration)
-- 🎯 **Type Safety**: Full TypeScript support
-- 📱 **Responsive Design**: Tailwind CSS v4 with mobile-first approach and Bluecopa design system
-- 🛠️ **Development Tools**: ESLint, TypeScript checking, and Vite fast build system
-- ⚡ **Fast Development**: Hot module replacement with Vite
-- 🔄 **Server-side Rendering**: React Router v7 with SSR support
-- 🌙 **Dark Mode**: Built-in theme switching with next-themes
-- 🗂️ **Data Tables**: TanStack Table with sorting, filtering, and pagination
-- 🎯 **Drag & Drop**: DND Kit integration for interactive interfaces
+- Node.js >= 18.0.0
+- npm >= 9, or pnpm (recommended). yarn is also supported.
 
 ## Usage
 
-### Creating a New Application
-
 ```bash
-# Create new app with default template
-create-bluecopa-react-app my-dashboard
+# Interactive — prompts for name, template, git, package manager, install
+create-bluecopa-react-app
 
-# Create new app with shadcn/ui template
-create-bluecopa-react-app my-dashboard --template shadcn
+# Non-interactive
+create-bluecopa-react-app my-dashboard --yes
 
-# Or use npx
-npx create-bluecopa-react-app my-dashboard
-npx create-bluecopa-react-app my-dashboard --template shadcn
+# Explicit options
+create-bluecopa-react-app my-app --package-manager pnpm --no-git
+create-bluecopa-react-app my-app --skip-install
 ```
 
-### Available Templates
+## CLI Options
 
-- **Default Template**: Basic React Router setup with essential components
-- **shadcn Template**: Full-featured template with shadcn/ui components, data tables, charts, and dark mode support
+Positional argument: `[project-name]` — name of the project directory (prompted if omitted).
 
-### CLI Options
+| Option                             | Alias | Description                            | Default    |
+| ---------------------------------- | ----- | -------------------------------------- | ---------- |
+| `--template <template>`            | `-t`  | Template to use (only `latest` exists) | `latest`   |
+| `--package-manager <manager>`      |       | Package manager: `npm`, `yarn`, `pnpm` | `auto`     |
+| `--skip-install`                   |       | Skip dependency installation           | installs   |
+| `--git` / `--no-git`               |       | Initialize (or skip) a git repository  | `--git`    |
+| `--yes`                            |       | Skip all prompts and use defaults      | off        |
+| `--typescript` / `--no-typescript` |       | Template language flag (see note)      | TypeScript |
+| `--version`                        |       | Print the CLI version                  |            |
+| `--help`                           |       | Show help                              |            |
 
-| Option           | Description                        |
-| ---------------- | ---------------------------------- |
-| `--skip-install` | Skip dependency installation       |
-| `--template`     | Specify template (default, shadcn) |
-| `--help`         | Show help information              |
+> **Note:** only a single TypeScript template (`latest`) ships today. The
+> `--typescript` / `--no-typescript` flags are parsed but there is no JavaScript
+> template, so they have no effect.
 
-## API Documentation
+## Interactive Prompts
 
-### `create-bluecopa-react-app [project-name] [options]`
+When `--yes` is not passed, the CLI prompts (via inquirer) in order:
 
-Creates a new Bluecopa React application.
+1. **Project name** — defaults to a random `my-<adjective>-<noun>`; validated against npm naming rules.
+2. **Template** — `latest` (Bluecopa MFE React app).
+3. **Initialize git repository?** — default yes (unless `--no-git`).
+4. **Package manager** — pnpm (recommended) / npm / auto-detect.
+5. **Install dependencies now?** — default depends on `--skip-install`.
 
-**Parameters:**
+If the target directory already exists, it asks to overwrite (auto-overwrites with `--yes`). After copying the template it sets `package.json` `name`, replaces `{{APP_NAME}}` placeholders in the HTML entry points, and (when git is enabled) writes a `.gitignore` and creates an initial commit.
 
-- `project-name`: Name of the new project directory
-- `options`: CLI options (see above)
+## Features
 
-**Returns:**
+- ⚛️ **React 18 + TypeScript** with the SWC-based Vite plugin
+- 🧩 **Microfrontend-ready** — single-spa mount/unmount + Module Federation (`@originjs/vite-plugin-federation`), SystemJS output
+- 📡 **Bluecopa data layer** — pre-configured [`@bluecopa/react`](https://www.npmjs.com/package/@bluecopa/react) hooks (TanStack Query under the hood)
+- 🎨 **Dream Light design system** on **Tailwind CSS v4** with the `copa:` prefix, plus shadcn/ui (`new-york`) + Radix UI primitives
+- 🗂️ **AG Grid** tables (community + enterprise) with a server-side datasource helper
+- 📊 **ECharts** charts via a `ChartProvider` and themed chart components
+- 🔔 **Toasts** with sonner, icons from lucide-react and Tabler
+- 🧭 **React Router v7** routing
+- ⚡ **Vite** dev server + fast build, `~/` path alias to `app/`
+- 🐳 **Deployment ready** — Dockerfile and `.env.example` included
 
-- Creates project structure
-- Installs dependencies
-- Configures environment
+## Generated App
 
-## Examples
+### Tech Stack
 
-### Basic Usage
+| Area          | Libraries                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Framework     | React `^18.3.1`, react-dom `^18.3.1`, react-router-dom `^7.16.0`                                                   |
+| Build         | Vite `8.0.16`, `@vitejs/plugin-react-swc`, `vite-tsconfig-paths`, TypeScript `^5.8.3`                              |
+| Data layer    | `@bluecopa/react` `0.1.117` (TanStack Query)                                                                       |
+| Styling       | Tailwind CSS v4 (`@tailwindcss/vite`), `tw-animate-css`, `cva`, `clsx`, `tailwind-merge`                           |
+| UI            | shadcn/ui (`new-york`), Radix UI (dialog, dropdown, tabs, tooltip, …), lucide-react, `@tabler/icons-react`, sonner |
+| Tables        | `ag-grid-community`, `ag-grid-enterprise`, `ag-grid-react` (v34)                                                   |
+| Charts        | `echarts` v6 + `echarts-for-react` (also `ag-charts-enterprise` available)                                         |
+| Microfrontend | `single-spa` `6.0.3`, `@originjs/vite-plugin-federation`                                                           |
 
-```bash
-create-bluecopa-react-app my-dashboard
-```
+`package.json` `overrides` pin security-sensitive transitive deps: `axios` `1.16.0`, `rollup` `4.59.0`, `ajv` `8.18.0`, `protobufjs` `>=7.5.8 <8`, `postcss` `>=8.5.10`, `ws` `>=8.20.1 <9`.
 
-### Skipping Dependency Installation
+### Project Structure
 
-```bash
-create-bluecopa-react-app my-dashboard --skip-install
+The source root is `app/` (aliased as `~/`), not `src/`:
+
+```
+my-app/
+├── index.html            # standalone entry ({{APP_NAME}} placeholder)
+├── preview/index.html    # preview build entry
+├── vite.config.ts        # dev server :8080, Module Federation, SystemJS output
+├── tsconfig.json         # ES2022, bundler resolution, ~/* → app/*
+├── components.json        # shadcn config (new-york, copa prefix, @bluecopa-ui registry)
+├── Dockerfile, .env.example, .gitignore
+├── CLAUDE.md, Agent.md    # agent/dev guides
+├── public/                # favicons
+└── app/
+    ├── app.tsx            # root: QueryClient, ChartProvider, AppProvider, MFE config
+    ├── main.tsx           # standalone BrowserRouter entry
+    ├── single-spa.tsx     # MFE MemoryRouter entry (manualMount / manualUnmount)
+    ├── app.css            # Tailwind v4 + Dream Light theme tokens
+    ├── components/        # bluecopa-logo, error-boundary, loading-screen
+    │   ├── ui/            # shadcn components (button, card, sidebar, ag-grid-table, …)
+    │   ├── charts/        # ECharts: bar-chart, donut-chart, chart-provider, chart-theme
+    │   └── layouts/       # app-layout, app-sidebar, nav-main, nav-user, site-header
+    ├── contexts/          # app-context
+    ├── hooks/             # use-mobile, use-permissions
+    ├── pages/             # dashboard, payments, settings
+    ├── routes/            # index route table
+    ├── constants/, types/ # MfeProps, EnvConfig, …
+    └── utils/             # ag-grid-datasource, ag-grid-license, ag-grid-theme,
+                           # component-style, style-drivers, cn()
 ```
 
-### Using npx (Recommended)
+The Vite config exposes `./App` → `app/single-spa.tsx` under the federation name
+`__copa_ext_app__react_route` (`remoteEntry.js`), externalizes `react`/`react-dom`,
+and emits SystemJS (`format: "system"`) so the Bluecopa shell can mount it.
 
-```bash
-npx create-bluecopa-react-app my-dashboard
-```
+### Scripts
+
+| Script      | Command                              | Purpose                       |
+| ----------- | ------------------------------------ | ----------------------------- |
+| `dev`       | `vite`                               | Dev server on port 8080       |
+| `build`     | `tsc && vite build`                  | Type-check + production build |
+| `start`     | `npx serve dist -l 3001 --cors`      | Serve the production build    |
+| `preview`   | `npx serve ./preview -l 8080 --cors` | Serve the preview build       |
+| `typecheck` | `tsc`                                | Type-check without emitting   |
 
 ## Development
 
-### Available Scripts
-
-- `npm run dev` - Start Vite development server with hot reload
-- `npm run build` - Build for production (TypeScript + Vite optimization)
-- `npm run start` - Start production build locally
-- `npm run preview` - Preview production build locally
-- `npm run lint` - Run ESLint for code quality
-- `npm run lint:fix` - Fix linting issues
-- `npm run type-check` - Run TypeScript type checking without emitting files
-- `npm run clean` - Clean build artifacts and dependencies
-
-### Technologies Used
-
-- **React 18** - Modern React with concurrent features
-- **React Router v7** - Modern routing with SSR support
-- **Vite 6** - Fast build tool and development server
-- **TypeScript** - Full type safety and developer experience
-- **[`@bluecopa/react`](packages/react:1)** - Bluecopa-specific React components and hooks
-- **shadcn/ui** - Accessible component library built on Radix UI
-- **Radix UI** - Unstyled, accessible UI primitives
-- **TanStack Table** - Headless table library for React
-- **Recharts** - Composable charting library for React
-- **DND Kit** - Drag and drop toolkit for React
-- **Tailwind CSS v4** - Utility-first CSS framework with Bluecopa design system
-- **next-themes** - Theme switching with dark mode support
-- **Lucide React** - Beautiful, customizable icons
+Working on the CLI itself (inside the monorepo):
 
-## Monorepo Integration
+```bash
+# From packages/boilerplate/react
+node bin/create-bluecopa-react-app.js my-test-app   # run the CLI locally
+pnpm format                                          # format with Prettier
+```
+
+The template lives in `templates/latest/`. Edit files there to change what gets
+scaffolded. Keep the CLI's `.version()` in `bin/create-bluecopa-react-app.js` in
+sync with `package.json` when publishing.
 
-This CLI tool is part of the Bluecopa UI monorepo and integrates with the following packages:
+## Monorepo Integration
 
-- **[`@bluecopa/react`](packages/react:1)** - Bluecopa-specific React components and hooks
+This CLI is part of the Bluecopa UI monorepo and pairs with:
 
-### Standalone Development
+- [`@bluecopa/react`](https://www.npmjs.com/package/@bluecopa/react) — React Query hooks over the Bluecopa API
+- [`@bluecopa/core`](https://www.npmjs.com/package/@bluecopa/core) — the underlying TypeScript API SDK
 
-The generated applications can also be developed independently:
+## License
 
-1. **Self-contained**: All dependencies are properly installed
-2. **Environment setup**: Includes proper environment variable configuration
-3. **Build optimization**: Uses Vite for fast development and production builds
-4. **Deployment ready**: Includes Docker configuration and deployment guides
+MIT

package/bin/create-bluecopa-react-app.js

@@ -17,7 +17,7 @@ const __dirname = path.dirname(__filename);
 const program = new Command();
 
 program
-  .version("1.0.5")
+  .version("1.0.45")
   .name("create-bluecopa-react-app")
   .description("Create a new Bluecopa React application")
   .argument("[project-name]", "Name of the project")
@@ -28,7 +28,7 @@ program
   .option(
     "--package-manager <manager>",
     "Package manager to use (npm, yarn, pnpm)",
-    "auto"
+    "auto",
   )
   .option("--git", "Initialize git repository", true)
   .option("--no-git", "Skip git initialization")
@@ -49,7 +49,7 @@ Templates:
 
 For more information, visit:
   https://github.com/bluecopa/blui/tree/dev/packages/boilerplate/react
-`
+`,
   )
   .action(async (projectName, options) => {
     try {
@@ -178,7 +178,7 @@ async function createApp(projectName, options) {
     // When using --yes flag, validate required options
     if (!appName) {
       console.error(
-        chalk.red("Project name is required when using --yes flag")
+        chalk.red("Project name is required when using --yes flag"),
       );
       process.exit(1);
     }
@@ -189,7 +189,7 @@ async function createApp(projectName, options) {
   if (!validTemplates.includes(selectedTemplate)) {
     console.error(chalk.red(`Invalid template: ${selectedTemplate}`));
     console.error(
-      chalk.yellow(`Available templates: ${validTemplates.join(", ")}`)
+      chalk.yellow(`Available templates: ${validTemplates.join(", ")}`),
     );
     process.exit(1);
   }
@@ -199,12 +199,12 @@ async function createApp(projectName, options) {
   if (!validation.validForNewPackages) {
     console.error(
       chalk.red("Invalid project name:"),
-      validation.errors?.[0] || validation.warnings?.[0]
+      validation.errors?.[0] || validation.warnings?.[0],
     );
     console.error(
       chalk.yellow(
-        "Project names must be lowercase, contain no spaces, and follow npm naming conventions."
-      )
+        "Project names must be lowercase, contain no spaces, and follow npm naming conventions.",
+      ),
     );
     process.exit(1);
   }
@@ -215,7 +215,7 @@ async function createApp(projectName, options) {
   if (fs.existsSync(targetDir)) {
     if (options.yes) {
       console.log(
-        chalk.yellow(`Directory ${appName} already exists. Overwriting...`)
+        chalk.yellow(`Directory ${appName} already exists. Overwriting...`),
       );
       await fs.remove(targetDir);
     } else {
@@ -238,7 +238,9 @@ async function createApp(projectName, options) {
   }
 
   console.log(
-    chalk.blue(`Creating a new Bluecopa React app in ${chalk.green(targetDir)}`)
+    chalk.blue(
+      `Creating a new Bluecopa React app in ${chalk.green(targetDir)}`,
+    ),
   );
   console.log(chalk.gray(`Template: ${selectedTemplate}`));
   console.log();
@@ -256,15 +258,15 @@ async function createApp(projectName, options) {
     if (!options.skipInstall) {
       const detectedPackageManager = await detectPackageManager(packageManager);
       spinner.start(
-        `Installing dependencies with ${detectedPackageManager}...`
+        `Installing dependencies with ${detectedPackageManager}...`,
       );
       await installDependencies(targetDir, detectedPackageManager);
       spinner.succeed("Dependencies installed");
     } else {
       console.log(
         chalk.yellow(
-          "Skipping dependency installation. You can run it manually later."
-        )
+          "Skipping dependency installation. You can run it manually later.",
+        ),
       );
     }
 
@@ -276,7 +278,7 @@ async function createApp(projectName, options) {
     }
 
     spinner.succeed(
-      chalk.green("Success! Created " + appName + " at " + targetDir)
+      chalk.green("Success! Created " + appName + " at " + targetDir),
     );
 
     console.log();
@@ -336,8 +338,8 @@ async function createApp(projectName, options) {
     console.log(chalk.gray("Need help? Check out the documentation:"));
     console.log(
       chalk.gray(
-        "  https://github.com/bluecopa/blui/tree/main/packages/boilerplate/react"
-      )
+        "  https://github.com/bluecopa/blui/tree/main/packages/boilerplate/react",
+      ),
     );
   } catch (error) {
     spinner.fail("Failed to create project");
@@ -356,7 +358,7 @@ async function createProjectStructure(targetDir, appName, options) {
   // Validate template directory exists
   if (!(await fs.pathExists(templateDir))) {
     throw new Error(
-      `Template '${options.template}' not found at ${templateDir}`
+      `Template '${options.template}' not found at ${templateDir}`,
     );
   }
 
@@ -400,8 +402,8 @@ async function detectPackageManager(preferredManager) {
     } catch {
       console.log(
         chalk.yellow(
-          `Warning: ${preferredManager} not found, falling back to auto-detection`
-        )
+          `Warning: ${preferredManager} not found, falling back to auto-detection`,
+        ),
       );
     }
   }
@@ -437,7 +439,7 @@ async function installDependencies(targetDir, packageManager) {
     execSync(installCommand, { stdio: "inherit" });
   } catch (error) {
     throw new Error(
-      `Failed to install dependencies with ${packageManager}: ${error.message}`
+      `Failed to install dependencies with ${packageManager}: ${error.message}`,
     );
   }
 }
@@ -466,7 +468,7 @@ pnpm-debug.log*
     if (!fs.existsSync(gitignorePath)) {
       fs.writeFileSync(gitignorePath, gitignoreContent.trimStart());
     }
-    
+
     // Initialize git repository
     execSync("git init", { stdio: "ignore" });
     // Create initial commit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.44",
+  "version": "1.0.45",
   "description": "CLI tool to create bluecopa React applications",
   "type": "module",
   "main": "./bin/create-bluecopa-react-app.js",

package/templates/latest/CLAUDE.md

@@ -35,6 +35,7 @@ interface MfeProps {
   basename?: string;       // Router basename
   envVars?: EnvConfig;     // Runtime env (workbook `storedEnvVariable`) — see below
   schemaMap?: SchemaMap;   // Column-name normalization (workbook `storedSchemaMap`)
+  permissions?: PermissionsMap; // Logged-in user's authz check (actionId → permission → granted)
 }
 ```
 
@@ -60,6 +61,29 @@ It sets the `x-bluecopa-solution-*` headers from `envVars.VITE_BLUECOPA_SOLUTION
 `_SOLUTION_BRANCH` / `_SOLUTION_BRANCH_TYPE` — **required by the Input Table V2 SDK
 (`copaInputTableDb`)**. Defaults: branch `main`, type `REMOTE`.
 
+### Permissions (authorization)
+
+The host injects a `permissions` prop — the logged-in user's live authorization
+check (`actionId → permission → granted`), computed before mount against the
+app's access-control matrix. It's exposed via `useAppContext().permissions` and,
+more conveniently, the `usePermissions()` hook (`app/hooks/use-permissions.ts`):
+
+```tsx
+import { usePermissions } from "~/hooks/use-permissions";
+
+function SendEmailButton() {
+  const { can } = usePermissions();
+  if (!can("send_email")) return null;                    // any permission grants it
+  return <Button>Send</Button>;
+}
+// can("send_email", "write_with_approval") checks a specific permission.
+```
+
+Fail-closed: `permissions` defaults to `{}` (no model configured / non-owner), so
+`can()` returns `false`. Configure actions + the permission matrix on the app's
+**Settings → Access control** tab in the host; assign users in **Settings →
+Authorization → User Permission**.
+
 ### Error handling
 
 `app/components/error-boundary.tsx` (`RouteErrorBoundary`) wraps the routed tree in `app.tsx`.

package/templates/latest/app/app.tsx

@@ -81,7 +81,11 @@ export default function App(props: MfeProps) {
     <QueryClientProvider client={queryClient}>
       <div className="mfe-root copa:min-h-svh copa:animate-in copa:fade-in copa:duration-300">
         <ChartProvider>
-          <AppProvider envConfig={envConfig} schemaMap={props.schemaMap}>
+          <AppProvider
+            envConfig={envConfig}
+            schemaMap={props.schemaMap}
+            permissions={props.permissions}
+          >
             <RouteErrorBoundary>
               <RouteConfig />
             </RouteErrorBoundary>

package/templates/latest/app/contexts/app-context.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
 import { useUser, useGetAllUsers } from "@bluecopa/react";
-import type { AppUser, EnvConfig, SchemaMap, WorkspaceDataSettings } from "~/types";
+import type { AppUser, EnvConfig, PermissionsMap, SchemaMap, WorkspaceDataSettings } from "~/types";
 import { DEFAULT_WORKSPACE_SETTINGS } from "~/constants";
 
 interface AppContextValue {
@@ -21,6 +21,8 @@ interface AppContextValue {
   envConfig: EnvConfig;
   /** Column-name normalization map injected by the host (workbook `storedSchemaMap`). */
   schemaMap: SchemaMap;
+  /** Logged-in user's live permissions injected by the host (actionId → permission → granted). */
+  permissions: PermissionsMap;
 }
 
 const AppContext = createContext<AppContextValue | undefined>(undefined);
@@ -73,15 +75,19 @@ export type AppProviderProps = {
   envConfig?: EnvConfig;
   /** Host-injected schema map. Defaults to empty. */
   schemaMap?: SchemaMap;
+  /** Host-injected permissions for the logged-in user. Defaults to empty. */
+  permissions?: PermissionsMap;
 };
 
-/** Stable empty fallback so the context-value memo isn't invalidated every render. */
+/** Stable empty fallbacks so the context-value memo isn't invalidated every render. */
 const EMPTY_SCHEMA_MAP: SchemaMap = {};
+const EMPTY_PERMISSIONS: PermissionsMap = {};
 
-export function AppProvider({ children, envConfig, schemaMap }: AppProviderProps) {
+export function AppProvider({ children, envConfig, schemaMap, permissions }: AppProviderProps) {
   const resolvedEnvConfig = (envConfig ??
     (import.meta.env as unknown as EnvConfig)) as EnvConfig;
   const resolvedSchemaMap = schemaMap ?? EMPTY_SCHEMA_MAP;
+  const resolvedPermissions = permissions ?? EMPTY_PERMISSIONS;
   const [currencyOverride, setCurrencyOverride] = useState<string | null>(null);
 
   const {
@@ -185,6 +191,7 @@ export function AppProvider({ children, envConfig, schemaMap }: AppProviderProps
       setCurrency: setCurrencyOverride,
       envConfig: resolvedEnvConfig,
       schemaMap: resolvedSchemaMap,
+      permissions: resolvedPermissions,
     }),
     [
       userWithDetails,
@@ -202,6 +209,7 @@ export function AppProvider({ children, envConfig, schemaMap }: AppProviderProps
       currentWorkspaceSettings,
       resolvedEnvConfig,
       resolvedSchemaMap,
+      resolvedPermissions,
     ]
   );
 

package/templates/latest/app/hooks/use-permissions.ts

@@ -0,0 +1,41 @@
+import { useMemo } from "react";
+import { useAppContext } from "~/contexts/app-context";
+import type { PermissionsMap } from "~/types";
+
+/**
+ * Access the logged-in user's permissions, injected by the host (PRD-3294).
+ *
+ * The host runs a backend authorization check before mounting this MFE and
+ * passes the result as the `permissions` prop — a map of `actionId → permission
+ * → granted`. Use the returned `can()` helper to gate UI:
+ *
+ * ```tsx
+ * const { can } = usePermissions();
+ * if (can("send_email")) { ... }                 // any permission grants the action
+ * if (can("send_email", "write_with_approval")) { ... } // a specific permission
+ * ```
+ *
+ * `permissions` is `{}` when the app has no permission model configured, so
+ * `can()` returns `false` by default (fail-closed).
+ */
+export function usePermissions() {
+  const { permissions } = useAppContext();
+
+  return useMemo(() => {
+    const can = (actionId: string, permission?: string): boolean => {
+      const actionPerms = permissions[actionId];
+      if (!actionPerms) return false;
+      if (permission) return actionPerms[permission] === true;
+      // No specific permission asked → granted if ANY permission is true.
+      return Object.values(actionPerms).some(Boolean);
+    };
+
+    /** All permissions granted to the user for an action (the `true` keys). */
+    const grantedFor = (actionId: string): string[] =>
+      Object.entries(permissions[actionId] ?? {})
+        .filter(([, granted]) => granted)
+        .map(([permission]) => permission);
+
+    return { permissions: permissions as PermissionsMap, can, grantedFor };
+  }, [permissions]);
+}

package/templates/latest/app/single-spa.tsx

@@ -70,6 +70,8 @@ export async function mount(props: MountProps): Promise<void> {
           // normalize API column names at runtime.
           envVars: props.envVars,
           schemaMap: props.schemaMap,
+          // Logged-in user's permissions (host ran the backend check pre-mount).
+          permissions: props.permissions,
         }}
       />,
     );

package/templates/latest/app/types/index.ts

@@ -2,6 +2,11 @@
  *  Keyed by env-var name → { backendColumn: frontendColumn }. */
 export type SchemaMap = Record<string, Record<string, string>>;
 
+/** Logged-in user's live permissions injected by the host (PRD-3294).
+ *  Keyed by actionId → { permission: granted }. The host computes this with a
+ *  backend check against the app's access-control matrix before mount. */
+export type PermissionsMap = Record<string, Record<string, boolean>>;
+
 /**
  * Runtime environment config. The host injects these via the `envVars` prop
  * (the app's Settings → Env Vars panel, persisted on the workbook). At
@@ -34,6 +39,8 @@ export interface MfeProps {
   envVars?: EnvConfig;
   /** Column-name normalization map injected by the host (workbook `storedSchemaMap`). */
   schemaMap?: SchemaMap;
+  /** Logged-in user's live permissions injected by the host (actionId → permission → granted). */
+  permissions?: PermissionsMap;
 }
 
 /** Normalized user object provided by AppContext. */