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

package/README.md

@@ -11,7 +11,7 @@ server by construction, and that agreement is gated over both pilot schemas.
 ## Setting up a frontend: `avclient init`
 
 ```bash
-npx @aventara/client init      # in your frontend project
+npx @aventara/client@pilot init      # in your frontend project; pnpm: pnpm dlx @aventara/client@pilot init
 ```
 
 It asks — or takes from flags, or with `--yes` takes every default — four things, and writes the setup:
@@ -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.ts`, the variable into `.env` (only with a variable), `"avclient:generate": "avclient
+It writes `framework.client.mts`, 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.ts` to the directory you run
+Install it as a dev dependency (or let `avclient init` do it), then add `framework.client.mts` to the directory you run
 the generator from:
 
 ```ts
@@ -50,6 +50,11 @@ 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).
+
 - **`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 —
@@ -67,9 +72,11 @@ npx avclient generate [--yes]
 - **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` is installed, under a consumer's
-  strictest plausible settings and with nothing outside the tree resolvable. Without it, the check degrades to a parse
-  with Node's own TypeScript parser, and says so loudly — it is never skipped.
+- **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
+  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.
 - **Determinism.** Two runs over one ClientContract write the same bytes; deleting the client and regenerating it gives
   the same bytes. Nothing volatile — no timestamp, generator version, host or path — is emitted.
 - **Failure is a sentence.** A refusal is one line and exit code 1, with no stack; anything the run warned about before
@@ -165,21 +172,21 @@ chose. The `.d.ts` files are core's copied declarations under `generated/derivat
 - `generated/enums.ts` — each enum as a union type and a same-named `as const` object.
 - `generated/metadata.ts` — the ClientContract hash and protocol version the client is bound to, and the entrypoint it
   was generated from, its default deployment (an entrypoint carrying credentials is refused at resolution).
-- `generated/runtime/codec.ts` — the nine scalars' wire codecs (§6.2), and the request-body serializer.
+- `generated/runtime/codec.ts` — the nine scalars' wire codecs, and the request-body serializer.
 - `generated/runtime/decimal.ts` — the framework's `Decimal`: a constructor, `toString` and `toJSON`.
 - `generated/runtime/descriptor.ts` — what the runtime reads of the contract: the result fields it revives and the
   relations it follows (the decode table), and the advertised operations.
 - `generated/runtime/errors.ts` — `FrameworkError`, its subclasses by code class (`AuthError`, `ConflictError`,
   `ContractMismatchError`, `InternalError`, `NotFoundError`, `ProtocolError`, `ValidationError`), `TransportError`, and
   the code unions, emitted from core's code arrays rather than retyped.
