prepend api_version to schema

[lopert]

WHY are these changes introduced?

Part of https://github.com/shop/issues-shopifyvm/issues/945

When a developer bumps api_version in a function's shopify.extension.toml, the on-disk schema.graphql becomes stale. The next shopify app function build then fails with cryptic graphql-code-generator errors like:

Cannot query field "parentRelationship" on type "CartLine"

…with no indication that the underlying problem is a stale schema that just needs to be re-fetched. Today the build path is fully local — it never consults api_version and schema.graphql carries no version metadata, so staleness is undetectable.

The error surfaced gives them no actionable hint pointing at shopify app function schema.

WHAT is this pull request doing?

Stamps the api_version into schema.graphql when shopify app function schema writes it, then validates that marker against the extension's TOML at the start of every shopify app function build. When they disagree, the build aborts up-front with an actionable message instead of letting codegen fail mysteriously.

New file

• packages/app/src/cli/services/function/schema-version.ts — self-contained helpers:
  • prependSchemaVersionHeader(definition, version) — adds a # api_version: <ver> marker line to the top of the SDL.
  • readSchemaApiVersion(path) — scans the leading comment block for the marker; returns undefined for missing files or legacy schemas (no marker).
  • validateSchemaApiVersion({directory, localIdentifier, apiVersion}) — throws an AbortError with remediation when the on-disk marker disagrees with the configured api_version.

Modified files

• services/generate-schema.ts — shopify app function schema now writes the marker as the first line of the SDL (both file and stdout output).
• services/build/extension.ts — buildFunctionExtension invokes validateSchemaApiVersion once, up-front, before any function build work (typegen, esbuild, javy, wasm-opt, trampoline).

Behavior

• Mismatched marker → fails fast with:

  The schema.graphql file for <extension> was generated for api_version 2025-07 but your function is now on api_version 2025-10. Run shopify app function schema to refresh it.

• Missing schema file → no-op (out of scope for this change; codegen handles its own missing-file error).
• Legacy schema with no marker → no-op (don't break existing setups; the marker self-heals on the next shopify app function schema).

The schema header is a single line:

# api_version: 2025-10

<SDL>

How to test your changes?

• Checkout this branch
• In a Shopify app with a function (e.g. discount function), set api_version = "2025-07" in the function's shopify.extension.toml.
• Run the schema command locally, and confirm schema.graphql now starts with # api_version: 2025-07.

pnpm shopify app function schema --path /Users/lopert/code/functions/schema-sync

• Bump api_version to "2025-10" in the TOML.
• Run the build command locally, it should abort immediately with a message naming both versions and pointing at shopify app function schema.

pnpm shopify app function build --path /Users/lopert/code/functions/schema-sync

• Run the schema command again to refresh, then the build command — it should now succeed.
• Sanity check the legacy path: delete the marker line from schema.graphql (simulate an older fetched file). The build command should behave exactly as it did before this change (no false-positive abort).

Post-release steps

N/A.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset add