jarvis-launcher 1.1.0 → 1.1.2

package/README.md

@@ -12,14 +12,12 @@ You need exactly three things on the host:
 
 1. **Docker** with **Compose v2** (`docker compose`, the plugin — not the old `docker-compose`). Docker Desktop on macOS/Windows or Docker Engine on Linux both work.
 2. **Node.js ≥ 20 (LTS)** — required to install and run the CLI.
-3. An **ACR repository-scoped token** for the integrator image registry `integratori-ggeybpb3azacdpfw.azurecr.io`. The token comes as a pair:
-   - the **token name** is the Docker login **username**;
-   - the **token password** is the **password**.
+3. A **Microsoft Entra application client secret** for the integrator's Azure tenant. One Entra application authenticates **both** the image registry `integratori-ggeybpb3azacdpfw.azurecr.io` (it must hold the **AcrPull** role) and the seed catalog in Azure Blob Storage (it must hold **Storage Blob Data Reader** on the `seedintegratori`/`seeds` container). You supply only the **client secret** — the application (client) id and tenant id are baked in.
 
 That is the whole floor. In particular you do **not** need:
 
 - **No** host-side MongoDB tools (`mongosh`, `mongorestore`, …) — every Mongo operation runs inside a container.
-- **No** Azure CLI — authentication is a plain `docker login` against the registry (see [`registry-login`](#registry-login)).
+- **No** Azure CLI — the launcher logs Docker in as the Entra application (`docker login … --password-stdin`) and talks to Blob Storage over plain REST (see [`registry-login`](#registry-login)).
 
 > **Apple Silicon (arm64):** the optional **SQL Server** service (`enable sql` / `start --sql`) runs only as an **x64** image — Microsoft ships no arm64 build of SQL Server — so on an Apple Silicon Mac it runs under emulation. Enable **"Use Rosetta for x86/amd64 emulation"** in Docker Desktop → *Settings → General* for it to start reliably; without it the QEMU fallback is slow and SQL Server can crash. The always-on core stack (Jarvis / Mongo / ES) runs natively on arm64 and is unaffected.
 
@@ -60,21 +58,20 @@ The all-in-one image lives in a private ACR, so Docker must be authenticated bef
 jarvis-launcher registry-login
 ```
 
-You are prompted (masked) for the **token name** (username) and **token password**. The credential is stored by **Docker's own credential store** (`~/.docker/config.json` / your OS keychain) — the launcher persists no secret itself — so you are asked **only once per machine**. Subsequent commands that pull the image reuse the stored credential silently; if the credential is ever missing or rejected, `start`/`update` re-prompt automatically and retry once.
+You are prompted (masked) for the **Entra application client secret**. The launcher logs Docker in as the Entra application — `docker login <registry> -u <client-id> --password-stdin` — and Docker's own credential store (`~/.docker/config.json` / your OS keychain) persists the resulting login. The **prompted client secret** is also persisted by the launcher, in your **OS keychain** (macOS Keychain / Windows Credential Manager / Linux Secret Service via `@napi-rs/keyring`), falling back to a `chmod 0600` `~/.jarvis-launcher/credentials.json` when the keychain is unavailable — so you are asked **only once per machine**, and the **same** secret is reused for the seed catalog. Subsequent commands reuse it silently; if it is ever **rejected**, the launcher clears the stored secret and re-prompts, then retries once (a Docker-daemon/network failure is reported as such and does **not** clear the stored secret).
 
-You can supply the credential non-interactively (e.g. in CI):
+You can supply the client secret non-interactively (e.g. in CI):
 
 ```bash
-# via flags
-jarvis-launcher registry-login --user <token-name> --password <token-password>
+# via flag
+jarvis-launcher registry-login --client-secret <client-secret>
 
-# or via environment variables
-export JARVIS_REGISTRY_USER=<token-name>
-export JARVIS_REGISTRY_PASSWORD=<token-password>
+# or via environment variable
+export JARVIS_CLIENT_SECRET=<client-secret>
 jarvis-launcher registry-login
 ```
 
-The credential-source precedence is **flags → environment variables → masked prompt**. `--registry <host>` overrides the default registry host if needed.
+The client-secret precedence is **flag → `JARVIS_CLIENT_SECRET` env → stored (keychain / file) → masked prompt**. The flag and the env var are deliberately **ephemeral, per-invocation overrides**: they are **never written to the keychain** (only a prompted secret is persisted), and when one of them is rejected the launcher leaves any stored secret untouched — fix or unset the override instead. `--registry <host>` overrides the default registry host if needed. The application (client) id and tenant id default to the integrator's and can be overridden with `JARVIS_CLIENT_ID` / `JARVIS_TENANT_ID`.
 
 > **`registry-login` is Docker registry authentication.** It is **not** the same as the Jarvis dev-[`login`](#login) command, which opens a browser impersonation session into a running Jarvis. Keep the two distinct.
 
@@ -119,12 +116,14 @@ Notes:
 
 ### Pre-seeding the initial state (`seed/state.json`)
 
-An integrator packaging a scenario can ship a **`seed/state.json`** file to pre-declare the environment's **initial** state, so the first `init`/`start` picks up the right project name, optional profiles, and image tag without anyone having to remember the flags. It is read **only when the scenario has no `.orchestrator/state.json` yet** (a brand-new environment); once the scenario has been started, its own `.orchestrator/state.json` drives everything and the seed is ignored.
+An integrator packaging a scenario can ship a **`seed/state.json`** file to give the seed an identity (a name and description) and pre-declare the environment's **initial** state, so the first `init`/`start` picks up the right project name, optional profiles, and image tag without anyone having to remember the flags. It is read **only when the scenario has no `.orchestrator/state.json` yet** (a brand-new environment); once the scenario has been started, its own `.orchestrator/state.json` drives everything and the seed is ignored.
 
-Only three properties are honored — anything else in the file (notably a `ports` block) is ignored, so you can copy a working environment's `.orchestrator/state.json` verbatim and only the portable bits are applied (fresh host ports are always re-allocated for the new machine):
+Only the properties below are honored — anything else in the file (notably a `ports` block) is ignored, so you can copy a working environment's `.orchestrator/state.json` verbatim and only the portable bits are applied (fresh host ports are always re-allocated for the new machine):
 
 ```json
 {
+  "name": "CMMS Demo",
+  "description": "Maintenance-management demo with SQL and sample data",
   "projectName": "cmms",
   "enabledProfiles": ["sql"],
   "tag": "1.2.3"
@@ -133,13 +132,23 @@ Only three properties are honored — anything else in the file (notably a `port
 
 | Property | Meaning | Default when omitted |
 |---|---|---|
+| `name` | short human-readable label for the seed (identity metadata; not applied to the environment) | none |
+| `description` | free-text summary of what the seed installs (identity metadata; not applied to the environment) | none |
 | `projectName` | the `docker compose -p` project name | derived from the folder name |
 | `enabledProfiles` | optional profiles to turn on (`sql`, `mail`) | none |
 | `tag` | base image tag to pin the scenario to | `latest` |
 
+`name` and `description` describe the seed itself — they are read back via `readSeedState` (the groundwork for letting the launcher list and choose a seed to import) but do not change what `start` brings up.
+
 Explicit CLI flags always win over the seed: `--tag` overrides `tag`, and `--sql`/`--mail` are **added to** the seed's `enabledProfiles`.
 
-In the interactive homepage, choosing **Start** on a brand-new scenario that ships a `seed/state.json` skips the initial questions (folder / tag / SQL / mail / force) and starts straight away — the seed already pre-declares that initial state, so there is nothing to ask.
+In the interactive homepage, choosing **Start** on a brand-new (uninitialized) folder first asks for the **scenario folder** (default: the current directory — one Enter keeps it, like Stop/Restore/Backup), then opens a submenu for that folder. A **local `seed/` takes precedence** over the remote catalog — when the folder already ships one (any payload counts, including a config-only seed), the remote catalog is never contacted (no client-secret prompt / network):
+
+- **Start from local seed** *(shown only when a local `seed/` is present)* — install the shipped seed by starting the folder. A seed **declared** by `seed/state.json` dictates its own environment and starts as-is (the status header above already previews what it will install); an **undeclared** seed (data/config only) still asks for the image tag and the optional SQL/mail toggles — with SQL defaulting to **on** when the seed ships a SQL backup.
+- **Start from an existing scenario** *(shown only when there is no local seed)* — pick from the **remote seed catalog**: the `.zip` blobs in the `seedintegratori`/`seeds` container, each shown by its blob-metadata `name`/`description`. Picking one downloads and extracts it into `<folder>/seed` (staged first — a failed download never leaves a half-installed or wiped seed), then starts it. An empty or unreachable catalog (offline / rejected secret) shows a short notice and returns.
+- **Start from an empty environment** — bring up a blank stack. If the folder ships a `seed/` (even a config-only one), this first asks to confirm and then **permanently deletes** the `seed/` folder (so the stack comes up empty instead of re-applying the seed), then asks for the image tag and the optional SQL/mail toggles.
+
+Choosing **Start** on an already-initialized folder (a stopped environment) skips the folder prompt and the submenu and resumes it directly.
 
 ### Pre-seeding the base configs (`seed/config/`)
 
@@ -179,7 +188,7 @@ After a restore, Elasticsearch repopulates in the background; the launcher print
 | Command | Synopsis | What it does |
 |---|---|---|
 | [`init`](#init) | `init [folder]` | Provision the three base config files into an empty/config-less folder. |
-| [`registry-login`](#registry-login) | `registry-login [--registry <host>] [--user <name>] [--password <pwd>]` | Authenticate Docker against the image registry (once per machine). |
+| [`registry-login`](#registry-login) | `registry-login [--registry <host>] [--client-secret <secret>]` | Authenticate Docker against the image registry as the Entra application (once per machine). |
 | [`start`](#start) | `start [folder] [--sql] [--mail] [--force]` | Bring up the full stack (auto-init + auto-restore) and report the URLs. |
 | [`stop`](#stop) | `stop [folder]` | Stop the stack (remove containers) while keeping all on-disk data. |
 | [`restore`](#restore) | `restore [folder] [--force]` | Restore the prepared artifact into the running stack (gated by `--force`). |
@@ -200,10 +209,10 @@ You rarely need `init` on its own — `start` performs the same provisioning aut
 ### `registry-login`
 
 ```bash
-jarvis-launcher registry-login [--registry <host>] [--user <token-name>] [--password <token-password>]
+jarvis-launcher registry-login [--registry <host>] [--client-secret <secret>]
 ```
 
-Forces a fresh `docker login` against the integrator registry so you can pre-seed or refresh the stored credential. See [Authenticate once](#authenticate-once-registry-login) above for the credential sources and the once-per-machine behavior.
+Forces a fresh `docker login` against the integrator registry (as the Entra application) so you can pre-seed or refresh the stored credential. See [Authenticate once](#authenticate-once-registry-login) above for the client-secret sources and the once-per-machine behavior.
 
 ### `start`
 
@@ -458,7 +467,7 @@ Docker/Mongo/ES-driven behavior (real `compose up/down`, copy-from-image, live r
 
 ## Troubleshooting
 
-- **`unauthorized` / `401` when pulling** — your Docker credential for the registry is missing or expired. Run `jarvis-launcher registry-login` again (or supply `--user`/`--password`).
+- **`unauthorized` / `401` when pulling** — the Entra client secret is missing, expired, or the application lacks the **AcrPull** role. Run `jarvis-launcher registry-login` again (or supply `--client-secret` / `JARVIS_CLIENT_SECRET`); a rejected secret is cleared automatically so you are re-prompted.
 - **"Refusing to restore: data already exists"** — the database is already populated. Re-run `restore` with `--force` to drop and reload, or leave it as-is.
 - **Port already in use** — the launcher re-probes persisted ports on every `start` and re-allocates a fresh block if one is taken, reporting the new proxy URL. There is a tiny window between picking a port and `compose up`; if a true conflict is hit, you get a clear bind-conflict error rather than a hang.
 - **"Nothing to stop / no started stack"** — that scenario was never started (no `.orchestrator/state.json`). Run `start` first.

package/dist/commands/backup.d.ts

@@ -34,6 +34,8 @@ export interface RunBackupResult {
     dsdataPath: string | null;
     /** Absolute path to the automation artifact when it was refreshed. */
     automationPath: string | null;
+    /** Absolute path to the encryption-keys artifact when it was refreshed. */
+    keysPath: string | null;
     /** Absolute path to the base-config artifact when it was refreshed. */
     configPath: string | null;
     /** Absolute path to the SQL `.bak` when it was refreshed (null when SQL is off or the seed ships none). */
@@ -42,6 +44,8 @@ export interface RunBackupResult {
     dsFiles: number;
     /** Top-level entries snapshotted into `seed/automation` (0 when absent). */
     automationEntries: number;
+    /** Top-level entries snapshotted into `seed/keys` (0 when absent). */
+    keyEntries: number;
     /** Base config files snapshotted into `seed/config` (0 when skipped). */
     configFiles: number;
 }

package/dist/commands/backup.js

@@ -112,6 +112,8 @@ export async function runBackup(options = {}) {
         parts.push(`seed/dsdata (${result.dsFiles} document-store files)`);
     if (result.automationEntries > 0)
         parts.push('seed/automation');
+    if (result.keyEntries > 0)
+        parts.push('seed/keys (encryption keys)');
     if (result.configFiles > 0)
         parts.push('seed/config (base configuration)');
     if (sqlBackupPath)
@@ -121,10 +123,12 @@ export async function runBackup(options = {}) {
         dumpPath: join(base, 'seed', 'dump'),
         dsdataPath: result.dsFiles > 0 ? join(base, 'seed', 'dsdata') : null,
         automationPath: result.automationEntries > 0 ? join(base, 'seed', 'automation') : null,
+        keysPath: result.keyEntries > 0 ? join(base, 'seed', 'keys') : null,
         configPath: result.configFiles > 0 ? join(base, 'seed', 'config') : null,
         sqlBackupPath,
         dsFiles: result.dsFiles,
         automationEntries: result.automationEntries,
+        keyEntries: result.keyEntries,
         configFiles: result.configFiles,
     };
     // The backup brought `mongo` (and `sql`, when enabled) up on its own to run the

package/dist/commands/backup.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"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"}

package/dist/commands/init.js

@@ -1,5 +1,6 @@
 import { prepareScenario } from '../lib/scenario.js';
 import { provisionConfigs, provisionConfigsFromSeed, missingConfigs } from '../lib/config.js';
+import { dockerPull } from '../lib/docker.js';
 import { resolveImageTag, DEFAULT_BASE_TAG } from '../lib/registry.js';
 import { readState, readSeedState, writeState, defaultProjectName, } from '../lib/state.js';
 import { progress } from '../lib/progress.js';
@@ -82,6 +83,20 @@ export async function runInit(folder, tag) {
     // take a while on a cold cache.
     progress(`Provisioning base configuration into "${base}"…`);
     const { baseTag, image } = await resolveImageTag({ baseTag: tag ?? seed?.tag });
+    // This branch exists to materialize the image's current reference configs, so a
+    // stale locally cached copy of the resolved tag (the moving `latest` above all)
+    // must be refreshed first — the copy-from-image below never pulls when a local
+    // image exists. A fast no-op when already current; a failure is downgraded to a
+    // warning because `resolveImageTag` just proved the tag reachable, and the copy
+    // below falls back to the cached image (or surfaces the real error itself).
+    progress(`Pulling ${image} so the configuration comes from the newest build…`);
+    try {
+        await dockerPull(image);
+    }
+    catch (error) {
+        progress(`⚠️  Could not pull ${image} — continuing with the locally cached image.\n` +
+            `${error.message}`);
+    }
     const provisioned = await provisionConfigs({ base, image });
     // Persist the initial state: a non-`latest` pinned tag (so a later tag-less `start`
     // reuses it without re-asking) plus any seed-declared project name / profiles.

package/dist/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/registry-login.d.ts

@@ -1,14 +1,15 @@
 import { Command } from 'commander';
 /**
- * `registry-login` — explicit `docker login` to the integrator-distribution ACR.
+ * `registry-login` — explicit `docker login` to the integrator-distribution ACR
+ * as the shared Microsoft Entra application.
  *
  * A thin wrapper over {@link ensureRegistryAuth}: it always forces a fresh login
  * (`force: true`, skipping the no-op probe) so the integrator can pre-seed or
- * refresh the credential at will (FR-ORC-047). Credentials follow the lib's own
- * precedence — `--registry`/`--user`/`--password` flags, then the
- * `JARVIS_REGISTRY_USER`/`JARVIS_REGISTRY_PASSWORD` env vars, then a masked
- * prompt — and are persisted by Docker's own credential store, so this is a
- * once-per-machine step (SC-ORC-008). No secret is written by the orchestrator.
+ * refresh the credential at will (FR-ORC-047). The client secret follows the lib's
+ * own precedence — the `--client-secret` flag, then the `JARVIS_CLIENT_SECRET` env
+ * var, then the stored copy (OS keychain / fallback file), then a masked prompt —
+ * and the resulting `docker login` is persisted by Docker's own credential store,
+ * so this is a once-per-machine step (SC-ORC-008).
  *
  * This is **Docker registry auth**, distinct from the Jarvis dev-`login` command
  * (browser impersonation).

package/dist/commands/registry-login.js

@@ -1,15 +1,16 @@
 import { ensureRegistryAuth, DEFAULT_REGISTRY, } from '../lib/registry.js';
 import { progress } from '../lib/progress.js';
 /**
- * `registry-login` — explicit `docker login` to the integrator-distribution ACR.
+ * `registry-login` — explicit `docker login` to the integrator-distribution ACR
+ * as the shared Microsoft Entra application.
  *
  * A thin wrapper over {@link ensureRegistryAuth}: it always forces a fresh login
  * (`force: true`, skipping the no-op probe) so the integrator can pre-seed or
- * refresh the credential at will (FR-ORC-047). Credentials follow the lib's own
- * precedence — `--registry`/`--user`/`--password` flags, then the
- * `JARVIS_REGISTRY_USER`/`JARVIS_REGISTRY_PASSWORD` env vars, then a masked
- * prompt — and are persisted by Docker's own credential store, so this is a
- * once-per-machine step (SC-ORC-008). No secret is written by the orchestrator.
+ * refresh the credential at will (FR-ORC-047). The client secret follows the lib's
+ * own precedence — the `--client-secret` flag, then the `JARVIS_CLIENT_SECRET` env
+ * var, then the stored copy (OS keychain / fallback file), then a masked prompt —
+ * and the resulting `docker login` is persisted by Docker's own credential store,
+ * so this is a once-per-machine step (SC-ORC-008).
  *
  * This is **Docker registry auth**, distinct from the Jarvis dev-`login` command
  * (browser impersonation).
@@ -21,27 +22,24 @@ import { progress } from '../lib/progress.js';
 export function registerRegistryLoginCommand(program) {
     program
         .command('registry-login')
-        .description('Authenticate Docker against the Jarvis image registry (once per machine). ' +
-        'Prompts for an ACR repository-scoped token (token name + password) unless ' +
-        'supplied via flags or the JARVIS_REGISTRY_USER/JARVIS_REGISTRY_PASSWORD env vars.')
+        .description('Authenticate Docker against the Jarvis image registry (once per machine) as the ' +
+        'Microsoft Entra application. Uses the client secret from --client-secret, the ' +
+        'JARVIS_CLIENT_SECRET env var, the stored secret, or a masked prompt.')
         .option('--registry <registry>', 'registry host to log in to (defaults to the integrator ACR)')
-        .option('--user <user>', 'ACR repository-scoped token name (username)')
-        .option('--password <password>', 'long-lived token password')
+        .option('--client-secret <secret>', 'the Entra application client secret')
         .action(async (opts) => {
         // Force a fresh login; pass only the flags the integrator actually supplied
-        // so absent ones fall through to the lib's env → masked-prompt precedence.
+        // so absent ones fall through to the lib's env → stored → prompt precedence.
         const authOptions = { force: true };
         if (opts.registry !== undefined)
             authOptions.registry = opts.registry;
-        if (opts.user !== undefined)
-            authOptions.user = opts.user;
-        if (opts.password !== undefined)
-            authOptions.password = opts.password;
+        if (opts.clientSecret !== undefined)
+            authOptions.clientSecret = opts.clientSecret;
         const registry = opts.registry ?? DEFAULT_REGISTRY;
         progress(`Logging Docker in to ${registry}…`);
         await ensureRegistryAuth(authOptions);
         // The lib throws on failure, so reaching here means the login succeeded —
-        // confirm it explicitly (creds may have come from flags/env with no prompt).
+        // confirm it explicitly (the secret may have come from a flag/env with no prompt).
         progress(`Logged in to ${registry}. Docker will reuse this credential.`);
     });
 }

package/dist/commands/registry-login.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry-login.js","sourceRoot":"","sources":["../../src/commands/registry-login.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAgB;IAC3D,OAAO;SACJ,OAAO,CAAC,gBAAgB,CAAC;SACzB,WAAW,CACV,4EAA4E;QAC1E,4EAA4E;QAC5E,mFAAmF,CACtF;SACA,MAAM,CAAC,uBAAuB,EAAE,6DAA6D,CAAC;SAC9F,MAAM,CAAC,eAAe,EAAE,6CAA6C,CAAC;SACtE,MAAM,CAAC,uBAAuB,EAAE,2BAA2B,CAAC;SAC5D,MAAM,CAAC,KAAK,EAAE,IAA6D,EAAE,EAAE;QAC9E,4EAA4E;QAC5E,2EAA2E;QAC3E,MAAM,WAAW,GAA8B,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC/D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACtE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAEtE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QACnD,QAAQ,CAAC,wBAAwB,QAAQ,GAAG,CAAC,CAAC;QAC9C,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACtC,0EAA0E;QAC1E,6EAA6E;QAC7E,QAAQ,CAAC,gBAAgB,QAAQ,sCAAsC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"registry-login.js","sourceRoot":"","sources":["../../src/commands/registry-login.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAgB;IAC3D,OAAO;SACJ,OAAO,CAAC,gBAAgB,CAAC;SACzB,WAAW,CACV,kFAAkF;QAChF,gFAAgF;QAChF,sEAAsE,CACzE;SACA,MAAM,CAAC,uBAAuB,EAAE,6DAA6D,CAAC;SAC9F,MAAM,CAAC,0BAA0B,EAAE,qCAAqC,CAAC;SACzE,MAAM,CAAC,KAAK,EAAE,IAAkD,EAAE,EAAE;QACnE,4EAA4E;QAC5E,6EAA6E;QAC7E,MAAM,WAAW,GAA8B,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC/D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QACtE,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAElF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QACnD,QAAQ,CAAC,wBAAwB,QAAQ,GAAG,CAAC,CAAC;QAC9C,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACtC,0EAA0E;QAC1E,mFAAmF;QACnF,QAAQ,CAAC,gBAAgB,QAAQ,sCAAsC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/start.d.ts

@@ -1,5 +1,14 @@
 import type { Command } from 'commander';
 import { type SeedSqlOptions } from '../lib/sql.js';
+/** Resolution for a new environment whose compose project name already exists in docker. */
+export type ProjectCollisionResolution = {
+    action: 'replace';
+} | {
+    action: 'rename';
+    newName: string;
+} | {
+    action: 'abort';
+};
 /** Options for {@link runStart}. */
 export interface StartOptions {
     /** Scenario folder (positional arg); defaults to the current working dir. */
@@ -23,6 +32,15 @@ export interface StartOptions {
      * to `lib/sql`'s {@link seedSql}.
      */
     seedSqlImpl?: (options: SeedSqlOptions) => Promise<void>;
+    /**
+     * Injectable collision prompt, invoked on a brand-new environment (no persisted
+     * state) whose resolved project name already has containers/volumes in docker.
+     * Defaults to an `@inquirer` select+input (mirrors `resolveImageTag`'s injected
+     * `promptForTag`); pinned by the unit tests. The default throws when stdin is
+     * not a TTY, so a non-interactive run fails with an actionable message instead
+     * of an opaque prompt error.
+     */
+    onProjectNameCollision?: (project: string) => Promise<ProjectCollisionResolution>;
 }
 /**
  * Bring up a fully-working, logged-in environment in one command. See module docs

package/dist/commands/start.js

@@ -1,10 +1,11 @@
 import { writeFileSync } from 'node:fs';
 import * as path from 'node:path';
+import { input, select } from '@inquirer/prompts';
 import { prepareScenario } from '../lib/scenario.js';
 import { provisionConfigs, provisionConfigsFromSeed, missingConfigs } from '../lib/config.js';
 import { resolveImageTag, DEFAULT_BASE_TAG } from '../lib/registry.js';
 import { readMongoCreds, generateEnv, templatePath, DEFAULT_SQL_SA_PASSWORD } from '../lib/compose.js';
-import { composeUp, listComposeServices } from '../lib/docker.js';
+import { composeUp, composeProjectExists, destroyComposeProject, dockerPull, listComposeServices, } from '../lib/docker.js';
 import { writeExternalServicesCompose, externalComposePath } from '../lib/external-services.js';
 import { mergeProxyConfig } from '../lib/proxy-merge.js';
 import { findBackupFile, seedSql } from '../lib/sql.js';
@@ -13,9 +14,10 @@ import { restore, isArtifactPresent } from '../lib/restore.js';
 import { waitForProxy, pollReindexProgress, REINDEX_BANNER } from '../lib/health.js';
 import { waitPortFree, allocatePortBlock, allocateAttachedPorts } from '../lib/ports.js';
 import { OPTIONAL_PROFILE_PORTS, optionalComposeServices, isOptionalProfile } from '../lib/profiles.js';
-import { progress, createProgressBar } from '../lib/progress.js';
+import { progress, createProgressBar, createSpinner } from '../lib/progress.js';
+import { gray } from '../lib/terminal-style.js';
 import { buildLoginUrl, ADMIN_EMAIL, USER_EMAIL } from './login.js';
-import { readState, readSeedState, writeState, defaultProjectName, envFilePath, } from '../lib/state.js';
+import { readState, readSeedState, writeState, defaultProjectName, sanitizeProjectName, envFilePath, } from '../lib/state.js';
 /**
  * start.ts — `jarvis-launcher start [folder] [--sql] [--mail] [--force]` (T-2-22).
  *
@@ -181,6 +183,76 @@ async function persistedPortsStillFree(ports) {
     const results = await Promise.all(persistedPorts.map((port) => waitPortFree(port)));
     return results.every((free) => free);
 }
+/**
+ * Default {@link StartOptions.onProjectNameCollision}: ask the integrator how to
+ * proceed when docker already holds an environment under the resolved project
+ * name. Non-interactive runs (no TTY) fail fast with an actionable message —
+ * nothing has been started or modified at this point.
+ */
+async function promptProjectNameCollision(project) {
+    if (!process.stdin.isTTY) {
+        throw new Error(`There is already an environment named "${project}" (leftover containers or data ` +
+            `volumes from a previous environment). Re-run interactively to choose what to do, ` +
+            `use a different folder name, or remove the existing environment first. ` +
+            `Nothing was started.`);
+    }
+    const action = await select({
+        message: `There is already an environment named "${project}". How do you want to proceed?`,
+        choices: [
+            {
+                name: `Permanently delete the existing "${project}" environment and create a fresh one`,
+                value: 'replace',
+            },
+            { name: 'Create this environment under a different name', value: 'rename' },
+            { name: 'Abort — leave everything untouched', value: 'abort' },
+        ],
+    });
+    if (action !== 'rename')
+        return { action };
+    const newName = await input({ message: 'New project name', default: `${project}-2` });
+    return { action: 'rename', newName };
+}
+/**
+ * Resolve the compose project name for a BRAND-NEW environment. Compose keys
+ * everything off `-p <project>`, so a new folder whose name matches an existing
+ * stack would silently adopt that stack's containers, network and data volumes.
+ * Probe docker for any footprint of the candidate name and, on a collision, ask
+ * the integrator (via `prompt`) to replace the leftover environment, pick a
+ * different name (re-probed — the new name may itself collide), or abort.
+ *
+ * A probe failure (docker engine unreachable) returns the name as-is: a
+ * read-only check must never abort `start` — the later `composeUp` surfaces the
+ * real engine error (mirrors {@link isProjectRunning}).
+ */
+async function resolveNewProjectName(initial, prompt) {
+    let project = initial;
+    for (;;) {
+        let exists;
+        try {
+            exists = await composeProjectExists(project);
+        }
+        catch {
+            return project;
+        }
+        if (!exists)
+            return project;
+        const resolution = await prompt(project);
+        if (resolution.action === 'abort') {
+            throw new Error(`Aborted: docker already has an environment named "${project}". Nothing was started.`);
+        }
+        if (resolution.action === 'replace') {
+            progress(`Deleting the existing "${project}" docker environment (containers + data volumes)…`);
+            await destroyComposeProject(project);
+            return project;
+        }
+        const requested = resolution.newName.trim() || `${project}-2`;
+        const sanitized = sanitizeProjectName(requested);
+        if (sanitized !== requested) {
+            progress(`Project name sanitized to "${sanitized}".`);
+        }
+        project = sanitized;
+    }
+}
 /**
  * Bring up a fully-working, logged-in environment in one command. See module docs
  * for the load-bearing ordering (FR-ORC-011).
@@ -212,6 +284,17 @@ export async function runStart(options) {
     // Only consulted when there is NO persisted state — an already-started scenario is
     // driven entirely by its own `.orchestrator/state.json`. Explicit flags win over it.
     const seedState = persistedState === null ? await readSeedState(base) : null;
+    // 1a. Resolve the compose project name — persisted, else seed-pinned, else derived
+    //     from the folder basename. On a BRAND-NEW environment, probe docker for a
+    //     leftover same-named stack FIRST (before the registry or configs are touched,
+    //     so an abort leaves no trace): compose would otherwise silently adopt its
+    //     containers and data volumes. A folder that only ever ran `init` carries a
+    //     state file and skips this gate — same `persistedState === null` signal as the
+    //     stale-volume / brand-new-folder SQL paths below.
+    let project = persistedState?.projectName ?? seedState?.projectName ?? defaultProjectName(base);
+    if (persistedState === null) {
+        project = await resolveNewProjectName(project, options.onProjectNameCollision ?? promptProjectNameCollision);
+    }
     // 1b. Resolve the image tag ONCE up front. The tag is the explicit `--tag`, else
     //     the tag remembered in state (so a non-`latest` tag is picked just once), else
     //     the seed's tag on a brand-new environment, else the arch-correct `latest`.
@@ -223,6 +306,26 @@ export async function runStart(options) {
     const { baseTag, image } = await resolveImageTag({
         baseTag: options.tag ?? persistedState?.tag ?? seedState?.tag,
     });
+    // 1c. New environment: a locally cached image for the resolved tag may be stale —
+    //     compose's default `missing` pull policy would silently reuse it, the moving
+    //     `latest` in particular. Refresh it explicitly so a brand-new environment
+    //     always starts on the newest published build; this also freshens the image
+    //     the auto-init below copies configs from. `docker pull` is a fast no-op when
+    //     the local image is already current. A failure is downgraded to a warning:
+    //     `resolveImageTag` just proved the tag reachable, so a failure here is
+    //     transient, and compose falls back to the cached image (or surfaces the real
+    //     error itself when none exists). Routine restarts of an EXISTING environment
+    //     never pull — `update` stays the deliberate refresh path.
+    if (persistedState === null) {
+        progress(`Pulling ${image} so the new environment starts on the newest build…`);
+        try {
+            await dockerPull(image);
+        }
+        catch (error) {
+            progress(`⚠️  Could not pull ${image} — continuing with the locally cached image.\n` +
+                `${error.message}`);
+        }
+    }
     // 2. Config absent → auto-init by calling the LIBs directly (FR-ORC-038),
     //    seed-first: a seed-shipped `seed/config/` wins over the image copies, the
     //    image fills whatever the seed did not provide. This runs BEFORE
@@ -243,9 +346,8 @@ export async function runStart(options) {
     // 3. Read Mongo creds ONCE (R-ORC2) — used by the empty-check + restore below.
     const mongoCreds = readMongoCreds(base);
     // Enabled profiles: union of the persisted (or, on a brand-new environment, the
-    // seed-declared) set and the requested --sql/--mail. The project name likewise
-    // falls back to the seed's before the folder-derived default.
-    const project = persistedState?.projectName ?? seedState?.projectName ?? defaultProjectName(base);
+    // seed-declared) set and the requested --sql/--mail. The project name was
+    // resolved (and collision-checked) in step 1a above.
     const network = networkFor(project);
     const profiles = mergeProfiles(persistedState?.enabledProfiles ?? seedState?.enabledProfiles, options);
     // 4. Ports: re-probe persisted block; re-allocate + rewrite state if any taken
@@ -444,13 +546,21 @@ export async function runStart(options) {
     progress('Starting Jarvis…');
     await composeUp({ project, template: templates, envFile, services: ['jarvis'], wait: true, image });
     // 9. Gate the report on the readiness poll (R-ORC8 — clear timeout, never a hang).
-    progress('Waiting for Jarvis to be ready…');
-    await waitForProxy(ports.proxy);
+    //    The poll is silent for up to 5 minutes, so it runs behind a spinner with a
+    //    live elapsed counter; `done()` in the finally settles the line whether the
+    //    proxy came up or the timeout error is about to surface.
+    const readiness = createSpinner('Waiting for Jarvis to be ready…', { showElapsed: true });
+    try {
+        await waitForProxy(ports.proxy);
+    }
+    finally {
+        readiness.done();
+    }
     reportAccess({ ports, profiles, externalServices });
     // After a restore the env is never presented as fully ready: print the banner +
     // best-effort reindex poll (FR-ORC-036, SC-ORC-003). The poll never throws.
     if (didRestore) {
-        console.log(REINDEX_BANNER);
+        console.log(gray(REINDEX_BANNER));
         await pollReindexProgress(ports.es);
     }
 }