@endora-commerce/cli 0.100.0

package/dist/lib/entity-index-artefact.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The entity index — one host's answer to *"which modules did I install, and
+ * which entity classes did each of them publish?"*
+ * (`specs/109-backend-test-kit/tasks.md` T065).
+ *
+ * ## Why a generated artefact and not a package
+ *
+ * A server-bound test writes rows, and to write one it needs the entity class
+ * **the ORM registered**: a structurally identical copy read out of a package's
+ * source is a class the ORM never discovered, and `em.find` against it answers
+ * with nothing (D-160.6, D-160.6.1). A module package publishes one `entities`
+ * array and **no entity class by name** (D-168), so the class is picked out of
+ * that array by name — `@endora-commerce/test-kit/support`'s `entityNamedIn`,
+ * which is the lookup half and holds no population.
+ *
+ * The population is where this has to be a generated file. *Which modules one
+ * deployment installed* is the single fact a package that may name no module is
+ * forbidden to know (109 R2.2, FR-001), which is why
+ * `backend/test/helpers/package-entities.ts` is permanently host-owned and may
+ * neither move into a module package nor be published by the kit
+ * (`specs/084-small-f4-package-layout/contracts/module-package-layout.md` R10's
+ * closing paragraph — *"do not re-open this on volume"*). This file is the
+ * successor that paragraph names: the per-host artefact that gives a
+ * **stranger's** host the same index, derived from their install rather than
+ * from ours.
+ *
+ * ## One derivation, two populations
+ *
+ * `contracts/instance-repository.md` R3.5, exactly as `admin-artefacts.ts` is
+ * shared: `endora generate` renders it over the packages an instance installed,
+ * and `composer:generate` renders it over this repository's workspace members.
+ * A second implementation inside either host would be two answers to one
+ * question — and the one this repository holds would be the one nobody outside
+ * could correct.
+ *
+ * ## What it deliberately does not import, and the annotation that is not optional
+ *
+ * Nothing but the installed modules. A `satisfies InstalledEntityIndex` would
+ * read better and would put a type-only import of `@endora-commerce/test-kit`
+ * into a file **every** instance renders, including the overwhelming majority
+ * that run no test and never install the kit — an unresolvable specifier the
+ * first time such a client compiles the file. The shape is checked where it is
+ * used, at `entityNamedIn`'s argument position, by the consumer that needs it.
+ *
+ * The export is nevertheless **annotated**, with a type the file declares itself,
+ * and that is a measurement rather than a style: left inferred, `tsc` answers
+ * **TS2742** — *"the inferred type of `installedModuleEntities` cannot be named
+ * without a reference to `../node_modules/@endora-commerce/mod-…/dist/backend/
+ * entities/….entity`"* — once per entity class in the whole install, because the
+ * inferred type is a tuple of classes declared inside packages whose paths the
+ * consumer cannot name. The annotation is structurally the kit's
+ * `InstalledEntityIndex` and loses nothing a caller uses: `entityNamedIn` takes
+ * the module id as a **string**, so per-key precision has no reader.
+ */
+import { type ModulePackage } from './module-packages.js';
+/** The symbol the artefact exports, named once so every consumer agrees. */
+export declare const ENTITY_INDEX_EXPORT = "installedModuleEntities";
+/** One installed module, as the index names it. */
+export interface EntityIndexEntry {
+    /** `endora.id`, the identity of record (D-142) — the index's key. */
+    readonly moduleId: string;
+    /** The bare specifier of its published `./backend`. */
+    readonly specifier: string;
+}
+/**
+ * Every installed module package, sorted by module id.
+ *
+ * **A module that publishes no `./backend` is refused, not skipped.** A skip is
+ * how a whole module goes missing from an index without a word, and the failure
+ * then lands on whichever test asked for one of its entities — as
+ * `ModuleNotInstalledError` for a module the client did install, which sends
+ * them to look at their install instead of at the artefact. It is the same
+ * reason `collectAdminContributions` refuses a package whose admin layer no
+ * subpath covers.
+ *
+ * There is no *"has entities"* predicate and there deliberately cannot be one:
+ * whether the array is empty is a runtime fact about a package's JavaScript, and
+ * a generator that imported every installed module to find out would evaluate a
+ * client's whole backend to render a test artefact. Seven of this repository's
+ * own module packages publish an empty array, and an empty array in the index is
+ * the correct, loud answer — `entityNamed` names every class the array does
+ * declare, `(empty)` included.
+ */
+export declare function collectEntityIndexEntries(packages: readonly ModulePackage[]): readonly EntityIndexEntry[];
+/** Where the artefact lands, relative to the workspace root a host owns. */
+export declare function entityIndexOutputPathIn(root: string): string;
+/**
+ * The "do not edit" header **this repository's own** generator writes, and the
+ * default for the same reason `emitAdminRegistry`'s is: an instance's own header
+ * says something different, and it passes it in.
+ */
+export declare const COMPOSER_ENTITY_INDEX_HEADER: string;
+/** Pure render of the entity index, exported so a test can drive it. */
+export declare function emitEntityIndex(entries: readonly EntityIndexEntry[], header?: string): string;
+//# sourceMappingURL=entity-index-artefact.d.ts.map

