@techspokes/typescript-wsdl-client 1.0.7 → 1.1.0

package/README.md

@@ -55,6 +55,8 @@ npx wsdl-tsc client \
 
 This produces `types.ts`, `client.ts`, `operations.ts`, and `utils.ts` in the output directory.
 
+Generated TypeScript includes an ESLint suppression preamble. See [generated-code linting guidance](docs/generated-code.md#generated-preambles-and-eslint) for strict policies, path exclusions, and editable scaffold ownership.
+
 ### Generate an OpenAPI spec
 
 ```bash
@@ -226,6 +228,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Production Guide](docs/production.md) | CI/CD, validation, logging |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and debugging |
 | [Release Notes](docs/releases/README.md) | Per-version GitHub release notes used by the draft release workflow |
+| [v1.1.0 Release Notes](docs/releases/v1.1.0.md) | Automatic generated TypeScript preambles and consumer lint guidance |
 
 ### Extend
 

package/dist/app/generateApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateApp.d.ts","sourceRoot":"","sources":["../../src/app/generateApp.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAuqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDzE"}
+{"version":3,"file":"generateApp.d.ts","sourceRoot":"","sources":["../../src/app/generateApp.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAuqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDzE"}

package/dist/app/generateApp.js

@@ -22,6 +22,7 @@
  * - Skip-if-exists protection for scaffold files (override with force option)
  */
 import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { deriveClientName } from "../util/tools.js";
 import { info, success } from "../util/cli.js";
@@ -306,7 +307,7 @@ main().catch((err) => {
   process.exit(1);
 });
 `;
-    fs.writeFileSync(filePath, content, "utf-8");
+    writeGeneratedSource(filePath, content, "app");
 }
 /**
  * Generates config.ts file
@@ -397,7 +398,7 @@ export function loadConfig(): AppConfig {
   };
 }
 `;
-    fs.writeFileSync(filePath, content, "utf-8");
+    writeGeneratedSource(filePath, content, "app");
 }
 function loadOptionalSecurityConfig(filePath) {
     return filePath ? loadSecurityConfigFile(filePath) : undefined;
@@ -503,7 +504,7 @@ function generateSecurityFile(appDir, opts, force) {
         return;
     const upstreamJson = JSON.stringify(securityCfg?.upstream ?? {}, null, 2);
     const content = loadRuntimeTemplate("appSecurity.tpl.txt").replace("__UPSTREAM_JSON__", upstreamJson);
-    fs.writeFileSync(filePath, content, "utf-8");
+    writeGeneratedSource(filePath, content, "app");
 }
 /**
  * Generates package.json file (skipped if already exists)

package/dist/client/generateClient.d.ts

@@ -15,6 +15,7 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  *
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or a TypeScript file cannot be written.
  */
 export declare function generateClient(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=generateClient.d.ts.map

package/dist/client/generateClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAsaxE"}
+{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QA8ZxE"}

package/dist/client/generateClient.js

@@ -12,10 +12,10 @@
  * - Support for custom attribute handling
  * - Consistent error handling and client configuration
  */
-import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { deriveClientName, pascal, pascalToSnakeCase } from "../util/tools.js";
-import { error, warn } from "../util/cli.js";
+import { warn } from "../util/cli.js";
 import { loadRuntimeSource } from "../util/runtimeSource.js";
 /**
  * Generates a TypeScript SOAP client class from a compiled WSDL catalog
@@ -33,6 +33,7 @@ import { loadRuntimeSource } from "../util/runtimeSource.js";
  *
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or a TypeScript file cannot be written.
  */
 export function generateClient(outFile, compiled) {
     const isValidIdent = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
@@ -433,22 +434,12 @@ ${methodsBody}
   }${streamMethodsBlock}
 }
 `;
-    try {
-        fs.writeFileSync(outFile, classTemplate.replace(`// noinspection JSAnnotator\n\n`, ''), "utf8");
-    }
-    catch (e) {
-        error(`Failed to write client to ${outFile}`);
-    }
+    writeGeneratedSource(outFile, classTemplate.replace(`// noinspection JSAnnotator\n\n`, ''), "client");
     // If any operation opted into streaming, drop the runtime XML parser
     // alongside the client so the generated class can import it without
     // depending on a `@techspokes/typescript-wsdl-client/runtime/...` subpath.
     if (anyStream) {
-        try {
-            const streamXmlOut = path.join(path.dirname(outFile), "streamXml.ts");
-            fs.writeFileSync(streamXmlOut, loadRuntimeSource("streamXml.ts"), "utf-8");
-        }
-        catch (e) {
-            error(`Failed to emit streamXml.ts next to ${outFile}: ${e instanceof Error ? e.message : String(e)}`);
-        }
+        const streamXmlOut = path.join(path.dirname(outFile), "streamXml.ts");
+        writeGeneratedSource(streamXmlOut, loadRuntimeSource("streamXml.ts"), "client/stream");
     }
 }

package/dist/client/generateOperations.d.ts

@@ -8,6 +8,7 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  *
  * @param outFile - Path to the output TypeScript file
  * @param compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateOperations(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=generateOperations.d.ts.map

package/dist/client/generateOperations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateOperations.d.ts","sourceRoot":"","sources":["../../src/client/generateOperations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKrE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CA8FnF"}
+{"version":3,"file":"generateOperations.d.ts","sourceRoot":"","sources":["../../src/client/generateOperations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CA0FnF"}

package/dist/client/generateOperations.js

@@ -5,9 +5,8 @@
  * This standalone interface enables mocking and testing without importing
  * the concrete SOAP client class or its runtime dependencies.
  */
-import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import { deriveClientName, pascal } from "../util/tools.js";
-import { error } from "../util/cli.js";
 import { loadRuntimeSource } from "../util/runtimeSource.js";
 /**
  * Generates an operations.ts file with a fully-typed interface for all SOAP operations
@@ -18,6 +17,7 @@ import { loadRuntimeSource } from "../util/runtimeSource.js";
  *
  * @param outFile - Path to the output TypeScript file
  * @param compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export function generateOperations(outFile, compiled) {
     const ext = compiled.options.imports ?? "bare";
@@ -95,10 +95,5 @@ ${typeImport}${streamHelper}/**
  */
 export interface ${clientName}Operations {
 ${methods.join("\n")}}\n`;
-    try {
-        fs.writeFileSync(outFile, content, "utf8");
-    }
-    catch (e) {
-        error(`Failed to write operations interface to ${outFile}`);
-    }
+    writeGeneratedSource(outFile, content, "client");
 }

package/dist/client/generateTypes.d.ts

@@ -17,6 +17,7 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  *
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateTypes(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=generateTypes.d.ts.map

package/dist/client/generateTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateTypes.d.ts","sourceRoot":"","sources":["../../src/client/generateTypes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAA0D,MAAM,+BAA+B,CAAC;AAI5H;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAsSvE"}
+{"version":3,"file":"generateTypes.d.ts","sourceRoot":"","sources":["../../src/client/generateTypes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAA0D,MAAM,+BAA+B,CAAC;AAG5H;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAkSvE"}

package/dist/client/generateTypes.js

@@ -12,8 +12,7 @@
  * - Consistent property ordering and interface structuring
  * - Optional/required markers based on XML schema requirements
  */
-import fs from "node:fs";
-import { error } from "../util/cli.js";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import { hasAttributeWildcards, wildcardAttributeBagName } from "../util/attributeWildcards.js";
 /**
  * Generates TypeScript interfaces and type aliases from a compiled WSDL catalog
@@ -33,6 +32,7 @@ import { hasAttributeWildcards, wildcardAttributeBagName } from "../util/attribu
  *
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export function generateTypes(outFile, compiled) {
     const lines = [];
@@ -308,10 +308,5 @@ export function generateTypes(outFile, compiled) {
         lines.push("}");
         lines.push("");
     }
-    try {
-        fs.writeFileSync(outFile, lines.join("\n"), "utf8");
-    }
-    catch (e) {
-        error(`Failed to write types to ${outFile}: ${e instanceof Error ? e.message : String(e)}`);
-    }
+    writeGeneratedSource(outFile, lines.join("\n"), "client");
 }

package/dist/client/generateUtils.d.ts

@@ -16,6 +16,7 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing metadata
  * @throws {Error} If metadata is missing or has an invalid structure
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export declare function generateUtils(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=generateUtils.d.ts.map

package/dist/client/generateUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateUtils.d.ts","sourceRoot":"","sources":["../../src/client/generateUtils.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAInE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAgCvE"}
+{"version":3,"file":"generateUtils.d.ts","sourceRoot":"","sources":["../../src/client/generateUtils.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAGnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QA4BvE"}

package/dist/client/generateUtils.js

@@ -10,9 +10,8 @@
  * - A DataTypes interface defining the structure of the metadata
  * - A constant containing the actual metadata mappings extracted from the compiled catalog
  */
-import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import { deriveClientName, pascalToSnakeCase } from "../util/tools.js";
-import { error } from "../util/cli.js";
 /**
  * Generates utility types and constants for XML serialization/deserialization
  *
@@ -30,6 +29,7 @@ import { error } from "../util/cli.js";
  * @param {string} outFile - Path to the output TypeScript file
  * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing metadata
  * @throws {Error} If metadata is missing or has an invalid structure
+ * @throws {Error} If a packaged preamble cannot be loaded or the TypeScript file cannot be written.
  */
 export function generateUtils(outFile, compiled) {
     const clientName = deriveClientName(compiled);
@@ -54,10 +54,5 @@ export interface ${clientName}DataTypes {
 }
 
 export const ${clientConstant}_DATA_TYPES: ${clientName}DataTypes = ${metas} as const;\n`;
-    try {
-        fs.writeFileSync(outFile, dataTypes, "utf8");
-    }
-    catch (e) {
-        error(`Failed to write utils to ${outFile}: ${e instanceof Error ? e.message : String(e)}`);
-    }
+    writeGeneratedSource(outFile, dataTypes, "client");
 }

package/dist/gateway/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}

package/dist/gateway/generators.js

@@ -11,6 +11,7 @@
  * All emitters follow deterministic generation rules for diff-friendly output.
  */
 import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { flattenAllOf, measureSchemaRefComplexity, rewriteSchemaRefs, slugName, } from "./helpers.js";
 import { detectArrayWrappers as detectArrayWrappersShared } from "../util/catalogMeta.js";
@@ -292,7 +293,7 @@ export function emitSchemasModule(outDir, modelsDir, versionSlug, serviceSlug) {
     schemasTs += `    fastify.addSchema(s as any);\n`;
     schemasTs += `  }\n`;
     schemasTs += `}\n`;
-    fs.writeFileSync(path.join(outDir, "schemas.ts"), schemasTs, "utf8");
+    writeGeneratedSource(path.join(outDir, "schemas.ts"), schemasTs, "gateway");
 }
 /**
  * Emits individual route files and routes.ts aggregator module
@@ -360,7 +361,7 @@ import type { FastifyInstance } from "fastify";
         routeTs += `    }\n`;
         routeTs += `  });\n`;
         routeTs += `}\n`;
-        fs.writeFileSync(path.join(routesDir, `${routeFileBase}.ts`), routeTs, "utf8");
+        writeGeneratedSource(path.join(routesDir, `${routeFileBase}.ts`), routeTs, "gateway/routes");
     });
     const routeFnName = `registerRoutes_${slugName(versionSlug)}_${slugName(serviceSlug)}`;
     routesTs += `\nexport async function ${routeFnName}(fastify: FastifyInstance) {\n`;
@@ -369,7 +370,7 @@ import type { FastifyInstance } from "fastify";
         routesTs += `  await ${fnName}(fastify);\n`;
     });
     routesTs += `}\n`;
-    fs.writeFileSync(path.join(outDir, "routes.ts"), routesTs, "utf8");
+    writeGeneratedSource(path.join(outDir, "routes.ts"), routesTs, "gateway/routes");
 }
 /**
  * Emits runtime.ts module with envelope builders and error handling utilities
@@ -647,7 +648,7 @@ export function createGatewayErrorHandler_${vSlug}_${sSlug}() {
 }
 `;
     const streamSection = opts?.hasStreams ? buildStreamRuntimeSection() : "";
-    fs.writeFileSync(path.join(outDir, "runtime.ts"), runtimeTs + unwrapSection + streamSection, "utf8");
+    writeGeneratedSource(path.join(outDir, "runtime.ts"), runtimeTs + unwrapSection + streamSection, "gateway/runtime");
 }
 /**
  * Returns the streaming helpers block for runtime.ts.
@@ -822,7 +823,7 @@ export default fp(${sSlug}GatewayPlugin, {
 // Named export for convenience
 export { ${sSlug}GatewayPlugin };
 `;
-    fs.writeFileSync(path.join(outDir, "plugin.ts"), pluginTs, "utf8");
+    writeGeneratedSource(path.join(outDir, "plugin.ts"), pluginTs, "gateway");
 }
 /**
  * Emits a type-check fixture that verifies plugin-client type compatibility
@@ -861,7 +862,7 @@ function _assertClientCompatible(client: ${clientMeta.className}): void {
 }
 void _assertClientCompatible;
 `;
-    fs.writeFileSync(path.join(outDir, "_typecheck.ts"), content, "utf8");
+    writeGeneratedSource(path.join(outDir, "_typecheck.ts"), content, "gateway");
 }
 /**
  * Emits individual route files with full handler implementations
@@ -973,7 +974,7 @@ ${handlerBody}
   });
 }
 `;
-        fs.writeFileSync(path.join(routesDir, `${routeFileBase}.ts`), routeTs, "utf8");
+        writeGeneratedSource(path.join(routesDir, `${routeFileBase}.ts`), routeTs, "gateway/routes");
     });
     // Generate routes.ts aggregator module
     const routeFnName = `registerRoutes_${vSlug}_${sSlug}`;
@@ -991,5 +992,5 @@ export async function ${routeFnName}(fastify: FastifyInstance): Promise<void> {
     }).join("\n");
     routesTs += `  // Register all routes\n${routeCalls}\n`;
     routesTs += `}\n`;
-    fs.writeFileSync(path.join(outDir, "routes.ts"), routesTs, "utf8");
+    writeGeneratedSource(path.join(outDir, "routes.ts"), routesTs, "gateway/routes");
 }

package/dist/generation/preamble.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates an internal resolver with an isolated cache for immutable resources.
+ * @param root - Absolute resource root; production uses only the module-relative packaged root.
+ * @returns Resolver selecting the nearest nonempty preamble, never concatenating resources.
+ * @throws If a scope is unsafe or a required/selected resource cannot be read.
+ */
+export declare function createPreambleResolver(root?: string): (artifact: string) => string;
+export declare const resolvePreamble: (artifact: string) => string;
+/**
+ * Prefixes a fresh complete source body, preserving its shebang and remaining bytes.
+ * @param body - Generator body, not an existing output file.
+ * @param preamble - Validated comment-only resource.
+ * @returns BOM-free source with one supplied preamble and a separating blank line.
+ * @constraints Embedded fragments must not pass through this composer separately.
+ */
+export declare function composeGeneratedSource(body: string, preamble: string): string;
+//# sourceMappingURL=preamble.d.ts.map

