@aventara/client 0.0.0-stage → 0.1.0-pilot.0

package/dist/init/client-config.template.js

@@ -0,0 +1,22 @@
+import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+/** The package the written config imports its two functions from. */
+const CLIENT_PACKAGE = "@aventara/client";
+/** R4, §15.2 — the `framework.client.ts` `avclient init` writes: developer-owned, read by `avclient generate`. */
+export function clientConfigSource(input) {
+    return [
+        // The specifier is spliced in, not written after `from`, so this module's own
+        // shipped JavaScript does not read as importing the package it names.
+        input.envVar === undefined
+            ? `import { defineClientConfig } from ${JSON.stringify(CLIENT_PACKAGE)};`
+            : `import { defineClientConfig, env } from ${JSON.stringify(CLIENT_PACKAGE)};`,
+        "",
+        `// ${CLIENT_CONFIG_FILE}: where the Aventara server is, and where its typed client goes.`,
+        "export default defineClientConfig({",
+        input.envVar === undefined
+            ? `\tentrypoint: ${JSON.stringify(input.entrypoint)},`
+            : `\tentrypoint: env(${JSON.stringify(input.envVar)}),`,
+        `\tgenerateAt: ${JSON.stringify(input.generateAt)},`,
+        "});",
+        "",
+    ].join("\n");
+}

package/dist/init/client-init.errors.d.ts

@@ -0,0 +1,9 @@
+/** `avclient init`'s refusals after the questions: each one sentence, exit 1. */
+/** Nobody confirmed replacing existing content. A refusal: nothing was touched. */
+export declare class ClientInitNotConfirmedError extends Error {
+    readonly name = "ClientInitNotConfirmedError";
+}
+/** A step after the write failed. Reported with what to run; the files are kept. */
+export declare class ClientInitStepError extends Error {
+    readonly name = "ClientInitStepError";
+}

package/dist/init/client-init.errors.js

@@ -0,0 +1,9 @@
+/** `avclient init`'s refusals after the questions: each one sentence, exit 1. */
+/** Nobody confirmed replacing existing content. A refusal: nothing was touched. */
+export class ClientInitNotConfirmedError extends Error {
+    name = "ClientInitNotConfirmedError";
+}
+/** A step after the write failed. Reported with what to run; the files are kept. */
+export class ClientInitStepError extends Error {
+    name = "ClientInitStepError";
+}

package/dist/init/client-init.orchestrator.d.ts

@@ -0,0 +1,3 @@
+import type { ClientInitCommand } from "../cli/command.parser.js";
+import { type CliIo } from "../cli/generate.command.js";
+export declare function runClientInit(command: ClientInitCommand, io: CliIo): Promise<number>;

package/dist/init/client-init.orchestrator.js