-- `generated/runtime/fingerprint.ts` — the operation fingerprint of §14.4 (RFC 8785 canonical JSON, SHA-256,
+- `generated/runtime/fingerprint.ts` — the operation fingerprint (RFC 8785 canonical JSON, SHA-256,
   base64url), dependency-free and pinned to core's; emitted only when transactions are `interactive`.
 - `generated/runtime/transaction.ts` — `avClient.tx`'s deferred handles and `avClient.transaction`'s plan assembly,
   refusals and one POST to `/_transactions`; emitted only when transactions are `interactive`.
-- `generated/runtime/transport.ts` — one POST per operation with the identity headers, and the response read by §13.5's
-  rule; arguments encoded by value, results revived by the decode table, the platform's own `fetch` type accepted.
+- `generated/runtime/transport.ts` — one POST per operation with the identity headers, and the response read by the
+  protocol's rule; arguments encoded by value, results revived by the decode table, the platform's own `fetch` type accepted.
   Its `execute` primitive is module-private: no public file re-exports it; `AvClient`'s methods wrap it.
-- `generated/types.d.ts` — §15.6's named Resource types, as a declaration file (`User`, `UserWhere`,
+- `generated/types.d.ts` — the named Resource types, as a declaration file (`User`, `UserWhere`,
   `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`, `UserSelect`, `UserInclude`), each only when
   its operation is advertised.
 
@@ -198,10 +205,9 @@ A deployment whose ClientContract differs refuses the request with `A2005`, whic
 
 The hash covers everything the deployment advertises, not only its schema: two deployments of one schema can advertise
 different ClientContracts, and a client generated against one is refused by the other. Whatever the cause, the remedy
-is the same — **generate against the deployment the client will call, and regenerate when it changes.** (This closes
-the generator's half of follow-up row F-801, by the architect's decision to state the binding rather than its causes.)
+is the same — **generate against the deployment the client will call, and regenerate when it changes.**
 
-That holds for an operation the deployment **no longer advertises**, too (F-716, closed): the server checks the client's
+That holds for an operation the deployment **no longer advertises**, too: the server checks the client's
 identity before it routes, so a stale client calling a removed operation also hears `A2005` and throws
 `ContractMismatchError`. A response that is not a framework envelope at all — a host's own 404 for a path it does not
 mount — is a `TransportError`, which names no remedy: nothing in it says the client is stale.
@@ -209,59 +215,19 @@ mount — is a `TransportError`, which names no remedy: nothing in it says the c
 The embedded entrypoint is a **default**: `new AvClient({ entrypoint })` may point a client at another deployment, and
 doing so re-binds nothing — the ClientContract hash still decides whether that deployment accepts the client.
 
-## Phase 12's deliverables
-
-| Phase 12 deliverable | Status |
-|---|---|
-| `avclient generate` CLI (bin `avclient`, R3) | Delivered, with `--yes` and the foreign-content question. |
-| `.env` loading | Delivered: the five-file cascade, no dependency. |
-| Deployed `/_contract` fetch | Delivered: conditional on the output it finds (`If-None-Match`, `304` → "up to date" only when re-emission is byte-identical). |
-| Protocol compatibility validation | Delivered: the supported-version set, and the hash recomputed with core's function and compared — never trusted as delivered. |
-| ClientContract structure validation | Delivered, by core's `validateClientContractStructure`. |
-| Deterministic named type generation | Delivered: §15.6's named types as aliases over core's derivation, the rename ladder keeping every derived name free. |
-| Resource operation methods, the client class and the default singleton | Delivered: `AvClient` and `avClient`, one method per advertised operation (P4: the runtime's list equals the type grammar's keys over both pilots). |
-| Projection inference | Delivered: core's own call grammar — the caller's `select`/`include` literal inferred. Facts the capability model cannot state yet are unstated on both sides alike: **F-809**, **F-812**, **F-813**, **F-818** no longer block the client. |
-| Deferred transaction builder | Delivered, iff the ClientContract advertises `interactive`; core's Contract-derived `Operation<T>` (**F-701**, closed) types each handle. |
-| Transport runtime emitted into output | Delivered, including the stale-client mechanism (**F-716**, closed: server-side). |
-| Scalar codecs | Delivered: all nine scalars of §6.2, encoded by value, revived by a decode table. |
-| Typed framework and transport errors | Delivered. |
-| Contract version and hash embedded into output | Delivered (`generated/metadata.ts`), with the resolved entrypoint as the default (§15.2). |
-| Atomic temp → validate → replace | Delivered. |
-| Generated-file ownership banners | Delivered. |
-| No runtime import from `@aventara/client` | Delivered, and gated: nothing outside the tree, `@aventara/core` included. |
-| Availability readers | Read through core's `isOperationVariantAvailable` (**F-820**, closed). Not hand-rolled here. |
-
-### Phase 12's exit gate
-
-- *"Delete the generated client, regenerate it from the same contract, and obtain equivalent output"* — **passed, and
-  strengthened to byte-identical**, through the packed bin against a real HTTP server, with the callable surface, core's
-  derivation and the transaction runtime in the tree.
-- *"A generated test application compiles without depending on server source types"* — **passed, and run**: a
-  throwaway project where neither `@aventara/core` nor `@aventara/client` can resolve generates its client from a
-  running host, compiles a program against it with `tsc`, and runs it — scalars revived, an enum, a `$count` envelope, a
-  transaction with a `$ref`, a `NotFoundError`, an abort, and `ContractMismatchError` after the host's contract changes.
-
-### Type-checking cost in a consumer
+## Type-checking cost in a consumer
 
 A consumer pays for the calls it type-checks, not for the schema — under `skipLibCheck: true` (the common default),
 where the named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read:
 about 33,000 instantiations for a 50-Resource schema and seven typed calls. Under `skipLibCheck: false` every named type
-is resolved where it is declared, about 2,900 instantiations per Resource (**F-839**): about 204,000 for the same
+is resolved where it is declared, about 2,900 instantiations per Resource: about 204,000 for the same
 program, the 500,000 line near 150 Resources.
 
-### Known seams, to be closed when their owners land
-
-- **The envelope check** — "did a framework envelope arrive?" — is the emitted transport's own, pinned to core's
-  `AvProtocol.isOperationResponse` over every corpus row.
-- **Specification edits owed to the specification owner** are listed in follow-up row F-838: the names (`avClient`,
-  `AvClient`, `CallOptions`), the emitted tree's layout, the forms map, credentials, "up to date".
-- **The end-to-end and ownership gates read a gitignored file by path:** the SQLite pilot's discovery artifact,
-  `packages/prisma7-adapter/generated/artifact/sqlite.artifact.ts`, which exists only after the adapter's generate step
-  has run (`pnpm typecheck` runs it). This package takes no dependency on the adapter.
-- **The `Aventara` wire prefix** of the identity headers must be frozen before the first external release (§12.4). It is
-  one constant in `generated/runtime/transport.ts`, so the freeze is a one-line change.
-- **A tarball from `npm pack` is not a releasable artifact** while `@aventara/core` is spelled `workspace:*`, and does
-  not install outside this workspace (F-808, Phase 13). Do not validate a pilot against one.
+## Before 1.0
+
+- **The `Aventara` wire prefix** of the protocol's headers (`Aventara-Protocol-Version`, `Aventara-Contract-Hash`,
+  `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.
 
 ## License
 

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

@@ -5,7 +5,11 @@
  * source of the same fact. `--yes` is not one: it answers the one question the
  * generator asks (architect, 2026-10-04).
  */
-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 in the current directory,\n                              fetch <entrypoint>/_contract, and write AvClient.ts\n                              and generated/ into its generateAt directory.\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\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";
+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";
+/** `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";
+/** `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 type ClientInitCommand = {
     readonly command: "init";
@@ -16,8 +20,11 @@ export type ClientInitCommand = {
     readonly yes: boolean;
 };
 /** What the command line asked for. */
-export type CliCommand = {
+export type CliCommand = 
+/** `--help`; with `topic`, `avclient <topic> --help` (pilot.1). */
+{
     readonly command: "help";
+    readonly topic?: "generate" | "init";
 } | {
     readonly command: "generate";
     readonly yes: boolean;

package/dist/cli/command.parser.js

@@ -1,4 +1,4 @@
-import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+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),
@@ -9,9 +9,10 @@ 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} 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 ${LEGACY_CLIENT_CONFIG_FILE}) in the
+                              current directory, fetch <entrypoint>/_contract, and
+                              write AvClient.ts and generated/ into its generateAt
+                              directory.
   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.