package/dist/generation/preamble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preamble.d.ts","sourceRoot":"","sources":["../../src/generation/preamble.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAmChG;AAED,eAAO,MAAM,eAAe,aArCoD,MAAM,KAAK,MAqCpC,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO7E"}

package/dist/generation/preamble.js

@@ -0,0 +1,73 @@
+/**
+ * Resolves trusted packaged TypeScript preambles by logical artifact scope.
+ * @since 1.1.0
+ * @constraints Resource content is validated by package tooling, without a runtime TypeScript dependency.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const packagedRoot = fileURLToPath(new URL("../../src/generation/preambles/", import.meta.url));
+/**
+ * Creates an internal resolver with an isolated cache for immutable resources.
+ * @param root - Absolute resource root; production uses only the module-relative packaged root.
+ * @returns Resolver selecting the nearest nonempty preamble, never concatenating resources.
+ * @throws If a scope is unsafe or a required/selected resource cannot be read.
+ */
+export function createPreambleResolver(root = packagedRoot) {
+    const absoluteRoot = path.resolve(root);
+    const cache = new Map();
+    function readResource(file, optional) {
+        try {
+            if (!fs.statSync(file).isFile())
+                throw new Error("Resource is not a regular file");
+            const content = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+            if (!content.trim())
+                throw new Error("Resource is empty");
+            return content;
+        }
+        catch (cause) {
+            if (optional && cause.code === "ENOENT")
+                return undefined;
+            throw new Error(`Could not load TypeScript preamble ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+    }
+    return (artifact) => {
+        if (!/^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/.test(artifact)) {
+            throw new Error(`Invalid preamble artifact scope: ${artifact}`);
+        }
+        const cached = cache.get(artifact);
+        if (cached !== undefined)
+            return cached;
+        const rootFile = path.join(absoluteRoot, "typescript.preamble");
+        const fallback = cache.get("") ?? readResource(rootFile, false);
+        cache.set("", fallback);
+        const segments = artifact.split("/");
+        while (segments.length > 0) {
+            const selected = readResource(path.join(absoluteRoot, ...segments, "typescript.preamble"), true);
+            if (selected !== undefined) {
+                cache.set(artifact, selected);
+                return selected;
+            }
+            segments.pop();
+        }
+        cache.set(artifact, fallback);
+        return fallback;
+    };
+}
+export const resolvePreamble = createPreambleResolver();
+/**
+ * Prefixes a fresh complete source body, preserving its shebang and remaining bytes.
+ * @param body - Generator body, not an existing output file.
+ * @param preamble - Validated comment-only resource.
+ * @returns BOM-free source with one supplied preamble and a separating blank line.
+ * @constraints Embedded fragments must not pass through this composer separately.
+ */
+export function composeGeneratedSource(body, preamble) {
+    const source = body.replace(/^\uFEFF/, "");
+    const header = preamble.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").replace(/\n+$/, "") + "\n\n";
+    if (!source.startsWith("#!"))
+        return header + source;
+    const shebang = source.match(/^#![^\r\n]*(?:\r\n|\r|\n|$)/)[0];
+    const separator = /[\r\n]$/.test(shebang) ? "" : "\n";
+    return shebang + separator + header + source.slice(shebang.length);
+}

package/dist/generation/writeGeneratedSource.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Writes a generated TypeScript file after resolving its packaged preamble.
+ * @param filePath - Destination whose parent directory already exists.
+ * @param content - Fresh complete source body.
+ * @param artifact - Logical scope, independent of the consumer output directory.
+ * @returns Nothing.
+ * @throws If resource resolution, composition, or writing fails.
+ * @constraints Call only after any scaffold skip/force guard.
+ */
+export declare function writeGeneratedSource(filePath: string, content: string, artifact: string): void;
+//# sourceMappingURL=writeGeneratedSource.d.ts.map

package/dist/generation/writeGeneratedSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeGeneratedSource.d.ts","sourceRoot":"","sources":["../../src/generation/writeGeneratedSource.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAO9F"}

package/dist/generation/writeGeneratedSource.js

@@ -0,0 +1,24 @@
+/**
+ * Applies output policy once at the complete TypeScript file boundary.
+ * @since 1.1.0
+ */
+import fs from "node:fs";
+import { composeGeneratedSource, resolvePreamble } from "./preamble.js";
+/**
+ * Writes a generated TypeScript file after resolving its packaged preamble.
+ * @param filePath - Destination whose parent directory already exists.
+ * @param content - Fresh complete source body.
+ * @param artifact - Logical scope, independent of the consumer output directory.
+ * @returns Nothing.
+ * @throws If resource resolution, composition, or writing fails.
+ * @constraints Call only after any scaffold skip/force guard.
+ */
+export function writeGeneratedSource(filePath, content, artifact) {
+    try {
+        const source = composeGeneratedSource(content, resolvePreamble(artifact));
+        fs.writeFileSync(filePath, source, "utf8");
+    }
+    catch (cause) {
+        throw new Error(`Failed to generate ${filePath} (${artifact} preamble): ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+}

package/dist/test/generateTests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateTests.d.ts","sourceRoot":"","sources":["../../src/test/generateTests.ts"],"names":[],"mappings":"AAiCA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAuBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiK7E"}
+{"version":3,"file":"generateTests.d.ts","sourceRoot":"","sources":["../../src/test/generateTests.ts"],"names":[],"mappings":"AAkCA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAuBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiK7E"}

package/dist/test/generateTests.js

@@ -12,6 +12,7 @@
  * 5. For each file: skip-if-exists check, then write
  */
 import fs from "node:fs";
+import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { info, success } from "../util/cli.js";
 import { resolveClientMeta, resolveOperationMeta, slugName } from "../gateway/helpers.js";
@@ -33,11 +34,11 @@ function shouldWriteTestFile(filePath, force) {
 /**
  * Writes a test file if it should be written (skip-if-exists with force override).
  */
-function writeTestFile(filePath, content, force) {
+function writeTestFile(filePath, content, force, artifact = "test") {
     if (!shouldWriteTestFile(filePath, force))
         return;
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, content, "utf-8");
+    writeGeneratedSource(filePath, content, artifact);
 }
 /**
  * Generates a complete Vitest test suite for the generated gateway artifacts.
@@ -117,25 +118,25 @@ export async function generateTests(opts) {
     // Emit vitest.config.ts
     writeTestFile(path.join(testDir, "vitest.config.ts"), emitVitestConfig(), force);
     // Emit helpers/mock-client.ts
-    writeTestFile(path.join(testDir, "helpers", "mock-client.ts"), emitMockClientHelper(testDir, clientDir, importsMode, clientMeta, operations, mocks), force);
+    writeTestFile(path.join(testDir, "helpers", "mock-client.ts"), emitMockClientHelper(testDir, clientDir, importsMode, clientMeta, operations, mocks), force, "test/helpers");
     // Emit helpers/test-app.ts
-    writeTestFile(path.join(testDir, "helpers", "test-app.ts"), emitTestAppHelper(testDir, gatewayDir, importsMode, clientMeta), force);
+    writeTestFile(path.join(testDir, "helpers", "test-app.ts"), emitTestAppHelper(testDir, gatewayDir, importsMode, clientMeta), force, "test/helpers");
     // Emit gateway/routes.test.ts
-    writeTestFile(path.join(testDir, "gateway", "routes.test.ts"), emitRoutesTest(testDir, importsMode, operations, mocks), force);
+    writeTestFile(path.join(testDir, "gateway", "routes.test.ts"), emitRoutesTest(testDir, importsMode, operations, mocks), force, "test/gateway");
     // Emit gateway/errors.test.ts
-    writeTestFile(path.join(testDir, "gateway", "errors.test.ts"), emitErrorsTest(testDir, importsMode, operations, mocks), force);
+    writeTestFile(path.join(testDir, "gateway", "errors.test.ts"), emitErrorsTest(testDir, importsMode, operations, mocks), force, "test/gateway");
     // Emit gateway/envelope.test.ts
-    writeTestFile(path.join(testDir, "gateway", "envelope.test.ts"), emitEnvelopeTest(testDir, importsMode, operations, mocks), force);
+    writeTestFile(path.join(testDir, "gateway", "envelope.test.ts"), emitEnvelopeTest(testDir, importsMode, operations, mocks), force, "test/gateway");
     // Emit gateway/validation.test.ts
-    writeTestFile(path.join(testDir, "gateway", "validation.test.ts"), emitValidationTest(testDir, importsMode, operations, mocks, catalog), force);
+    writeTestFile(path.join(testDir, "gateway", "validation.test.ts"), emitValidationTest(testDir, importsMode, operations, mocks, catalog), force, "test/gateway");
     // Emit runtime/classify-error.test.ts
-    writeTestFile(path.join(testDir, "runtime", "classify-error.test.ts"), emitClassifyErrorTest(testDir, gatewayDir, importsMode), force);
+    writeTestFile(path.join(testDir, "runtime", "classify-error.test.ts"), emitClassifyErrorTest(testDir, gatewayDir, importsMode), force, "test/runtime");
     // Emit runtime/envelope-builders.test.ts
-    writeTestFile(path.join(testDir, "runtime", "envelope-builders.test.ts"), emitEnvelopeBuildersTest(testDir, gatewayDir, importsMode), force);
+    writeTestFile(path.join(testDir, "runtime", "envelope-builders.test.ts"), emitEnvelopeBuildersTest(testDir, gatewayDir, importsMode), force, "test/runtime");
     // Emit runtime/unwrap.test.ts (conditional: only when ArrayOf* wrappers exist)
     const unwrapContent = emitUnwrapTest(testDir, gatewayDir, importsMode, catalog);
     if (unwrapContent) {
-        writeTestFile(path.join(testDir, "runtime", "unwrap.test.ts"), unwrapContent, force);
+        writeTestFile(path.join(testDir, "runtime", "unwrap.test.ts"), unwrapContent, force, "test/runtime");
     }
     success(`Test suite generated in ${testDir}`);
 }

package/docs/api-reference.md

@@ -4,6 +4,8 @@ All CLI commands are available as TypeScript functions. This document covers eac
 
 See the main [README](../README.md) for installation, CLI usage, and project overview.
 
+All file-producing APIs automatically apply [TypeScript preambles](generated-code.md#generated-preambles-and-eslint). Signatures and options are unchanged; existing scaffold skip/force behavior still applies. Resource and TypeScript file-write failures propagate to callers.
+
 ## compileWsdlToProject
 
 Generate a TypeScript SOAP client from WSDL.

package/docs/architecture.md

@@ -4,6 +4,16 @@ Internal architecture of the wsdl-tsc code generator for contributors.
 
 See [CONTRIBUTING](../CONTRIBUTING.md) for development setup and [README](../README.md) for user documentation.
 
+## Generated Source Policy
+
+Complete TypeScript writes pass through `src/generation/writeGeneratedSource.ts` after any scaffold ownership guard. Runtime/template loaders remain fragment loaders; provenance and documentation are preserved when the final body receives its preamble.
+
+`src/generation/preamble.ts` resolves trusted raw resources relative to this package's module location, never the consumer working directory. Logical scopes use nearest-resource fallback: `gateway/routes/typescript.preamble`, then `gateway/typescript.preamble`, then the required root `typescript.preamble`. One resource wins; resources are not concatenated. App and test overrides describe editable scaffolds.
+
+Successful resource resolutions are cached per resolver and logical scope for the process lifetime. A missing optional resource falls back, but a broken selected resource or missing required root fails generation. The writer preserves shebang placement and body text while normalizing preamble line endings and removing leading BOMs.
+
+Package validation uses the development TypeScript compiler to reject non-comment content and compiler-control directives. The generator runtime does not load that compiler. Raw `.preamble` files are included in npm packages, and `package:smoke` verifies installed generation outside the checkout during full CI. No custom resource roots or new public options are exposed.
+
 ## Pipeline Overview
 
 ```text

package/docs/cli-reference.md

@@ -8,6 +8,8 @@ Generation paths are explicit. Examples use the git-ignored `.generated/` direct
 
 The tool provides six commands for different integration scenarios.
 
+TypeScript outputs automatically receive [generated preambles](generated-code.md#generated-preambles-and-eslint), including app/test scaffolds when actually written. Command syntax is unchanged and there is no preamble flag. `compile` and `openapi` data outputs remain unchanged.
+
 | Command | Purpose | Typical Use Case |
 |---------|---------|------------------|
 | pipeline | Full pipeline: client + OpenAPI + gateway + app | CI/CD automation, complete stack generation |

package/docs/file-naming-and-path-organization.md

@@ -2,6 +2,12 @@
 
 Contributor guide for naming files and organizing fixture paths. See the root [README.md](../README.md) for the authoritative documentation index.
 
+## Preamble Resources
+
+Raw comment-only headers live under `src/generation/preambles/` with the filename `typescript.preamble`. Subdirectories express logical artifact scopes rather than consumer output paths. See [generated source policy](architecture.md#generated-source-policy) for fallback and packaging rules.
+
+Package-smoke tarballs and logs belong in `tmp/preflight/package/`; the isolated consumer installation uses a verified temporary directory outside the checkout to prove that package resources resolve independently.
+
 ## Purpose
 
 Paths should classify files before a reader opens them. The left side of a path carries the broadest concept; each segment to the right narrows the classification until the filename states the exact artifact purpose.

package/docs/generated-code.md

@@ -4,6 +4,106 @@ Guide to using the TypeScript SOAP clients and types generated by wsdl-tsc.
 
 See [README](../README.md) for quick start and [Concepts](concepts.md) for type modeling details.
 
+## Generated Preambles and ESLint
+
+Every newly written TypeScript client, gateway, app, and generated-test file starts with `/* eslint-disable */`. This includes conditional streaming/security helpers, stub routes, and gateway typecheck fixtures. CLI and programmatic generation use the same defaults with no new flags or required arguments.
+
+Generator-owned client and gateway files receive this preamble:
+
+```typescript
+/* eslint-disable */
+// Generated by @techspokes/typescript-wsdl-client.
+// Do not edit manually. Regenerate with wsdl-tsc.
+```
+
+Editable app and test scaffolds receive distinct ownership guidance:
+
+```typescript
+/* eslint-disable */
+// Scaffold generated by @techspokes/typescript-wsdl-client.
+// Customize this file. Remove eslint-disable when adopting it as maintained source.
+```
+
+Existing scaffolds are not rewritten unless their existing `--force-init` or `--force-test` option explicitly requests regeneration. Remove the directive when adopting a scaffold as maintained source, and keep that source outside globally ignored generated directories. JSON, YAML, Markdown, configuration data, and environment files do not receive preambles.
+
+### Suppression Versus Exclusion
+
+The directive suppresses ESLint rule reports when inline configuration is allowed; ESLint still parses the file. It cannot fix syntax errors, missing TypeScript parsers, or parser project-configuration errors. TypeScript compilation and checking remain enabled.
+
+`noInlineConfig: true` or `--no-inline-config` prevents the suppression from taking effect. An otherwise clean file may produce an unused-disable warning or error under `reportUnusedDisableDirectives`. Keep corporate lint policies for maintained source and globally ignore disposable generated paths when those policies conflict with the directive.
+
+### Ignore Generated Directories
+
+For projects using `eslint`, `@eslint/js`, and `typescript-eslint`, this flat configuration excludes generated client and gateway directories:
+
+```javascript
+// eslint.config.mjs
+import js from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+export default defineConfig([
+  globalIgnores([".generated/client/**", ".generated/gateway/**"]),
+  js.configs.recommended,
+  tseslint.configs.recommended,
+]);
+```
+
+Add the ignore entry to an existing configuration while retaining its presets, plugins, parser, and rules. Use `.generated/**` only when that entire directory is disposable; adopted app/test scaffolds should remain linted. Monorepos can scope generated paths explicitly, for example `packages/*/.generated/client/**`.
+
+An ignores-only entry also works as a separate item in the configuration array:
+
+```javascript
+const generatedIgnores = {
+  ignores: [".generated/client/**", ".generated/gateway/**"],
+};
+```
+
+Do not add `files`, `rules`, or `languageOptions` to this entry and expect it to remain a global exclusion. Modern flat configuration does not automatically load `.eslintignore`; the generator does not create or rewrite consumer ESLint configuration.
+
+### Mixed Source Directories
+
+When generated output shares a directory with maintained code, add an explicit ignore entry instead of broad patterns such as `**/client.ts`:
+
+```javascript
+import { globalIgnores } from "eslint/config";
+
+const generatedIgnores = globalIgnores([
+  "src/integrations/weather/client.ts",
+  "src/integrations/weather/types.ts",
+  "src/integrations/weather/operations.ts",
+  "src/integrations/weather/utils.ts",
+  "src/integrations/weather/gateway/**",
+]);
+```
+
+Include any conditional generated helpers, such as `streamXml.ts`, in your explicit paths. Dedicated generated directories make this easier to maintain.
+
+### Strict Policies and Hooks
+
+Global ignores can coexist with this separate policy entry for maintained source:
+
+```javascript
+const inlineConfigPolicy = {
+  linterOptions: {
+    noInlineConfig: true,
+    reportUnusedDisableDirectives: "error",
+  },
+};
+```
+
+For a single invocation, use `npx eslint . --ignore-pattern ".generated/client/**" --ignore-pattern ".generated/gateway/**"`. Normal configuration patterns are relative to the configuration file; CLI patterns and patterns from an alternate `--config` resolve against the working directory.
+
+Hooks that pass ignored files explicitly may produce warnings. With the ignore configuration already installed, use:
+
+```bash
+npx eslint --max-warnings 0 --no-warn-ignored .generated/client/client.ts src/app.ts
+```
+
+`--no-warn-ignored` does not create exclusions or hide lint failures in `src/app.ts`. It does not suppress unused-disable diagnostics on files ESLint actually lints.
+
+See ESLint's [ignore documentation](https://eslint.org/docs/latest/use/configure/ignore) and [configuration documentation](https://eslint.org/docs/latest/use/configure/configuration-files) for pattern and policy details.
+
 ## Client Construction
 
 ```typescript

package/docs/output-anatomy.md

@@ -2,6 +2,10 @@
 
 This document describes each file produced by the generator, what it contains, and how to work with it. For CLI flags that control output, see [CLI Reference](cli-reference.md).
 
+## TypeScript File Preambles
+
+All complete emitted TypeScript files receive one [generated preamble](generated-code.md#generated-preambles-and-eslint), including optional helpers and `_typecheck.ts`. App and generated-test scaffolds use editable-source wording and retain their existing skip/force behavior. Data outputs and existing consumer source remain unchanged.
+
 ## Generation Flow
 
 The pipeline follows this sequence: WSDL source is parsed and compiled into a catalog, then each emitter reads the catalog and produces its output.

package/docs/releases/v1.1.0.md

@@ -0,0 +1,42 @@
+# TypeScript WSDL Client v1.1.0
+
+## Generated TypeScript with explicit lint ownership
+
+This minor release adds automatic ESLint suppression preambles to newly emitted TypeScript and documents path exclusions for consumers with restrictive lint policies.
+
+## What This Improves
+
+Regenerated client and gateway files carry their ESLint directive automatically, eliminating repeated manual edits. App and generated-test scaffolds use distinct wording that explains when to remove suppression as those files become maintained source.
+
+Preambles are packaged resources selected by logical artifact scope and applied at the final file-write boundary. Resource validation and installed-package consumer tests ensure the behavior works outside the repository checkout, including conditional helpers and programmatic generation.
+
+## Highlights
+
+- Add one preamble to every complete generated TypeScript file, including streaming helpers and stub routes.
+- Preserve existing app/test files unless their existing force option requests regeneration.
+- Propagate TypeScript generation failures instead of logging write failures as successful generation.
+- Document consumer global ignores, strict inline policies, parser limitations, and hook behavior.
+- Verify real ESLint suppression alongside maintained-source controls and installed-package tests.
+
+## Upgrade Notes
+
+CLI syntax, public API signatures, catalog semantics, and runtime behavior are unchanged. Regeneration adds a comment preamble to TypeScript output; existing editable scaffolds retain their current contents unless explicitly regenerated.
+
+`/* eslint-disable */` suppresses rule reports only when inline configuration is allowed. It does not bypass parsing or TypeScript checking, and clean files may produce unused-disable diagnostics. Use the [consumer ESLint guidance](../generated-code.md#generated-preambles-and-eslint) to exclude generated paths while keeping maintained-source policies intact.
+
+Remove the suppression when adopting an app or test scaffold as maintained source, and keep adopted files outside ignored generated directories. No runtime or schema migration is required.
+
+## Validation
+
+- Generated-file, resource-validation, and ESLint tests passed on Node 24 and Node 26.
+- Full CI, generated-artifact conformance, and pipeline smoke validation passed.
+- Installed tarball generation, consumer typechecking, and generated tests passed outside the checkout.
+- NPM package contents and comment-only resources were validated.
+- The agent skill artifact was validated and packaged with the new consumer guidance.
+- Release preflight passed against the target tag.
+
+## Notes
+
+Release tag: `v1.1.0`.
+
+Implements [issue #142](https://github.com/TechSpokes/typescript-wsdl-client/issues/142).

package/docs/testing.md

@@ -4,6 +4,8 @@ Guide to running and writing tests for wsdl-tsc development and for testing gene
 
 See [README](../README.md) for quick start and [CONTRIBUTING](../CONTRIBUTING.md) for development setup.
 
+Generated test files receive an [editable scaffold preamble](generated-code.md#generated-preambles-and-eslint). Remove its ESLint suppression when adopting the tests as maintained source; existing files are preserved unless `--force-test` is used. Full local CI includes `package:smoke`, which installs a tarball outside the checkout and validates generation, consumer compilation, and generated tests.
+
 ## Test Architecture
 
 The project uses three layers of testing:

package/docs/troubleshooting.md

@@ -4,6 +4,14 @@ Common issues and debugging guidance for wsdl-tsc.
 
 See [README](../README.md) for quick start and [CLI Reference](cli-reference.md) for command details.
 
+## Generated Files and ESLint
+
+If the generated directive appears ineffective, check `noInlineConfig` and `--no-inline-config`. Unused-disable diagnostics can occur on files with no rule violations. Parser or TypeScript project errors are not rule reports and cannot be suppressed by the header.
+
+Use the [generated-code ESLint guidance](generated-code.md#generated-preambles-and-eslint) for global exclusions that preserve maintained-source policies, explicit-file hook warnings, and scaffold adoption. Do not disable TypeScript checking or weaken lint policy globally to accommodate generated output.
+
+A missing, empty, or unreadable packaged preamble fails generation with the resource and destination path. Reinstall the intact package; do not edit `node_modules` or patch generated files to work around a damaged installation.
+
 ## Common Issues
 
 | Symptom | Resolution |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",
@@ -57,7 +57,8 @@
     "LICENSE",
     "llms.txt",
     "src/runtime/*.ts",
-    "src/runtime/*.tpl.txt"
+    "src/runtime/*.tpl.txt",
+    "src/generation/preambles/**/*.preamble"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",
@@ -95,22 +96,26 @@
     "skill:validate": "node scripts/validate-agent-skill.mjs",
     "skill:package": "node scripts/build-agent-skill.mjs",
     "package:validate": "node scripts/validate-npm-package.mjs",
+    "package:smoke": "node scripts/smoke-npm-package.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:publish-check": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate",
-    "ci": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run && npm run smoke:pipeline",
+    "ci": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && npm run docs:validate && vitest run && npm run smoke:pipeline && npm run package:smoke",
     "ci:github": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && npm run docs:validate && npm run test:github && npm run smoke:pipeline",
     "ci:github:node26": "npm run clean && npm run build && npm run typecheck && npm run test:unit && npm run smoke:pipeline",
     "examples:regenerate": "tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir examples/generated-output/client --openapi-file examples/generated-output/openapi.json --gateway-dir examples/generated-output/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^26.6.2",
     "@types/yargs": "^17.0.35",
+    "eslint": "^10.11.0",
     "fastify": "^5.12.5",
     "fastify-plugin": "^6.0.0",
     "rimraf": "^6.1.3",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.1"
   },
   "dependencies": {

package/src/generation/preambles/app/typescript.preamble

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Scaffold generated by @techspokes/typescript-wsdl-client.
+// Customize this file. Remove eslint-disable when adopting it as maintained source.

package/src/generation/preambles/test/typescript.preamble

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Scaffold generated by @techspokes/typescript-wsdl-client.
+// Customize this file. Remove eslint-disable when adopting it as maintained source.

package/src/generation/preambles/typescript.preamble

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Generated by @techspokes/typescript-wsdl-client.
+// Do not edit manually. Regenerate with wsdl-tsc.