jarvis-launcher 0.1.0-alpha.43

package/README.md

@@ -0,0 +1,451 @@
+# jarvis-launcher
+
+`jarvis-launcher` is a cross-platform command-line tool that prepares a **scenario folder** and runs the full Jarvis stack around the published all-in-one image. It is a thin wrapper over `docker` / `docker compose` (plus a short-lived `mongo` container used only for restores) — it never re-implements what those tools already do.
+
+Your only inputs are a **folder** and a **command**. The launcher authors every compose / `.env` file for you, picks free host ports, provisions the base configuration out of the image, and (when a prepared dump is present) restores it before Jarvis starts serving.
+
+---
+
+## Prerequisites
+
+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**.
+
+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)).
+
+> **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.
+
+> **Note:** MongoDB, Elasticsearch and SQL Server data live on Docker **named volumes** (`<project>_mongo_data` / `<project>_es_data` / `<project>_sql_data`), not host bind-mounts. A macOS/Windows Docker Desktop bind-mount (grpcfuse) makes WiredTiger index builds fail intermittently with `Operation not permitted` (EPERM), which crashes Automation and wedges the stack; named volumes live on the Docker VM's native filesystem and avoid this. They also sidestep the raw-Linux non-root-UID bind-mount permission issue entirely (Docker initializes volume ownership for the container). Because the volumes survive `stop` (which never passes `-v`), a restored SQL database persists across a `stop`/`start` cycle — the seed itself only re-runs on a first start, a stale-volume replace, or an explicit `--sql` enable, never on a routine restart.
+
+---
+
+## Install
+
+From a published package:
+
+```bash
+npm install -g jarvis-launcher
+```
+
+Or run it directly without installing, via `npx`:
+
+```bash
+npx jarvis-launcher <command>
+```
+
+Or, running from a checkout of this repository:
+
+```bash
+npm install
+npm run build
+```
+
+This produces the `jarvis-launcher` executable (its bin is `dist/cli.js`). The examples below assume it is on your `PATH`; when running from source you can substitute `npm run dev --` for `jarvis-launcher`.
+
+---
+
+## Authenticate once: `registry-login`
+
+The all-in-one image lives in a private ACR, so Docker must be authenticated before the launcher can pull it. Run this **once per machine**:
+
+```bash
+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 can supply the credential non-interactively (e.g. in CI):
+
+```bash
+# via flags
+jarvis-launcher registry-login --user <token-name> --password <token-password>
+
+# or via environment variables
+export JARVIS_REGISTRY_USER=<token-name>
+export JARVIS_REGISTRY_PASSWORD=<token-password>
+jarvis-launcher registry-login
+```
+
+The credential-source precedence is **flags → environment variables → masked prompt**. `--registry <host>` overrides the default registry host if needed.
+
+> **`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.
+
+---
+
+## The scenario folder
+
+A **scenario folder** is the single root the launcher operates on. It is **both** the source of the three base config files **and** the host data root for Jarvis-owned files (document store, etc.) via the image's `/scenario` bind-mount. MongoDB and Elasticsearch data, by contrast, live on Docker **named volumes** (see the note above). Everything **survives teardown and recreate**: `stop`/`update` remove containers but never the host data or the named volumes (only `docker compose down -v` would wipe the volumes).
+
+The launcher creates the host data subfolders **idempotently** and **never wipes** existing content. Layout:
+
+```
+<scenario>/
+  jarvis-host-config.json     # base config — provisioned by init/start (copied from the image)
+  jarvis.proxy.json           #   "
+  jarvis.automation.json      #   "
+  data/                       # Jarvis-owned data (mounted as /scenario/data)
+  seed/                       # restore artifact: an inner dump/ (mongo bson.gz) + document-store files
+    state.json                # optional: pre-declared initial state — see "Pre-seeding the initial state"
+    dsdata/                   #   document-store tree (original/ artifacts/ avatars/ …) -> data/ds/*
+                              #   (legacy alternative: dstore/ -> data/ds/original)
+    automation/               # optional: Elsa automation assets -> data/automation
+                              #   (merged; a same-named sub-folder is replaced entirely)
+    sqlbackup/                # optional SQL Server .bak file(s)
+    externalservice_*/        # optional: your own companion service(s) — see "External services" below
+  .orchestrator/              # launcher-owned: state.json (persisted ports + project name) + generated .env
+
+# Mongo, Elasticsearch & SQL Server data are NOT here — they live on Docker named volumes:
+#   <project>_mongo_data  ->  /data/db
+#   <project>_es_data     ->  /usr/share/elasticsearch/data
+#   <project>_sql_data    ->  /var/opt/mssql   (only when the `sql` profile is active)
+```
+
+Notes:
+
+- The three `jarvis-*.json` configs are **lifted out of the image** (`/jarvis/reference/`); there is no bundled offline fallback. If the image is unreachable, provisioning fails fast with a clear error.
+- A **missing** config triggers auto-provisioning. A config that is **present but invalid** is **never overwritten** — the launcher fails fast so you can fix or remove it.
+- There is **no `automationrepo/`** folder — git-backed automation repos are not wired; automation uses the in-container default.
+- `.orchestrator/` is launcher-owned, regenerable state. Deleting it only means new host ports get chosen on the next `start`.
+
+### 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.
+
+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):
+
+```json
+{
+  "projectName": "cmms",
+  "enabledProfiles": ["sql"],
+  "tag": "1.2.3"
+}
+```
+
+| Property | Meaning | Default when omitted |
+|---|---|---|
+| `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` |
+
+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.
+
+---
+
+## Quick start (brand-new scenario)
+
+```bash
+mkdir my-scenario && cd my-scenario
+jarvis-launcher registry-login        # once per machine, if not already done
+jarvis-launcher start
+```
+
+`start` from an empty folder does everything for you:
+
+1. scaffolds the data subfolders and **auto-provisions** the three base configs from the image;
+2. **allocates a free, clustered block of host ports** and persists them (so the URL stays stable across restarts);
+3. brings up `mongo` + `es`, waits until they are healthy;
+4. **auto-restores** the prepared dump **if** one is present under `seed/` **and** the database is empty (an empty `seed/` or no seed at all is fine — Jarvis simply comes up with an empty database; a populated DB is left untouched — restore only on `--force`);
+5. starts `jarvis`, waits for the proxy to answer, then prints the access URLs and the dev-login links.
+
+After a restore, Elasticsearch repopulates in the background; the launcher prints a banner and best-effort indexing progress so you know search may be briefly incomplete.
+
+---
+
+## Commands
+
+`<folder>` is an **optional** positional on every command — it defaults to the **current working directory**, so `cd`-ing into the scenario folder and omitting it is the common case.
+
+| 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). |
+| [`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`). |
+| [`update`](#update) | `update [folder] --tag <T>` | Pull a new image tag and recreate the stack on it, preserving data. |
+| [`enable`](#enable) | `enable [folder] <sql\|mail>` | Attach an optional service (SQL Server or mail catcher) to the stack. |
+| [`login`](#login) | `login [folder] [--admin\|--user]` | Open the browser at the Jarvis dev-login (impersonation) URL. |
+
+### `init`
+
+```bash
+jarvis-launcher init [folder]
+```
+
+Resolves the folder (default: CWD), scaffolds the data subfolders, and copies any **absent** base config out of the image's `/jarvis/reference/`. It is only-if-absent: when all three configs already exist it is a no-op and the image is not even pulled. A present-but-invalid config is never overwritten — it fails fast instead.
+
+You rarely need `init` on its own — `start` performs the same provisioning automatically — but it is useful to lay down (and review) the configs before the first `start`.
+
+### `registry-login`
+
+```bash
+jarvis-launcher registry-login [--registry <host>] [--user <token-name>] [--password <token-password>]
+```
+
+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.
+
+### `start`
+
+```bash
+jarvis-launcher start [folder] [--sql] [--mail] [--force]
+```
+
+Brings up the full, logged-in environment in one command. See [Quick start](#quick-start-brand-new-scenario) for the brand-new-folder flow.
+
+| Flag | Effect |
+|---|---|
+| `--sql` | Also start the optional **SQL Server** service. If a `.bak` is present under `<folder>/seed/sqlbackup`, it is restored after the SQL container is healthy. |
+| `--mail` | Also start the optional **mail catcher** (catch-all SMTP + web UI). |
+| `--force` | Run the restore **even if the database already has data** (drops the existing data first). Without it, a populated DB is left as-is. |
+
+On success it prints the Web UI / API URL, both dev-login links, and the Mongo / ES (and optional SQL / mail) host ports. Enabled optional profiles are remembered, so a later plain `start` keeps them on.
+
+### `stop`
+
+```bash
+jarvis-launcher stop [folder]
+```
+
+Removes the scenario's containers (including any optional `sql`/`mail` ones) while **keeping all on-disk data** — it never passes `-v`/`--volumes`. The next `start` sees the data and performs no restore. If the scenario was never started, it reports there is nothing to stop and exits non-zero.
+
+### `restore`
+
+```bash
+jarvis-launcher restore [folder] [--force]
+```
+
+Explicitly reseeds Mongo / document-store / ES from the prepared artifact under `<folder>/seed`. It brings `mongo`+`es` up healthy first, then applies the gate:
+
+- **`--force`** → restore regardless of DB contents (drops non-system DBs first, then replaces the data).
+- **no `--force`, DB already populated** → **refuses** and changes nothing.
+- **no `--force`, DB empty** → restores.
+
+The artifact must live at `<folder>/seed/` and contain an inner `dump/` (the `mongorestore --gzip` payload). The document-store files are picked up from either `seed/dsdata/` — a full `data/ds` tree (`original/`, `artifacts/`, `avatars/`, …), copied subfolder-by-subfolder into `data/ds/*` — or, for backward compatibility, the legacy `seed/dstore/` (moved into `data/ds/original`). A missing/incomplete `dump/` aborts cleanly with a clear message; if neither document-store folder is present the restore proceeds but warns that stored blobs will be missing their files. If the artifact carries a `seed/automation/` folder, its contents are moved into `data/automation` (the container's `/scenario/data/automation`, Elsa's `AssetsLocation`): a top-level merge that overwrites same-named files, replaces a same-named sub-folder entirely, and leaves unrelated existing assets in place.
+
+### `update`
+
+```bash
+jarvis-launcher update [folder] --tag <tag>
+```
+
+Moves the stack to a new image tag, **preserving all data and without restoring**. It is **pull-first** so you are never left with no runnable environment:
+
+1. resolves the architecture-correct image variant (a `-arm` suffix is added automatically on ARM hosts) and **pulls it first** (re-authenticating + retrying once if needed);
+2. **only if the pull succeeds**, recreates the stack on the new image (down → up, data kept via the `/scenario` host mount and the Mongo/ES named volumes) — **no restore**, the existing data is reused;
+3. if the pull **fails** (typo, offline, unpublished tag, rejected credentials), it reports the error and **leaves the running stack untouched**.
+
+`--tag` is required (e.g. `--tag latest` or `--tag 1.2.3`).
+
+### `enable`
+
+```bash
+jarvis-launcher enable [folder] <sql|mail>
+```
+
+Attaches one optional service to the scenario and remembers it for future starts:
+
+- **`sql`** — starts the SQL Server service. When `<folder>/seed/sqlbackup` contains a `.bak`, it is restored into the database; with no `.bak`, the container is started and reachable but not seeded.
+- **`mail`** — starts a catch-all mail catcher (Mailpit); all outgoing mail is captured and viewable in its web UI. No seed step is needed.
+
+`enable` attaches **only** the requested service — it does not recreate the always-on `jarvis`/`mongo`/`es` containers. If the stack is not running yet, the profile is persisted and activates on the next `start`. (Enabling a service is equivalent to passing `--sql`/`--mail` to `start`.)
+
+### `login`
+
+```bash
+jarvis-launcher login [folder] [--admin|--user]
+```
+
+Opens your browser at the Jarvis **dev-login (impersonation)** URL through the scenario's persisted proxy port, so you can jump straight into a session:
+
+- `--admin` (default) — log in as the admin account;
+- `--user` — log in as the standard user account.
+
+This works because the image is built as a non-production / dev environment with forced-login enabled. It is a Jarvis application convenience and is **distinct from [`registry-login`](#registry-login)** (Docker registry authentication). The stack must already be started (otherwise there is no persisted port and the command fails with a clear message).
+
+---
+
+## Optional services
+
+Both optional services are off by default and can be turned on either at start time (`start --sql` / `start --mail`) or afterwards (`enable sql` / `enable mail`):
+
+- **SQL Server (`sql`)** — for scenarios that need the relational side. Drop a prepared `.bak` into `<folder>/seed/sqlbackup` and it is restored automatically the first time SQL is brought up, when the service is enabled with `--sql`, or on a brand-new folder (only a seed, no `.orchestrator/state.json`) — in that last case the restore **replaces** any leftover data from a reused `<project>_sql_data` volume, without needing `--force`, mirroring the Mongo auto-restore. A routine restart never re-seeds, so the persisted database is left untouched. Without a `.bak` the server is simply available and empty.
+- **Mail catcher (`mail`)** — a catch-all SMTP server with a web inbox (Mailpit). All mail Jarvis would send is intercepted there, so you can inspect notifications without a real mail server.
+
+---
+
+## External services
+
+Any folder under `<folder>/seed/` whose name starts with `externalservice_`
+is picked up automatically and brought up as an extra container alongside
+the Jarvis stack — no compose file to hand-edit. This is for your own
+companion services (a CMMS API, a mock third-party integration, …) that
+Jarvis or its automation should be able to reach on the compose network.
+It lives under `seed/`, grouped with the other integrator-supplied scenario
+resources (`dsdata/`, `automation/`, `sqlbackup/`) — a top-level folder is
+**not** picked up.
+
+```
+<scenario>/
+  seed/
+    externalservice_cmms.api/
+      Dockerfile              # your own — built as-is, context = this folder
+      jarvis-service.json     # tells the launcher how to wire the service in
+      ...                     # the service's own source
+```
+
+`jarvis-service.json`:
+
+```json
+{
+  "name": "cmms-api",
+  "dockerfile": "Dockerfile",
+  "ports": ["8080:80"],
+  "environment": {
+    "ASPNETCORE_ENVIRONMENT": "Development"
+  }
+}
+```
+
+`Dockerfile` — entirely yours, built as-is (the launcher only sets `build:
+{ context: <folder>, dockerfile: <this file> }`, nothing else). A typical
+.NET example:
+
+```dockerfile
+# Build stage
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /externalservice_cmms.api/src
+
+COPY . .
+RUN dotnet publish -c Release -r linux-x64 --self-contained false -o /externalservice_cmms.api/app/publish
+
+# Runtime stage
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+WORKDIR /externalservice_cmms.api/app
+
+COPY --from=build /externalservice_cmms.api/app/publish .
+
+ENTRYPOINT ["dotnet", "Cmms.Api.dll"]
+```
+
+All fields are optional:
+
+- **`name`** — the compose service name. Defaults to the folder name with
+  the `externalservice_` prefix stripped and sanitized (e.g.
+  `externalservice_cmms.api` → `cmms.api`).
+- **`dockerfile`** — path relative to the folder. Defaults to `Dockerfile`.
+- **`ports`** — `"host:container"` strings, published exactly as given
+  (host ports are **not** auto-allocated the way `sql`/`mail` are — pick a
+  port that's free on your machine). Omit for a service that's only reached
+  from inside the compose network, by service name.
+- **`environment`** — a flat map of environment variables passed to the
+  container as-is.
+
+### Exposing an external service through the Jarvis proxy
+
+An external service is reachable from `jarvis` over the compose network at
+`http://<service-name>:<container-port>/` (the compose service `name` from
+`jarvis-service.json`, and the port your app listens on **inside** the
+container — never the host-published one, and never `localhost`, which
+inside the `jarvis` container means the `jarvis` container itself).
+
+To route Jarvis's reverse proxy at that address, drop a `jarvis.proxy.json`
+**fragment** next to `Dockerfile`/`jarvis-service.json` in the same
+`externalservice_*` folder:
+
+```
+<scenario>/
+  seed/
+    externalservice_cmms.api/
+      Dockerfile
+      jarvis-service.json
+      jarvis.proxy.json        # NEW — proxy wiring fragment (optional)
+```
+
+```json
+{
+  "ReverseProxy": {
+    "Clusters": {
+      "jarvis-cmms": {
+        "Destinations": {
+          "jarvis-cmms/destination1": {
+            "Address": "http://cmms-api:5200/"
+          }
+        }
+      }
+    }
+  },
+  "ReverseProxyDynamicRoutes": {
+    "Routes": {
+      "cmms": {
+        "ClusterId": "jarvis-cmms",
+        "AuthorizationPolicy": "JarvisProxy",
+        "Match": { "Path": "/jarvis-cmms/{**catchall}" },
+        "Transforms": [{ "PathPattern": "/{**catchall}" }]
+      }
+    }
+  }
+}
+```
+
+The launcher merges this into the scenario's live `<folder>/jarvis.proxy.json`
+on every `start`/`update` (`lib/proxy-merge.ts`). Only three dict paths are
+ever touched: `ReverseProxy.Routes`, `ReverseProxy.Clusters`,
+`ReverseProxyDynamicRoutes.Routes` — everything else in that file (the base
+routes/clusters, anything you added by hand) is left alone. Rules:
+
+- an entry is only **added** the first time it appears — it's never
+  overwritten if something with the same id already exists there with
+  different content (you get a warning instead, so a name clash never
+  silently clobbers your own edits);
+- removing (or renaming) the `externalservice_*` folder removes the entries
+  it added on the next `start`/`update` — but only if you haven't hand-edited
+  them since (otherwise they're left in place with a warning);
+- `jarvis.proxy.json` at the scenario root stays the file you provisioned
+  once and can still edit directly — this only ever *adds to* it, and only
+  through the fragment above.
+
+The launcher scans for the compose overlay and (re)generates
+`.orchestrator/external-services.yml` on every `start`/`stop`/`update` — like
+`.orchestrator/state.json` and the `.env`, this file is launcher-owned and
+regenerable; never hand-edit it. A folder that's missing its `Dockerfile`,
+missing/malformed `jarvis-service.json`, or whose resolved name collides with
+another service (including the core `jarvis`/`mongo`/`es`/`sql`/`mail`
+names) is **skipped with a warning** — it never blocks the rest of the stack
+from starting. Removing or renaming the folder and running `start`/`stop`
+again tears its container down.
+
+Images are built the first time the service comes up; a later code change to
+the service is **not** picked up automatically on the next `start` — rebuild
+explicitly (e.g. `docker compose -p <project> build <service>`) or remove the
+built image first.
+
+---
+
+## Build and test (developing the launcher)
+
+```bash
+npm install        # install dependencies
+npm run build      # tsc → dist/ (this is the "does it compile" gate)
+npm test           # run the vitest unit suite
+```
+
+Docker/Mongo/ES-driven behavior (real `compose up/down`, copy-from-image, live restore, real `docker login`) is covered by integration/manual checks that require Docker and the published image; the unit suite covers the pure logic.
+
+---
+
+## 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`).
+- **"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/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function shouldRunHomepage(argv: string[], stdinIsTTY: boolean, stdoutIsTTY: boolean): boolean;
+export declare function isEntrypoint(modulePath: string, argv1: string | undefined, canonicalize?: (path: string) => string): boolean;

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { Command, CommanderError } from 'commander';
+import { registerInit } from './commands/init.js';
+import { registerRegistryLoginCommand } from './commands/registry-login.js';
+import { registerStartCommand } from './commands/start.js';
+import { registerStopCommand } from './commands/stop.js';
+import { registerRestoreCommand } from './commands/restore.js';
+import { registerBackupCommand } from './commands/backup.js';
+import { loginCommand } from './commands/login.js';
+import { update } from './commands/update.js';
+import { enable } from './commands/enable.js';
+import { OPTIONAL_PROFILES, isOptionalProfile } from './lib/profiles.js';
+import { runHomepage } from './homepage/home.js';
+// Read version from package.json at runtime. Using createRequire keeps this
+// compatible with NodeNext ESM without relying on a JSON import assertion
+// (which would also pull package.json into the emitted dist/ tree via rootDir).
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const program = new Command();
+program
+    .name('jarvis-launcher')
+    .description('Prepare a scenario folder and run the full Jarvis all-in-one stack via docker compose.')
+    .version(pkg.version);
+// --- subcommand registration (T-2-23) ---------------------------------------
+//
+// The command modules were built in parallel and expose intentionally
+// different shapes. `cli.ts` is the single place that knows about all of them and
+// reconciles those shapes onto one program (commands never import each other):
+//
+//   * `register…Command(program)` builders register themselves and return nothing
+//     useful to us — call them for their side effect: init, registry-login, start,
+//     stop, restore, backup.
+//   * `loginCommand()` returns a ready-made `Command` instance → `addCommand`.
+//   * `update` / `enable` export only an action function (no builder), so we
+//     declare the `program.command(...)` surface here and call the action.
+registerInit(program);
+registerRegistryLoginCommand(program);
+registerStartCommand(program);
+registerStopCommand(program);
+registerRestoreCommand(program);
+registerBackupCommand(program);
+program.addCommand(loginCommand());
+// `update [folder] --tag <tag>` — the action fn lives in commands/update.ts. The
+// tag is required (the update is meaningless without a target image tag).
+program
+    .command('update')
+    .description('Pull a new image tag and recreate the stack on it, preserving all data.')
+    .argument('[folder]', 'scenario folder (defaults to the current directory)')
+    .requiredOption('--tag <tag>', 'the image tag to update to (e.g. latest, 1.2.3)')
+    .action(async (folder, opts) => {
+    await update({ folder, tag: opts.tag });
+});
+// `enable [folder] <service>` — `service` is `sql` | `mail`. The action fn lives
+// in commands/enable.ts; we validate the positional here so an unknown service
+// yields a clear message + non-zero exit (mapped by the dispatcher below).
+program
+    .command('enable')
+    .description('Attach an optional service (sql | mail) to a scenario stack.')
+    .argument('[folder]', 'scenario folder (defaults to the current directory)')
+    .argument('<service>', 'optional service to enable: sql or mail')
+    .action(async (folder, service) => {
+    if (!isOptionalProfile(service)) {
+        throw new Error(`Unknown service "${service}". Expected one of: ${OPTIONAL_PROFILES.join(', ')}.`);
+    }
+    await enable({ folder, service });
+});
+// `help [command]` — print general usage, or the usage of a single command. The
+// argument is optional; with no argument it behaves like the top-level help.
+program
+    .command('help [command]')
+    .description('Display help for the CLI or for a specific command.')
+    .action((commandName) => {
+    if (!commandName) {
+        program.outputHelp();
+        return;
+    }
+    const sub = program.commands.find((c) => c.name() === commandName);
+    if (!sub) {
+        throw new Error(`Unknown command "${commandName}". Run "jarvis-launcher help" to list commands.`);
+    }
+    sub.outputHelp();
+});
+// --- no-args TTY dispatch (FR-HOME-001/002/003, SC-HOME-001/007) -------------
+//
+// "No subcommand" = only the node binary + this script path (`argv.length <= 2`).
+// The interactive homepage may only launch when BOTH stdin and stdout are real
+// TTYs (R-HOME5): a stdout-piped-but-stdin-a-TTY invocation must NOT hang waiting
+// on a keypress, so requiring both keeps the non-interactive path on the
+// help+exit branch below. Pure and exported so the three branches are unit-tested
+// with no TTY (see cli.test.ts).
+export function shouldRunHomepage(argv, stdinIsTTY, stdoutIsTTY) {
+    return argv.length <= 2 && Boolean(stdinIsTTY && stdoutIsTTY);
+}
+export function isEntrypoint(modulePath, argv1, canonicalize = realpathSync.native) {
+    if (!argv1) {
+        return false;
+    }
+    try {
+        return canonicalize(modulePath) === canonicalize(argv1);
+    }
+    catch {
+        return modulePath === argv1;
+    }
+}
+// --- error → message + non-zero exit (FR-ORC-034/035/046) -------------------
+//
+// Every command's action is async; commander surfaces a rejected action promise
+// out of `parseAsync`. We catch here and print only the error's `.message` —
+// which the libs build to carry surfaced execa stderr verbatim — never a raw
+// stack trace or an execa object dump. A `CommanderError` (e.g. a missing
+// required option, or `--version`/`--help` exit) is commander's own controlled
+// flow: it has already printed its message and chosen an exit code, so we honor
+// that exit code instead of re-printing.
+async function main() {
+    // No subcommand + a real interactive terminal ⇒ the always-on homepage
+    // (FR-HOME-001). Done BEFORE parseAsync so commander never sees the empty argv.
+    if (shouldRunHomepage(process.argv, Boolean(process.stdin.isTTY), Boolean(process.stdout.isTTY))) {
+        await runHomepage();
+        return;
+    }
+    // No subcommand but NOT interactive (piped / CI / non-TTY) ⇒ print help to
+    // stderr and exit non-zero, EXPLICITLY (FR-HOME-002, SC-HOME-007). Handled
+    // here rather than relying on commander's default no-args behavior so the
+    // help+non-zero guarantee can't regress with a commander version bump.
+    if (process.argv.length <= 2) {
+        program.outputHelp({ error: true });
+        process.exit(1);
+    }
+    // An explicit command ⇒ the existing dispatch path, completely unchanged
+    // (FR-HOME-003, FR-HOME-027), including the CommanderError → exit-code mapping.
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            process.exit(err.exitCode);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+// Run only when executed as the program entry point (not when imported by a
+// test). Comparing this module's file path to the invoked script (argv[1]) keeps
+// `import { shouldRunHomepage }` from cli.test.ts side-effect-free, so importing
+// the module never spawns the homepage or touches process.argv/exit.
+if (isEntrypoint(fileURLToPath(import.meta.url), process.argv[1])) {
+    void main();
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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