jarvis-launcher 0.1.0 → 1.0.0

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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"}

package/dist/commands/backup.d.ts

@@ -0,0 +1,53 @@
+import type { Command } from 'commander';
+/**
+ * commands/backup.ts — snapshot a scenario's current state into its seed folder.
+ *
+ * `backup [folder]` is the inverse of `restore`: it persists the running
+ * scenario's Mongo data (as `seed/dump`), document-store files (`seed/dsdata`)
+ * and automation assets (`seed/automation`) — making `seed/` the exact,
+ * re-restorable artifact `restore` consumes. The previous snapshot is replaced
+ * automatically; safety comes from staging, not a gate: the engine
+ * (`lib/backup.ts`) stages everything first and swaps only after the dump
+ * verifiably holds payload, so a failure leaves `seed/` untouched.
+ *
+ * Ordering mirrors `runRestore` step-for-step: `mongo` is brought up and awaited
+ * healthy BEFORE the dump (the ephemeral mongodump container needs a reachable
+ * `mongo` on the compose project network) — `es`/`jarvis` are not needed and not
+ * started. One extra guard the restore doesn't have: the empty-check runs in
+ * REVERSE — an **empty** database means there is nothing to back up, so the
+ * command refuses rather than letting an empty dump clobber a good seed.
+ *
+ * Mongo creds are read ONCE here (`compose.readMongoCreds`, R-ORC2) and passed
+ * to both the empty-check and the backup — nothing hard-codes a second copy.
+ */
+/** Options for {@link runBackup}. */
+export interface RunBackupOptions {
+    /** Scenario folder (default: CWD, resolved in `lib/scenario`). */
+    folder?: string;
+}
+/** Summary of seed artifacts written by {@link runBackup}. */
+export interface RunBackupResult {
+    /** Absolute path to the Mongo dump artifact. */
+    dumpPath: string;
+    /** Absolute path to the document-store artifact when it was refreshed. */
+    dsdataPath: string | null;
+    /** Absolute path to the automation artifact when it was refreshed. */
+    automationPath: string | null;
+    /** Files snapshotted into `seed/dsdata` (0 when `data/ds` was absent). */
+    dsFiles: number;
+    /** Top-level entries snapshotted into `seed/automation` (0 when absent). */
+    automationEntries: number;
+}
+/**
+ * Run the seed-snapshot backup for a scenario folder.
+ *
+ * @throws when the scenario was never started (no persisted state) or its
+ * database is empty (the caller maps this to a clear message + non-zero exit in
+ * `cli.ts`).
+ */
+export declare function runBackup(options?: RunBackupOptions): Promise<RunBackupResult>;
+/**
+ * Register the `backup` subcommand on the commander program (wired by `cli.ts`).
+ * `folder` is an optional positional defaulting to CWD.
+ */
+export declare function registerBackupCommand(program: Command): void;

package/dist/commands/backup.js

@@ -0,0 +1,113 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { composeUp, composeStop, listComposeServices } from '../lib/docker.js';
+import { fetchListDatabases, isJarvisDataPresent } from '../lib/mongo.js';
+import { generateEnv, readMongoCreds, templatePath } from '../lib/compose.js';
+import { backup } from '../lib/backup.js';
+import { readState, defaultProjectName, envFilePath } from '../lib/state.js';
+import { resolveScenario } from '../lib/scenario.js';
+import { progress, createProgressBar } from '../lib/progress.js';
+/**
+ * Run the seed-snapshot backup for a scenario folder.
+ *
+ * @throws when the scenario was never started (no persisted state) or its
+ * database is empty (the caller maps this to a clear message + non-zero exit in
+ * `cli.ts`).
+ */
+export async function runBackup(options = {}) {
+    const base = resolveScenario(options.folder);
+    // Single source of Mongo creds (R-ORC2): read once, pass everywhere.
+    const creds = readMongoCreds(base);
+    // A backup needs a started stack: the compose project name is persisted by
+    // `start`. With no state (never started) there is nothing to back up — fail
+    // fast with a clear, actionable message BEFORE any composeUp, mirroring
+    // `restore`/`stop`.
+    const state = await readState(base);
+    if (state === null) {
+        throw new Error(`No started stack found for "${base}" (no .orchestrator/state.json). ` +
+            'Run `jarvis-launcher start` first, then `backup`.');
+    }
+    const project = state.projectName ?? defaultProjectName(base);
+    const network = `${project}_default`;
+    const profiles = state.enabledProfiles ?? [];
+    // Regenerate the orchestrator-owned `.env` before any compose call (the
+    // template substitutes from it) — verbatim the restore pattern.
+    const template = templatePath();
+    const envFile = envFilePath(base);
+    const env = generateEnv({ base, state, tag: 'latest', profiles });
+    writeFileSync(envFile, env);
+    // Bring mongo up healthy BEFORE the empty-check/dump. `mongo` is a PUBLIC
+    // image (`mongo:6.0.15`) and the backup never starts `jarvis` at all, so the
+    // bring-up must NOT be auth-gated (same rationale as restore's).
+    progress('Starting MongoDB — waiting until it is healthy…');
+    await composeUp({
+        project,
+        template,
+        envFile,
+        services: ['mongo'],
+        wait: true,
+        authGate: false,
+    });
+    // The reverse of restore's gate: an EMPTY database means there is nothing to
+    // back up — refuse, so an empty dump can never clobber a good seed snapshot.
+    progress('Checking that the database has data to back up…');
+    const listDatabases = await fetchListDatabases({ creds, network });
+    if (!isJarvisDataPresent(listDatabases)) {
+        throw new Error('Nothing to back up: the scenario database is empty. ' +
+            'The existing seed folder was left untouched.');
+    }
+    // Render the engine's phase updates as one in-place progress bar (percentage +
+    // running status) instead of the raw mongodump chatter; warnings are collected
+    // and flushed AFTER the bar closes so they never corrupt the in-place render.
+    const bar = createProgressBar({ label: 'Backing up' });
+    const warnings = [];
+    const result = await backup({
+        base,
+        creds,
+        network,
+        onProgress: (update) => bar.update(update.percent, update.message),
+        onWarn: (message) => warnings.push(message),
+    });
+    bar.done();
+    for (const warning of warnings)
+        progress(`⚠️  ${warning}`);
+    const parts = ['seed/dump (mongo)'];
+    if (result.dsFiles > 0)
+        parts.push(`seed/dsdata (${result.dsFiles} document-store files)`);
+    if (result.automationEntries > 0)
+        parts.push('seed/automation');
+    progress(`Seed snapshot updated: ${parts.join(', ')}.`);
+    const backupResult = {
+        dumpPath: join(base, 'seed', 'dump'),
+        dsdataPath: result.dsFiles > 0 ? join(base, 'seed', 'dsdata') : null,
+        automationPath: result.automationEntries > 0 ? join(base, 'seed', 'automation') : null,
+        dsFiles: result.dsFiles,
+        automationEntries: result.automationEntries,
+    };
+    // The backup brought `mongo` up on its own to run the dump. Now that it's done,
+    // leave the environment as we found it: if the stack is NOT in a running state
+    // — the `jarvis` proxy is down, which is exactly how `lib/status` defines
+    // "running" — then that `mongo` was started solely for this backup, so stop the
+    // mongo container it spun up. When the stack IS running, `mongo` belongs to it
+    // and must stay up. `listComposeServices` is a read-only `docker ps` probe.
+    const running = await listComposeServices(project);
+    if (!running.includes('jarvis')) {
+        progress('Stopping MongoDB — it was started only for this backup…');
+        await composeStop({ project, template, envFile, services: ['mongo'] });
+    }
+    return backupResult;
+}
+/**
+ * Register the `backup` subcommand on the commander program (wired by `cli.ts`).
+ * `folder` is an optional positional defaulting to CWD.
+ */
+export function registerBackupCommand(program) {
+    program
+        .command('backup [folder]')
+        .description("Snapshot the running scenario's Mongo data, document-store files and automation assets " +
+        'into the seed folder (replaces the previous snapshot).')
+        .action(async (folder) => {
+        await runBackup({ folder });
+    });
+}
+//# sourceMappingURL=backup.js.map

