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

package/dist/config/tsconfig.locator.js

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { createFilesMatcher, getTsconfig, parseTsconfig, } from "get-tsconfig";
+import { ClientConfigError } from "./config.resolver.js";
+export function locateTsconfig(location) {
+    if (location.tsconfigFile !== undefined) {
+        return namedTsconfig(location.tsconfigFile);
+    }
+    const found = getTsconfig(location.generateAt);
+    if (found === null) {
+        return undefined;
+    }
+    if (found.config.references === undefined ||
+        createFilesMatcher(found)(location.entryFile) !== undefined) {
+        return found;
+    }
+    for (const reference of found.config.references) {
+        const referenced = referencedTsconfig(found.path, reference.path);
+        if (referenced !== undefined &&
+            createFilesMatcher(referenced)(location.entryFile) !== undefined) {
+            return referenced;
+        }
+    }
+    return found;
+}
+function namedTsconfig(file) {
+    try {
+        readFileSync(file, "utf8");
+        return { path: file, config: parseTsconfig(file) };
+    }
+    catch (error) {
+        const reason = error instanceof Error && "code" in error
+            ? String(error.code)
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        throw new ClientConfigError(`tsconfigFile names ${file}, which could not be read (${reason}); it must name the tsconfig.json your project compiles the generated client with.`);
+    }
+}
+function referencedTsconfig(from, reference) {
+    const target = path.resolve(path.dirname(from), reference);
+    for (const candidate of [target, path.join(target, "tsconfig.json")]) {
+        try {
+            readFileSync(candidate, "utf8");
+        }
+        catch {
+            continue;
+        }
+        return { path: candidate, config: parseTsconfig(candidate) };
+    }
+    return undefined;
+}

package/dist/contract/contract.acceptance.d.ts

@@ -1,9 +1,5 @@
 import { type ClientContract } from "@aventara/core";
 /**
- * §15.3's validation steps over a fetched body, in the specification's order, as
- * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
- * structure, then the advertised hash recomputed and compared (§19.2).
- *
  * # The structure check is core's, never a second implementation
  *
  * What a ClientContract IS belongs to core, so the structure step is core's
@@ -22,39 +18,29 @@ import { type ClientContract } from "@aventara/core";
  *
  * # A value, not a throw site
  *
- * M3's rule — failure is a message and an exit code, never a stack — needs both to
- * be typed members, so a rejection is the `ContractRejected` arm carrying its
- * sentence and its exit code, and `ContractProtocolError` is built from it only
- * where generation stops.
- *
  * # The hash is core's, never a second implementation
  *
  * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
- * the function the compiler stamps it with (M6a) — and compared. A hash computed
- * here would be a second source of the Contract's identity.
- *
- * # Bodies the hash cannot be recomputed over (S0)
+ * the function the compiler stamps it with — and compared. A hash computed here
+ * would be a second source of the Contract's identity.
  *
  * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
- * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
- * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
- * stamped a hash over such a body — its own canonicalizer would have refused — so it
- * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
- * never let escape as a stack. Both values are ones the ClientContract TYPE admits
- * (`number`, `string`), so core's structure check accepts them by design; what
- * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
- * hashing is not a known property of the input, and keeps its stack as a defect.
+ * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses
+ * to a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can
+ * have stamped a hash over such a body — its own canonicalizer would have refused
+ * — so it is refused at THIS step, as `hash-mismatch` with its own sentence and
+ * core's path, never let escape as a stack. ONLY that class is caught: anything
+ * else thrown while hashing is not a known property of the input, and keeps its
+ * stack as a defect.
  */
-/** The protocol versions this generator speaks (§19.1: support is explicit). */
+/** The protocol versions this generator speaks. */
 export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
-/** Closed at three (plan §7): §19.1, §19.2, and §15.3's structure step. */
 export type ContractRejectionReason = "protocol-unsupported" | "hash-mismatch" | "structure-invalid";
 export type ContractAccepted = {
     readonly accepted: true;
     /**
-     * Trusted to the depth this step checks: core's structure check and the hash.
-     * It is the erased ClientContract (ADR 0009): no capability is interpreted here
-     * (plan §1).
+     * Trusted to the depth this step checks: core's structure check and the hash. It
+     * is the erased ClientContract: no capability is interpreted here.
      */
     readonly contract: ClientContract;
 };

package/dist/contract/contract.acceptance.js

@@ -1,55 +1,7 @@
 import { AVENTARA_PROTOCOL_VERSION, CanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core";
-/**
- * §15.3's validation steps over a fetched body, in the specification's order, as
- * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
- * structure, then the advertised hash recomputed and compared (§19.2).
- *
- * # The structure check is core's, never a second implementation
- *
- * What a ClientContract IS belongs to core, so the structure step is core's
- * `validateClientContractStructure` and nothing here restates a member, a kind or
- * a vocabulary. Before it, a body with a valid envelope and a malformed member —
- * `resources: { Spell: 5 }` — reached core's canonicalizer, which reads members
- * without validating them, and escaped as a plain `TypeError` and a stack.
- *
- * # Protocol support is judged first, from a read rather than a rule
- *
- * A body from a protocol this generator does not speak may have a different
- * structure, and "unsupported" is then the true and useful answer. So the
- * advertised version is READ — leniently, never judged — and judged against the
- * supported set before any structure is. A body whose version cannot be read at
- * all goes on to the structure step, which names what is wrong with it.
- *
- * # A value, not a throw site
- *
- * M3's rule — failure is a message and an exit code, never a stack — needs both to
- * be typed members, so a rejection is the `ContractRejected` arm carrying its
- * sentence and its exit code, and `ContractProtocolError` is built from it only
- * where generation stops.
- *
- * # The hash is core's, never a second implementation
- *
- * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
- * the function the compiler stamps it with (M6a) — and compared. A hash computed
- * here would be a second source of the Contract's identity.
- *
- * # Bodies the hash cannot be recomputed over (S0)
- *
- * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
- * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
- * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
- * stamped a hash over such a body — its own canonicalizer would have refused — so it
- * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
- * never let escape as a stack. Both values are ones the ClientContract TYPE admits
- * (`number`, `string`), so core's structure check accepts them by design; what
- * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
- * hashing is not a known property of the input, and keeps its stack as a defect.
- */
-/** The protocol versions this generator speaks (§19.1: support is explicit). */
 export const SUPPORTED_PROTOCOL_VERSIONS = new Set([
     AVENTARA_PROTOCOL_VERSION,
 ]);
-/** A refused contract stops generation; the adapter CLI's precedent is 1 (M3). */
 const REFUSED_EXIT_CODE = 1;
 const CHECK_ENTRYPOINT = "Check that the entrypoint is the deployed Aventara entrypoint (origin plus mount path).";
 export async function acceptClientContract(body) {
@@ -84,7 +36,6 @@ export async function acceptClientContract(body) {
     }
     return { accepted: true, contract };
 }
-/** The refusal that stops generation, carrying the rejection's reason and sentence. */
 export class ContractProtocolError extends Error {
     name = "ContractProtocolError";
     reason;
@@ -95,11 +46,6 @@ export class ContractProtocolError extends Error {
         this.exitCode = rejection.exitCode;
     }
 }
-/**
- * `protocol.version` where the body states a number there, `undefined` otherwise.
- * A read, not a rule: it judges nothing, and a body it cannot read a version from
- * is left for the structure step to describe.
- */
 function advertisedProtocolVersion(body) {
     if (!isJsonObject(body) || !Object.hasOwn(body, "protocol")) {
         return undefined;

package/dist/contract/contract.fetcher.d.ts

@@ -1,19 +1,14 @@
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 /**
- * §12.5's discovery request: one `GET <entrypoint>/_contract`, with no headers —
- * §12.4: *"The contract GET itself requires neither header because it is the
- * discovery mechanism."* The entrypoint is the CLIENT config's URL (§15.2,
- * resolved in S2), not the server's mount-path setting.
- *
  * # Transport, and only transport
  *
  * This file's success is "a JSON value arrived". It does not judge the value: a
  * body that is a JSON array is still a successful fetch, and refusing it is
- * `contract.acceptance.ts`'s job. Every way of failing to produce a JSON value is a
- * `ContractTransportError`, a different class from `ContractProtocolError`,
- * because the two have different remedies — reach the deployment, versus regenerate
- * or upgrade against what it served — and a message that blurs them sends the
- * developer to the wrong one.
+ * `contract.acceptance.ts`'s job. Every way of failing to produce a JSON value is
+ * a `ContractTransportError`, a different class from `ContractProtocolError`,
+ * because the two have different remedies — reach the deployment, versus
+ * regenerate or upgrade against what it served — and a message that blurs them
+ * sends the developer to the wrong one.
  *
  * `fetch` is injected, so the transport is tested without a server; the default is
  * the platform's.
@@ -26,8 +21,8 @@ export type ContractFetch = (url: URL, init: {
     readonly headers?: Readonly<Record<string, string>>;
 }) => Promise<ContractResponse>;
 /**
- * What a conditional GET answers when the served ClientContract is the one named
- * (`304 Not Modified`, Phase 10 Q8): no body, nothing to judge.
+ * What a conditional GET answers when the served ClientContract is the one named:
+ * no body, nothing to judge.
  */
 export declare const CONTRACT_NOT_MODIFIED: unique symbol;
 export type ContractTransportFailureReason = 
@@ -46,9 +41,9 @@ export declare class ContractTransportError extends Error {
 }
 /**
  * `<entrypoint>/_contract`: the canonical mount path and the route, concatenated.
- * The path's canonical form is resolution's (F-822) — root is `""` — so the join
- * repairs nothing and special-cases nothing. URL resolution would be wrong here:
- * `new URL("_contract", "https://h/api")` replaces `api`.
+ * The path's canonical form is resolution's — root is `""` — so the join repairs
+ * nothing and special-cases nothing. URL resolution would be wrong here: `new
+ * URL("_contract", "https://h/api")` replaces `api`.
  */
 export declare function contractUrlOf(entrypoint: ClientEntrypoint): URL;
 /** The URL as it may be printed: credentials in the entrypoint never are. */
@@ -56,8 +51,8 @@ export declare function displayUrl(url: URL): string;
 /**
  * GETs the ClientContract and returns the parsed body, unjudged — or, when
  * `ifNoneMatch` (a quoted contract hash, the deployment's entity tag) is sent and
- * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED} (Phase 12-rest Q6).
- * A `304` to a request that sent none is no answer, like any other non-2xx.
+ * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED}. A `304` to a
+ * request that sent none is no answer, like any other non-2xx.
  *
  * @throws ContractTransportError when no JSON value arrives.
  */

package/dist/contract/contract.fetcher.js

@@ -1,7 +1,3 @@
-/**
- * What a conditional GET answers when the served ClientContract is the one named
- * (`304 Not Modified`, Phase 10 Q8): no body, nothing to judge.
- */
 export const CONTRACT_NOT_MODIFIED = Symbol("aventara.contract-not-modified");
 export class ContractTransportError extends Error {
     reason;
@@ -11,32 +7,17 @@ export class ContractTransportError extends Error {
         this.reason = reason;
     }
 }
-/**
- * `<entrypoint>/_contract`: the canonical mount path and the route, concatenated.
- * The path's canonical form is resolution's (F-822) — root is `""` — so the join
- * repairs nothing and special-cases nothing. URL resolution would be wrong here:
- * `new URL("_contract", "https://h/api")` replaces `api`.
- */
 export function contractUrlOf(entrypoint) {
     const url = new URL(entrypoint.deployment.href);
     url.pathname = `${entrypoint.path}/_contract`;
     return url;
 }
-/** The URL as it may be printed: credentials in the entrypoint never are. */
 export function displayUrl(url) {
     const shown = new URL(url.href);
     shown.username = "";
     shown.password = "";
     return shown.href;
 }
-/**
- * GETs the ClientContract and returns the parsed body, unjudged — or, when
- * `ifNoneMatch` (a quoted contract hash, the deployment's entity tag) is sent and
- * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED} (Phase 12-rest Q6).
- * A `304` to a request that sent none is no answer, like any other non-2xx.
- *
- * @throws ContractTransportError when no JSON value arrives.
- */
 export async function fetchClientContractBody(entrypoint, fetch = globalThis.fetch, ifNoneMatch) {
     const url = contractUrlOf(entrypoint);
     const shown = displayUrl(url);
@@ -67,14 +48,9 @@ export async function fetchClientContractBody(entrypoint, fetch = globalThis.fet
         return JSON.parse(text);
     }
     catch (error) {
-        // The body itself is not printed: it may be a whole HTML page.
         throw new ContractTransportError("body-not-json", `The response from ${shown} is not JSON, so it is not a ClientContract. ${remedy}`, { cause: error });
     }
 }
-/**
- * A failure's own words and, for Node's `fetch failed`, its cause's — the part
- * that says ECONNREFUSED or ENOTFOUND. Messages only, never a stack.
- */
 function describeCause(error) {
     if (!(error instanceof Error)) {
         return String(error);

package/dist/contract/contract.loader.d.ts

@@ -2,12 +2,11 @@ import type { ClientContract } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ContractFetch } from "./contract.fetcher.js";
 /**
- * §15.3's first steps as one call: GET the ClientContract, then accept it — protocol
- * support, structure, hash. Where the pipeline stops on a rejection, so it is where
- * the `ContractRejected` value becomes a thrown `ContractProtocolError`.
+ * Where the pipeline stops on a rejection, so it is where the `ContractRejected`
+ * value becomes a thrown `ContractProtocolError`.
  */
 export interface ClientContractLoadInput {
-    /** The client config's resolved entrypoint (§15.2, S2). */
+    /** The client config's resolved entrypoint. */
     readonly entrypoint: ClientEntrypoint;
     /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
@@ -17,7 +16,7 @@ export interface ClientContractLoadInput {
  * @throws ContractProtocolError when what arrived is refused.
  */
 export declare function loadClientContract(input: ClientContractLoadInput): Promise<ClientContract>;
-/** A ClientContract loaded against one the caller already holds (Phase 12-rest Q6). */
+/** A ClientContract loaded against one the caller already holds. */
 export interface ClientContractSince {
     readonly contract: ClientContract;
     /** The deployment answered `304`: `contract` is the one the caller held. */

package/dist/contract/contract.loader.js

@@ -1,18 +1,8 @@
 import { acceptClientContract, ContractProtocolError, } from "./contract.acceptance.js";
 import { CONTRACT_NOT_MODIFIED, contractUrlOf, displayUrl, fetchClientContractBody, } from "./contract.fetcher.js";
-/**
- * @throws ContractTransportError when no JSON value arrives.
- * @throws ContractProtocolError when what arrived is refused.
- */
 export async function loadClientContract(input) {
     return accepted(await fetchClientContractBody(input.entrypoint, input.fetch), input);
 }
-/**
- * {@link loadClientContract}, conditional on `stored` — a ClientContract the
- * caller holds, already verified (its parsed carrier): the GET sends
- * `If-None-Match: "<its hash>"`, and a `304` answers with `stored` itself. Without
- * `stored` the GET is unconditional.
- */
 export async function loadClientContractSince(input, stored) {
     if (stored === undefined) {
         return { contract: await loadClientContract(input), notModified: false };

package/dist/emit/banner.emitter.d.ts

@@ -1,22 +1,21 @@
 /**
- * The banner line that says who owns a file. It is what the output writer reads
- * to decide that a directory is a previous generation it may replace whole
- * (§15.3) rather than someone's files it would delete — so it is its own
- * constant, and must not change between generator versions: an output written
- * by an older generator has to stay recognisable to a newer one.
+ * The banner line that says who owns a file. It is what the output writer reads to
+ * decide that a directory is a previous generation it may replace whole rather
+ * than someone's files it would delete — so it is its own constant, and must not
+ * change between generator versions: an output written by an older generator has
+ * to stay recognisable to a newer one.
  */
 export declare const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
 /**
- * The ownership banner every emitted file opens with (§15.3: "Files are stamped as
- * generated/do-not-edit").
+ * The ownership banner every emitted file opens with.
  *
- * The Biome suppressions are EMITTED rather than configured (M17, the adapter's
- * `artifact.emitter.ts` precedent), so the output stays correct wherever a
- * consumer drops it, including a repository whose formatter nobody here chose.
+ * The Biome suppressions are EMITTED rather than configured, so the output stays
+ * correct wherever a consumer drops it, including a repository whose formatter
+ * nobody here chose.
  *
  * Nothing in it can change between two runs over one contract: no timestamp, no
- * generator version, no host, no path (Q4, §19.3) — any of them would break the
- * exit gate's byte-equality on the first re-run. And no driver prose (Q4 = A).
+ * generator version, no host, no path — any of them would break the exit gate's
+ * byte-equality on the first re-run. And no driver prose.
  */
 export declare const GENERATED_BANNER: readonly string[];
 /** `source` with the banner before it and one blank line between. */

package/dist/emit/banner.emitter.js

@@ -1,40 +1,14 @@
-/**
- * The banner line that says who owns a file. It is what the output writer reads
- * to decide that a directory is a previous generation it may replace whole
- * (§15.3) rather than someone's files it would delete — so it is its own
- * constant, and must not change between generator versions: an output written
- * by an older generator has to stay recognisable to a newer one.
- */
 export const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
-/**
- * The ownership banner every emitted file opens with (§15.3: "Files are stamped as
- * generated/do-not-edit").
- *
- * The Biome suppressions are EMITTED rather than configured (M17, the adapter's
- * `artifact.emitter.ts` precedent), so the output stays correct wherever a
- * consumer drops it, including a repository whose formatter nobody here chose.
- *
- * Nothing in it can change between two runs over one contract: no timestamp, no
- * generator version, no host, no path (Q4, §19.3) — any of them would break the
- * exit gate's byte-equality on the first re-run. And no driver prose (Q4 = A).
- */
 export const GENERATED_BANNER = [
     "// biome-ignore-all format: generated output; these bytes are the artifact",
     "// biome-ignore-all lint: generated output",
     GENERATED_OWNERSHIP_LINE,
     "/* Regenerate with `avclient generate`. */",
 ];
-/** `source` with the banner before it and one blank line between. */
 export function withGeneratedBanner(source) {
     return `${GENERATED_BANNER.join("\n")}\n\n${source}`;
 }
-/**
- * How far into a file the ownership line is looked for. The banner opens every
- * emitted file, so the line sits well inside this; a reader never has to read a
- * whole file to learn it is foreign.
- */
 export const GENERATED_OWNERSHIP_HEAD_BYTES = 1024;
-/** Whether `head` — a file's first bytes, as text — carries the ownership line. */
 export function carriesGeneratedOwnership(head) {
     return head
         .slice(0, GENERATED_OWNERSHIP_HEAD_BYTES)

package/dist/emit/client-surface.emitter.d.ts

@@ -1,32 +1,28 @@
 import type { ClientContract } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
 import { type EmittedNames } from "./name.deriver.js";
 /**
- * `generated/client.ts` — the typed surface (Phase 12-rest S4; plan §6): the class
- * `AvClient` (Q8), its options `AvClientOptions` and the per-call `CallOptions`
- * (Q9, Q17), and the ready instance `avClient`, this module's default export
- * (Q7).
+ * `generated/client.ts` — the typed surface: the class `AvClient`, its options
+ * `AvClientOptions` and the per-call `CallOptions`, and the ready instance
+ * `avClient`, this module's default export.
  *
  * Every argument and result type is an instantiation of core's own derivation,
- * copied under `generated/derivation/` (Q1 = A): the call grammar
- * (`OperationGrammar`, `OperationCall`, `DeferredOperationCall`, S1) over the
- * carrier's contract (`ClientContractShape`, Q4), in the client's forms (Q3 = A:
- * core's application forms, with this tree's own `Decimal`). Nothing here
- * re-spells a rule. A call resolves to the data (Q11 = a: `"data"`), a
- * first-style miss to `null`.
+ * copied under `generated/derivation/`: the call grammar over the carrier's
+ * contract, in the client's forms. Nothing here re-spells a rule. A call resolves
+ * to the data, a first-style miss to `null`.
  *
- * Each surface is one mapped alias over the one contract (Phase 9's variance
- * lesson). A Resource is reached by its contract name, except where that name is
- * one of the client's own members (Q12), which renames the property only.
- * `tx` and `transaction` exist iff the contract advertises `interactive`
- * transactions (P3), in the type as in the runtime.
+ * Each surface is one mapped alias over the one contract. A Resource is reached by
+ * its contract name, except where that name is one of the client's own members,
+ * which renames the property only. `tx` and `transaction` exist iff the contract
+ * advertises `interactive` transactions, in the type as in the runtime.
  *
  * Also declared here, for `types.d.ts` alone, the two helpers the named types are
- * aliases of (Q10): `ResourceRecord` and `ResourceArgument`.
+ * aliases of: `ResourceRecord` and `ResourceArgument`.
  *
- * At runtime (S5) the class builds one frozen object per Resource from the
- * advertised operations (P4) — each variant a function that runs the operation
- * through the transport, reading the fetch when it is called — and the default
- * entrypoint is the generated one (§15.2, Q5) unless the options name another.
+ * At runtime the class builds one frozen object per Resource from the advertised
+ * operations — each variant a function that runs the operation through the
+ * transport, reading the fetch when it is called — and the default entrypoint is
+ * the generated one unless the options name another.
  */
-export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames): EmittedModule;
+export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames, style: ClientModuleStyle): EmittedModule;