@endora-commerce/cli 0.100.0

package/dist/check/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/check/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,gBAAgB,GAAG,YAAY,GAAG,SAAS,CAAC;AAE1E,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,aAAa,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iDAAiD;IACjD,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,UAAU,EAAE,MAAM,EAClB,UAAU,UAAQ,GACjB,SAAS,CAgBX;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAkB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,CAIR;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAe/D"}

package/dist/check/run.js

@@ -0,0 +1,111 @@
+/**
+ * The verdicts, the arithmetic and the reduction
+ * (`specs/101-endora-check/contracts/exit-reduction.md` §1, §3, §4).
+ *
+ * ## The reduction is `max`, and that is not a new decision
+ *
+ * `0` and `1` are statements about the **tree**; `2` is a statement about the
+ * **run**. So the aggregate's job is to make each code a *complete* statement:
+ *
+ *   * **2** — the picture is incomplete. There may or may not be findings under
+ *     it; repair the picture.
+ *   * **1** — the picture is complete and there are findings.
+ *   * **0** — the picture is complete and there are none.
+ *
+ * Every member of this estate already reduces this way internally, over many
+ * signals and many files: `check:module-boundary` exits 2 on an owner map that
+ * resolved zero tables even when its walk found real unledgered reaches. An
+ * aggregate reducing differently would be a second derivation of one convention.
+ *
+ * The masking objection — *"one unreadable input hides every real finding"* — is
+ * answered where it lives: it masks them **in the exit code and nowhere else**.
+ * Every rule prints its own line regardless, and {@link countsOf}'s `findings`
+ * is printed on the arithmetic line **even when the code is 2**. That is
+ * normative (FR-014), not cosmetic.
+ *
+ * ## The identities have to be able to fail
+ *
+ * {@link countsOf} takes the estate's size as an argument rather than deriving it
+ * from the results it was handed. A count computed by summing the results a run
+ * happens to hold can never detect a lost rule — it is a tautology, and the
+ * whole point of §3's first identity is that losing a rule is the failure this
+ * command exists to make impossible. The second identity fails on a malformed
+ * host: a result that is not `ran` and still carries a finding.
+ */
+/** Which findings count against the exit code, for this reader. */
+export function effectiveFindings(result, asPlatform) {
+    return asPlatform ? [...result.findings, ...result.acknowledged] : result.findings;
+}
+/**
+ * The counts, over the results and an **independently supplied** estate size.
+ *
+ * `estateSize` is a parameter rather than `results.length` on purpose — see the
+ * header. `clean` and `findings` are each counted directly rather than one being
+ * derived from the other, so §3's second identity is a real comparison.
+ */
+export function countsOf(results, estateSize, asPlatform = false) {
+    const withFindings = results.filter((result) => effectiveFindings(result, asPlatform).length > 0);
+    return {
+        estate: estateSize,
+        ran: results.filter((result) => result.verdict === 'ran').length,
+        clean: results.filter((result) => result.verdict === 'ran' && effectiveFindings(result, asPlatform).length === 0).length,
+        findings: withFindings.length,
+        notApplicable: results.filter((result) => result.verdict === 'not-applicable').length,
+        unreadable: results.filter((result) => result.verdict === 'unreadable').length,
+        pending: results.filter((result) => result.verdict === 'pending').length,
+    };
+}
+/**
+ * Why §3's identities do not hold, or an empty list.
+ *
+ * A narrowed run suppresses the first — it is meaningless over a subset — and
+ * keeps the second, which is about the results themselves.
+ */
+export function arithmeticFailures(counts, narrowed) {
+    const failures = [];
+    const verdicts = counts.ran + counts.notApplicable + counts.unreadable + counts.pending;
+    if (!narrowed && verdicts !== counts.estate) {
+        failures.push(`the run reported ${verdicts} verdict(s) over an estate of ${counts.estate}: ` +
+            `ran + not-applicable + unreadable + pending != estate. The command has lost a ` +
+            `rule, which is the failure this arithmetic exists to make impossible.`);
+    }
+    if (counts.clean + counts.findings !== counts.ran) {
+        failures.push(`clean=${counts.clean} + findings=${counts.findings} != ran=${counts.ran}: a rule ` +
+            `reported a finding under a verdict that cannot carry one, so the estate's ` +
+            `finding count is not a statement about the rules that ran.`);
+    }
+    return failures;
+}
+/**
+ * The exit code. `max` over the members' own codes, with `pending` folded into 2.
+ *
+ * ```
+ * exit 2  if  unreadable > 0  or  pending > 0  or  either identity fails
+ * exit 1  else if  findings > 0  or  a ledger entry is stale
+ * exit 0  else
+ * ```
+ */
+export function reduce(counts, failures, ledgerFindings) {
+    if (counts.unreadable > 0 || counts.pending > 0 || failures.length > 0)
+        return 2;
+    if (counts.findings > 0 || ledgerFindings.length > 0)
+        return 1;
+    return 0;
+}
+export function buildRunReport(input) {
+    const asPlatform = input.asPlatform ?? false;
+    const ledgerFindings = input.ledgerFindings ?? [];
+    const counts = countsOf(input.results, input.estateSize, asPlatform);
+    const failures = arithmeticFailures(counts, input.selected !== null);
+    return {
+        packageName: input.packageName,
+        packageVersion: input.packageVersion,
+        results: input.results,
+        selected: input.selected,
+        counts,
+        ledgerFindings,
+        arithmeticFailures: failures,
+        exitCode: reduce(counts, failures, ledgerFindings),
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/check/run.js.map

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

package/dist/checks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@endora-commerce/cli/checks` — the estate manifest and the run report, as a
+ * subpath a stranger can import.
+ *
+ * It is a subpath of its own because **a stranger's run cannot read a `vitest`
+ * file** (`data-model.md` preamble). The estate, its verdicts and the shapes
+ * `endora check` reports in are tooling contracts, not an HTTP API, so
+ * `packages/contracts/` is not their home — this is the same placement
+ * `module-roots` and `read-size` already have.
+ *
+ * This repository's own reconciliation
+ * (`backend/test/unit/scripts/check-inventory.test.ts`) imports it here too, and
+ * that is the point: one manifest, read by the tool and by the test that holds
+ * the tool to the inventory.
+ */
+export * from './check/index.js';
+//# sourceMappingURL=checks.d.ts.map

package/dist/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,kBAAkB,CAAC"}

package/dist/checks.js

@@ -0,0 +1,17 @@
+/**
+ * `@endora-commerce/cli/checks` — the estate manifest and the run report, as a
+ * subpath a stranger can import.
+ *
+ * It is a subpath of its own because **a stranger's run cannot read a `vitest`
+ * file** (`data-model.md` preamble). The estate, its verdicts and the shapes
+ * `endora check` reports in are tooling contracts, not an HTTP API, so
+ * `packages/contracts/` is not their home — this is the same placement
+ * `module-roots` and `read-size` already have.
+ *
+ * This repository's own reconciliation
+ * (`backend/test/unit/scripts/check-inventory.test.ts`) imports it here too, and
+ * that is the point: one manifest, read by the tool and by the test that holds
+ * the tool to the inventory.
+ */
+export * from './check/index.js';
+//# sourceMappingURL=checks.js.map

package/dist/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,kBAAkB,CAAC"}

package/dist/dev/index.d.ts

@@ -0,0 +1,83 @@
+/** The root script a scaffolded instance declares for this command. */
+export declare const DEV_ALL_SCRIPT = "dev:all";
+/** A refusal the operator can act on — exit 1. */
+export declare class DevInputError extends Error {
+    readonly name = "DevInputError";
+}
+/** An input this run could not read — exit 2. */
+export declare class DevHostError extends Error {
+    readonly name = "DevHostError";
+}
+/** One layer, as the plan decides it: which script, run where. */
+export interface DevLayer {
+    readonly label: 'api' | 'admin' | 'storefront';
+    readonly cwd: string;
+    /** The package script it runs, by name — never its contents. */
+    readonly script: string;
+}
+export interface DevPlan {
+    readonly instanceDir: string;
+    readonly storefrontDir: string | null;
+    readonly processes: readonly DevLayer[];
+    /** What was left out and why, printed before anything starts. */
+    readonly notes: readonly string[];
+}
+export interface DevOptions {
+    /** The directory it was typed in; the instance is its root manifest. */
+    readonly cwd: string;
+    /**
+     * Where the storefront is. `undefined` looks for the default sibling,
+     * a string names one (relative to {@link cwd}), `false` starts none.
+     */
+    readonly storefront?: string | false | undefined;
+}
+/**
+ * The layers this tree has, decided from its manifests and from nothing else.
+ *
+ * Validates completely before anything is started, in `runNewInstance`'s
+ * discipline: a run that started the API and then refused over the storefront
+ * would leave a process behind for a refusal.
+ */
+export declare function planDev(options: DevOptions): DevPlan;
+/** One process the supervisor runs, as a command line. */
+export interface SupervisedProcess {
+    readonly label: string;
+    readonly cwd: string;
+    readonly bin: string;
+    readonly argv: readonly string[];
+}
+/**
+ * How a package script is run from here.
+ *
+ * `pnpm run dev:all` sets `npm_execpath` to the package manager that is running
+ * it, so the layers are started by the same one — which matters when the
+ * operator reached pnpm through `corepack pnpm@…` and there is no `pnpm` on
+ * `PATH` at all. Absent, `pnpm` is what an instance declares in its own
+ * `packageManager`.
+ */
+export declare function commandFor(layer: DevLayer, env?: NodeJS.ProcessEnv): SupervisedProcess;
+export interface SuperviseOptions {
+    /** Where a line goes. The argv layer passes stdout. */
+    readonly write: (line: string) => void;
+    /** An interrupt: every layer is stopped and the run ends `0`. */
+    readonly signal?: AbortSignal | undefined;
+    /** How long a layer gets between the polite stop and the forced one. */
+    readonly graceMs?: number | undefined;
+}
+/**
+ * Run the layers until one ends or the operator interrupts, then stop them all.
+ *
+ * Resolves with the exit code the command reports: `0` for an interrupt (the
+ * operator asked for the stop and got it), the ending layer's own code when it
+ * failed, and `1` when a layer ended with `0` — a server that returned is not
+ * running, and the other layers are no use without it.
+ */
+export declare function superviseDev(processes: readonly SupervisedProcess[], options: SuperviseOptions): Promise<number>;
+/**
+ * The whole command: plan, print what starts and what does not, supervise.
+ */
+export declare function runDev(options: DevOptions & {
+    readonly write: (line: string) => void;
+    readonly signal?: AbortSignal | undefined;
+}): Promise<number>;
+//# sourceMappingURL=index.d.ts.map

package/dist/dev/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dev/index.ts"],"names":[],"mappings":"AAwDA,uEAAuE;AACvE,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,kDAAkD;AAClD,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAmB;CAC1C;AAED,iDAAiD;AACjD,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,kBAAkB;CACzC;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,YAAY,CAAC;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;CAClD;AAcD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAkEpD;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,QAAQ,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,iBAAiB,CAWnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAqBD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAgGjB;AAED;;GAEG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,UAAU,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C,GACA,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/dev/index.js

@@ -0,0 +1,298 @@
+/**
+ * `endora dev` — the supervisor behind an instance's `pnpm run dev:all`
+ * (`specs/136-open-source-publication/spec.md` GAP-7, FR-060, FR-061;
+ * research R-10).
+ *
+ * ## What it is, in one sentence
+ *
+ * One foreground process over the development commands an instance already
+ * has — the API, the admin preview and, when present, the storefront — that
+ * prefixes their output, stops all of them on an interrupt, and stops all of
+ * them when any one of them ends, naming which.
+ *
+ * ## What it is not
+ *
+ * A fusion of the layers. D-230 deploys the backend, the admin and the
+ * storefront to hosts of their own and builds each with a command of its own;
+ * this changes none of those commands and none of the artefacts (FR-061). It
+ * runs the **root scripts** the instance declares — `start` and
+ * `preview:admin` — and the storefront's own `dev`, by name, so a change to
+ * what a layer runs reaches the composite with nothing here edited. That is
+ * `setup`'s derivation one level over.
+ *
+ * **Why the storefront runs `dev` and the other two do not.** The instance's
+ * `start` and `preview:admin` serve what `setup` built, and `endora install`
+ * runs `setup`. It does not build the storefront — it installs it — so the one
+ * storefront command that works on a tree the install left is `next dev`. The
+ * admin is the admin *preview* because FR-060 says so: the built bundle is
+ * what an operator signs in to.
+ *
+ * ## Where the storefront is
+ *
+ * Its own repository (D-195), so nothing in the instance names it. The default
+ * is the sibling `endora install` writes by default — `<dir>-storefront`
+ * (125 FR-160) — and `--storefront-dir` names another. Absent, it is not a
+ * refusal: FR-060 says *"when present"*. Named and absent, it is: the operator
+ * asked for a layer that is not there.
+ *
+ * ## Why process groups
+ *
+ * The instance's own `dev` script is `tsc --watch & node --watch …`, and
+ * `pnpm run` puts a shell between this process and the one doing the work.
+ * Signalling the pid this process spawned reaches the shell and nothing it
+ * backgrounded. Each layer is therefore spawned as the leader of a group of its
+ * own and the whole group is signalled — which is also why an interrupt from
+ * the terminal is received here and forwarded, rather than delivered to every
+ * process at once by the terminal's own group.
+ *
+ * No dependency: `node:child_process` only (research R-10 rejected
+ * `concurrently` and `npm-run-all` for ~60 lines the CLI already has the
+ * primitives for).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { constants } from 'node:os';
+/** The root script a scaffolded instance declares for this command. */
+export const DEV_ALL_SCRIPT = 'dev:all';
+/** A refusal the operator can act on — exit 1. */
+export class DevInputError extends Error {
+    name = 'DevInputError';
+}
+/** An input this run could not read — exit 2. */
+export class DevHostError extends Error {
+    name = 'DevHostError';
+}
+function scriptsOf(manifestPath) {
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const scripts = manifest.scripts;
+        return typeof scripts === 'object' && scripts !== null && !Array.isArray(scripts)
+            ? scripts
+            : {};
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The layers this tree has, decided from its manifests and from nothing else.
+ *
+ * Validates completely before anything is started, in `runNewInstance`'s
+ * discipline: a run that started the API and then refused over the storefront
+ * would leave a process behind for a refusal.
+ */
+export function planDev(options) {
+    const instanceDir = resolve(options.cwd);
+    const manifestPath = join(instanceDir, 'package.json');
+    if (!existsSync(manifestPath)) {
+        throw new DevHostError(`there is no package.json in ${instanceDir}. \`endora dev\` is run from the root of an ` +
+            'instance — the directory `endora install` or `endora new instance` wrote — as ' +
+            '`pnpm run dev:all`.');
+    }
+    const scripts = scriptsOf(manifestPath);
+    if (scripts === null) {
+        throw new DevHostError(`${manifestPath} could not be read as JSON.`);
+    }
+    if (typeof scripts['start'] !== 'string') {
+        throw new DevInputError(`${manifestPath} declares no \`start\` script, so there is no API to start. An instance ` +
+            "declares one; this is not an instance's root, or its manifest has lost the script.");
+    }
+    const notes = [];
+    const processes = [{ label: 'api', cwd: instanceDir, script: 'start' }];
+    if (typeof scripts['preview:admin'] === 'string') {
+        processes.push({ label: 'admin', cwd: instanceDir, script: 'preview:admin' });
+    }
+    else {
+        notes.push('no admin preview: this instance declares no `preview:admin`, because it was written ' +
+            'without the admin member.');
+    }
+    let storefrontDir = null;
+    if (options.storefront !== false) {
+        const named = typeof options.storefront === 'string';
+        const candidate = named
+            ? isAbsolute(options.storefront)
+                ? options.storefront
+                : resolve(instanceDir, options.storefront)
+            : join(dirname(instanceDir), `${basename(instanceDir)}-storefront`);
+        const storefrontManifest = join(candidate, 'package.json');
+        if (!existsSync(storefrontManifest)) {
+            if (named) {
+                throw new DevInputError(`--storefront-dir ${candidate} holds no storefront (no package.json there). Name the ` +
+                    'directory `endora new storefront` wrote, or pass `--no-storefront`.');
+            }
+            notes.push(`no storefront: none at ${candidate}, where \`endora install\` writes it by default. ` +
+                'Pass `--storefront-dir <path>` if yours is elsewhere.');
+        }
+        else {
+            const storefrontScripts = scriptsOf(storefrontManifest);
+            if (storefrontScripts === null || typeof storefrontScripts['dev'] !== 'string') {
+                throw new DevInputError(`${storefrontManifest} declares no \`dev\` script, so there is no storefront to start ` +
+                    'from it. Pass `--no-storefront` to start the other layers alone.');
+            }
+            storefrontDir = candidate;
+            processes.push({ label: 'storefront', cwd: candidate, script: 'dev' });
+        }
+    }
+    return { instanceDir, storefrontDir, processes, notes };
+}
+/**
+ * How a package script is run from here.
+ *
+ * `pnpm run dev:all` sets `npm_execpath` to the package manager that is running
+ * it, so the layers are started by the same one — which matters when the
+ * operator reached pnpm through `corepack pnpm@…` and there is no `pnpm` on
+ * `PATH` at all. Absent, `pnpm` is what an instance declares in its own
+ * `packageManager`.
+ */
+export function commandFor(layer, env = process.env) {
+    const execPath = env['npm_execpath'];
+    if (execPath !== undefined && /pnpm/.test(basename(execPath)) && /\.[cm]?js$/.test(execPath)) {
+        return {
+            label: layer.label,
+            cwd: layer.cwd,
+            bin: process.execPath,
+            argv: [execPath, 'run', layer.script],
+        };
+    }
+    return { label: layer.label, cwd: layer.cwd, bin: 'pnpm', argv: ['run', layer.script] };
+}
+/** `128 + n`, the shell's own convention for a process ended by a signal. */
+function codeForSignal(signal) {
+    const number = constants.signals[signal];
+    return number === undefined ? 1 : 128 + number;
+}
+/** Signal a layer and everything it started. */
+function signalGroup(pid, signal) {
+    try {
+        if (process.platform === 'win32') {
+            process.kill(pid, signal);
+        }
+        else {
+            process.kill(-pid, signal);
+        }
+    }
+    catch {
+        // Already gone, which is the state being asked for.
+    }
+}
+/**
+ * Run the layers until one ends or the operator interrupts, then stop them all.
+ *
+ * Resolves with the exit code the command reports: `0` for an interrupt (the
+ * operator asked for the stop and got it), the ending layer's own code when it
+ * failed, and `1` when a layer ended with `0` — a server that returned is not
+ * running, and the other layers are no use without it.
+ */
+export function superviseDev(processes, options) {
+    const graceMs = options.graceMs ?? 10_000;
+    const { write } = options;
+    return new Promise((resolveCode) => {
+        const running = new Map();
+        const exits = [];
+        let stopping = false;
+        let result = null;
+        let forceTimer = null;
+        const finishWhenAllStopped = () => {
+            void Promise.all(exits).then(() => {
+                if (forceTimer !== null)
+                    clearTimeout(forceTimer);
+                options.signal?.removeEventListener('abort', onAbort);
+                resolveCode(result ?? 0);
+            });
+        };
+        const stopAll = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            const left = [...running.keys()];
+            if (left.length > 0)
+                write(`[endora dev] stopping ${left.join(', ')}`);
+            for (const pid of running.values())
+                signalGroup(pid, 'SIGTERM');
+            forceTimer = setTimeout(() => {
+                for (const pid of running.values())
+                    signalGroup(pid, 'SIGKILL');
+            }, graceMs);
+            forceTimer.unref();
+            finishWhenAllStopped();
+        };
+        function onAbort() {
+            if (result === null)
+                result = 0;
+            stopAll();
+        }
+        for (const entry of processes) {
+            const child = spawn(entry.bin, [...entry.argv], {
+                cwd: entry.cwd,
+                env: process.env,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                detached: process.platform !== 'win32',
+            });
+            const prefix = (chunk, carry) => {
+                const text = carry.rest + chunk;
+                const lines = text.split(/\r?\n/);
+                carry.rest = lines.pop() ?? '';
+                for (const line of lines)
+                    write(`[${entry.label}] ${line}`);
+            };
+            const out = { rest: '' };
+            const err = { rest: '' };
+            child.stdout.setEncoding('utf8').on('data', (chunk) => prefix(chunk, out));
+            child.stderr.setEncoding('utf8').on('data', (chunk) => prefix(chunk, err));
+            if (child.pid !== undefined)
+                running.set(entry.label, child.pid);
+            exits.push(new Promise((done) => {
+                let settled = false;
+                const settle = (code, signal) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    for (const carry of [out, err]) {
+                        if (carry.rest.length > 0)
+                            write(`[${entry.label}] ${carry.rest}`);
+                        carry.rest = '';
+                    }
+                    running.delete(entry.label);
+                    // Anything it left behind in its group goes with it.
+                    if (child.pid !== undefined)
+                        signalGroup(child.pid, 'SIGKILL');
+                    if (!stopping) {
+                        const described = signal !== null ? `was ended by ${signal}` : `exited with code ${String(code)}`;
+                        write(`[endora dev] ${entry.label} ${described}`);
+                        result = signal !== null ? codeForSignal(signal) : code === 0 ? 1 : (code ?? 1);
+                        stopAll();
+                    }
+                    done();
+                };
+                child.on('error', (error) => {
+                    write(`[endora dev] ${entry.label} could not be started: ${error.message}`);
+                    if (!stopping) {
+                        result = 127;
+                        stopAll();
+                    }
+                    settle(127, null);
+                });
+                child.on('close', settle);
+            }));
+        }
+        if (options.signal?.aborted === true) {
+            onAbort();
+        }
+        else {
+            options.signal?.addEventListener('abort', onAbort);
+        }
+    });
+}
+/**
+ * The whole command: plan, print what starts and what does not, supervise.
+ */
+export async function runDev(options) {
+    const plan = planDev(options);
+    options.write(`endora dev — ${plan.processes.map((layer) => `${layer.label} (pnpm run ${layer.script})`).join(', ')}`);
+    for (const note of plan.notes)
+        options.write(`  ${note}`);
+    options.write('  Ctrl-C stops all of them; any one ending stops the rest.');
+    return superviseDev(plan.processes.map((layer) => commandFor(layer)), { write: options.write, signal: options.signal });
+}
+//# sourceMappingURL=index.js.map

