[Blueprints] Restrict Blueprint v2 file references

[adamziel]

What?

Tightens the Blueprint v2 declaration types so fields that consume a single file no longer accept directory-like data references.

This adds DataSources.FileDataReference and uses it for:

• content[].source for mysql-dump, posts, and wxr imports
• media sources
• runPHP.code
• runSQL.source
• unzip.zipFile

It also adds a type-level spec that accepts file references for those fields and rejects inline directories where a single file is required.

Why?

DataReference can point to URLs, execution-context paths, inline files, inline directories, or git paths. That is too broad for fields that are executed or imported as a single file. For example, runPHP.code cannot sensibly execute an inline directory, and unzip.zipFile needs a zip file, not a directory tree.

This does not add runtime behavior. It makes the public Blueprint v2 TypeScript contract match the shape those consumers already require.

Who benefits?

• TypeScript users authoring Blueprint v2 objects get earlier feedback for invalid declarations.
• Playground APIs that accept BlueprintV2Declaration avoid advertising impossible input shapes.
• Future schema/runner work gets a smaller, clearer distinction between "any data reference" and "one file".

Testing

• npm exec nx run playground-blueprints:typecheck
• npm exec nx run playground-blueprints:lint
• npm exec nx run playground-blueprints:test:vite -- --testFiles=packages/playground/blueprints/src/tests/v2/blueprint-v2-declaration.spec.ts
• git diff --check

Part of #2592.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Tightens Blueprint v2 TypeScript declaration types so fields that consume a single file no longer accept directory-style inline data references.

Changes:

• Introduced DataSources.FileDataReference for “single file” data references.
• Updated v2 schema fields (content[].source, media, runPHP.code, runSQL.source, unzip.zipFile) to use FileDataReference.
• Added type-level tests ensuring inline directories are rejected for some file-only fields.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
packages/playground/blueprints/src/tests/v2/blueprint-v2-declaration.spec.ts	Adds TS type tests for accepting file references and rejecting inline directories in select fields.
packages/playground/blueprints/src/lib/v2/wep-1-blueprint-v2-schema/appendix-B-data-sources.ts	Adds FileDataReference type to represent “single file” references.
packages/playground/blueprints/src/lib/v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema.ts	Replaces broad DataReference with FileDataReference for file-only schema fields.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.