package/dist/commands/backup.js.map

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

package/dist/commands/enable.d.ts

@@ -0,0 +1,24 @@
+import { type OptionalProfile } from '../lib/profiles.js';
+import { type SeedSqlOptions } from '../lib/sql.js';
+/** Inputs for {@link enable}. */
+export interface EnableOptions {
+    /** Scenario folder (default: CWD). */
+    folder?: string;
+    /** Optional service to attach. */
+    service: OptionalProfile;
+    /**
+     * Bring the service up now (default true). When the stack is not yet running
+     * (no persisted state) pass `false` to only persist the profile for the next
+     * `start`.
+     */
+    start?: boolean;
+    /** Injectable SQL-seed flow (default: `lib/sql`'s {@link seedSql}); tests pin it. */
+    seedSqlImpl?: (options: SeedSqlOptions) => Promise<void>;
+}
+/**
+ * Enable an optional service on a scenario stack — see the module doc for the
+ * ordered behavior. Persists the profile, regenerates `.env`, and (when running)
+ * attaches the single service without recreating the core stack; for `sql`,
+ * seeds from `<base>/seed/sqlbackup` when a `.bak` is present.
+ */
+export declare function enable(options: EnableOptions): Promise<void>;

package/dist/commands/enable.js

@@ -0,0 +1,169 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { readState, writeState, defaultProjectName, envFilePath } from '../lib/state.js';
+import { generateEnv, templatePath, DEFAULT_SQL_SA_PASSWORD } from '../lib/compose.js';
+import { composeUp } from '../lib/docker.js';
+import { allocateAttachedPorts } from '../lib/ports.js';
+import { OPTIONAL_PROFILE_PORTS } from '../lib/profiles.js';
+import { findBackupFile, seedSql } from '../lib/sql.js';
+import { progress, createProgressBar } from '../lib/progress.js';
+/**
+ * commands/enable.ts — attach an optional service (`sql` | `mail`) to a scenario
+ * (T-2-19).
+ *
+ * `enable [folder] <sql|mail>`:
+ *  1. resolve the folder (default CWD) → project name from persisted state;
+ *  2. add the requested profile to `state.enabledProfiles` and persist it
+ *     (so a not-yet-running stack activates it on the next `start`);
+ *  3. regenerate `<base>/.orchestrator/.env` with the updated `COMPOSE_PROFILES`;
+ *  4. `docker compose up -d <service>` scoped to **only** the optional service —
+ *     which attaches it to the existing project **without recreating** the core
+ *     `jarvis`/`mongo`/`es` containers (FR-ORC-042);
+ *  5. for `sql`: when `<base>/seed/sqlbackup` holds a `.bak`, run the SQL-seed flow
+ *     (FR-ORC-029); with no `.bak` the container is still started and reachable
+ *     but not seeded (FR-ORC-028).
+ *
+ * `mail` (FR-ORC-030) needs no seed step — its env wiring already lives in
+ * `compose.generateEnv` (T-2-11); enabling the profile is enough to activate the
+ * mail container + those vars.
+ *
+ * The SQL-seed *logic* (`buildRestoreSql`, the `.bak`-presence guard, the live
+ * `seedSql` flow) lives in `lib/sql.ts` — a pure, unit-tested seam plus a
+ * DEFERRED live integration half — so BOTH `enable sql` and `start --sql` reuse
+ * it without importing one another.
+ *
+ * This command imports only `lib/*` — never another command (the command files
+ * stay mutually independent so the phase builds in parallel).
+ */
+/**
+ * Ensure `ports` carries a host port for every port the enabled `service`
+ * publishes ({@link OPTIONAL_PROFILE_PORTS}), allocating only the ones not already
+ * persisted (idempotent — a re-`enable` keeps the existing port and never rebinds).
+ * New ports slot into the scenario's contiguous base+offset block when free
+ * (base = the persisted proxy port), else an OS-assigned free port. Returns `ports`
+ * unchanged when all are already present. This is what backs the persisted
+ * `state.ports.sql`/`mailUi` so the container binds a known host port AND the
+ * homepage status header can surface the service's port + connect URL (without it
+ * the `.env` port renders empty, the container binds a random host port, and the
+ * header drops the row).
+ */
+async function ensurePortsFor(ports, service) {
+    const needed = OPTIONAL_PROFILE_PORTS[service].filter(({ stateKey }) => ports[stateKey] === undefined);
+    if (needed.length === 0) {
+        return ports;
+    }
+    const allocated = await allocateAttachedPorts(ports.proxy, needed.map(({ portKey }) => portKey));
+    const next = { ...ports };
+    for (const { portKey, stateKey } of needed) {
+        next[stateKey] = allocated[portKey];
+    }
+    return next;
+}
+/**
+ * Enable an optional service on a scenario stack — see the module doc for the
+ * ordered behavior. Persists the profile, regenerates `.env`, and (when running)
+ * attaches the single service without recreating the core stack; for `sql`,
+ * seeds from `<base>/seed/sqlbackup` when a `.bak` is present.
+ */
+export async function enable(options) {
+    const { service, start = true } = options;
+    const seedSqlImpl = options.seedSqlImpl ?? seedSql;
+    const base = resolve(options.folder ?? process.cwd());
+    // 1. Read state (regenerable; absent ⇒ stack never started). Derive the
+    //    project name from state or the folder default.
+    const existing = await readState(base);
+    const projectName = existing?.projectName ?? defaultProjectName(base);
+    // The stack is "running" only when it has been started (persisted state with a
+    // real port block exists). With no state we must never synthesize placeholder
+    // `0` ports nor `composeUp` (that would publish an invalid `0:80`); we only
+    // record the profile so the next `start` activates it — regardless of the
+    // `start` flag the caller passed (FR-ORC-042, T-2-19).
+    const stackRunning = existing !== null;
+    const shouldStart = start && stackRunning;
+    // 2. Add the profile to the persisted set (idempotent) and persist.
+    const previousProfiles = existing?.enabledProfiles ?? [];
+    const enabledProfiles = previousProfiles.includes(service)
+        ? previousProfiles
+        : [...previousProfiles, service];
+    // Carry the persisted ports when the stack is running, reserving a stable host
+    // port for the newly-enabled service (so the container binds a known port and the
+    // homepage status header can surface it — FR-ORC-042). When the stack is NOT
+    // running, persist an EMPTY port map: the next `start` re-probes, finds no real
+    // always-on ports, and allocates the whole block. Never synthesize placeholder
+    // `0` ports — a `0:80` publish is invalid and a persisted `0` would be reused.
+    let ports = existing?.ports ?? {};
+    if (shouldStart) {
+        ports = await ensurePortsFor(ports, service);
+    }
+    // Spread `existing` first so fields `enable` does not touch — notably the pinned
+    // image `tag` (and any future additive state) — survive; then override only the
+    // three this command owns. Dropping them would silently unpin the tag, so the
+    // next tag-less `start` falls back to `latest`. `{...null}` is `{}`, so this is
+    // also correct when the stack was never started.
+    const nextState = {
+        ...existing,
+        projectName,
+        ports,
+        enabledProfiles,
+    };
+    await writeState(base, nextState);
+    // When the stack is not running yet, persist-only: the profile activates on the
+    // next `start`. Nothing is brought up now.
+    if (!shouldStart) {
+        progress(`Enabled the "${service}" service — it will start on the next \`start\`.`);
+        return;
+    }
+    // 3. Regenerate the `.env` next to the persisted state with the updated
+    //    profiles so `COMPOSE_PROFILES` activates the optional container. Ensure
+    //    `.orchestrator/` exists (a not-yet-started folder may lack it).
+    const envFile = envFilePath(base);
+    await mkdir(dirname(envFile), { recursive: true });
+    const env = generateEnv({
+        base,
+        state: nextState,
+        tag: 'latest',
+        profiles: enabledProfiles,
+    });
+    await writeFile(envFile, env, 'utf8');
+    const template = templatePath();
+    // 4. Attach ONLY the optional service — scoped `up -d <service>` does NOT
+    //    recreate the always-on jarvis/mongo/es (FR-ORC-042).
+    //
+    //    Both optional services this command can enable are PUBLIC images (`sql` →
+    //    mcr.microsoft.com/mssql/server, `mail` → axllent/mailpit) and never pull the
+    //    authenticated `jarvis-dev` image, so skip the registry auth gate. Gating here
+    //    would probe the ACR against the default canary — the possibly-unpublished
+    //    `jarvis-dev:latest[-arm]` — and abort with a spurious "could not reach the
+    //    image registry" (`no such manifest`) even though nothing this up touches the
+    //    ACR (see ComposeUpOptions.authGate).
+    progress(`Starting the "${service}" container — waiting until it is healthy…`);
+    await composeUp({
+        project: projectName,
+        template,
+        envFile,
+        services: [service],
+        wait: true,
+        authGate: false,
+    });
+    // 5. SQL seeding (FR-ORC-029): only when a `.bak` is present. No `.bak` ⇒ the
+    //    container is up + reachable but not seeded (FR-ORC-028).
+    if (service === 'sql') {
+        const bakFile = await findBackupFile(join(base, 'seed', 'sqlbackup'));
+        if (bakFile) {
+            progress(`Seeding SQL Server from "${basename(bakFile)}"…`);
+            // Render the seed's phases as a single in-place progress bar (percentage +
+            // status), mirroring the Mongo restore, rather than the raw `sqlcmd` chatter.
+            const bar = createProgressBar({ label: 'Restoring SQL' });
+            await seedSqlImpl({
+                base,
+                bakFile,
+                project: projectName,
+                saPassword: DEFAULT_SQL_SA_PASSWORD,
+                onProgress: (update) => bar.update(update.percent, update.message),
+            });
+            bar.done();
+        }
+    }
+    progress(`The "${service}" service is ready.`);
+}
+//# sourceMappingURL=enable.js.map