@@ -0,0 +1,82 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { runGenerate } from "../cli/generate.command.js";
+import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+import { ContractTransportError } from "../contract/contract.fetcher.js";
+import { ClientInitNotConfirmedError, ClientInitStepError, } from "./client-init.errors.js";
+import { GENERATE_SCRIPT, planClientInit } from "./client-init.planner.js";
+import { resolveClientInitAnswers } from "./client-init.questions.js";
+import { inspectClientProject } from "./client-project.inspector.js";
+import { runCommand } from "./command.runner.js";
+/**
+ * R4 — `avclient init`, the whole frontend setup, in the order every wizard of
+ * this item keeps: inspect, ask, plan, confirm, and only then write; then the
+ * install (N6) and, unless skipped, the first generation through the very path
+ * `avclient generate` takes. A refusal before the write leaves the project as
+ * it was; a failure after it says what to run next, and keeps the files.
+ */
+const MANIFEST = new URL("../../package.json", import.meta.url);
+function ownVersion() {
+    return JSON.parse(readFileSync(MANIFEST, "utf8"))
+        .version;
+}
+export async function runClientInit(command, io) {
+    const project = inspectClientProject(io.cwd);
+    const userAgent = io.env.npm_config_user_agent;
+    const answers = await resolveClientInitAnswers({
+        given: command.given,
+        noEnvVar: command.noEnvVar,
+        yes: command.yes,
+        interactive: io.interactive,
+        ask: io.ask ?? (async () => ""),
+        say: (line) => io.stderr(`${line}\n`),
+        detectedPackageManager: project.lockfile ??
+            (userAgent?.split("/")[0] === "pnpm" ? "pnpm" : "npm"),
+    });
+    const clientVersion = ownVersion();
+    const plan = planClientInit({ project, answers, clientVersion });
+    // The generateAt rule (architect, 2026-10-04; R5).
+    if (plan.conflicts.length > 0 && !command.yes) {
+        const them = plan.conflicts.length === 1 ? "it" : "them";
+        const has = plan.conflicts.length === 1 ? "has" : "have";
+        if (!io.interactive) {
+            throw new ClientInitNotConfirmedError(`not initializing, and nothing was touched: ${plan.conflicts.join(", ")} already ${has} other content and nobody can be asked (stdin is not a terminal); run \`avclient init --yes\` to replace ${them}.`);
+        }
+        io.stderr(`avclient: warning: ${plan.conflicts.join(", ")} already ${has} other content, and initializing will replace ${them}.\n`);
+        if (!(await io.confirm("avclient: replace them and initialize? [y/N] "))) {
+            throw new ClientInitNotConfirmedError(`cancelled, and nothing was touched; run again and answer yes to replace ${them}.`);
+        }
+    }
+    const writes = plan.conflicts.length === 0 ? plan.keeping : plan.replacing;
+    for (const write of writes) {
+        const target = path.join(io.cwd, write.path);
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, write.content);
+    }
+    io.stdout(`avclient: initialized ${io.cwd}: ${writes.map((write) => write.path).join(", ") || "nothing to change"}.\n`);
+    const install = `${answers.packageManager} install`;
+    if (command.skipInstall) {
+        io.stdout(`Next:\n  1. Install @aventara/client ${clientVersion}: ${install}\n  2. With the server running: ${answers.packageManager} run ${GENERATE_SCRIPT}\n`);
+        return 0;
+    }
+    io.stdout(`avclient: running ${install}…\n`);
+    const installed = await (io.run ?? runCommand)(answers.packageManager, ["install"], {
+        cwd: io.cwd,
+    });
+    if (installed.code !== 0) {
+        throw new ClientInitStepError(`\`${install}\` exited with code ${installed.code} after ${CLIENT_CONFIG_FILE} was written; fix what it reports and run \`${install}\` again:\n${installed.stderr.trimEnd()}`);
+    }
+    if (command.skipGenerate) {
+        io.stdout(`Next: with the server running, ${answers.packageManager} run ${GENERATE_SCRIPT}\n`);
+        return 0;
+    }
+    try {
+        return await runGenerate(io, command.yes);
+    }
+    catch (error) {
+        if (error instanceof ContractTransportError) {
+            throw new ClientInitStepError(`the project is set up, but the server did not answer (${error.message.replace(/\.$/, "")}); once it is running, run \`avclient generate\`.`);
+        }
+        throw error;
+    }
+}

package/dist/init/client-init.planner.d.ts

@@ -0,0 +1,26 @@
+import type { ClientInitAnswers } from "./client-init.questions.js";
+import type { ClientProject } from "./client-project.inspector.js";
+/**
+ * §4.5 — what `avclient init` writes, decided before anything is: the config
+ * file, the `.env` entry (only with a variable), the `avclient:generate` script
+ * and the exact devDependency (N6) — each computed with existing content kept
+ * and replaced, and every **conflict** (content it did not produce) named for
+ * the generateAt rule.
+ */
+/** R4: the script a frontend regenerates its client with. */
+export declare const GENERATE_SCRIPT = "avclient:generate";
+export type ClientInitWrite = {
+    readonly path: string;
+    readonly content: string;
+};
+export type ClientInitPlan = {
+    readonly keeping: readonly ClientInitWrite[];
+    readonly replacing: readonly ClientInitWrite[];
+    readonly conflicts: readonly string[];
+};
+export declare function planClientInit(input: {
+    readonly project: ClientProject;
+    readonly answers: ClientInitAnswers;
+    /** This package's own version: the devDependency is pinned to it exactly (N6). */
+    readonly clientVersion: string;
+}): ClientInitPlan;