package/dist/dev/index.js.map

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

package/dist/generate/divergence.d.ts

@@ -0,0 +1,38 @@
+import { type DivergenceRendering } from '../lib/divergence-artefacts.js';
+import { type ModulePackage } from '../lib/module-packages.js';
+/** Raised when this half has an input it could not read — the caller's exit 2. */
+export declare class DivergenceHostError extends Error {
+    readonly name = "DivergenceHostError";
+}
+/** The "do not edit" header an instance's rendered report carries. */
+export declare const INSTANCE_DIVERGENCE_MARKDOWN_HEADER: string[];
+/** Every deployment in an instance — one directory under `<root>/apps/`. */
+export declare function instanceDeployments(root: string): readonly string[];
+/** One deployment's rendered pair, and what the run could not read producing it. */
+export interface InstanceDivergence {
+    readonly deployment: string;
+    readonly renderings: readonly DivergenceRendering[];
+    readonly overlayModules: readonly string[];
+    readonly entries: number;
+    /** Findings the derivation raised — `check:divergence`'s subject, printed here. */
+    readonly findings: ReadonlyArray<{
+        readonly kind: string;
+        readonly where: string;
+        readonly detail: string;
+    }>;
+    /** Declaration fields this run could not resolve to literals, each named. */
+    readonly unresolvedDeclaration: readonly string[];
+}
+/**
+ * Render one report per deployment this instance holds.
+ *
+ * A tree with no `apps/` directory at all is the empty list rather than a
+ * refusal: an instance scaffolded and not yet customised is a supported state,
+ * and the caller names it as an omission the way it names an absent admin
+ * member.
+ */
+export declare function renderInstanceDivergence(input: {
+    readonly root: string;
+    readonly packages: readonly ModulePackage[];
+}): readonly InstanceDivergence[];
+//# sourceMappingURL=divergence.d.ts.map

package/dist/generate/divergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence.d.ts","sourceRoot":"","sources":["../../src/generate/divergence.ts"],"names":[],"mappings":"AAgEA,OAAO,EAUL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAEnC,kFAAkF;AAClF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAyB;CAChD;AAED,sEAAsE;AACtE,eAAO,MAAM,mCAAmC,UAI/C,CAAC;AAeF,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEnE;AAsBD,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7G,6EAA6E;IAC7E,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,GAAG,SAAS,kBAAkB,EAAE,CAmIhC"}