@techspokes/typescript-wsdl-client 0.19.2 → 0.21.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
@@ -222,6 +223,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Testing Guide](docs/testing.md) | Testing patterns and mock client 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 |
 
 ### Extend
 
@@ -230,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.1",
+            soap: "^1.9.2",
         },
         devDependencies: {
-            "@types/node": "^25.7.0",
-            tsx: "^4.21.0",
+            "@types/node": "^25.9.0",
+            tsx: "^4.22.2",
             typescript: "^6.0.3",
         },
     };

package/docs/README.md

@@ -21,12 +21,14 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [testing.md](testing.md): testing patterns and mock client examples
 - [production.md](production.md): CI/CD, validation, logging
 - [troubleshooting.md](troubleshooting.md): common issues and debugging
+- [releases/README.md](releases/README.md): per-version GitHub release notes used by the draft release workflow
 
 ## Extend
 
 - [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

@@ -0,0 +1,53 @@
+# Release Notes
+
+Add one Markdown file per release tag. The draft release workflow requires this file before it creates or updates a GitHub draft release.
+
+## File Naming
+
+Use the Git tag as the filename:
+
+```text
+vX.Y.Z.md
+```
+
+For example, release `0.20.1` uses tag `v0.20.1` and release notes file `docs/releases/v0.20.1.md`.
+
+## File Structure
+
+Each release notes file must use this structure:
+
+```markdown
+# TypeScript WSDL Client vX.Y.Z
+
+## 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
+
+- User-facing release highlight.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- 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.20.0.md

@@ -0,0 +1,22 @@
+# TypeScript WSDL Client v0.20.0
+
+This release refreshes dependency minimums and adds a tag-driven draft release workflow so each GitHub release starts from a reviewed release notes document.
+
+## Highlights
+
+- Bump root and generated app dependency minimums for `@types/node`, `soap`, and `tsx`.
+- Add a `vX.Y.Z` tag workflow that validates the release state and creates or updates a GitHub draft release from `docs/releases/vX.Y.Z.md`.
+- Require release notes in agent and contributor guidance so the changelog, package version, tag, and release description stay synchronized.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- `npm run maint:deps`
+- `npm run ci`
+
+## Notes
+
+Release tag: `v0.20.0`.

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/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.19.2",
+  "version": "0.21.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,17 +80,20 @@
     "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.7.0",
+    "@types/node": "^25.9.0",
     "@types/yargs": "^17.0.35",
     "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0",
     "rimraf": "^6.1.3",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   },
@@ -97,7 +102,7 @@
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "saxes": "^6.0.0",
-    "soap": "^1.9.1",
+    "soap": "^1.9.2",
     "yargs": "^18.0.0"
   },
   "funding": {