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

package/README.md

@@ -23,7 +23,7 @@ It asks — or takes from flags, or with `--yes` takes every default — four th
 | `--generate-at <dir>` | Where the client goes | `./src/api` |
 | `--package-manager <npm\|pnpm>` | | the lockfile's, else the launching one, else npm |
 
-It writes `framework.client.mts`, the variable into `.env` (only with a variable), `"avclient:generate": "avclient
+It writes `framework.client.ts` (or reuses the config the project already has), the variable into `.env` (only with a variable), `"avclient:generate": "avclient
 generate"` into the scripts and `@aventara/client` as an **exact** devDependency at its own version; runs the install
 (`--skip-install` prints it instead); and generates the client right away (`--skip-generate` to skip; a server that does
 not answer leaves the files and names `avclient generate`). Existing content that differs is listed and replaced only
@@ -32,7 +32,7 @@ committed: regenerating it needs a running server.
 
 ## Generating a client
 
-Install it as a dev dependency (or let `avclient init` do it), then add `framework.client.mts` to the directory you run
+Install it as a dev dependency (or let `avclient init` do it), then add `framework.client.ts` to the directory you run
 the generator from:
 
 ```ts
@@ -50,15 +50,34 @@ and run:
 npx avclient generate [--yes]
 ```
 
-**Why `.mts`.** `npm init -y` writes `"type": "commonjs"`, and under it Node reads a `.ts` file as CommonJS — the
-config's `import` would stop the run. A `.mts` file is an ES module in every project. A `framework.client.ts` written
-before 0.1.0-pilot.1 is still read; with both files present the generator refuses, and `avclient init` moves the old one
-to `framework.client.mts` (asking first if you edited it).
+**The config file** is loaded the way Prisma 7 loads `prisma.config.ts`: `framework.client.ts` — or `.mts`, `.cts`,
+`.js`, `.mjs`, `.cjs` — in ES module or CommonJS syntax, whatever your `package.json`'s `"type"`. A
+`framework.client.mts` written by 0.1.0-pilot.1 keeps working, and `avclient init` reuses it. Two config files in one
+directory are refused, naming both.
 
 - **`entrypoint`** is the deployment's framework entrypoint: origin plus mount path, one absolute `http(s)` URL. It
   may not carry credentials — the platform's `fetch` refuses such a URL, and the entrypoint ships inside the client.
 - **`generateAt`** is a directory you may share with your own files. The generator owns exactly two entries in it —
   `AvClient.ts` and `generated/` — and never reads, moves or removes anything else there.
+
+### Your tsconfig decides how the client is written
+
+The client is TypeScript source that **your own toolchain compiles**, like your own files — `tsc`, Next.js (Turbopack or
+webpack), Vite, `tsx`, Node's type stripping. Its modules import each other the way your project imports its files,
+read from your `tsconfig.json` (the nearest one above `generateAt`, `extends` included) by Prisma 7's rules:
+
+| Your tsconfig | The client's own imports | You import it as |
+|---|---|---|
+| `allowImportingTsExtensions` or `rewriteRelativeImportExtensions` (Vite's react-ts template, Node's type stripping) | `./generated/client.ts` | `./api/AvClient.ts` |
+| `moduleResolution: "bundler"` (Next.js) or `module: "commonjs"` | `./generated/client` | `./api/AvClient` |
+| anything else — `module: "nodenext"`/`"node16"` (NestJS 12) | `./generated/client.js` | `./api/AvClient.js` (ES module) or `./api/AvClient` (CommonJS) |
+
+Under `nodenext`, the nearest `package.json`'s `"type"` decides whether the client is checked as an ES module or as
+CommonJS. Vite's `tsconfig.json`, which only lists `references`, defers to the referenced project that includes the
+client (`tsconfig.app.json`). The validate step type-checks the client in your project's resolution and module format.
+
+A project with no `tsconfig.json` is refused: the generated client is TypeScript, and JavaScript projects are not
+supported yet.
 - **The `.env` cascade** is read from the current directory before the config is evaluated, highest precedence first:
   the process environment, `.env.<mode>.local`, `.env.<mode>`, `.env.local`, `.env`; `mode` is `NODE_ENV`, or
   `development`. The config reads it through `env("NAME")`; `process.env` is never written.
