@lego-box/shell 1.0.5

package/README.md

@@ -0,0 +1,67 @@
+# @lego-box/shell
+
+Piral microfrontend shell providing authentication, PocketBase integration, RBAC, and shared UI components for the Lego Box ecosystem.
+
+## Installation
+
+```bash
+npm install @lego-box/shell
+# or
+pnpm add @lego-box/shell
+```
+
+## Usage
+
+### Creating a Pilet
+
+```bash
+pilet new @lego-box/shell --target my-pilet
+cd my-pilet
+pnpm install
+pnpm start
+```
+
+### Pilet Development
+
+```typescript
+import type { PiletApi } from '@lego-box/shell/pilet';
+
+export function setup(app: PiletApi) {
+  // Access authentication
+  const user = app.auth.getUser();
+  
+  // Access PocketBase
+  const records = await app.pocketbase.collection('items').getList();
+  
+  // Register protected pages
+  app.registerProtectedPage('/my-route', MyPage, {
+    action: 'read',
+    subject: 'items'
+  });
+  
+  // Register sidebar menu
+  app.registerSidebarMenu({
+    id: 'my-menu',
+    label: 'My Feature',
+    href: '/my-route',
+    action: 'read',
+    subject: 'items'
+  });
+}
+```
+
+## Shared Dependencies
+
+The shell provides these dependencies to all pilets:
+- `@lego-box/ui-kit` - Reusable UI components
+- `pocketbase` - Backend SDK
+- `piral-auth` - Authentication plugin
+- `react` & `react-dom` - UI framework
+
+## API Reference
+
+See [full documentation](link-to-docs) for complete API reference.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@lego-box/shell",
+  "version": "1.0.5",
+  "description": "Piral microfrontend shell for Lego Box - provides authentication, PocketBase integration, RBAC, and shared UI components",
+  "keywords": [
+    "piral",
+    "microfrontend",
+    "shell",
+    "pocketbase",
+    "react",
+    "typescript",
+    "rbac",
+    "authentication"
+  ],
+  "license": "MIT",
+  "author": "Lego Box",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lego-box/lego-box.git"
+  },
+  "homepage": "https://github.com/lego-box/lego-box#readme",
+  "bugs": {
+    "url": "https://github.com/lego-box/lego-box/issues"
+  },
+  "files": [
+    "dist/emulator",
+    "pilet.ts",
+    "src/types.ts",
+    "src/auth/ability.ts",
+    "README.md"
+  ],
+  "main": "dist/emulator/index.js",
+  "types": "pilet.ts",
+  "exports": {
+    ".": {
+      "types": "./pilet.ts",
+      "default": "./dist/emulator/index.js"
+    },
+    "./pilet": {
+      "types": "./pilet.ts",
+      "default": "./pilet.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "app": "./src/index.html",
+  "piral": {
+    "name": "@lego-box/shell",
+    "externals": [
+      "@lego-box/ui-kit",
+      "pocketbase",
+      "piral-auth",
+      "react",
+      "react-dom"
+    ],
+    "sharedDependencies": [
+      "@lego-box/ui-kit",
+      "pocketbase",
+      "piral-auth",
+      "react",
+      "react-dom"
+    ]
+  },
+  "dependencies": {
+    "@casl/ability": "^6.8.0",
+    "@casl/react": "^5.0.1",
+    "clsx": "^2.1.1",
+    "dotenv": "^17.2.3",
+    "framer-motion": "^12.29.2",
+    "lucide-react": "^0.400.0",
+    "piral": "1.9.2",
+    "piral-auth": "^1.5.0",
+    "pocketbase": "^0.21.0",
+    "process": "^0.11.10",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router": "^6.28.1",
+    "react-router-dom": "^6.28.1",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^2.6.0",
+    "tslib": "^2.8.1",
+    "zod": "^3.22.4",
+    "@lego-box/ui-kit": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.30",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "autoprefixer": "^10.4.16",
+    "piral-cli": "1.9.2",
+    "piral-cli-webpack5": "^1.9.2",
+    "piral-core": "^1.9.2",
+    "postcss": "^8.4.32",
+    "postcss-loader": "^8.2.0",
+    "tailwindcss": "^3.4.0",
+    "tailwindcss-animate": "^1.0.7",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "start": "piral debug",
+    "build": "piral build --type emulator-package",
+    "build:all": "piral build --type all",
+    "migrate": "ts-node src/migrations/run-migrations.ts",
+    "migrate:status": "ts-node src/migrations/run-migrations.ts --status",
+    "migrate:rollback": "ts-node src/migrations/run-migrations.ts --rollback",
+    "migrate:clean": "ts-node src/migrations/run-migrations.ts --clean"
+  }
+}

package/pilet.ts

@@ -0,0 +1,33 @@
+/**
+ * Pilet API types for Lego Box shell.
+ * Import these in pilets to get proper typing for the setup context and page props.
+ *
+ * @example
+ * import type { PiletApi, PiletMenuItem, ProtectedPageOptions } from '@lego-box/shell/pilet';
+ *
+ * export function setup(context: PiletApi) {
+ *   context.auth.getId();
+ *   context.registerProtectedPage('/demo', DemoPage, { action: 'read', subject: 'users' });
+ *   context.registerSidebarMenu({ id: 'demo', label: 'Demo', href: '/demo', action: 'read', subject: 'users' });
+ * }
+ *
+ * function DemoPage({ api }: { api: PiletApi }) {
+ *   return <div>{api.auth.getEmail()}</div>;
+ * }
+ */
+
+// Load shell types so PiletCustomApi augmentation is applied
+import type {} from './src/types';
+
+// Re-export PiletApi from Piral (includes our augmented PiletCustomApi)
+export type { PiletApi } from 'piral';
+
+// Re-export shell-specific types for pilets
+export type {
+  PiletMenuItem,
+  AuthUser,
+  ProtectedPageOptions,
+  PiletAuthObject,
+  PiletCaslApi,
+  PermissionString,
+} from './src/types';

package/src/auth/ability.ts

@@ -0,0 +1,91 @@
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from '@casl/ability';
+
+/**
+ * AppAbility - CASL ability type for the application.
+ * Subjects are collection/resource names (e.g., 'users', 'tickets').
+ * Actions are CRUD + custom actions (e.g., 'create', 'read', 'update', 'delete').
+ */
+export type AppAbility = MongoAbility<[string, string]>;
+
+export interface UserWithPermissions {
+  id?: string;
+  is_superuser?: boolean;
+  role?: string;
+}
+
+/**
+ * Parses a permission string in "action:collection" format into { action, subject }.
+ * Handles malformed or empty strings.
+ */
+export function parsePermissionString(
+  permissionName: string
+): { action: string; subject: string } | null {
+  if (!permissionName || typeof permissionName !== 'string') {
+    return null;
+  }
+  const trimmed = permissionName.trim();
+  if (!trimmed) return null;
+
+  const colonIndex = trimmed.indexOf(':');
+  if (colonIndex === -1) return null;
+
+  const action = trimmed.slice(0, colonIndex).trim();
+  const subject = trimmed.slice(colonIndex + 1).trim();
+
+  if (!action || !subject) return null;
+
+  return { action, subject };
+}
+
+/** Permission for CASL rule: action + subject (collection). */
+export interface PermissionDefinition {
+  action: string;
+  subject: string;
+}
+
+/**
+ * Creates a CASL ability instance for the given user and permissions.
+ *
+ * - For superusers: grants all permissions using can('manage', 'all')
+ * - For regular users: iterates through permission definitions and adds
+ *   rules using can(action, subject)
+ * - Accepts permission objects with action/subject or "action:collection" strings
+ * - Handles empty or malformed permissions gracefully
+ */
+export function defineAbilityFor(
+  user: UserWithPermissions | null | undefined,
+  permissions: (PermissionDefinition | string)[] = []
+): AppAbility {
+  const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+  if (!user) {
+    return build();
+  }
+
+  if (user.is_superuser === true) {
+    can('manage', 'all');
+    return build();
+  }
+
+  const permissionArray = Array.isArray(permissions) ? permissions : [];
+  for (const perm of permissionArray) {
+    let action: string;
+    let subject: string;
+    if (typeof perm === 'object' && perm !== null && 'action' in perm && 'subject' in perm) {
+      action = String(perm.action).trim();
+      subject = String(perm.subject).trim();
+    } else {
+      const parsed = parsePermissionString(
+        typeof perm === 'string' ? perm : String(perm)
+      );
+      if (!parsed) continue;
+      action = parsed.action;
+      subject = parsed.subject;
+    }
+    if (action && subject) {
+      can(action, subject);
+    }
+  }
+
+  return build();
+}

package/src/types.ts

@@ -0,0 +1,282 @@
+import type PocketBase from 'pocketbase';
+import type * as React from 'react';
+
+/** Re-export CASL ability type for convenience. */
+export type { AppAbility } from './auth/ability';
+
+/** Result of a permission check. */
+export interface PermissionCheck {
+  action: string;
+  subject: string;
+  allowed: boolean;
+}
+
+/**
+ * Menu item structure for sidebar navigation.
+ * Supports both single items and nested children.
+ * When action and subject are provided, the shell will hide the menu item
+ * if the user does not have the required CASL permission.
+ */
+export interface PiletMenuItem {
+  /** Unique identifier for the menu item */
+  id: string;
+  /** Display label for the menu */
+  label: string;
+  /** Route path to navigate to when clicked */
+  href?: string;
+  /** Optional icon component */
+  icon?: React.ReactNode;
+  /** Child menu items for nested menus */
+  children?: PiletMenuItem[];
+  /** For flat structure: parent menu ID (alternative to nested children) */
+  parent?: string;
+  /** CASL action required to show this menu (e.g. 'read'). When set with subject, menu is hidden if user lacks permission. */
+  action?: string;
+  /** CASL subject required to show this menu (e.g. 'users'). When set with action, menu is hidden if user lacks permission. */
+  subject?: string;
+}
+
+/**
+ * Custom test API extension for demonstration.
+ * Use app.test.getTesting() in pilets to verify plugin connectivity.
+ */
+export interface TestApi {
+  /**
+   * Returns a greeting message to verify the PocketBase plugin is working.
+   */
+  getTesting(): string;
+}
+
+/**
+ * Extended API exposed to all pilets via the PocketBase plugin.
+ *
+ * Usage in pilet:
+ * ```tsx
+ * export function setup(app: PiletContext) {
+ *   const users = await app.pocketbase.collection('users').getList(1, 20);
+ *   const msg = app.test.getTesting();
+ * }
+ * ```
+ */
+export interface PiletPocketBaseApi {
+  /** Full PocketBase SDK instance – use for all PocketBase operations */
+  pocketbase: PocketBase;
+  /** Custom wrapper for testing and common operations */
+  test: TestApi;
+}
+
+/** User representation for auth (PocketBase user or admin). */
+export interface AuthUser {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+}
+
+/** Extended RBAC User with role information. */
+export interface RBACUser extends AuthUser {
+  role: string;
+  roleName?: string;
+  is_superuser: boolean;
+  isActive: boolean;
+  verified?: boolean;
+  permissions: string[];
+  created?: string;
+  updated?: string;
+}
+
+/** Distinguishes regular user vs PocketBase admin. */
+export type UserType = 'user' | 'admin' | null;
+
+/** RBAC Permission action types. */
+export type PermissionAction = 'create' | 'read' | 'update' | 'delete';
+
+/** RBAC Permission definition. */
+export interface Permission {
+  id: string;
+  name: string;
+  action: PermissionAction;
+  collection: string;
+  description?: string;
+  resourceType: 'collection' | 'field' | 'custom';
+  resourceName?: string;
+}
+
+/** RBAC Role definition. */
+export interface Role {
+  id: string;
+  name: string;
+  description?: string;
+  permissions: string[] | Permission[];
+  isDefault?: boolean;
+  permissionCount?: number;
+  userCount?: number;
+  created?: string;
+  updated?: string;
+}
+
+/** Audit log action types. */
+export type AuditLogAction = 'create' | 'update' | 'delete' | 'login' | 'logout';
+
+/** Audit log entry for tracking user actions. */
+export interface AuditLog {
+  id: string;
+  action: AuditLogAction;
+  resource: string;
+  resourceId: string;
+  resourceName: string;
+  userId: string;
+  userName: string;
+  userEmail: string;
+  details?: Record<string, any>;
+  ipAddress?: string;
+  userAgent?: string;
+  timestamp: string;
+  created?: string;
+}
+
+/** Migration tracking entry. */
+export interface Migration {
+  id: string;
+  filename: string;
+  timestamp: number;
+  name: string;
+  status: 'pending' | 'applied' | 'failed' | 'rolled_back';
+  appliedAt: string | null;
+  errorMessage?: string;
+  checksum: string;
+  batch: number;
+}
+
+/** Migration history entry for audit trail. */
+export interface MigrationHistory {
+  id: string;
+  migrationId: string;
+  action: 'apply' | 'rollback' | 'fail';
+  executedAt: string;
+  executedBy: string;
+  errorMessage?: string;
+  duration: number;
+}
+
+/** Ticket category types for support system. */
+export type TicketCategory = 'bug' | 'feature' | 'inquiry';
+
+/** Ticket priority levels. */
+export type TicketPriority = 'low' | 'medium' | 'high';
+
+/** Ticket status types. */
+export type TicketStatus = 'open' | 'in_progress' | 'resolved' | 'closed';
+
+/** Support ticket definition for centralized ticketing system. */
+export interface Ticket {
+  id: string;
+  app_name: string;
+  app_identifier: string;
+  title: string;
+  description: string;
+  category: TicketCategory;
+  priority: TicketPriority;
+  status: TicketStatus;
+  created_by?: string;
+  assigned_to?: string;
+  resolved_at?: string;
+  closed_at?: string;
+  created: string;
+  updated: string;
+}
+
+/** Permission string in "action:subject" format (e.g. "read:users"). */
+export type PermissionString = string;
+
+/**
+ * Auth API exposed to pilets (getUser from piral-auth; login/logout/getUserType from our plugin).
+ */
+export interface PiletAuthApi {
+  getUser(): AuthUser | undefined;
+  getUserId(): string | null;
+  isAuthenticated(): boolean;
+  getUserType(): UserType;
+  login(email: string, password: string): Promise<void>;
+  logout(): void;
+}
+
+/**
+ * Unified auth object exposed to pilets via app.auth.
+ * Provides convenient access to user info, role, permissions, and authorization.
+ */
+export interface PiletAuthObject {
+  /** User ID. */
+  getId(): string | null;
+  /** User email. */
+  getEmail(): string | null;
+  /** User role name (e.g. "Admin"). Returns null if not loaded or no role. */
+  getRole(): string | null;
+  /** All permissions assigned to the user's role (e.g. ["read:users", "create:users"]). */
+  getPermissions(): PermissionString[];
+  /** CASL check: returns true if user can perform action on subject. */
+  can(action: string, subject: string): boolean;
+  getUser(): AuthUser | undefined;
+  isAuthenticated(): boolean;
+  login(email: string, password: string): Promise<void>;
+  logout(): void;
+}
+
+/**
+ * CASL authorization API exposed to pilets via app.casl.
+ * Use for permission checks in pilet components and pages.
+ */
+export interface PiletCaslApi {
+  /** Returns true if the current user can perform the given action on the subject. */
+  can(action: string, subject: string): boolean;
+}
+
+/** Options for registerProtectedPage – route-level permission guard. */
+export interface ProtectedPageOptions {
+  /** CASL action (e.g. "read") */
+  action: string;
+  /** CASL subject (e.g. "users") */
+  subject: string;
+}
+
+/**
+ * Extended API with auth, casl, and protected page registration.
+ */
+export interface PiletAuthCaslApi {
+  auth: PiletAuthObject;
+  casl: PiletCaslApi;
+  /**
+   * Register a page route with permission guard. User must have can(action, subject) to view.
+   * Shows AccessDenied when permission is lacking (same as core ProtectedPage).
+   */
+  registerProtectedPage(
+    route: string,
+    Component: React.ComponentType,
+    options: ProtectedPageOptions
+  ): void;
+}
+
+/**
+ * Menu API exposed to pilets for dynamic sidebar menu registration.
+ * Pilets can register single or multilevel menu items.
+ */
+export interface PiletMenuApi {
+  /**
+   * Register a menu item in the sidebar.
+   * @param menuItem - The menu item to register
+   */
+  registerSidebarMenu(menuItem: PiletMenuItem): void;
+  /**
+   * Unregister a menu item from the sidebar.
+   * @param id - The unique ID of the menu item to remove
+   */
+  unregisterSidebarMenu(id: string): void;
+}
+
+/**
+ * Module augmentation: extends Piral's PiletCustomApi so pilets get
+ * app.pocketbase, app.test, app.auth, app.casl, and menu registration with full TypeScript IntelliSense.
+ */
+declare module 'piral-core/lib/types/custom' {
+  interface PiletCustomApi extends PiletPocketBaseApi, PiletAuthApi, PiletMenuApi, PiletAuthCaslApi {}
+}