package/dist/lib/entity-index-artefact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-index-artefact.d.ts","sourceRoot":"","sources":["../../src/lib/entity-index-artefact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiB9E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,SAAS,gBAAgB,EAAE,CAoB7B;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAYD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,QAIK,CAAC;AAE/C,wEAAwE;AACxE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,MAAM,GAAE,MAAqC,GAC5C,MAAM,CA2ER"}

package/dist/lib/entity-index-artefact.js

@@ -0,0 +1,210 @@
+/**
+ * The entity index — one host's answer to *"which modules did I install, and
+ * which entity classes did each of them publish?"*
+ * (`specs/109-backend-test-kit/tasks.md` T065).
+ *
+ * ## Why a generated artefact and not a package
+ *
+ * A server-bound test writes rows, and to write one it needs the entity class
+ * **the ORM registered**: a structurally identical copy read out of a package's
+ * source is a class the ORM never discovered, and `em.find` against it answers
+ * with nothing (D-160.6, D-160.6.1). A module package publishes one `entities`
+ * array and **no entity class by name** (D-168), so the class is picked out of
+ * that array by name — `@endora-commerce/test-kit/support`'s `entityNamedIn`,
+ * which is the lookup half and holds no population.
+ *
+ * The population is where this has to be a generated file. *Which modules one
+ * deployment installed* is the single fact a package that may name no module is
+ * forbidden to know (109 R2.2, FR-001), which is why
+ * `backend/test/helpers/package-entities.ts` is permanently host-owned and may
+ * neither move into a module package nor be published by the kit
+ * (`specs/084-small-f4-package-layout/contracts/module-package-layout.md` R10's
+ * closing paragraph — *"do not re-open this on volume"*). This file is the
+ * successor that paragraph names: the per-host artefact that gives a
+ * **stranger's** host the same index, derived from their install rather than
+ * from ours.
+ *
+ * ## One derivation, two populations
+ *
+ * `contracts/instance-repository.md` R3.5, exactly as `admin-artefacts.ts` is
+ * shared: `endora generate` renders it over the packages an instance installed,
+ * and `composer:generate` renders it over this repository's workspace members.
+ * A second implementation inside either host would be two answers to one
+ * question — and the one this repository holds would be the one nobody outside
+ * could correct.
+ *
+ * ## What it deliberately does not import, and the annotation that is not optional
+ *
+ * Nothing but the installed modules. A `satisfies InstalledEntityIndex` would
+ * read better and would put a type-only import of `@endora-commerce/test-kit`
+ * into a file **every** instance renders, including the overwhelming majority
+ * that run no test and never install the kit — an unresolvable specifier the
+ * first time such a client compiles the file. The shape is checked where it is
+ * used, at `entityNamedIn`'s argument position, by the consumer that needs it.
+ *
+ * The export is nevertheless **annotated**, with a type the file declares itself,
+ * and that is a measurement rather than a style: left inferred, `tsc` answers
+ * **TS2742** — *"the inferred type of `installedModuleEntities` cannot be named
+ * without a reference to `../node_modules/@endora-commerce/mod-…/dist/backend/
+ * entities/….entity`"* — once per entity class in the whole install, because the
+ * inferred type is a tuple of classes declared inside packages whose paths the
+ * consumer cannot name. The annotation is structurally the kit's
+ * `InstalledEntityIndex` and loses nothing a caller uses: `entityNamedIn` takes
+ * the module id as a **string**, so per-key precision has no reader.
+ */
+import { ModulePackageError } from './module-packages.js';
+/**
+ * The subpath a module package publishes its composition root on, and the
+ * subpath the `entities` array comes off.
+ *
+ * Spelled rather than derived from the `exports` map's shape, because a module
+ * package's key set is **closed** (`module-package-layout.md` §2.2) and this is
+ * one of its keys: `MODULE_SUBPATH_MEANINGS` in
+ * `backend/scripts/lib/package-identity-files.ts` refuses a published subpath it
+ * has no meaning for, so `./backend` is a name and not a convention. Deriving it
+ * from a target directory's last segment — the shape the admin layer needs,
+ * because `./admin` is optional and a package may lay it out its own way — would
+ * be answering a question nobody is asking here.
+ */
+const BACKEND_SUBPATH = './backend';
+/** The symbol the artefact exports, named once so every consumer agrees. */
+export const ENTITY_INDEX_EXPORT = 'installedModuleEntities';
+/**
+ * Every installed module package, sorted by module id.
+ *
+ * **A module that publishes no `./backend` is refused, not skipped.** A skip is
+ * how a whole module goes missing from an index without a word, and the failure
+ * then lands on whichever test asked for one of its entities — as
+ * `ModuleNotInstalledError` for a module the client did install, which sends
+ * them to look at their install instead of at the artefact. It is the same
+ * reason `collectAdminContributions` refuses a package whose admin layer no
+ * subpath covers.
+ *
+ * There is no *"has entities"* predicate and there deliberately cannot be one:
+ * whether the array is empty is a runtime fact about a package's JavaScript, and
+ * a generator that imported every installed module to find out would evaluate a
+ * client's whole backend to render a test artefact. Seven of this repository's
+ * own module packages publish an empty array, and an empty array in the index is
+ * the correct, loud answer — `entityNamed` names every class the array does
+ * declare, `(empty)` included.
+ */
+export function collectEntityIndexEntries(packages) {
+    const entries = [];
+    for (const pkg of packages) {
+        if (!pkg.exports.has(BACKEND_SUBPATH)) {
+            const declared = [...pkg.exports.keys()].sort().join(', ') || '(none)';
+            throw new ModulePackageError(`[composer] ${pkg.name} declares itself a module ('${pkg.moduleId}') and publishes no ` +
+                `'${BACKEND_SUBPATH}' subpath (declared: ${declared}). That subpath is the ` +
+                `composition root the platform calls and the one place a module's \`entities\` array ` +
+                `is reachable from, so the entity index cannot name this module's classes at all. ` +
+                `Leaving it out instead would report a module the client installed as one they did ` +
+                `not, which sends them to look at their install rather than at this artefact.`);
+        }
+        entries.push({
+            moduleId: pkg.moduleId,
+            specifier: `${pkg.name}/${BACKEND_SUBPATH.slice(2)}`,
+        });
+    }
+    return [...entries].sort((a, b) => a.moduleId.localeCompare(b.moduleId));
+}
+/** Where the artefact lands, relative to the workspace root a host owns. */
+export function entityIndexOutputPathIn(root) {
+    // The backend member, and **outside its `src`**: the member's own tsconfig
+    // sets `include: ['src']` with `rootDir: 'src'`, so a test artefact placed
+    // there would join the production build, and a `.ts` outside `rootDir` is
+    // TS6059 even for a type-only import. One path in both trees rather than one
+    // per tree — in this repository it lands beside the rest of `backend/test`'s
+    // own support files, which is where its only consumer already is.
+    return `${root}/backend/test/entities.generated.ts`;
+}
+/** A JS identifier for one entry's import binding — by position, never by id. */
+function entityBindingOf(index) {
+    return `entities${index}`;
+}
+/** A module id as an object key: bare when it is an identifier, quoted otherwise. */
+function keyOf(moduleId) {
+    return /^[A-Za-z$_][A-Za-z0-9$_]*$/.test(moduleId) ? moduleId : `'${moduleId}'`;
+}
+/**
+ * The "do not edit" header **this repository's own** generator writes, and the
+ * default for the same reason `emitAdminRegistry`'s is: an instance's own header
+ * says something different, and it passes it in.
+ */
+export const COMPOSER_ENTITY_INDEX_HEADER = `// AUTO-GENERATED by scripts/generate-composer.ts — DO NOT EDIT.\n` +
+    `// Run \`pnpm --filter backend run composer:generate\` to refresh. Editing this\n` +
+    `// file by hand is undone by the next run, and a stale index is a test asking\n` +
+    `// the ORM about a table nothing mapped.\n`;
+/** Pure render of the entity index, exported so a test can drive it. */
+export function emitEntityIndex(entries, header = COMPOSER_ENTITY_INDEX_HEADER) {
+    const imports = entries
+        .map((entry, index) => `import { entities as ${entityBindingOf(index)} } from '${entry.specifier}';`)
+        .join('\n');
+    const body = entries
+        .map((entry, index) => `  ${keyOf(entry.moduleId)}: ${entityBindingOf(index)},`)
+        .join('\n');
+    return `${header}//
+// The entity index — every module **this host installed**, keyed by its module
+// id, with the \`entities\` array that module published on its own \`./backend\`
+// (\`specs/109-backend-test-kit/\` T065).
+//
+// ## What it is for
+//
+// A server-bound test writes rows, and a row needs the entity class **the ORM
+// registered**. A module package publishes one \`entities\` array and no entity
+// class by name (D-168), so a test picks the class out of the array:
+//
+//     import { entityNamedIn } from '@endora-commerce/test-kit/support';
+//     import type { Widget as WidgetRow } from '@endora-commerce/mod-widgets/test-support';
+//     import { ${ENTITY_INDEX_EXPORT} } from './entities.generated.js';
+//
+//     const Widget = entityNamedIn<WidgetRow>(${ENTITY_INDEX_EXPORT}, 'widgets', 'Widget');
+//
+// The **class** comes off the array, which is the one copy the ORM discovered;
+// the **row type** comes off that module's \`./test-support\`, \`export type\` only,
+// so nothing is evaluated twice (R10 property 3).
+//
+// ## Why it is generated and cannot be a package
+//
+// *Which modules one deployment installed* is the single fact a package that may
+// name no module is forbidden to know (109 R2.2, FR-001). The kit therefore
+// carries the lookup and the index's type and never a member of it, and this
+// file — one per host, rendered from that host's own install — carries the
+// population.
+//
+// **Resolution is by class name, never by position.** A tuple index compiles for
+// any ordering, so re-ordering the array inside a module would silently re-point
+// every caller at another table.
+
+${imports}${imports === '' ? '' : '\n'}
+/**
+ * What a module package publishes in its \`entities\` array.
+ *
+ * Declared here rather than imported from the kit, so this file has no
+ * dependency of its own — an instance that runs no test never installs the kit,
+ * and a type-only import of it would be unresolvable the first time such a client
+ * compiled this file. It is structurally \`InstalledEntityIndex\`, which is what
+ * the consumer's argument position checks it against.
+ */
+type PublishedEntityClass = abstract new (...args: never[]) => object;
+
+/**
+ * Every installed module's published entity classes, keyed by module id.
+ *
+ * **Annotated, not inferred**, and that is TS2742 rather than a preference: the
+ * inferred type is a tuple of classes declared inside packages whose paths a
+ * consumer cannot name, so \`tsc\` refuses it once per entity class in the whole
+ * install. Nothing a caller uses is lost — \`entityNamedIn\` takes the module id as
+ * a string.
+ *
+ * A module with an empty array is a module that owns no table, which is a legal
+ * state with a loud answer: asking for a class of it names every class it does
+ * declare, \`(empty)\` included. A module that is **absent** is a different
+ * answer — \`ModuleNotInstalledError\`, naming the ids that are here.
+ */
+export const ${ENTITY_INDEX_EXPORT}: Readonly<
+  Record<string, readonly PublishedEntityClass[]>
+> = {
+${body}${body === '' ? '' : '\n'}};
+`;
+}
+//# sourceMappingURL=entity-index-artefact.js.map

package/dist/lib/entity-index-artefact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-index-artefact.js","sourceRoot":"","sources":["../../src/lib/entity-index-artefact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,kBAAkB,EAAsB,MAAM,sBAAsB,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,eAAe,GAAG,WAAW,CAAC;AAEpC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,yBAAyB,CAAC;AAU7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAkC;IAElC,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;YACvE,MAAM,IAAI,kBAAkB,CAC1B,cAAc,GAAG,CAAC,IAAI,+BAA+B,GAAG,CAAC,QAAQ,sBAAsB;gBACrF,IAAI,eAAe,wBAAwB,QAAQ,yBAAyB;gBAC5E,sFAAsF;gBACtF,mFAAmF;gBACnF,oFAAoF;gBACpF,8EAA8E,CACjF,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,SAAS,EAAE,GAAG,GAAG,CAAC,IAAI,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;SACrD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,kEAAkE;IAClE,OAAO,GAAG,IAAI,qCAAqC,CAAC;AACtD,CAAC;AAED,iFAAiF;AACjF,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,WAAW,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,qFAAqF;AACrF,SAAS,KAAK,CAAC,QAAgB;IAC7B,OAAO,4BAA4B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GACvC,oEAAoE;IACpE,mFAAmF;IACnF,iFAAiF;IACjF,4CAA4C,CAAC;AAE/C,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAC7B,OAAoC,EACpC,SAAiB,4BAA4B;IAE7C,MAAM,OAAO,GAAG,OAAO;SACpB,GAAG,CACF,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CACf,wBAAwB,eAAe,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,SAAS,IAAI,CAChF;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,GAAG,OAAO;SACjB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC;SAC/E,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO,GAAG,MAAM;;;;;;;;;;;;;kBAaA,mBAAmB;;iDAEY,mBAAmB;;;;;;;;;;;;;;;;;;EAkBlE,OAAO,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;eA0BvB,mBAAmB;;;EAGhC,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;CAC/B,CAAC;AACF,CAAC"}