@@ -72,8 +91,9 @@ to `framework.client.mts` (asking first if you edited it).
 - **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.
@@ -85,7 +105,7 @@ to `framework.client.mts` (asking first if you edited it).
 ## Calling the API
 
 ```ts
-import avClient, { AvClient, type User, type UserWhere } from "./api/AvClient";
+import avClient, { AvClient, type User, type UserWhere } from "./api/AvClient"; // as you import your own files
 
 const where: UserWhere = { email: { equals: "ada@example.com" } };
 const users = await avClient.User.find.many({ where, select: ["id", "email", { posts: { select: ["$count"] } }] });
@@ -229,6 +249,21 @@ program, the 500,000 line near 150 Resources.
   `Aventara-Request-Id`) may still change before the first stable release. It is one constant in the generated
   `generated/runtime/transport.ts`; regenerating picks up a change.
 
+## Known issues
+
+- **The generator read the wrong `tsconfig.json`.** In a monorepo or a non-standard layout, the nearest
+  `tsconfig.json` above `generateAt` may not be the one your project compiles the client with, and the client's
+  imports or module format then do not match your compiler (`Cannot find module './generated/client.js'`, an
+  extension your bundler will not resolve). Name the right one in `framework.client.ts`, relative to the config file:
+
+  ```ts
+  export default defineClientConfig({
+  	entrypoint: env("AVENTARA_API_URL"),
+  	generateAt: "./src/api",
+  	tsconfigFile: "./tsconfig.app.json",
+  });
+  ```
+
 ## License
 
 PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not

package/dist/avclient.bin.js

@@ -1,15 +1,5 @@
 #!/usr/bin/env node
 import { refuseUnsupportedNode } from "./node-version.guard.js";
-/**
- * `avclient`'s entry, what the manifest's `bin` names (F-855). It always runs — no
- * `import.meta.main` — and checks this Node against the package's
- * `engines.node` before it loads anything else: the program is imported only
- * once the guard admits this Node, so an older Node meets one sentence and exit
- * 1, never a silent exit 0 or a parse error from a module it cannot run.
- *
- * A promise chain rather than a top-level `await`, which Node 12 cannot parse:
- * this file is read by the Nodes the package does not support.
- */
 if (!refuseUnsupportedNode("avclient", new URL("../package.json", import.meta.url))) {
     void import("./cli.js").then((program) => program.runFromProcess());
 }

package/dist/cli/command.parser.d.ts

@@ -1,16 +1,16 @@
 /**
- * The `avclient` command line: one command, its one flag, and help. Everything
- * the generator needs is in `framework.client.ts` and the `.env` cascade (§15.2),
- * so `generate` takes no flag that would duplicate a config member — a second
- * source of the same fact. `--yes` is not one: it answers the one question the
- * generator asks (architect, 2026-10-04).
+ * The `avclient` command line: one command, its one flag, and help. Everything the
+ * generator needs is in `framework.client.ts` and the `.env` cascade, so
+ * `generate` takes no flag that would duplicate a config member — a second source
+ * of the same fact. `--yes` is not one: it answers the one question the generator
+ * asks.
  */
-export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.mts (or framework.client.ts) in the\n                              current directory, fetch <entrypoint>/_contract, and\n                              write AvClient.ts and generated/ into its generateAt\n                              directory.\n  avclient init [options]     Set up this frontend: write framework.client.mts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.mts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.mts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
+export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .js, .mjs, .cjs, .mts,\n                              .cts) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
 /** `avclient generate --help` (pilot.1): that command's usage alone. */
-export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.mts (or framework.client.ts) in the current directory, fetch\n<entrypoint>/_contract, and write AvClient.ts and generated/ into its generateAt\ndirectory.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
+export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .js, .mjs, .cjs, .mts, .cts) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
 /** `avclient init --help` (pilot.1): that command's usage alone. */
-export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.mts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.mts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
-/** `avclient init`'s command line (R4, Q16 rows 12–15). */
+export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
+/** `avclient init`'s command line. */
 export type ClientInitCommand = {
     readonly command: "init";
     readonly given: Readonly<Partial<Record<"entrypoint" | "envVar" | "generateAt" | "packageManager", string>>>;
@@ -25,6 +25,8 @@ export type CliCommand =
 {
     readonly command: "help";
     readonly topic?: "generate" | "init";
+} | {
+    readonly command: "version";
 } | {
     readonly command: "generate";
     readonly yes: boolean;
@@ -33,5 +35,8 @@ export type CliCommand =
 export declare class CliCommandError extends Error {
     readonly name = "CliCommandError";
 }
-/** @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `--help` or `-h`. */
+/**
+ * @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `init …`,
+ *   `--help`/`-h` or `--version`/`-v`.
+ */
 export declare function parseCliCommand(argv: readonly string[]): CliCommand;

package/dist/cli/command.parser.js

@@ -1,18 +1,12 @@
-import { CLIENT_CONFIG_FILE, LEGACY_CLIENT_CONFIG_FILE, } from "../config/config.loader.js";
-/**
- * The `avclient` command line: one command, its one flag, and help. Everything
- * the generator needs is in `framework.client.ts` and the `.env` cascade (§15.2),
- * so `generate` takes no flag that would duplicate a config member — a second
- * source of the same fact. `--yes` is not one: it answers the one question the
- * generator asks (architect, 2026-10-04).
- */
+import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
 export const USAGE = `avclient — generate a typed Aventara client from a deployed ClientContract.
 
 Usage:
