@aventara/client 0.0.0-stage → 0.1.0-pilot.1

package/dist/output/output.writer.js

@@ -0,0 +1,499 @@
+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 { 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,
+            warnings: [...earlier, ...this.warnings],
+        });
+    }
+}
+/**
+ * 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, [
+            ...earlier,
+            ...warningsRaisedBeforeDefect(defect),
+        ]);
+    }
+    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) ?? [])
+        : [];
+}
+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 = {
+        generateAt,
+        generated: path.join(generateAt, GENERATED_DIRECTORY),
+        entry: path.join(generateAt, CLIENT_ENTRY_FILE),
+        previous: path.join(generateAt, PREVIOUS_GENERATED),
+    };
+    const writerWarnings = [];
+    let validationWarnings = [];
+    /** The outermost directory this run created on the way to `generateAt`, if any. */
+    let created;
+    try {
+        return await writeStagedOutput();
+    }
+    catch (error) {
+        if (created !== undefined) {
+            writerWarnings.push(...(await removeCreatedDirectories(fs, generateAt, created)));
+        }
+        const said = [
+            ...input.emission.warnings,
+            ...validationWarnings,
+            ...writerWarnings,
+        ];
+        throw error instanceof OutputWriteError
+            ? error.precededBy(said)
+            : 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)));
+            const inspection = await inspectOwnedEntries(fs, paths);
+            const confirmed = new Set(input.overrideForeign ?? []);
+            const unconfirmed = inspection.foreign.filter((entry) => !confirmed.has(entry));
+            if (unconfirmed.length > 0) {
+                throw foreignContentRefusal(paths, unconfirmed);
+            }
+            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) {
+                    const target = path.join(staging, file.path);
+                    await fs.mkdir(path.dirname(target), { recursive: true });
+                    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));
+            if (validation.accepted) {
+                validationWarnings = validation.warnings;
+            }
+            else {
+                throw new OutputWriteError("validate", `the generated output failed its ${validation.checked} check, so ${LEFT_AS_THEY_WERE(paths)} ` +
+                    "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);
+                staging = ready;
+                const movedAside = state.generated === "present";
+                if (movedAside) {
+                    await fs.rename(paths.generated, paths.previous);
+                }
+                try {
+                    await fs.rename(path.join(staging, GENERATED_DIRECTORY), paths.generated);
+                }
+                catch (error) {
+                    if (movedAside) {
+                        await rollBack(paths, error, () => fs.rename(paths.previous, paths.generated));
+                    }
+                    throw error;
+                }
+                try {
+                    await fs.rename(path.join(staging, CLIENT_ENTRY_FILE), paths.entry);
+                }
+                catch (error) {
+                    await rollBack(paths, error, async () => {
+                        await fs.rename(paths.generated, path.join(staging, GENERATED_DIRECTORY));
+                        if (movedAside) {
+                            await fs.rename(paths.previous, paths.generated);
+                        }
+                    });
+                    throw error;
+                }
+            });
+            if (state.generated === "present") {
+                try {
+                    await fs.rm(paths.previous, { recursive: true, force: true });
+                }
+                catch (error) {
+                    writerWarnings.push(`the previous generated/ was replaced, but its copy at ${paths.previous} could not be removed ` +
+                        `(${describe(error)}); the next run removes it.`);
+                }
+            }
+            return {
+                generateAt: generateAt,
+                checked: validation.checked,
+                warnings: [
+                    ...input.emission.warnings,
+                    ...validationWarnings,
+                    ...writerWarnings,
+                ],
+            };
+        }
+        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.`;
+}
+/**
+ * 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) {
+        return fs.mkdir(generateAt, { recursive: true });
+    }
+    if (!stats.isDirectory()) {
+        throw notADirectory(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 {
+            await fs.rmdir(directory);
+        }
+        catch (error) {
+            return [
+                `${directory}, which this run created, could not be removed (${describe(error)}); ` +
+                    "remove it if you do not want it.",
+            ];
+        }
+        if (directory === outermost || path.dirname(directory) === directory) {
+            return [];
+        }
+    }
+}
+/**
+ * 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.`);
+            }
+            await fs.rm(leftover, { recursive: true, force: true });
+        }
+        else if (entry.startsWith(NEXT_PREFIX)) {
+            await fs.rm(leftover, { recursive: true, force: true });
+        }
+    }
+    if ((await lstatOrUndefined(fs, paths.previous)) === undefined) {
+        return warnings;
+    }
+    if ((await generatedAfterRecovery(fs, paths)) === paths.previous) {
+        await fs.rename(paths.previous, paths.generated);
+        warnings.push(`an interrupted run had moved the previous generated/ aside; it was put back at ${paths.generated} before generating.`);
+    }
+    else {
+        await fs.rm(paths.previous, { recursive: true, force: true });
+    }
+    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);
+    if (stats === undefined) {
+        return [];
+    }
+    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 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("/");
+    const generatedStats = await lstatOrUndefined(fs, generatedSource);
+    if (generatedStats !== undefined) {
+        if (!generatedStats.isDirectory()) {
+            throw new OutputWriteError("prepare", `refusing to replace ${generatedSource}: it is not a directory, and the generator owns ` +
+                `${GENERATED_DIRECTORY}/ as one; move it, or choose another \`generateAt\`. Nothing was written.`);
+        }
+        const entries = await fs.readdir(generatedSource, {
+            recursive: true,
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                continue;
+            }
+            const file = path.join(entry.parentPath, entry.name);
+            if (!entry.isFile() || !(await carriesOwnershipLine(fs, file))) {
+                foreign.push(relative(path.join(paths.generated, path.relative(generatedSource, file))));
+            }
+        }
+    }
+    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} ` +
+                "as one; move it, or choose another `generateAt`. Nothing was written.");
+        }
+        if (!(await carriesOwnershipLine(fs, paths.entry))) {
+            foreign.push(relative(paths.entry));
+        }
+    }
+    return {
+        generated: generatedStats === undefined ? "absent" : "present",
+        entry: entryStats === undefined ? "absent" : "present",
+        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"} ` +
+        `not generated by @aventara/client, and generating would overwrite or remove ${them}; confirm the ` +
+        `override, move ${them} out, or choose another \`generateAt\`. Nothing was written.`);
+}
+function notADirectory(generateAt) {
+    return new OutputWriteError("prepare", `refusing to generate into ${generateAt}: it is not a directory. ` +
+        "`generateAt` must name a directory; choose another `generateAt`. Nothing was written.");
+}
+async function carriesOwnershipLine(fs, file) {
+    const handle = await fs.open(file, "r");
+    try {
+        const head = Buffer.alloc(GENERATED_OWNERSHIP_HEAD_BYTES);
+        const { bytesRead } = await handle.read(head, 0, GENERATED_OWNERSHIP_HEAD_BYTES, 0);
+        return carriesGeneratedOwnership(head.subarray(0, bytesRead).toString("utf8"));
+    }
+    finally {
+        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();
+    }
+    catch (rollbackError) {
+        throw new OutputWriteError("replace", `the generated output could not be moved into ${paths.generateAt} (${describe(cause)}), and the ` +
+            `previous output could not be restored (${describe(rollbackError)}). The previous ` +
+            `${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();
+    }
+    catch (error) {
+        if (error instanceof OutputWriteError || !isSystemError(error)) {
+            throw error;
+        }
+        throw new OutputWriteError(name, `could not ${STAGE_ACTIONS[name]} (${describe(error)}); ${LEFT_AS_THEY_WERE(paths)}`, { cause: error });
+    }
+}
+const STAGE_ACTIONS = {
+    prepare: "inspect the generated output",
+    temp: "write the generated output to a staging directory",
+    validate: "validate the generated output",
+    replace: "replace the generated output",
+};
+async function lstatOrUndefined(fs, file) {
+    try {
+        return await fs.lstat(file);
+    }
+    catch (error) {
+        if (isSystemError(error) && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function isSystemError(error) {
+    return (error instanceof Error &&
+        typeof error.code === "string");
+}
+function describe(error) {
+    return isSystemError(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;
+    }
+    let present;
+    try {
+        present = (await fsPromises.readdir(path.join(root, GENERATED_DIRECTORY), {
+            recursive: true,
+            withFileTypes: true,
+        }))
+            .filter((entry) => !entry.isDirectory())
+            .map((entry) => path
+            .relative(root, path.join(entry.parentPath, entry.name))
+            .split(path.sep)
+            .join("/"));
+    }
+    catch (error) {
+        if (isSystemError(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+    const expected = new Set(tree.map((file) => file.path));
+    if (present.length + 1 !== expected.size ||
+        present.some((file) => !expected.has(file))) {
+        return false;
+    }
+    for (const file of tree) {
+        let bytes;
+        try {
+            bytes = await fsPromises.readFile(path.join(root, file.path));
+        }
+        catch (error) {
+            if (isSystemError(error) && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+        if (!bytes.equals(Buffer.from(file.bytes))) {
+            return false;
+        }
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@aventara/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-pilot.1",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "Development-time generator for Aventara typed remote clients.",
+  "type": "module",
+  "engines": {
+    "node": "^22.18.0 || >=24.2.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "avclient": "./dist/avclient.bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE-ADDITIONAL-PERMISSION.md"
+  ],
+  "dependencies": {
+    "@aventara/core": "0.1.0-pilot.1"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@aventara/testing": "0.1.0-pilot.1",
+    "@types/node": "24.10.1",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
+    "lint": "biome lint src"
+  }
 }