@endora-commerce/platform 0.100.0

package/dist/demo/host-command.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The host's side of `endora demo seed` and `endora demo reset` (feature 113
+ * Phase 0, `contracts/module-demo-data-layer.md` §3.1–§3.2), and the shape the
+ * dispatcher takes an instance's own composition in.
+ *
+ * ## Why it is a *host* command and not a module's
+ *
+ * §3.2: both commands live on the CLI that **composes the platform** and must
+ * not live on `@endora-commerce/cli`. The scaffolder opens no database, resolves
+ * no container and builds no `ModuleContext`; acquiring those would make it the
+ * platform. And the demo run is not any one module's command — it fans out over
+ * every module that declares demo data — so it cannot be a `cliCommands` entry
+ * either, which is addressed as `<module id> <command>` and runs exactly one.
+ *
+ * ## Why it is in the package now, and it was the last thing keeping a
+ * scaffolded instance from running any command at all
+ *
+ * It was `backend/src/cli/demo-command.ts`, and
+ * `test/unit/kernel/host-residue-partition.test.ts` had it ledgered as
+ * *"platform-shaped — the move"*: it names no path in the tree that installs the
+ * platform, so `operator-half.md` §1.1 puts it here. The ledger's `retiredBy`
+ * named the shape this took — *"the logic in the package, a ~20-line entry point
+ * in the application"*.
+ *
+ * The cost of leaving it was measured rather than aesthetic. `endora new
+ * instance` reported `backend/src/cli.ts` as an **omission**, whose written
+ * reason was *"the demo layer around it is exported under no subpath"* — and a
+ * scaffolded instance therefore had no `admin_users create`, so nobody could log
+ * in to the admin bundle A5 and A13 prove is built and styled
+ * (`specs/123-oss-install-experience/` G2).
+ *
+ * ## What is here and what the dispatcher's
+ *
+ * The same split `module-commands.ts` makes: everything decidable with no
+ * process and no database is here, so it can be driven from a test. The three
+ * things that are **not** are the ones §3.3 orders relative to each other — the
+ * production guard first, then the composition, then one system scope — and
+ * their order is `../cli/dispatch.ts`' property rather than a value this file
+ * could return.
+ */
+import type { ModuleManifest } from '@endora-commerce/contracts';
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { DemoManifestEntry, DemoMode } from './plan.js';
+import type { DemoComposition } from './runner.js';
+/** The one host verb this feature adds. */
+export declare const DEMO_HOST_COMMAND = "demo";
+/** One command the **host** offers, in the address an operator types. */
+export interface HostCommandDescriptor {
+    readonly address: string;
+    readonly summary: string;
+}
+export declare const DEMO_HOST_COMMANDS: readonly HostCommandDescriptor[];
+/** Is this argv the host's demo command rather than a module id? */
+export declare function isDemoInvocation(first: string | undefined): boolean;
+/**
+ * `seed` or `reset`, or a refusal naming what the command does offer.
+ *
+ * Refuses rather than defaulting: the two directions are destructive in
+ * opposite ways, and a missing verb that chose one would be the worst possible
+ * guess.
+ */
+export declare function parseDemoVerb(name: string | undefined): DemoMode;
+/**
+ * `--help`, answered from the declaration alone — before anything is composed.
+ *
+ * `program` is how the operator reached the dispatcher, and it is a parameter
+ * for defect F-1's reason: this line used to open `endora demo seed`, and in a
+ * scaffolded instance `endora` is the scaffolder, which has no demo verb
+ * (`specs/125-first-mile-install/spec.md` §2.5). The dispatcher is told; this
+ * function is told by the dispatcher.
+ */
+export declare function demoHelpFor(verb: DemoMode, program?: string): string;
+/** `--list` output for the host's own commands, in `formatCommandList`'s shape. */
+export declare function formatHostCommandList(commands: readonly HostCommandDescriptor[]): string;
+/** A module id that would be unreachable because the host reads it as a verb. */
+export declare class ShadowedHostCommandError extends Error {
+    readonly moduleId: string;
+    constructor(moduleId: string);
+}
+/** The minimum of a resolved manifest entry this file reads. */
+interface ManifestCarrier {
+    readonly manifest: Pick<ModuleManifest, 'id' | 'dependencies' | 'demo'>;
+}
+/**
+ * The runner's input, from the set the composition was actually built from.
+ *
+ * It carries the declaration and not the presence answer: §3.5 puts that
+ * decision in `planDemoRun`, before a context is built and outside every `try`.
+ *
+ * The refusal is here because this is the one place that sees every resolved id
+ * next to the host's own verb. `moduleIdRe` admits `demo`, and the verb is read
+ * first, so such a module would have commands nothing could address — the
+ * *"command silently not found"* failure D-157.8 rejected path-convention
+ * dispatch for.
+ */
+export declare function demoEntriesFrom(entries: readonly ManifestCarrier[]): DemoManifestEntry[];
+/**
+ * The one sentence §5.6 asks for. It says what is absent and what that means,
+ * and enumerates nothing.
+ *
+ * It is the platform's rather than any one tree's because the **dispatcher**
+ * prints it: an instance that supplies no composition loader at all is the
+ * ordinary case (D-216 — a client scaffolding an instance for their own trading
+ * receives no demo artefact unless they ask), and the default has to say so
+ * without the instance holding a copy of the sentence.
+ */
+export declare const NO_DEMO_COMPOSITION_NOTICE: string;
+/** What a composition loader is given. */
+export interface DemoCompositionInput {
+    readonly em: EntityManager;
+    readonly isPresent: (moduleId: string) => boolean;
+}
+/** Present and loaded, or absent with the sentence to print. Never both. */
+export type DemoCompositionLookup = {
+    readonly found: true;
+    readonly composition: DemoComposition;
+} | {
+    readonly found: false;
+    readonly notice: string;
+};
+/**
+ * Finding a tree's demo composition — the parameter, not an implementation.
+ *
+ * **Locating one is the application's**, and that is the whole of why this is a
+ * function type rather than a function: the file lives at a path relative to the
+ * *caller's* own source, which is a path in a tree the platform cannot name
+ * (`operator-half.md` §1.1). This repository's is
+ * `backend/src/demo/composition-loader.ts`; a scaffolded instance supplies none
+ * and gets {@link NO_DEMO_COMPOSITION_NOTICE}.
+ */
+export type DemoCompositionLoader = (input: DemoCompositionInput) => Promise<DemoCompositionLookup>;
+export {};
+//# sourceMappingURL=host-command.d.ts.map

