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

package/create-app/src/audit-events.d.ts

@@ -0,0 +1,22 @@
+/** One declared event, as `audit`'s `auditEvents` takes it. */
+export interface Declared {
+    readonly attributes: readonly string[];
+    readonly when: string;
+}
+/** Each package exporting `./audit-events`, with its declarations, by package name. */
+export declare function declarationsIn(root: string): Promise<{
+    readonly owner: string;
+    readonly events: Readonly<Record<string, Declared>>;
+}[]>;
+/** Each kind more than one module declares, unlike in some way: one kind holds one meaning. */
+export declare function unlikeKinds(modules: readonly {
+    readonly owner: string;
+    readonly events: Readonly<Record<string, Declared>>;
+}[]): string[];
+/** The reference, generated: one table per module, its kinds in code point order. */
+export declare function auditReferenceOf(modules: readonly {
+    readonly owner: string;
+    readonly events: Readonly<Record<string, Declared>>;
+}[]): string;
+/** Where the reference lies in the workspace. */
+export declare const auditReferenceFile: (root: string) => string;

package/create-app/src/audit-events.js

@@ -0,0 +1,76 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** The audit event reference: every module's declared events, as one document. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { workspacePackages } from "./project.js";
+/** Each package exporting `./audit-events`, with its declarations, by package name. */
+export async function declarationsIn(root) {
+    const found = [];
+    for (const [name, dir] of workspacePackages(root)) {
+        if (dir === root)
+            continue;
+        const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        const entry = manifest.exports?.["./audit-events"];
+        if (!entry)
+            continue;
+        const events = (await import(__rewriteRelativeImportExtension(join(dir, entry)))).default;
+        found.push({ owner: name, events });
+    }
+    return found.sort((a, b) => (a.owner < b.owner ? -1 : 1));
+}
+/** Each kind more than one module declares, unlike in some way: one kind holds one meaning. */
+export function unlikeKinds(modules) {
+    const first = new Map();
+    const unlike = new Set();
+    for (const { owner, events } of modules) {
+        for (const [kind, declared] of Object.entries(events)) {
+            const shape = JSON.stringify({
+                attributes: [...declared.attributes].sort(),
+                when: declared.when,
+            });
+            const held = first.get(kind);
+            if (!held)
+                first.set(kind, { owner, declared: shape });
+            else if (held.declared !== shape)
+                unlike.add(`${kind}: ${held.owner} and ${owner} declare it differently`);
+        }
+    }
+    return [...unlike];
+}
+const text = (value) => value.replaceAll("|", "\\|").replaceAll("\n", " ");
+/** The reference, generated: one table per module, its kinds in code point order. */
+export function auditReferenceOf(modules) {
+    const blocks = modules.map(({ owner, events }) => [
+        `## ${owner}`,
+        "",
+        "| Kind | Attributes | Recorded when |",
+        "|---|---|---|",
+        ...Object.keys(events)
+            .sort()
+            .map((kind) => {
+            const e = events[kind];
+            const attributes = e.attributes.map((a) => `\`${a}\``).join(", ");
+            return `| \`${kind}\` | ${attributes} | ${text(e.when)} |`;
+        }),
+    ].join("\n"));
+    return `${[
+        "# Audit events",
+        "",
+        "Generated by `create-app` from each module's `./audit-events` declarations: do not edit; run `pnpm --filter @mod/create-app run configuration`.",
+        "Every event carries its kind and the time `kernel`'s clock gives it, and a subject where the table's module names one.",
+        "`audit` bounds a `userAgent`, the request's own text, before any receiver gets it: a `?` for each character outside RFC 6749's NQSCHAR, at most 200 characters; the subject and other attributes stay as written.",
+        "",
+        ...blocks.flatMap((b) => [b, ""]),
+    ]
+        .join("\n")
+        .trimEnd()}\n`;
+}
+/** Where the reference lies in the workspace. */
+export const auditReferenceFile = (root) => join(root, "docs", "audit-events.md");

package/create-app/src/command.d.ts

@@ -0,0 +1,5 @@
+/** Runs the command on its arguments, writing to `io`: 0 once the project is written, 64 for a usage error. */
+export declare function run(args: readonly string[], io?: {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+}): Promise<number>;

