create-lego-box 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# create-lego-box
+
+Scaffolds a new Lego Box microfrontend app with ui-kit, pilets, and shell from npm.
+
+## Usage
+
+### From npm (recommended for external developers)
+
+```bash
+pnpm create lego-box
+# or
+npm create lego-box
+```
+
+### From monorepo (local development)
+
+```bash
+pnpm create:app
+# or
+node packages/create-lego-box/index.js
+```
+
+### With app name
+
+```bash
+pnpm create lego-box my-awesome-app
+```
+
+## What it creates
+
+```
+/my-app
+  package.json
+  pnpm-workspace.yaml
+  tsconfig.base.json
+  .env.example
+  scripts/
+    dev-multi-pilet.js
+    discover-pilets.js
+    run-shell.js
+  packages/
+    ui-kit/         # Extensible – re-exports @lego-box/ui-kit, add custom components here
+    create-pilet/   # CLI to scaffold new pilets
+  pilets/
+    my-pilet/       # Initial pilet
+```
+
+## Architecture
+
+- **Shell**: `@lego-box/shell` from npm (maintained by Lego Box team)
+- **ui-kit**: Local workspace package – extends `@lego-box/ui-kit`, add your components
+- **Pilets**: Create with `pnpm create:pilet` – auto-saved to `pilets/`
+
+## Next steps after creation
+
+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
+5. Add pilets: `pnpm create:pilet`
+6. Extend ui-kit: edit `packages/ui-kit/src/components/`
+
+## Publishing
+
+To publish to npm for `pnpm create lego-box`:
+
+1. Add to changesets
+2. Publish as `create-lego-box` (unscoped) or `@lego-box/create` (scoped)
+
+The `create-*` convention: `pnpm create foo` runs the `create-foo` package.

