@techspokes/typescript-wsdl-client 0.20.0 → 0.22.0

package/README.md

@@ -29,6 +29,7 @@ Most tools in this space stop at one layer: a SOAP runtime, type generation, or
 - Generated `operations.ts` interface enables testing without importing `soap` or calling a live service
 - OpenAPI is a first-class output, not an afterthought; types, schemas, and descriptions stay aligned
 - Opt-in NDJSON streaming for large SOAP responses: client emits `AsyncIterable<RecordType>`, gateway flushes records incrementally, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
+- Optional agent skill ZIP for consumer-project AI agents that need package-specific generation guidance
 - MIT licensed; generated code is yours with no attribution required
 
 ## Installation
@@ -231,6 +232,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Programmatic API](docs/api-reference.md) | TypeScript functions for build tools |
 | [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
 | [Architecture](docs/architecture.md) | Internal pipeline for contributors |
+| [Agent Skill Artifact](docs/agent-skill.md) | Release ZIP for consumer-project AI agents |
 | [Streamable Responses (ADR-002)](docs/decisions/002-streamable-responses.md) | Opt-in streaming: client `AsyncIterable`, gateway NDJSON, `x-wsdl-tsc-stream` |
 | [Version Migration](docs/migration.md) | Upgrading between package versions |
 

package/dist/app/generateApp.js

@@ -512,11 +512,11 @@ function generatePackageJson(appDir, force) {
             fastify: "^5.8.5",
             "fastify-plugin": "^5.1.0",
             saxes: "^6.0.0",
-            soap: "^1.9.2",
+            soap: "^1.9.3",
         },
         devDependencies: {
-            "@types/node": "^25.9.0",
-            tsx: "^4.22.2",
+            "@types/node": "^25.9.1",
+            tsx: "^4.22.3",
             typescript: "^6.0.3",
         },
     };

package/docs/README.md

@@ -28,6 +28,7 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [api-reference.md](api-reference.md): programmatic TypeScript API
 - [concepts.md](concepts.md): flattening, `$value`, primitives, determinism
 - [architecture.md](architecture.md): internal pipeline for contributors
+- [agent-skill.md](agent-skill.md): release ZIP for consumer-project AI agents
 - [decisions/002-streamable-responses.md](decisions/002-streamable-responses.md): opt-in streaming design (client `AsyncIterable`, gateway NDJSON, `x-wsdl-tsc-stream` OpenAPI extension); shipped in 0.17.0
 - [migration.md](migration.md): upgrading between package versions
 

package/docs/agent-skill.md

