@endora-commerce/cli 0.100.0

package/dist/install/index.js

@@ -0,0 +1,793 @@
+/**
+ * `endora install <dir>` — one command from nothing to an installed Endora
+ * Commerce (`specs/125-first-mile-install/spec.md` §4.3, FR-140…FR-161).
+ *
+ * ## What it is, in one sentence
+ *
+ * The two `new` commands write trees and run nothing; between the second of
+ * them and a shop there were **nine** further typed steps (§2.3). This verb
+ * runs them, and it is deliberately the only place in the product where a
+ * scaffold and a pipeline meet.
+ *
+ * ## It composes, and reimplements nothing (FR-143)
+ *
+ * `runNewInstance` and `runNewStorefront` are the writers. Nothing here renders
+ * a template, resolves a module or decides a member: a second implementation of
+ * any of those is D-100's failure mode with a new name, and the case in
+ * `test/install.test.ts` that reads this file's own source is what keeps it
+ * true. The four flags that belong to `new instance` — `--module`,
+ * `--deployment`, `--registry`, `--topology` — are passed through unread.
+ *
+ * ## When it asks, and when it never does
+ *
+ * `cli-product.md` R2.5c is a **ceiling**: a prompt may be issued only when
+ * both descriptors are TTYs and no `--non-interactive`, `--dry-run` or CI
+ * marker is present. Below it, this command asks nothing at all and every
+ * missing answer is part of the one refusal — the posture Phase 3 shipped, and
+ * unchanged. At a terminal it runs the wizard (`wizard.ts`, spec §6), under
+ * R2.5f — 125's PR-1(b), accepted by the owner on 2026-09-25 and placed as
+ * D-269. The wizard is a thing that fills flags in: its question set is the
+ * flag set, so what it hands the rest of this function is the same options a
+ * fully-flagged `--non-interactive` run supplies (SC-107).
+ *
+ * ## Validate completely, then write — and then, only then, run
+ *
+ * `runNewInstance`'s discipline (R5.2), one layer up and with a third phase.
+ * Every precondition is decided before the first byte is written: the target,
+ * the Node version, a package-manager runner, a reachable Docker daemon unless
+ * `--no-services`, a reference storefront unless `--no-storefront`, and every
+ * answer the pipeline will need. They are reported in **one** refusal naming
+ * all of them (FR-157), because a client who has to run a command five times to
+ * learn five things has been handed a puzzle.
+ *
+ * ## Where nothing of ours is installed, it provisions a host first (D-271)
+ *
+ * `new instance` reads the platform's and every module's manifest off the
+ * packages installed beside the target or the working directory, and under
+ * `npx` there are none there. So when the platform does not resolve, the first
+ * step installs this CLI's release index into a temporary directory
+ * (`host.ts`) and `new instance` is called with that directory as its working
+ * directory — before the target is written, removed once it has been, kept and
+ * named when anything fails. It is not a pipeline step: the instance is not
+ * left with it, and a checkout or a pre-installed host never plans it.
+ *
+ * ## Every step prints the command it is about to run (FR-156)
+ *
+ * So an operator watching can reproduce any step by hand, and a failure names a
+ * command rather than a phase. A failure exits with **that step's own** exit
+ * code and prints what is left as a resumable list — the steps are the
+ * instance's own root scripts, so the list is a sequence a client can finish by
+ * typing.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { parseEnvFile, writeEnvFile } from '../inputs/env-file.js';
+import { generateSecret, interactivityOf, mayPrompt, } from '../inputs/resolve.js';
+import { ownReleaseIndexPath } from '../lib/release-index.js';
+import { developmentAddresses, developmentMailUrl, DEV_COMPOSE_PATH, } from '../new-instance/deploy.js';
+import { MEMBER_VOCABULARY, memberRefusal, runNewInstance, } from '../new-instance/index.js';
+import { probePlatform } from '../new-instance/host.js';
+import { runNewStorefront, } from '../new-storefront/index.js';
+import { HOST_DIRECTORY_PREFIX, hostNpmrc, readReleaseIndex, writeHost } from './host.js';
+import { answeredByFlags, answersLine, askWizard, WizardClosedError, } from './wizard.js';
+/** A refusal the operator can act on — exit 1. */
+export class InstallInputError extends Error {
+    name = 'InstallInputError';
+}
+/**
+ * An input this run could not read — exit 2 — or a failed host install, which
+ * exits with **that step's own** code like every other step (FR-156).
+ */
+export class InstallHostError extends Error {
+    name = 'InstallHostError';
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * The lowest Node this command will run an instance on.
+ *
+ * The **CLI's own** `engines.node`, read from its own manifest, for R2.3's
+ * reason: an instance re-declares that value rather than choosing one, so a
+ * one-shot that checked a different number would be enforcing a requirement
+ * nobody wrote down.
+ */
+function ownEnginesNode() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        return typeof manifest.engines?.node === 'string' ? manifest.engines.node : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `>=22.17.0` against `process.versions.node`, and nothing cleverer. */
+function satisfiesNode(range, version) {
+    const wanted = /(\d+)\.(\d+)\.(\d+)/.exec(range);
+    if (wanted === null)
+        return true;
+    const have = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (have === null)
+        return true;
+    for (let index = 1; index <= 3; index += 1) {
+        const left = Number(have[index]);
+        const right = Number(wanted[index]);
+        if (left !== right)
+            return left > right;
+    }
+    return true;
+}
+/** Does this command answer at all? A probe, never a version comparison. */
+function probe(command, args) {
+    const result = spawnSync(command, [...args], { stdio: 'ignore', timeout: 20_000 });
+    return result.error === undefined && result.status === 0;
+}
+/**
+ * How this machine runs `pnpm`, in the declared order (FR-158).
+ *
+ * `pnpm` on `PATH` first, then `corepack pnpm@<range>` — and **never**
+ * `corepack enable`, which is baseline step A1 and a command that writes shims
+ * into a directory this program does not own. `corepack pnpm@…` runs the
+ * package manager without changing anything about the machine, which is the
+ * property that lets this step be a fallback rather than an installation.
+ */
+function resolvePackageManagers() {
+    const found = [];
+    if (probe('pnpm', ['--version'])) {
+        found.push({ command: 'pnpm', prefix: [], label: 'pnpm' });
+    }
+    if (probe('corepack', ['--version'])) {
+        found.push({ command: 'corepack', prefix: ['pnpm@latest'], label: 'corepack pnpm@latest' });
+    }
+    return found;
+}
+/**
+ * Is a Docker daemon there? `docker info` answers, `docker --version` does not.
+ *
+ * **The server version it prints is the answer, not its exit status.** Docker
+ * CLI 28 exits 0 with an empty line when no daemon is listening (29 exits 1),
+ * so a status-only probe told a client on 28 with Docker stopped that the
+ * services step could run. Only a daemon can name its own version.
+ */
+function dockerIsReachable() {
+    const result = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        encoding: 'utf8',
+        timeout: 20_000,
+    });
+    return result.error === undefined && result.status === 0 && result.stdout.trim() !== '';
+}
+/**
+ * The refusals, collected.
+ *
+ * One object, filled completely and then thrown once: FR-157's *"in one
+ * refusal naming all of them"*. A `throw` at the first finding is the shape
+ * this deliberately is not — it makes the number of runs a client needs equal
+ * to the number of things they got wrong.
+ */
+class Refusals {
+    found = [];
+    add(sentence) {
+        this.found.push(sentence);
+    }
+    get length() {
+        return this.found.length;
+    }
+    throwIfAny() {
+        if (this.found.length === 0)
+            return;
+        throw new InstallInputError(`\`endora install\` cannot run yet — ${String(this.found.length)} thing` +
+            `${this.found.length === 1 ? '' : 's'} to settle first:\n` +
+            this.found.map((sentence) => `  - ${sentence}`).join('\n') +
+            `\n\nNothing was written and nothing was started.`);
+    }
+}
+/** The target must be empty, or hold nothing but a `.env` — `new instance`'s rule. */
+function occupied(dir) {
+    if (!existsSync(dir))
+        return null;
+    const entries = readdirSync(dir);
+    if (entries.length === 0)
+        return null;
+    if (entries.length === 1 && entries[0] === '.env')
+        return null;
+    return entries.slice(0, 5).join(', ');
+}
+/**
+ * Is there a reference storefront to copy, from where this command is standing?
+ *
+ * **The finding this function exists for**: `endora new storefront` copies the
+ * reference storefront out of a **checkout of the platform repository**
+ * (`new-storefront/reference.ts`: *"no pnpm-workspace.yaml above …"*), so an
+ * installed CLI standing in an empty directory cannot write one however it is
+ * asked. The spec's §7.6 assumes otherwise. The honest answer here is to refuse
+ * **before** writing an instance, naming the flag that skips the storefront —
+ * fail-closed, with a remedy the client can act on — rather than to write half
+ * the trio and fail in the middle of the pipeline.
+ */
+function referenceStorefrontRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * FR-105's derivation, performed on the tree this run just wrote.
+ *
+ * The values are read off **the rendered `compose.dev.yml`** and are written
+ * only over names the instance's own `.env` already lists as unanswered
+ * placeholders. That is the intersection stated structurally rather than as a
+ * list: the placeholders are this instance's declaration, rendered, so an
+ * instance that installs neither `search` nor `email` has no line to fill in
+ * for either and no name of theirs appears in this file.
+ *
+ * A value the operator already supplied is never written over — `writeEnvFile`
+ * fills a **commented** placeholder in place, and a filled line is not one.
+ */
+function deriveEnvironment(targetDir) {
+    const envPath = join(targetDir, '.env');
+    const composePath = join(targetDir, DEV_COMPOSE_PATH);
+    if (!existsSync(envPath) || !existsSync(composePath))
+        return [];
+    const text = readFileSync(envPath, 'utf8');
+    const answered = parseEnvFile(text);
+    const placeholders = new Set([...text.matchAll(/^\s*#\s*([A-Z][A-Z0-9_]*)\s*=/gm)].map((match) => match[1]));
+    const addresses = [...developmentAddresses(readFileSync(composePath, 'utf8'))].filter(([name]) => placeholders.has(name) && !answered.has(name));
+    if (addresses.length === 0)
+        return [];
+    // The sentence is the whole of the mitigation, so it names **which** values
+    // it is about: they are filled in above, each over its own placeholder and in
+    // the declaration's own order, and a comment at the bottom saying "these" and
+    // nothing more would send a reader looking for a block that is not there.
+    const header = [
+        '',
+        `# ${addresses.map(([name]) => name).join(', ')} above were DERIVED by \`endora install\``,
+        `# from ${DEV_COMPOSE_PATH} beside this file: they are the addresses of the containers`,
+        '# `pnpm run dev:services` starts, on THIS machine. Nothing invented them and nothing',
+        '# asked you — change a published port in that file and they are what it publishes.',
+        '#',
+        '# On a machine that is not a development one they are not the values you want: replace',
+        '# each with the address of the service you actually run. They fail closed — a database',
+        '# that is not there refuses a connection — rather than quietly writing somewhere else.',
+    ].join('\n');
+    const written = writeEnvFile(`${text.replace(/\n+$/, '')}\n${header}\n`, new Map(addresses));
+    writeFileSync(envPath, written, 'utf8');
+    return addresses.map(([name]) => name);
+}
+/** The storefront's own `.env`, with the values this run owes it (FR-153/154). */
+function storefrontInputs(instance, secret) {
+    const port = '3001';
+    return {
+        NEXT_PUBLIC_API_BASE_URL: `http://localhost:${port}`,
+        BACKEND_BASE_URL: `http://localhost:${port}`,
+        NEXT_PUBLIC_SITE_URL: 'http://localhost:3000',
+        // The platform's own fallback, which is what the instance's default Sales
+        // Channel is created with when `DEFAULT_SALES_CHANNEL_CODE` is unset
+        // (`kernel/sales-channels/default-channel-reconciler.ts`). A different
+        // string here would point the storefront at a channel nothing creates.
+        NEXT_PUBLIC_SALES_CHANNEL_CODE: 'default',
+        REVALIDATE_SECRET: secret,
+        ...Object.fromEntries(instance.resolved
+            .filter((entry) => entry.name === 'DEFAULT_SALES_CHANNEL_CODE')
+            .map((entry) => ['NEXT_PUBLIC_SALES_CHANNEL_CODE', entry.value])),
+    };
+}
+/**
+ * The whole command.
+ *
+ * Three phases, in this order and never interleaved: **decide** (every
+ * precondition, one refusal), **write** (the two scaffolds and the derived
+ * `.env`), **run** (the pipeline, each step echoed). A `--dry-run` stops after
+ * the first and reports the other two.
+ */
+export async function runInstall(given) {
+    const cwd = given.cwd ?? process.cwd();
+    const output = [];
+    const say = (line) => {
+        output.push(line);
+        given.echo?.(line);
+    };
+    // ── ask, only where R2.5c's conjunction holds (R2.5f i) ───────────────────
+    const interactive = mayPrompt(given.interactivity ??
+        interactivityOf({
+            nonInteractive: given.nonInteractive === true,
+            dryRun: given.dryRun === true,
+        }));
+    let options = given;
+    let provenance;
+    if (interactive) {
+        try {
+            const outcome = await askWizard(given, given.io ?? { input: process.stdin, output: process.stdout, terminal: true }, {
+                vocabulary: MEMBER_VOCABULARY,
+                storefront: {
+                    available: referenceStorefrontRoot(cwd) !== null,
+                    reason: 'not from here: it is copied out of a checkout of the platform repository, ' +
+                        'and there is none above this directory — `endora new storefront` adds it later',
+                },
+            });
+            options = { ...given, ...outcome.answers };
+            provenance = outcome;
+        }
+        catch (error) {
+            if (error instanceof WizardClosedError)
+                throw new InstallInputError(error.message);
+            throw error;
+        }
+    }
+    else {
+        // Nothing asked: every answer is a flag, and the two offered questions a
+        // flag did not answer take §6.2's recommendation — *everything*, *yes* —
+        // which is what Phase 3 already did and is now said out loud.
+        const fromFlags = answeredByFlags(given);
+        provenance = {
+            fromFlags,
+            prompted: [],
+            recommended: ['parts', 'services'].filter((id) => !fromFlags.has(id)),
+        };
+    }
+    // ── decide ────────────────────────────────────────────────────────────────
+    const refusals = new Refusals();
+    // A missing directory is one refusal among the others rather than the first
+    // and only one: a run with no answers at all is told everything it owes in
+    // one message (FR-157, R3.2), and the checks that need a directory are the
+    // only ones it skips.
+    const namedDir = options.dir === undefined || options.dir.trim().length === 0
+        ? null
+        : isAbsolute(options.dir)
+            ? options.dir
+            : resolve(cwd, options.dir);
+    if (namedDir === null) {
+        refusals.add('`endora install` takes the directory to write — `<dir>` — and outside the wizard has no ' +
+            "default: the directory's basename becomes the workspace name, so a default would " +
+            'invent a name nobody chose.');
+    }
+    const wantsStorefront = options.storefront !== false;
+    const wantsServices = options.services !== false;
+    const namedStorefrontDir = !wantsStorefront || namedDir === null
+        ? null
+        : options.storefrontDir === undefined
+            ? `${namedDir}-storefront`
+            : isAbsolute(options.storefrontDir)
+                ? options.storefrontDir
+                : resolve(cwd, options.storefrontDir);
+    const declinedRefusal = memberRefusal(options.without ?? []);
+    if (declinedRefusal !== null)
+        refusals.add(declinedRefusal);
+    const inTheWay = namedDir === null ? null : occupied(namedDir);
+    if (inTheWay !== null) {
+        refusals.add(`${namedDir} exists and is not empty (${inTheWay}). An instance's files are yours; ` +
+            'this command never merges into a directory. Scaffold into an empty one — a ' +
+            'directory holding nothing but a `.env` is the exception, and that file is read as ' +
+            'your own answers.');
+    }
+    // FR-160 — a sibling, never a child. A storefront inside the instance would
+    // be swept into its `pnpm-workspace.yaml` globs and become a member of a
+    // workspace it is not part of, which is D-230's topology broken by a
+    // directory choice.
+    if (namedStorefrontDir !== null && namedStorefrontDir.startsWith(namedDir + sep)) {
+        refusals.add(`--storefront-dir ${namedStorefrontDir} is inside ${namedDir}. The storefront is its own ` +
+            "repository (D-195): written there it would be swept into the instance's workspace " +
+            'globs and become a member of a workspace it is not part of. Put it beside the ' +
+            'instance — the default is `<dir>-storefront`.');
+    }
+    if (namedStorefrontDir !== null) {
+        const storefrontInTheWay = occupied(namedStorefrontDir);
+        if (storefrontInTheWay !== null) {
+            refusals.add(`${namedStorefrontDir} exists and is not empty (${storefrontInTheWay}). Pass ` +
+                '`--storefront-dir <path>` for another directory, or `--no-storefront` to write no ' +
+                'storefront at all.');
+        }
+    }
+    const engines = ownEnginesNode();
+    if (engines !== undefined && !satisfiesNode(engines, process.versions.node)) {
+        refusals.add(`this build needs Node ${engines} and is running on ${process.versions.node}. The ` +
+            'instance it writes declares the same range, so a run on this one would install a ' +
+            'tree its own manifest refuses.');
+    }
+    const runners = options.packageManagers ?? resolvePackageManagers();
+    if (runners.length === 0) {
+        refusals.add('no package manager to run: `pnpm` is not on PATH and `corepack` is not either. ' +
+            'Install pnpm (`npm i -g pnpm`), or use a Node that ships corepack — this command ' +
+            'runs `corepack pnpm@latest` when it has to, and never `corepack enable`, which ' +
+            'writes shims into a directory it does not own.');
+    }
+    if (wantsServices && (options.dockerReachable ?? dockerIsReachable()) === false) {
+        refusals.add('no Docker daemon answered. The development stack — PostgreSQL, Redis, Meilisearch ' +
+            'and a mail catcher — is started with `docker compose`, so this run has nothing to ' +
+            'migrate against. Start Docker, or pass `--no-services` and point the instance at ' +
+            'services you run yourself.');
+    }
+    if (wantsStorefront && referenceStorefrontRoot(cwd) === null) {
+        refusals.add('`endora new storefront` copies the reference storefront out of a checkout of the ' +
+            `platform repository, and there is none above ${cwd}. Run this from inside a ` +
+            'checkout to get both trees, or pass `--no-storefront` to write the instance alone ' +
+            '— the storefront can be added later with `endora new storefront <dir>`.');
+    }
+    const admin = {
+        email: options.adminEmail,
+        password: options.adminPassword,
+        firstName: options.adminFirstName,
+        lastName: options.adminLastName,
+    };
+    const missingAdmin = [
+        ['--admin-email', admin.email],
+        ['--admin-password', admin.password],
+        ['--admin-first-name', admin.firstName],
+        ['--admin-last-name', admin.lastName],
+    ].filter(([, value]) => value === undefined || value.trim().length === 0);
+    if (missingAdmin.length > 0) {
+        // FR-159 — a generated password is not permitted: `generable` requires that
+        // two correct values are interchangeable, and a password the operator has
+        // to remember is not one of those.
+        refusals.add(`the administrator is missing ${missingAdmin.map(([flag]) => flag).join(', ')}. ` +
+            'Nothing else creates one — a freshly migrated instance has no account at all — and ' +
+            'the password is never generated: it is the one value you have to remember.');
+    }
+    if (options.demo === undefined) {
+        // FR-124 — required, by 125 PR-2 option (c) as ruled (D-269).
+        refusals.add('say whether to install demo data: `--demo` seeds every installed module\'s example ' +
+            'rows, `--no-demo` seeds none. There is deliberately no default — an instance you ' +
+            'are going to sell from wants none of it and one you are evaluating wants it before ' +
+            'the first screen, and picking for you would be picking wrong for one of them.');
+    }
+    refusals.throwIfAny();
+    // Both are decided: a missing directory was a refusal above.
+    const targetDir = namedDir;
+    const storefrontDir = namedStorefrontDir;
+    const runner = runners[0];
+    const dryRun = options.dryRun === true;
+    const run = options.run ?? spawnStep;
+    // ── provision, only where nothing of ours resolves (D-271) ───────────────
+    // Decided before anything is written, like every other input: an index this
+    // build cannot read, or a `--registry` that is not one, refuses here.
+    const hostStep = planHost({
+        cwd,
+        targetDir,
+        runner,
+        registry: options.registry,
+        releaseIndexFile: options.releaseIndexFile,
+    });
+    // ── write ─────────────────────────────────────────────────────────────────
+    say(`endora install ${targetDir}${dryRun ? ' — dry run, nothing written' : ''}`);
+    const answers = answersLine(provenance);
+    say(`  ${answers}`);
+    if (hostStep !== null) {
+        const keptLine = `  the temporary host is kept at ${hostStep.cwd} so you can read what its install ` +
+            'left; delete it when you are done.';
+        say(`\n[host] ${hostStep.command}   # in ${hostStep.cwd}`);
+        say(`      ${hostStep.purpose}`);
+        const code = await run(hostStep);
+        if (code !== 0) {
+            say(keptLine);
+            throw new InstallHostError(`${hostStep.command} failed (exit ${String(code)}) in the temporary host ` +
+                `${hostStep.cwd}, so no package of this release could be read and nothing was ` +
+                `written to ${targetDir}. The host is kept there so you can read what its install ` +
+                'left. If the registry needs configuration, pass `--registry <url>`; then run this ' +
+                'command again.', code);
+        }
+    }
+    const without = (options.without ?? []).filter((name) => name.trim().length > 0);
+    let instance;
+    try {
+        instance = await runNewInstance({
+            dir: targetDir,
+            ...(options.modules === undefined ? {} : { modules: options.modules }),
+            // R6.3b — nothing at all when every member is wanted, so the common case
+            // is the argv a bare `endora new instance <dir>` has.
+            ...(without.length === 0 ? {} : { without }),
+            ...(options.deployment === undefined ? {} : { deployment: options.deployment }),
+            ...(options.registry === undefined ? {} : { registry: options.registry }),
+            ...(options.topology === undefined ? {} : { topology: options.topology }),
+            // D-270 — with no `--module`, every module of the open-source set this
+            // run resolved rather than the smallest set. A policy, not a list: which
+            // modules that is stays `new instance`'s to derive (FR-143).
+            moduleSeed: 'available',
+            dryRun,
+            // The host, when there is one, is only a place to look: every resolution
+            // is `new instance`'s, unchanged (D-271 clause 1.1).
+            cwd: hostStep?.cwd ?? cwd,
+        });
+    }
+    catch (error) {
+        if (hostStep !== null) {
+            say(`  the temporary host is kept at ${hostStep.cwd} so you can read what it holds; ` +
+                'delete it when you are done.');
+        }
+        throw error;
+    }
+    if (hostStep !== null) {
+        rmSync(hostStep.cwd, { recursive: true, force: true });
+        say(`  removed the temporary host at ${hostStep.cwd}` +
+            (dryRun ? ` — it was provisioned to read the module set; nothing was written to ${targetDir}` : ''));
+    }
+    say(`  ${dryRun ? 'would write' : 'wrote'} ${String(instance.plan.files.length)} files across ` +
+        `${instance.plan.members.join(', ')} — ${instance.modules.ids.length} module(s)`);
+    say(`  ${instance.provenance}`);
+    // FR-153 — generated **once**, for two trees. See `revalidateSecret` above.
+    const secret = options.revalidateSecret ?? (dryRun ? '<generated on a real run>' : generateSecret());
+    let storefront = null;
+    if (storefrontDir !== null) {
+        storefront = await runNewStorefront({
+            dir: storefrontDir,
+            cwd,
+            dryRun,
+            nonInteractive: true,
+            inputs: storefrontInputs(instance, secret),
+        });
+        say(`  ${dryRun ? 'would write' : 'wrote'} the storefront at ${storefrontDir} — ` +
+            `${String(storefront.plan.files.length)} files`);
+        say(`  ${storefront.provenance}`);
+    }
+    const derived = dryRun || !wantsServices ? [] : deriveEnvironment(targetDir);
+    if (derived.length > 0) {
+        say(`  derived from ${DEV_COMPOSE_PATH} into .env: ${derived.join(', ')} — the addresses of ` +
+            'the containers the next step starts, on this machine');
+    }
+    if (!dryRun && storefrontDir !== null && options.revalidateSecret === undefined) {
+        writeSharedSecret(targetDir, secret);
+        say('  generated REVALIDATE_SECRET once and wrote it into both trees — the one value no ' +
+            'sequence of `endora new instance` and `endora new storefront` can agree on');
+    }
+    // ── run ───────────────────────────────────────────────────────────────────
+    const steps = plan({
+        targetDir,
+        storefrontDir,
+        runner,
+        services: wantsServices,
+        demo: options.demo === true,
+        admin,
+    });
+    let exitCode = 0;
+    const done = [];
+    if (!dryRun) {
+        for (const step of steps) {
+            say(`\n[${String(done.length + 1)}/${String(steps.length)}] ${step.command}`);
+            say(`      ${step.purpose}`);
+            const code = await run(step);
+            done.push(step);
+            if (code === 0)
+                continue;
+            if (step.optional === true) {
+                say(`      that failed (exit ${String(code)}) and the install is complete without it. ` +
+                    `Retry with \`${step.command}\`, and \`pnpm run cli demo reset\` withdraws it again.`);
+                continue;
+            }
+            exitCode = code;
+            say(`\n${step.command} failed (exit ${String(code)}). Remaining steps, in order:`);
+            for (const left of steps.slice(done.length))
+                say(`  ${left.command}   # ${left.purpose}`);
+            break;
+        }
+    }
+    else {
+        say('\nThe pipeline it would run, in order:');
+        for (const step of steps)
+            say(`  ${step.command}   # ${step.purpose}`);
+    }
+    if (exitCode === 0) {
+        for (const line of closing({
+            targetDir,
+            storefrontDir,
+            admin,
+            instance,
+            dryRun,
+            demo: options.demo === true,
+            recommended: provenance.recommended,
+            services: wantsServices,
+            passwordFromFlag: provenance.fromFlags.has('admin-password'),
+        })) {
+            say(line);
+        }
+    }
+    return {
+        targetDir,
+        storefrontDir,
+        instance,
+        storefront,
+        steps,
+        hostStep,
+        output,
+        exitCode,
+        derived,
+        answers,
+        dryRun,
+    };
+}
+/**
+ * The temporary host step, or `null` when the platform already resolves.
+ *
+ * D-271: provisioned **exactly** when `@endora-commerce/platform` does not
+ * resolve beside the target or the working directory — a checkout, the
+ * acceptance harness and a client who installed the packages beside all plan
+ * none, and run exactly as before. Its files are written here, before the
+ * header is printed, because a release index this build cannot read is an input
+ * the run could not read and is refused before anything is started.
+ */
+function planHost(input) {
+    const { scope, resolves } = probePlatform({ cwd: input.cwd, targetDir: input.targetDir });
+    if (resolves)
+        return null;
+    const file = input.releaseIndexFile ?? ownReleaseIndexPath();
+    const read = readReleaseIndex(file);
+    if ('problem' in read) {
+        throw new InstallHostError(`${scope}platform does not resolve from ${input.targetDir} or ${input.cwd}, and this ` +
+            `build's release index — the packages it would install to read the module set from — ` +
+            `could not be read: ${read.problem}. Nothing was written. Reinstall ` +
+            `\`${scope}cli\`, or install the platform beside the target directory and run this ` +
+            'command again.');
+    }
+    const npmrc = hostNpmrc(input.registry, scope);
+    const dir = mkdtempSync(join(tmpdir(), HOST_DIRECTORY_PREFIX));
+    writeHost(dir, read.index, npmrc);
+    const argv = ['install'];
+    return {
+        id: 'host',
+        command: `${input.runner.label} ${argv.join(' ')}`,
+        purpose: `nothing of ours is installed beside ${input.targetDir}, so every package of this ` +
+            `release (${String(read.index.packages.length)}) is installed into a temporary host to ` +
+            'read the module manifests from. It is removed when the instance is written.',
+        bin: input.runner.command,
+        argv: [...input.runner.prefix, ...argv],
+        cwd: dir,
+    };
+}
+/**
+ * The shared secret, into the instance's own `.env`.
+ *
+ * The storefront gets it as a resolved input — it declares the variable, so its
+ * own resolution writes it. The instance's `.env` lists it as a placeholder
+ * (the platform declares it `generable: false`, so `new instance` writes no
+ * value), and this is where the second half of the pair is filled in.
+ */
+function writeSharedSecret(targetDir, secret) {
+    const envPath = join(targetDir, '.env');
+    if (!existsSync(envPath))
+        return;
+    const text = readFileSync(envPath, 'utf8');
+    if (!/^\s*#?\s*REVALIDATE_SECRET\s*=/m.test(text))
+        return;
+    if (parseEnvFile(text).has('REVALIDATE_SECRET'))
+        return;
+    writeFileSync(envPath, writeEnvFile(text, new Map([['REVALIDATE_SECRET', secret]])), 'utf8');
+}
+/**
+ * The pipeline (FR-155).
+ *
+ * It is the printed next-steps sequence and nothing else, and it runs the
+ * instance's **own root scripts** rather than their contents: `setup` is the
+ * composite the block names, so a client reproducing this by hand types the
+ * same four words. A step this list has that the block does not would make the
+ * two paths two products.
+ */
+function plan(input) {
+    const { runner } = input;
+    const step = (id, cwd, argv, purpose, optional = false) => ({
+        id,
+        command: `${runner.label} ${argv.join(' ')}`.trim(),
+        purpose,
+        bin: runner.command,
+        argv: [...runner.prefix, ...argv],
+        cwd,
+        ...(optional ? { optional: true } : {}),
+    });
+    const steps = [
+        step('install', input.targetDir, ['install'], 'the platform, the admin shell and every module you declared, from the registry'),
+    ];
+    if (input.services) {
+        steps.push(step('services', input.targetDir, ['run', 'dev:services'], 'PostgreSQL, Redis, Meilisearch and a mail catcher, waited for until each is healthy'));
+    }
+    steps.push(step('setup', input.targetDir, ['run', 'setup'], 'generate, build, migrate and install every module — the four steps, in order'), step('admin', input.targetDir, [
+        'run',
+        'admin:create',
+        '--',
+        `--email=${input.admin.email ?? ''}`,
+        `--password=${input.admin.password ?? ''}`,
+        `--first-name=${input.admin.firstName ?? ''}`,
+        `--last-name=${input.admin.lastName ?? ''}`,
+    ], 'the administrator you sign in as. Nothing else creates one'));
+    if (input.demo) {
+        // FR-126 — after `module:install --all` and after the administrator, and
+        // non-fatal. The reverse ordering would make an optional extra able to red
+        // a mandatory outcome.
+        steps.push(step('demo', input.targetDir, ['run', 'cli', 'demo', 'seed'], "every installed module's example rows, withdrawable with `cli demo reset`", true));
+    }
+    if (input.storefrontDir !== null) {
+        steps.push(step('storefront-install', input.storefrontDir, ['install'], 'the storefront\'s own dependencies, in its own repository'));
+    }
+    return steps;
+}
+/** What a client reads when it worked: where things are, and what is next. */
+function closing(input) {
+    const lines = ['', input.dryRun ? 'It would then be yours to start:' : 'Done. To start it:'];
+    // One command first (`specs/136-open-source-publication/` GAP-7, FR-060):
+    // the supervisor over the per-layer commands below, which stay printed for
+    // the operator who wants a layer on its own. A storefront somewhere other
+    // than the default sibling is named, since `dev:all` looks for the default.
+    const defaultStorefront = `${input.targetDir}-storefront`;
+    const devAllArgs = input.storefrontDir !== null && input.storefrontDir !== defaultStorefront
+        ? ` -- --storefront-dir ${input.storefrontDir}`
+        : '';
+    const rootManifest = input.instance.plan.files.find((file) => file.path === 'package.json');
+    const rootScripts = rootManifest === undefined
+        ? {}
+        : (JSON.parse(rootManifest.content).scripts ?? {});
+    if (typeof rootScripts['dev:all'] === 'string') {
+        lines.push(`  cd ${input.targetDir} && pnpm run dev:all${devAllArgs}   # every layer, one terminal; Ctrl-C stops them`, '', 'Or one layer at a time:');
+    }
+    lines.push(`  cd ${input.targetDir} && pnpm run start      # the API, on http://localhost:3001`);
+    if (input.instance.plan.members.includes('admin')) {
+        lines.push('  pnpm run preview:admin                    # the admin bundle, in a second terminal');
+    }
+    if (input.storefrontDir !== null) {
+        lines.push(`  cd ${input.storefrontDir} && pnpm run build && pnpm run start   # the shop`);
+    }
+    const mail = developmentMailUrl(existsSync(join(input.targetDir, DEV_COMPOSE_PATH))
+        ? readFileSync(join(input.targetDir, DEV_COMPOSE_PATH), 'utf8')
+        : '');
+    if (mail !== undefined) {
+        lines.push(`  mail this instance sends is caught at ${mail} and leaves your machine never`);
+    }
+    lines.push('', `Sign in as ${input.admin.email ?? ''} with the password you ` +
+        `${input.passwordFromFlag ? 'passed on the command line' : 'entered above'}.`, input.demo
+        ? `Demo data ${input.dryRun ? 'would be' : 'was'} seeded. \`pnpm run cli demo reset\` withdraws it ` +
+            'and leaves your own rows alone.'
+        : `No demo data ${input.dryRun ? 'would be' : 'was'} seeded. \`pnpm run cli demo seed\` adds a ` +
+            "shop's worth of it, and `demo reset` withdraws it again.");
+    // D-270 — the module set is not a question and not an input, so it is not in
+    // the `[answers]` or `[inputs]` line; it is a derived value, and the run says
+    // what it derived and how to take any of it back. Off is non-destructive
+    // (Constitution XVII), which is what makes "everything" the safe default.
+    if (input.instance.modules.defaulted) {
+        const count = input.instance.modules.ids.length;
+        lines.push('', `${String(count)} module${count === 1 ? '' : 's'} ${input.dryRun ? 'would be' : 'were'} ` +
+            'installed, because no `--module` was given: every module of the open-source set ' +
+            'this run found, each switched on.', 'Switch any of them off in the admin under Modules (/platform/modules). Off keeps its ' +
+            'data, and switching it back on brings it back.');
+    }
+    // R2.5f (iv) — every answer taken as a recommendation, said to be one, with
+    // what reverses it. A recommendation nobody is told they accepted is a
+    // default with better manners.
+    const reversals = {
+        directory: `the directory ${input.targetDir} — pass another as \`endora install <dir>\``,
+        parts: 'every part this build can write — `--without <member>` and `--no-storefront` leave one ' +
+            'out of the next install',
+        services: input.services
+            ? 'the development services, started — `pnpm run dev:services:down` stops them'
+            : null,
+        demo: null,
+        'admin-email': null,
+        'admin-password': null,
+        'admin-name': null,
+    };
+    const taken = input.recommended
+        .map((id) => reversals[id])
+        .filter((line) => line !== null);
+    if (taken.length > 0) {
+        lines.push('', 'Recommended, and taken because nothing said otherwise:');
+        for (const line of taken)
+            lines.push(`  ${line}`);
+    }
+    return lines;
+}
+/** The default runner: spawn it, inherit the descriptors, answer its code. */
+function spawnStep(step) {
+    return new Promise((resolveCode) => {
+        const child = spawn(step.bin, [...step.argv], {
+            cwd: step.cwd,
+            stdio: 'inherit',
+            env: process.env,
+        });
+        child.on('error', () => resolveCode(127));
+        child.on('close', (code) => resolveCode(code ?? 1));
+    });
+}
+//# sourceMappingURL=index.js.map