@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/platform-cli/commands.mdx

@@ -0,0 +1,604 @@
+---
+title: Command Reference
+description: Complete reference for all Platform CLI commands — arguments, prompts, and examples
+---
+
+import { Aside, Tabs, TabItem, Card, CardGrid } from '@astrojs/starlight/components';
+
+This page documents every command available in `@bluealba/platform-cli`. For each command you will find:
+
+- A description of what the command does
+- The interactive prompts it presents
+- The headless arguments it accepts
+- An end-to-end example
+
+All commands follow the same invocation pattern:
+
+```bash
+# Interactive (guided)
+platform
+
+# Headless
+platform <command-name> key1=value1 key2=value2
+```
+
+---
+
+## init
+
+**Description**: Initializes a new Blue Alba Platform in the current directory. This is always the first command you run. It scaffolds the core directory structure, generates the product manifest, creates a bootstrap service, and creates a customization UI module.
+
+**Requires a platform**: No — this command must be run before any other.
+
+### What it creates
+
+```
+<current-directory>/
+└── <platformName>-core/
+    ├── product.manifest.json         ← Product manifest (tracks all applications)
+    ├── local/
+    │   └── .env                      ← Generated environment configuration
+    └── services/
+        └── <platformName>-bootstrap-service/
+            └── ...                   ← Bootstrap NestJS service scaffold
+    └── ui/
+        └── <platformName>-customization-ui/
+            └── ...                   ← Customization React UI module scaffold
+```
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Organization name | Your organization or npm scope (e.g. `acme`) |
+| Platform name | The machine name for the platform (lowercase, hyphens only; e.g. `my-platform`) |
+| Platform display name | The human-readable title shown in the UI (e.g. `My Platform`) |
+| Customize artifact names? | Whether to override the default suffixes for the bootstrap service and customization UI |
+| Bootstrap service suffix | Only shown if customizing; defaults to `bootstrap-service` |
+| Customization UI suffix | Only shown if customizing; defaults to `customization-ui` |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `organizationName` | Yes | npm scope / organization identifier |
+| `platformName` | Yes | Machine name (lowercase letters, numbers, and hyphens) |
+| `platformDisplayName` | Yes | Human-readable display name |
+| `bootstrapServiceSuffix` | No | Defaults to `bootstrap-service` |
+| `customizationUiSuffix` | No | Defaults to `customization-ui` |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "init" and press Enter
+    # Follow the prompts
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform init \
+      organizationName=acme \
+      platformName=my-platform \
+      platformDisplayName="My Platform"
+    ```
+
+    With custom artifact names:
+
+    ```bash
+    platform init \
+      organizationName=acme \
+      platformName=my-platform \
+      platformDisplayName="My Platform" \
+      bootstrapServiceSuffix=bootstrap \
+      customizationUiSuffix=customization
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## configure-idp
+
+**Description**: Configures an Identity Provider (IdP) for the platform. This command writes the necessary IdP settings into the platform's environment configuration so the gateway service can authenticate users via OAuth/OIDC.
+
+**Requires a platform**: Yes.
+
+**Supported providers**:
+
+| Provider | Type value |
+|----------|------------|
+| Okta | `okta` |
+| Microsoft Entra ID | `entra-id` |
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Select IDP type | Single-select list: Okta or Entra ID |
+| Provider name | A label for this provider (e.g. `My Okta`) |
+| Issuer URL | The OIDC issuer URL from your IdP |
+| Client ID | The OAuth application client ID |
+| Client Secret | The OAuth application client secret |
+| Tenant ID | Entra ID only — your Azure tenant ID |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `providerType` | Yes | `okta` or `entra-id` |
+| `name` | Yes | Human-readable label for this provider |
+| `issuer` | Yes | OIDC issuer URL |
+| `clientId` | Yes | OAuth client ID |
+| `clientSecret` | Yes | OAuth client secret |
+| `tenantId` | Entra ID only | Azure tenant ID |
+
+### Example
+
+<Tabs>
+  <TabItem label="Okta">
+    ```bash
+    platform configure-idp \
+      providerType=okta \
+      name="Acme Okta" \
+      issuer=https://acme.okta.com/oauth2/default \
+      clientId=0oa1ab2cd3ef4gh5ij6k \
+      clientSecret=abc123secretvalue
+    ```
+  </TabItem>
+  <TabItem label="Entra ID">
+    ```bash
+    platform configure-idp \
+      providerType=entra-id \
+      name="Acme Entra" \
+      issuer=https://login.microsoftonline.com/your-tenant-id/v2.0 \
+      clientId=00000000-0000-0000-0000-000000000000 \
+      clientSecret=your-client-secret \
+      tenantId=your-tenant-id
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## create-application
+
+**Description**: Adds a new application to an existing platform. An application is an independent domain (e.g. "Billing", "HR") that can include a backend service, a UI module, or both. The command adds the application to the product manifest and optionally scaffolds the service and UI skeletons.
+
+**Requires a platform**: Yes.
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Application name | Machine name (lowercase, hyphens only; e.g. `billing`) |
+| Application display name | Human-readable title (e.g. `Billing`) |
+| Application description | Short description of the application's purpose |
+| Does this application have a user interface? | Whether to scaffold a React UI module |
+| Does this application have a backend service? | Whether to scaffold a NestJS backend service |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `applicationName` | Yes | Machine name (lowercase letters, numbers, and hyphens) |
+| `applicationDisplayName` | Yes | Human-readable display name |
+| `applicationDescription` | Yes | Short description |
+| `hasUserInterface` | No | `yes` or `no` (default: `no`) |
+| `hasBackendService` | No | `yes` or `no` (default: `no`) |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "create-application" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform create-application \
+      applicationName=billing \
+      applicationDisplayName="Billing" \
+      applicationDescription="Invoice and payment management" \
+      hasUserInterface=yes \
+      hasBackendService=yes
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## create-service-module
+
+**Description**: Adds a NestJS backend service module to an existing application. The command reads the product manifest to present a list of registered applications, then scaffolds a new service workspace inside the selected application.
+
+**Requires a platform**: Yes. At least one application must exist (if none exist, the CLI offers to create one first).
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Select application | Single-select from registered applications |
+| Service name | Machine name for the service (e.g. `payments`) |
+| Include "-service" suffix? | Whether to append `-service` to the generated directory name |
+| Service display name | Human-readable title (e.g. `Payments Service`) |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `applicationName` | Yes | Must match a registered application name |
+| `serviceName` | Yes | Machine name (lowercase letters, numbers, and hyphens) |
+| `serviceDisplayName` | Yes | Human-readable display name |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "create-service-module" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform create-service-module \
+      applicationName=billing \
+      serviceName=payments \
+      serviceDisplayName="Payments Service"
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## create-ui-module
+
+**Description**: Adds a React micro-frontend UI module to an existing application. The command reads the product manifest to present a list of registered applications, then scaffolds a new React workspace that integrates with the single-spa shell.
+
+**Requires a platform**: Yes. At least one application must exist (if none exist, the CLI offers to create one first).
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Select application | Single-select from registered applications |
+| Include "-ui" suffix? | Whether to append `-ui` to the generated directory name |
+| Application display name | Human-readable title for the UI module |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `applicationName` | Yes | Must match a registered application name |
+| `applicationDisplayName` | Yes | Human-readable display name |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "create-ui-module" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform create-ui-module \
+      applicationName=billing \
+      applicationDisplayName="Billing"
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## status
+
+**Description**: Displays a comprehensive health report for the current platform environment and guides you through remediation. The report covers:
+
+- Prerequisites (Node.js version, Docker daemon availability)
+- Lifecycle stage (initialized, dependencies installed, built, running)
+- Per-application container state
+- Identity Provider configuration
+
+After printing the report, `status` identifies the next required action and offers to run it immediately. This makes `status` the single command you need to go from a freshly cloned repository to a fully running environment.
+
+**Requires a platform**: Yes (hides in the command palette until initialized).
+
+### Interactive behaviour
+
+1. Gathers all checks and prints a formatted report
+2. Determines the next step (`init`, `install`, `build`, or `start`)
+3. Asks whether to execute the next step
+4. If the step succeeds, loops and re-checks
+5. If all checks pass, optionally prompts to configure an IdP if none is configured
+
+### Headless
+
+`status` is primarily an interactive command. In headless contexts it prints the report and exits with a zero code when everything is healthy, non-zero otherwise.
+
+```bash
+platform status
+```
+
+### Example output (abbreviated)
+
+```
+Platform: My Platform (my-platform)
+Organization: acme
+
+Prerequisites
+  ✓ Node.js  v22.14.0
+  ✓ Docker   27.5.1
+
+Lifecycle
+  ✓ Initialized
+  ✓ Dependencies installed
+  ✓ Built
+  ✓ Running
+
+Containers (core)
+  ✓ gateway         running   0.0.0.0:9443->443/tcp
+  ✓ shell-ui        running   0.0.0.0:8080->80/tcp
+  ✓ postgres        running   0.0.0.0:5432->5432/tcp
+
+IDP
+  ✓ Acme Okta  (okta, active)
+
+All checks passed!
+```
+
+---
+
+## manage-platform-admins
+
+**Description**: Lists, grants, and revokes platform administrator access for user accounts. Platform admins have full permissions across the entire platform. Changes are written to the bootstrap service configuration so they are applied on the next bootstrap run.
+
+**Requires a platform**: Yes.
+
+### Interactive behaviour
+
+The command presents a looping menu with four options:
+
+- **List current admins** — prints all users who currently have platform admin access
+- **Add admin(s)** — prompts for usernames one at a time (pre-filled with your `git config user.email`); allows adding multiple admins before confirming
+- **Remove admin(s)** — presents a multi-select list of current admins to remove; asks for confirmation before proceeding
+- **Back to main menu** — exits the sub-menu
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `action` | Yes | `list`, `add`, or `remove` |
+| `usernames` | Required for `add` and `remove` | Comma-separated list of usernames |
+
+### Example
+
+<Tabs>
+  <TabItem label="List">
+    ```bash
+    platform manage-platform-admins action=list
+    ```
+  </TabItem>
+  <TabItem label="Add">
+    ```bash
+    platform manage-platform-admins action=add usernames=alice@acme.com,bob@acme.com
+    ```
+  </TabItem>
+  <TabItem label="Remove">
+    ```bash
+    platform manage-platform-admins action=remove usernames=bob@acme.com
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## install-ai-plugin
+
+**Description**: Installs AI assistant plugins that give your AI coding assistant (e.g. Claude Code) comprehensive knowledge about the Blue Alba Platform. Plugins are versioned and the command will prompt before upgrading an already-installed plugin.
+
+**Requires a platform**: No — this command can be run anywhere.
+
+### Available plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `ba-platform-plugin` | Blue Alba Platform knowledge and CLI skills for AI assistants. Includes two skills: `platform` (architecture and concepts) and `platform-cli` (CLI commands and usage) |
+
+### Available providers
+
+| Provider | Value |
+|----------|-------|
+| Claude Code | `claude` |
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Select AI provider | Single-select list of supported AI providers |
+| Select plugins to install | Multi-select list of available plugins |
+| Update confirmation | If a plugin is already installed, asks whether to upgrade to the new version |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `provider` | Yes | AI provider name (e.g. `claude`) |
+| `plugins` | Yes | Comma-separated list of plugin names |
+| `force` | No | `true` to skip update confirmation prompts |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "install-ai-plugin" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform install-ai-plugin \
+      provider=claude \
+      plugins=ba-platform-plugin
+    ```
+
+    Force-update without confirmation:
+
+    ```bash
+    platform install-ai-plugin \
+      provider=claude \
+      plugins=ba-platform-plugin \
+      force=true
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## Local Environment Commands
+
+The following five commands manage the lifecycle of your local Docker Compose environment. They all share the same target-selection model: when run interactively, they present a multi-select list of available targets (`Platform (Core)` plus each registered application); when run headlessly, target names are passed as positional arguments.
+
+<Aside type="note" title="Hidden until initialized">
+  These commands are hidden in the command palette until `init` has been run in the current directory.
+</Aside>
+
+### install
+
+**Description**: Installs Node.js dependencies for the platform core and selected applications by running `npm install` in each workspace.
+
+**When to run**: After `init` and whenever new dependencies are added.
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "install" and press Enter
+    # Multi-select the targets
+    ```
+  </TabItem>
+  <TabItem label="Headless (all targets)">
+    ```bash
+    platform install
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+### build
+
+**Description**: Compiles TypeScript source code and builds Docker images for the platform core and selected applications using Turborepo.
+
+**When to run**: After `install` and whenever source code changes that need to be reflected in the running containers.
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "build" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform build
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+### start
+
+**Description**: Starts the local development environment by running `docker compose up` with the appropriate Compose files for the platform core and selected applications.
+
+**When to run**: After `build`, or any time you want to bring the environment up.
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "start" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless (all targets)">
+    ```bash
+    platform start
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+### stop
+
+**Description**: Stops the running Docker Compose services without removing containers or volumes.
+
+**When to run**: When you want to pause the environment without losing state.
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "stop" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform stop
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+### destroy
+
+**Description**: Stops and removes all Docker Compose containers, networks, and volumes for the selected targets. This is a destructive operation — all local data stored in Docker volumes will be lost.
+
+**When to run**: When you want a completely clean slate, for example before re-running the bootstrap service with fresh configuration.
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform
+    # Press / then type "destroy" and press Enter
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform destroy
+    ```
+  </TabItem>
+</Tabs>
+
+<Aside type="caution" title="Data loss warning">
+  The `destroy` command removes Docker volumes. Any data stored in the local PostgreSQL database, Kafka topics, or other stateful services will be permanently deleted. Run `stop` instead if you want to preserve your data.
+</Aside>
+
+---
+
+## Command Summary
+
+| Command | Requires init | Description |
+|---------|--------------|-------------|
+| `init` | No | Initialize a new platform |
+| `configure-idp` | Yes | Configure an Identity Provider (Okta, Entra ID) |
+| `create-application` | Yes | Add an application to the platform |
+| `create-service-module` | Yes | Add a NestJS backend service to an application |
+| `create-ui-module` | Yes | Add a React UI module to an application |
+| `status` | Yes | Show platform health and guide through next steps |
+| `manage-platform-admins` | Yes | List, add, or remove platform administrators |
+| `install-ai-plugin` | No | Install AI assistant plugins for the platform |
+| `install` | Yes | Install dependencies in the local environment |
+| `build` | Yes | Build the local environment |
+| `start` | Yes | Start the local Docker Compose environment |
+| `stop` | Yes | Stop the local Docker Compose environment |
+| `destroy` | Yes | Destroy the local environment (removes volumes) |