@endora-commerce/cli 0.100.0

package/dist/new-instance/deploy.d.ts

@@ -0,0 +1,211 @@
+/**
+ * The example deployment files an instance is scaffolded with
+ * (`specs/122-layer-deployment-independence/contracts/layer-independence.md` §3,
+ * under owner ruling **D-230**).
+ *
+ * ## Why this file exists
+ *
+ * `instance-repository.md` R2.1 lists a compose file, an nginx configuration
+ * and an `.env` as *"always in the instance"*. Measured on 2026-09-13, an
+ * instance was handed **none of them**, and no Dockerfile either — so a client
+ * asked for the owner's three-host topology wrote three deployment files from
+ * scratch, against a compose example that lives in *our* repository and assumes
+ * one host.
+ *
+ * ## They are examples, and they are derived from two axes and nothing else
+ *
+ * D-215: an instance holds *examples*, never a client's concrete files. So no
+ * real registry, no real domain, no real secret and none of this repository's
+ * container names appear below. What decides their content is the **member
+ * set** — an admin-less instance has no admin service, no admin image and no
+ * admin origin in its nginx example — and the **topology**, which selects which
+ * files are written and records nothing (R3.2). A topology written into the
+ * root manifest would be a third home for what an instance is, beside the
+ * `dependencies` that are the module set.
+ *
+ * ## The three-host split is derived, not written
+ *
+ * Every service carries the host it belongs to, and {@link composeDocument}
+ * drops an edge whose target is not in the same file. That is what makes R3.6
+ * checkable rather than asserted: the single-host graph partitions with exactly
+ * one edge crossing — `storefront -> backend`, `service_healthy`, a readiness
+ * convenience — and every `service_completed_successfully` edge in the file,
+ * `backend-install -> backend-migrate` and `backend -> backend-install`, lives
+ * entirely inside the backend host. The lost edge is replaced by **nothing**: each layer starts, answers its own
+ * health check and tolerates an absent peer, and a wait-for-it script is the
+ * temptation this rule exists to refuse. An edge added across a boundary
+ * changes what the renderer drops and reds `test/new-instance/deploy-examples.test.ts`.
+ *
+ * ## Nothing here spells a build input twice
+ *
+ * Every `--build-arg` the Dockerfile examples pass, and every `ARG` they
+ * declare, is emitted from `../lib/instance-build-inputs.js` (§2 R2.3). A
+ * fourth spelling of a build input cannot arrive here, because there is no
+ * place to write one.
+ *
+ * ## The development compose is the same catalogue in a second mode
+ *
+ * `specs/125-first-mile-install/spec.md` §4.1 (FR-100…FR-112). A scaffolded
+ * instance also carries `compose.dev.yml`, at its **root** and not under
+ * `deploy/`, and that file is **runnable as written** where every file under
+ * `deploy/` is an example the client has to build and push images for first. It
+ * is rendered by {@link developmentComposeFile} from the **same**
+ * {@link services} records, in `development` mode, and FR-103 is what that mode
+ * exists for: *"no second statement of what Endora needs to run may enter the
+ * tree"*. Two things differ between the modes and both are derived — where a
+ * value comes from (an operator-filled `${NAME}` against an inline-defaulted
+ * `${NAME:-…}`) and whether the service publishes a host port. The image, the
+ * healthcheck and the volume are one record's.
+ *
+ * Defect F-2 is what that requirement is measured against: this repository's own
+ * `docker-compose.yml` and the catalogue below name the same three stateful
+ * images, and they agreed by coincidence until
+ * `test/new-instance/dev-compose.test.ts` made them agree by instrument — that
+ * case reads both files and names both paths, and it is also why no image tag
+ * is written twice in this file, not even in this sentence. Writing a **third**
+ * statement of them into every client's tree is what
+ * this file would have done if the development compose had been authored rather
+ * than derived.
+ */
+import { type EnvironmentInput } from '@endora-commerce/contracts';
+import { type BuildTarget } from '../lib/instance-build-inputs.js';
+import type { FileKind, MemberName } from './template.js';
+/** Which machine layout the examples describe. `--topology`'s vocabulary. */
+export type Topology = 'single-host' | 'three-host';
+/**
+ * The vocabulary, in the order the flag's refusal prints it.
+ *
+ * `single-host` is first because it is the default, on the owner's own *"the
+ * most common scenario is probably all three layers on one machine"* (D-215).
+ */
+export declare const TOPOLOGIES: readonly ["single-host", "three-host"];
+/** What a run that named no topology gets (D-230). */
+export declare const DEFAULT_TOPOLOGY: Topology;
+/**
+ * `--topology`'s value, or an operator-fixable refusal naming the vocabulary.
+ *
+ * F3's class: a flag the operator wrote and can rewrite, which
+ * `instance-tree.md` §4 puts at exit `1`. It is refused rather than defaulted —
+ * a run that silently ignored `--topology three-hosts` would write a
+ * single-host example to a client who asked for three, and the first they would
+ * hear of it is a compose file with a database in it.
+ */
+export declare function assertTopology(value: string): Topology;
+/** Everything the examples are derived from. */
+export interface DeployInput {
+    readonly topology: Topology;
+    /** The admin member was written (§2.4), so there is an admin artefact. */
+    readonly admin: boolean;
+    /** An `.npmrc` was written, so an image build has to carry it (R5.7). */
+    readonly npmrc: boolean;
+    /** The documentation member was written — it changes the image's install. */
+    readonly docs: boolean;
+    /** The root manifest's `engines.node`, which the image's tag is read from. */
+    readonly enginesNode: string;
+    /** The root manifest's `packageManager`, or `undefined`. */
+    readonly packageManager: string | undefined;
+    /**
+     * What this instance reads from its environment — the platform's declaration
+     * unioned with the manifests of the modules it installs.
+     *
+     * The **same** value the root `.env.example` is derived from, threaded here
+     * rather than re-derived, so a variable an operator has to fill in has one
+     * sentence in this repository and not two
+     * (`specs/123-oss-install-experience/` G3). See {@link envExampleFor} for
+     * which of the three sources answers a given name.
+     */
+    readonly declared: readonly EnvironmentInput[];
+}
+/** One planned file, in `template.ts`' own shape. */
+export interface DeployFile {
+    readonly path: string;
+    readonly kind: FileKind;
+    readonly member: MemberName;
+    readonly content: string;
+}
+/** Where the development compose is written, relative to the instance root. */
+export declare const DEV_COMPOSE_PATH = "compose.dev.yml";
+/**
+ * The names a document expands **without** an inline default (FR-111).
+ *
+ * The guard `envExampleFor` does not give you, and the reason it is a second
+ * pattern rather than that function's constant is one character:
+ * `/\$\{([A-Z0-9_]+)(?::-[^}]*)?\}/g`'s default clause is **non-capturing**, so
+ * a match there says nothing about which of the two forms it was. Reusing it
+ * here would report every expansion as defaulted — a guard that is green on
+ * precisely the document it was written to refuse (spec §5.3.3).
+ *
+ * Sorted and de-duplicated, because the sentence this feeds is read by whoever
+ * added the record, and three occurrences of one name is one repair.
+ */
+export declare function undefaultedExpansions(document: string): readonly string[];
+/**
+ * `compose.dev.yml`, rendered from the catalogue in `development` mode.
+ *
+ * **Which services reach it is derived rather than listed** (FR-104): every
+ * service whose image is this repository's own build — `${REGISTRY_IMAGE}/…` —
+ * is an application service and is dropped, and everything else is a backing
+ * service and is kept. So a backing service the catalogue gains appears here in
+ * the same merge request with nothing edited, and an application service it
+ * gains stays out, which is the direction both rules want. A list would have
+ * been a second statement of the partition.
+ *
+ * `extra` exists for the guard's own proof and for nothing else: it is the only
+ * way to put an expansion into this document that the catalogue cannot produce,
+ * and a test that could not do that would be asserting the throw over a
+ * document that never reaches it.
+ */
+export declare function developmentComposeFile(input: DeployInput, extra?: readonly string[]): DeployFile;
+/**
+ * How a **natively running** process reaches the development stack (FR-105).
+ *
+ * One entry per input the rendered document actually answers, composed from the
+ * defaults that document carries — so a changed port or a changed credential
+ * moves the address in the same run, with no second list to edit. An entry
+ * whose composition names something the document does not carry is **not
+ * produced**: a document with no mail catcher yields no `SMTP_URL`, and nothing
+ * here has to know that `SMTP_URL` is the `email` module's input.
+ *
+ * That is the compose half of FR-105's intersection. The other half is the
+ * instance's own declaration and belongs to the caller: *"an input is derived
+ * only when the development compose provides a service for it **and** this
+ * instance declares it"*, and a caller that skipped the second test would write
+ * a value for a module nobody installed.
+ *
+ * `localhost` and not a container name, for the reason FR-104 gives: nothing in
+ * this document is an application, so every reader of these values is a process
+ * on the host reaching a published port.
+ */
+export declare function developmentAddresses(document: string): ReadonlyMap<string, string>;
+/**
+ * Where the mail catcher's own interface is, if this document runs one.
+ *
+ * Not an environment input — nothing reads it — and therefore not in
+ * {@link developmentAddresses}. It is printed, because a client whose instance
+ * sends mail to a port has no way to learn where that mail went.
+ */
+export declare function developmentMailUrl(document: string): string | undefined;
+/**
+ * The base image tag, derived from the `engines.node` the instance declares.
+ *
+ * R2.5a: a version this command chose would be a value nobody reviewed. The
+ * major is what the range actually constrains, and a range with no digit in it
+ * is not something a resolved manifest produces — the running interpreter's own
+ * major is the fallback rather than a literal written here.
+ */
+export declare function nodeImage(enginesNode: string): string;
+/** `corepack`, activating the package manager the root manifest pins. */
+export declare function corepack(packageManager: string | undefined): readonly string[];
+/** The `docker build` line, with every `--build-arg` the declaration emits. */
+export declare function buildInvocation(target: BuildTarget, path: string): readonly string[];
+/** The `ARG`/`ENV` pair per input this target's build reads. */
+export declare function argDeclarations(target: BuildTarget): readonly string[];
+/**
+ * Every `deploy/` file this run writes.
+ *
+ * They are the **client's** kind: rendered once, edited by them, and read back
+ * by nothing here. A file this command would read again would be a second home
+ * for a fact the manifest already holds.
+ */
+export declare function deployFiles(input: DeployInput): readonly DeployFile[];
+//# sourceMappingURL=deploy.d.ts.map

package/dist/new-instance/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/new-instance/deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnF,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,wCAAuE,CAAC;AAE/F,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,EAAE,QAAwB,CAAC;AAExD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAStD;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAgfD,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMzE;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,UAAU,CAgBZ;AAmBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBlF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AA6YD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,CAQ9E;AAgBD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAOpF;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,MAAM,EAAE,CAMtE;AAiQD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,UAAU,EAAE,CAgErE"}