@bluealba/platform-cli 1.1.1-alpha.0 → 1.2.0-alpha.0

package/docs/platform-cli/commands.mdx

@@ -167,12 +167,18 @@ platform <command-name> key1=value1 key2=value2
 
 **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.
+**Requires a platform**: No — when run outside a platform, additional prompts for platform name and organization name are shown, and configuration is saved to the standalone config cache.
+
+<Aside type="note" title="Dual-mode behavior">
+  `create-application` works whether or not you are inside a platform repository. Inside a platform, it reads the product manifest and registers the application there. Outside a platform, it prompts for `platformName` and `organizationName`, scaffolds a standalone application monorepo, and saves initial configuration to `~/.ba-platform/standalone.json` so you can immediately use `platform standalone`.
+</Aside>
 
 ### Interactive prompts
 
 | Prompt | Description |
 |--------|-------------|
+| Platform name | Only shown when outside a platform — machine name for the platform (lowercase, hyphens only; e.g. `myplatform`) |
+| Organization name | Only shown when outside a platform — npm scope / organization identifier (e.g. `myorg`) |
 | 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 |
@@ -188,6 +194,8 @@ platform <command-name> key1=value1 key2=value2
 | `applicationDescription` | Yes | Short description |
 | `hasUserInterface` | No | `yes` or `no` (default: `no`) |
 | `hasBackendService` | No | `yes` or `no` (default: `no`) |
+| `platformName` | Outside a platform only | Machine name for the platform (lowercase letters, numbers, and hyphens) |
+| `organizationName` | Outside a platform only | npm scope / organization identifier |
 
 ### Example
 
@@ -198,7 +206,7 @@ platform <command-name> key1=value1 key2=value2
     # Press / then type "create-application" and press Enter
     ```
   </TabItem>
-  <TabItem label="Headless">
+  <TabItem label="Headless (inside a platform)">
     ```bash
     platform create-application \
       applicationName=billing \