-  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or ${LEGACY_CLIENT_CONFIG_FILE}) in the
-                              current directory, fetch <entrypoint>/_contract, and
-                              write AvClient.ts and generated/ into its generateAt
-                              directory.
+  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts,
+                              .cts) in the current directory, fetch
+                              <entrypoint>/_contract, and write AvClient.ts and
+                              generated/ into its generateAt directory, its imports
+                              spelled as the project's tsconfig.json says.
   avclient init [options]     Set up this frontend: write ${CLIENT_CONFIG_FILE}, the
                               .env entry, the avclient:generate script and the
                               @aventara/client devDependency; install; generate.
@@ -26,6 +20,7 @@ Usage:
       -y, --yes               Accept every default, and replace differing content.
   avclient --help             Print this and exit 0.
   avclient <command> --help   Print that command's usage and exit 0.
+  avclient --version, -v      Print this generator's version and exit 0.
 
 Options:
   -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
@@ -42,12 +37,11 @@ current directory, highest precedence first: the process environment,
 .env.<mode>.local, .env.<mode>, .env.local, .env — where mode is NODE_ENV, or
 "development".
 `;
-/** `avclient generate --help` (pilot.1): that command's usage alone. */
 export const GENERATE_USAGE = `Usage: avclient generate [--yes]
 
-Read ${CLIENT_CONFIG_FILE} (or ${LEGACY_CLIENT_CONFIG_FILE}) in the current directory, fetch
-<entrypoint>/_contract, and write AvClient.ts and generated/ into its generateAt
-directory.
+Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts, .cts) in the current directory,
+fetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its
+generateAt directory, its imports spelled as the project's tsconfig.json says.
 
 Options:
   -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
@@ -62,7 +56,6 @@ Before the config is evaluated, the .env cascade is read from the current
 directory, highest precedence first: the process environment, .env.<mode>.local,
 .env.<mode>, .env.local, .env — where mode is NODE_ENV, or "development".
 `;
-/** `avclient init --help` (pilot.1): that command's usage alone. */
 export const INIT_USAGE = `Usage: avclient init [options]
 
 Set up this frontend: write ${CLIENT_CONFIG_FILE}, the .env entry, the avclient:generate
