@aventara/client 0.1.0-pilot.2 → 0.1.0-pilot.3

package/README.md

@@ -91,8 +91,9 @@ supported yet.
 - **A failed run leaves the previous output exactly as it was.** The whole tree is written to a staging directory inside
   `generateAt`, validated there as one program, and only then moved into place. A run killed part-way is repaired by the
   next run that writes, before it writes anything. A first run that fails removes the directories it created.
-- **The validate step is a real type check** when the optional peer `typescript` (5.5 to 6) is installed, under a
-  consumer's strictest plausible settings and with nothing outside the tree resolvable. Without it — or under
+- **The validate step is a real type check** when your project has the optional peer `typescript` (5.5 to 6) — it is
+  resolved from your project, so `npx @aventara/client@pilot init` type-checks too — under a consumer's strictest plausible
+  settings and with nothing outside the tree resolvable. Without it — or under
   TypeScript 7, which has no classic compiler API to check with — the check degrades to a parse with Node's own
   TypeScript parser, and says so loudly in one warning; it is never skipped, and the client is still written. The peer
   range has no upper bound, so a frontend on TypeScript 7 installs it; your own `tsc` checks the tree when it compiles.

package/dist/generate.d.ts

@@ -32,7 +32,10 @@ export interface ClientGenerationInput {
     readonly overrideForeign?: boolean;
     /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
-    /** The `typescript` optional peer; the installed one by default. */
+    /**
+     * The `typescript` optional peer; by default the project's own, resolved from
+     * `generateAt`.
+     */
     readonly resolveTypeScript?: TypeScriptResolver;
 }
 export interface ClientGenerated {

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

@@ -2,7 +2,9 @@ import { mkdirSync, readFileSync, rmSync, 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 { resolveModuleStyle } from "../config/module-style.resolver.js";
 import { ContractTransportError } from "../contract/contract.fetcher.js";
+import { CLIENT_ENTRY_FILE } from "../emit/emitted-tree.interface.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";
@@ -26,6 +28,11 @@ export async function runClientInit(command, io) {
         detectedPackageManager: project.lockfile ??
             (userAgent?.split("/")[0] === "pnpm" ? "pnpm" : "npm"),
     });
+    const generateAt = path.resolve(io.cwd, answers.generateAt);
+    resolveModuleStyle({
+        generateAt,
+        entryFile: path.join(generateAt, CLIENT_ENTRY_FILE),
+    });
     const clientVersion = ownVersion();
     const plan = planClientInit({ project, answers, clientVersion });
     if (plan.conflicts.length > 0 && !command.yes) {

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

@@ -47,6 +47,16 @@ export function planClientInit(input) {
             replaced[at] = line;
         }
         add(".env", before, `${kept.join("\n")}\n`, `${replaced.join("\n")}\n`);
+        const ignore = project.read(".gitignore");
+        const ignored = (ignore ?? "")
+            .split("\n")
+            .some((line) => line.trim() === ".env");
+        if (!ignored) {
+            const appended = ignore === undefined || ignore === ""
+                ? ".env\n"
+                : `${ignore.endsWith("\n") ? ignore : `${ignore}\n`}.env\n`;
+            add(".gitignore", ignore, appended, appended);
+        }
     }
     const manifest = (replace) => {
         const parsed = JSON.parse(project.manifestText);

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

@@ -14,17 +14,19 @@ import type { ClientEmission } from "../emit/emitted-tree.interface.js";
  *   so a file without it would make the next run refuse. The imports are read
  *   lexically (`module-specifier.scanner.ts`), with no compiler — so a wrongly
  *   spelled import is refused even where the type check cannot run (TypeScript 7).
- * - **Types**, when the `typescript` optional peer resolves: a real program over
- *   the tree under a consumer's strictest plausible settings, in the project's
- *   module resolution and format (`compilerOptionsFor`). 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.
+ * - **Types**, when the `typescript` optional peer resolves FROM THE PROJECT in
+ *   its peer range: a real program over the tree under a consumer's strictest
+ *   plausible settings, in the project's module resolution and format
+ *   (`compilerOptionsFor`). 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.
  * - **Syntax**, when it does not — or when the `typescript` that resolves has no
  *   classic compiler API: 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, and never a refusal: the
- *   developer's own `tsc` still checks the tree when their project compiles.
+ *   (`node:module`'s `stripTypeScriptTypes`, its ExperimentalWarning held back),
+ *   with a loud warning of our own that the output was NOT type-checked. Degraded,
+ *   never skipped, and never a refusal: the developer's own `tsc` still checks the
+ *   tree when their project compiles.
  */
 /** The `typescript` module, as the validator uses it. */
 export type TypeScriptCompiler = typeof ts;
@@ -35,12 +37,23 @@ export type TypeScriptCompiler = typeof ts;
  */
 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.
+ * A resolver for `specifier`, looked up from `directory` the way Node looks up
+ * a package from a file there: its `node_modules`, then each parent's.
  */
-export declare function typeScriptResolverFor(specifier: string): TypeScriptResolver;
-/** The `typescript` this package's optional peer names. */
-export declare const resolveInstalledTypeScript: TypeScriptResolver;
+export declare function typeScriptResolverFor(specifier: string, directory: string): TypeScriptResolver;
+/**
+ * The `typescript` of the project that compiles the client, resolved from its
+ * `generateAt`. Never this package's own: run through `npx`, the generator is
+ * installed in npm's cache, where its optional peer never is — and the type check
+ * is a stand-in for the project's own `tsc`, so the project's compiler is the one
+ * that answers.
+ */
+export declare function projectTypeScriptResolver(generateAt: string): TypeScriptResolver;
+/**
+ * The lowest `typescript` the generator type-checks with: this package's
+ * optional peer range, `>=5.5.0` (`packaging-gate.spec.ts` holds the two equal).
+ */
+export declare const MINIMUM_TYPESCRIPT = "5.5.0";
 /** How deeply the tree was judged. */
 export type OutputCheck = "types" | "syntax" | "shape";
 export interface OutputAccepted {
@@ -70,6 +83,15 @@ export declare const SYNTAX_CHECK_UNAVAILABLE_WARNING: string;
  */
 export declare function typeScriptWithoutCompilerApiWarning(version: string, checked: "syntax" | "shape"): string;
 /**
- * Judges `directory`, which the caller has just filled with `tree`.
+ * The warning a run carries when the project's `typescript` is older than the
+ * peer range: its compiler API lacks options the check sets (`Bundler`
+ * resolution, `verbatimModuleSyntax`), so its verdict would not be the one a
+ * supported compiler gives.
+ */
+export declare function typeScriptBelowRangeWarning(version: string, checked: "syntax" | "shape"): string;
+/**
+ * Judges `directory`, which the caller has just filled with `tree`, with the
+ * `typescript` `resolveTypeScript` finds — the project's
+ * ({@link projectTypeScriptResolver}).
  */
-export declare function validateOutputTree(directory: string, emission: Pick<ClientEmission, "style" | "tree">, resolveTypeScript?: TypeScriptResolver): Promise<OutputValidation>;
+export declare function validateOutputTree(directory: string, emission: Pick<ClientEmission, "style" | "tree">, resolveTypeScript: TypeScriptResolver): Promise<OutputValidation>;

package/dist/output/output.validator.js

@@ -5,11 +5,11 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { carriesGeneratedOwnership } from "../emit/banner.emitter.js";
 import { scanModuleSpecifiers } from "../emit/module-specifier.scanner.js";
-export function typeScriptResolverFor(specifier) {
+export function typeScriptResolverFor(specifier, directory) {
     return async () => {
         let resolved;
         try {
-            resolved = createRequire(import.meta.url).resolve(specifier);
+            resolved = createRequire(path.join(directory, "package.json")).resolve(specifier);
         }
         catch (error) {
             if (isErrorWithCode(error, "MODULE_NOT_FOUND")) {
@@ -21,7 +21,25 @@ export function typeScriptResolverFor(specifier) {
         return loaded.default ?? loaded;
     };
 }
-export const resolveInstalledTypeScript = typeScriptResolverFor("typescript");
+export function projectTypeScriptResolver(generateAt) {
+    return typeScriptResolverFor("typescript", generateAt);
+}
+export const MINIMUM_TYPESCRIPT = "5.5.0";
+function meetsMinimum(version) {
+    const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    const minimum = MINIMUM_TYPESCRIPT.split(".").map(Number);
+    if (parts === null) {
+        return false;
+    }
+    for (let at = 0; at < 3; at += 1) {
+        const have = Number(parts[at + 1]);
+        const need = minimum[at];
+        if (have !== need) {
+            return have > need;
+        }
+    }
+    return true;
+}
 function hasClassicCompilerApi(compiler) {
     return (typeof compiler.createProgram ===
         "function");
@@ -41,14 +59,34 @@ export function typeScriptWithoutCompilerApiWarning(version, checked) {
         `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
         "Your project's own `tsc` checks it when it compiles; a `typescript` 5.5 to 6 restores the generator's own type check.");
 }
-export async function validateOutputTree(directory, emission, resolveTypeScript = resolveInstalledTypeScript) {
+export function typeScriptBelowRangeWarning(version, checked) {
+    return (`the installed \`typescript\` ${version} is older than ${MINIMUM_TYPESCRIPT}, the lowest @aventara/client supports, so the generated ` +
+        `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
+        `Upgrade the project's \`typescript\` to ${MINIMUM_TYPESCRIPT} or later to restore the type check.`);
+}
+function degradedWarning(compiler, checked) {
+    if (compiler === undefined) {
+        return checked === "syntax"
+            ? TYPESCRIPT_UNRESOLVED_WARNING
+            : SYNTAX_CHECK_UNAVAILABLE_WARNING;
+    }
+    if (!hasClassicCompilerApi(compiler)) {
+        return typeScriptWithoutCompilerApiWarning(versionOf(compiler), checked);
+    }
+    if (!meetsMinimum(versionOf(compiler))) {
+        return typeScriptBelowRangeWarning(versionOf(compiler), checked);
+    }
+    return undefined;
+}
+export async function validateOutputTree(directory, emission, resolveTypeScript) {
     const { tree, style } = emission;
     const shapeFindings = await shapeFindingsOf(directory, tree, style);
     if (shapeFindings.length > 0) {
         return { accepted: false, checked: "shape", findings: shapeFindings };
     }
     const compiler = await resolveTypeScript();
-    if (compiler !== undefined && hasClassicCompilerApi(compiler)) {
+    if (compiler !== undefined &&
+        degradedWarning(compiler, "syntax") === undefined) {
         const findings = typeFindingsOf(compiler, directory, tree, style);
         return findings.length > 0
             ? { accepted: false, checked: "types", findings }
@@ -59,11 +97,7 @@ export async function validateOutputTree(directory, emission, resolveTypeScript
         return {
             accepted: true,
             checked: "shape",
-            warnings: [
-                compiler === undefined
-                    ? SYNTAX_CHECK_UNAVAILABLE_WARNING
-                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "shape"),
-            ],
+            warnings: [degradedWarning(compiler, "shape")],
         };
     }
     const findings = syntaxFindingsOf(strip, tree);
@@ -72,11 +106,7 @@ export async function validateOutputTree(directory, emission, resolveTypeScript
         : {
             accepted: true,
             checked: "syntax",
-            warnings: [
-                compiler === undefined
-                    ? TYPESCRIPT_UNRESOLVED_WARNING
-                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "syntax"),
-            ],
+            warnings: [degradedWarning(compiler, "syntax")],
         };
 }
 async function shapeFindingsOf(directory, tree, style) {
@@ -225,7 +255,29 @@ function isInside(directory, file) {
 }
 function nodeTypeScriptParser() {
     const candidate = nodeModule.stripTypeScriptTypes;
-    return typeof candidate === "function" ? candidate : undefined;
+    if (typeof candidate !== "function") {
+        return undefined;
+    }
+    return (source) => {
+        const emitWarning = process.emitWarning;
+        process.emitWarning = function (warning, ...rest) {
+            const [kind] = rest;
+            const type = typeof kind === "string"
+                ? kind
+                : kind?.type;
+            if (type === "ExperimentalWarning" &&
+                String(warning).startsWith("stripTypeScriptTypes ")) {
+                return;
+            }
+            emitWarning.call(this, warning, ...rest);
+        };
+        try {
+            return candidate(source);
+        }
+        finally {
+            process.emitWarning = emitWarning;
+        }
+    };
 }
 function syntaxFindingsOf(strip, tree) {
     const decoder = new TextDecoder("utf-8");

package/dist/output/output.writer.d.ts

@@ -118,7 +118,10 @@ export interface ClientOutputWriteInput {
      * refused.
      */
     readonly overrideForeign?: readonly string[];
-    /** The `typescript` optional peer; the installed one by default. */
+    /**
+     * The `typescript` optional peer; by default the project's own, resolved from
+     * `generateAt`.
+     */
     readonly resolveTypeScript?: TypeScriptResolver;
     readonly fileSystem?: OutputFileSystem;
 }

package/dist/output/output.writer.js

@@ -3,7 +3,7 @@ import * as fsPromises from "node:fs/promises";
 import path from "node:path";
 import { carriesGeneratedOwnership, GENERATED_OWNERSHIP_HEAD_BYTES, } from "../emit/banner.emitter.js";
 import { CLIENT_ENTRY_FILES, GENERATED_DIRECTORY, LEGACY_CLIENT_ENTRY_FILES, } from "../emit/emitted-tree.interface.js";
-import { resolveInstalledTypeScript, validateOutputTree, } from "./output.validator.js";
+import { projectTypeScriptResolver, validateOutputTree, } from "./output.validator.js";
 export class OutputWriteError extends Error {
     stage;
     name = "OutputWriteError";
@@ -94,7 +94,7 @@ export async function writeClientOutput(input) {
                     await fs.writeFile(target, file.bytes);
                 }
             });
-            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? resolveInstalledTypeScript));
+            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? projectTypeScriptResolver(generateAt)));
             if (validation.accepted) {
                 validationWarnings = validation.warnings;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.2",
+  "version": "0.1.0-pilot.3",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -23,7 +23,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.2",
+    "@aventara/core": "0.1.0-pilot.3",
     "c12": "3.3.4",
     "get-tsconfig": "4.10.0"
   },
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "0.1.0-pilot.2",
+    "@aventara/testing": "0.1.0-pilot.3",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },