@o3co/auth-provider-scaffold 0.0.0 → 0.18.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 1o1 Co. Ltd.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,6 +1,5 @@
 # @o3co/auth-provider-scaffold
 
-This version is a placeholder, published only to bind the package to its trusted
-publisher. It has no contents. Use 0.18.0-rc.1 or later.
+Part of auth-provider 0.18.0-rc.1, built from `modules/scaffold` of https://github.com/o3co/auth.provider. Its modules, settings and documentation are there.
 
-Source: https://github.com/o3co/auth.provider (`modules/scaffold`)
+Copyright 2026 1o1 Co. Ltd. Licensed under the Apache License, Version 2.0.

package/combinations/README.md

@@ -0,0 +1,42 @@
+# combinations
+
+## Responsibilities
+- Completes a list of modules with what comes with them by default: each feature's wirings, and the bridges whose modules are all composed.
+- Composes a selection, and the full template, from what the packages need to run and the axes their adapters declare.
+- Reads all of it from the package.json of each package the workspace definition lists or, built into a bundle, from the index at the bundle's root (those manifests as written); adding a wiring, a bridge or an adapter needs no change here.
+
+## Not here
+- Whether a composition boots: the kernel's refusals.
+- What each kind may depend on, and the checks on it: `guard`.
+- Generating an app: `create-app`.
+- Running scenes: the conformance areas.
+- Checking that each feature declaring `storeWiring` has a wiring: `guard`.
+
+## Offers
+- `completed`: the modules given, each owner whose declared default replaces it swapped for that default and each adapter's owner counted for bridges, then the wirings and bridges they come with, including those of what is brought in, each once, in the order first named.
+- `composed` (features in named groups, an adapter or the owner by axis owner, modules added): the selection, what it needs to run (a foundation or feature among its dependencies, in turn), each composed axis's chosen adapter or default, then `completed`.
+- `composed` refuses, naming each: a name the workspace lacks, a group value that is not a feature, an addition that is not a feature or adapter with a module, an axis key that owns no axis, an axis value that is neither its adapter nor its owner, and an owner chosen for its own axis that has no module.
+- `needed` (modules): the modules given, what they need to run, then `completed`, as `composed` reaches them but with no axis default other than one declared to replace its owner; owners a reached adapter replaces are left out.
+- `full` (modules added): every foundation and feature with a module that does not opt in, composed alike. `optIns`: the features that opt in.
+- `kinds`: the kinds a package's manifest may name, the one place their words are written.
+
+## Invariants
+- A wiring names the feature it `wires`; it comes with the feature, whether given or brought in.
+- A bridge names the modules it `joins`, a non-empty list of names; it comes once every one of them is composed, whether given or brought in. An axis owner reached counts, with a module or not.
+- A `joins` that is not a non-empty list of names, or a `wires` that is not a name, is refused, naming each such package.
+- Wirings of one feature, and bridges, come in code point order of name.
+- An axis is its owner's: an adapter `replaces` the owner (composed instead of its module) or `adapts` it (beside it). Its default is the one adapter declaring `default`, or its only one.
+- An axis's default comes only where its owner is composed (reached among what runs, with a module or not, as the kernel), and not where another adapter of that axis is already composed. A default declared to replace its owner comes wherever that owner would, whether the owner has a module or not, so the owner's module is never composed beside it.
+- A feature that opts in comes in `full` only where something composed needs it to run.
+- Every name it gives is a module of the workspace, as it reads them there.
+
+## Data
+- The workspace's declarations, read once per process; nothing is written.
+
+## Depends on
+- `pnpm` (asks it for the packages the workspace definition lists); nothing in the workspace.
+
+## Vocabulary
+- axis: an owner's adapters to outside systems; default: the adapter composed unless another is chosen.
+- wiring: the module that ties a feature's store interfaces to an implementation.
+- bridge: a module that comes once every module it joins is composed: one module it adds to (`metrics` to `http`), or several it ties together (`session-tokens`).

package/combinations/src/composed.d.ts