@@ -208,6 +216,25 @@ platform <command-name> key1=value1 key2=value2
       hasBackendService=yes
     ```
   </TabItem>
+  <TabItem label="Headless (outside a platform)">
+    ```bash
+    platform create-application \
+      platformName=myplatform \
+      organizationName=myorg \
+      applicationName=billing \
+      applicationDisplayName="Billing" \
+      applicationDescription="Invoice and payment management" \
+      hasUserInterface=yes \
+      hasBackendService=yes
+    ```
+
+    After the command completes, navigate into the new directory and start standalone mode:
+
+    ```bash
+    cd myplatform-billing
+    platform standalone
+    ```
+  </TabItem>
 </Tabs>
 
 ---
@@ -462,6 +489,243 @@ The command presents a looping menu with four options:
 
 ---
 
+## standalone
+
+**Description**: Starts the platform in standalone mode for the current application. Scaffolds a temporary platform core in `/tmp/platform-standalone-{platformName}/`, installs dependencies, builds, starts Docker containers, waits for the gateway to become healthy, and configures IDP and admin users. Auto-detects app identity from the bootstrap service configuration. Press Ctrl+C to stop and clean up, or use the `detach` flag to run in the background.
+
+**Requires a platform**: No — requires being in an application monorepo root (must have `docker-compose.yml` and `package.json`, and must not be inside an initialized platform).
+
+<Aside type="note" title="Context-aware visibility">
+  `standalone` is visible in the command palette only when the current directory is an application monorepo and no platform core is initialized nearby. It is hidden when inside a full platform repository.
+</Aside>
+
+### Interactive prompts
+
+When no configuration exists for the detected application, the CLI runs a setup wizard:
+
+| Prompt | Description |
+|--------|-------------|
+| Platform name | Pre-filled from auto-detection or existing defaults |
+| Organization name | Pre-filled from existing defaults if available |
+| Application name | Pre-filled from auto-detection |
+| Application display name | Pre-filled from auto-detection |
+| Select IDP provider | Single-select: Okta or Entra ID (skipped if a default IDP exists and you confirm reuse) |
+| Provider name, Issuer URL, Client ID, Client Secret | IDP credentials |
+| Admin user(s) | One or more email addresses (first pre-filled from `git config user.email`) |
+| Run in detached mode? | Whether to start in the background |
+
+Once configuration is saved, subsequent runs skip the wizard and start immediately.
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `detach` | No | `true` to run in the background (also accepted as `-d` flag) |
+
+<Aside type="caution" title="Headless prerequisites">
+  In headless mode, `platform standalone` requires that configuration already exists in `~/.ba-platform/standalone.json` for the detected application. Run it interactively at least once, or use `platform standalone-config-set` to pre-configure.
+</Aside>
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive (foreground)">
+    ```bash
+    cd myplatform-billing
+    platform standalone
+    # Follow the first-time setup wizard if needed
+    # Press Ctrl+C to stop
+    ```
+  </TabItem>
+  <TabItem label="Interactive (detached)">
+    ```bash
+    cd myplatform-billing
+    platform standalone
+    # When prompted "Run in detached mode?", answer yes
+    ```
+  </TabItem>
+  <TabItem label="Headless (detached)">
+    ```bash
+    cd myplatform-billing
+    platform standalone detach=true
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## standalone-stop
+
+**Description**: Stops a detached standalone platform and cleans up the temporary platform core in `/tmp/`. Has no effect if no detached standalone platform is running.
+
+**Requires a platform**: No.
+
+### Interactive behaviour
+
+The command locates the running standalone instance by scanning `/tmp/` for a directory matching `platform-standalone-*` that contains a running marker. It tears down all Docker Compose services (removing containers and volumes) and deletes the temporary directory.
+
+### Headless
+
+`standalone-stop` requires no arguments:
+
+```bash
+platform standalone-stop
+```
+
+---
+
+## standalone-config-show
+
+**Description**: Shows the resolved standalone configuration for the current application. If run from outside an application monorepo, shows the full contents of `~/.ba-platform/standalone.json` including defaults and all app entries.
+
+**Requires a platform**: No.
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `app` | No | Specific app to show, in `platformName/applicationName` format. Auto-detected from cwd if omitted. |
+
+### Example
+
+<Tabs>
+  <TabItem label="Current app (auto-detected)">
+    ```bash
+    platform standalone-config-show
+    ```
+  </TabItem>
+  <TabItem label="Specific app">
+    ```bash
+    platform standalone-config-show app=myplatform/billing
+    ```
+  </TabItem>
+  <TabItem label="All config (from outside app dir)">
+    ```bash
+    cd ~
+    platform standalone-config-show
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## standalone-config-set
+
+**Description**: Edits standalone configuration defaults or app-specific overrides. Defaults are shared across all applications; app overrides take precedence over defaults for the specific application.
+
+**Requires a platform**: No.
+
+### Interactive prompts
+
+The command first asks whether to edit defaults or app-specific config, then presents the relevant fields pre-filled with existing values. IDP and admin user fields can only be configured in interactive mode.
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `defaults` | No | Set to `true` to edit the defaults section. Provide field values as additional key=value pairs. |
+| `app` | No | App key in `platformName/applicationName` format to edit. Auto-detected from cwd if omitted. |
+| `platformName` | No | Used with `defaults=true` |
+| `organizationName` | No | Used with `defaults=true` |
+| `applicationName` | No | Used with `app=...` |
+| `applicationDisplayName` | No | Used with `app=...` |
+
+<Aside type="note">
+  IDP credentials and admin user lists can only be set or updated through interactive mode. They cannot be passed as headless arguments.
+</Aside>
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform standalone-config-set
+    # Select "Defaults" or "App-specific config" and follow prompts
+    ```
+  </TabItem>
+  <TabItem label="Edit defaults (headless)">
+    ```bash
+    platform standalone-config-set defaults=true platformName=myplatform organizationName=myorg
+    ```
+  </TabItem>
+  <TabItem label="Edit app (headless)">
+    ```bash
+    platform standalone-config-set app=myplatform/billing applicationDisplayName="Billing v2"
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## standalone-config-delete
+
+**Description**: Deletes a saved standalone app config entry from `~/.ba-platform/standalone.json`. Defaults are not affected.
+
+**Requires a platform**: No.
+
+### Interactive prompts
+
+| Prompt | Description |
+|--------|-------------|
+| Select app config to delete | Single-select from all saved app entries |
+| Confirm deletion | Yes/No confirmation before proceeding |
+
+### Headless arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `app` | Yes | App key in `platformName/applicationName` format |
+
+### Example
+
+<Tabs>
+  <TabItem label="Interactive">
+    ```bash
+    platform standalone-config-delete
+    # Select from list and confirm
+    ```
+  </TabItem>
+  <TabItem label="Headless">
+    ```bash
+    platform standalone-config-delete app=myplatform/billing
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## standalone-config-list
+
+**Description**: Lists all applications that have standalone configuration saved in `~/.ba-platform/standalone.json`, along with their resolved settings.
+
+**Requires a platform**: No.
+
+### Headless
+
+`standalone-config-list` requires no arguments:
+
+```bash
+platform standalone-config-list
+```
+
+Example output:
+
+```
+Config file: /Users/you/.ba-platform/standalone.json
+
+Defaults:
+  Platform: myplatform
+  Organization: myorg
+  IDP: okta (My Okta)
+  Admin Users: you@example.com
+
+Apps:
+  myplatform/billing — Billing [IDP: yes, Admins: 1]
+  myplatform/hr — HR [IDP: no, Admins: 1]
+```
+
+---
+
 ## 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.