@@ -81,11 +74,9 @@ Options:
 On a terminal every unanswered question is asked; anywhere else, pass its flag
 or --yes, or the run stops before writing anything.
 `;
-/** The command line cannot be understood. A refusal: one sentence, exit 1. */
 export class CliCommandError extends Error {
     name = "CliCommandError";
 }
-/** @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `--help` or `-h`. */
 export function parseCliCommand(argv) {
     const [command, ...rest] = argv;
     const help = "run `avclient --help` for usage.";
@@ -95,6 +86,9 @@ export function parseCliCommand(argv) {
     if (command === "--help" || command === "-h") {
         return { command: "help" };
     }
+    if (command === "--version" || command === "-v") {
+        return { command: "version" };
+    }
     if ((command === "init" || command === "generate") &&
         (rest.includes("--help") || rest.includes("-h"))) {
         return { command: "help", topic: command };

package/dist/cli/generate.command.js

@@ -1,11 +1,5 @@
 import { generateClient } from "../generate.js";
 import { FOREIGN_CONTENT_QUESTION, renderForeignContentCancellation, renderForeignContentWarning, renderGenerationSuccess, renderUpToDate, } from "./generation-success.renderer.js";
-/**
- * `avclient generate` — the generation, the generateAt rule's question, and the
- * report. Shared by `init`, which generates once the project is set up.
- *
- * @throws whatever the generation raises; the caller renders it.
- */
 export async function runGenerate(io, yes) {
     const outcome = await generateClient({
         directory: io.cwd,

package/dist/cli/generation-failure.renderer.js

@@ -9,18 +9,6 @@ import { ClientProjectRefusedError } from "../init/client-project.inspector.js";
 import { OutputWriteError, warningsRaisedBeforeDefect, } from "../output/output.writer.js";
 import { CliCommandError } from "./command.parser.js";
 import { renderWarningLines } from "./warning.renderer.js";
-/**
- * How a failed generation reaches the person running it (M3, the adapter CLI's
- * precedent): a refusal is a sentence and a non-zero exit code, never a stack — a
- * stack printed over it buries the sentence that says what to do. Anything else is
- * a defect and keeps its stack.
- *
- * A refusal that stopped a run part-way carries what the run said before it —
- * a crash recovered, a name renamed — and those lines come first, in the order a
- * success prints them, so nothing the run did goes unreported because it failed.
- * A defect's come first too, then its stack, whole.
- */
-/** Every error the generator raises on purpose. One list, read by `instanceof`. */
 const REFUSALS = [
     CliCommandError,
     ClientConfigError,
@@ -39,8 +27,6 @@ export function renderGenerationFailure(error) {
     if (REFUSALS.some((refusal) => error instanceof refusal)) {
         const carried = error instanceof OutputWriteError ? error.warnings : [];
         return {
-            // A refused contract carries its own (plan §7); the other refusals are 1,
-            // the adapter CLI's precedent (M3).
             exitCode: error instanceof ContractProtocolError ? error.exitCode : 1,
             text: `${renderWarningLines(carried)}avclient: ${error.message}\n`,
         };

package/dist/cli/generation-success.renderer.d.ts

@@ -13,7 +13,10 @@ export interface GenerationSuccessReport {
     readonly stderr: string;
 }
 export declare function renderGenerationSuccess(result: ClientGenerated): GenerationSuccessReport;
-/** Nothing written (Phase 12-rest Q6): the deployment's ClientContract and these bytes are what is there. */
+/**
+ * Nothing written: the deployment's ClientContract and these bytes are what is
+ * there.
+ */
 export declare function renderUpToDate(result: ClientUpToDate): GenerationSuccessReport;
 /**
  * What the person running the generator is told before being asked: every path

package/dist/cli/generation-success.renderer.js

@@ -10,32 +10,19 @@ export function renderGenerationSuccess(result) {
         stderr: renderWarningLines(result.warnings),
     };
 }
-/** Nothing written (Phase 12-rest Q6): the deployment's ClientContract and these bytes are what is there. */
 export function renderUpToDate(result) {
     return {
         stdout: `avclient: up to date: ${result.generateAt} already holds this deployment's client; nothing was written.\n`,
         stderr: renderWarningLines(result.warnings),
     };
 }