package/create-app/src/command.js

@@ -0,0 +1,69 @@
+import { parseArgs } from "node:util";
+import { generate } from "./generate.js";
+import { groups } from "./patterns/pattern.js";
+/** Runs the command on its arguments, writing to `io`: 0 once the project is written, 64 for a usage error. */
+export async function run(args, io = {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+}) {
+    const usage = () => {
+        io.err("usage: create-app <target> [--workspace <root>] [--pattern <name>] [--add <feature>]...\n" +
+            "         [--axis <owner>=<module>]... [--<group> <feature>,...]...\n" +
+            `         groups: ${groups.join(", ")}; axes and groups need a pattern other than full\n` +
+            "       create-app <target> [--workspace <root>] [--sink <package>] <package>...\n");
+        return 64;
+    };
+    const groupOptions = Object.fromEntries(groups.map((group) => [group, { type: "string" }]));
+    const { values, positionals } = parseArgs({
+        args: [...args],
+        allowPositionals: true,
+        options: {
+            workspace: { type: "string" },
+            sink: { type: "string" },
+            pattern: { type: "string" },
+            add: { type: "string", multiple: true },
+            axis: { type: "string", multiple: true },
+            ...groupOptions,
+        },
+    });
+    const [target, ...modules] = positionals;
+    const pattern = values.pattern ?? "full";
+    const axes = (values.axis ?? []).map((given) => given.split("="));
+    const chosen = groups.flatMap((group) => {
+        const listed = values[group];
+        return typeof listed === "string" ? [[group, listed.split(",")]] : [];
+    });
+    // Packages listed make the app of those; none makes a pattern's, full when none is named.
+    const listed = modules.length > 0;
+    const patterned = values.add || values.pattern || axes.length > 0 || chosen.length > 0;
+    const malformedAxis = axes.some((pair) => pair.length !== 2 || pair.includes(""));
+    const choiceForFull = pattern === "full" && (axes.length > 0 || chosen.length > 0);
+    if (!target ||
+        (listed && patterned) ||
+        (!listed && values.sink) ||
+        malformedAxis ||
+        choiceForFull) {
+        return usage();
+    }
+    const workspace = values.workspace ? { workspace: values.workspace } : {};
+    const add = values.add ? { add: values.add } : {};
+    function planOf(target) {
+        if (listed)
+            return { target, modules, ...workspace, ...(values.sink ? { sink: values.sink } : {}) };
+        if (pattern === "full")
+            return { target, template: "full", ...workspace, ...add };
+        return {
+            target,
+            template: pattern,
+            ...workspace,
+            ...add,
+            ...(axes.length > 0 ? { axes: Object.fromEntries(axes) } : {}),
+            ...(chosen.length > 0 ? { features: Object.fromEntries(chosen) } : {}),
+        };
+    }
+    await generate(planOf(target ?? ""));
+    io.out(listed
+        ? `created ${target}\nnext: cd ${target} && pnpm install && pnpm start\n`
+        : `created ${target}\nnext: cd ${target} and follow its README.md\n`);
+    return 0;
+}

package/create-app/src/configuration.d.ts

@@ -0,0 +1,44 @@
+/** The part of a JSON Schema the reference reads. */
+export interface JsonSchema {
+    readonly type?: string | readonly string[];
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: JsonSchema;
+    readonly enum?: readonly unknown[];
+    readonly anyOf?: readonly JsonSchema[];
+    readonly oneOf?: readonly JsonSchema[];
+    readonly const?: unknown;
+    readonly default?: unknown;
+    readonly description?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+}
+/** One key of a section, as the reference shows it. */
+export interface Row {
+    readonly key: string;
+    readonly type: string;
+    readonly default?: unknown;
+    readonly required: boolean;
+    readonly env?: string;
+    readonly example?: unknown;
+    readonly description?: string;
+}
+/** Each key of a schema, objects with properties walked into; `at` reads the fragment's value and env. */
+export declare function rowsOf(schema: JsonSchema, path: readonly string[], at: (key: string) => {
+    readonly env?: string;
+    readonly example?: unknown;
+}): Row[];
+/** Every section of the workspace: its owner, and its rows. */
+export declare function sectionsIn(root: string): Promise<{
+    readonly section: string;
+    readonly owner: string;
+    readonly rows: Row[];
+}[]>;
+/** The reference, generated: one table per section. */
+export declare function referenceOf(sections: readonly {
+    readonly section: string;
+    readonly owner: string;
+    readonly rows: readonly Row[];
+}[]): string;
+/** Where the reference lies in the workspace. */
+export declare const referenceFile: (root: string) => string;