@@ -0,0 +1,81 @@
+# Agent Skill Artifact
+
+Standalone agent skill artifact for consumer projects using `@techspokes/typescript-wsdl-client`. See the root [README.md](../README.md) for the authoritative documentation index.
+
+## Purpose
+
+Release assets include a ZIP named `typescript-wsdl-client-agent-skill-vX.Y.Z.zip`. The ZIP contains an installable `typescript-wsdl-client/` skill folder that helps AI agents in consumer projects generate clients, OpenAPI specs, gateways, apps, tests, and catalogs from WSDL or catalog inputs.
+
+The skill is for consumer-project agents. It tells agents how to choose `wsdl-tsc` commands, handle generated output boundaries, load reference material, and validate generated code without treating generated files as hand-maintained source.
+
+## Packaged Shape
+
+```text
+typescript-wsdl-client/
+  SKILL.md
+  install.mjs
+  references/
+    architecture.md
+    consumer-workflows.md
+    cli-reference.md
+    generated-code.md
+    testing.md
+    troubleshooting.md
+    streaming.md
+    SOURCE-MAP.json
+```
+
+## Evergreen Content
+
+Evergreen content lives under `agent-skill/` and is reviewed as source code. Update evergreen files only when stable agent workflow, architecture guidance, dependency rules, or generated-output safety rules change.
+
+The evergreen files are `agent-skill/SKILL.md`, `agent-skill/install.mjs`, `agent-skill/evergreen/architecture.md`, and `agent-skill/evergreen/consumer-workflows.md`.
+
+## Fluid References
+
+Fluid references are generated from maintained repository docs during validation and release packaging. Repository docs remain the single source of truth for command flags, generated-code details, testing guidance, troubleshooting steps, and streaming behavior.
+
+Do not maintain `agent-skill/references/` by hand. The package scripts generate packaged references under `dist/`.
+
+## Installation
+
+Download the release ZIP from the GitHub draft or published release, extract it, and run the installer from the extracted skill folder:
+
+```bash
+node install.mjs --target ./skills
+```
+
+Use `--name <folder-name>` to choose a different installed folder name. Use `--force` only when replacing an existing installed copy.
+
+The installer copies only the skill folder. It does not edit Codex, Claude, IDE, MCP, shell, or global configuration files.
+
+## Maintainer Workflow
+
+Update `agent-skill/reference-manifest.json` when packaged references need new or different source sections. Each entry declares whether content is evergreen or fluid, where it comes from, where it is packaged, which headings or marker ranges are extracted, and whether links are rewritten.
+
+Use exact reusable headings in docs when possible. Add marker ranges such as `<!-- agent-skill:start stream-configuration -->` only when heading extraction would be too broad.
+
+## Validation
+
+Run the validation script before release packaging:
+
+```bash
+npm run skill:validate
+```
+
+Validation checks skill frontmatter, manifest sources, extracted headings, packaged Markdown structure, packaged links, forbidden files, deterministic staged output, and oversized evergreen duplication of fluid references.
+
+## Packaging
+
+Package the release skill with the exact release tag. For the `0.21.0` release:
+
+```bash
+npm run skill:package -- v0.21.0
+```
+
+The script requires the tag to match `package.json` and writes `dist/assets/typescript-wsdl-client-agent-skill-v0.21.0.zip`.
+
+## Drift Control
+
+Changing an extracted docs section changes the packaged reference on the next package run. Renaming or removing an extracted heading fails validation. Packaged links must resolve after rewrite, and `references/SOURCE-MAP.json` records the source path, output path, and extracted sections for each packaged reference.
+

package/docs/releases/README.md

@@ -19,7 +19,13 @@ Each release notes file must use this structure:
 ```markdown
 # TypeScript WSDL Client vX.Y.Z
 
-Short summary paragraph.
+## Short agent-generated subtitle
+
+A concise summary paragraph.
+
+## What This Improves
+
+Explain the practical developer impact of the release. Focus on what becomes easier, safer, clearer, more reliable, or more complete for developers using or maintaining this package.
 
 ## Highlights
 
@@ -31,12 +37,17 @@ No special upgrade steps.
 
 ## Validation
 
-- `npm run maint:deps`
-- `npm run ci`
+- CI passed.
+- NPM package contents were validated.
+- Agent skill artifact was validated and packaged.
 
 ## Notes
 
 Release tag: `vX.Y.Z`.
 ```
 
+Keep the H1 in the repository file so each release note remains a complete source document. The draft release workflow strips only that H1 when generating the GitHub release body, so the GitHub page uses `TypeScript WSDL Client vX.Y.Z` as the release title and starts the body with the H2 subtitle.
+
+Write validation as consumer-facing outcomes, not as maintainer command transcripts. Keep exact release operator commands in `.github/copilot-instructions.md` and workflow logs.
+
 Write release notes for users and maintainers, not as a file-by-file change log. Use `CHANGELOG.md` for the canonical version history.

package/docs/releases/v0.21.0.md

@@ -0,0 +1,30 @@
+# TypeScript WSDL Client v0.21.0
+
+## Standalone Agent Skill Artifacts
+
+This release adds a drift-controlled standalone AI agent skill artifact for consumer projects that use `@techspokes/typescript-wsdl-client`.
+
+## What This Improves
+
+Developers can install release-matched agent guidance alongside the package, which makes generated-client workflows easier to apply in consumer repositories. Maintainers also get validation and packaging checks that keep the skill artifact aligned with the repository docs before a release is drafted.
+
+## Highlights
+
+- Adds a release ZIP with an installable `typescript-wsdl-client` agent skill.
+- Generates fluid skill references from maintained repository docs during validation and packaging.
+- Keeps evergreen agent workflow guidance separate from documentation-derived CLI, generated-code, testing, troubleshooting, and streaming references.
+- Updates the draft release workflow to upload the skill ZIP with each tagged draft release.
+
+## Upgrade Notes
+
+No runtime upgrade steps are required. Consumers can download the skill ZIP from the GitHub release and install it into their agent host's skill directory.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Agent skill artifact was validated and packaged.
+
+## Notes
+
+Release tag: `v0.21.0`.

