@techspokes/typescript-wsdl-client 0.10.1 → 0.10.4

package/README.md

@@ -35,7 +35,7 @@ npx wsdl-tsc pipeline \
   --gateway-dir ./tmp/gateway \
   --gateway-service-name weather \
   --gateway-version-prefix v1 \
-  --generate-app
+  --init-app
 ```
 
 This parses the WSDL, generates a typed SOAP client, creates an OpenAPI 3.1 spec, builds Fastify gateway handlers, and creates a runnable application.
@@ -43,7 +43,7 @@ This parses the WSDL, generates a typed SOAP client, creates an OpenAPI 3.1 spec
 ### Run and Test
 
 ```bash
-cd tmp/app && cp .env.example .env && npx tsx server.js
+cd tmp/app && npm install && cp .env.example .env && npm start
 ```
 
 ```bash

package/dist/app/generateApp.d.ts

@@ -13,6 +13,7 @@
  * @property {string} [prefix] - Route prefix (default: "")
  * @property {boolean} [logger] - Enable Fastify logger (default: true)
  * @property {"copy"|"reference"} [openapiMode] - How to handle OpenAPI file (default: "copy")
+ * @property {boolean} [force] - Overwrite existing scaffold files (default: false)
  */
 export interface GenerateAppOptions {
     clientDir: string;
@@ -26,19 +27,24 @@ export interface GenerateAppOptions {
     prefix?: string;
     logger?: boolean;
     openapiMode?: "copy" | "reference";
+    force?: boolean;
 }
 /**
- * Generates a runnable Fastify application
+ * Generates a runnable Fastify application scaffold
  *
- * This function orchestrates the complete app generation process:
+ * This function orchestrates the complete app scaffold process:
  * 1. Validates all required inputs exist
  * 2. Reads catalog.json for metadata
  * 3. Creates app directory
  * 4. Generates server.ts with Fastify setup
  * 5. Generates config.ts with environment loading
- * 6. Generates .env.example with configuration template
- * 7. Generates README.md with usage instructions
- * 8. Optionally copies OpenAPI spec into app directory
+ * 6. Generates package.json with dependencies
+ * 7. Generates tsconfig.json with TypeScript settings
+ * 8. Generates .env.example with configuration template
+ * 9. Generates README.md with usage instructions
+ * 10. Optionally copies OpenAPI spec into app directory
+ *
+ * Files that already exist are skipped unless force is true.
  *
  * @param {GenerateAppOptions} opts - App generation options
  * @returns {Promise<void>}

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

@@ -1 +1 @@
-{"version":3,"file":"generateApp.d.ts","sourceRoot":"","sources":["../../src/app/generateApp.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;GAeG;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;CACpC;AA2gBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCzE"}
+{"version":3,"file":"generateApp.d.ts","sourceRoot":"","sources":["../../src/app/generateApp.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;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;CACjB;AAymBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDzE"}

package/dist/app/generateApp.js

@@ -1,23 +1,30 @@
 // noinspection HttpUrlsUsage
 /**
- * Fastify App Generator
+ * Fastify App Scaffold Generator
  *
  * This module generates a runnable Fastify application that imports and uses
  * the generated gateway plugin and SOAP client. The app serves the OpenAPI spec,
  * health checks, and all gateway routes.
  *
+ * The generated scaffold is intended as a one-time starting point. Developers
+ * should customize it freely after generation. Use --force-init to overwrite
+ * existing scaffold files.
+ *
  * Core capabilities:
  * - Generates server.ts with Fastify setup and plugin registration
  * - Generates config.ts with environment-based configuration
+ * - Generates package.json with required dependencies
+ * - Generates tsconfig.json with NodeNext/ES2022 settings
  * - Generates .env.example with required/optional environment variables
  * - Generates README.md with instructions for running the app
  * - Optionally copies OpenAPI spec into app directory
  * - Validates required inputs (client-dir, gateway-dir, openapi-file, catalog-file)
+ * - Skip-if-exists protection for scaffold files (override with force option)
  */
 import fs from "node:fs";
 import path from "node:path";
 import { deriveClientName } from "../util/tools.js";
-import { success } from "../util/cli.js";
+import { info, success } from "../util/cli.js";
 /**
  * Validates that all required files and directories exist
  *
@@ -73,16 +80,13 @@ function getExtension(imports) {
     return "";
 }
 /**
- * Returns the file extension for executable app files (server, config)
- * These always need extensions even with bare imports since they are entry points
+ * Returns the file extension for scaffold app files (server, config).
+ * Always .ts — the scaffold is TypeScript for full type safety.
  *
- * @param {string} imports - Import mode (js, ts, or bare)
  * @returns {string} - File extension with leading dot
  */
-function getAppFileExtension(imports) {
-    if (imports === "ts")
-        return ".ts";
-    return ".js"; // Use .js for both "js" and "bare" modes
+function getAppFileExtension() {
+    return ".ts";
 }
 /**
  * Computes a relative import path from source to target
@@ -105,6 +109,48 @@ function computeRelativeImport(from, to, imports) {
     }
     return prefixed;
 }
+/**
+ * Checks if a string is a URL (http:// or https://)
+ */
+function isUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+/**
+ * Normalizes a file path to POSIX separators
+ */
+function toPosix(filePath) {
+    return filePath.split(path.sep).join("/");
+}
+/**
+ * Resolves a WSDL source path relative to the app directory.
+ * URLs are returned as-is. File paths are computed relative to appDir.
+ *
+ * @param {string} wsdlSource - Original WSDL source from catalog
+ * @param {string} appDir - Resolved app output directory
+ * @returns {string} - WSDL source suitable for use from the app directory
+ */
+function resolveWsdlSourceForApp(wsdlSource, appDir) {
+    if (isUrl(wsdlSource))
+        return wsdlSource;
+    return toPosix(path.relative(appDir, path.resolve(wsdlSource)));
+}
+/**
+ * Checks whether a scaffold file should be written.
+ * Returns true if the file does not exist or force is enabled.
+ * Logs an info message and returns false if the file exists and force is disabled.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @param {boolean} force - Whether to overwrite existing files
+ * @returns {boolean} - Whether the file should be written
+ */
+function shouldWriteScaffoldFile(filePath, force) {
+    if (!fs.existsSync(filePath))
+        return true;
+    if (force)
+        return true;
+    info(`Skipping ${path.basename(filePath)} (already exists, use --force-init to overwrite)`);
+    return false;
+}
 /**
  * Reads and parses the catalog file
  *
@@ -135,10 +181,14 @@ function getCatalogWsdlSource(catalog) {
  * @param {string} appDir - App output directory
  * @param {GenerateAppOptions} opts - App generation options
  * @param {string} clientClassName - Derived client class name
+ * @param {boolean} force - Whether to overwrite existing files
  */
-function generateServerFile(appDir, opts, clientClassName) {
+function generateServerFile(appDir, opts, clientClassName, force) {
     const imports = opts.imports || "js";
-    const ext = getAppFileExtension(imports); // Use getAppFileExtension for executable entry point
+    const ext = getAppFileExtension();
+    const filePath = path.join(appDir, `server${ext}`);
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
     const configImport = computeRelativeImport(appDir, path.join(appDir, "config"), imports);
     const gatewayPluginImport = computeRelativeImport(appDir, path.join(opts.gatewayDir, "plugin"), imports);
     const clientImport = computeRelativeImport(appDir, path.join(opts.clientDir, "client"), imports);
@@ -149,6 +199,11 @@ function generateServerFile(appDir, opts, clientClassName) {
   const openapiSpecPath = path.join(__dirname, "openapi.json");
   const openapiSpec = JSON.parse(fs.readFileSync(openapiSpecPath, "utf-8"));
 
+  // Override OpenAPI server URL at runtime if configured
+  if (config.openapiServerUrl) {
+    openapiSpec.servers = [{ url: config.openapiServerUrl }];
+  }
+
   // Serve OpenAPI specification
   fastify.get("/openapi.json", async () => {
     return openapiSpec;
@@ -158,11 +213,16 @@ function generateServerFile(appDir, opts, clientClassName) {
   const openapiSpecPath = path.resolve(__dirname, "${computeRelativeImport(appDir, opts.openapiFile, "bare")}");
   const openapiSpec = JSON.parse(fs.readFileSync(openapiSpecPath, "utf-8"));
 
+  // Override OpenAPI server URL at runtime if configured
+  if (config.openapiServerUrl) {
+    openapiSpec.servers = [{ url: config.openapiServerUrl }];
+  }
+
   fastify.get("/openapi.json", async () => {
     return openapiSpec;
   });`;
     const content = `/**
- * Generated Fastify Application
+ * Fastify Application
  *
  * This file bootstraps a Fastify server that:
  * - Loads configuration from environment variables
@@ -171,7 +231,7 @@ function generateServerFile(appDir, opts, clientClassName) {
  * - Serves the OpenAPI specification
  * - Provides health check endpoint
  *
- * Auto-generated - do not edit manually.
+ * Scaffolded by wsdl-tsc. Customize freely.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -245,7 +305,7 @@ main().catch((err) => {
   process.exit(1);
 });
 `;
-    fs.writeFileSync(path.join(appDir, `server${ext}`), content, "utf-8");
+    fs.writeFileSync(filePath, content, "utf-8");
 }
 /**
  * Generates config.ts file
@@ -253,18 +313,35 @@ main().catch((err) => {
  * @param {string} appDir - App output directory
  * @param {GenerateAppOptions} opts - App generation options
  * @param {string|undefined} defaultWsdlSource - Default WSDL source from catalog
+ * @param {boolean} force - Whether to overwrite existing files
  */
-function generateConfigFile(appDir, opts, defaultWsdlSource) {
-    const imports = opts.imports || "js";
-    const ext = getAppFileExtension(imports); // Use getAppFileExtension for executable entry point
+function generateConfigFile(appDir, opts, defaultWsdlSource, force) {
+    const ext = getAppFileExtension();
+    const filePath = path.join(appDir, `config${ext}`);
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
     const defaultHost = opts.host || "127.0.0.1";
     const defaultPort = opts.port || 3000;
     const defaultPrefix = opts.prefix || "";
     const defaultLogger = opts.logger !== false;
-    // For .js files, we need to generate plain JavaScript (no TypeScript types)
-    // For .ts files, we can use TypeScript syntax
-    const isTypeScript = ext === ".ts";
-    const typeAnnotations = isTypeScript ? `
+    // Resolve WSDL source relative to app directory
+    const resolvedWsdlSource = defaultWsdlSource
+        ? resolveWsdlSourceForApp(defaultWsdlSource, appDir)
+        : undefined;
+    // For URL sources, use as fallback default. For file sources, require explicit WSDL_SOURCE.
+    const wsdlIsUrl = resolvedWsdlSource && isUrl(resolvedWsdlSource);
+    const wsdlFallback = wsdlIsUrl ? ` || "${resolvedWsdlSource}"` : "";
+    const content = `/**
+ * Application Configuration
+ *
+ * Loads configuration from environment variables with sensible defaults.
+ * Configuration precedence:
+ * 1. Environment variables (runtime overrides)
+ * 2. Hard defaults (defined in this file)
+ *
+ * Scaffolded by wsdl-tsc. Customize freely.
+ */
+
 /**
  * Application configuration interface
  */
@@ -274,6 +351,7 @@ export interface AppConfig {
   port: number;
   prefix: string;
   logger: boolean;
+  openapiServerUrl: string;
 }
 
 /**
@@ -281,30 +359,12 @@ export interface AppConfig {
  *
  * @returns {AppConfig} - Application configuration
  * @throws {Error} If required configuration is missing
- */` : `
-/**
- * Loads configuration from environment variables
- *
- * @returns {object} - Application configuration with wsdlSource, host, port, prefix, logger
- * @throws {Error} If required configuration is missing
- */`;
-    const content = `/**
- * Application Configuration
- *
- * Loads configuration from environment variables with sensible defaults.
- * Configuration precedence:
- * 1. Environment variables (runtime overrides)
- * 2. Catalog defaults (generation-time recorded values)
- * 3. Hard defaults (defined in this file)
- *
- * Auto-generated - do not edit manually.
  */
-${typeAnnotations}
-export function loadConfig() {
-  // WSDL source: required from env or catalog default
-  const wsdlSource = process.env.WSDL_SOURCE${defaultWsdlSource ? ` || "${defaultWsdlSource}"` : ""};
+export function loadConfig(): AppConfig {
+  // WSDL source: required from env${wsdlIsUrl ? " or URL default" : ""}
+  const wsdlSource = process.env.WSDL_SOURCE${wsdlFallback};
   if (!wsdlSource) {
-    throw new Error("WSDL_SOURCE environment variable is required");
+    throw new Error("WSDL_SOURCE environment variable is required${resolvedWsdlSource && !wsdlIsUrl ? ` (hint: ${resolvedWsdlSource})` : ""}");
   }
 
   // Host: default to ${defaultHost}
@@ -322,16 +382,20 @@ export function loadConfig() {
   // Logger: default to ${defaultLogger}
   const logger = process.env.LOGGER ? process.env.LOGGER === "true" : ${defaultLogger};
 
+  // OpenAPI server URL override (replaces servers in OpenAPI spec at runtime)
+  const openapiServerUrl = process.env.OPENAPI_SERVER_URL || "";
+
   return {
     wsdlSource,
     host,
     port,
     prefix,
     logger,
+    openapiServerUrl,
   };
 }
 `;
-    fs.writeFileSync(path.join(appDir, `config${ext}`), content, "utf-8");
+    fs.writeFileSync(filePath, content, "utf-8");
 }
 /**
  * Generates .env.example file
@@ -339,23 +403,42 @@ export function loadConfig() {
  * @param {string} appDir - App output directory
  * @param {GenerateAppOptions} opts - App generation options
  * @param {string|undefined} defaultWsdlSource - Default WSDL source from catalog
+ * @param {boolean} force - Whether to overwrite existing files
  */
-function generateEnvExample(appDir, opts, defaultWsdlSource) {
+function generateEnvExample(appDir, opts, defaultWsdlSource, force) {
+    const filePath = path.join(appDir, ".env.example");
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
     const defaultHost = opts.host || "127.0.0.1";
     const defaultPort = opts.port || 3000;
     const defaultPrefix = opts.prefix || "";
     const defaultLogger = opts.logger !== false;
-    const content = `# Generated Fastify Application Environment Variables
+    // Resolve WSDL source relative to app directory
+    const resolvedWsdlSource = defaultWsdlSource
+        ? resolveWsdlSourceForApp(defaultWsdlSource, appDir)
+        : undefined;
+    const wsdlIsUrl = resolvedWsdlSource && isUrl(resolvedWsdlSource);
+    let wsdlSection;
+    if (wsdlIsUrl) {
+        // URL source: show as commented default (it's the fallback in config.ts)
+        wsdlSection = `# WSDL source URL (default: ${resolvedWsdlSource})
+#WSDL_SOURCE=${resolvedWsdlSource}`;
+    }
+    else if (resolvedWsdlSource) {
+        // File source: require explicit setting, show hint
+        wsdlSection = `# WSDL source (required — set to URL or file path)
+# Generation-time path: ${resolvedWsdlSource}
+WSDL_SOURCE=`;
+    }
+    else {
+        wsdlSection = `# WSDL source (required — set to URL or file path)
+WSDL_SOURCE=`;
+    }
+    const content = `# Fastify Application Environment Variables
 #
 # Copy this file to .env and customize as needed.
-# Configuration precedence:
-# 1. Environment variables (runtime overrides)
-# 2. Catalog defaults (generation-time recorded values)
-# 3. Hard defaults (see config file)
 
-# WSDL source (required unless provided in catalog)
-${defaultWsdlSource ? `# Default from catalog: ${defaultWsdlSource}` : "# Required: specify the WSDL URL or local file path"}
-${defaultWsdlSource ? `#WSDL_SOURCE=${defaultWsdlSource}` : `WSDL_SOURCE=`}
+${wsdlSection}
 
 # Server host (default: ${defaultHost})
 HOST=${defaultHost}
@@ -369,151 +452,162 @@ PREFIX=${defaultPrefix}
 # Enable Fastify logger (default: ${defaultLogger})
 LOGGER=${defaultLogger}
 
+# Override OpenAPI spec server URL at runtime (default: use generation-time value)
+#OPENAPI_SERVER_URL=http://localhost:${defaultPort}
+
 # Optional: SOAP security settings (configure based on your client requirements)
 # SOAP_USERNAME=
 # SOAP_PASSWORD=
 # SOAP_ENDPOINT=
 `;
-    fs.writeFileSync(path.join(appDir, ".env.example"), content, "utf-8");
+    fs.writeFileSync(filePath, content, "utf-8");
+}
+/**
+ * Generates package.json file (skipped if already exists)
+ *
+ * @param {string} appDir - App output directory
+ * @param {boolean} force - Whether to overwrite existing files
+ */
+function generatePackageJson(appDir, force) {
+    const filePath = path.join(appDir, "package.json");
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
+    const pkg = {
+        name: "wsdl-gateway-app",
+        version: "0.0.1",
+        private: true,
+        type: "module",
+        scripts: {
+            start: "tsx server.ts",
+            dev: "tsx watch server.ts",
+        },
+        dependencies: {
+            fastify: "^5.7.4",
+            "fastify-plugin": "^5.1.0",
+            soap: "^1.6.5",
+        },
+        devDependencies: {
+            tsx: "^4.21.0",
+            typescript: "^5.9.3",
+        },
+    };
+    fs.writeFileSync(filePath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+}
+/**
+ * Generates tsconfig.json file (skipped if already exists)
+ *
+ * @param {string} appDir - App output directory
+ * @param {GenerateAppOptions} opts - App generation options
+ * @param {boolean} force - Whether to overwrite existing files
+ */
+function generateTsConfig(appDir, opts, force) {
+    const filePath = path.join(appDir, "tsconfig.json");
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
+    // Compute include paths relative to app directory
+    const clientInclude = toPosix(path.relative(appDir, opts.clientDir)) + "/**/*.ts";
+    const gatewayInclude = toPosix(path.relative(appDir, opts.gatewayDir)) + "/**/*.ts";
+    const tsconfig = {
+        compilerOptions: {
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            target: "ES2022",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            outDir: "dist",
+            rootDir: ".",
+        },
+        include: [
+            "*.ts",
+            clientInclude,
+            gatewayInclude,
+        ],
+    };
+    fs.writeFileSync(filePath, JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
 }
 /**
  * Generates README.md file
  *
  * @param {string} appDir - App output directory
  * @param {GenerateAppOptions} opts - App generation options
+ * @param {boolean} force - Whether to overwrite existing files
  */
-function generateReadme(appDir, opts) {
-    const imports = opts.imports || "js";
-    const ext = getExtension(imports);
-    const runCommand = ext === ".ts"
-        ? "npx tsx server.ts"
-        : "node server.js";
+function generateReadme(appDir, opts, force) {
+    const filePath = path.join(appDir, "README.md");
+    if (!shouldWriteScaffoldFile(filePath, force))
+        return;
     const content = `# Generated Fastify Application
 
-This application was auto-generated by \`wsdl-tsc app\`.
+This application was scaffolded by \`wsdl-tsc\`. Customize freely.
 
-## Overview
+## Quick Start
 
-This Fastify application provides a REST gateway to a SOAP service, automatically bridging between REST endpoints and SOAP operations.
+\`\`\`bash
+npm install
+cp .env.example .env
+# Edit .env — set WSDL_SOURCE to your WSDL URL or file path
+npm start
+\`\`\`
 
 ## Structure
 
-- \`server${ext}\` - Main application entry point
-- \`config${ext}\` - Configuration loader (environment-based)
+- \`server.ts\` - Main application entry point
+- \`config.ts\` - Configuration loader (environment-based)
+- \`package.json\` - Dependencies and scripts
+- \`tsconfig.json\` - TypeScript configuration
 - \`.env.example\` - Example environment configuration
 - \`openapi.json\` - OpenAPI specification${opts.openapiMode === "copy" ? " (copied)" : " (referenced)"}
 
-## Prerequisites
-
-- Node.js >= 20.0.0
-- Dependencies installed (\`npm install\`)
-
-## Quick Start
-
-1. **Copy environment template**:
-   \`\`\`bash
-   cp .env.example .env
-   \`\`\`
-
-2. **Configure environment**:
-   Edit \`.env\` and set required variables (especially \`WSDL_SOURCE\` if not provided via catalog).
-
-3. **Run the server**:
-   \`\`\`bash
-   ${runCommand}
-   \`\`\`
-
 ## Endpoints
 
-### Health Check
-\`\`\`
-GET /health
-\`\`\`
-Returns: \`{ ok: true }\`
-
-### OpenAPI Specification
-\`\`\`
-GET /openapi.json
-\`\`\`
-Returns: OpenAPI 3.1 specification document
-
-### Gateway Routes
-All SOAP operations are exposed as REST endpoints. See \`openapi.json\` for complete API documentation.
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| \`/health\` | GET | Health check — returns \`{ "ok": true }\` |
+| \`/openapi.json\` | GET | OpenAPI 3.1 specification |
+| All SOAP operations | POST | REST-to-SOAP gateway routes (see openapi.json) |
 
 ## Configuration
 
-Configuration is loaded from environment variables with the following precedence:
-
-1. Environment variables (runtime overrides)
-2. Catalog defaults (from generation-time)
-3. Hard defaults (in config file)
-
-### Environment Variables
-
 | Variable | Default | Description |
 |----------|---------|-------------|
-| \`WSDL_SOURCE\` | (from catalog) | WSDL URL or local file path (required) |
+| \`WSDL_SOURCE\` | (see .env.example) | WSDL URL or local file path (required) |
 | \`HOST\` | ${opts.host || "127.0.0.1"} | Server bind address |
 | \`PORT\` | ${opts.port || 3000} | Server listen port |
-| \`PREFIX\` | ${opts.prefix || "(empty)"} | Route prefix |
+| \`PREFIX\` | (empty) | Route prefix |
 | \`LOGGER\` | ${opts.logger !== false} | Enable Fastify logger |
+| \`OPENAPI_SERVER_URL\` | (empty) | Override OpenAPI spec server URL at runtime |
 
 ## Development
 
-### Running with watch mode
-\`\`\`bash
-npx tsx watch server${ext}
-\`\`\`
-
-### Testing endpoints
 \`\`\`bash
-# Health check
-curl http://localhost:3000/health
-
-# OpenAPI spec
-curl http://localhost:3000/openapi.json
-\`\`\`
-
-## Troubleshooting
-
-### WSDL_SOURCE missing
-If you see "WSDL_SOURCE environment variable is required", set it in your \`.env\` file or export it:
-\`\`\`bash
-export WSDL_SOURCE=path/to/service.wsdl
-${runCommand}
-\`\`\`
-
-### Port already in use
-Change the \`PORT\` in your \`.env\` file or:
-\`\`\`bash
-PORT=8080 ${runCommand}
+npm run dev          # Start with file watching
+curl localhost:3000/health
+curl localhost:3000/openapi.json
 \`\`\`
 
-## Notes
-
-- This app uses the generated client from: \`${opts.clientDir}\`
-- Gateway plugin from: \`${opts.gatewayDir}\`
-- OpenAPI spec from: \`${opts.openapiFile}\`
-
 ## Generated By
 
-- Tool: [@techspokes/typescript-wsdl-client](https://github.com/TechSpokes/typescript-wsdl-client)
-- Command: \`wsdl-tsc app\`
+[@techspokes/typescript-wsdl-client](https://github.com/TechSpokes/typescript-wsdl-client)
 `;
-    fs.writeFileSync(path.join(appDir, "README.md"), content, "utf-8");
+    fs.writeFileSync(filePath, content, "utf-8");
 }
 /**
- * Generates a runnable Fastify application
+ * Generates a runnable Fastify application scaffold
  *
- * This function orchestrates the complete app generation process:
+ * This function orchestrates the complete app scaffold process:
  * 1. Validates all required inputs exist
  * 2. Reads catalog.json for metadata
  * 3. Creates app directory
  * 4. Generates server.ts with Fastify setup
  * 5. Generates config.ts with environment loading
- * 6. Generates .env.example with configuration template
- * 7. Generates README.md with usage instructions
- * 8. Optionally copies OpenAPI spec into app directory
+ * 6. Generates package.json with dependencies
+ * 7. Generates tsconfig.json with TypeScript settings
+ * 8. Generates .env.example with configuration template
+ * 9. Generates README.md with usage instructions
+ * 10. Optionally copies OpenAPI spec into app directory
+ *
+ * Files that already exist are skipped unless force is true.
  *
  * @param {GenerateAppOptions} opts - App generation options
  * @returns {Promise<void>}
@@ -529,6 +623,7 @@ export async function generateApp(opts) {
         catalogFile: path.resolve(opts.catalogFile),
         appDir: path.resolve(opts.appDir),
     };
+    const force = resolvedOpts.force ?? false;
     // Validate required files and directories
     validateRequiredFiles(resolvedOpts);
     // Read catalog for metadata
@@ -537,17 +632,27 @@ export async function generateApp(opts) {
     const defaultWsdlSource = getCatalogWsdlSource(catalog);
     // Create app directory
     fs.mkdirSync(resolvedOpts.appDir, { recursive: true });
-    // Generate app files
-    generateServerFile(resolvedOpts.appDir, resolvedOpts, clientClassName);
-    generateConfigFile(resolvedOpts.appDir, resolvedOpts, defaultWsdlSource);
-    generateEnvExample(resolvedOpts.appDir, resolvedOpts, defaultWsdlSource);
-    generateReadme(resolvedOpts.appDir, resolvedOpts);
+    // Generate scaffold files (each checks for existing files unless force is set)
+    generateServerFile(resolvedOpts.appDir, resolvedOpts, clientClassName, force);
+    generateConfigFile(resolvedOpts.appDir, resolvedOpts, defaultWsdlSource, force);
+    generatePackageJson(resolvedOpts.appDir, force);
+    generateTsConfig(resolvedOpts.appDir, resolvedOpts, force);
+    generateEnvExample(resolvedOpts.appDir, resolvedOpts, defaultWsdlSource, force);
+    generateReadme(resolvedOpts.appDir, resolvedOpts, force);
     // Handle OpenAPI file
     const openapiMode = resolvedOpts.openapiMode || "copy";
     if (openapiMode === "copy") {
         const destPath = path.join(resolvedOpts.appDir, "openapi.json");
-        fs.copyFileSync(resolvedOpts.openapiFile, destPath);
-        success(`Copied OpenAPI spec to ${destPath}`);
+        if (shouldWriteScaffoldFile(destPath, force)) {
+            const spec = JSON.parse(fs.readFileSync(resolvedOpts.openapiFile, "utf-8"));
+            const host = resolvedOpts.host || "127.0.0.1";
+            const port = resolvedOpts.port || 3000;
+            const prefix = resolvedOpts.prefix || "";
+            const urlHost = ["0.0.0.0", "127.0.0.1", "::", "::1"].includes(host) ? "localhost" : host;
+            spec.servers = [{ url: `http://${urlHost}:${port}${prefix}` }];
+            fs.writeFileSync(destPath, JSON.stringify(spec, null, 2) + "\n", "utf-8");
+            success(`Copied OpenAPI spec to ${destPath}`);
+        }
     }
-    success(`Generated runnable Fastify app in ${resolvedOpts.appDir}`);
+    success(`Scaffolded Fastify app in ${resolvedOpts.appDir}`);
 }

package/dist/cli.js

@@ -457,6 +457,11 @@ if (rawArgs[0] === "app") {
         choices: ["copy", "reference"],
         default: "copy",
         desc: "How to handle OpenAPI file: copy into app dir or reference original"
+    })
+        .option("force", {
+        type: "boolean",
+        default: false,
+        desc: "Overwrite existing scaffold files"
     })
         .strict()
         .help()
@@ -500,6 +505,7 @@ if (rawArgs[0] === "app") {
         prefix: String(appArgv.prefix),
         logger: Boolean(appArgv.logger),
         openapiMode: appArgv["openapi-mode"],
+        force: Boolean(appArgv.force),
     });
     process.exit(0);
 }
@@ -602,11 +608,21 @@ if (rawArgs[0] === "pipeline") {
         default: false,
         desc: "Skip generating runtime.ts utilities"
     })
-        // App generation flags
+        // App scaffold flags
+        .option("init-app", {
+        type: "boolean",
+        default: false,
+        desc: "Scaffold a runnable Fastify application (one-time setup, requires --client-dir, --gateway-dir, --openapi-file)"
+    })
+        .option("force-init", {
+        type: "boolean",
+        default: false,
+        desc: "Overwrite existing scaffold files when using --init-app"
+    })
         .option("generate-app", {
         type: "boolean",
         default: false,
-        desc: "Generate runnable Fastify application (requires --client-dir, --gateway-dir, --openapi-file)"
+        hidden: true, // deprecated, use --init-app
     })
         .option("app-dir", {
         type: "string",
@@ -617,6 +633,21 @@ if (rawArgs[0] === "pipeline") {
         choices: ["copy", "reference"],
         default: "copy",
         desc: "How to handle OpenAPI file in app: copy or reference"
+    })
+        .option("app-host", {
+        type: "string",
+        default: "127.0.0.1",
+        desc: "Default server host for app scaffold"
+    })
+        .option("app-port", {
+        type: "number",
+        default: 3000,
+        desc: "Default server port for app scaffold"
+    })
+        .option("app-prefix", {
+        type: "string",
+        default: "",
+        desc: "Route prefix for app scaffold"
     })
         .strict()
         .help()
@@ -662,7 +693,14 @@ if (rawArgs[0] === "pipeline") {
             fs.rmSync(clientOutDir, { recursive: true, force: true });
         }
     }
-    const servers = parseServers(pipelineArgv["openapi-servers"]);
+    // Resolve --init-app (new name) or --generate-app (deprecated alias)
+    const initApp = pipelineArgv["init-app"] || pipelineArgv["generate-app"];
+    const forceInit = pipelineArgv["force-init"];
+    let servers = parseServers(pipelineArgv["openapi-servers"]);
+    // Default OpenAPI servers to localhost when scaffolding an app and no explicit servers provided
+    if (initApp && servers.length === 0) {
+        servers = ["http://localhost:3000"];
+    }
     // Validate gateway requirements
     validateGatewayRequirements(gatewayOut, openapiOut, pipelineArgv["gateway-service-name"], pipelineArgv["gateway-version-prefix"]);
     // Parse gateway default response status codes if provided
@@ -680,11 +718,10 @@ if (rawArgs[0] === "pipeline") {
     const openApiOptions = openapiOut
         ? buildOpenApiOptionsFromArgv(pipelineArgv, format, servers)
         : undefined;
-    // Validate app generation requirements
-    const generateApp = pipelineArgv["generate-app"];
-    if (generateApp) {
+    // Validate app scaffold requirements
+    if (initApp) {
         if (!clientOut || !gatewayOut || !openapiOut) {
-            handleCLIError("--generate-app requires --client-dir, --gateway-dir, and --openapi-file to be set");
+            handleCLIError("--init-app requires --client-dir, --gateway-dir, and --openapi-file to be set");
         }
     }
     await runGenerationPipeline({
@@ -707,11 +744,15 @@ if (rawArgs[0] === "pipeline") {
             emitPlugin: pipelineArgv["gateway-skip-plugin"] ? false : undefined,
             emitRuntime: pipelineArgv["gateway-skip-runtime"] ? false : undefined,
         } : undefined,
-        app: generateApp ? {
+        app: initApp ? {
             appDir: pipelineArgv["app-dir"]
                 ? path.resolve(pipelineArgv["app-dir"])
                 : path.join(path.dirname(path.resolve(gatewayOut)), "app"),
             openapiMode: pipelineArgv["app-openapi-mode"],
+            force: forceInit,
+            host: pipelineArgv["app-host"],
+            port: pipelineArgv["app-port"],
+            prefix: pipelineArgv["app-prefix"],
         } : undefined,
     });
     process.exit(0);

package/dist/pipeline.d.ts

@@ -35,6 +35,10 @@ export interface PipelineOptions {
     app?: {
         appDir: string;
         openapiMode?: "copy" | "reference";
+        force?: boolean;
+        host?: string;
+        port?: number;
+        prefix?: string;
     };
 }
 /**

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAC,KAAK,eAAe,EAAyB,MAAM,aAAa,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1G,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;KACpC,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,GAAG,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC;CAAE,CAAC,CAmHhH"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAC,KAAK,eAAe,EAAyB,MAAM,aAAa,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1G,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;QACnC,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,GAAG,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC;CAAE,CAAC,CAuHhH"}

package/dist/pipeline.js

@@ -117,6 +117,10 @@ export async function runGenerationPipeline(opts) {
             appDir: path.resolve(opts.app.appDir),
             imports: finalCompiler.imports,
             openapiMode: opts.app.openapiMode || "copy",
+            force: opts.app.force,
+            host: opts.app.host,
+            port: opts.app.port,
+            prefix: opts.app.prefix,
         });
     }
     // Return the compiled catalog and OpenAPI doc for potential further processing

package/docs/AGENTS.md

@@ -0,0 +1,47 @@
+# Agent Instructions for docs/
+
+## Summary
+
+This directory contains human-maintained reference documentation for `@techspokes/typescript-wsdl-client`. Documents here are not generated; agents may edit them but must preserve cross-references, formatting conventions, and consistency with the root README.
+
+## Must-follow rules
+
+- Maintain cross-references between documents; when a doc mentions a related topic, link to the relevant file.
+- Use relative links for all internal references (e.g. `[CLI Reference](cli-reference.md)`, `[root README](../README.md)`).
+- Each document must open with an H1 title, a one-line description, and a cross-reference to the root [README.md](../README.md).
+- When adding, renaming, or removing a document, update the Documentation table in the root [README.md](../README.md) — that table is the single source of truth for this directory's contents.
+- Do not duplicate content from root-level files (README.md, CONTRIBUTING.md, CHANGELOG.md); link to them instead.
+
+## Must-read documents
+
+- [Root README.md](../README.md): authoritative Documentation table and project overview
+- [Root AGENTS.md](../AGENTS.md): project-wide agent instructions pointing to `.github/copilot-instructions.md` for full detail
+
+## Agent guidelines
+
+### Style conventions
+
+- Use fenced code blocks for CLI examples and inline code for flag names (`` `--flag-name` ``).
+- Keep language direct and task-oriented.
+- `architecture.md` targets contributors; all other documents target users.
+
+### Adding a new document
+
+1. Create the file in `docs/` with an H1 title and description.
+2. Add a row to the Documentation table in the root README.md.
+3. Add a bullet to the Contents list in `docs/README.md`.
+4. Cross-reference from related existing documents where appropriate.
+
+### Editing existing documents
+
+- Preserve the H1 + description + cross-reference opening pattern.
+- If renaming a file, update the root README.md Documentation table and fix any relative links in other docs.
+
+## Context
+
+The `docs/` directory was introduced in v0.8.x to move detailed reference material out of the root README. `architecture.md` covers the internal pipeline for contributors; the remaining documents serve end users integrating with or deploying generated code.
+
+## References
+
+- [examples/README.md](../examples/README.md): folder README pattern example
+- [Root README.md Documentation table](../README.md#documentation): authoritative listing of all docs

package/docs/README.md

@@ -0,0 +1,35 @@
+# Documentation
+
+Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. The root [README.md](../README.md) Documentation table is the authoritative index with descriptions; the list below is a quick local reference.
+
+## Contents
+
+- [api-reference.md](api-reference.md) – Programmatic TypeScript API
+- [architecture.md](architecture.md) – Internal pipeline for contributors
+- [cli-reference.md](cli-reference.md) – All 6 commands with flags and examples
+- [concepts.md](concepts.md) – Flattening, `$value`, primitives, determinism
+- [configuration.md](configuration.md) – Security, tags, operations config files
+- [gateway-guide.md](gateway-guide.md) – Fastify integration and error handling
+- [generated-code.md](generated-code.md) – Using clients and types
+- [migration.md](migration.md) – Upgrade paths between versions
+- [production.md](production.md) – CI/CD, validation, logging, limitations
+- [troubleshooting.md](troubleshooting.md) – Common issues and debugging
+
+## Conventions
+
+- Each document opens with an H1 title and a one-line description.
+- Cross-reference related documents and the root README where relevant.
+- Use fenced code blocks for CLI examples; format flags as inline code (`` `--flag-name` ``).
+- Keep language direct and task-oriented; architecture.md targets contributors, all others target users.
+
+## Related
+
+- [Root README](../README.md) – project overview, quick start, and authoritative Documentation table
+- [CONTRIBUTING.md](../CONTRIBUTING.md) – development setup and workflow
+- [CHANGELOG.md](../CHANGELOG.md) – version history
+- [examples/](../examples/) – sample WSDL files and generated output
+
+## Not Here
+
+- Generated code samples live in `examples/generated-output/`, not in `docs/`.
+- Installation and dev setup belong in the root README and CONTRIBUTING.md respectively.

package/docs/architecture.md

@@ -54,7 +54,7 @@ generateGateway.ts orchestrates all gateway file generation. generators.ts conta
 
 ### app/
 
-generateApp.ts generates server.js, config.js, and .env.example.
+generateApp.ts scaffolds server.ts, config.ts, package.json, tsconfig.json, .env.example, and README.md.
 
 ### Top-level Modules
 

package/docs/cli-reference.md

@@ -54,7 +54,6 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--client-dir` | Generate TypeScript client in this directory |
 | `--openapi-file` | Generate OpenAPI spec at this path |
 | `--gateway-dir` | Generate Fastify gateway in this directory |
-| `--generate-app` | Generate runnable app (requires gateway) |
 
 ### Client Flags
 
@@ -79,7 +78,10 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--openapi-title` | (derived) | API title |
 | `--openapi-version` | `0.0.0` | API version |
 | `--openapi-description` | (empty) | API description |
-| `--openapi-servers` | `/` | Comma-separated server URLs |
+| `--openapi-servers` | `/` | Comma-separated server URLs (see note below) |
+
+> When `--init-app` is used and `--openapi-servers` is not provided, servers default to `http://localhost:3000`. The app scaffold also rewrites the servers array in its local `openapi.json` copy to match the configured port and prefix.
+
 | `--openapi-base-path` | (empty) | Base path prefix |
 | `--openapi-path-style` | `kebab` | Path transform: kebab, asis, or lower |
 | `--openapi-method` | `post` | Default HTTP method |
@@ -106,6 +108,18 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--gateway-skip-plugin` | `false` | Skip plugin.ts generation |
 | `--gateway-skip-runtime` | `false` | Skip runtime.ts generation |
 
+### App Scaffold Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--init-app` | `false` | Scaffold runnable Fastify app (requires client, gateway, OpenAPI) |
+| `--force-init` | `false` | Overwrite existing scaffold files |
+| `--app-dir` | sibling `app/` | Output directory for app scaffold |
+| `--app-openapi-mode` | `copy` | How to handle OpenAPI file: copy or reference |
+| `--app-host` | `127.0.0.1` | Default server host |
+| `--app-port` | `3000` | Default server port |
+| `--app-prefix` | (empty) | Route prefix |
+
 ### Pipeline Workflow
 
 Steps execute in order:
@@ -116,7 +130,7 @@ Steps execute in order:
 4. Generate client (if --client-dir)
 5. Generate OpenAPI (if --openapi-file)
 6. Generate gateway (if --gateway-dir)
-7. Generate app (if --generate-app)
+7. Scaffold app (if --init-app)
 
 All steps share the same parsed WSDL and compiled catalog.
 
@@ -134,17 +148,17 @@ npx wsdl-tsc pipeline \
   --gateway-version-prefix v1
 ```
 
-With app generation:
+With app scaffold:
 
 ```bash
 npx wsdl-tsc pipeline \
-  --wsdl-source examples/minimal/weather.wsdl \
-  --client-dir tmp/client \
-  --openapi-file tmp/openapi.json \
-  --gateway-dir tmp/gateway \
+  --wsdl-source https://example.com/weather?wsdl \
+  --client-dir ./generated/client \
+  --openapi-file ./generated/openapi.json \
+  --gateway-dir ./generated/gateway \
   --gateway-service-name weather \
   --gateway-version-prefix v1 \
-  --generate-app
+  --init-app
 ```
 
 Client and OpenAPI only:
@@ -371,7 +385,9 @@ npx wsdl-tsc gateway \
 
 ## app
 
-Generate a runnable Fastify application integrating client, gateway, and OpenAPI spec.
+Scaffold a runnable Fastify application integrating client, gateway, and OpenAPI spec. The generated app is TypeScript and includes `package.json` and `tsconfig.json` for immediate use.
+
+Scaffold files that already exist are skipped by default. Use `--force` to overwrite.
 
 ### Usage
 
@@ -404,13 +420,16 @@ npx wsdl-tsc app \
 | `--prefix` | (empty) | Route prefix |
 | `--logger` | true | Enable Fastify logger |
 | `--openapi-mode` | copy | copy or reference |
+| `--force` | false | Overwrite existing scaffold files |
 
 ### Generated Structure
 
 ```text
 app/
-├── server.js        # Main entry point
-├── config.js        # Configuration with env support
+├── server.ts        # Main entry point (TypeScript)
+├── config.ts        # Configuration with env support
+├── package.json     # Dependencies (fastify, soap, tsx)
+├── tsconfig.json    # NodeNext/ES2022 configuration
 ├── .env.example     # Environment template
 ├── README.md        # Usage instructions
 └── openapi.json     # OpenAPI spec (when --openapi-mode=copy)
@@ -420,11 +439,12 @@ app/
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `WSDL_SOURCE` | From catalog or required | WSDL URL or path |
+| `WSDL_SOURCE` | URL fallback or required | WSDL URL or path |
 | `HOST` | 127.0.0.1 | Server bind address |
 | `PORT` | 3000 | Server listen port |
 | `PREFIX` | (empty) | Route prefix |
 | `LOGGER` | true | Fastify logger |
+| `OPENAPI_SERVER_URL` | (empty) | Override OpenAPI spec server URL at runtime |
 
 ### Endpoints
 
@@ -432,7 +452,17 @@ app/
 - `GET /openapi.json` returns the OpenAPI specification
 - All SOAP operations are exposed as REST endpoints
 
-The app can also be generated via pipeline with `--generate-app`.
+### Quick Start
+
+```bash
+cd app/
+npm install
+cp .env.example .env
+# Edit .env — set WSDL_SOURCE to your WSDL URL
+npm start
+```
+
+The app can also be scaffolded via pipeline with `--init-app`.
 
 ## compile
 

package/docs/gateway-guide.md

@@ -63,17 +63,18 @@ Route handlers call the SOAP client automatically:
 
 ```typescript
 import type { FastifyInstance } from "fastify";
+import type { GetCityForecastByZIP } from "../../client/types.js";
 import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
 import { buildSuccessEnvelope } from "../runtime.js";
 
 export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
-  fastify.route({
+  fastify.route<{ Body: GetCityForecastByZIP }>({
     method: "POST",
     url: "/get-city-forecast-by-zip",
     schema,
     handler: async (request) => {
       const client = fastify.weatherClient;
-      const result = await client.GetCityForecastByZIP(request.body);
+      const result = await client.GetCityForecastByZIP(request.body as GetCityForecastByZIP);
       return buildSuccessEnvelope(result.response);
     },
   });
@@ -117,6 +118,39 @@ All generated JSON Schemas use deterministic URN identifiers:
 
 Example: `urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse`
 
+## Multi-Service Setup
+
+When integrating multiple SOAP services, each service gets its own client, gateway, and OpenAPI spec. Register each in its own Fastify encapsulation scope to prevent decorator collisions:
+
+```typescript
+import Fastify from "fastify";
+import weatherPlugin from "./generated/weather/gateway/plugin.js";
+import inventoryPlugin from "./generated/inventory/gateway/plugin.js";
+import { Weather } from "./generated/weather/client/client.js";
+import { Inventory } from "./generated/inventory/client/client.js";
+
+const app = Fastify({ logger: true });
+
+// Each plugin gets its own scope to isolate decorators
+await app.register(async (scope) => {
+  await scope.register(weatherPlugin, {
+    client: new Weather({ source: "https://example.com/weather?wsdl" }),
+    prefix: "/api/weather",
+  });
+});
+
+await app.register(async (scope) => {
+  await scope.register(inventoryPlugin, {
+    client: new Inventory({ source: "https://example.com/inventory?wsdl" }),
+    prefix: "/api/inventory",
+  });
+});
+
+await app.listen({ port: 3000 });
+```
+
+See [`examples/fastify-gateway/`](../examples/fastify-gateway/) for a complete example.
+
 ## Contract Assumptions
 
 - All request/response bodies must use $ref to components.schemas

package/docs/generated-code.md

@@ -72,3 +72,35 @@ result.GetCityWeatherByZIPResult.Temperature;
 ```
 
 Autocomplete and type checking work across all generated interfaces.
+
+## Gateway Route Handlers
+
+When generating a Fastify gateway (`--gateway-dir`), each SOAP operation gets a fully typed route handler. The handler imports the request type from the client, uses Fastify's `Body: T` generic for type inference, and wraps the SOAP response in a standard envelope.
+
+```typescript
+import type { FastifyInstance } from "fastify";
+import type { GetCityForecastByZIP } from "../../client/types.js";
+import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
+import { buildSuccessEnvelope } from "../runtime.js";
+
+export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
+  fastify.route<{ Body: GetCityForecastByZIP }>({
+    method: "POST",
+    url: "/get-city-forecast-by-zip",
+    schema,
+    handler: async (request) => {
+      const client = fastify.weatherClient;
+      const result = await client.GetCityForecastByZIP(request.body as GetCityForecastByZIP);
+      return buildSuccessEnvelope(result.response);
+    },
+  });
+}
+```
+
+Key features of the generated handlers:
+
+- **`Body: T` generic** — Fastify infers `request.body` type from the route generic, enabling IDE autocomplete and compile-time checks
+- **JSON Schema validation** — the `schema` import provides Fastify with request/response validation at runtime, before the handler runs
+- **Envelope wrapping** — `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
+
+See [Gateway Guide](gateway-guide.md) for the full architecture and [CLI Reference](cli-reference.md) for generation flags.

package/llms.txt

@@ -47,5 +47,7 @@ npx wsdl-tsc pipeline \
 - README.md: project overview and quick start
 - CONTRIBUTING.md: development setup, project structure, testing strategy
 - docs/migration.md: upgrade paths between versions
+- .github/copilot-instructions.md: authoritative detailed agent instructions (referenced by AGENTS.md)
+- docs/README.md: documentation directory index and conventions
 - npm: https://www.npmjs.com/package/@techspokes/typescript-wsdl-client
 - GitHub: https://github.com/TechSpokes/typescript-wsdl-client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.10.1",
+  "version": "0.10.4",
   "description": "Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.",
   "keywords": [
     "wsdl",
@@ -65,25 +65,26 @@
     "smoke:client": "npm run smoke:reset && tsx src/cli.ts client --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client && tsc -p tsconfig.smoke.json",
     "smoke:openapi": "npm run smoke:reset && tsx src/cli.ts openapi --wsdl-source examples/minimal/weather.wsdl --openapi-file tmp/openapi.json --openapi-format json && tsc -p tsconfig.smoke.json",
     "smoke:gateway": "npm run smoke:reset && tsx src/cli.ts client --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client && tsx src/cli.ts openapi --catalog-file tmp/client/catalog.json --openapi-file tmp/openapi.json --openapi-format json && tsx src/cli.ts gateway --openapi-file tmp/openapi.json --client-dir tmp/client --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 && tsc -p tsconfig.smoke.json",
-    "smoke:pipeline": "npm run smoke:reset && tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client --openapi-file tmp/openapi.json --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json --openapi-servers https://example.com/api --generate-app && tsc -p tsconfig.smoke.json",
-    "smoke:app": "npm run smoke:reset && tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client --openapi-file tmp/openapi.json --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json --openapi-servers https://example.com/api && tsx src/cli.ts app --client-dir tmp/client --gateway-dir tmp/gateway --openapi-file tmp/openapi.json --app-dir tmp/app && tsc -p tsconfig.smoke.json",
-    "ci": "npm run clean && npm run build && npm run typecheck && npm run smoke:pipeline"
+    "smoke:pipeline": "npm run smoke:reset && tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client --openapi-file tmp/openapi.json --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json --init-app && tsc -p tsconfig.smoke.json",
+    "smoke:app": "npm run smoke:reset && tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client --openapi-file tmp/openapi.json --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json --openapi-servers https://example.com/api && tsx src/cli.ts app --client-dir tmp/client --gateway-dir tmp/gateway --openapi-file tmp/openapi.json --app-dir tmp/app --port 8080 && tsc -p tsconfig.smoke.json",
+    "ci": "npm run clean && npm run build && npm run typecheck && 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": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.0.2",
-    "@types/yargs": "^17.0.33",
-    "fastify": "^5.2.0",
+    "@types/node": "^25.2.0",
+    "@types/yargs": "^17.0.35",
+    "fastify": "^5.7.0",
     "fastify-plugin": "^5.1.0",
-    "rimraf": "^6.0.0",
-    "tsx": "^4.20.0",
-    "typescript": "^5.6.3"
+    "rimraf": "^6.1.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.0"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "fast-xml-parser": "^5.2.5",
+    "fast-xml-parser": "^5.3.0",
     "js-yaml": "^4.1.1",
-    "soap": "^1.3.0",
+    "soap": "^1.6.0",
     "yargs": "^18.0.0"
   },
   "funding": {