package/create-app/src/configuration.js

@@ -0,0 +1,161 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** The configuration reference: every module's section, from its schema and its fragment, as one document. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fragmentsIn, settingsOf } from "./fragments.js";
+import { kernel, workspacePackages } from "./project.js";
+const typeOf = (s) => {
+    if (s.const !== undefined)
+        return String(s.const);
+    if (s.enum)
+        return s.enum.map((v) => String(v)).join(" | ");
+    const either = s.anyOf ?? s.oneOf;
+    if (either)
+        return [...new Set(either.map(typeOf))].join(" | ");
+    if (s.type === "array")
+        return `list of ${s.items ? typeOf(s.items) : "any"}`;
+    if (s.type === "object")
+        return "map";
+    const name = Array.isArray(s.type) ? s.type.join(" | ") : (s.type ?? "any");
+    const range = s.minimum !== undefined || s.maximum !== undefined
+        ? ` (${s.minimum ?? ""}–${s.maximum ?? ""})`
+        : "";
+    return `${name}${range}`;
+};
+/** An object's keys, or a union of objects' keys merged: required only where every variant requires it. */
+function objectOf(s) {
+    if (s.properties)
+        return s;
+    const variants = (s.oneOf ?? s.anyOf ?? []).map(objectOf);
+    if (variants.length === 0 || variants.some((v) => v === undefined))
+        return undefined;
+    const properties = {};
+    for (const v of variants) {
+        for (const [name, p] of Object.entries(v.properties ?? {})) {
+            const held = properties[name];
+            const either = held ? [...(held.anyOf ?? [held]), p] : undefined;
+            properties[name] = either
+                ? {
+                    anyOf: either,
+                    ...(held?.default !== undefined ? { default: held.default } : {}),
+                    ...(held?.description ? { description: held.description } : {}),
+                }
+                : p;
+        }
+    }
+    const required = Object.keys(properties).filter((name) => variants.every((v) => (v.required ?? []).includes(name)));
+    return { type: "object", properties, required };
+}
+/** Each key of a schema, objects with properties walked into; `at` reads the fragment's value and env. */
+export function rowsOf(schema, path, at) {
+    const object = objectOf(schema);
+    return Object.entries(object?.properties ?? {}).flatMap(([name, s]) => {
+        const keyPath = [...path, name];
+        const inner = objectOf(s);
+        if (inner)
+            return rowsOf(inner, keyPath, at);
+        const key = keyPath.join(".");
+        return [
+            {
+                key,
+                type: typeOf(s),
+                ...(s.default === undefined ? {} : { default: s.default }),
+                required: (object?.required ?? []).includes(name) && s.default === undefined,
+                ...at(key),
+                ...(s.description ? { description: s.description } : {}),
+            },
+        ];
+    });
+}
+/** A fragment's own leaves, typed by their sample, for a section read without a schema. */
+function fragmentRows(fragment, at) {
+    const walk = (tree, path) => Object.entries(tree).flatMap(([name, value]) => {
+        const keyPath = [...path, name];
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            return walk(value, keyPath);
+        }
+        const key = keyPath.join(".");
+        const type = Array.isArray(value) ? "list" : typeof value;
+        return [{ key, type, required: false, ...at(key), example: value }];
+    });
+    return walk(fragment.tree, [fragment.section]);
+}
+/** Every section of the workspace: its owner, and its rows. */
+export async function sectionsIn(root) {
+    const found = [];
+    for (const [name, dir] of workspacePackages(root)) {
+        if (dir === root)
+            continue;
+        const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        const entry = manifest.exports?.["./module"];
+        const module = entry
+            ? (await import(__rewriteRelativeImportExtension(join(dir, entry)))).default
+            : undefined;
+        const [fragment] = await fragmentsIn([dir]);
+        const env = new Map(fragment ? settingsOf([fragment]).map((s) => [s.key, s.env]) : []);
+        const example = new Map(fragment ? fragmentRows(fragment, () => ({})).map((r) => [r.key, r.example]) : []);
+        const at = (key) => {
+            const variable = env.get(key);
+            return {
+                ...(variable === undefined ? {} : { env: variable }),
+                ...(example.has(key) ? { example: example.get(key) } : {}),
+            };
+        };
+        const schema = module?.section?.["~standard"].jsonSchema?.input({ target: "draft-2020-12" });
+        if (module && schema) {
+            found.push({
+                section: module.name,
+                owner: name,
+                rows: rowsOf(schema, [module.name], at),
+            });
+        }
+        else if (fragment && name === kernel) {
+            // The kernel reads its own section, by the schema its contract exports.
+            const own = (await import(__rewriteRelativeImportExtension(join(dir, manifest.exports["."])))).kernelSection;
+            const read = own?.["~standard"].jsonSchema?.input({ target: "draft-2020-12" });
+            const rows = read
+                ? rowsOf(read, [fragment.section], at)
+                : fragmentRows(fragment, at);
+            found.push({ section: fragment.section, owner: name, rows });
+        }
+    }
+    return found.sort((a, b) => (a.section < b.section ? -1 : 1));
+}
+const cell = (value) => value === undefined
+    ? ""
+    : `\`${(typeof value === "string" ? value : JSON.stringify(value)).replaceAll("|", "\\|")}\``;
+const text = (value) => (value ?? "").replaceAll("|", "\\|").replaceAll("\n", " ");
+/** The reference, generated: one table per section. */
+export function referenceOf(sections) {
+    const blocks = sections.map(({ section, owner, rows }) => {
+        const lines = rows.map((r) => `| \`${r.key}\` | ${text(r.type)} | ${cell(r.default)} | ${r.required ? "yes" : ""} | ${r.env ? `\`${r.env}\`` : ""} | ${cell(r.example)} | ${text(r.description)} |`);
+        return [
+            `## ${section}`,
+            "",
+            `From \`${owner}\`.`,
+            "",
+            "| Key | Type | Default | Required | Variable | Example | Description |",
+            "|---|---|---|---|---|---|---|",
+            ...lines,
+        ].join("\n");
+    });
+    return `${[
+        "# Configuration",
+        "",
+        "Generated by `create-app` from each module's section schema and its `config.example`: do not edit; run `pnpm --filter @mod/create-app run configuration`.",
+        "A variable is read by the configuration `create-app` generates, for a key the module's example holds; any other key is written in the local layer.",
+        "",
+        ...blocks.flatMap((b) => [b, ""]),
+    ]
+        .join("\n")
+        .trimEnd()}\n`;
+}
+/** Where the reference lies in the workspace. */
+export const referenceFile = (root) => join(root, "docs", "configuration.md");