package/dist/init/client-init.planner.js

@@ -0,0 +1,88 @@
+import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+import { clientConfigSource } from "./client-config.template.js";
+/**
+ * §4.5 — what `avclient init` writes, decided before anything is: the config
+ * file, the `.env` entry (only with a variable), the `avclient:generate` script
+ * and the exact devDependency (N6) — each computed with existing content kept
+ * and replaced, and every **conflict** (content it did not produce) named for
+ * the generateAt rule.
+ */
+/** R4: the script a frontend regenerates its client with. */
+export const GENERATE_SCRIPT = "avclient:generate";
+const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
+function unquoted(value) {
+    const quote = value[0];
+    return (quote === '"' || quote === "'") && value.endsWith(quote)
+        ? value.slice(1, -1)
+        : value;
+}
+export function planClientInit(input) {
+    const { project, answers } = input;
+    const conflicts = [];
+    const keeping = [];
+    const replacing = [];
+    const add = (path, before, kept, replaced) => {
+        if (kept !== before) {
+            keeping.push({ path, content: kept });
+        }
+        if (replaced !== before) {
+            replacing.push({ path, content: replaced });
+        }
+    };
+    const config = clientConfigSource(answers);
+    const existingConfig = project.read(CLIENT_CONFIG_FILE);
+    if (existingConfig !== undefined && existingConfig !== config) {
+        conflicts.push(CLIENT_CONFIG_FILE);
+    }
+    add(CLIENT_CONFIG_FILE, existingConfig, existingConfig ?? config, config);
+    if (answers.envVar !== undefined) {
+        const before = project.read(".env");
+        const lines = before === undefined || before === ""
+            ? []
+            : before.replace(/\n$/, "").split("\n");
+        const at = lines.findIndex((line) => ENV_LINE.exec(line)?.[1] === answers.envVar);
+        const line = `${answers.envVar}="${answers.entrypoint}"`;
+        const kept = [...lines];
+        const replaced = [...lines];
+        if (at === -1) {
+            kept.push(line);
+            replaced.push(line);
+        }
+        else if (unquoted(ENV_LINE.exec(lines[at])?.[2] ?? "") !==
+            answers.entrypoint) {
+            conflicts.push(`.env's ${answers.envVar}`);
+            replaced[at] = line;
+        }
+        add(".env", before, `${kept.join("\n")}\n`, `${replaced.join("\n")}\n`);
+    }
+    const manifest = (replace) => {
+        const parsed = JSON.parse(project.manifestText);
+        const scripts = {
+            ...(parsed.scripts ?? {}),
+        };
+        const command = "avclient generate";
+        if (scripts[GENERATE_SCRIPT] === undefined || replace) {
+            scripts[GENERATE_SCRIPT] = command;
+        }
+        const devDependencies = {
+            ...(parsed.devDependencies ?? {}),
+        };
+        if (devDependencies["@aventara/client"] === undefined || replace) {
+            devDependencies["@aventara/client"] = input.clientVersion;
+        }
+        parsed.scripts = scripts;
+        parsed.devDependencies = Object.fromEntries(Object.entries(devDependencies).sort(([left], [right]) => left < right ? -1 : 1));
+        return `${JSON.stringify(parsed, null, 2)}\n`;
+    };
+    const parsed = JSON.parse(project.manifestText);
+    const script = parsed.scripts?.[GENERATE_SCRIPT];
+    if (script !== undefined && script !== "avclient generate") {
+        conflicts.push(`package.json's scripts["${GENERATE_SCRIPT}"]`);
+    }
+    const pinned = parsed.devDependencies?.["@aventara/client"];
+    if (pinned !== undefined && pinned !== input.clientVersion) {
+        conflicts.push(`package.json's devDependencies["@aventara/client"] (${pinned})`);
+    }
+    add("package.json", project.manifestText, manifest(false), manifest(true));
+    return { keeping, replacing, conflicts };
+}