package/dist/lib/instance-build-inputs.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The per-instance build inputs — the values that genuinely vary between one
+ * deployment of this platform and another, and that nothing derives
+ * (`specs/110-instance-repository/` FR-009).
+ *
+ * ## Why this file exists
+ *
+ * They are an **instance's**, not our pipeline's. Under D-207 a client's
+ * repository depends on the platform, the admin shell and the module packages
+ * and holds a copy of none of them, so everything a build needs is either
+ * derived by the platform or is one of these; and `spec.md` §5 is the argument
+ * against the *kind* of input that does not belong here — five of
+ * `endora.config.ts`'s six fields restate a fact something already derives,
+ * which is D-100 at the scale of a whole file in a tree we cannot grep.
+ *
+ * **§5 was written down as "there is no fifth", and a fifth arrived.**
+ * `STOREFRONT_DOMAIN` was already a required CI/CD variable, classified in
+ * `.gitlab-ci.yml` as a domain the pipeline *deploys to* rather than one a build
+ * reads — correct until the storefront had to name its own public origin inside
+ * a bundle. Nothing derives it, and the storefront's canonicals, its sitemap and
+ * its robots.txt are all built from it. So the closed set was a count of a
+ * derived fact written into prose (D-100); what survives the correction is §5's
+ * actual test — *does something already derive this?* — which is a predicate and
+ * not a number.
+ *
+ * Before this declaration existed, the set was written in three places in
+ * `.gitlab-ci.yml` and nowhere else: a comment block listing the CI/CD
+ * variables an operator must set, and two `docker build` invocations spelling
+ * the mapping from an input to the build argument each image reads. Nothing
+ * reconciled the three, nothing could tell a client which values they owe, and
+ * **`DEPLOYMENT` reached no build at all** — the one input whose absence is
+ * silent, because `selectedDeployment` reads a blank value as *bare core* and a
+ * deployment whose overlay modules simply did not compose looks exactly like a
+ * deployment that has none.
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * Each input carries its **meaning**, an **example**, and its **default** —
+ * `null` where the instance must supply one, because a value the tool invented
+ * is a value nobody reviewed (`cli-product.md` R2.5). Each also carries its
+ * consumers: which build reads it, under which name, and how the value is
+ * spelled.
+ *
+ * The spelling is a **shell expansion** over the input names (`https://${API_DOMAIN}`)
+ * for one reason: it is the form a pipeline can paste verbatim and the form a
+ * renderer can substitute into, so the mapping has one home rather than one per
+ * consumer. Nothing here knows what a GitLab job is; `.gitlab-ci.yml` reads
+ * this list, `endora new instance` will render an `.env` and a pipeline from it
+ * (T132), and `backend/test/unit/ci/instance-build-inputs.test.ts` is what
+ * refuses a third spelling.
+ */
+/** Which build reads an input. The storefront is scaffolded separately (D-195). */
+export type BuildTarget = 'backend' | 'admin' | 'storefront';
+/** One build's use of one input. */
+export interface BuildInputConsumer {
+    readonly target: BuildTarget;
+    /** The `ARG` the image declares, and the `--build-arg` a pipeline passes. */
+    readonly buildArg: string;
+    /**
+     * The value, written as a shell expansion over the input names.
+     *
+     * `${API_DOMAIN}` rather than `$API_DOMAIN`: both expand, and the braced form
+     * is the one that cannot silently swallow a following character.
+     */
+    readonly value: string;
+}
+/** One per-instance build input. */
+export interface InstanceBuildInput {
+    /** The environment variable an operator sets, and the name a value expands to. */
+    readonly name: string;
+    /** What it decides. One sentence, for a client's developer reading it first. */
+    readonly meaning: string;
+    readonly example: string;
+    /**
+     * The value used when the instance sets none, or `null` when it must set one.
+     *
+     * A `null` default is not an omission: it says the platform has no honest
+     * answer, and the refusal belongs to whatever reads it.
+     */
+    readonly default: string | null;
+    readonly consumers: readonly BuildInputConsumer[];
+}
+/**
+ * They are declared in the order a client meets them.
+ *
+ * `DEPLOYMENT` first because it is the one an instance always has — it names
+ * the client's own deployment directory, where their overlay modules and their
+ * `divergence.ts` live (Principle XV) — and the rest are what the two frontend
+ * builds inline into their bundles.
+ */
+export declare const INSTANCE_BUILD_INPUTS: readonly InstanceBuildInput[];
+/** Every consumer of one build target, in declaration order. */
+export declare function buildInputsFor(target: BuildTarget, inputs?: readonly InstanceBuildInput[]): readonly {
+    readonly input: InstanceBuildInput;
+    readonly consumer: BuildInputConsumer;
+}[];
+/**
+ * The `--build-arg` flags one image build takes, one per line.
+ *
+ * Emitted rather than written down, so a pipeline — ours or a client's — passes
+ * what the declaration says and cannot come to pass a fourth spelling of it.
+ *
+ * A default is applied **here**, as POSIX's own `${NAME:-value}` expansion,
+ * rather than being repeated inside every template that mentions the input:
+ * the default has one home, and a reader of the emitted flag can see it.
+ */
+export declare function buildArgFlags(target: BuildTarget, inputs?: readonly InstanceBuildInput[]): readonly string[];
+//# sourceMappingURL=instance-build-inputs.d.ts.map