-/**
- * What the person running the generator is told before being asked: every path
- * in `AvClient.ts` and `generated/` that the generator did not produce, which
- * proceeding overwrites or removes.
- */
 export function renderForeignContentWarning(found) {
     return (`${WARNING_LINE_PREFIX}${found.foreign.join(", ")} in ${found.generateAt} ` +
         `${found.foreign.length === 1 ? "was" : "were"} not generated by @aventara/client, ` +
         "and generating will overwrite or remove " +
         `${found.foreign.length === 1 ? "it" : "them"}.\n`);
 }
-/** The question; answered yes, generation proceeds. */
 export const FOREIGN_CONTENT_QUESTION = "avclient: overwrite them and generate? [y/N] ";
-/**
- * Nobody confirmed: nothing was touched. One sentence naming what to sort out —
- * and, where nobody could have been asked, the flag that answers yes — after
- * every warning the run raised before it stopped, so a cancelled run's renames
- * are reported as a refused one's are.
- */
 export function renderForeignContentCancellation(found, asked) {
     const them = found.foreign.length === 1 ? "it" : "them";
     return `${renderWarningLines(found.warnings)}${asked

package/dist/cli/terminal.prompter.d.ts

@@ -2,8 +2,7 @@
  * The terminal's questions — `generate`'s yes/no and `init`'s wizard — over one
  * `node:readline` interface whose lines are **queued**: a line typed (or piped
  * into a pseudo-terminal) before its question is kept for it, where a fresh
- * interface per question, or `readline/promises`' `question`, drops it (measured
- * in `@aventara/cli`'s S5; the same rule there, P7).
+ * interface per question, or `readline/promises`' `question`, drops it.
  */
 export type TerminalPrompter = {
     readonly ask: (prompt: string) => Promise<string>;

package/dist/cli/warning.renderer.d.ts

@@ -1,8 +1,8 @@
 /**
  * How one warning reaches the person running the generator: its own stderr line,
  * under the CLI's one prefix. Warnings carry no prefix of their own, so the line
- * says "warning" once (S7b's report: the degraded check used to say it twice).
- * Shared by a success and a refusal, so a warning reads the same either way.
+ * says "warning" once. Shared by a success and a refusal, so a warning reads the
+ * same either way.
  */
 /** The prefix every warning line opens with. */
 export declare const WARNING_LINE_PREFIX = "avclient: warning: ";

package/dist/cli/warning.renderer.js

@@ -1,12 +1,4 @@
-/**
- * How one warning reaches the person running the generator: its own stderr line,
- * under the CLI's one prefix. Warnings carry no prefix of their own, so the line
- * says "warning" once (S7b's report: the degraded check used to say it twice).
- * Shared by a success and a refusal, so a warning reads the same either way.
- */
-/** The prefix every warning line opens with. */
 export const WARNING_LINE_PREFIX = "avclient: warning: ";
-/** One newline-terminated line per warning, in the order given; empty for none. */
 export function renderWarningLines(warnings) {
     return warnings
         .map((warning) => `${WARNING_LINE_PREFIX}${warning}\n`)

package/dist/cli.d.ts

@@ -1,22 +1,14 @@
 import { type CliIo } from "./cli/generate.command.js";
 export type { CliIo } from "./cli/generate.command.js";
 /**
- * `avclient` — the generator's bin (`avclient generate`), S7b.
- *
- * It parses the command line, runs §15.3's pipeline (`generate.ts`) in the
- * current directory, and owns the terminal: the success line goes to stdout,
- * every warning the run returned to stderr in the run's order, and a failure
- * through the refusal renderer — a refusal is one sentence and exit 1 with no
- * stack (M3), anything else is a defect and keeps its stack.
- *
- * It is also the one place that ASKS (architect, 2026-10-04): when content the
- * generator did not produce stands in `AvClient.ts` or `generated/`, the paths
- * are listed and the person is asked whether to overwrite them. `--yes` answers
- * for them. Where nobody can answer — stdin is not a terminal — it never asks
- * and never overrides: it refuses, naming `--yes`. Cancelled or refused, nothing
- * was touched, the run's warnings are printed before the sentence, and the exit
- * code is 1. A killed run's leftovers are looked at before the question, so the
- * answer — and `--yes` — covers what it hid as well.
+ * It is also the one place that ASKS: when content the generator did not produce
+ * stands in `AvClient.ts` or `generated/`, the paths are listed and the person is
+ * asked whether to overwrite them. `--yes` answers for them. Where nobody can
+ * answer — stdin is not a terminal — it never asks and never overrides: it
+ * refuses, naming `--yes`. Cancelled or refused, nothing was touched, the run's
+ * warnings are printed before the sentence, and the exit code is 1. A killed run's
+ * leftovers are looked at before the question, so the answer — and `--yes` —
+ * covers what it hid as well.
  */
 /** Runs one command line; resolves to the exit code. Never throws. */
 export declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;

package/dist/cli.js

@@ -2,27 +2,9 @@ import { GENERATE_USAGE, INIT_USAGE, parseCliCommand, USAGE, } from "./cli/comma
 import { runGenerate } from "./cli/generate.command.js";
 import { renderGenerationFailure } from "./cli/generation-failure.renderer.js";
 import { createTerminalPrompter } from "./cli/terminal.prompter.js";
+import { AVENTARA_CLIENT_GENERATOR_VERSION } from "./index.js";
 import { runClientInit } from "./init/client-init.orchestrator.js";
 import { runCommand } from "./init/command.runner.js";
-/**
- * `avclient` — the generator's bin (`avclient generate`), S7b.
- *
- * It parses the command line, runs §15.3's pipeline (`generate.ts`) in the
- * current directory, and owns the terminal: the success line goes to stdout,
- * every warning the run returned to stderr in the run's order, and a failure
- * through the refusal renderer — a refusal is one sentence and exit 1 with no
- * stack (M3), anything else is a defect and keeps its stack.
- *
- * It is also the one place that ASKS (architect, 2026-10-04): when content the
- * generator did not produce stands in `AvClient.ts` or `generated/`, the paths
- * are listed and the person is asked whether to overwrite them. `--yes` answers
- * for them. Where nobody can answer — stdin is not a terminal — it never asks
- * and never overrides: it refuses, naming `--yes`. Cancelled or refused, nothing
- * was touched, the run's warnings are printed before the sentence, and the exit
- * code is 1. A killed run's leftovers are looked at before the question, so the
- * answer — and `--yes` — covers what it hid as well.
- */
-/** Runs one command line; resolves to the exit code. Never throws. */
 export async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
@@ -34,6 +16,10 @@ export async function runCli(argv, io) {
                     : GENERATE_USAGE);
             return 0;
         }
+        if (command.command === "version") {
+            io.stdout(`${AVENTARA_CLIENT_GENERATOR_VERSION}\n`);
+            return 0;
+        }
         if (command.command === "init") {
             return await runClientInit(command, io);
         }
@@ -45,12 +31,6 @@ export async function runCli(argv, io) {
         return failure.exitCode;
     }
 }
-/**
- * Runs `avclient` over this process — its arguments, its terminal, its exit
- * code. Called by the bin's entry (`avclient.bin.ts`) once the Node guard has
- * admitted this Node; importing this module runs nothing, which is what lets
- * `runCli` be tested in process.
- */
 export async function runFromProcess() {
     const terminal = createTerminalPrompter();
     try {

package/dist/config/client-config.interface.d.ts

@@ -1,15 +1,11 @@
 /**
- * The generator's configuration, in its two states (plan §7, group 1).
+ * The generator's configuration, in its two states.
  *
  * `ClientConfigInput` is what a `framework.client.ts` default-exports through
- * `defineClientConfig`. It is passive data: an environment variable appears as
- * an `EnvReference`, a NAME to look up, so the file can be evaluated without the
+ * `defineClientConfig`. It is passive data: an environment variable appears as an
+ * `EnvReference`, a NAME to look up, so the file can be evaluated without the
  * environment having been loaded into the global and resolution stays a pure
  * function of the input and an `EnvRecord`.
- *
- * `ResolvedClientConfig` is what later slices consume: the one §15.2 entrypoint
- * split into the deployment it addresses and its canonical mount path,
- * `generateAt` made absolute, and the mode the cascade resolved under.
  */
 /** A deferred read of one environment variable from the resolved cascade. */
 export interface EnvReference {
@@ -19,32 +15,36 @@ export interface EnvReference {
 /** A value written literally, or read from the resolved environment. */
 export type ConfigValue = string | EnvReference;
 export interface ClientConfigInput {
-    /** The full deployed framework entrypoint: origin plus mount path (§15.2). */
+    /** The full deployed framework entrypoint: origin plus mount path. */
     readonly entrypoint: ConfigValue;
     /**
      * The directory the client is generated into, relative to the config file's
-     * directory (architect, 2026-10-04). It is SHARED: the generator owns only
-     * `AvClient.ts` and `generated/` in it, and never touches anything else there.
-     * Named `generateAt`, not §15.2's `output`, by the architect's decision.
+     * directory. It is SHARED: the generator owns only `AvClient.ts` and `generated/`
+     * in it, and never touches anything else there.
      */
     readonly generateAt: ConfigValue;
+    /**
+     * The `tsconfig.json` the generated client is written for, relative to the
+     * config file's directory — only for a layout the discovery gets wrong (a
+     * monorepo, a non-standard name). Absent, the nearest `tsconfig.json` above
+     * `generateAt` (`tsconfig.locator.ts`).
+     */
+    readonly tsconfigFile?: string;
 }
 /** A filesystem path known to be absolute. */
 export type AbsolutePath = string & {
     readonly __absolutePath: true;
 };
 /**
- * A mount path in F-822's canonical form: `""` at the root, otherwise
- * `/seg(/seg)*` — one leading slash, no trailing slash, no empty segment. Root is
- * the empty string, not `"/"`, so every route is `path + "/<route>"` with no
- * special case. Only resolution makes one.
+ * Root is the empty string, not `"/"`, so every route is `path + "/<route>"` with
+ * no special case. Only resolution makes one.
  */
 export type EntrypointPath = ("" | `/${string}`) & {
     readonly __entrypointPath: true;
 };
 /**
  * The deployed entrypoint, normalised once at resolution so every consumer reads
- * one canonical form (F-822). Joining a route onto it is concatenation.
+ * one canonical form. Joining a route onto it is concatenation.
  */
 export interface ClientEntrypoint {
     /**
@@ -58,5 +58,7 @@ export interface ResolvedClientConfig {
     readonly entrypoint: ClientEntrypoint;
     /** `generateAt`, made absolute. */
     readonly generateAt: AbsolutePath;
+    /** `tsconfigFile`, made absolute; absent when the config names none. */
+    readonly tsconfigFile?: AbsolutePath;
     readonly mode: string;
 }

package/dist/config/client-config.interface.js

@@ -1,14 +1 @@
-/**
- * The generator's configuration, in its two states (plan §7, group 1).
- *
- * `ClientConfigInput` is what a `framework.client.ts` default-exports through
- * `defineClientConfig`. It is passive data: an environment variable appears as
- * an `EnvReference`, a NAME to look up, so the file can be evaluated without the
- * environment having been loaded into the global and resolution stays a pure
- * function of the input and an `EnvRecord`.
- *
- * `ResolvedClientConfig` is what later slices consume: the one §15.2 entrypoint
- * split into the deployment it addresses and its canonical mount path,
- * `generateAt` made absolute, and the mode the cascade resolved under.
- */
 export {};