package/dist/init/client-init.questions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * R4, R5, Q16 rows 12–15 — `avclient init`'s questions in one table: each
+ * question's flag, label and default, from which the command line, the prompt,
+ * `--yes`'s defaults and the non-interactive refusal are derived — the rule
+ * `@aventara/cli`'s wizard follows, implemented here because the two packages
+ * never import each other (P7).
+ */
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+export type ClientInitAnswers = {
+    /** The deployment's entrypoint (Q16-12: `--entrypoint`, `defineClientConfig`'s key). */
+    readonly entrypoint: string;
+    /** The variable `framework.client.ts` reads it from, or `undefined` for a literal (Q16-13). */
+    readonly envVar: string | undefined;
+    /** Where the client is generated (Q16-14: `--generate-at`, the config key). */
+    readonly generateAt: string;
+    readonly packageManager: PackageManager;
+};
+type QuestionId = "entrypoint" | "envVar" | "generateAt" | "packageManager";
+/** An answer the question cannot take. A refusal: one sentence. */
+export declare class ClientInitAnswerError extends Error {
+    readonly name = "ClientInitAnswerError";
+}
+/** Nobody can answer and some questions are unanswered. A refusal: one sentence. */
+export declare class ClientInitUnansweredError extends Error {
+    readonly name = "ClientInitUnansweredError";
+}
+export type ClientInitQuestion = {
+    readonly id: QuestionId;
+    readonly flag: string;
+    readonly placeholder: string;
+    readonly label: string;
+    readonly defaultFor: (detectedPackageManager: PackageManager) => string;
+    /** @throws ClientInitAnswerError */
+    readonly parse: (raw: string) => string;
+};
+/** The project convention for the variable (spec §15.2). */
+export declare const DEFAULT_ENV_VAR = "AVENTARA_API_URL";
+export declare const CLIENT_INIT_QUESTIONS: readonly ClientInitQuestion[];
+export type ClientInitSources = {
+    readonly given: Readonly<Partial<Record<QuestionId, string>>>;
+    /** `--no-env-var`: the entrypoint is written as a literal, and no variable is asked. */
+    readonly noEnvVar: boolean;
+    readonly yes: boolean;
+    readonly interactive: boolean;
+    readonly ask: (prompt: string) => Promise<string>;
+    readonly say: (line: string) => void;
+    readonly detectedPackageManager: PackageManager;
+};
+/** Flag → `--yes`'s default → the prompt → the refusal naming exactly the unanswered flags (R5). */
+export declare function resolveClientInitAnswers(sources: ClientInitSources): Promise<ClientInitAnswers>;
+export {};

package/dist/init/client-init.questions.js