package/create-app/src/contract.d.ts

@@ -0,0 +1,6 @@
+export { run } from "./command.js";
+export { type FullPlan, generate, type ModulesPlan, type Plan } from "./generate.js";
+export type { PatternPlan } from "./pattern.js";
+export type { Choice } from "./patterns/pattern.js";
+export { type PatternSummary, patterns } from "./patterns/patterns.js";
+export { trialSettings } from "./trial.js";

package/create-app/src/contract.js

@@ -0,0 +1,4 @@
+export { run } from "./command.js";
+export { generate } from "./generate.js";
+export { patterns } from "./patterns/patterns.js";
+export { trialSettings } from "./trial.js";

package/create-app/src/deployment.d.ts

@@ -0,0 +1,8 @@
+/** Writes the project assembling `modules` into an empty target, its guide from `readme`'s template and values. */
+export declare function writeDeployment(plan: {
+    readonly target: string;
+    readonly workspace?: string;
+}, modules: readonly string[], readme: {
+    readonly template: string;
+    readonly fill: Readonly<Record<string, string>>;
+}): Promise<void>;

package/create-app/src/deployment.js

@@ -0,0 +1,100 @@
+/** A deployment's project from a list of modules: configuration from their fragments, the image and a guide. */
+import { applicationConf, envExample, envName, localConfExample, settingsOf, writtenOf, } from "./fragments.js";
+import { packagesFor } from "./packages.js";
+import { filled, mainSource, manifestOf, vacant, withKernel, writeProject } from "./project.js";
+/** The files the generated project names in its guide, each written where the guide says. */
+const paths = {
+    application: "config/application.conf",
+    local: "config/local.conf",
+    localExample: "config/local.conf.example",
+    main: "src/main.ts",
+};
+/** Node 24 by version and by digest (the multi-platform index); update both together. */
+const nodeImage = "node:24.21.0-alpine@sha256:ebfe2f90462722a7a4de65e91990e97fe0d401c70e0e762c5b53302f905ec1c1";
+/** The corepack that gives the image the manifest's pnpm; pinned, so a build never takes the latest. */
+const corepack = "0.36.0";
+/** http's default port: the image changes only the interface it listens on. */
+const httpPort = 8080;
+/** Secrets of any file name stay out of git: env files but their example, the local layer, keys. */
+const gitIgnored = [
+    "node_modules/",
+    "config/local*.conf",
+    ".env",
+    ".env.*",
+    "!.env.example",
+    "*.pem",
+    "*.key",
+];
+/** The image's build context leaves out git, every env file, the local layer, keys and the host's install. */
+const dockerIgnored = [
+    ".git",
+    ".env",
+    ".env.*",
+    "config/local*.conf",
+    "*.pem",
+    "*.key",
+    "node_modules/",
+];
+const lines = (entries) => `${entries.join("\n")}\n`;
+/** Writes the project assembling `modules` into an empty target, its guide from `readme`'s template and values. */
+export async function writeDeployment(plan, modules, readme) {
+    await vacant(plan.target);
+    const names = withKernel(modules);
+    const packages = packagesFor(plan);
+    const fragments = await packages.fragments(names);
+    const settings = settingsOf(fragments);
+    await writeProject(plan.target, {
+        "package.json": manifestOf("node --env-file-if-exists=.env src/main.ts", packages.dependencies(names)),
+        [paths.main]: await mainSource(modules, packages.importOf),
+        [paths.application]: applicationConf(fragments),
+        [paths.localExample]: localConfExample(fragments),
+        ".env.example": envExample(settings),
+        Dockerfile: dockerfile(),
+        ".dockerignore": lines(dockerIgnored),
+        ".gitignore": lines(gitIgnored),
+        "README.md": await filled(readme.template, {
+            ...paths,
+            ...guideLists(settings, writtenOf(fragments)),
+            port: String(httpPort),
+            ...readme.fill,
+        }),
+    });
+}
+/** The guide's lists: the keys read from env as table rows, and those written in the local layer. */
+const guideLists = (settings, written) => ({
+    settings: settings
+        .map((s) => `| \`${s.key}\` | \`${s.env}\` | \`${s.placeholder}\` |`)
+        .join("\n"),
+    written: written
+        .map((w) => `- \`${w.key}\`${w.spansSections ? " (spans sections: written by the operator)" : ""}`)
+        .join("\n"),
+});
+function dockerfile() {
+    return `# syntax=docker/dockerfile:1
+# Node 24 pinned by version and digest, corepack pinned too; pnpm is the manifest's packageManager.
+FROM ${nodeImage} AS base
+# An init as process 1 passes signals on and reaps what node leaves behind.
+RUN apk add --no-cache tini && npm install --global corepack@${corepack} && corepack enable
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+
+FROM base AS runtime
+ENV NODE_ENV=production
+COPY --from=deps /app/node_modules ./node_modules
+COPY package.json ./
+COPY src ./src
+COPY ${paths.application} ./${paths.application}
+# Listens on every interface inside the container; the port is http's, which the health check follows.
+ENV ${envName("http.host")}=0.0.0.0
+ENV ${envName("http.port")}=${httpPort}
+USER node
+EXPOSE \${${envName("http.port")}}
+# Liveness, not readiness: the container is restarted only when the process stops answering.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD ["node", "-e", "fetch('http://127.0.0.1:' + process.env.${envName("http.port")} + '/_healthcheck').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "${paths.main}"]
+`;
+}