package/dist/lib/instance-build-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-build-inputs.d.ts","sourceRoot":"","sources":["../../src/lib/instance-build-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;AAE7D,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAkF9D,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,SAAS,kBAAkB,EAA0B,GAC5D,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,EAAE,CAM1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,SAAS,kBAAkB,EAA0B,GAC5D,SAAS,MAAM,EAAE,CAWnB"}

package/dist/lib/instance-build-inputs.js

@@ -0,0 +1,165 @@
+/**
+ * The per-instance build inputs — the values that genuinely vary between one
+ * deployment of this platform and another, and that nothing derives
+ * (`specs/110-instance-repository/` FR-009).
+ *
+ * ## Why this file exists
+ *
+ * They are an **instance's**, not our pipeline's. Under D-207 a client's
+ * repository depends on the platform, the admin shell and the module packages
+ * and holds a copy of none of them, so everything a build needs is either
+ * derived by the platform or is one of these; and `spec.md` §5 is the argument
+ * against the *kind* of input that does not belong here — five of
+ * `endora.config.ts`'s six fields restate a fact something already derives,
+ * which is D-100 at the scale of a whole file in a tree we cannot grep.
+ *
+ * **§5 was written down as "there is no fifth", and a fifth arrived.**
+ * `STOREFRONT_DOMAIN` was already a required CI/CD variable, classified in
+ * `.gitlab-ci.yml` as a domain the pipeline *deploys to* rather than one a build
+ * reads — correct until the storefront had to name its own public origin inside
+ * a bundle. Nothing derives it, and the storefront's canonicals, its sitemap and
+ * its robots.txt are all built from it. So the closed set was a count of a
+ * derived fact written into prose (D-100); what survives the correction is §5's
+ * actual test — *does something already derive this?* — which is a predicate and
+ * not a number.
+ *
+ * Before this declaration existed, the set was written in three places in
+ * `.gitlab-ci.yml` and nowhere else: a comment block listing the CI/CD
+ * variables an operator must set, and two `docker build` invocations spelling
+ * the mapping from an input to the build argument each image reads. Nothing
+ * reconciled the three, nothing could tell a client which values they owe, and
+ * **`DEPLOYMENT` reached no build at all** — the one input whose absence is
+ * silent, because `selectedDeployment` reads a blank value as *bare core* and a
+ * deployment whose overlay modules simply did not compose looks exactly like a
+ * deployment that has none.
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * Each input carries its **meaning**, an **example**, and its **default** —
+ * `null` where the instance must supply one, because a value the tool invented
+ * is a value nobody reviewed (`cli-product.md` R2.5). Each also carries its
+ * consumers: which build reads it, under which name, and how the value is
+ * spelled.
+ *
+ * The spelling is a **shell expansion** over the input names (`https://${API_DOMAIN}`)
+ * for one reason: it is the form a pipeline can paste verbatim and the form a
+ * renderer can substitute into, so the mapping has one home rather than one per
+ * consumer. Nothing here knows what a GitLab job is; `.gitlab-ci.yml` reads
+ * this list, `endora new instance` will render an `.env` and a pipeline from it
+ * (T132), and `backend/test/unit/ci/instance-build-inputs.test.ts` is what
+ * refuses a third spelling.
+ */
+/**
+ * They are declared in the order a client meets them.
+ *
+ * `DEPLOYMENT` first because it is the one an instance always has — it names
+ * the client's own deployment directory, where their overlay modules and their
+ * `divergence.ts` live (Principle XV) — and the rest are what the two frontend
+ * builds inline into their bundles.
+ */
+export const INSTANCE_BUILD_INPUTS = [
+    {
+        name: 'DEPLOYMENT',
+        meaning: "The deployment whose overlay modules and divergence declaration this build composes. " +
+            'Unset, or blank, is bare core: no overlay module is composed and the build behaves ' +
+            'byte-for-byte like one with no deployment directory at all.',
+        example: 'acme',
+        // A platform with no deployment is a real and supported state — it is what
+        // `test:backend`'s bare-core shards run — so "none" is a default rather
+        // than a missing value.
+        default: null,
+        consumers: [{ target: 'backend', buildArg: 'DEPLOYMENT', value: '${DEPLOYMENT}' }],
+    },
+    {
+        name: 'API_DOMAIN',
+        meaning: 'The host the instance serves its API from. Both frontends inline it at build time, ' +
+            'because a bundle cannot resolve it later.',
+        example: 'api.example.com',
+        default: null,
+        consumers: [
+            { target: 'admin', buildArg: 'VITE_API_BASE_URL', value: 'https://${API_DOMAIN}' },
+            {
+                target: 'storefront',
+                buildArg: 'NEXT_PUBLIC_API_BASE_URL',
+                value: 'https://${API_DOMAIN}',
+            },
+        ],
+    },
+    {
+        name: 'STOREFRONT_DOMAIN',
+        // It was already a required CI/CD variable and was classified as a domain
+        // this pipeline *deploys to* rather than a build input — true until the
+        // storefront had to name its own origin in a bundle. `endora new storefront`
+        // asks for the same fact as `NEXT_PUBLIC_SITE_URL`, and the backend's
+        // `STOREFRONT_BASE_URL` is built from this variable in
+        // `deploy/compose.prod.yml`, so this is one fact reaching a third reader.
+        meaning: 'The host the instance serves its storefront from. The storefront inlines it at build ' +
+            'time as the origin it puts in every canonical link, in its sitemap and in its ' +
+            'robots.txt — none of which a running container can correct afterwards.',
+        example: 'example.com',
+        default: null,
+        consumers: [
+            {
+                target: 'storefront',
+                buildArg: 'NEXT_PUBLIC_SITE_URL',
+                value: 'https://${STOREFRONT_DOMAIN}',
+            },
+        ],
+    },
+    {
+        name: 'SALES_CHANNEL_CODE',
+        meaning: 'The sales channel the storefront resolves its content against (Principle XII). One ' +
+            'always exists — the install creates it — so this names which, never whether.',
+        example: 'pl_default',
+        default: null,
+        consumers: [
+            {
+                target: 'storefront',
+                buildArg: 'NEXT_PUBLIC_SALES_CHANNEL_CODE',
+                value: '${SALES_CHANNEL_CODE}',
+            },
+        ],
+    },
+    {
+        name: 'DEFAULT_LOCALE',
+        meaning: "The locale the storefront renders when the reader asks for none. A message missing " +
+            'from it falls back to English, which is the platform default every module ships.',
+        example: 'en-US',
+        default: 'en-US',
+        consumers: [
+            {
+                target: 'storefront',
+                buildArg: 'NEXT_PUBLIC_DEFAULT_LOCALE',
+                value: '${DEFAULT_LOCALE}',
+            },
+        ],
+    },
+];
+/** Every consumer of one build target, in declaration order. */
+export function buildInputsFor(target, inputs = INSTANCE_BUILD_INPUTS) {
+    return inputs.flatMap((input) => input.consumers
+        .filter((consumer) => consumer.target === target)
+        .map((consumer) => ({ input, consumer })));
+}
+/**
+ * The `--build-arg` flags one image build takes, one per line.
+ *
+ * Emitted rather than written down, so a pipeline — ours or a client's — passes
+ * what the declaration says and cannot come to pass a fourth spelling of it.
+ *
+ * A default is applied **here**, as POSIX's own `${NAME:-value}` expansion,
+ * rather than being repeated inside every template that mentions the input:
+ * the default has one home, and a reader of the emitted flag can see it.
+ */
+export function buildArgFlags(target, inputs = INSTANCE_BUILD_INPUTS) {
+    const defaults = new Map(inputs
+        .filter((input) => input.default !== null)
+        .map((input) => [`\${${input.name}}`, `\${${input.name}:-${input.default}}`]));
+    return buildInputsFor(target, inputs).map(({ consumer }) => {
+        let value = consumer.value;
+        for (const [plain, withDefault] of defaults)
+            value = value.split(plain).join(withDefault);
+        return `--build-arg ${consumer.buildArg}="${value}"`;
+    });
+}
+//# sourceMappingURL=instance-build-inputs.js.map

package/dist/lib/instance-build-inputs.js.map

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