package/dist/commands/enable.js.map

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

package/dist/commands/init.d.ts

@@ -0,0 +1,40 @@
+import type { Command } from 'commander';
+/**
+ * commands/init.ts — provision the three base config files into an empty or
+ * config-less scenario folder (FR-ORC-038/039/040).
+ *
+ * A thin command over `lib/scenario` + `lib/config`:
+ *
+ *  1. `scenario.prepareScenario(folder)` resolves the folder (default = CWD),
+ *     scaffolds the data subfolders idempotently, and runs the fail-fast
+ *     write-probe (on the base + the UID-sensitive `mongo/`/`es/` subpaths).
+ *     It throws on a non-writable folder and reports the config state.
+ *  2. A present-but-invalid config (unparseable, or a partially-present set) is
+ *     **never overwritten** (FR-ORC-040): we fail fast with a clear, actionable
+ *     message before touching anything.
+ *  3. `config.provisionConfigs({ base, image })` copies only the **absent**
+ *     configs out of the image's `/jarvis/reference/` — when all three are
+ *     already present it is a no-op (the image is not even pulled). The image
+ *     ref is **arch-correct** (`arch.imageTag('latest')`) so ARM hosts lift the
+ *     `-arm` variant (R-ORC11); auth is gated inside `lib/docker`.
+ *  4. We log which files were newly provisioned (the lib returns their names).
+ *
+ * `start` (T-2-22) calls the **same libs** directly when config is absent — it
+ * does NOT import this command (commands never import other commands).
+ */
+/**
+ * Run the `init` action against an optional scenario folder argument.
+ *
+ * @param folder - Scenario folder; when omitted, `lib/scenario` defaults to the
+ *   current working directory.
+ * @param tag - Optional base image tag to provision from; defaults to `latest`
+ *   inside `resolveImageTag` (which still prompts for an alternative if the chosen
+ *   tag turns out to be unpublished). `arch.imageTag` applies the `-arm` suffix.
+ */
+export declare function runInit(folder?: string, tag?: string): Promise<void>;
+/**
+ * Register the `init` subcommand on the commander program (called by cli.ts).
+ * `folder` is an optional positional that defaults to CWD (resolved in
+ * `lib/scenario`).
+ */
+export declare function registerInit(program: Command): void;