package/dist/demo/host-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-command.d.ts","sourceRoot":"","sources":["../../src/demo/host-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAS9D,CAAC;AAIF,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAOhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,SAAiB,GAAG,MAAM,CAgB5E;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,MAAM,CAKxF;AAED,iFAAiF;AACjF,qBAAa,wBAAyB,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAQtC;AAED,gEAAgE;AAChE,UAAU,eAAe;IACvB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,cAAc,GAAG,MAAM,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,iBAAiB,EAAE,CAWxF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAIkC,CAAC;AAE1E,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACnD;AAED,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,oBAAoB,KACxB,OAAO,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/demo/host-command.js

@@ -0,0 +1,113 @@
+import { UnknownCommandError } from '../cli/module-commands.js';
+/** The one host verb this feature adds. */
+export const DEMO_HOST_COMMAND = 'demo';
+export const DEMO_HOST_COMMANDS = [
+    {
+        address: `${DEMO_HOST_COMMAND} seed`,
+        summary: "Create every present module's demo data, plus the instance composition.",
+    },
+    {
+        address: `${DEMO_HOST_COMMAND} reset`,
+        summary: 'Withdraw the demo data this instance seeded, leaving your own rows alone.',
+    },
+];
+const DEMO_VERBS = ['seed', 'reset'];
+/** Is this argv the host's demo command rather than a module id? */
+export function isDemoInvocation(first) {
+    return first === DEMO_HOST_COMMAND;
+}
+/**
+ * `seed` or `reset`, or a refusal naming what the command does offer.
+ *
+ * Refuses rather than defaulting: the two directions are destructive in
+ * opposite ways, and a missing verb that chose one would be the worst possible
+ * guess.
+ */
+export function parseDemoVerb(name) {
+    const found = DEMO_VERBS.find((verb) => verb === name);
+    if (found)
+        return found;
+    const typed = name === undefined ? DEMO_HOST_COMMAND : `${DEMO_HOST_COMMAND} ${name}`;
+    throw new UnknownCommandError(`[cli] '${typed}' is not a demo command. It offers: ${DEMO_VERBS.join(', ')}.`);
+}
+/**
+ * `--help`, answered from the declaration alone — before anything is composed.
+ *
+ * `program` is how the operator reached the dispatcher, and it is a parameter
+ * for defect F-1's reason: this line used to open `endora demo seed`, and in a
+ * scaffolded instance `endora` is the scaffolder, which has no demo verb
+ * (`specs/125-first-mile-install/spec.md` §2.5). The dispatcher is told; this
+ * function is told by the dispatcher.
+ */
+export function demoHelpFor(verb, program = 'pnpm run cli') {
+    const seeding = verb === 'seed';
+    return (`${program} ${DEMO_HOST_COMMAND} ${verb}\n\n` +
+        (seeding
+            ? 'Creates the demo data of every module that is installed here and switched on,\n' +
+                "in the order the manifest dependency graph gives, then applies this instance's\n" +
+                'own composition — the wiring that spans modules. A module that is not present\n' +
+                'contributes nothing and is reported as a skip, never as an error.\n'
+            : "Withdraws this instance's composition and then every present module's demo\n" +
+                'rows, in the reverse of the order they were created in. Rows you created\n' +
+                'yourself are left alone.\n') +
+        '\nIt refuses to run against a production database — both NODE_ENV and the\n' +
+        'DATABASE_URL are checked, each with its own explicit override — and writes\n' +
+        'nothing when it refuses.\n');
+}
+/** `--list` output for the host's own commands, in `formatCommandList`'s shape. */
+export function formatHostCommandList(commands) {
+    const width = Math.max(...commands.map((command) => command.address.length));
+    return `${commands
+        .map((command) => `  ${command.address.padEnd(width)}  ${command.summary}`)
+        .join('\n')}\n`;
+}
+/** A module id that would be unreachable because the host reads it as a verb. */
+export class ShadowedHostCommandError extends Error {
+    moduleId;
+    constructor(moduleId) {
+        super(`[cli] a module is installed with the id '${moduleId}', which is the host's own ` +
+            `command. The host reads the first argument as its own verb before it dispatches ` +
+            `to a module, so that module's commands would be unreachable. Rename the module.`);
+        this.moduleId = moduleId;
+        this.name = 'ShadowedHostCommandError';
+    }
+}
+/**
+ * The runner's input, from the set the composition was actually built from.
+ *
+ * It carries the declaration and not the presence answer: §3.5 puts that
+ * decision in `planDemoRun`, before a context is built and outside every `try`.
+ *
+ * The refusal is here because this is the one place that sees every resolved id
+ * next to the host's own verb. `moduleIdRe` admits `demo`, and the verb is read
+ * first, so such a module would have commands nothing could address — the
+ * *"command silently not found"* failure D-157.8 rejected path-convention
+ * dispatch for.
+ */
+export function demoEntriesFrom(entries) {
+    return entries.map((entry) => {
+        if (entry.manifest.id === DEMO_HOST_COMMAND) {
+            throw new ShadowedHostCommandError(entry.manifest.id);
+        }
+        return {
+            id: entry.manifest.id,
+            dependencies: entry.manifest.dependencies,
+            ...(entry.manifest.demo === undefined ? {} : { demo: entry.manifest.demo }),
+        };
+    });
+}
+/**
+ * The one sentence §5.6 asks for. It says what is absent and what that means,
+ * and enumerates nothing.
+ *
+ * It is the platform's rather than any one tree's because the **dispatcher**
+ * prints it: an instance that supplies no composition loader at all is the
+ * ordinary case (D-216 — a client scaffolding an instance for their own trading
+ * receives no demo artefact unless they ask), and the default has to say so
+ * without the instance holding a copy of the sentence.
+ */
+export const NO_DEMO_COMPOSITION_NOTICE = 'No demo composition was found in this instance, so only the modules above ran. ' +
+    'A composition is the wiring that spans modules — which categories a menu mirrors, ' +
+    'which channel sells which products — and it belongs to whoever owns the instance, ' +
+    'not to the platform. An instance without one is an ordinary instance.';
+//# sourceMappingURL=host-command.js.map