@@ -0,0 +1,124 @@
+import { resolveEntrypoint } from "../config/config.resolver.js";
+/**
+ * R4, R5, Q16 rows 12–15 — `avclient init`'s questions in one table: each
+ * question's flag, label and default, from which the command line, the prompt,
+ * `--yes`'s defaults and the non-interactive refusal are derived — the rule
+ * `@aventara/cli`'s wizard follows, implemented here because the two packages
+ * never import each other (P7).
+ */
+export const PACKAGE_MANAGERS = ["npm", "pnpm"];
+/** An answer the question cannot take. A refusal: one sentence. */
+export class ClientInitAnswerError extends Error {
+    name = "ClientInitAnswerError";
+}
+/** Nobody can answer and some questions are unanswered. A refusal: one sentence. */
+export class ClientInitUnansweredError extends Error {
+    name = "ClientInitUnansweredError";
+}
+/** The project convention for the variable (spec §15.2). */
+export const DEFAULT_ENV_VAR = "AVENTARA_API_URL";
+export const CLIENT_INIT_QUESTIONS = [
+    {
+        id: "entrypoint",
+        flag: "--entrypoint",
+        placeholder: "<url>",
+        label: "Server entrypoint",
+        defaultFor: () => "http://localhost:3000/api",
+        parse: (raw) => {
+            try {
+                resolveEntrypoint(raw.trim());
+            }
+            catch (error) {
+                throw new ClientInitAnswerError(error.message.replace(/\.$/, ""));
+            }
+            return raw.trim();
+        },
+    },
+    {
+        id: "envVar",
+        flag: "--env-var",
+        placeholder: "<NAME>",
+        label: "Environment variable holding it",
+        defaultFor: () => DEFAULT_ENV_VAR,
+        parse: (raw) => {
+            const name = raw.trim();
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+                throw new ClientInitAnswerError(`${JSON.stringify(raw)} is not an environment variable name.`);
+            }
+            return name;
+        },
+    },
+    {
+        id: "generateAt",
+        flag: "--generate-at",
+        placeholder: "<dir>",
+        label: "Generate the client into",
+        defaultFor: () => "./src/api",
+        parse: (raw) => {
+            const directory = raw.trim();
+            if (directory === "") {
+                throw new ClientInitAnswerError("--generate-at takes a directory.");
+            }
+            return directory;
+        },
+    },
+    {
+        id: "packageManager",
+        flag: "--package-manager",
+        placeholder: `<${PACKAGE_MANAGERS.join("|")}>`,
+        label: `Package manager (${PACKAGE_MANAGERS.join(", ")})`,
+        defaultFor: (detected) => detected,
+        parse: (raw) => {
+            const manager = PACKAGE_MANAGERS.find((candidate) => candidate === raw.trim());
+            if (manager === undefined) {
+                throw new ClientInitAnswerError(`${JSON.stringify(raw)} is not a supported package manager; choose ${PACKAGE_MANAGERS.join(" or ")}.`);
+            }
+            return manager;
+        },
+    },
+];
+/** Flag → `--yes`'s default → the prompt → the refusal naming exactly the unanswered flags (R5). */
+export async function resolveClientInitAnswers(sources) {
+    const answered = {};
+    const missing = [];
+    for (const question of CLIENT_INIT_QUESTIONS) {
+        if (question.id === "envVar" && sources.noEnvVar) {
+            continue;
+        }
+        const given = sources.given[question.id];
+        const fallback = question.defaultFor(sources.detectedPackageManager);
+        if (given !== undefined) {
+            answered[question.id] = question.parse(given);
+        }
+        else if (sources.yes) {
+            answered[question.id] = question.parse(fallback);
+        }
+        else if (sources.interactive) {
+            for (;;) {
+                const typed = (await sources.ask(`${question.label} [${fallback}]: `)).trim();
+                try {
+                    answered[question.id] = question.parse(typed === "" ? fallback : typed);
+                    break;
+                }
+                catch (error) {
+                    if (!(error instanceof ClientInitAnswerError)) {
+                        throw error;
+                    }
+                    sources.say(error.message);
+                }
+            }
+        }
+        else {
+            missing.push(`${question.flag} ${question.placeholder}`);
+        }
+    }
+    if (missing.length > 0) {
+        throw new ClientInitUnansweredError(`stdin is not a terminal, so nothing can be asked: pass ${missing.join(", ")}, or pass --yes to accept their defaults.`);
+    }
+    return {
+        entrypoint: answered.entrypoint,
+        envVar: sources.noEnvVar ? undefined : answered.envVar,
+        generateAt: answered.generateAt,
+        packageManager: answered.packageManager,
+    };
+}

package/dist/init/client-project.inspector.d.ts

@@ -0,0 +1,15 @@
+import type { PackageManager } from "./client-init.questions.js";
+/** The frontend `avclient init` serves, read before anything is asked or written. */
+/** The directory is not a project `avclient init` can set up. A refusal: nothing written. */
+export declare class ClientProjectRefusedError extends Error {
+    readonly name = "ClientProjectRefusedError";
+}
+export type ClientProject = {
+    readonly directory: string;
+    readonly manifestText: string;
+    /** The package manager its lockfile names, if exactly one does. */
+    readonly lockfile: PackageManager | undefined;
+    /** The current text of a project file, or `undefined`. */
+    readonly read: (file: string) => string | undefined;
+};
+export declare function inspectClientProject(directory: string): ClientProject;

