@endora-commerce/cli 0.100.0

package/dist/new-storefront/npmrc.js

@@ -0,0 +1,217 @@
+/**
+ * The `.npmrc` a scaffolded storefront installs through — and the reason the
+ * command writes none unless it is asked.
+ *
+ * ## No `--registry` writes no file, and that is the destination
+ *
+ * `specs/104-package-publication/contracts/registry-and-scope.md` R3.4: a public
+ * consumer installs `@endora-commerce/*` with no `.npmrc` and no token. So the
+ * path this command takes **without being told anything** is the public one, and
+ * the private registry is the argument. The other way round would make every
+ * open-source consumer's first act the deletion of a file naming a host they
+ * have no credential for.
+ *
+ * ## The file holds no secret, and that is enforced rather than trusted
+ *
+ * The token is written as an environment **reference**, `${ENDORA_NPM_TOKEN}`,
+ * which pnpm expands at install time in both the registry and the auth position
+ * (measured, `research.md` §5). So the file is committable, and a registry URL
+ * carrying its own credentials — `https://user:token@host/…`, the one shape that
+ * would put a secret into a client's repository — is a refusal rather than a
+ * string this module copies through.
+ *
+ * ## The scope is derived from what the storefront installs
+ *
+ * Never a literal: the scopes are read off the reference storefront's own
+ * `workspace:` ranges, which are exactly the packages a registry has to answer
+ * for. A checkout that grows a second scope gets a second registry line in the
+ * same run, and a storefront that declares no scoped workspace dependency is a
+ * refusal — an `.npmrc` naming no scope configures nothing.
+ *
+ * ## A registry does not have to serve its tarballs under its metadata path
+ *
+ * That premise is what this file held until the acceptance criterion's registry
+ * mode was first run. It wrote **one** auth line, keyed on the configured
+ * endpoint, on the reasoning that *a credential is a property of the endpoint
+ * rather than of a scope*. The second half of that sentence is still true and the
+ * first no longer follows from it: the endpoint serves the **packument**, and the
+ * `dist.tarball` URL inside that document is the **server's** to choose. GitLab
+ * chooses the owning project's path, so an instance- or group-level endpoint
+ * answers with a tarball on `/api/v4/projects/<id>/packages/npm/…` — a path whose
+ * project id varies per package and is unknowable at the moment this file is
+ * written. The endpoint key does not cover it, that one fetch goes out
+ * unauthenticated, and GitLab answers an absent credential with **404**, the same
+ * sentence it gives for a package that was never published (`research.md` §6). So
+ * the install fails with *the package is not there*, immediately after a metadata
+ * request for that same package succeeded.
+ *
+ * `authKeys` below is the repair, and it is where the reasoning for the shape
+ * that was chosen — and for the two that were not — is written down.
+ */
+import { StorefrontInputError, workspaceRanges } from './reference.js';
+/**
+ * The environment variable the auth line refers to.
+ *
+ * One name, spelled here and in `.gitlab-ci.yml`'s `publish:packages` job,
+ * because it is the name the contract writes (R3) and the one an operator is told
+ * to set. It is deliberately not an option: a per-scaffold variable name is a
+ * support conversation per client for no capability.
+ */
+export const TOKEN_VARIABLE = 'ENDORA_NPM_TOKEN';
+/**
+ * The registry URL as an `.npmrc` line writes it: absolute, `http(s)`, with the
+ * trailing slash GitLab's own troubleshooting requires (R3.2).
+ */
+export function normalizeRegistry(registry) {
+    const raw = registry.trim();
+    if (raw.length === 0) {
+        throw new StorefrontInputError('`--registry` was given no value. It names the endpoint the scaffolded storefront ' +
+            'installs `@endora-commerce/*` from; omit the flag entirely to get the public ' +
+            'registry, which is what an open-source consumer installs from and what this command ' +
+            'does when it is not told otherwise.');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new StorefrontInputError(`\`--registry ${raw}\` is not an absolute URL. An \`.npmrc\` registry line is a URL and ` +
+            `nothing else — npm resolves no relative form — so a value that is not one would be ` +
+            `written into the client's file and fail at their install rather than at this command.`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new StorefrontInputError(`\`--registry ${raw}\` names the "${url.protocol}" scheme. A registry is reached over ` +
+            `http or https; anything else is a value npm cannot fetch from.`);
+    }
+    if (url.username.length > 0 || url.password.length > 0) {
+        throw new StorefrontInputError(`\`--registry\` carries credentials in the URL. The \`.npmrc\` this command writes is a ` +
+            `file the client commits, and it holds no secret by construction: the token is written ` +
+            `as \${${TOKEN_VARIABLE}} and expanded at install time. Give the registry without its ` +
+            `userinfo and put the credential in the environment.`);
+    }
+    if (url.search.length > 0 || url.hash.length > 0) {
+        throw new StorefrontInputError(`\`--registry ${raw}\` carries a query or a fragment. Neither is part of a registry ` +
+            `endpoint, and the auth line is keyed on the host and path, so a value carrying one ` +
+            `would authenticate for an address the fetches never use.`);
+    }
+    const text = url.toString();
+    return text.endsWith('/') ? text : `${text}/`;
+}
+/**
+ * The scopes a scaffolded storefront installs from a registry.
+ *
+ * Read off the reference storefront's `workspace:` ranges — the packages that
+ * stop resolving the moment the copy leaves the workspace — rather than off the
+ * checkout's members. The two populations are not the same question: what the
+ * platform *publishes* is `check:release-intent`'s, and what this storefront
+ * *installs* is this one's.
+ */
+export function installedScopes(manifest) {
+    const scopes = new Set();
+    for (const range of workspaceRanges(manifest)) {
+        if (!range.name.startsWith('@'))
+            continue;
+        const slash = range.name.indexOf('/');
+        if (slash > 0)
+            scopes.add(range.name.slice(0, slash));
+    }
+    return [...scopes].sort();
+}
+/**
+ * The keys the auth lines are written under: the endpoint, and the host it is on.
+ *
+ * Both are npm's own spelling for a credential — the request URL with its scheme
+ * removed — and both matter, for two different fetches.
+ *
+ * **The endpoint key** is the narrowest key covering the one address the operator
+ * actually named, and it is what GitLab's own documentation writes. It is kept
+ * rather than replaced by the broader one below: pnpm was measured walking a
+ * request path upward — a key on `//host/api/v4/` authenticates a tarball under
+ * `/api/v4/projects/…` — so for pnpm the endpoint key is redundant, and a client
+ * matching these keys **exactly** would still authenticate the packument with it.
+ * No such client was measured here, so the honest reason to keep the line is the
+ * smaller one: dropping it would make the file say less than it knows about the
+ * one address the operator gave.
+ *
+ * **The host key** is the one that covers a tarball. It is broad on purpose: the
+ * tarball URL is chosen by the server and appears for the first time inside a
+ * packument this file will never see, so the only statically derivable key
+ * guaranteed to cover it is the whole host. Measured with a local registry
+ * standing in for GitLab's shape — a packument served on the endpoint whose
+ * `dist.tarball` names `/api/v4/projects/302/packages/npm/…` on the same host —
+ * under pnpm 9.15.0, the version CI pins, and under pnpm 10:
+ *
+ *   endpoint key alone   ERR_PNPM_FETCH_404 … Not Found - 404
+ *                        "No authorization header was set for the request."
+ *   endpoint + host key  the tarball request carries the header; the install
+ *                        completes.
+ *
+ * ### Why not a narrower prefix
+ *
+ * Not because a narrower one would fail — measured, `//host/api/v4/` and
+ * `//host/api/v4/projects/` both authenticate that same tarball, because pnpm
+ * walks a request's path upward looking for a key. The mechanism is not the
+ * obstacle; the **derivation** is. Getting `/api/v4/` out of
+ * `/api/v4/packages/npm/` means knowing GitLab's URL layout, which is trading one
+ * unexamined premise about the server for a narrower one — and `--registry` names
+ * *a registry*, not *a GitLab*: the flag is documented as the endpoint the
+ * storefront installs from, and a Verdaccio or an Artifactory behind it has its
+ * own layout. `ENDORA_NPM_REGISTRY` is masked and may be the instance endpoint or
+ * a group one, so the file cannot even be written against one observed shape.
+ *
+ * ### What is given up, stated rather than glossed
+ *
+ * The credential is offered to **every** request pnpm makes to this host and
+ * port, not only to the endpoint's own subtree. That is broader than the single
+ * line this file used to write. It is accepted because the host is the one the
+ * operator named on the command line, the credential a client is handed is a
+ * deploy token scoped `read_package_registry` (R3.3) whose whole authority on
+ * that host is reading packages, and the alternative — the credential not
+ * reaching the address the registry itself directed the client to — is an install
+ * that cannot work.
+ *
+ * And what it does **not** cover, so nobody reads it as more than it is: a
+ * registry that serves tarballs from a **different host** (a CDN, a storage
+ * bucket) is not reached by this key or by any other one derivable here, because
+ * that host appears nowhere in the input. Such a registry needs a line naming it,
+ * and the symptom would be this same 404 on the tarball alone.
+ *
+ * A registry configured at the root of its host makes the two keys identical, and
+ * then there is one line rather than two: a duplicate would not be wrong, it
+ * would read as though it said something.
+ */
+export function authKeys(registry) {
+    const endpoint = normalizeRegistry(registry);
+    const endpointKey = endpoint.replace(/^https?:/, '');
+    const hostKey = `//${new URL(endpoint).host}/`;
+    return endpointKey === hostKey ? [endpointKey] : [endpointKey, hostKey];
+}
+/**
+ * The file's text: one registry line per scope, and the auth lines `authKeys`
+ * derives.
+ *
+ * There is one set of auth lines however many scopes there are, because a
+ * credential is a property of the endpoint rather than of a scope — the half of
+ * this file's original reasoning that survived the measurement above.
+ */
+export function npmrcContent(registry, scopes) {
+    if (scopes.length === 0) {
+        throw new StorefrontInputError(`\`--registry ${registry}\` was given, and the reference storefront declares no scoped ` +
+            `\`workspace:\` dependency for it to answer for. An \`.npmrc\` naming no scope ` +
+            `configures nothing: every fetch would go to the default registry and the file would ` +
+            `read as though it did something.`);
+    }
+    const endpoint = normalizeRegistry(registry);
+    const lines = [
+        '# Written by `endora new storefront --registry`. It holds no secret: the token below is',
+        `# an environment reference that pnpm expands at install time, so set ${TOKEN_VARIABLE} in`,
+        '# your environment (a CI variable, a keyring) and commit this file as it is.',
+    ];
+    for (const scope of scopes)
+        lines.push(`${scope}:registry=${endpoint}`);
+    lines.push('# The endpoint serves the metadata; the tarball it names in that metadata can be on any', '# path of this host (GitLab serves it from the owning project), so the credential is', '# declared for the host as well. Without the second line that one fetch goes out', '# unauthenticated and the registry answers 404.');
+    for (const key of authKeys(endpoint))
+        lines.push(`${key}:_authToken=\${${TOKEN_VARIABLE}}`);
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=npmrc.js.map

package/dist/new-storefront/npmrc.js.map

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

package/dist/new-storefront/reference.d.ts

@@ -0,0 +1,189 @@
+import { type EnvironmentConsumer, type EnvironmentInput } from '@endora-commerce/contracts';
+/** Raised when the reference storefront cannot be read. Exit 2. */
+export declare class StorefrontHostError extends Error {
+}
+/** Raised when the author asked for something this command refuses. Exit 1. */
+export declare class StorefrontInputError extends Error {
+}
+/** The dependency fields a manifest can declare a `workspace:` range in. */
+export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
+/** The reference storefront this run copies. */
+export interface StorefrontReference {
+    /** The directory holding `pnpm-workspace.yaml`. */
+    readonly repoRoot: string;
+    /** The reference storefront's directory, absolute. */
+    readonly dir: string;
+    /** Its files, storefront-relative, as git reports them. */
+    readonly files: readonly string[];
+    /** Its parsed manifest. */
+    readonly manifest: Record<string, unknown>;
+}
+/** One `workspace:` range the copy has to rewrite. */
+export interface WorkspaceRange {
+    readonly field: DependencyField;
+    readonly name: string;
+    /** The range as written, e.g. `workspace:^`. */
+    readonly declared: string;
+}
+/** The shapes a declaration can name a path in. */
+export type ReferenceKind = 'module-specifier' | 'json-extends' | 'css-source';
+/** One declaration naming something above the storefront directory. */
+export interface OutwardReference {
+    /** The file that writes it, storefront-relative. */
+    readonly file: string;
+    readonly kind: ReferenceKind;
+    /** The specifier exactly as written. */
+    readonly specifier: string;
+    /** Where it resolves, absolute, before any glob segment. */
+    readonly target: string;
+}
+/** The nearest ancestor of `start` holding a `pnpm-workspace.yaml`, or `null`. */
+export declare function findRepoRoot(start: string): string | null;
+/**
+ * The reference storefront's files, from git.
+ *
+ * Git is the independent author here: the alternative is a walk plus an
+ * exclusion list, and an exclusion list is a second answer to "what is this
+ * application" that goes stale against `.gitignore` in silence. A checkout with
+ * no git, or a storefront directory git does not track, is exit 2 — never a
+ * partial copy.
+ */
+export declare function trackedFiles(repoRoot: string, storefrontDir: string): readonly string[];
+/**
+ * Locate the reference storefront.
+ *
+ * It is found by the **one workspace member that is a Next application**, not by
+ * a directory called `storefront`: the member's manifest declares `next` and a
+ * `build` script that runs it, and `pnpm-workspace.yaml` says which directories
+ * are members. A repository that renames the directory is followed; one that
+ * grows a second Next application is exit 2 rather than a run over whichever
+ * sorted first.
+ */
+export declare function resolveReference(cwd: string): StorefrontReference;
+/** Workspace member directories, from the `packages:` globs as written. */
+export declare function memberDirectories(repoRoot: string): readonly string[];
+/** Every `workspace:` range the reference storefront declares, in field order. */
+export declare function workspaceRanges(manifest: Record<string, unknown>): readonly WorkspaceRange[];
+/**
+ * Every relative declaration in the reference storefront that resolves outside
+ * it, in the three shapes an application writes one.
+ *
+ * The specifier's own leading `.` is what makes it a candidate: a bare specifier
+ * names a package and is resolved by the installer, not by this copy. A glob is
+ * resolved up to its first wildcard segment, because that prefix is the part
+ * that has to exist.
+ */
+export declare function outwardReferences(reference: StorefrontReference): readonly OutwardReference[];
+/** The path prefix of a glob: everything up to the first wildcard segment. */
+export declare function globPrefix(specifier: string): string;
+/**
+ * Every package a module's **static import and re-export statements** name,
+ * reduced to the package: `vitest/config` is `vitest`, `@scope/pkg/sub` is
+ * `@scope/pkg`. Relative specifiers and Node's own modules are not packages an
+ * installer resolves, so they are not here.
+ *
+ * Anchored at the start of a line, deliberately narrower than
+ * {@link outwardReferences}' pattern: that one looks for a path anywhere a
+ * declaration could write one, and over a configuration file it also matches
+ * the word "import" inside a rule's message string. Here a false match is a
+ * refusal of a correct scaffold, and the statements a configuration file
+ * loads its packages with are the static ones this reads.
+ */
+export declare function importedPackages(text: string): readonly string[];
+/** Every package name a manifest declares, in any dependency field. */
+export declare function declaredPackages(manifest: Record<string, unknown>): ReadonlySet<string>;
+/** The file a storefront declares its environment in, and the copy carries verbatim. */
+export declare const ENV_EXAMPLE_FILE = ".env.example";
+/** The binding a storefront's declaration is exported under. */
+export declare const STOREFRONT_DECLARATION_EXPORT = "STOREFRONT_ENVIRONMENT_INPUTS";
+/**
+ * Every declaration the file makes, in file order — the copy's own worked
+ * example of its environment.
+ *
+ * One parser, because there are two questions asked of this file and they must
+ * not come to disagree about what it says: *which of these names a backend*
+ * (below) and *what value does this file give for a name* — the second being how
+ * the acceptance criterion configures the instance it boots without carrying a
+ * list of variables of its own. A key repeated in the file keeps its last
+ * assignment, which is what every reader of a `.env` does.
+ *
+ * A blank value is **not** a declaration. `NEXT_PUBLIC_SITE_URL=` and no line at
+ * all are the same state for whoever has to supply it, and reading the first as
+ * an answer would let a consumer pass an empty string to a command whose whole
+ * subject is that nothing is invented — `inputs/env-file.ts` makes the same call
+ * for the same reason, one directory over.
+ */
+export declare function envExampleDeclarations(envExampleText: string): ReadonlyMap<string, string>;
+/** The same answer, read off a storefront directory. */
+export declare function envExampleDeclarationsOf(storefrontDir: string): ReadonlyMap<string, string>;
+/**
+ * The variables a storefront sets to name a member of its instance.
+ *
+ * **Derived from the storefront's own declaration, never written down here.**
+ * A sentence carrying the two backend names would be a copy of a fact the
+ * storefront already states, going stale the first time one is renamed (D-100),
+ * and the guidance this replaces is what that costs: it named
+ * `PUBLIC_API_BASE_URL`, which no file in the copy has ever read, so an operator
+ * who followed it got a storefront quietly talking to the fallback its fetchers
+ * compile in.
+ *
+ * **The predicate is `addressOf`, and it used to be the shape of the value.**
+ * This function read `.env.example` and answered *a declaration whose value is
+ * an absolute `http(s)` URL*, on the reasoning that a backend address is one and
+ * none of the file's other keys was. The second half stopped being true the
+ * moment the file gained the storefront's own public address: `.env.example`
+ * would then have swept `NEXT_PUBLIC_SITE_URL` in with the backend's, and
+ * `nextSteps` would have told a client — in a file they own outright and nobody
+ * revisits — that it "names the backend this storefront talks to". A confident
+ * wrong sentence is worse than the silence it replaces, and the criterion would
+ * have pointed the shop's canonical origin at its API host at the same time.
+ *
+ * So the question is asked of the declaration, which says what each value **is**
+ * rather than what it looks like. The scoping stays `.env.example`'s job for
+ * *values* (`envExampleDeclarations`, above); this is about meaning.
+ *
+ * Nothing is invented when the declaration names no address: the answer is empty
+ * and each caller says so in its own words.
+ */
+export declare function addressVariables(declared: readonly EnvironmentInput[], member: EnvironmentConsumer): readonly string[];
+/**
+ * The same answer, read off a storefront directory.
+ *
+ * It loads that directory's own `environment-inputs.mjs` — the copy's, when the
+ * caller is holding a copy — through the one loader every other reader uses, so
+ * a declaration that will not parse is a refusal here as it is everywhere else.
+ * A storefront with no declaration at all is `DeclarationLoadError` and not an
+ * empty answer: that was `.env.example`'s rule, and it was right for a file that
+ * is a worked example. This one is the tree's statement of what it reads, and
+ * "absent" is not "reads nothing" (`loadTreeDeclaration`'s own header).
+ */
+export declare function backendAddressVariablesOf(storefrontDir: string): Promise<readonly string[]>;
+/** The variables naming the storefront's own public address, off a directory. */
+export declare function storefrontAddressVariablesOf(storefrontDir: string): Promise<readonly string[]>;
+/**
+ * Every variable this storefront's own process reads, off a directory.
+ *
+ * The two functions above answer *which of these names a member* — a subset
+ * chosen by `addressOf`. This one is the whole population, scoped to the one
+ * member that runs here, and it exists because a caller that **spawns** a
+ * storefront's toolchain has to know which names in its own environment belong
+ * to the instance rather than to itself.
+ *
+ * That is not a curiosity. Next loads a `.env` and does **not** override a
+ * variable the process already carries, so any of these names present in a
+ * parent's environment silently displaces the value written into the copy's own
+ * `.env` — and a harness that passed its environment on wholesale would be
+ * measuring its own configuration while reporting on the command's. `NODE_ENV`
+ * is the case that made this real: this storefront's declaration says in as many
+ * words that its toolchain sets it and that *"setting it by hand is how a
+ * production build ends up serving development output"*, and a CI job that set
+ * it for the **backend** it booted put it on every process in the job, including
+ * a `next build` in a scaffolded instance outside the checkout.
+ *
+ * Scoped with `scopeToMembers` rather than by name, for `storefrontDeclaredInputs`'
+ * reason: a declaration may carry an input another member reads, and the question
+ * here is what *this* process reads.
+ */
+export declare function declaredVariablesOf(storefrontDir: string): Promise<readonly string[]>;
+//# sourceMappingURL=reference.d.ts.map

package/dist/new-storefront/reference.d.ts.map

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