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

package/dist/output/output.writer.js

@@ -2,24 +2,17 @@ import { randomBytes } from "node:crypto";
 import * as fsPromises from "node:fs/promises";
 import path from "node:path";
 import { carriesGeneratedOwnership, GENERATED_OWNERSHIP_HEAD_BYTES, } from "../emit/banner.emitter.js";
-import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "../emit/emitted-tree.interface.js";
+import { CLIENT_ENTRY_FILES, GENERATED_DIRECTORY, LEGACY_CLIENT_ENTRY_FILES, } from "../emit/emitted-tree.interface.js";
 import { resolveInstalledTypeScript, validateOutputTree, } from "./output.validator.js";
-/** A write that stopped; the previous output is intact unless it says otherwise. */
 export class OutputWriteError extends Error {
     stage;
     name = "OutputWriteError";
-    /**
-     * What the run said before it stopped, in the order a success returns its
-     * warnings: the emission's, the validator's, the writer's. Printed before the
-     * refusal's sentence.
-     */
     warnings;
     constructor(stage, message, options) {
         super(message, options);
         this.stage = stage;
         this.warnings = options?.warnings ?? [];
     }
-    /** The same refusal, with `earlier` said before the warnings it already carries. */
     precededBy(earlier) {
         return new OutputWriteError(this.stage, this.message, {
             cause: this.cause,
@@ -27,18 +20,7 @@ export class OutputWriteError extends Error {
         });
     }
 }
-/**
- * What a run said before a defect stopped it, kept beside the defect rather than
- * on a wrapper: a defect propagates as the very error thrown, with its own stack,
- * so a caller matching it by identity or type still can. Keyed weakly, so it
- * lives exactly as long as the error does. A thrown primitive cannot be a key;
- * what was said before one is not kept.
- */
 const WARNINGS_BEFORE_DEFECT = new WeakMap();
-/**
- * Records `earlier` as said before `defect`, ahead of anything already recorded,
- * and returns `defect` unchanged so the caller rethrows the same error.
- */
 export function precedeDefect(defect, earlier) {
     if (earlier.length > 0 && typeof defect === "object" && defect !== null) {
         WARNINGS_BEFORE_DEFECT.set(defect, [
@@ -48,10 +30,6 @@ export function precedeDefect(defect, earlier) {
     }
     return defect;
 }
-/**
- * What the run said before `defect` stopped it, in the order a success returns
- * its warnings; empty when nothing was, or for an error no run threw.
- */
 export function warningsRaisedBeforeDefect(defect) {
     return typeof defect === "object" && defect !== null
         ? (WARNINGS_BEFORE_DEFECT.get(defect) ?? [])
@@ -60,23 +38,20 @@ export function warningsRaisedBeforeDefect(defect) {
 const NEXT_PREFIX = ".aventara-next-";
 const READY_PREFIX = ".aventara-ready-";
 const PREVIOUS_GENERATED = `.${GENERATED_DIRECTORY}.aventara-previous`;
-/**
- * Writes `emission.tree` as `<generateAt>/AvClient.ts` and `<generateAt>/generated/`.
- *
- * @throws OutputWriteError when the write stops; the previous output is intact.
- */
-export async function writeClientOutput(input) {
-    const fs = input.fileSystem ?? fsPromises;
-    const generateAt = path.resolve(input.generateAt);
-    const paths = {
+const PREVIOUS_ENTRIES = ".previous-entries";
+function outputPathsOf(generateAt) {
+    return {
         generateAt,
         generated: path.join(generateAt, GENERATED_DIRECTORY),
-        entry: path.join(generateAt, CLIENT_ENTRY_FILE),
         previous: path.join(generateAt, PREVIOUS_GENERATED),
     };
+}
+export async function writeClientOutput(input) {
+    const fs = input.fileSystem ?? fsPromises;
+    const generateAt = path.resolve(input.generateAt);
+    const paths = outputPathsOf(generateAt);
     const writerWarnings = [];
     let validationWarnings = [];
-    /** The outermost directory this run created on the way to `generateAt`, if any. */
     let created;
     try {
         return await writeStagedOutput();
@@ -95,7 +70,6 @@ export async function writeClientOutput(input) {
             : precedeDefect(error, said);
     }
     async function writeStagedOutput() {
-        // prepare — recover a killed run, then decide whether the two entries are ours.
         const state = await stage("prepare", paths, async () => {
             created = await ensureDirectory(fs, generateAt);
             writerWarnings.push(...(await recoverInterruptedRun(fs, paths)));
@@ -107,14 +81,11 @@ export async function writeClientOutput(input) {
             }
             return inspection;
         });
-        // temp — the whole tree, AvClient.ts and generated/ together, staged in generateAt.
         const suffix = randomBytes(6).toString("hex");
         let staging = path.join(generateAt, `${NEXT_PREFIX}${suffix}`);
         let stagingExists = false;
         try {
             await stage("temp", paths, async () => {
-                // `mkdir`, not `mkdtemp`: generated/ is moved out of this directory and
-                // takes the mode any directory the user creates takes (`mkdtemp` makes 0700).
                 await fs.mkdir(staging);
                 stagingExists = true;
                 for (const file of input.emission.tree) {
@@ -123,8 +94,7 @@ export async function writeClientOutput(input) {
                     await fs.writeFile(target, file.bytes);
                 }
             });
-            // validate — Q6, over AvClient.ts and generated/ as one program.
-            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission.tree, input.resolveTypeScript ?? resolveInstalledTypeScript));
+            const validation = await stage("validate", paths, () => validateOutputTree(staging, input.emission, input.resolveTypeScript ?? resolveInstalledTypeScript));
             if (validation.accepted) {
                 validationWarnings = validation.warnings;
             }
@@ -133,7 +103,6 @@ export async function writeClientOutput(input) {
                     "This is a defect in @aventara/client; please report it with these findings:\n" +
                     validation.findings.map((finding) => `  ${finding}`).join("\n"));
             }
-            // replace — the order and its rollbacks are the module doc's.
             await stage("replace", paths, async () => {
                 const ready = path.join(generateAt, `${READY_PREFIX}${suffix}`);
                 await fs.rename(staging, ready);
@@ -151,11 +120,28 @@ export async function writeClientOutput(input) {
                     }
                     throw error;
                 }
+                const aside = path.join(staging, PREVIOUS_ENTRIES);
+                const movedOut = [];
+                const movedIn = [];
                 try {
-                    await fs.rename(path.join(staging, CLIENT_ENTRY_FILE), paths.entry);
+                    await fs.mkdir(aside);
+                    for (const name of [...state.entries, ...state.legacy]) {
+                        await fs.rename(path.join(generateAt, name), path.join(aside, name));
+                        movedOut.push(name);
+                    }
+                    for (const name of CLIENT_ENTRY_FILES) {
+                        await fs.rename(path.join(staging, name), path.join(generateAt, name));
+                        movedIn.push(name);
+                    }
                 }
                 catch (error) {
                     await rollBack(paths, error, async () => {
+                        for (const name of movedIn.reverse()) {
+                            await fs.rename(path.join(generateAt, name), path.join(staging, name));
+                        }
+                        for (const name of movedOut.reverse()) {
+                            await fs.rename(path.join(aside, name), path.join(generateAt, name));
+                        }
                         await fs.rename(paths.generated, path.join(staging, GENERATED_DIRECTORY));
                         if (movedAside) {
                             await fs.rename(paths.previous, paths.generated);
@@ -186,23 +172,14 @@ export async function writeClientOutput(input) {
         finally {
             if (stagingExists) {
                 await fs.rm(staging, { recursive: true, force: true }).catch(() => {
-                    // The next run removes it by name; the error being thrown matters more.
                 });
             }
         }
     }
 }
-/** The sentence's ending when the previous output was not changed. */
 function LEFT_AS_THEY_WERE(paths) {
-    return `${CLIENT_ENTRY_FILE} and ${GENERATED_DIRECTORY}/ in ${paths.generateAt} were left exactly as they were.`;
+    return `${CLIENT_ENTRY_FILES.join(", ")} and ${GENERATED_DIRECTORY}/ in ${paths.generateAt} were left exactly as they were.`;
 }
-/**
- * Creates `generateAt` when missing; refuses when something other than a
- * directory is there.
- *
- * @returns the outermost directory it created — `generateAt` or an ancestor —
- *   or `undefined` when `generateAt` already existed.
- */
 async function ensureDirectory(fs, generateAt) {
     const stats = await lstatOrUndefined(fs, generateAt);
     if (stats === undefined) {
@@ -213,12 +190,6 @@ async function ensureDirectory(fs, generateAt) {
     }
     return undefined;
 }
-/**
- * Removes, after a failed run, the directories it created: `generateAt` and each
- * parent up to `outermost`, innermost first. `rmdir` removes only an empty
- * directory, so nothing anyone else put there meanwhile is lost; the first one
- * that cannot be removed ends the walk, and is named in the warning returned.
- */
 async function removeCreatedDirectories(fs, generateAt, outermost) {
     for (let directory = generateAt;; directory = path.dirname(directory)) {
         try {
@@ -235,29 +206,23 @@ async function removeCreatedDirectories(fs, generateAt, outermost) {
         }
     }
 }
-/**
- * Leftovers of a run that was killed, recognised only by the names this writer
- * gives them:
- *
- * - a staging directory that never became ready was not validated: removed;
- * - a ready one whose `generated/` was already moved in but whose `AvClient.ts`
- *   was not: its `AvClient.ts` is moved in, completing the new pair;
- * - any other ready one: removed;
- * - a previous `generated/` moved aside: put back when nothing replaced it,
- *   removed when something did.
- */
 async function recoverInterruptedRun(fs, paths) {
     const warnings = [];
     for (const entry of (await fs.readdir(paths.generateAt)).sort()) {
         const leftover = path.join(paths.generateAt, entry);
         if (entry.startsWith(READY_PREFIX)) {
-            const stagedEntry = path.join(leftover, CLIENT_ENTRY_FILE);
             const generatedMovedIn = (await lstatOrUndefined(fs, path.join(leftover, GENERATED_DIRECTORY))) === undefined;
-            if (generatedMovedIn &&
-                (await lstatOrUndefined(fs, stagedEntry)) !== undefined) {
-                await fs.rename(stagedEntry, paths.entry);
-                warnings.push(`an interrupted run had moved its generated/ in but not its AvClient.ts; ` +
-                    `the validated AvClient.ts was moved in at ${paths.entry} before generating.`);
+            const completed = [];
+            for (const name of generatedMovedIn ? CLIENT_ENTRY_FILES : []) {
+                const staged = path.join(leftover, name);
+                if ((await lstatOrUndefined(fs, staged)) !== undefined) {
+                    await fs.rename(staged, path.join(paths.generateAt, name));
+                    completed.push(name);
+                }
+            }
+            if (completed.length > 0) {
+                warnings.push(`an interrupted run had moved its generated/ in but not all of its entry files; ` +
+                    `the validated ${completed.join(", ")} ${completed.length === 1 ? "was" : "were"} moved in at ${paths.generateAt} before generating.`);
             }
             await fs.rm(leftover, { recursive: true, force: true });
         }
@@ -277,35 +242,12 @@ async function recoverInterruptedRun(fs, paths) {
     }
     return warnings;
 }
-/**
- * Where the `generated/` a run works with comes from once a killed run is
- * recovered: the previous one moved aside when nothing replaced it — recovery
- * puts it back — and `generated/` otherwise. One answer for the recovery and for
- * the read-only look ahead of it, so the two cannot disagree.
- */
 async function generatedAfterRecovery(fs, paths) {
     return (await lstatOrUndefined(fs, paths.generated)) === undefined &&
         (await lstatOrUndefined(fs, paths.previous)) !== undefined
         ? paths.previous
         : paths.generated;
 }
-/**
- * Lists what in `<generateAt>/AvClient.ts` and `<generateAt>/generated/` the
- * generator did not produce — a file without the ownership line, a symbolic link,
- * anything that is not a regular file — so the person running it can be asked
- * before a generation overwrites or removes it (architect, 2026-10-04). Reads
- * only; looks at nothing else in `generateAt`. Empty when `generateAt` does not
- * exist yet.
- *
- * It sees what the write will see once it has recovered a killed run, without
- * recovering it: a `generated/` the killed run moved aside with nothing in its
- * place is read where it lies and its files named where recovery puts them back
- * (`generated/…`). So the question asked, and `--yes`, cover them too — and a
- * run that stops here has still touched nothing.
- *
- * @throws OutputWriteError when `generateAt` is not a directory, `generated` is
- *   not a directory or `AvClient.ts` is not a file: no confirmation repairs that.
- */
 export async function findForeignOutputContent(generateAt, fileSystem = fsPromises) {
     const root = path.resolve(generateAt);
     const stats = await lstatOrUndefined(fileSystem, root);
@@ -315,21 +257,10 @@ export async function findForeignOutputContent(generateAt, fileSystem = fsPromis
     if (!stats.isDirectory()) {
         throw notADirectory(root);
     }
-    const paths = {
-        generateAt: root,
-        generated: path.join(root, GENERATED_DIRECTORY),
-        entry: path.join(root, CLIENT_ENTRY_FILE),
-        previous: path.join(root, PREVIOUS_GENERATED),
-    };
+    const paths = outputPathsOf(root);
     const inspection = await inspectOwnedEntries(fileSystem, paths, await generatedAfterRecovery(fileSystem, paths));
     return inspection.foreign;
 }
-/**
- * What stands at the two owned entries. `generatedSource` is the directory read
- * as `generated/` — `generated/` itself, or the previous one a killed run moved
- * aside, which recovery will put back there — and its files are named as
- * `generated/…` either way.
- */
 async function inspectOwnedEntries(fs, paths, generatedSource = paths.generated) {
     const foreign = [];
     const relative = (file) => path.relative(paths.generateAt, file).split(path.sep).join("/");
@@ -353,23 +284,37 @@ async function inspectOwnedEntries(fs, paths, generatedSource = paths.generated)
             }
         }
     }
-    const entryStats = await lstatOrUndefined(fs, paths.entry);
-    if (entryStats !== undefined) {
-        if (!entryStats.isFile()) {
-            throw new OutputWriteError("prepare", `refusing to replace ${paths.entry}: it is not a file, and the generator owns ${CLIENT_ENTRY_FILE} ` +
+    const entries = [];
+    for (const name of CLIENT_ENTRY_FILES) {
+        const file = path.join(paths.generateAt, name);
+        const stats = await lstatOrUndefined(fs, file);
+        if (stats === undefined) {
+            continue;
+        }
+        if (!stats.isFile()) {
+            throw new OutputWriteError("prepare", `refusing to replace ${file}: it is not a file, and the generator owns ${name} ` +
                 "as one; move it, or choose another `generateAt`. Nothing was written.");
         }
-        if (!(await carriesOwnershipLine(fs, paths.entry))) {
-            foreign.push(relative(paths.entry));
+        entries.push(name);
+        if (!(await carriesOwnershipLine(fs, file))) {
+            foreign.push(relative(file));
+        }
+    }
+    const legacy = [];
+    for (const name of LEGACY_CLIENT_ENTRY_FILES) {
+        const file = path.join(paths.generateAt, name);
+        if ((await lstatOrUndefined(fs, file))?.isFile() === true &&
+            (await carriesOwnershipLine(fs, file))) {
+            legacy.push(name);
         }
     }
     return {
         generated: generatedStats === undefined ? "absent" : "present",
-        entry: entryStats === undefined ? "absent" : "present",
+        entries,
+        legacy,
         foreign: foreign.sort(),
     };
 }
-/** Foreign content nobody confirmed may be overwritten. */
 function foreignContentRefusal(paths, foreign) {
     const them = foreign.length === 1 ? "it" : "them";
     return new OutputWriteError("prepare", `refusing to generate into ${paths.generateAt}: ${foreign.join(", ")} ${foreign.length === 1 ? "was" : "were"} ` +
@@ -391,10 +336,6 @@ async function carriesOwnershipLine(fs, file) {
         await handle.close();
     }
 }
-/**
- * Undoes a replace that stopped part-way. When the undo itself fails, the
- * sentence says where the previous `generated/` is: the next run puts it back.
- */
 async function rollBack(paths, cause, undo) {
     try {
         await undo();
@@ -405,11 +346,6 @@ async function rollBack(paths, cause, undo) {
             `${GENERATED_DIRECTORY}/ is intact at ${paths.previous}; the next run puts it back.`, { cause });
     }
 }
-/**
- * Runs one stage, turning a filesystem error into that stage's sentence. An
- * `OutputWriteError` passes through; anything without a `code` is a defect and
- * keeps its stack.
- */
 async function stage(name, paths, run) {
     try {
         return await run();
@@ -447,16 +383,18 @@ function describe(error) {
         ? `${error.code}: ${error.message}`
         : String(error);
 }
-/**
- * Whether `AvClient.ts` and `generated/` in `generateAt` hold exactly `tree` —
- * every file byte for byte, no other file, and nothing a killed run moved aside —
- * so that writing `tree` would change nothing (Phase 12-rest Q6: "up to date").
- */
 export async function ownedOutputMatches(generateAt, tree) {
     const root = path.resolve(generateAt);
     if ((await lstatOrUndefined(fsPromises, path.join(root, PREVIOUS_GENERATED))) !== undefined) {
         return false;
     }
+    for (const name of LEGACY_CLIENT_ENTRY_FILES) {
+        const file = path.join(root, name);
+        if ((await lstatOrUndefined(fsPromises, file))?.isFile() === true &&
+            (await carriesOwnershipLine(fsPromises, file))) {
+            return false;
+        }
+    }
     let present;
     try {
         present = (await fsPromises.readdir(path.join(root, GENERATED_DIRECTORY), {
@@ -476,7 +414,7 @@ export async function ownedOutputMatches(generateAt, tree) {
         throw error;
     }
     const expected = new Set(tree.map((file) => file.path));
-    if (present.length + 1 !== expected.size ||
+    if (present.length + CLIENT_ENTRY_FILES.length !== expected.size ||
         present.some((file) => !expected.has(file))) {
         return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "0.1.0-pilot.1",
+  "version": "0.1.0-pilot.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -23,7 +23,9 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.1"
+    "@aventara/core": "0.1.0-pilot.2",
+    "c12": "3.3.4",
+    "get-tsconfig": "4.10.0"
   },
   "peerDependencies": {
     "typescript": ">=5.5.0"
@@ -37,12 +39,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "0.1.0-pilot.1",
+    "@aventara/testing": "0.1.0-pilot.2",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src"