package/docs/releases/v0.22.0.md

@@ -0,0 +1,30 @@
+# TypeScript WSDL Client v0.22.0
+
+## Release Workflow And Dependency Refresh
+
+This release refreshes dependency pins from the recent bot merges and carries forward release documentation improvements for the packaged agent skill workflow.
+
+## What This Improves
+
+Maintainers get a release flow whose generated draft bodies use validated release-note subtitles and consumer-facing validation language. Consumer projects generated by the app scaffold also receive newer SOAP runtime and TypeScript execution pins without manual dependency editing.
+
+## Highlights
+
+- Updates root pins to `@types/node` 25.9.1, `soap` 1.9.3, `tsx` 4.22.3, and `vitest` 4.1.7.
+- Updates app scaffold pins to `@types/node` 25.9.1, `soap` 1.9.3, and `tsx` 4.22.3.
+- Renders draft release bodies from validated release-note subtitles.
+- Describes release validation as consumer-facing outcomes and surfaces the standalone agent skill artifact in docs.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Agent skill artifact was validated and packaged.
+
+## Notes
+
+Release tag: `v0.22.0`.

package/docs/start-here.md

@@ -96,6 +96,12 @@ Stream operations return `StreamOperationResponse<RecordType>` on the client (`r
 
 Next: [ADR-002: Streamable Responses](decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
 
+### I want an AI agent to help in my project
+
+Release assets include an optional `typescript-wsdl-client` agent skill ZIP for consumer-project AI agents. Install it when you want an agent to choose `wsdl-tsc` commands, respect generated-output boundaries, load package reference docs, and validate generated clients, OpenAPI specs, gateways, apps, tests, or catalogs in your repository.
+
+Next: [Agent Skill Artifact](agent-skill.md) for package contents, installation, and maintainer validation details.
+
 ## What NOT to Expect
 
 This package does not replace a full API management platform. It does not provide rate limiting, policy enforcement, or multi-language SDK generation. It generates code; it does not run a proxy or manage deployments.
@@ -113,3 +119,4 @@ For more on scope boundaries, see the "When NOT to Use This" section of the [REA
 | Set up testing for generated code | [Testing Guide](testing.md) |
 | Review all CLI flags | [CLI Reference](cli-reference.md) |
 | Opt specific operations into NDJSON streaming | [ADR-002](decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
+| Install package-specific agent guidance | [Agent Skill Artifact](agent-skill.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.20.0",
+  "version": "0.22.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",
@@ -49,7 +49,9 @@
     }
   },
   "files": [
-    "dist",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
     "docs",
     "README.md",
     "LICENSE",
@@ -69,7 +71,7 @@
     "test:snap": "vitest run test/snapshot",
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run clean && npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm run package:validate",
     "smoke:reset": "npm run clean:tmp",
     "smoke:compile": "npm run smoke:reset && tsx src/cli.ts compile --wsdl-source examples/minimal/weather.wsdl --catalog-file tmp/catalog.json",
     "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",
@@ -78,26 +80,29 @@
     "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",
     "maint:deps": "node scripts/maint-deps.mjs",
-    "ci": "npm run clean && npm run build && npm run typecheck && vitest run && npm run smoke:pipeline",
+    "skill:validate": "node scripts/validate-agent-skill.mjs",
+    "skill:package": "node scripts/build-agent-skill.mjs",
+    "package:validate": "node scripts/validate-npm-package.mjs",
+    "ci": "npm run clean && npm run build && npm run typecheck && npm run skill:validate && npm run package:validate && vitest run && 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.9.0",
+    "@types/node": "^25.9.1",
     "@types/yargs": "^17.0.35",
     "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.2",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.7"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "saxes": "^6.0.0",
-    "soap": "^1.9.2",
+    "soap": "^1.9.3",
     "yargs": "^18.0.0"
   },
   "funding": {