@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/platform-cli/overview.mdx

@@ -0,0 +1,195 @@
+---
+title: Platform CLI Overview
+description: Introduction to the Blue Alba Platform CLI — how to install it, use the interactive command palette, and run commands in headless mode
+---
+
+import { Steps, Aside, Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The `@bluealba/platform-cli` (invoked as `platform`) is the official scaffolding and management tool for the Blue Alba Platform. It handles the complete lifecycle of a platform environment: initializing a new product repository structure, adding applications and modules, configuring identity providers, managing local development environments, and checking platform health.
+
+The CLI ships in two modes that can be freely combined:
+
+- **Interactive mode** — a terminal UI built with [Ink](https://github.com/vadimdemedes/ink) and a fuzzy-searchable command palette. No arguments needed; the CLI guides you through every step with prompts.
+- **Headless mode** — a non-interactive path where all inputs are supplied as `key=value` arguments on the command line. Suitable for CI pipelines, scripts, and AI agent automation.
+
+---
+
+## Installation
+
+<Tabs>
+  <TabItem label="Global install (recommended)">
+    Install the CLI globally so the `platform` command is available anywhere on your system:
+
+    ```bash
+    npm install -g @bluealba/platform-cli
+    ```
+
+    Verify the installation:
+
+    ```bash
+    platform --version
+    ```
+  </TabItem>
+
+  <TabItem label="From monorepo source">
+    If you are working inside the Blue Alba Platform monorepo you can build and install the CLI from source with a single command from the repository root:
+
+    ```bash
+    npm run cli:install-local
+    ```
+
+    This builds the CLI with `tsup`, packs it into a `.tgz`, installs it globally, and removes the tarball. After it completes the `platform` command reflects your latest local changes.
+  </TabItem>
+</Tabs>
+
+### Prerequisites
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js | >= 22 |
+| npm | >= 10 |
+| Docker | Any recent version with the Compose plugin (required for local environment commands) |
+
+<Aside type="tip">
+  The CLI requires a real TTY for interactive mode. If you are running inside a script or CI pipeline, always supply all arguments on the command line (headless mode).
+</Aside>
+
+---
+
+## Interactive Mode
+
+Running `platform` with no arguments launches the interactive terminal UI.
+
+```bash
+platform
+```
+
+You are presented with a status banner and a blinking cursor. The interface is intentionally minimal — most of the time you will open the command palette to do something.
+
+### The Command Palette
+
+Press `/` at any time to open the command palette. Start typing to fuzzy-search across all available commands by name or description.
+
+```
+> /init
+```
+
+Use the arrow keys to move through results and press `Enter` to run the highlighted command.
+
+<Aside type="note" title="Context-aware visibility">
+  Commands that require a platform to be initialized (such as `create-application`, `install`, `build`, `start`, `stop`, `destroy`, `status`, and `manage-platform-admins`) are hidden from the palette until `init` has been run in the current directory. This prevents accidentally running lifecycle commands against the wrong directory.
+</Aside>
+
+### Interactive Prompt Types
+
+Depending on the command, the CLI may present:
+
+| Prompt type | Behaviour |
+|-------------|-----------|
+| Text input | Free-form text; press `Enter` to confirm |
+| Confirm (`y/n`) | Yes/No question; the default is shown in brackets |
+| Single-select list | Arrow keys to navigate, `Enter` to select |
+| Multi-select list | Arrow keys to navigate, `Space` to toggle, `Enter` to confirm |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `/` | Open command palette |
+| `Arrow Up / Down` | Navigate palette or select lists |
+| `Enter` | Confirm selection or submit input |
+| `Escape` | Abort the running command and return to the idle state |
+| `Ctrl+C` | Exit the CLI |
+
+---
+
+## Headless Mode
+
+Supply the command name as the first argument followed by any required inputs as `key=value` pairs:
+
+```bash
+platform <command> key1=value1 key2=value2
+```
+
+All key-value pairs are positional after the command name and can appear in any order.
+
+### Example
+
+```bash
+platform init \
+  organizationName=acme \
+  platformName=my-platform \
+  platformDisplayName="My Platform"
+```
+
+If a required argument is missing the CLI prints an error message and exits with a non-zero code, making it safe to use in scripts that check exit codes.
+
+### Boolean Arguments
+
+Boolean flags use the string values `"yes"` and `"no"`:
+
+```bash
+platform create-application \
+  applicationName=billing \
+  applicationDisplayName="Billing" \
+  applicationDescription="Invoice and payment management" \
+  hasUserInterface=yes \
+  hasBackendService=yes
+```
+
+### Comma-separated Lists
+
+Some commands accept multiple values as a comma-separated string:
+
+```bash
+platform manage-platform-admins action=add usernames=alice,bob,carol
+```
+
+---
+
+## Platform Lifecycle
+
+The CLI models a four-stage lifecycle for every platform environment:
+
+```
+init → install → build → start
+```
+
+| Stage | What it does | CLI command |
+|-------|-------------|-------------|
+| **init** | Scaffolds the core directory structure, product manifest, bootstrap service, and customization UI | `platform init` |
+| **install** | Runs `npm install` across the platform and all registered applications | `platform install` |
+| **build** | Compiles TypeScript and builds Docker images via Turborepo | `platform build` |
+| **start** | Brings up the full local environment with Docker Compose | `platform start` |
+
+The `status` command checks where you are in this lifecycle and offers to run the next required step automatically.
+
+---
+
+## Working Directory Convention
+
+The CLI determines the platform root by looking for a `*-core/` directory in the current working directory or its parents. This directory contains the product manifest (`product.manifest.json`) and the `local/` subdirectory with Docker Compose files.
+
+Run all CLI commands from the root of your product repository (the directory that contains the `*-core/` folder):
+
+```
+my-product/
+├── my-product-core/          ← The CLI looks for this directory
+│   ├── product.manifest.json
+│   ├── local/
+│   │   ├── .env
+│   │   └── *.yml
+│   └── services/
+│       └── ...
+└── my-application/
+    └── ...
+```
+
+---
+
+## Next Steps
+
+- [Command Reference](./commands/) — Complete documentation for every command
+- [Quick Start Guide](../getting-started/quick-start/) — Get the platform running for the first time
+- [Creating Services Guide](../guides/creating-services/) — Add a backend service to your platform
+- [Creating UI Modules Guide](../guides/creating-ui-modules/) — Add a React micro-frontend module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/platform-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Blue Alba Platform CLI",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",
@@ -9,9 +9,12 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "docs",
+    "skills"
   ],
   "scripts": {
+    "prebuild": "node scripts/copy-docs.mjs",
     "build": "tsup",
     "dev": "tsup --watch",
     "start": "node dist/index.js",

package/skills/ba-platform/platform-cli.skill.md

@@ -0,0 +1,26 @@
+# Blue Alba Platform CLI — Expert Knowledge
+
+You are an expert on the Blue Alba Platform CLI (`@bluealba/platform-cli`, command: `platform`). Use the documentation files referenced below to answer questions accurately.
+
+## Documentation
+
+Read these files for comprehensive CLI knowledge:
+
+- `{{docsPath}}/platform-cli/overview.mdx` — What the CLI is, installation, interactive mode (command palette), headless mode, platform lifecycle
+- `{{docsPath}}/platform-cli/commands.mdx` — Complete reference for all commands: init, configure-idp, create-application, create-service-module, create-ui-module, status, manage-platform-admins, install-ai-plugin, install, build, start, stop, destroy
+
+## When to Use This Knowledge
+
+- When the user asks how to use the platform CLI
+- When guiding users through scaffolding, configuration, or environment management
+- When explaining what a specific CLI command does or what parameters it accepts
+- When helping users troubleshoot CLI errors
+
+## Instructions
+
+1. Always read both documentation files above before answering CLI-specific questions
+2. Provide concrete command examples with the correct parameter syntax
+3. Explain side effects and what files or infrastructure a command creates
+4. When a user's goal can be achieved with a CLI command, prefer the CLI over manual steps
+5. For interactive mode: the command palette is opened with `/` inside the TUI
+6. For headless mode: args are passed as `key=value` pairs (e.g. `platform create-application applicationName=my-app`)

package/skills/ba-platform/platform.skill.md

@@ -0,0 +1,35 @@
+# Blue Alba Platform — Expert Knowledge
+
+You are an expert on the Blue Alba Platform monorepo. Use the documentation files referenced below to answer questions accurately.
+
+## Documentation
+
+Read these files for comprehensive platform knowledge:
+
+- `{{docsPath}}/getting-started/overview.mdx` — Platform overview and core concepts
+- `{{docsPath}}/getting-started/core-concepts.mdx` — Core concepts explained in depth
+- `{{docsPath}}/getting-started/installation.mdx` — Installation and local setup
+- `{{docsPath}}/architecture/overview.mdx` — Architecture overview and system components
+- `{{docsPath}}/architecture/gateway-architecture.mdx` — NestJS Gateway Service architecture
+- `{{docsPath}}/architecture/authentication-system.mdx` — JWT, OAuth 2.0, API keys, impersonation
+- `{{docsPath}}/architecture/authorization-system.mdx` — RBAC model, operations, roles, rules
+- `{{docsPath}}/architecture/multi-tenancy.mdx` — Tenant isolation and context
+- `{{docsPath}}/architecture/shell.mdx` — Shell UI architecture and extension points
+- `{{docsPath}}/architecture/scheduler.mdx` — Job scheduling system
+- `{{docsPath}}/development/workflow.mdx` — Development workflow, git branching, changesets, testing
+- `{{docsPath}}/platform-cli/overview.mdx` — Platform CLI tool: installation, interactive mode, headless mode
+- `{{docsPath}}/platform-cli/commands.mdx` — All CLI commands reference
+
+## When to Use This Knowledge
+
+- When the user asks about the platform's architecture, services, or conventions
+- When explaining how the gateway, microservices, or UI applications work
+- When guiding development decisions that must align with platform patterns
+- When reviewing code against platform conventions
+
+## Instructions
+
+1. Always read the relevant documentation files above before answering platform-specific questions
+2. Reference specific sections from the docs when explaining concepts
+3. Follow the conventions and patterns described in the architecture documentation
+4. When uncertain, prefer the documented approach over assumptions

package/templates/application-monorepo-template/gitignore

@@ -0,0 +1,95 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+# .env
+
+# next.js build output
+.next
+dist
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.DS_Store
+
+# Monorepo directories
+core/*/node_modules
+core/*/dist
+services/*/node_modules
+services/*/dist
+ui/*/node_modules
+ui/*/dist
+
+# Turbo directories
+.turbo
+
+# dependencies management script
+.package-json-backup.json
+.changeset-in-progress
+.tools
+
+*storybook.log
+storybook-static
+
+version.json
+
+.release-notes/

package/templates/bootstrap-service-template/Dockerfile.development

@@ -1,4 +1,4 @@
-FROM node:20.11-alpine as development
+FROM node:20.11-alpine AS development
 
 ENV NODE_ENV=development
 ENV PORT=80

package/templates/bootstrap-service-template/gitignore

@@ -0,0 +1,57 @@
+# compiled output
+/dist
+/node_modules
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+/.vscode
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# temp directory
+.temp
+.tmp
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

package/templates/bootstrap-service-template/package.json

@@ -13,7 +13,7 @@
     "lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix"
   },
   "dependencies": {
-    "@bluealba/pae-bootstrap-lib": "3.1.2",
+    "@bluealba/pae-bootstrap-lib": "3.2.0",
     "@bluealba/pae-core": "5.5.0",
     "copyfiles": "^2.4.1",
     "express": "^4.21.2"

package/templates/bootstrap-service-template/src/main.ts

@@ -13,26 +13,16 @@ const createApp = async (): Promise<express.Application> => {
 };
 
 const serviceAccessName = process.env.SERVICE_ACCESS_NAME;
-if (!serviceAccessName) {
-  console.error('No SERVICE_ACCESS_NAME env variable set !');
-  process.exit(1);
-}
 
 // fire it up
 createApp().then(app => {
   app.listen(config.port, () => {
     console.log('Server listening on Port', config.port);
-    console.log(`Waiting ${config.waitTime} before synchronizing ...`);
-    setTimeout(() => {
-      bootstrapPlatform({
-        path: join(process.cwd(), 'src', 'data'),
-        scopedTo: serviceAccessName
-      })
-        .then(() => console.log('\n\n\n\n>\n> Platform Successfully Synchronized !!!\n>'))
-        .catch(e => {
-          console.error('\n\n\n\n>\n> Error Synchronizing Platform !!!\n>', e);
-          process.exit(1);
-        });
-    }, config.waitTime);
+    bootstrapPlatform({
+      path: join(process.cwd(), 'src', 'data'),
+      scopedTo: serviceAccessName ?? '',
+      initialDelay: config.waitTime,
+      retries: 10
+    }).catch(e => console.error('[Bootstrap] Unhandled error:', e));
   });
 });

package/templates/customization-ui-module-template/Dockerfile.development

@@ -1,4 +1,4 @@
-FROM node:20-alpine as development
+FROM node:20-alpine AS development
 
 ENV NODE_ENV=development
 ENV PORT=80

package/templates/customization-ui-module-template/gitignore

@@ -0,0 +1,73 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# next.js build output
+.next
+dist
+distLib
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.DS_Store

package/templates/nestjs-service-module-template/Dockerfile.development

@@ -1,4 +1,4 @@
-FROM node:20.11-alpine as development
+FROM node:20.11-alpine AS development
 
 ENV NODE_ENV=development
 ENV PORT=80

package/templates/nestjs-service-module-template/gitignore

@@ -0,0 +1,56 @@
+# compiled output
+/dist
+/node_modules
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# temp directory
+.temp
+.tmp
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json