package/dist/init/client-project.inspector.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/** The frontend `avclient init` serves, read before anything is asked or written. */
+/** The directory is not a project `avclient init` can set up. A refusal: nothing written. */
+export class ClientProjectRefusedError extends Error {
+    name = "ClientProjectRefusedError";
+}
+export function inspectClientProject(directory) {
+    const manifest = path.join(directory, "package.json");
+    if (!existsSync(manifest)) {
+        throw new ClientProjectRefusedError("avclient init runs in a frontend project: no package.json here; create one first.");
+    }
+    const lockfiles = [
+        ["package-lock.json", "npm"],
+        ["pnpm-lock.yaml", "pnpm"],
+    ]
+        .filter(([file]) => existsSync(path.join(directory, file)))
+        .map(([, manager]) => manager);
+    return {
+        directory,
+        manifestText: readFileSync(manifest, "utf8"),
+        lockfile: lockfiles.length === 1 ? lockfiles[0] : undefined,
+        read: (file) => {
+            try {
+                return readFileSync(path.join(directory, file), "utf8");
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/init/command.runner.d.ts

@@ -0,0 +1,8 @@
+/** One child process, stdout and stderr piped and collected: `init`'s install. */
+export type CommandRunner = (command: string, args: readonly string[], options: {
+    readonly cwd: string;
+}) => Promise<{
+    readonly code: number;
+    readonly stderr: string;
+}>;
+export declare const runCommand: CommandRunner;

package/dist/init/command.runner.js

@@ -0,0 +1,17 @@
+import { spawn } from "node:child_process";
+export const runCommand = (command, args, options) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: process.env,
+    });
+    let stderr = "";
+    child.stdout.resume();
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+        stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (code) => {
+        resolve({ code: code ?? 1, stderr });
+    });
+});

package/dist/node-version.guard.d.ts

@@ -0,0 +1,8 @@
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export declare function nodeVersionRefusal(bin: string, packageName: string, range: string, version: string): string | undefined;
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export declare function refuseUnsupportedNode(bin: string, manifestUrl: URL): boolean;

package/dist/node-version.guard.js