@@ -24,6 +25,7 @@ Usage:
       --skip-generate         Do not generate now.
       -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.
 
 Options:
   -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
@@ -40,6 +42,45 @@ 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.
+
+Options:
+  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
+              generator did not produce, without asking. Without it, such content
+              is listed and you are asked; where nobody can answer (stdin is not a
+              terminal, as in CI), the run is refused and nothing is touched.
+
+The generator owns AvClient.ts and generated/ in generateAt, and nothing else
+there: your own files beside them are never read, moved or removed.
+
+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
+script and the @aventara/client devDependency; install; generate.
+
+Options:
+  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].
+  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].
+  --no-env-var                   Write it into ${CLIENT_CONFIG_FILE} as a literal.
+  --generate-at <dir>            Where the client goes [./src/api].
+  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]
+  --skip-install                 Print the install instead of running it.
+  --skip-generate                Do not generate now.
+  -y, --yes                      Accept every default, and replace differing content.
+
+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";
@@ -54,6 +95,10 @@ export function parseCliCommand(argv) {
     if (command === "--help" || command === "-h") {
         return { command: "help" };
     }
+    if ((command === "init" || command === "generate") &&
+        (rest.includes("--help") || rest.includes("-h"))) {
+        return { command: "help", topic: command };
+    }
     if (command === "init") {
         return parseInit(rest, help);
     }

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

@@ -6,7 +6,6 @@ import { GeneratedNameError } from "../emit/name.deriver.js";
 import { ClientInitNotConfirmedError, ClientInitStepError, } from "../init/client-init.errors.js";
 import { ClientInitAnswerError, ClientInitUnansweredError, } from "../init/client-init.questions.js";
 import { ClientProjectRefusedError } from "../init/client-project.inspector.js";
-import { UnsupportedTypeScriptError } from "../output/output.validator.js";
 import { OutputWriteError, warningsRaisedBeforeDefect, } from "../output/output.writer.js";
 import { CliCommandError } from "./command.parser.js";
 import { renderWarningLines } from "./warning.renderer.js";
@@ -30,7 +29,6 @@ const REFUSALS = [
     ContractProtocolError,
     GeneratedNameError,
     OutputWriteError,
-    UnsupportedTypeScriptError,
     ClientInitAnswerError,
     ClientInitUnansweredError,
     ClientProjectRefusedError,

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { parseCliCommand, USAGE } from "./cli/command.parser.js";
+import { GENERATE_USAGE, INIT_USAGE, parseCliCommand, USAGE, } from "./cli/command.parser.js";
 import { runGenerate } from "./cli/generate.command.js";
 import { renderGenerationFailure } from "./cli/generation-failure.renderer.js";
 import { createTerminalPrompter } from "./cli/terminal.prompter.js";
@@ -27,7 +27,11 @@ export async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
         if (command.command === "help") {
-            io.stdout(USAGE);
+            io.stdout(command.topic === undefined
+                ? USAGE
+                : command.topic === "init"
+                    ? INIT_USAGE
+                    : GENERATE_USAGE);
             return 0;
         }
         if (command.command === "init") {

package/dist/config/config.loader.d.ts

@@ -1,11 +1,16 @@
 import type { ClientConfigInput } from "./client-config.interface.js";
 /**
- * Finds and evaluates the client config: `framework.client.ts`, default-exporting
- * `defineClientConfig({ entrypoint, generateAt })`, exactly as §15.2 writes it. One
- * file name, looked up in one directory — no search up the tree, no alternative
- * spellings, no `package.json` key: the specification names one file, and a
- * second way to configure the generator would be a second source of the same
- * fact.
+ * Finds and evaluates the client config: `framework.client.mts` (or, for a setup
+ * written before pilot.1, `framework.client.ts`), default-exporting
+ * `defineClientConfig({ entrypoint, generateAt })` as §15.2 writes it. One file,
+ * looked up in one directory — no search up the tree, no `package.json` key —
+ * and when both spellings are present the run refuses rather than choose: two
+ * files would be two sources of the same fact.
+ *
+ * Why `.mts` (pilot.1): `npm init -y` writes `"type": "commonjs"`, under which
+ * Node reads a `.ts` file as CommonJS and the config's `import`/`export` stop
+ * the run. A `.mts` file is an ES module in every project. A `.ts` config that
+ * fails that way is told to rename itself.
  *
  * The file is TypeScript and is evaluated by Node itself (type stripping, on by
  * default in the Node this repository requires), so the generator needs no
@@ -17,17 +22,20 @@ import type { ClientConfigInput } from "./client-config.interface.js";
  * is trusted: the config is the consumer's code, and a typo there should be a
  * sentence naming the member, not a `TypeError` from deep inside resolution.
  */
-/** The config file §15.2 names. */
-export declare const CLIENT_CONFIG_FILE = "framework.client.ts";
+/** The config file `avclient init` writes: an ES module whatever the project's `type` (pilot.1). */
+export declare const CLIENT_CONFIG_FILE = "framework.client.mts";
+/** §15.2's spelling, still read for the setups written before pilot.1. */
+export declare const LEGACY_CLIENT_CONFIG_FILE = "framework.client.ts";
 export interface LoadedClientConfig {
     /** The config file's absolute path; `generateAt` resolves against its directory. */
     readonly file: string;
     readonly config: ClientConfigInput;
 }
 /**
- * Evaluates `<directory>/framework.client.ts`.
+ * Evaluates `<directory>/framework.client.mts`, or `framework.client.ts` when
+ * only that one is there.
  *
- * @throws ClientConfigError, in one line, when the file is missing, does not
- *   evaluate, or does not default-export a client config.
+ * @throws ClientConfigError, in one line, when neither or both are there, or
+ *   the file does not evaluate, or does not default-export a client config.
  */
 export declare function loadClientConfigFile(directory: string): Promise<LoadedClientConfig>;

package/dist/config/config.loader.js

@@ -3,12 +3,17 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ClientConfigError } from "./config.resolver.js";
 /**
- * Finds and evaluates the client config: `framework.client.ts`, default-exporting
- * `defineClientConfig({ entrypoint, generateAt })`, exactly as §15.2 writes it. One
- * file name, looked up in one directory — no search up the tree, no alternative
- * spellings, no `package.json` key: the specification names one file, and a
- * second way to configure the generator would be a second source of the same
- * fact.
+ * Finds and evaluates the client config: `framework.client.mts` (or, for a setup
+ * written before pilot.1, `framework.client.ts`), default-exporting
+ * `defineClientConfig({ entrypoint, generateAt })` as §15.2 writes it. One file,
+ * looked up in one directory — no search up the tree, no `package.json` key —
+ * and when both spellings are present the run refuses rather than choose: two
+ * files would be two sources of the same fact.
+ *
+ * Why `.mts` (pilot.1): `npm init -y` writes `"type": "commonjs"`, under which
+ * Node reads a `.ts` file as CommonJS and the config's `import`/`export` stop
+ * the run. A `.mts` file is an ES module in every project. A `.ts` config that
+ * fails that way is told to rename itself.
  *
  * The file is TypeScript and is evaluated by Node itself (type stripping, on by
  * default in the Node this repository requires), so the generator needs no
@@ -20,26 +25,36 @@ import { ClientConfigError } from "./config.resolver.js";
  * is trusted: the config is the consumer's code, and a typo there should be a
  * sentence naming the member, not a `TypeError` from deep inside resolution.
  */
-/** The config file §15.2 names. */
-export const CLIENT_CONFIG_FILE = "framework.client.ts";
+/** The config file `avclient init` writes: an ES module whatever the project's `type` (pilot.1). */
+export const CLIENT_CONFIG_FILE = "framework.client.mts";
+/** §15.2's spelling, still read for the setups written before pilot.1. */
+export const LEGACY_CLIENT_CONFIG_FILE = "framework.client.ts";
 /**
- * Evaluates `<directory>/framework.client.ts`.
+ * Evaluates `<directory>/framework.client.mts`, or `framework.client.ts` when
+ * only that one is there.
  *
- * @throws ClientConfigError, in one line, when the file is missing, does not
- *   evaluate, or does not default-export a client config.
+ * @throws ClientConfigError, in one line, when neither or both are there, or
+ *   the file does not evaluate, or does not default-export a client config.
  */
 export async function loadClientConfigFile(directory) {
-    const file = path.resolve(directory, CLIENT_CONFIG_FILE);
-    if (!existsSync(file)) {
-        throw new ClientConfigError(`no ${CLIENT_CONFIG_FILE} at ${file}; create it with ` +
-            "`export default defineClientConfig({ entrypoint, generateAt })` and run the generator from its directory.");
+    const present = [CLIENT_CONFIG_FILE, LEGACY_CLIENT_CONFIG_FILE].filter((name) => existsSync(path.resolve(directory, name)));
+    if (present.length > 1) {
+        throw new ClientConfigError(`both ${CLIENT_CONFIG_FILE} and ${LEGACY_CLIENT_CONFIG_FILE} are in ${path.resolve(directory)}, and only one may configure the generator; keep ${CLIENT_CONFIG_FILE} and delete ${LEGACY_CLIENT_CONFIG_FILE}.`);
+    }
+    const [name] = present;
+    if (name === undefined) {
+        throw new ClientConfigError(`no ${CLIENT_CONFIG_FILE} at ${path.resolve(directory, CLIENT_CONFIG_FILE)}; create it with ` +
+            "`export default defineClientConfig({ entrypoint, generateAt })` (or run `avclient init`) and run the generator from its directory.");
     }
+    const file = path.resolve(directory, name);
     let evaluated;
     try {
         evaluated = (await import(pathToFileURL(file).href));
     }
     catch (error) {
-        throw new ClientConfigError(`${file} could not be evaluated: ${firstLineOf(error)}`, { cause: error });
+        throw new ClientConfigError(`${file} could not be evaluated: ${firstLineOf(error)}${name === LEGACY_CLIENT_CONFIG_FILE && error instanceof SyntaxError
+            ? `; if this project's package.json says "type": "commonjs" (npm init -y writes it), Node reads a .ts file as CommonJS — rename it ${CLIENT_CONFIG_FILE}, which is an ES module in every project`
+            : ""}`, { cause: error });
     }
     return { file, config: clientConfigOf(file, evaluated) };
 }

package/dist/init/client-config.template.d.ts

@@ -1,6 +1,11 @@
-/** R4, §15.2 — the `framework.client.ts` `avclient init` writes: developer-owned, read by `avclient generate`. */
+/**
+ * R4, §15.2 — the config `avclient init` writes: developer-owned, read by
+ * `avclient generate`. `file` names it in its own comment line: the
+ * `framework.client.mts` it writes, or — to recognize what pilot.0 wrote —
+ * `framework.client.ts`.
+ */
 export declare function clientConfigSource(input: {
     readonly entrypoint: string;
     readonly envVar: string | undefined;
     readonly generateAt: string;
-}): string;
+}, file?: string): string;

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

@@ -1,8 +1,13 @@
 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) {
+/**
+ * R4, §15.2 — the config `avclient init` writes: developer-owned, read by
+ * `avclient generate`. `file` names it in its own comment line: the
+ * `framework.client.mts` it writes, or — to recognize what pilot.0 wrote —
+ * `framework.client.ts`.
+ */
+export function clientConfigSource(input, file = CLIENT_CONFIG_FILE) {
     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.
@@ -10,7 +15,7 @@ export function clientConfigSource(input) {
             ? `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.`,
+        `// ${file}: where the Aventara server is, and where its typed client goes.`,
         "export default defineClientConfig({",
         input.envVar === undefined
             ? `\tentrypoint: ${JSON.stringify(input.entrypoint)},`

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

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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";
@@ -50,10 +50,14 @@ export async function runClientInit(command, io) {
     const writes = plan.conflicts.length === 0 ? plan.keeping : plan.replacing;
     for (const write of writes) {
         const target = path.join(io.cwd, write.path);
+        if (write.content === undefined) {
+            rmSync(target, { force: true });
+            continue;
+        }
         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`);
+    io.stdout(`avclient: initialized ${io.cwd}: ${writes.map((write) => (write.content === undefined ? `removed ${write.path}` : 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`);

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

@@ -9,9 +9,10 @@ import type { ClientProject } from "./client-project.inspector.js";
  */
 /** R4: the script a frontend regenerates its client with. */
 export declare const GENERATE_SCRIPT = "avclient:generate";
+/** One change to a project file: its new content, or `undefined` to remove it. */
 export type ClientInitWrite = {
     readonly path: string;
-    readonly content: string;
+    readonly content: string | undefined;
 };
 export type ClientInitPlan = {
     readonly keeping: readonly ClientInitWrite[];

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

@@ -1,4 +1,4 @@
-import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+import { CLIENT_CONFIG_FILE, LEGACY_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
@@ -31,6 +31,17 @@ export function planClientInit(input) {
     };
     const config = clientConfigSource(answers);
     const existingConfig = project.read(CLIENT_CONFIG_FILE);
+    // pilot.1: a `framework.client.ts` is moved to `framework.client.mts` — two
+    // configs would make `avclient generate` refuse. The one pilot.0 wrote for
+    // these answers moves without asking; anything else is a conflict.
+    const legacyConfig = project.read(LEGACY_CLIENT_CONFIG_FILE);
+    if (legacyConfig !== undefined) {
+        if (legacyConfig !== clientConfigSource(answers, LEGACY_CLIENT_CONFIG_FILE)) {
+            conflicts.push(`${LEGACY_CLIENT_CONFIG_FILE} (replaced by ${CLIENT_CONFIG_FILE})`);
+        }
+        keeping.push({ path: LEGACY_CLIENT_CONFIG_FILE, content: undefined });
+        replacing.push({ path: LEGACY_CLIENT_CONFIG_FILE, content: undefined });
+    }
     if (existingConfig !== undefined && existingConfig !== config) {
         conflicts.push(CLIENT_CONFIG_FILE);
     }

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

@@ -19,9 +19,12 @@ import type { EmittedTree } from "../emit/emitted-tree.interface.js";
  *   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).
+ * - **Syntax**, when it does not — or when the `typescript` that resolves has no
+ *   classic compiler API (TypeScript 7, plan B3; pilot.1): 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), 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;
@@ -38,16 +41,6 @@ export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
 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 {
@@ -70,6 +63,12 @@ export type OutputValidation = OutputAccepted | OutputRejected;
 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;
+/**
+ * The warning a run carries when the `typescript` that resolves is one the
+ * generator cannot type-check with (TypeScript 7): what was checked instead,
+ * and where the type check still happens.
+ */
+export declare function typeScriptWithoutCompilerApiWarning(version: string, checked: "syntax" | "shape"): string;
 /**
  * Judges `directory`, which the caller has just filled with `tree`.
  */

package/dist/output/output.validator.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import * as nodeModule from "node:module";
 import { createRequire } from "node:module";
@@ -28,30 +27,22 @@ export function typeScriptResolverFor(specifier) {
 /** The `typescript` this package's optional peer names (Q5). */
 export const resolveInstalledTypeScript = typeScriptResolverFor("typescript");
 /**
- * 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.
+ * Whether `compiler` has the classic compiler API {@link typeFindingsOf} uses.
+ * TypeScript 7 does not (plan B3: its package exports its version and nothing
+ * else); before pilot.1 the generator refused it, and its peer range stopped
+ * below it — which made `npm i` fail with ERESOLVE in any frontend whose
+ * `typescript` is the current `latest`.
  */
-export class UnsupportedTypeScriptError extends Error {
-    name = "UnsupportedTypeScriptError";
+function hasClassicCompilerApi(compiler) {
+    // One member, not `Partial<typeof ts>`: a mapped type over the whole
+    // compiler namespace costs thousands of instantiations to ask one question.
+    return (typeof compiler.createProgram ===
+        "function");
 }
-/** This package's own manifest: the one statement of the `typescript` range it supports. */
-const MANIFEST = new URL("../../package.json", import.meta.url);
-function declaredTypeScriptRange() {
-    const manifest = JSON.parse(readFileSync(MANIFEST, "utf8"));
-    return manifest.peerDependencies?.typescript ?? "(undeclared)";
-}
-/** Refuses a compiler without the API {@link typeFindingsOf} uses. */
-function assertClassicCompilerApi(compiler) {
-    // Two members, not `Partial<typeof ts>`: a mapped type over the whole
-    // compiler namespace costs thousands of instantiations to ask two questions.
-    const api = compiler;
-    if (typeof api.createProgram === "function") {
-        return;
-    }
-    throw new UnsupportedTypeScriptError(`the installed \`typescript\` ${api.version ?? "(no version)"} has no classic compiler API (\`createProgram\`) to type-check the generated output with; install \`typescript\` in the range @aventara/client supports, ${declaredTypeScriptRange()}.`);
+/** The version a resolved `typescript` names, whatever its API. */
+function versionOf(compiler) {
+    const { version } = compiler;
+    return typeof version === "string" ? version : "(no version)";
 }
 /**
  * The warning a run without `typescript` carries. Loud on purpose, in its words:
@@ -64,6 +55,16 @@ export const TYPESCRIPT_UNRESOLVED_WARNING = "`typescript` could not be resolved
 export const SYNTAX_CHECK_UNAVAILABLE_WARNING = "neither `typescript` nor Node's TypeScript parser is available, so the generated " +
     "output was NOT type-checked or parsed — only its shape was. Install `typescript` (an " +
     "optional peer of @aventara/client) in this project to restore the type check.";
+/**
+ * The warning a run carries when the `typescript` that resolves is one the
+ * generator cannot type-check with (TypeScript 7): what was checked instead,
+ * and where the type check still happens.
+ */
+export function typeScriptWithoutCompilerApiWarning(version, checked) {
+    return (`the installed \`typescript\` ${version} has no classic compiler API (\`createProgram\`), so the generated ` +
+        `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.");
+}
 /**
  * Judges `directory`, which the caller has just filled with `tree`.
  */
@@ -73,8 +74,7 @@ export async function validateOutputTree(directory, tree, resolveTypeScript = re
         return { accepted: false, checked: "shape", findings: shapeFindings };
     }
     const compiler = await resolveTypeScript();
-    if (compiler !== undefined) {
-        assertClassicCompilerApi(compiler);
+    if (compiler !== undefined && hasClassicCompilerApi(compiler)) {
         const findings = typeFindingsOf(compiler, directory, tree);
         return findings.length > 0
             ? { accepted: false, checked: "types", findings }
@@ -85,7 +85,11 @@ export async function validateOutputTree(directory, tree, resolveTypeScript = re
         return {
             accepted: true,
             checked: "shape",
-            warnings: [SYNTAX_CHECK_UNAVAILABLE_WARNING],
+            warnings: [
+                compiler === undefined
+                    ? SYNTAX_CHECK_UNAVAILABLE_WARNING
+                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "shape"),
+            ],
         };
     }
     const findings = syntaxFindingsOf(strip, tree);
@@ -94,7 +98,11 @@ export async function validateOutputTree(directory, tree, resolveTypeScript = re
         : {
             accepted: true,
             checked: "syntax",
-            warnings: [TYPESCRIPT_UNRESOLVED_WARNING],
+            warnings: [
+                compiler === undefined
+                    ? TYPESCRIPT_UNRESOLVED_WARNING
+                    : typeScriptWithoutCompilerApiWarning(versionOf(compiler), "syntax"),
+            ],
         };
 }
 /* ------------------------------------------------------------------ *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.0",
+  "version": "0.1.0-pilot.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -23,10 +23,10 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.0"
+    "@aventara/core": "0.1.0-pilot.1"
   },
   "peerDependencies": {
-    "typescript": ">=5.5.0 <7"
+    "typescript": ">=5.5.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "0.1.0-pilot.0",
+    "@aventara/testing": "0.1.0-pilot.1",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },