toolcraft-openapi: stop embedding spec SHA in every generated file

[kamilio]

Problem

toolcraft-openapi-generate embeds the upstream spec SHA in generated operation files:

/**
 * Generated by toolcraft-openapi.
 * spec-sha: sha256:...
 */

In poe-agent-tools, that means a spec SHA change dirties a large number of generated files even when the generated code for those operations is otherwise unchanged. The current regen after toolcraft-openapi@0.0.63 shows this clearly: many leaf files changed only because the header SHA changed.

This makes generated diffs noisy and hides the meaningful changes. A reviewer has to scan dozens of generated files to learn that most of the diff is provenance metadata, not behavioral codegen output.

Recommendation

Remove spec-sha from per-file generated headers.

The generated code files should be stable based on their actual generated content. If an operation's generated command is unchanged, that operation file should not change just because the whole input document has a new hash.

If provenance is still useful, keep it in a single generated metadata/lock location instead of stamping every file:

• existing openapi.lock with specSha, or
• a generated metadata file such as src/generated/.toolcraft-openapi.json, or
• no SHA at all if the checked-in src/generated/openapi.json is considered sufficient provenance.

My preferred shape:

1. Do not emit spec-sha comments in generated TS/JS source files.
2. Keep at most one SHA/provenance record outside the operation files, probably openapi.lock if it is actively used by the generator.
3. If the lock is not needed for generation behavior, consider removing it or making it optional. The checked-in src/generated/openapi.json plus generated source diffs are enough for normal code review.
4. Ensure the generator writes files only when their content actually changes.

Why not keep per-file SHA?

The SHA is document-level metadata, not operation-level generated code. Putting it in every generated file turns one document-level change into broad source churn. That is especially expensive in repos that check in generated sources and compiled dist output.

Acceptance criteria

• Regenerating with a different input spec SHA does not modify operation files whose generated code is otherwise identical.
• Generated operation headers no longer include spec-sha.
• If provenance is retained, it appears in only one metadata/lock file.
• Add a regression test in packages/toolcraft-openapi:
  • generate from fixture spec A;
  • generate from fixture spec B where the document hash differs but generated commands are identical;
  • assert generated operation files are byte-identical, with only the metadata/lock file changing if one is retained.
• Re-run poe-agent-tools generation and confirm diffs become focused on real generated code changes rather than global SHA churn.

[kamilio]

Fixed in ce7ca12 and released via the successful Release workflow: https://github.com/poe-platform/poe-code/actions/runs/27774761155