create-lego-box 0.1.1 → 0.1.2

package/README.md

@@ -35,8 +35,10 @@ pnpm create lego-box my-awesome-app
   tsconfig.base.json
   .env.example
   scripts/
+    dev-all-pilets.js
     dev-multi-pilet.js
     discover-pilets.js
+    update-scaffold.js
     run-shell.js
   packages/
     ui-kit/         # Extensible – re-exports @lego-box/ui-kit, add custom components here
@@ -56,10 +58,28 @@ pnpm create lego-box my-awesome-app
 1. `cd my-app`
 2. `pnpm install` (if not run automatically)
 3. Start PocketBase: `pb serve` (or your PocketBase setup)
-4. `pnpm dev` – runs shell + ui-kit + pilets
+4. `pnpm dev` – runs shell + ui-kit + all pilets
 5. Add pilets: `pnpm create:pilet`
 6. Extend ui-kit: edit `packages/ui-kit/src/components/`
 
+## Updating your scaffolded app
+
+To get the latest shell, ui-kit, and scaffold template files (README, scripts, configs):
+
+```bash
+pnpm update
+```
+
+Or step by step:
+
+```bash
+pnpm update @lego-box/shell@latest @lego-box/ui-kit@latest
+pnpm update create-lego-box@latest
+pnpm update:scaffold
+```
+
+**Note:** `update:scaffold` pulls latest template files but **does not modify your pilets** or custom components in `packages/ui-kit/src/components/`.
+
 ## Publishing
 
 To publish to npm for `pnpm create lego-box`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lego-box",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Scaffold a new Lego Box microfrontend app with ui-kit and pilets",
   "type": "module",
   "bin": {

package/templates/root/README.md

@@ -2,6 +2,33 @@
 
 This README is written for AI assistants to help developers build microfrontends with Lego Box. Use this as context when implementing features via vibe coding.
 
+## Quick Start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Then open http://localhost:1234. Start PocketBase (`pb serve`) for full functionality.
+
+## Updating Dependencies
+
+To get the latest shell, ui-kit, and scaffold files (scripts, README, root config):
+
+```bash
+pnpm update @lego-box/shell@latest @lego-box/ui-kit@latest
+pnpm update create-lego-box@latest
+pnpm update:scaffold
+```
+
+Or use the combined command:
+
+```bash
+pnpm update
+```
+
+**Note:** `update:scaffold` pulls the latest template files (README, scripts, packages/create-pilet, packages/ui-kit config) but **does not modify your pilets** — you own those. Your custom components in `packages/ui-kit/src/components/` are preserved.
+
 ## Architecture
 
 - **Shell** (@lego-box/shell): Piral microfrontend shell. Provides auth, PocketBase, RBAC, routing.
@@ -45,9 +72,10 @@ context.registerProtectedPage('/my-page', MyPage, { action: 'read', subject: 'us
 ```
 
 ### registerSidebarMenu(menuItem)
-Register a menu item in the sidebar. Menu label = pilet name when scaffolded with create:pilet.
+Register a menu item in the sidebar. Supports single items and multilevel (nested) menus.
 
 ```ts
+// Single menu item
 context.registerSidebarMenu({
   id: 'my-pilet',
   label: 'My Pilet',
@@ -56,19 +84,51 @@ context.registerSidebarMenu({
   subject: 'demo',
   icon: <MyIcon />
 });
+
+// Multilevel menu (parent with children)
+context.registerSidebarMenu({
+  id: 'parent-menu',
+  label: 'Parent Menu',
+  icon: <FolderIcon />,
+  children: [
+    { id: 'child-1', label: 'Child 1', href: '/child-1' },
+    { id: 'child-2', label: 'Child 2', href: '/child-2', action: 'read', subject: 'reports' }
+  ]
+});
 ```
 
-## Permissions
+## Creating Custom UI-Kit Components
 
-Format: `action:collection` (e.g. `read:users`, `create:tickets`). Permissions are assigned to roles. Use `auth.can('read', 'users')` or `casl.can('read', 'users')` to check.
+Your `packages/ui-kit` extends the base UI-Kit from npm. Add your own components:
 
-## Creating Custom UI-Kit Components
+1. **Create** `packages/ui-kit/src/components/my-component.tsx`:
+
+```tsx
+import * as React from 'react';
+import { cn } from '@lego-box/ui-kit-base';
+
+export function MyCustomCard({ className, children }: { className?: string; children?: React.ReactNode }) {
+  return <div className={cn('rounded-lg border p-4', className)}>{children}</div>;
+}
+```
+
+2. **Export** from `packages/ui-kit/src/components/index.ts`:
+
+```ts
+export { MyCustomCard } from './my-component';
+```
+
+3. **Use** in pilets:
+
+```ts
+import { MyCustomCard } from '@lego-box/ui-kit';
+```
+
+Use `cn()` from `@lego-box/ui-kit-base` for className merging. Follow existing component patterns.
 
-1. Create `packages/ui-kit/src/components/my-component.tsx`
-2. Export from `packages/ui-kit/src/index.ts`
-3. Use in pilets: `import { MyComponent } from '@lego-box/ui-kit';`
+## Permissions
 
-Use `cn()` from `../lib/utils` for className merging. Follow existing component patterns.
+Format: `action:collection` (e.g. `read:users`, `create:tickets`). Permissions are assigned to roles. Use `auth.can('read', 'users')` or `casl.can('read', 'users')` to check.
 
 ## Migrations
 
@@ -113,10 +173,13 @@ Copy `.env.example` to `.env`:
 
 ## Commands
 
+- `pnpm install` – Install dependencies
 - `pnpm dev` – Start UI-Kit, shell, all pilets. Migrations run automatically.
 - `pnpm migrate` – Run migrations manually
 - `pnpm create:pilet` – Scaffold new pilet in `pilets/`
 - `pnpm build` – Build ui-kit and shell
+- `pnpm update` – Update shell, ui-kit, and scaffold template files
+- `pnpm update:scaffold` – Pull latest scaffold files (scripts, README, configs) without touching pilets
 
 ## Feeds
 

package/templates/root/package.json

@@ -1 +1 @@
-{"name":"{{APP_NAME}}","version":"1.0.0","private":true,"scripts":{"predev":"node scripts/run-migrations.js","dev":"node scripts/dev-multi-pilet.js","predev:all":"node scripts/run-migrations.js","dev:all":"node scripts/dev-all-pilets.js","dev:discover":"node scripts/discover-pilets.js","create:pilet":"node packages/create-pilet/index.js","build":"pnpm --filter @lego-box/ui-kit build","migrate":"node scripts/run-migrations.js","postinstall":"node scripts/copy-tsconfig-base.js"},"devDependencies":{"@lego-box/shell":"^1.0.0","create-pilet":"workspace:*","concurrently":"^8.2.2","cross-env":"^10.1.0","dotenv":"^17.2.3","ts-node":"^10.9.2"}}
+{"name":"{{APP_NAME}}","version":"1.0.0","private":true,"scripts":{"predev":"node scripts/run-migrations.js","dev":"node scripts/dev-all-pilets.js","predev:all":"node scripts/run-migrations.js","dev:all":"node scripts/dev-all-pilets.js","dev:discover":"node scripts/discover-pilets.js","create:pilet":"node packages/create-pilet/index.js","build":"pnpm --filter @lego-box/ui-kit build","migrate":"node scripts/run-migrations.js","postinstall":"node scripts/copy-tsconfig-base.js","update:scaffold":"node scripts/update-scaffold.js","update":"pnpm update @lego-box/shell@latest @lego-box/ui-kit@latest && pnpm update create-lego-box@latest && pnpm update:scaffold"},"devDependencies":{"@lego-box/shell":"^1.0.0","create-lego-box":"^0.1.1","create-pilet":"workspace:*","concurrently":"^8.2.2","cross-env":"^10.1.0","dotenv":"^17.2.3","ts-node":"^10.9.2"}}

package/templates/scripts/update-scaffold.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * update-scaffold - Pull latest scaffold template files into your project
+ *
+ * Copies templates from node_modules/create-lego-box, EXCLUDING pilets
+ * (you own your pilets). Preserves packages/ui-kit/src/components/
+ * (your custom components).
+ *
+ * Run after: pnpm update create-lego-box@latest
+ * Or as part of: pnpm update
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const CREATE_LEGO_BOX = path.resolve(ROOT_DIR, 'node_modules/create-lego-box');
+const TEMPLATES = path.join(CREATE_LEGO_BOX, 'templates');
+
+if (!fs.existsSync(CREATE_LEGO_BOX) || !fs.existsSync(TEMPLATES)) {
+  console.error('create-lego-box not found. Run: pnpm add -D create-lego-box@latest');
+  process.exit(1);
+}
+
+console.log('Updating scaffold files (preserving pilets and custom components)...\n');
+
+// Paths to exclude: pilets, and packages/ui-kit/src/components (user's custom components)
+function shouldExclude(relPath) {
+  if (relPath.startsWith('pilets' + path.sep) || relPath === 'pilets') return true;
+  if (relPath.includes('packages' + path.sep + 'ui-kit' + path.sep + 'src' + path.sep + 'components')) return true;
+  return false;
+}
+
+function copyRecursive(src, dest, base = '') {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (shouldExclude(rel)) continue;
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath, rel);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Copy root files (preserve app name in package.json)
+const rootFiles = ['package.json', 'pnpm-workspace.yaml', 'tsconfig.base.json', 'env.example', 'README.md'];
+for (const file of rootFiles) {
+  const srcPath = path.join(TEMPLATES, 'root', file);
+  if (fs.existsSync(srcPath)) {
+    const destPath = path.join(ROOT_DIR, file === 'env.example' ? '.env.example' : file);
+    if (file === 'package.json') {
+      // Preserve user's app name and merge devDependencies (template base + user extras)
+      const current = JSON.parse(fs.readFileSync(destPath, 'utf-8'));
+      const template = JSON.parse(fs.readFileSync(srcPath, 'utf-8'));
+      const merged = {
+        ...template,
+        name: current.name,
+        devDependencies: { ...template.devDependencies, ...current.devDependencies },
+      };
+      fs.writeFileSync(destPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+    console.log('  Updated:', (destPath.replace(ROOT_DIR, '') || file).replace(/^\/+/, ''));
+  }
+}
+
+// Copy scripts
+const scriptsSrc = path.join(TEMPLATES, 'scripts');
+const scriptsDest = path.join(ROOT_DIR, 'scripts');
+if (fs.existsSync(scriptsSrc)) {
+  fs.mkdirSync(scriptsDest, { recursive: true });
+  const files = fs.readdirSync(scriptsSrc);
+  for (const file of files) {
+    fs.copyFileSync(path.join(scriptsSrc, file), path.join(scriptsDest, file));
+    console.log('  Updated: scripts/' + file);
+  }
+}
+
+// Copy packages/create-pilet
+const createPiletSrc = path.join(TEMPLATES, 'packages', 'create-pilet');
+const createPiletDest = path.join(ROOT_DIR, 'packages', 'create-pilet');
+if (fs.existsSync(createPiletSrc)) {
+  fs.rmSync(createPiletDest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(createPiletDest), { recursive: true });
+  copyRecursive(createPiletSrc, createPiletDest, 'packages/create-pilet');
+  console.log('  Updated: packages/create-pilet');
+}
+
+// Copy packages/ui-kit (excluding src/components)
+const uiKitSrc = path.join(TEMPLATES, 'packages', 'ui-kit');
+const uiKitDest = path.join(ROOT_DIR, 'packages', 'ui-kit');
+if (fs.existsSync(uiKitSrc)) {
+  const uiKitComponentsDest = path.join(uiKitDest, 'src', 'components');
+  const preserveComponents = fs.existsSync(uiKitComponentsDest);
+  if (preserveComponents) {
+    const componentsBackup = path.join(ROOT_DIR, '.tmp-ui-kit-components');
+    fs.rmSync(componentsBackup, { recursive: true, force: true });
+    fs.cpSync(uiKitComponentsDest, componentsBackup, { recursive: true });
+  }
+  fs.rmSync(uiKitDest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(uiKitDest), { recursive: true });
+  copyRecursive(uiKitSrc, uiKitDest, 'packages/ui-kit');
+  if (preserveComponents) {
+    const componentsBackup = path.join(ROOT_DIR, '.tmp-ui-kit-components');
+    fs.rmSync(path.join(uiKitDest, 'src', 'components'), { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(path.join(uiKitDest, 'src', 'components')), { recursive: true });
+    fs.cpSync(componentsBackup, path.join(uiKitDest, 'src', 'components'), { recursive: true });
+    fs.rmSync(componentsBackup, { recursive: true, force: true });
+    console.log('  Updated: packages/ui-kit (preserved your custom components)');
+  } else {
+    console.log('  Updated: packages/ui-kit');
+  }
+}
+
+// Copy migrations
+const migrationsSrc = path.join(TEMPLATES, 'migrations');
+const migrationsDest = path.join(ROOT_DIR, 'migrations');
+if (fs.existsSync(migrationsSrc)) {
+  fs.mkdirSync(migrationsDest, { recursive: true });
+  const files = fs.readdirSync(migrationsSrc);
+  for (const file of files) {
+    fs.copyFileSync(path.join(migrationsSrc, file), path.join(migrationsDest, file));
+  }
+  console.log('  Updated: migrations/');
+}
+
+console.log('\nScaffold updated. Run pnpm install if package.json changed.');
+console.log('Your pilets were not modified.');