@@ -0,0 +1,59 @@
+// biome-ignore lint/style/useNodejsImportProtocol: Node 14.0–14.13.0 resolves no "node:" specifier in an ES module, and this module runs on the Nodes the packages do not support.
+import { readFileSync } from "fs";
+function versionOf(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null) {
+        throw new Error(`"${text}" is not a Node version`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left[index] - right[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+/**
+ * Whether `range` admits `version`. Reads `^x.y.z` (the same major, from the
+ * floor; majors ≥ 1) and `>=x.y.z`, joined by `||`; anything else throws rather
+ * than admit or refuse by guess.
+ */
+function admits(range, version) {
+    return range.split("||").some((part) => {
+        const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
+        if (comparator === null) {
+            throw new Error(`engines.node "${range}": the bin's Node guard reads only "^x.y.z" and ">=x.y.z" joined by "||"`);
+        }
+        const floor = versionOf(comparator[2]);
+        return (compareVersions(version, floor) >= 0 &&
+            (comparator[1] === ">=" || version[0] === floor[0]));
+    });
+}
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export function nodeVersionRefusal(bin, packageName, range, version) {
+    return admits(range, versionOf(version))
+        ? undefined
+        : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
+}
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export function refuseUnsupportedNode(bin, manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const range = manifest.engines === undefined ? undefined : manifest.engines.node;
+    if (range === undefined) {
+        throw new Error(`${manifest.name} declares no engines.node for its bin's Node guard`);
+    }
+    const refusal = nodeVersionRefusal(bin, manifest.name, range, process.version);
+    if (refusal === undefined) {
+        return false;
+    }
+    process.stderr.write(`${refusal}\n`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/output/output.validator.d.ts

@@ -0,0 +1,76 @@
+import type * as ts from "typescript";
+import type { EmittedTree } from "../emit/emitted-tree.interface.js";
+/**
+ * §15.3's "type/sanity validation" step, between emit-to-temp and the replace:
+ * the gate that makes the atomicity worth having (plan §4 Q6). It judges a
+ * directory the writer has just filled with `tree`, and answers with a value — the
+ * writer decides what a rejection means for the previous output.
+ *
+ * # Three checks, the strongest available first
+ *
+ * - **Shape**, always: the directory holds exactly `tree` — no file missing, none
+ *   extra, every one byte-for-byte what was emitted — and every file carries the
+ *   ownership line. That last is not decoration: the NEXT run reads it to decide
+ *   that this directory is a previous generation it may replace whole, so a file
+ *   without it would make the next run refuse.
+ * - **Types**, when the `typescript` optional peer resolves (Q5, Q6): a real
+ *   program over the tree under a consumer's strictest plausible settings. The
+ *   tree is judged ALONE — the compiler host serves nothing outside the directory
+ *   but TypeScript's own `lib` files, so an import the tree cannot satisfy itself
+ *   fails here even when a `node_modules` beside the output could satisfy it
+ *   (§15.5).
+ * - **Syntax**, when it does not: each file through Node's own TypeScript parser
+ *   (`node:module`'s `stripTypeScriptTypes`), with a loud warning that the output
+ *   was NOT type-checked. Degraded, never skipped (S7).
+ */
+/** The `typescript` module, as the validator uses it. */
+export type TypeScriptCompiler = typeof ts;
+/**
+ * Finds the `typescript` optional peer: the module, or `undefined` when it is not
+ * installed. Anything else — an installation that resolves but fails to load — is
+ * not "absent" and is thrown.
+ */
+export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
+/**
+ * A resolver for `specifier`, looked up from this package the way Node would look
+ * it up: an optional peer is linked beside the package that declares it.
+ */
+export declare function typeScriptResolverFor(specifier: string): TypeScriptResolver;
+/** The `typescript` this package's optional peer names (Q5). */
+export declare const resolveInstalledTypeScript: TypeScriptResolver;
+/**
+ * D4 — the resolved `typescript` has no classic compiler API. TypeScript 7 is
+ * such a package (plan B3: it exports its version and nothing else), and before
+ * this refusal the type check died on it with a `TypeError` stack. A refusal,
+ * not a degraded check: a compiler the developer installed is not "absent", and
+ * passing it over silently would weaken the check they chose.
+ */
+export declare class UnsupportedTypeScriptError extends Error {
+    readonly name = "UnsupportedTypeScriptError";
+}
+/** How deeply the tree was judged. */
+export type OutputCheck = "types" | "syntax" | "shape";
+export interface OutputAccepted {
+    readonly accepted: true;
+    readonly checked: OutputCheck;
+    /** Said once to the person running the generator; empty when nothing degraded. */
+    readonly warnings: readonly string[];
+}
+export interface OutputRejected {
+    readonly accepted: false;
+    readonly checked: OutputCheck;
+    /** What is wrong, one line per finding, paths relative to the tree. */
+    readonly findings: readonly string[];
+}
+export type OutputValidation = OutputAccepted | OutputRejected;
+/**
+ * The warning a run without `typescript` carries. Loud on purpose, in its words:
+ * the prefix is the CLI's one `warning:`, so the text carries none of its own.
+ */
+export declare const TYPESCRIPT_UNRESOLVED_WARNING: string;
+/** The warning a run with neither `typescript` nor Node's parser carries. */
+export declare const SYNTAX_CHECK_UNAVAILABLE_WARNING: string;
+/**
+ * Judges `directory`, which the caller has just filled with `tree`.
+ */
+export declare function validateOutputTree(directory: string, tree: EmittedTree, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;