package/index.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import prompts from 'prompts';
+import chalk from 'chalk';
+import fse from 'fs-extra';
+import { execSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, 'templates');
+
+function isValidAppName(name) {
+  if (!name || typeof name !== 'string') return false;
+  const sanitized = name.toLowerCase().replace(/\s+/g, '-');
+  return /^[a-z0-9][a-z0-9._-]*$/.test(sanitized);
+}
+
+function sanitizeAppName(name) {
+  return name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9._-]/g, '');
+}
+
+function getAllFiles(dir, base = '') {
+  const entries = fs.readdirSync(path.join(dir, base), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      files.push(...getAllFiles(dir, rel));
+    } else {
+      files.push(rel);
+    }
+  }
+  return files;
+}
+
+function processContent(content, variables) {
+  let result = content;
+  for (const [key, value] of Object.entries(variables)) {
+    if (value !== undefined && value !== null) {
+      result = result.replace(new RegExp(`{{${key}}}`, 'g'), String(value));
+    }
+  }
+  return result;
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('-'));
+  const appNameArg = args[0];
+  const suggestedName = appNameArg ? sanitizeAppName(appNameArg) : 'my-app';
+  const isNonInteractive = process.argv.includes('--yes') || process.argv.includes('-y');
+
+  console.log(chalk.cyan('\n create-lego-box – Scaffold a new Lego Box microfrontend app\n'));
+  console.log(chalk.gray('Creates: app structure with ui-kit, pilets, and shell from npm.\n'));
+
+  const response = isNonInteractive
+    ? { appName: suggestedName, runInstall: !process.argv.includes('--no-install') }
+    : await prompts([
+    {
+      type: 'text',
+      name: 'appName',
+      message: 'App name:',
+      initial: suggestedName,
+      validate: (v) => (isValidAppName(v || suggestedName) ? true : 'Use lowercase, no spaces (e.g. my-app)'),
+    },
+    {
+      type: 'confirm',
+      name: 'runInstall',
+      message: 'Run pnpm install after creating the app?',
+      initial: true,
+    },
+  ]);
+
+  if (Object.keys(response).length === 0) {
+    console.log(chalk.yellow('Cancelled.'));
+    process.exit(0);
+  }
+
+  const appName = sanitizeAppName(response.appName || suggestedName) || 'my-app';
+  const runInstall = response.runInstall ?? true;
+
+  const targetDir = path.resolve(process.cwd(), appName);
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    const { overwrite } = await prompts({
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Directory ${targetDir} already exists. Overwrite?`,
+      initial: false,
+    });
+    if (!overwrite) {
+      console.log(chalk.yellow('Cancelled.'));
+      process.exit(0);
+    }
+    fse.removeSync(targetDir);
+  }
+
+  const variables = { APP_NAME: appName };
+
+  console.log(chalk.gray(`Creating app at ${targetDir}...`));
+
+  // Root files
+  const rootFiles = ['package.json', 'pnpm-workspace.yaml', 'tsconfig.base.json', 'env.example'];
+  for (const file of rootFiles) {
+    const srcPath = path.join(TEMPLATES_DIR, 'root', file);
+    if (!fs.existsSync(srcPath)) continue;
+    const destPath = path.join(targetDir, file === 'env.example' ? '.env.example' : file);
+    fse.ensureDirSync(path.dirname(destPath));
+    let content = fs.readFileSync(srcPath, 'utf-8');
+    content = processContent(content, variables);
+    fs.writeFileSync(destPath, content, 'utf-8');
+  }
+
+  // Scripts
+  const scriptsDir = path.join(TEMPLATES_DIR, 'scripts');
+  const scriptFiles = fs.readdirSync(scriptsDir);
+  const scriptsDest = path.join(targetDir, 'scripts');
+  fse.ensureDirSync(scriptsDest);
+  for (const file of scriptFiles) {
+    const content = fs.readFileSync(path.join(scriptsDir, file), 'utf-8');
+    fs.writeFileSync(path.join(scriptsDest, file), content, 'utf-8');
+  }
+
+  // packages/ui-kit
+  const uiKitSrc = path.join(TEMPLATES_DIR, 'packages', 'ui-kit');
+  const uiKitDest = path.join(targetDir, 'packages', 'ui-kit');
+  fse.copySync(uiKitSrc, uiKitDest);
+
+  // packages/create-pilet
+  const createPiletSrc = path.join(TEMPLATES_DIR, 'packages', 'create-pilet');
+  const createPiletDest = path.join(targetDir, 'packages', 'create-pilet');
+  fse.copySync(createPiletSrc, createPiletDest);
+
+  // pilets/my-pilet
+  const piletSrc = path.join(TEMPLATES_DIR, 'pilets', 'my-pilet');
+  const piletDest = path.join(targetDir, 'pilets', 'my-pilet');
+  fse.copySync(piletSrc, piletDest);
+
+  if (runInstall) {
+    console.log(chalk.gray('Running pnpm install...'));
+    try {
+      execSync('pnpm install', {
+        cwd: targetDir,
+        stdio: 'inherit',
+      });
+    } catch (err) {
+      console.warn(chalk.yellow('pnpm install failed. Run it manually from the app directory.'));
+    }
+  }
+
+  console.log(chalk.green('\n App created successfully!\n'));
+  console.log(chalk.white('Next steps:'));
+  console.log(chalk.cyan(`  cd ${appName}`));
+  if (!runInstall) {
+    console.log(chalk.cyan('  pnpm install'));
+  }
+  console.log(chalk.cyan('  pnpm dev'));
+  console.log(chalk.gray('\nStart PocketBase (e.g. pb serve) for full functionality.'));
+  console.log(chalk.gray('Add pilets with: pnpm create:pilet'));
+  console.log(chalk.gray('Extend ui-kit in packages/ui-kit/src/components/'));
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error(chalk.red('Error:'), err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-lego-box",
+  "version": "0.1.0",
+  "description": "Scaffold a new Lego Box microfrontend app with ui-kit and pilets",
+  "type": "module",
+  "bin": {
+    "create-lego-box": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "keywords": [
+    "lego-box",
+    "piral",
+    "microfrontend",
+    "scaffold",
+    "create"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lego-box/lego-box.git",
+    "directory": "packages/create-lego-box"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
+  }
+}

package/templates/packages/create-pilet/index.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import prompts from 'prompts';
+import chalk from 'chalk';
+import fse from 'fs-extra';
+import { execSync } from 'child_process';
+import { getTemplateFiles, generateFileContent } from './templates.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ROOT = path.resolve(__dirname, '../..');
+const PILETS_DIR = path.join(WORKSPACE_ROOT, 'pilets');
+
+function isValidPiletName(name) {
+  if (!name || typeof name !== 'string') return false;
+  const sanitized = name.toLowerCase().replace(/\s+/g, '-');
+  return /^[a-z0-9][a-z0-9._-]*$/.test(sanitized);
+}
+
+function sanitizePiletName(name) {
+  return name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9._-]/g, '');
+}
+
+function getNextAvailablePort() {
+  if (!fs.existsSync(PILETS_DIR)) return 9000;
+  const entries = fs.readdirSync(PILETS_DIR, { withFileTypes: true });
+  const usedPorts = new Set([9000]);
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const krasrcPath = path.join(PILETS_DIR, entry.name, '.krasrc');
+      if (fs.existsSync(krasrcPath)) {
+        try {
+          const krasrc = JSON.parse(fs.readFileSync(krasrcPath, 'utf-8'));
+          const url = krasrc?.injectors?.pilet?.assetUrl || '';
+          const match = url.match(/localhost:(\d+)/);
+          if (match) usedPorts.add(parseInt(match[1], 10));
+        } catch (_) {}
+      }
+    }
+  }
+
+  let port = 9000;
+  while (usedPorts.has(port)) port++;
+  return port;
+}
+
+function getShellDep() {
+  const shellPath = path.join(WORKSPACE_ROOT, 'packages', 'app-shell', 'package.json');
+  return fs.existsSync(shellPath) ? 'workspace:*' : '^1.0.0';
+}
+
+function getUiKitDep() {
+  const uiKitPath = path.join(WORKSPACE_ROOT, 'packages', 'ui-kit', 'package.json');
+  return fs.existsSync(uiKitPath) ? 'workspace:*' : '^0.1.0';
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const targetDirArg = args[0];
+  const defaultName = targetDirArg ? path.basename(path.resolve(targetDirArg)) : 'my-pilet';
+  const suggestedName = sanitizePiletName(defaultName) || 'my-pilet';
+  const nextPort = getNextAvailablePort();
+
+  console.log(chalk.cyan('\n create-pilet – Scaffold a new Piral pilet\n'));
+
+  const response = await prompts([
+    {
+      type: 'text',
+      name: 'piletName',
+      message: 'Pilet name (package name):',
+      initial: suggestedName,
+      validate: (v) => (isValidPiletName(v || suggestedName) ? true : 'Use lowercase, no spaces (e.g. my-pilet)'),
+    },
+    {
+      type: 'text',
+      name: 'description',
+      message: 'Description:',
+      initial: '',
+    },
+    {
+      type: 'text',
+      name: 'author',
+      message: 'Author:',
+      initial: '',
+    },
+    {
+      type: 'select',
+      name: 'mode',
+      message: 'Package mode:',
+      choices: [
+        { title: 'Workspace (monorepo development, workspace:* deps)', value: 'workspace' },
+        { title: 'Published (external use, versioned deps)', value: 'published' },
+      ],
+      initial: 0,
+    },
+    {
+      type: 'number',
+      name: 'port',
+      message: 'Development port:',
+      initial: nextPort,
+      min: 1024,
+      max: 65535,
+    },
+    {
+      type: 'confirm',
+      name: 'runInstall',
+      message: 'Run pnpm install after creating the pilet?',
+      initial: true,
+    },
+  ]);
+
+  if (Object.keys(response).length === 0) {
+    console.log(chalk.yellow('Cancelled.'));
+    process.exit(0);
+  }
+
+  const piletName = sanitizePiletName(response.piletName || suggestedName) || 'my-pilet';
+  const description = response.description || '';
+  const author = response.author || '';
+  const mode = response.mode || 'workspace';
+  const port = response.port ?? nextPort;
+  const runInstall = response.runInstall ?? true;
+
+  const isMonorepo = fs.existsSync(path.join(WORKSPACE_ROOT, 'pnpm-workspace.yaml'));
+  const targetDir = isMonorepo
+    ? path.join(PILETS_DIR, piletName)
+    : targetDirArg
+      ? path.resolve(process.cwd(), targetDirArg)
+      : path.resolve(process.cwd(), piletName);
+
+  const shellDep = mode === 'workspace' ? getShellDep() : '^1.0.0';
+  const uiKitDep = mode === 'workspace' ? getUiKitDep() : '^0.1.0';
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    const { overwrite } = await prompts({
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Directory ${targetDir} already exists. Overwrite?`,
+      initial: false,
+    });
+    if (!overwrite) {
+      console.log(chalk.yellow('Cancelled.'));
+      process.exit(0);
+    }
+    fse.removeSync(targetDir);
+  }
+
+  const variables = {
+    PILET_NAME: piletName,
+    DESCRIPTION: description,
+    AUTHOR: author,
+    PORT: port,
+    SHELL_DEPENDENCY: shellDep,
+    UI_KIT_DEPENDENCY: uiKitDep,
+  };
+
+  console.log(chalk.gray(`Creating pilet at ${targetDir}...`));
+
+  fse.ensureDirSync(path.join(targetDir, 'src', 'pages'));
+
+  const templateFiles = getTemplateFiles();
+  for (const templatePath of templateFiles) {
+    const content = generateFileContent(templatePath, variables, mode);
+    const destPath = path.join(targetDir, templatePath);
+    fse.ensureDirSync(path.dirname(destPath));
+    fs.writeFileSync(destPath, content, 'utf-8');
+  }
+
+  if (runInstall) {
+    console.log(chalk.gray('Running pnpm install...'));
+    try {
+      execSync('pnpm install', {
+        cwd: isMonorepo ? WORKSPACE_ROOT : targetDir,
+        stdio: 'inherit',
+      });
+    } catch (err) {
+      console.warn(chalk.yellow('pnpm install failed. Run it manually.'));
+    }
+  }
+
+  console.log(chalk.green('\n Pilet created successfully!\n'));
+  console.log(chalk.white('Next steps:'));
+  console.log(chalk.cyan(`  cd ${path.relative(process.cwd(), targetDir) || targetDir}`));
+  if (isMonorepo) {
+    console.log(chalk.cyan('  pnpm dev'));
+    console.log(chalk.gray('\nRun from app root to start shell + pilets.'));
+  } else {
+    console.log(chalk.cyan('  pnpm start'));
+    console.log(chalk.gray('\nConfigure the feed URL in your shell to point to this pilet.'));
+  }
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error(chalk.red('Error:'), err.message);
+  process.exit(1);
+});