package/dist/demo/host-command.js.map

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

package/dist/demo/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The platform's demo-data layer (feature 113 Phase 0, D-209).
+ *
+ * Four things, and the split is the design rather than tidiness:
+ *
+ *  - **`guard.ts`** — the production refusal, which must ship because a client
+ *    running a demo seed against production is what it prevents (spec §7).
+ *  - **`scope.ts`** — the reasons the one system scope carries (§3.4).
+ *  - **`plan.ts`** — which modules contribute and in what order, decidable with
+ *    no database, with presence answered before any context exists (§3.5).
+ *  - **`runner.ts` / `report.ts`** — the invocation and what an operator reads.
+ *
+ * ## `./demo`, a host-internal subpath of its own
+ *
+ * `specs/110-instance-repository/` T119b. This barrel had **no `exports` subpath
+ * at all**, and its own header said it was reached through
+ * `@endora-commerce/platform/composition` while the shim above it said the
+ * opposite in as many words — *"it is deliberately not on `./composition` … so
+ * this is the ordinary host-internal reach the other platform shims are, naming
+ * the built file directly"*. What was true of neither sentence: five application
+ * consumers reached `packages/platform/dist/demo/index.js` through a re-export
+ * shim, a specifier that resolves in this checkout and in no client's, which is
+ * the state `check:platform-surface`'s application half exists to refuse.
+ *
+ * The shim's reasoning — *"widening a ruling's table to save a shim would be a
+ * self-certified exemption issued by the party being measured"* — was right
+ * about `./composition`, and is answered by giving this directory an address of
+ * its own instead. It is **host-internal**, for `./composition`'s own reason: a
+ * module *declares* demo data through `@endora-commerce/contracts` and never
+ * names the runner, while the thing that runs one has already composed the
+ * platform. `PUBLISHED_SUBPATHS` is unchanged at five, and a module naming
+ * `@endora-commerce/platform/demo` is `host-internal-subpath` — refused.
+ *
+ * ## Why it carries less than it used to export
+ *
+ * What is on it is a **consequence**, not a ruling, so it is held to its
+ * consumers by `test/unit/kernel/published-surface.test.ts` in `./lifecycle`'s
+ * shape rather than `./composition`'s written table: *a name on the barrel that
+ * no first-party source outside the platform imports is surface parked against a
+ * future need*. Eighteen names were in exactly that state and left in the merge
+ * request that gave the directory an address — `planDemoRun`,
+ * `classifySeedTarget`, `createDemoPackageResolver`, the plan and run-result
+ * shapes among them. They were unreachable while there was no subpath, so
+ * nothing had ever asked for one of them by name; publishing them on the day the
+ * address arrives would park the directory's internals against a need nobody
+ * has. Adding one back is not a breaking change and belongs to the merge request
+ * that gives it a consumer.
+ *
+ * Nothing here imports a module, and the composition that does is a **parameter**
+ * (`DemoComposition`), which is what lets the runner live in the platform at all
+ * (§5.3, D-52/D-53).
+ *
+ * ## What `specs/123-oss-install-experience/` G2 took off it, and why that is
+ * the ratchet working rather than a regression
+ *
+ * Six names went — `formatDemoReport`, `unwrapDemoFailure`, `DemoManifestEntry`
+ * and `DemoMode`, and the whole of what `host-command.ts` would have added. G2
+ * moved the demo **dispatch** into `../cli/dispatch.ts`, so the files that used
+ * to import those six from outside the package — `backend/src/cli.ts` and
+ * `backend/src/cli/demo-command.ts` — either no longer name them or are in this
+ * package now. A name whose last first-party consumer outside the platform went
+ * with the move is surface parked against a future need, which is exactly what
+ * the paragraph above says a subpath is not a place for, and
+ * `test/unit/kernel/published-surface.test.ts` holds the barrel to it in both
+ * directions.
+ *
+ * `host-command.ts` is therefore reachable from outside at three names and not
+ * thirteen: the notice and the two composition-loader shapes, which
+ * `backend/src/demo/composition-loader.ts` imports because locating a tree's own
+ * composition stays that tree's (`operator-half.md` §1.1). `DEMO_HOST_COMMANDS`,
+ * `demoEntriesFrom`, `parseDemoVerb` and the rest have one consumer and it is
+ * `../cli/dispatch.ts`, one directory over inside this package, which reaches
+ * them by relative path and needs no address for them at all.
+ *
+ * Adding one back is not a breaking change and belongs to the merge request that
+ * brings it a consumer.
+ */
+export { mustBeNonProduction, TEST_DATABASE_NAME_PATTERN } from './guard.js';
+export { DEMO_RESET_SCOPE_REASON, DEMO_SEED_SCOPE_REASON } from './scope.js';
+export { runDemo, type DemoComposition, type DemoCompositionResult } from './runner.js';
+export { NO_DEMO_COMPOSITION_NOTICE, type DemoCompositionInput, type DemoCompositionLookup, } from './host-command.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/demo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC"}

package/dist/demo/index.js

@@ -0,0 +1,82 @@
+/**
+ * The platform's demo-data layer (feature 113 Phase 0, D-209).
+ *
+ * Four things, and the split is the design rather than tidiness:
+ *
+ *  - **`guard.ts`** — the production refusal, which must ship because a client
+ *    running a demo seed against production is what it prevents (spec §7).
+ *  - **`scope.ts`** — the reasons the one system scope carries (§3.4).
+ *  - **`plan.ts`** — which modules contribute and in what order, decidable with
+ *    no database, with presence answered before any context exists (§3.5).
+ *  - **`runner.ts` / `report.ts`** — the invocation and what an operator reads.
+ *
+ * ## `./demo`, a host-internal subpath of its own
+ *
+ * `specs/110-instance-repository/` T119b. This barrel had **no `exports` subpath
+ * at all**, and its own header said it was reached through
+ * `@endora-commerce/platform/composition` while the shim above it said the
+ * opposite in as many words — *"it is deliberately not on `./composition` … so
+ * this is the ordinary host-internal reach the other platform shims are, naming
+ * the built file directly"*. What was true of neither sentence: five application
+ * consumers reached `packages/platform/dist/demo/index.js` through a re-export
+ * shim, a specifier that resolves in this checkout and in no client's, which is
+ * the state `check:platform-surface`'s application half exists to refuse.
+ *
+ * The shim's reasoning — *"widening a ruling's table to save a shim would be a
+ * self-certified exemption issued by the party being measured"* — was right
+ * about `./composition`, and is answered by giving this directory an address of
+ * its own instead. It is **host-internal**, for `./composition`'s own reason: a
+ * module *declares* demo data through `@endora-commerce/contracts` and never
+ * names the runner, while the thing that runs one has already composed the
+ * platform. `PUBLISHED_SUBPATHS` is unchanged at five, and a module naming
+ * `@endora-commerce/platform/demo` is `host-internal-subpath` — refused.
+ *
+ * ## Why it carries less than it used to export
+ *
+ * What is on it is a **consequence**, not a ruling, so it is held to its
+ * consumers by `test/unit/kernel/published-surface.test.ts` in `./lifecycle`'s
+ * shape rather than `./composition`'s written table: *a name on the barrel that
+ * no first-party source outside the platform imports is surface parked against a
+ * future need*. Eighteen names were in exactly that state and left in the merge
+ * request that gave the directory an address — `planDemoRun`,
+ * `classifySeedTarget`, `createDemoPackageResolver`, the plan and run-result
+ * shapes among them. They were unreachable while there was no subpath, so
+ * nothing had ever asked for one of them by name; publishing them on the day the
+ * address arrives would park the directory's internals against a need nobody
+ * has. Adding one back is not a breaking change and belongs to the merge request
+ * that gives it a consumer.
+ *
+ * Nothing here imports a module, and the composition that does is a **parameter**
+ * (`DemoComposition`), which is what lets the runner live in the platform at all
+ * (§5.3, D-52/D-53).
+ *
+ * ## What `specs/123-oss-install-experience/` G2 took off it, and why that is
+ * the ratchet working rather than a regression
+ *
+ * Six names went — `formatDemoReport`, `unwrapDemoFailure`, `DemoManifestEntry`
+ * and `DemoMode`, and the whole of what `host-command.ts` would have added. G2
+ * moved the demo **dispatch** into `../cli/dispatch.ts`, so the files that used
+ * to import those six from outside the package — `backend/src/cli.ts` and
+ * `backend/src/cli/demo-command.ts` — either no longer name them or are in this
+ * package now. A name whose last first-party consumer outside the platform went
+ * with the move is surface parked against a future need, which is exactly what
+ * the paragraph above says a subpath is not a place for, and
+ * `test/unit/kernel/published-surface.test.ts` holds the barrel to it in both
+ * directions.
+ *
+ * `host-command.ts` is therefore reachable from outside at three names and not
+ * thirteen: the notice and the two composition-loader shapes, which
+ * `backend/src/demo/composition-loader.ts` imports because locating a tree's own
+ * composition stays that tree's (`operator-half.md` §1.1). `DEMO_HOST_COMMANDS`,
+ * `demoEntriesFrom`, `parseDemoVerb` and the rest have one consumer and it is
+ * `../cli/dispatch.ts`, one directory over inside this package, which reaches
+ * them by relative path and needs no address for them at all.
+ *
+ * Adding one back is not a breaking change and belongs to the merge request that
+ * brings it a consumer.
+ */
+export { mustBeNonProduction, TEST_DATABASE_NAME_PATTERN } from './guard.js';
+export { DEMO_RESET_SCOPE_REASON, DEMO_SEED_SCOPE_REASON } from './scope.js';
+export { runDemo } from './runner.js';
+export { NO_DEMO_COMPOSITION_NOTICE, } from './host-command.js';
+//# sourceMappingURL=index.js.map