@@ -591,7 +855,7 @@ The following five commands manage the lifecycle of your local Docker Compose en
 |---------|--------------|-------------|
 | `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-application` | No | Add an application to a platform, or create a standalone application |
 | `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 |
@@ -602,3 +866,9 @@ The following five commands manage the lifecycle of your local Docker Compose en
 | `start` | Yes | Start the local Docker Compose environment |
 | `stop` | Yes | Stop the local Docker Compose environment |
 | `destroy` | Yes | Destroy the local environment (removes volumes) |
+| `standalone` | No (app monorepo) | Start the platform in standalone mode for this application |
+| `standalone-stop` | No | Stop a detached standalone platform |
+| `standalone-config-show` | No | Show resolved standalone config for current or specified app |
+| `standalone-config-set` | No | Edit standalone config defaults or app-specific overrides |
+| `standalone-config-delete` | No | Delete a saved standalone app config entry |
+| `standalone-config-list` | No | List all apps with standalone config |

package/docs/platform-cli/overview.mdx

@@ -5,7 +5,7 @@ description: Introduction to the Blue Alba Platform CLI — how to install it, u
 
 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 `@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, checking platform health, and running individual applications in standalone mode without a full product repository.
 
 The CLI ships in two modes that can be freely combined:
 
@@ -187,9 +187,32 @@ my-product/
 
 ---
 
+## Standalone Mode
+
+Standalone mode lets you run a single application with a fully functional platform infrastructure — gateway, database, and bootstrap service — without setting up a full product repository. It is designed for rapid application development and testing in isolation.
+
+```bash
+# Create a new standalone application
+platform create-application \
+  platformName=myplatform \
+  organizationName=myorg \
+  applicationName=billing
+
+# Navigate to the new app and start the platform
+cd myplatform-billing
+platform standalone
+```
+
+IDP credentials and admin users are stored once in `~/.ba-platform/standalone.json` and reused automatically for all your standalone applications.
+
+See [Standalone Mode](./standalone-mode/) for the complete guide.
+
+---
+
 ## Next Steps
 
 - [Command Reference](./commands/) — Complete documentation for every command
+- [Standalone Mode](./standalone-mode/) — Run a single application without a full product repository
 - [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