@@ -0,0 +1,18 @@
+import { type Declared } from "./declared.js";
+/** What to compose: features in named groups, an adapter (or the owner itself) by axis owner, and anything added. */
+export interface Selection {
+    readonly features: Readonly<Record<string, readonly string[]>>;
+    readonly axes?: Readonly<Record<string, string>>;
+    readonly add?: readonly string[];
+}
+/** A selection's modules, first reached first: what it names and needs, each composed axis's chosen
+ * adapter or default (none where another adapter of it is there), wirings and bridges; replaced owners left out. */
+export declare function composedWith(declared: Declared, selection: Selection): string[];
+/** The modules given and what they need to run, in turn, then wirings and bridges; owners a reached adapter replaces left out; of axis defaults, only one declared to replace its owner. */
+export declare const neededWith: (declared: Declared, modules: readonly string[]) => string[];
+/** The modules given, owners a declared default replaces swapped for it (still counted for bridges), then wirings and bridges. */
+export declare function completedOf(declared: Declared, modules: readonly string[]): string[];
+/** The full template: every foundation and feature with a module that does not opt in, and what is added. */
+export declare function fullWith(declared: Declared, add?: readonly string[]): string[];
+/** The features that opt in: the full template leaves them out until added. */
+export declare const optInsOf: (declared: Declared) => string[];

package/combinations/src/composed.js