package/templates/packages/create-pilet/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "create-pilet",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "create-pilet": "./index.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
+  }
+}

package/templates/packages/create-pilet/templates/.krasrc

@@ -0,0 +1 @@
+{"injectors":{"pilet":{"assetUrl":"http://localhost:9000"}}}

package/templates/packages/create-pilet/templates/package.json

@@ -0,0 +1 @@
+{"name":"pilet-demo","version":"1.0.0","private":true,"piral":{"name":"@lego-box/shell","importmap":{"inherit":["@lego-box/shell"]},"sharedDependencies":["@lego-box/ui-kit","piral","pocketbase","react","react-dom"]},"peerDependencies":{"react":"^18.2.0","react-dom":"^18.2.0"},"devDependencies":{"@lego-box/shell":"workspace:*","@lego-box/ui-kit":"workspace:*","@types/react":"^18.2.0","@types/react-dom":"^18.2.0","piral":"1.9.2","piral-cli":"1.9.2","piral-cli-webpack5":"^1.9.2","strip-ansi":"^6.0.1","react":"^18.2.0","react-dom":"^18.2.0","tailwindcss":"^3.4.0","typescript":"^5.3.3"},"scripts":{"start":"pilet debug","build":"pilet build"}}

package/templates/packages/create-pilet/templates/src/index.tsx

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import type { PiletApi } from '@lego-box/shell/pilet';
+import { HomePage } from './pages/home';
+import { DemoPage } from './pages/demo';
+import { Test1Page } from './pages/Test1Page';
+import { Test2Page } from './pages/Test2Page';
+
+/**
+ * Pilet demonstrating extended API, UI Kit, and dynamic menu registration.
+ * Shows getUser, getUserId, getUserType, test.getTesting(), and sidebar menu registration.
+ */
+export function setup(context: PiletApi) {
+  console.log('PocketBase plugin test:', context.test.getTesting());
+
+  // Register demo page with route-level permission guard (read:users)
+  context.registerProtectedPage(
+    '/demo',
+    () => <DemoPage api={context} />,
+    { action: 'read', subject: 'demo' }
+  );
+
+  // Register test pages with route-level permission guards (read:audit_logs)
+  context.registerProtectedPage('/testing/test1', () => <Test1Page />, {
+    action: 'read',
+    subject: 'demo',
+  });
+  context.registerProtectedPage('/testing/test2', () => <Test2Page />, {
+    action: 'read',
+    subject: 'demo',
+  });
+  // Register a single-level menu item with permission guard (read:users)
+  context.registerSidebarMenu({
+    id: 'pilet-demo',
+    label: 'Pilet Demo',
+    href: '/demo',
+    action: 'read',
+    subject: 'demo',
+    icon: (
+      <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
+      </svg>
+    ),
+  });
+
+  // Register a multilevel menu with permission guards (children require read:audit_logs)
+  context.registerSidebarMenu({
+    id: 'testing-menu',
+    label: 'Testing',
+    action: 'read',
+    subject: 'demo',
+    icon: (
+      <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19.428 15.428a2 2 0 00-1.022-.547l-2.387-.477a6 6 0 00-3.86.517l-.318.158a6 6 0 01-3.86.517L6.05 15.21a2 2 0 00-1.806.547M8 4h8l-1 1v5.172a2 2 0 00.586 1.414l5 5c1.26 1.26.367 3.414-1.415 3.414H4.828c-1.782 0-2.674-2.154-1.414-3.414l5-5A2 2 0 009 10.172V5L8 4z" />
+      </svg>
+    ),
+    children: [
+      {
+        id: 'test-1',
+        label: 'Test 1',
+        href: '/testing/test1',
+        action: 'read',
+        subject: 'demo',
+        icon: (
+          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+        ),
+      },
+      {
+        id: 'test-2',
+        label: 'Test 2',
+        href: '/testing/test2',
+        action: 'read',
+        subject: 'demo',
+        icon: (
+          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+        ),
+      },
+    ],
+  });
+
+  console.log('[pilet-demo] Registered pages and sidebar menus');
+}

package/templates/packages/create-pilet/templates/src/pages/Test1Page.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { Card } from '@lego-box/ui-kit';
+
+/**
+ * Test1Page - Sample page for "Test 1" menu item
+ * Demonstrates pilet-registered menu with working navigation
+ */
+export function Test1Page() {
+  return (
+    <Card title="Test 1 Page">
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Hello from Test 1 menu!</h1>
+        <p className="text-muted-foreground">
+          This page is registered by the pilet-demo pilet and accessible via the sidebar menu.
+        </p>
+        <p className="mt-4 text-muted-foreground">
+          The menu item was dynamically registered using{' '}
+          <code className="bg-muted px-2 py-1 rounded text-sm">context.registerSidebarMenu()</code>.
+        </p>
+      </div>
+    </Card>
+  );
+}

package/templates/packages/create-pilet/templates/src/pages/Test2Page.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { Card } from '@lego-box/ui-kit';
+
+/**
+ * Test2Page - Sample page for "Test 2" menu item
+ * Demonstrates pilet-registered menu with working navigation
+ */
+export function Test2Page() {
+  return (
+    <Card title="Test 2 Page">
+      <div className="p-6">
+        <h1 className="text-2xl font-bold mb-4">Hello from Test 2 menu!</h1>
+        <p className="text-muted-foreground">
+          This is another sample page registered by pilet-demo via the dynamic menu system.
+        </p>
+        <p className="mt-4 text-muted-foreground">
+          This page is part of a multilevel menu structure under "Testing" menu.
+        </p>
+      </div>
+    </Card>
+  );
+}