package/dist/demo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/demo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAoD,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,0BAA0B,GAG3B,MAAM,mBAAmB,CAAC"}

package/dist/demo/packages.d.ts

@@ -0,0 +1,67 @@
+import type { ModuleDemoManifest } from '@endora-commerce/contracts';
+/**
+ * How the runner finds a module's demo package, in two steps (§6.4).
+ *
+ * Injected rather than reached for, so the three answers §6.3 requires are
+ * assertable with no package on disk — the same reason `isPresent` and
+ * `contextFor` are parameters.
+ */
+export interface DemoPackageResolver {
+    /**
+     * Is this package installed?
+     *
+     * Answered by resolution alone: it must not evaluate the package, because a
+     * package that throws on evaluation is §6.3's **third** answer and not its
+     * second.
+     */
+    isInstalled(name: string): boolean;
+    /**
+     * Load it.
+     *
+     * A throw here is a failure and is reported as one (§3.8). Nothing may catch
+     * it and report the package as absent.
+     */
+    load(name: string): Promise<unknown>;
+}
+/**
+ * The default resolver: Node's own resolution, from the instance's root.
+ *
+ * `from` is the directory whose `node_modules` the package is installed into —
+ * the **instance's**, not the platform's. A bare `import(name)` inside this
+ * package would resolve against `@endora-commerce/platform`'s own dependencies,
+ * where a client's demo package is not and must not be; a host that runs from
+ * somewhere other than the instance root passes its own `from`.
+ *
+ * The probe is `require.resolve`, which answers without evaluating, and the
+ * load is a real ESM `import()` of the path it returned. The bound is stated
+ * rather than discovered: for a **dual** CJS/ESM package `require.resolve`
+ * takes the `require` condition, so the file imported would be the CommonJS
+ * one. Every package this repository generates declares a single `default`
+ * condition per subpath, so the two coincide — measured over every module
+ * package's own manifest in this repository.
+ */
+export declare function createDemoPackageResolver(from?: string): DemoPackageResolver;
+/**
+ * A demo package that loaded but does not carry a demo body.
+ *
+ * Its own error rather than a `TypeError` from the first call, because the two
+ * are indistinguishable to an operator and only one of them names the field to
+ * fix. It reaches the report as {@link DemoRunFailedError}'s `cause`, so §3.8's
+ * *"naming the module"* holds for it exactly as for a body that threw.
+ */
+export declare class DemoPackageShapeError extends Error {
+    readonly moduleId: string;
+    readonly packageName: string;
+    constructor(moduleId: string, packageName: string, detail: string);
+}
+/**
+ * The demo body a loaded package supplies, or a refusal naming what is wrong.
+ *
+ * **`after` is deliberately not read from here.** Ordering is decided by
+ * `planDemoRun` from the *declarations*, before anything is loaded — that is
+ * the property that makes the plan decidable with no database and no module
+ * system — so a package's own `after` would arrive after the sequence it wants
+ * to change. The module's manifest keeps that field, as it keeps `package`.
+ */
+export declare function demoBodyFromPackage(loaded: unknown, moduleId: string, packageName: string): ModuleDemoManifest<never>;
+//# sourceMappingURL=packages.d.ts.map