@@ -0,0 +1,132 @@
+import { completedWith } from "./declared.js";
+import { kinds } from "./kinds.js";
+/** The axis owner a package adapts to or replaces. */
+const axisOf = (p) => p?.replaces ?? p?.adapts;
+/** Each axis's adapters, by owner; the default is the one declaring it, or the only one. */
+function axesIn(declared) {
+    const adapters = new Map();
+    for (const p of declared.packages.values()) {
+        const owner = axisOf(p);
+        if (owner !== undefined)
+            adapters.set(owner, [...(adapters.get(owner) ?? []), p]);
+    }
+    const defaultOf = (owner) => {
+        const of = adapters.get(owner) ?? [];
+        return (of.length === 1 ? of[0] : of.find((p) => p.default))?.name;
+    };
+    /** The adapter declared the default that replaces an owner: it composes in the owner's place, a module or not. */
+    const replacingOf = (owner) => (adapters.get(owner) ?? []).find((p) => p.default && p.replaces === owner)?.name;
+    return { adapters, defaultOf, replacingOf };
+}
+/** Why each name cannot be selected, or none. */
+function refusals(declared, selection) {
+    const { adapters } = axesIn(declared);
+    const known = (name) => declared.packages.get(name);
+    const absent = (name) => (known(name) ? [] : [`${name}: not in the workspace`]);
+    const grouped = Object.values(selection.features).flat();
+    const added = selection.add ?? [];
+    const axes = Object.entries(selection.axes ?? {});
+    return [
+        ...[...grouped, ...added, ...axes.flat()]
+            .filter((n, i, all) => all.indexOf(n) === i)
+            .flatMap(absent),
+        ...grouped
+            .filter((n) => known(n) && known(n)?.kind !== kinds.feature)
+            .map((n) => `${n}: not a feature`),
+        ...added
+            .filter((n) => {
+            const p = known(n);
+            return p && !(p.module && (p.kind === kinds.feature || p.kind === kinds.adapter));
+        })
+            .map((n) => `${n}: not a feature or an adapter with a module`),
+        ...axes
+            .filter(([owner]) => known(owner) && !adapters.has(owner))
+            .map(([owner]) => `${owner}: not an axis's owner`),
+        ...axes
+            .filter(([owner, chosen]) => adapters.has(owner) && known(chosen) && chosen !== owner)
+            .filter(([owner, chosen]) => axisOf(known(chosen)) !== owner)
+            .map(([owner, chosen]) => `${chosen}: not an adapter of ${owner}`),
+        ...axes
+            .filter(([owner, chosen]) => adapters.has(owner) && chosen === owner && !known(owner)?.module)
+            .map(([owner]) => `axes.${owner} = ${owner}: the owner has no module, so it cannot serve its own axis`),
+    ];
+}
+/** A selection's modules, first reached first: what it names and needs, each composed axis's chosen
+ * adapter or default (none where another adapter of it is there), wirings and bridges; replaced owners left out. */
+export function composedWith(declared, selection) {
+    const refused = refusals(declared, selection);
+    if (refused.length > 0)
+        throw new Error(refused.join("; "));
+    return composing(declared, [...Object.values(selection.features).flat(), ...(selection.add ?? [])], selection.axes ?? {});
+}
+/** The modules given and what they need to run, in turn, then wirings and bridges; owners a reached adapter replaces left out; of axis defaults, only one declared to replace its owner. */
+export const neededWith = (declared, modules) => composing(declared, modules, {}, { defaults: false });
+function composing(declared, start, chosen, { defaults } = { defaults: true }) {
+    const { adapters, defaultOf, replacingOf } = axesIn(declared);
+    const runs = (name) => {
+        const p = declared.packages.get(name);
+        return p?.kind === kinds.foundation || p?.kind === kinds.feature;
+    };
+    /** Every package reached, a module or not: an axis owner reached is composed. */
+    const reached = [];
+    const reach = (name) => {
+        if (!reached.includes(name))
+            reached.push(name);
+    };
+    for (const name of start)
+        reach(name);
+    for (let size = -1; size !== reached.length;) {
+        size = reached.length;
+        for (const name of reached)
+            for (const need of declared.packages.get(name)?.needs ?? []) {
+                // An axis owner is reached whatever its kind, as the kernel: its axis then applies.
+                if (runs(need) || adapters.has(need))
+                    reach(need);
+            }
+        for (const owner of reached.filter((name) => adapters.has(name))) {
+            const pick = chosen[owner];
+            if (pick !== undefined) {
+                if (pick !== owner)
+                    reach(pick);
+            }
+            else if (!(adapters.get(owner) ?? []).some((a) => reached.includes(a.name))) {
+                const fallback = defaults ? defaultOf(owner) : replacingOf(owner);
+                if (fallback !== undefined)
+                    reach(fallback);
+            }
+        }
+        // An axis owner reached counts for bridges, as a module does, whether it has one or not.
+        const joined = reached.filter((name) => declared.packages.get(name)?.module || adapters.has(name));
+        for (const name of completedWith(declared, joined))
+            reach(name);
+    }
+    const replaced = new Set(reached.flatMap((name) => declared.packages.get(name)?.replaces ?? []));
+    return reached.filter((name) => declared.packages.get(name)?.module && !replaced.has(name));
+}
+/** The modules given, owners a declared default replaces swapped for it (still counted for bridges), then wirings and bridges. */
+export function completedOf(declared, modules) {
+    const { replacingOf } = axesIn(declared);
+    // An owner named brings its default; an adapter named brings the owner it replaces, for bridges.
+    const swapped = modules.flatMap((name) => {
+        const by = replacingOf(name);
+        const owner = declared.packages.get(name)?.replaces;
+        const missing = (other) => other === undefined || modules.includes(other) ? [] : [other];
+        return [name, ...missing(by), ...missing(owner)];
+    });
+    const replaced = new Set(swapped.flatMap((name) => declared.packages.get(name)?.replaces ?? []));
+    return completedWith(declared, swapped).filter((name) => !replaced.has(name));
+}
+/** The full template: every foundation and feature with a module that does not opt in, and what is added. */
+export function fullWith(declared, add = []) {
+    const refused = refusals(declared, { features: {}, add });
+    if (refused.length > 0)
+        throw new Error(refused.join("; "));
+    const base = [...declared.packages.values()]
+        .filter((p) => p.module && !p.optIn && (p.kind === kinds.foundation || p.kind === kinds.feature))
+        .map((p) => p.name);
+    return composing(declared, [...base, ...add], {});
+}
+/** The features that opt in: the full template leaves them out until added. */
+export const optInsOf = (declared) => [...declared.packages.values()]
+    .filter((p) => p.optIn && p.kind === kinds.feature)
+    .map((p) => p.name);

package/combinations/src/contract.d.ts

@@ -0,0 +1,13 @@
+import { type Selection } from "./composed.js";
+export type { Selection } from "./composed.js";
+export { type Kind, kinds } from "./kinds.js";
+/** The modules given (owners a declared default replaces swapped for it), then their wirings and bridges, each once, first named first. */
+export declare function completed(modules: readonly string[]): string[];
+/** What a selection composes (see `composedWith`); refuses, naming each, what cannot be selected. */
+export declare const composed: (selection: Selection) => string[];
+/** The full template: every foundation and feature that does not opt in, with each default, and what is added. */
+export declare const full: (add?: readonly string[]) => string[];
+/** The features that opt in, which the full template leaves out until added. */
+export declare const optIns: () => string[];
+/** The modules given, what they need to run, then `completed`, as `composed` reaches them but with no axis default. */
+export declare const needed: (modules: readonly string[]) => string[];

package/combinations/src/contract.js

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { completedOf, composedWith, fullWith, neededWith, optInsOf, } from "./composed.js";
+import { declaredIn, declaredInIndex } from "./declared.js";
+export { kinds } from "./kinds.js";
+let workspace;
+/** The modules given (owners a declared default replaces swapped for it), then their wirings and bridges, each once, first named first. */
+export function completed(modules) {
+    return completedOf(declared(), modules);
+}
+/** Read once: built into a bundle, the index at its root; in the workspace, the workspace itself. */
+const declared = () => {
+    const index = join(import.meta.dirname, "..", "..", "index.json");
+    workspace ??= existsSync(index)
+        ? declaredInIndex(index)
+        : declaredIn(join(import.meta.dirname, "..", "..", "..", ".."));
+    return workspace;
+};
+/** What a selection composes (see `composedWith`); refuses, naming each, what cannot be selected. */
+export const composed = (selection) => composedWith(declared(), selection);
+/** The full template: every foundation and feature that does not opt in, with each default, and what is added. */
+export const full = (add) => fullWith(declared(), add);
+/** The features that opt in, which the full template leaves out until added. */
+export const optIns = () => optInsOf(declared());
+/** The modules given, what they need to run, then `completed`, as `composed` reaches them but with no axis default. */
+export const needed = (modules) => neededWith(declared(), modules);

package/combinations/src/declared.d.ts

@@ -0,0 +1,38 @@
+/** What one package declares that composing reads. */
+export interface Package {
+    readonly name: string;
+    readonly kind?: string;
+    /** Whether it can be composed: it exports `./module`. */
+    readonly module: boolean;
+    /** The packages it needs to run (`dependencies`, not `devDependencies`). */
+    readonly needs: readonly string[];
+    readonly optIn: boolean;
+    /** The axis owner it replaces or adapts to, and whether it is that axis's default. */
+    readonly replaces?: string;
+    readonly adapts?: string;
+    readonly default: boolean;
+}
+export interface Declared {
+    /** Each feature's wirings, by the feature's name. */
+    readonly wirings: ReadonlyMap<string, readonly string[]>;
+    readonly bridges: readonly {
+        readonly joins: readonly string[];
+        readonly bridge: string;
+    }[];
+    /** Every package, by name, in code point order of name. */
+    readonly packages: ReadonlyMap<string, Package>;
+}
+/**
+ * What the packages of the workspace rooted at `root` declare in their package.json, as the
+ * workspace definition lists them: a wiring names the feature it `wires`, a bridge the modules it
+ * `joins`, a non-empty list of names; any other `wires` or `joins` is refused. Each list is in
+ * code point order of name.
+ */
+export declare function declaredIn(root: string): Declared;
+/** The same, from the index a bundle carries: each member's manifest as the workspace wrote it. */
+export declare function declaredInIndex(file: string): Declared;
+/**
+ * The modules given, then the wirings and bridges declared for them, each once and in the order
+ * first named. What is brought in is completed in turn, until nothing more comes.
+ */
+export declare function completedWith(declared: Declared, modules: readonly string[]): string[];

package/combinations/src/declared.js

@@ -0,0 +1,75 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const packageOf = (m) => ({
+    name: m.name,
+    ...(isName(m.kind) ? { kind: m.kind } : {}),
+    module: typeof m.exports === "object" && m.exports !== null && "./module" in m.exports,
+    needs: typeof m.dependencies === "object" && m.dependencies !== null
+        ? Object.keys(m.dependencies)
+        : [],
+    optIn: m.optIn === true,
+    ...(isName(m.replaces) ? { replaces: m.replaces } : {}),
+    ...(isName(m.adapts) ? { adapts: m.adapts } : {}),
+    default: m.default === true,
+});
+const isName = (value) => typeof value === "string" && value !== "";
+const isNames = (value) => Array.isArray(value) && value.length > 0 && value.every(isName);
+/**
+ * What the packages of the workspace rooted at `root` declare in their package.json, as the
+ * workspace definition lists them: a wiring names the feature it `wires`, a bridge the modules it
+ * `joins`, a non-empty list of names; any other `wires` or `joins` is refused. Each list is in
+ * code point order of name.
+ */
+export function declaredIn(root) {
+    const listed = JSON.parse(execFileSync("pnpm", ["ls", "-r", "--json", "--depth", "-1"], { cwd: root, encoding: "utf8" }));
+    return declaredOf(listed.map(({ path }) => JSON.parse(readFileSync(join(path, "package.json"), "utf8"))));
+}
+/** The same, from the index a bundle carries: each member's manifest as the workspace wrote it. */
+export function declaredInIndex(file) {
+    const index = JSON.parse(readFileSync(file, "utf8"));
+    return declaredOf(index.packages.map(({ manifest }) => manifest));
+}
+function declaredOf(manifests) {
+    const packages = [...manifests].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    // Refused, never left missing with no word why: a bridge joining nothing would come with all.
+    const misdeclared = (key, ok, shape) => {
+        const names = packages.filter((m) => m[key] !== undefined && !ok(m[key])).map((m) => m.name);
+        return names.length > 0 ? [`${names.join(", ")}: ${key} is not ${shape}`] : [];
+    };
+    const refusals = [
+        ...misdeclared("joins", isNames, "a non-empty list of module names"),
+        ...misdeclared("wires", isName, "a module name"),
+    ];
+    if (refusals.length > 0)
+        throw new Error(refusals.join("; "));
+    const wirings = new Map();
+    for (const { name, wires } of packages) {
+        if (isName(wires))
+            wirings.set(wires, [...(wirings.get(wires) ?? []), name]);
+    }
+    const bridges = packages.flatMap(({ name, joins }) => isNames(joins) ? [{ joins, bridge: name }] : []);
+    return { wirings, bridges, packages: new Map(packages.map((m) => [m.name, packageOf(m)])) };
+}
+/**
+ * The modules given, then the wirings and bridges declared for them, each once and in the order
+ * first named. What is brought in is completed in turn, until nothing more comes.
+ */
+export function completedWith(declared, modules) {
+    const all = [...modules];
+    const add = (name) => {
+        if (!all.includes(name))
+            all.push(name);
+    };
+    for (let size = -1; size !== all.length;) {
+        size = all.length;
+        for (const name of all)
+            for (const wiring of declared.wirings.get(name) ?? [])
+                add(wiring);
+        for (const { joins, bridge } of declared.bridges) {
+            if (joins.every((m) => all.includes(m)))
+                add(bridge);
+        }
+    }
+    return all;
+}

package/combinations/src/kinds.d.ts

@@ -0,0 +1,12 @@
+/** The kinds a package's manifest names, each the one word the product and its checks read. */
+export declare const kinds: {
+    readonly common: "common";
+    readonly foundation: "foundation";
+    readonly capability: "capability";
+    readonly feature: "feature";
+    readonly adapter: "adapter";
+    readonly assembly: "assembly";
+    readonly wiring: "wiring";
+    readonly verification: "verification";
+};
+export type Kind = (typeof kinds)[keyof typeof kinds];

package/combinations/src/kinds.js

@@ -0,0 +1,11 @@
+/** The kinds a package's manifest names, each the one word the product and its checks read. */
+export const kinds = {
+    common: "common",
+    foundation: "foundation",
+    capability: "capability",
+    feature: "feature",
+    adapter: "adapter",
+    assembly: "assembly",
+    wiring: "wiring",
+    verification: "verification",
+};

package/create-app/README.md

@@ -0,0 +1,54 @@
+# create-app
+
+## Responsibilities
+- Generates a new project: a minimal app that assembles the modules asked for through their `./module`, with the wirings and bridges `combinations` adds by default.
+- Generates the full template: what `combinations` composes in full, with the features added, its configuration from the modules' fragments, an image and the operator's guide.
+- Generates a pattern's deployment the same way, from what `combinations` composes of the pattern's selection and the operator's choice; its internal module `patterns` holds the patterns.
+- Maps each fragment's keys to the environment and the local layer: the boundary that keeps module words out of the environment's.
+- Adds one log sink to a listed app: `log-stdout`, unless the plan names another.
+- Writes a start script, and what git leaves out (`node_modules/`, local configuration files, and for full and a pattern the env files and key files).
+- The app reads the configuration files `APP_CONFIG` lists, comma-separated, layered in order; the generated configuration file when unset.
+
+## Not here
+- What each module's configuration means, and its fragment (`config.example` beside its package.json): each module's.
+- What the full template and a selection compose: `combinations`.
+
+## Offers
+- `generate`, and the `create-app` command around it (also `run`, the command on given arguments, answering its exit status, for a package that runs it): packages listed make their app; none makes a pattern's, `--pattern` naming it (default `full`), `--add` naming features to add, `--axis <owner>=<module>` an axis's choice and `--<group>` a group's features, comma-separated (not for full).
+- `patterns()`: each pattern's name, use, conformance areas and what conformance adds for its run.
+- The workspace's configuration reference: each section's keys from its schema (type, bounds, default, whether required, description) and its fragment (example, variable), written by `pnpm --filter @mod/create-app run configuration`.
+- The configuration reference's test fails when the committed file differs, or when a key has no description outside the sections listed as described later.
+- The audit event reference beside it: each module's events as its `./audit-events` declares them through `audit`, written by the same command and held to the committed file the same way.
+- A kind two modules declare must be declared alike in the audit event reference.
+- `trialSettings(target, { redisUrl, port?, deployment?, leave?, allow?, plainLoopback? })`: for a generated app, by the modules its manifest depends on, an environment and a local layer that boot it for a test or a conformance run.
+  - Its hosts are under `.invalid` and its keys made fresh, never a deployment's values.
+  - The sections in `leave` get neither a variable nor a block.
+  - Hosts in `allow` and `plainLoopback` join the trial's one outbound block.
+  - `mfa` is optional where composed.
+  - `webauthn`'s relying party is the trial's public origin.
+- For full and a pattern: the project's manifest and app, the configuration file, the local layer's and the environment's examples, a Dockerfile, a `.dockerignore` and a README; a pattern's README opens with its use and carries its card.
+
+## Invariants
+- A target that holds anything is refused, never overwritten; a missing or empty one is taken.
+- A module, sink, added feature or axis choice not named as an npm package is refused, before anything is written; so is a name the workspace lacks, one that is not a feature, a pattern or group not known, and axes or groups for full.
+- With a workspace, each dependency links to the workspace's package; a module the workspace does not hold is refused. Built into a bundle and given none, it reads the bundle's index: the app depends on each public bundle at the index's version, imports public entries, and takes the fragments the index holds; a module it does not hold is refused.
+- A listed app's configuration file holds `kernel`'s section only, and no secret values.
+- A pattern whose store is kept in memory says in its README that the deployment runs as one instance.
+- The full template's and a pattern's configuration file reads the collected fragments' scalar keys from env only, holding no values; each variable is the section and key path joined by `_`, upper-cased, `-` as `_`.
+- Two keys reading one variable refuse generation, naming both.
+- Neither example holds a live value line: the local layer's holds each fragment list with its placeholders and each value spanning sections (`audit.receivers`), the environment's each variable, all as comments; a copy sets nothing, and boot refuses each key still needed. A value spanning sections never goes to env.
+- Git leaves out every env file but `.env.example`, the local layer, `*.pem` and `*.key`; the image's build context leaves out those, `.env.example` and `.git`.
+- The image pins Node by version and digest and corepack by version, installs the locked production dependencies in a stage of their own, runs node under `tini` as a user other than root, and checks liveness (`/_healthcheck`, after a start period).
+- The app exits 78 on a refused boot, writing each refusal on standard error.
+- SIGTERM or SIGINT stops the app, draining; one that comes while it starts stops it once started.
+
+## Data
+- Writes the target only; reads the workspace's package list, and the fragments of the modules the full template composes.
+
+## Depends on
+- `kernel`, `combinations` (the modules it assembles become dependencies of the output); the HOCON library, to read the fragments.
+
+## Vocabulary
+- output: a project created from the template.
+- fragment: a module's example of its section, placeholders only; a secret's is `REPLACE-…` text its section refuses.
+- local layer: the operator's configuration file layered first, for lists and values the environment does not carry.