package/create-app/src/fragments.d.ts

@@ -0,0 +1,41 @@
+/** The file beside a package's manifest that holds its section's example. */
+export declare const fragmentFile = "config.example";
+type Tree = {
+    readonly [key: string]: unknown;
+};
+/** One section's example, as its owner wrote it: placeholders only. */
+export interface Fragment {
+    readonly section: string;
+    readonly tree: Tree;
+}
+/** A scalar key of a fragment, read from the environment variable named for it. */
+export interface Setting {
+    readonly key: string;
+    readonly env: string;
+    readonly placeholder: string;
+}
+/** A key the configuration file does not read from env: a list, or a value the operator writes. */
+export interface Written {
+    readonly key: string;
+    readonly example: string;
+    /** Whether it spans sections: the fragment's value is for its schema only, and the operator writes it. */
+    readonly spansSections: boolean;
+}
+/** The fragments beside the packages in `dirs`, in that order; a package without one is skipped. */
+export declare function fragmentsIn(dirs: readonly string[]): Promise<Fragment[]>;
+/** Fragments from their texts, each of exactly one section, no section twice; `from` names it in a refusal. */
+export declare function fragmentsOf(texts: readonly {
+    readonly from: string;
+    readonly text: string;
+}[]): Fragment[];
+export declare const envName: (key: string) => string;
+/** The fragments' scalar keys with their variables; refuses two keys reading one, naming both, and an unnameable one. */
+export declare function settingsOf(fragments: readonly Fragment[]): Setting[];
+/** The keys the operator writes in a local layer: the fragments' lists, and the values that span sections. */
+export declare function writtenOf(fragments: readonly Fragment[]): Written[];
+/** Every scalar key reads its environment variable, and holds no value. */
+export declare function applicationConf(fragments: readonly Fragment[]): string;
+/** Each list with its placeholders, and each value that spans sections, by its dotted key. */
+export declare function localConfExample(fragments: readonly Fragment[]): string;
+export declare function envExample(settings: readonly Setting[]): string;
+export {};