package/dist/demo/packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/demo/packages.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,MAAsB,GAAG,mBAAmB,CAmB3F;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM;gBADnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EAC5B,MAAM,EAAE,MAAM;CAUjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,kBAAkB,CAAC,KAAK,CAAC,CAwB3B"}

package/dist/demo/packages.js

@@ -0,0 +1,132 @@
+/**
+ * The escape hatch's resolution half (feature 113, T235 —
+ * `specs/113-module-owned-demo-data/contracts/module-demo-data-layer.md` §6).
+ *
+ * A module that would ship more demo data than the budget allows moves it into
+ * a package of its own and names that package in `demo.package`. This file is
+ * how the runner finds it, and it exists as a file of its own so that §6.4's
+ * two steps are two functions:
+ *
+ * > **§6.4** The runner MUST probe resolvability before importing, and MUST NOT
+ * > distinguish the two states by catching the import's throw.
+ *
+ * A single `try { await import(name) } catch { … }` that reads the throw as
+ * *not installed* answers both questions with one signal, so a demo package
+ * that is installed and **broken** reads as absent and the run continues
+ * quietly without it. That is
+ * the fail-open shape `check:port-catches` refuses one seam over, and it is the
+ * reason {@link DemoPackageResolver} has two methods rather than one.
+ *
+ * ## Why the name is not an `import` specifier, measured
+ *
+ * §6.2, and it is the whole reason this resolution is the runner's rather than
+ * the module's. A module package's `package.json` is generated
+ * (`backend/scripts/lib/module-package-manifest.ts`), and `peerNamesOf` records
+ * every specifier `namedSpecifiers` yields **with no filter on kind** — a walk
+ * that recognises `dynamic-import`. So a literal
+ * `await import('@endora-commerce/mod-<id>-demo')` written anywhere in the
+ * module's own sources is emitted as a **required** peer, and pnpm then installs
+ * the demo package for every client, which is the opposite of what the field is
+ * for. Both halves re-verified against those two files on 2026-09-09.
+ *
+ * The consequence is worth stating because it decides the shape below: since
+ * the module may not import the package, the module's own body cannot *use* it
+ * either. So the package supplies the demo body, and the declaration's own
+ * `seed` / `reset` are not called when it loads — §6.3's first row in its own
+ * words, *"the module's demo data is the package's"*.
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+/**
+ * The default resolver: Node's own resolution, from the instance's root.
+ *
+ * `from` is the directory whose `node_modules` the package is installed into —
+ * the **instance's**, not the platform's. A bare `import(name)` inside this
+ * package would resolve against `@endora-commerce/platform`'s own dependencies,
+ * where a client's demo package is not and must not be; a host that runs from
+ * somewhere other than the instance root passes its own `from`.
+ *
+ * The probe is `require.resolve`, which answers without evaluating, and the
+ * load is a real ESM `import()` of the path it returned. The bound is stated
+ * rather than discovered: for a **dual** CJS/ESM package `require.resolve`
+ * takes the `require` condition, so the file imported would be the CommonJS
+ * one. Every package this repository generates declares a single `default`
+ * condition per subpath, so the two coincide — measured over every module
+ * package's own manifest in this repository.
+ */
+export function createDemoPackageResolver(from = process.cwd()) {
+    const require = createRequire(pathToFileURL(`${from}/package.json`));
+    return {
+        isInstalled(name) {
+            // The one `catch` in this file, and it is not a classification: a
+            // resolution failure *is* the answer to "is this installed", and nothing
+            // about evaluation has happened yet. §6.3's third answer is decided by
+            // `load` throwing, one method down, where nothing catches it.
+            try {
+                require.resolve(name);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async load(name) {
+            return await import(pathToFileURL(require.resolve(name)).href);
+        },
+    };
+}
+/**
+ * A demo package that loaded but does not carry a demo body.
+ *
+ * Its own error rather than a `TypeError` from the first call, because the two
+ * are indistinguishable to an operator and only one of them names the field to
+ * fix. It reaches the report as {@link DemoRunFailedError}'s `cause`, so §3.8's
+ * *"naming the module"* holds for it exactly as for a body that threw.
+ */
+export class DemoPackageShapeError extends Error {
+    moduleId;
+    packageName;
+    constructor(moduleId, packageName, detail) {
+        super(`[demo] module '${moduleId}' names '${packageName}' in \`demo.package\`, and that ` +
+            `package ${detail}. A demo package exports \`demo\`: an object with a \`summary\` ` +
+            'string and \`seed\` and \`reset\` functions, the same shape a module declares in ' +
+            'its own `manifest.ts`.');
+        this.moduleId = moduleId;
+        this.packageName = packageName;
+        this.name = 'DemoPackageShapeError';
+    }
+}
+/**
+ * The demo body a loaded package supplies, or a refusal naming what is wrong.
+ *
+ * **`after` is deliberately not read from here.** Ordering is decided by
+ * `planDemoRun` from the *declarations*, before anything is loaded — that is
+ * the property that makes the plan decidable with no database and no module
+ * system — so a package's own `after` would arrive after the sequence it wants
+ * to change. The module's manifest keeps that field, as it keeps `package`.
+ */
+export function demoBodyFromPackage(loaded, moduleId, packageName) {
+    if (typeof loaded !== 'object' || loaded === null || !('demo' in loaded)) {
+        return refuse(moduleId, packageName, 'exports no `demo`');
+    }
+    const demo = loaded.demo;
+    if (typeof demo !== 'object' || demo === null) {
+        return refuse(moduleId, packageName, 'exports a `demo` that is not an object');
+    }
+    const candidate = demo;
+    if (typeof candidate.summary !== 'string' || candidate.summary.length === 0) {
+        return refuse(moduleId, packageName, 'exports a `demo` with no `summary`');
+    }
+    if (typeof candidate.seed !== 'function' || typeof candidate.reset !== 'function') {
+        return refuse(moduleId, packageName, 'exports a `demo` whose `seed` or `reset` is not a function');
+    }
+    return {
+        summary: candidate.summary,
+        seed: candidate.seed,
+        reset: candidate.reset,
+    };
+}
+function refuse(moduleId, packageName, detail) {
+    throw new DemoPackageShapeError(moduleId, packageName, detail);
+}
+//# sourceMappingURL=packages.js.map

package/dist/demo/packages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.js","sourceRoot":"","sources":["../../src/demo/packages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA4BzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAe,OAAO,CAAC,GAAG,EAAE;IACpE,MAAM,OAAO,GAAG,aAAa,CAAC,aAAa,CAAC,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC;IACrE,OAAO;QACL,WAAW,CAAC,IAAI;YACd,kEAAkE;YAClE,yEAAyE;YACzE,uEAAuE;YACvE,8DAA8D;YAC9D,IAAI,CAAC;gBACH,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACtB,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI;YACb,OAAO,MAAM,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAEnC;IACA;IAFX,YACW,QAAgB,EAChB,WAAmB,EAC5B,MAAc;QAEd,KAAK,CACH,kBAAkB,QAAQ,YAAY,WAAW,kCAAkC;YACjF,WAAW,MAAM,kEAAkE;YACnF,mFAAmF;YACnF,wBAAwB,CAC3B,CAAC;QATO,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;QAS5B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAe,EACf,QAAgB,EAChB,WAAmB;IAEnB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC;QACzE,OAAO,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,IAAI,GAAI,MAA4B,CAAC,IAAI,CAAC;IAChD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,wCAAwC,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,SAAS,GAAG,IAA0C,CAAC;IAC7D,IAAI,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5E,OAAO,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,oCAAoC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAClF,OAAO,MAAM,CACX,QAAQ,EACR,WAAW,EACX,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,QAAgB,EAAE,WAAmB,EAAE,MAAc;IACnE,MAAM,IAAI,qBAAqB,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;AACjE,CAAC"}