@endora-commerce/cli 0.100.0

package/dist/inputs/env-file.js

@@ -0,0 +1,134 @@
+/**
+ * The `.env` a command reads values from and writes values into.
+ *
+ * `specs/117-instance-bring-up/contracts/input-resolution.md` tier 2, and R1.3:
+ * **this is not a configuration file for the tool**. `cli-product.md` R2.5's
+ * *"there is no `.endorarc`"* stands unamended. Nothing in a `.env` changes a
+ * verdict, a rule or a behaviour of the CLI — it supplies values, exactly as a
+ * flag does, and it is the *instance's* own runtime configuration, which is to
+ * say the artefact the command's own output already contains.
+ *
+ * ## Blank does not answer
+ *
+ * `SESSION_COOKIE_SECRET=` and no line at all are the same state for whoever has
+ * to fix it, so a blank value does not resolve an input: it is skipped, and the
+ * input goes on to the next tier. Reading it as an answer would let a run print
+ * `env-file=6` over six empty strings and a shop boot with an unsigned session
+ * cookie — a provenance line that is true about where it looked and false about
+ * what it found. `storefront/lib/env.mjs` makes the same call for the same
+ * reason and calls the state `missing` rather than malformed.
+ *
+ * ## What it deliberately does not implement
+ *
+ * No variable expansion (`${OTHER}`), no multi-line values, no `.env.local`
+ * chain. Each is a dialect: `dotenv`, `pnpm`, Next and Docker Compose disagree
+ * about all three, and a scaffold that picked one would write a file that means
+ * something different to the tool that reads it next. What is implemented is the
+ * intersection every one of them agrees on — `KEY=value`, one line, optional
+ * quotes, `#` comments — and a line outside it is left alone rather than
+ * rewritten.
+ */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+function unquote(raw) {
+    const trimmed = raw.trim();
+    const quoted = /^(['"])([\s\S]*)\1$/.exec(trimmed);
+    return quoted === null ? trimmed : quoted[2];
+}
+function parseLine(line) {
+    if (/^\s*(#|$)/.test(line))
+        return { key: null, value: line };
+    const match = ASSIGNMENT.exec(line);
+    if (match === null)
+        return { key: null, value: line };
+    return { key: match[1], value: unquote(match[2]) };
+}
+/**
+ * Every value the file supplies, in file order.
+ *
+ * A blank value is **absent** — see the header. A key repeated in one file keeps
+ * the last assignment, which is what every reader of a `.env` does.
+ */
+export function parseEnvFile(text) {
+    const values = new Map();
+    for (const line of text.split('\n')) {
+        const parsed = parseLine(line);
+        if (parsed.key === null)
+            continue;
+        if (parsed.value.length === 0) {
+            values.delete(parsed.key);
+            continue;
+        }
+        values.set(parsed.key, parsed.value);
+    }
+    return values;
+}
+/**
+ * A value as it is written back, quoted only where it has to be.
+ *
+ * A generated secret is base64 and needs no quoting; a URL needs none. What does
+ * is a value carrying a space, a quote or a `#`, because an unquoted `#` starts
+ * a comment in every dialect above and would truncate the value silently.
+ */
+export function renderEnvValue(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]*$/.test(value))
+        return value;
+    return `"${value.replace(/(["\\])/g, '\\$1')}"`;
+}
+/** A commented-out assignment — `# DATABASE_URL=` — and the key it names. */
+const COMMENTED_ASSIGNMENT = /^\s*#\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * The file's new text: every existing line kept, in place, with the values this
+ * run resolved written over the keys they name and appended where they are new.
+ *
+ * **Kept in place** rather than re-rendered, because the operator may already
+ * have put comments, ordering and their own keys in it, and a scaffold that
+ * rewrote the file would silently discard all three. That is the same rule
+ * `endora new storefront` applies to a directory it will not merge into, one
+ * granularity down.
+ *
+ * ## A commented-out placeholder is filled in, not duplicated
+ *
+ * `endora new instance` writes its `.env` with every declared input present and
+ * **commented out**, because a blank assignment is not the same state as no
+ * assignment: Node's `--env-file` sets `MEILISEARCH_URL=` to the empty string,
+ * and the platform's `??` fallbacks read that as a value. Measured — the
+ * instance acceptance criterion's health route answered 503 over a search
+ * engine that was running, because a file listing every optional input as a
+ * blank had turned twenty "unset"s into twenty empty strings.
+ *
+ * So a value written over such a placeholder replaces the commented line rather
+ * than being appended below it, which keeps the operator's ordering and the
+ * sentence above it and leaves no second assignment of the same key for a
+ * reader to wonder about. A key the run has no value for stays commented, and
+ * therefore stays genuinely unset.
+ */
+export function writeEnvFile(existingText, values) {
+    const remaining = new Map(values);
+    const lines = existingText.length === 0 ? [] : existingText.split('\n');
+    const rewritten = lines.map((line) => {
+        const parsed = parseLine(line);
+        if (parsed.key === null) {
+            const commented = COMMENTED_ASSIGNMENT.exec(line);
+            if (commented === null || !remaining.has(commented[1]))
+                return line;
+            const key = commented[1];
+            const value = remaining.get(key);
+            remaining.delete(key);
+            return `${key}=${renderEnvValue(value)}`;
+        }
+        if (!remaining.has(parsed.key))
+            return line;
+        const value = remaining.get(parsed.key);
+        remaining.delete(parsed.key);
+        return `${parsed.key}=${renderEnvValue(value)}`;
+    });
+    // A trailing empty line is the file's own last newline; append before it so
+    // the result ends in exactly one.
+    while (rewritten.length > 0 && rewritten[rewritten.length - 1].trim().length === 0) {
+        rewritten.pop();
+    }
+    for (const [key, value] of remaining)
+        rewritten.push(`${key}=${renderEnvValue(value)}`);
+    return `${rewritten.join('\n')}\n`;
+}
+//# sourceMappingURL=env-file.js.map

package/dist/inputs/env-file.js.map

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

package/dist/inputs/prompt.d.ts

@@ -0,0 +1,21 @@
+import type { EnvironmentInput } from '@endora-commerce/contracts';
+import type { ResolvedInput } from './resolve.js';
+/** Where the questions are asked and answered. Injected, so a test drives it. */
+export interface PromptIo {
+    readonly input: NodeJS.ReadableStream;
+    readonly output: NodeJS.WritableStream;
+}
+/**
+ * Ask for each input, in the declaration's own order.
+ *
+ * The order is the declaration's rather than an alphabet's: whoever wrote the
+ * declaration decided what an operator is asked first, and a comparator here
+ * would take that decision away from them and give it to the alphabet.
+ *
+ * Each question names **what the value configures**, in the operator's terms —
+ * the declaration's `describes` sentence, which is exactly the field that exists
+ * for this. A prompt reading `SESSION_COOKIE_SECRET:` and nothing else asks a
+ * person to answer a question they have not been told.
+ */
+export declare function promptForInputs(inputs: readonly EnvironmentInput[], language: 'en' | 'pl', io: PromptIo): Promise<readonly ResolvedInput[]>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/inputs/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/inputs/prompt.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,QAAQ,EAAE,IAAI,GAAG,IAAI,EACrB,EAAE,EAAE,QAAQ,GACX,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAoBnC"}

package/dist/inputs/prompt.js

@@ -0,0 +1,59 @@
+/**
+ * The prompt — tier 3, and the whole of what
+ * `cli-product.md` R2.5 gave up when it was amended to R2.5a–e.
+ *
+ * ## It costs no dependency, and that is half the amendment's argument
+ *
+ * `node:readline/promises` is Node core, like the `node:util` `parseArgs` this
+ * program already reads its own arguments with, so Constitution IV is untouched.
+ * R2.5's *"a prompt is a dependency"* is measured false in the package sense and
+ * true in the other one — a prompt depends on a human and a terminal — and that
+ * half is answered by {@link mayPrompt}'s conjunction rather than by an
+ * argument.
+ *
+ * ## It is a fallback, never a default-generator
+ *
+ * Every question here is for a **required** input the flag tier and the `.env`
+ * tier did not answer. An empty answer is not a value: it re-asks. That is the
+ * one place a prompt could quietly become the thing R2.5a forbids — a prompt
+ * that accepted `''` would be a tool inventing the empty string, and it would be
+ * counted as `prompted=` in the provenance line, which is worse than inventing
+ * it in source because it would carry a human's authority.
+ */
+import { createInterface } from 'node:readline/promises';
+/**
+ * Ask for each input, in the declaration's own order.
+ *
+ * The order is the declaration's rather than an alphabet's: whoever wrote the
+ * declaration decided what an operator is asked first, and a comparator here
+ * would take that decision away from them and give it to the alphabet.
+ *
+ * Each question names **what the value configures**, in the operator's terms —
+ * the declaration's `describes` sentence, which is exactly the field that exists
+ * for this. A prompt reading `SESSION_COOKIE_SECRET:` and nothing else asks a
+ * person to answer a question they have not been told.
+ */
+export async function promptForInputs(inputs, language, io) {
+    if (inputs.length === 0)
+        return [];
+    const rl = createInterface({ input: io.input, output: io.output });
+    try {
+        const answers = [];
+        for (const input of inputs) {
+            io.output.write(`\n${input.describes[language]}\n`);
+            let value = '';
+            while (value.length === 0) {
+                // An empty answer re-asks rather than resolving to `''`. See the header:
+                // accepting it would be the tool inventing a value and reporting it as
+                // one a human supplied.
+                value = (await rl.question(`${input.name}: `)).trim();
+            }
+            answers.push({ name: input.name, value, provenance: 'prompt' });
+        }
+        return answers;
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/inputs/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/inputs/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAYzD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAmC,EACnC,QAAqB,EACrB,EAAY;IAEZ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC;QACH,MAAM,OAAO,GAAoB,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACpD,IAAI,KAAK,GAAG,EAAE,CAAC;YACf,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,yEAAyE;gBACzE,uEAAuE;gBACvE,wBAAwB;gBACxB,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACxD,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/inputs/resolve.d.ts

@@ -0,0 +1,163 @@
+import { type EnvironmentConsumer, type EnvironmentInput } from '@endora-commerce/contracts';
+/** Where a value came from. Four tiers, closed, and there is no fifth. */
+export type Provenance = 'flag' | 'env-file' | 'prompt' | 'generated';
+export interface ResolvedInput {
+    readonly name: string;
+    readonly value: string;
+    readonly provenance: Provenance;
+}
+/** An input the run needs and could not resolve, with the flag that supplies it. */
+export interface MissingInput {
+    readonly name: string;
+    /** `--<kebab-cased name>`, so a refusal names the remedy and not only the gap. */
+    readonly flag: string;
+    /** The declaration's own sentence, in the language this run reports in. */
+    readonly describes: string;
+    readonly secret: boolean;
+}
+/** The counts the provenance line prints. */
+export interface ProvenanceCounts {
+    readonly total: number;
+    readonly flags: number;
+    readonly envFile: number;
+    readonly prompted: number;
+    readonly generated: number;
+    /** The residue. Contract-bound to `0` — see the header for why by subtraction. */
+    readonly defaulted: number;
+}
+/** What the process can prove about its own invocation (R3.1). */
+export interface InteractivityFacts {
+    readonly stdinIsTty: boolean;
+    readonly stdoutIsTty: boolean;
+    readonly nonInteractive: boolean;
+    readonly dryRun: boolean;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+}
+/** Is a CI marker set to something meaning yes? */
+export declare function ciMarkerSet(environment: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * May this run issue a prompt? (R3.1 — a conjunction of five.)
+ *
+ * **Checking stdin alone is insufficient and R3.5 forbids it**: a run whose
+ * stdout is captured and whose stdin is inherited would prompt into a log nobody
+ * reads, which is the same hang wearing different clothes.
+ *
+ * There is deliberately no `--interactive` (R3.4). A flag that turns the
+ * assistance on is a flag the person who needs it does not know about.
+ */
+export declare function mayPrompt(facts: InteractivityFacts): boolean;
+/** The facts, read off this process. The only place the resolution touches globals. */
+export declare function interactivityOf(options: {
+    readonly nonInteractive: boolean;
+    readonly dryRun: boolean;
+}): InteractivityFacts;
+/**
+ * The flag that supplies an input, derived from its name and never written down.
+ *
+ * `SESSION_COOKIE_SECRET` → `--session-cookie-secret`. Deriving it is what keeps
+ * the refusal's remedy true for an input nobody has declared yet — including one
+ * a module installed from a registry declares, which no table here could name.
+ */
+export declare function flagFor(name: string): string;
+/** The variable a flag names, inverted from {@link flagFor}. */
+export declare function inputForFlag(flag: string): string;
+/**
+ * A value whose only required properties are that it is unguessable and
+ * per-environment (R4.1).
+ *
+ * **32 random bytes, base64**, one format for every generable input, and the
+ * format is not arbitrary: the platform's own secret settings are decrypted with
+ * `Buffer.from(key, 'base64')` over a 32-byte AES key, so a hex key would fail
+ * at the first secret setting an operator wrote. The same string is a perfectly
+ * good cookie-signing key, which is why one format serves both and no `format`
+ * field exists to get wrong.
+ *
+ * **Never at boot** (R4.4). That is a rule about the platform rather than about
+ * this function, and it is why generation lives in a command an operator ran
+ * once: a signing key that changed on restart would invalidate every session,
+ * and a settings-encryption key that did would make every stored secret
+ * unreadable. Both are worse than a refusal.
+ */
+export declare function generateSecret(): string;
+/**
+ * The counts, over a record loose enough for a proof to break.
+ *
+ * The parameter is `{ provenance: string }` rather than {@link ResolvedInput} on
+ * purpose: `defaulted` is a residue and a residue can only be *shown* to work by
+ * handing in something outside the partition. With the parameter narrowed, the
+ * one assertion that proves the guarantee would not compile.
+ */
+export declare function provenanceCounts(resolved: readonly {
+    readonly provenance: string;
+}[]): ProvenanceCounts;
+/** The line itself (R2.1), in the estate's `read:` grammar. */
+export declare function provenanceLine(resolved: readonly {
+    readonly provenance: string;
+    readonly name: string;
+}[]): string;
+/** Everything a resolution run needs, with no global read inside it. */
+export interface ResolutionRequest {
+    /** The whole declaration of the tree being written. */
+    readonly declared: readonly EnvironmentInput[];
+    /**
+     * The members this run actually writes.
+     *
+     * `specs/118-instance-member-selection/`: an input read by no written member
+     * is **out of the population** — not resolved, not prompted for, not counted,
+     * not refused. Reading it the other way would force a fifth provenance
+     * outcome, because such an input can be neither defaulted (there is nothing to
+     * invent) nor honestly reported as resolved.
+     */
+    readonly members: readonly EnvironmentConsumer[];
+    /** Values given as explicit flags — tier 1. */
+    readonly flags: Readonly<Record<string, string | undefined>>;
+    /** Values the target directory's own `.env` already supplies — tier 2. */
+    readonly envFile: ReadonlyMap<string, string>;
+    readonly interactivity: InteractivityFacts;
+    /** Which language the reported sentences are in. */
+    readonly language: 'en' | 'pl';
+}
+/** What a resolution decided, before anything is asked or written. */
+export interface ResolutionPlan {
+    /** Values already in hand, in declaration order. */
+    readonly resolved: readonly ResolvedInput[];
+    /**
+     * Required, unanswered, and this run will ask — or, under `--dry-run`, would
+     * have (R2.4).
+     *
+     * One list for both, because they are one answer to one question: *which
+     * inputs is nobody supplying?* A dry run reports it, a real run acts on it,
+     * and splitting them would let the two drift into disagreeing about the very
+     * thing a dry run exists to preview.
+     */
+    readonly toPrompt: readonly EnvironmentInput[];
+    /** Secret, generable, unanswered — a value this run may supply (R4.1). */
+    readonly toGenerate: readonly EnvironmentInput[];
+    /** Required, unanswered, and this run may not ask: the refusal (R3.2). */
+    readonly missing: readonly MissingInput[];
+    /** Declared, in scope, and legitimately left unset — an optional nobody set. */
+    readonly unset: readonly EnvironmentInput[];
+}
+/**
+ * The first two tiers, and the decision about the other two.
+ *
+ * Pure: it asks nothing, generates nothing and writes nothing, so a caller can
+ * print the whole plan under `--dry-run` (R2.4, R7.3) and a test can assert
+ * every branch without a terminal.
+ *
+ * **A condition is answered against the values this run has resolved**, not
+ * against `process.env`, which is the case that happens: a run supplying
+ * `--catalog-search-backend meilisearch` on its command line has to be asked for
+ * `MEILISEARCH_URL` in the same run rather than in the next one.
+ */
+export declare function planResolution(request: ResolutionRequest): ResolutionPlan;
+/**
+ * The refusal a run that may not ask prints, naming **every** missing input
+ * (R3.2).
+ *
+ * Not one per run: a twelve-input setup must not be twelve failed invocations,
+ * and that is a design point rather than a nicety — it is precisely the
+ * experience the owner asked to have removed.
+ */
+export declare function missingInputsRefusal(missing: readonly MissingInput[], facts: InteractivityFacts): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/inputs/resolve.d.ts.map

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