package/create-app/src/fragments.js

@@ -0,0 +1,109 @@
+/** The boundary between the modules' sections and the project's environment: fragments mapped to env and the local layer. */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "@o3co/ts.hocon";
+import { missingAs } from "./project.js";
+/** The file beside a package's manifest that holds its section's example. */
+export const fragmentFile = "config.example";
+/** Values spanning sections, in a fragment for its schema only: copied, they would boot; the operator writes them. */
+const spanningSections = new Map([
+    ["audit.receivers", "[REPLACE-RECEIVER-NAMES]"],
+]);
+const isTree = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The fragments beside the packages in `dirs`, in that order; a package without one is skipped. */
+export async function fragmentsIn(dirs) {
+    const read = [];
+    for (const dir of dirs) {
+        const file = join(dir, fragmentFile);
+        const text = await readFile(file, "utf8").catch(missingAs(undefined));
+        if (text !== undefined)
+            read.push({ from: file, text });
+    }
+    return fragmentsOf(read);
+}
+/** Fragments from their texts, each of exactly one section, no section twice; `from` names it in a refusal. */
+export function fragmentsOf(texts) {
+    const fragments = [];
+    for (const { from, text } of texts) {
+        const tree = parse(text).toObject();
+        const roots = isTree(tree) ? Object.entries(tree) : [];
+        const [root] = roots;
+        if (roots.length !== 1 || root === undefined || !isTree(root[1])) {
+            throw new Error(`${from} does not hold exactly one section`);
+        }
+        if (fragments.some((f) => f.section === root[0])) {
+            throw new Error(`${from}: a second fragment for ${root[0]}`);
+        }
+        fragments.push({ section: root[0], tree: root[1] });
+    }
+    return fragments;
+}
+/** Each leaf of a tree with its path: objects are walked into, lists and scalars are leaves. */
+function leaves(tree, path) {
+    return Object.entries(tree).flatMap(([key, value]) => isTree(value) ? leaves(value, [...path, key]) : [[[...path, key], value]]);
+}
+const scalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+/** The environment variable a key reads: the path joined by `_`, upper-cased, `-` as `_`. */
+const envOf = (path) => path.join("_").toUpperCase().replaceAll("-", "_");
+export const envName = (key) => envOf(key.split("."));
+/** The fragments' scalar keys with their variables; refuses two keys reading one, naming both, and an unnameable one. */
+export function settingsOf(fragments) {
+    const settings = fragments.flatMap((f) => leaves(f.tree, [f.section])
+        .filter(([path, value]) => scalar(value) && !spanningSections.has(path.join(".")))
+        .map(([path, value]) => ({
+        key: path.join("."),
+        env: envOf(path),
+        placeholder: String(value),
+    })));
+    const refusals = settings.flatMap((s, i) => {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(s.env))
+            return [`${s.key}: no environment variable name`];
+        const first = settings.findIndex((other) => other.env === s.env);
+        return first < i ? [`${settings[first]?.key} and ${s.key} both read ${s.env}`] : [];
+    });
+    if (refusals.length > 0)
+        throw new Error(refusals.join("; "));
+    return settings;
+}
+/** The keys the operator writes in a local layer: the fragments' lists, and the values that span sections. */
+export function writtenOf(fragments) {
+    return fragments.flatMap((f) => leaves(f.tree, [f.section]).flatMap(([path, value]) => {
+        const key = path.join(".");
+        const noted = spanningSections.get(key);
+        if (noted !== undefined)
+            return [{ key, example: noted, spansSections: true }];
+        return Array.isArray(value)
+            ? [{ key, example: JSON.stringify(value, null, "\t"), spansSections: false }]
+            : [];
+    }));
+}
+const hoconKey = (key) => (/^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key));
+/** HOCON for the fragments, nested as they nest: `line` writes each leaf it keeps; a block keeping none is left out. */
+function render(header, fragments, line) {
+    const block = (tree, path) => Object.entries(tree).flatMap(([name, value]) => {
+        const at = [...path, name];
+        if (!isTree(value))
+            return line(at.join("."), hoconKey(name))?.split("\n") ?? [];
+        const inner = block(value, at).map((l) => `\t${l}`);
+        return inner.length === 0 ? [] : [`${hoconKey(name)} {`, ...inner, "}"];
+    });
+    const tree = Object.fromEntries(fragments.map((f) => [f.section, f.tree]));
+    return `${[header, ...block(tree, [])].join("\n")}\n`;
+}
+/** Every scalar key reads its environment variable, and holds no value. */
+export function applicationConf(fragments) {
+    const env = new Map(settingsOf(fragments).map((s) => [s.key, s.env]));
+    return render("# Each key reads its environment variable (see .env.example); this file holds no values.", fragments, (key, name) => (env.has(key) ? `${name} = \${?${env.get(key)}}` : undefined));
+}
+/** No live line in an example: `## ` opens prose, `# ` a value, so a copy sets nothing. */
+const prose = "## ";
+const commented = (text) => text.replace(/^/gm, "# ");
+const example = (header, values) => `${[`${prose}${header}`, ...values.map(commented)].join("\n")}\n`;
+/** Each list with its placeholders, and each value that spans sections, by its dotted key. */
+export function localConfExample(fragments) {
+    return example("Copy to config/local.conf, uncomment each key and replace its placeholders; git and the image leave that file out.", writtenOf(fragments).map((w) => `${w.key.split(".").map(hoconKey).join(".")} = ${w.example}`));
+}
+export function envExample(settings) {
+    const quoted = (value) => (/^[^\s"'#\\]*$/.test(value) ? value : JSON.stringify(value));
+    return example("Copy to .env, uncomment each line and replace its placeholder; git and the image leave .env out.", settings.map((s) => `${s.env}=${quoted(s.placeholder)}`));
+}

package/create-app/src/full.d.ts

@@ -0,0 +1,2 @@
+import type { FullPlan } from "./contract.js";
+export declare function generateFull(plan: FullPlan): Promise<void>;