feat: add JSON schemas and Copilot prompts for filter/override configuration#183
feat: add JSON schemas and Copilot prompts for filter/override configuration#183EMaher wants to merge 14 commits into
Conversation
…uration
- Add auto-generated JSON Schema files (schemas/extractor-config.schema.json,
schemas/override-config.schema.json) for IDE autocompletion in YAML configs
- Add scripts/generate-schemas.mjs that derives schemas from TypeScript
interfaces and runs on every build/lint/test
- Add Copilot prompt files (apiops-configure-filter, apiops-configure-overrides)
that conversationally guide users through creating filter and override files
- Update apiops init to lay down the new prompt files alongside identity setup
- Include {#[TOKEN_NAME]#} placeholder syntax guidance and Key Vault patterns
in the overrides prompt (per issue #117)
- Update docs for filtering-resources, environment-overrides, and init command
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
@copilot, have the Squad handle all the comments in this PR. |
…tect instead The overrides prompt now instructs Copilot to detect environments by scanning for existing configuration.*.yaml files before falling back to asking the user. This makes the prompt reusable outside of apiops init context. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Move the shared renderTemplate function from src/templates/shared/template-utils.ts to src/lib/render-template.ts and remove the duplicate private method from identity-guide-service.ts. All template consumers now import from the single canonical location. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR improves authoring ergonomics for APIOps filter (configuration.extractor.yaml) and override (configuration.{env}.yaml) configs by adding IDE JSON Schemas (published under schemas/v1/) and adding new GitHub Copilot “prompt” templates that apiops init scaffolds into .github/prompts/.
Changes:
- Add schema generation (
scripts/generate-schemas.mjs) and commit the generated schemas underschemas/v1/for editor autocomplete/validation. - Add Copilot prompt templates for configuring filters and environment overrides, and have
apiops initgenerate them. - Update config templates to include
yaml-language-server$schemaheaders, update packaging tests to include YAML templates, and refresh docs/devcontainer tooling.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/templates/copilot/configure-overrides-prompt.test.ts | Adds unit coverage for the overrides Copilot prompt generator. |
| tests/unit/templates/copilot/configure-filter-prompt.test.ts | Adds unit coverage for the filter Copilot prompt generator. |
| tests/unit/templates/configs/config-templates.test.ts | Verifies generated config templates include schema URLs and no unrendered placeholders. |
| tests/unit/services/init-service.test.ts | Extends init-service tests to cover prompt generation and conflict detection. |
| tests/integration/package-build/package-build.test.ts | Updates packaging test to assert YAML templates are embedded/shipped, not only markdown. |
| src/templates/copilot/identity-setup-prompt.ts | Refactors to reuse shared renderTemplate helper. |
| src/templates/copilot/configure-overrides-prompt.ts | Adds generator for the overrides Copilot prompt template (static content). |
| src/templates/copilot/configure-overrides-prompt.md | Adds the overrides Copilot prompt content to guide creating configuration.{environment}.yaml files. |
| src/templates/copilot/configure-filter-prompt.ts | Adds generator for the filter Copilot prompt template (currently static). |
| src/templates/copilot/configure-filter-prompt.md | Adds the filter Copilot prompt content to guide creating configuration.extractor.yaml. |
| src/templates/configs/schema-ref.ts | Adds helper to build versioned raw GitHub schema URLs from package.json’s schemaVersion. |
| src/templates/configs/override-config.yaml | Adds an override config template with a $schema placeholder for init-time rendering. |
| src/templates/configs/override-config.ts | Switches override config generation to embedded template + token rendering + schema URL injection. |
| src/templates/configs/filter-config.yaml | Adds a filter config template with a $schema placeholder for init-time rendering. |
| src/templates/configs/filter-config.ts | Switches filter config generation to embedded template + token rendering + schema URL injection. |
| src/services/init-service.ts | Adds generation + conflict detection for the two new Copilot prompt files during init. |
| src/services/identity-guide-service.ts | Refactors to reuse shared renderTemplate helper. |
| src/lib/render-template.ts | Introduces shared {{TOKEN}} template rendering utility. |
| scripts/generate-schemas.mjs | Adds schema generator deriving schema structure from config model field names and emitting to schemas/v<N>/. |
| scripts/embed-markdown-templates.mjs | Embeds the new Copilot prompts and the new YAML config templates into generated constants. |
| schemas/v1/override-config.schema.json | Adds the published JSON Schema for override files. |
| schemas/v1/extractor-config.schema.json | Adds the published JSON Schema for extractor filter files. |
| package.json | Adds schemaVersion and runs schema generation in prelint/prebuild/pretest. |
| docs/guides/filtering-resources.md | Documents $schema usage and points to the init-generated Copilot prompt. |
| docs/guides/environment-overrides.md | Documents $schema usage and points to the init-generated Copilot prompt (contains a duplicated schema section). |
| docs/commands/init.md | Documents new prompt files and updates “next steps” guidance to mention them. |
| .github/skills/update-config-schema-version/SKILL.md | Adds internal skill documentation for safely bumping schema versions and updating references. |
| .github/skills/codespace-multi-repo/SKILL.md | Adds internal skill documentation for multi-repo auth workflows in Codespaces/devcontainers. |
| .github/skills/codespace-clone-repo/SKILL.md | Removes the old single-repo clone skill doc (replaced by the multi-repo skill). |
| .devcontainer/devcontainer.json | Adds the Red Hat YAML extension to support schema-based autocomplete in the devcontainer. |
petehauge
left a comment
petehauge
left a comment
There was a problem hiding this comment.
Marking approve since I think all my suggestions can be done later if needed!
|
|
||
| ## Copilot-Assisted Configuration | ||
|
|
||
| If you ran `apiops init`, a Copilot prompt file was generated at `.github/prompts/apiops-configure-overrides.prompt.md`. Open it in VS Code and ask GitHub Copilot to help you configure environment overrides — it will guide you through setting up environment-specific values interactively. |
There was a problem hiding this comment.
Now that the files are separated (better design), maybe we can link to them? IE: if the user didn't start with apiops init - go for the prompt to use?
|
|
||
| ## IDE Autocompletion with JSON Schema | ||
|
|
||
| A JSON Schema is available for `configuration.{env}.yaml` override files. Add yaml-language-server comment at the top of your override file. Requires yaml language extension in VSCode. |
There was a problem hiding this comment.
This is very cool, great idea!
|
|
||
| These rules apply to **every** step below. Follow them strictly: | ||
|
|
||
| 1. **Confirm before proceeding.** At the end of every step, summarize what you |
There was a problem hiding this comment.
I'm not sure it matters, but the word wrapping here is a bit strange - like it was generated thinking that a window would be a certain width... It might be better if it was more naturally formatted and let the containing editor handle the wrapping
| @@ -0,0 +1,299 @@ | |||
| --- | |||
There was a problem hiding this comment.
Just a thought that occurred to me - I wonder if we should preface all the prompts with 'apiops', so it kind of matches the cli but it's also easier to find all of them, so /apiops-configure-overrides etc.
|
|
||
| These rules apply to **every** step below. Follow them strictly: | ||
|
|
||
| 1. **Confirm before proceeding.** At the end of every step, summarize what you |
There was a problem hiding this comment.
Similar to above, the formatting is a little strange to have artificial wrapping rather than letting the editor handle the word wrap...
|
|
||
| Before filling in any value, **ask the user** which environment variables / | ||
| pipeline variables are available for this environment, and get the **exact, | ||
| case-sensitive** token names. |
There was a problem hiding this comment.
Should we validate what the user tells us? (only if gh cli is available)?
|
|
||
| > Note: some repos use `AZURE_SUBSCRIPTION_ID` (global, no env suffix) as the | ||
| > default init-generated name. Others customize to `AZURE_SUBSCRIPTION_ID_<ENV>`. | ||
| > Ask the user which naming pattern exists in their pipeline. |
There was a problem hiding this comment.
It looks like we're asking the user for a lot of things - can we just go look at the pipeline?
| time** (for example one `resourceId` or one `value` field), not one whole | ||
| override object at a time. Do not batch multiple settings in a single prompt. | ||
|
|
||
| **Single-setting cadence for Step 4:** |
There was a problem hiding this comment.
I'd be curious how this works in practice to get tokens first and then fill in overrides after... If it feels cumbersome to the user, we could consider an approach where copilot goes over the artifacts, find things that should be overriden and then prompts the user (want a token for any part, etc), then at the end just populate any missing tokens to github environment?
| - Re-read each `configuration.{env}.yaml` file and confirm it is valid YAML | ||
| with no leftover blank values from the stubs. | ||
| - Confirm the schema comment is present as the first line of each file. | ||
| - Keep files easy to compare across environments and avoid duplicating |
There was a problem hiding this comment.
Should we also have copilot confirm that the yaml file contents matches the schema?
| - Keep files easy to compare across environments and avoid duplicating | ||
| unchanged base configuration. | ||
|
|
||
| Show the finalized files and **STOP for confirmation** before treating them as |
There was a problem hiding this comment.
In terms of 'show' - I guess it's hard because user could be in vs code terminal, github copilot, or even agent tab in github or other places. I'm curious what copilot would do in this case - if it's enough instruction then sounds good - if not, we could consider another approach like telling the user to review the files that they're correct before checking them in and that's the end of the prompt?
Motivation
When working with
configuration.extractor.yaml(filter) andconfiguration.{env}.yaml(override) files, users have no IDE autocompletion or guided workflow for building these configs correctly. This makes onboarding harder and increases the chance of typos or structural mistakes.Approach
This PR adds two complementary features:
JSON Schema files (
schemas/extractor-config.schema.json,schemas/override-config.schema.json) that provide IDE autocompletion via theyaml-language-server$schemadirective. These are auto-generated from the TypeScript interfaces on every build by a newscripts/generate-schemas.mjsscript, so they stay in sync with the code automatically.Copilot prompt files (
apiops-configure-filter.prompt.md,apiops-configure-overrides.prompt.md) that conversationally guide users through creating filter/override files. The overrides prompt covers environment promotion (dev -> stage -> prod), Key Vault references, and{#[TOKEN_NAME]#}pipeline placeholder syntax per Enable pipeline token/placeholder substitution in publish pipeline (APIOps Toolkit parity) #117.Both prompts are laid down by
apiops initalongside the existing identity setup prompt.Key changes
scripts/generate-schemas.mjs-- readsFilterConfig,ApiSubFilter,WorkspaceSubFilter, andOverrideConfigfromsrc/models/config.tsand generates both schema files. Runs as part ofprebuild/prelint/pretest.src/templates/copilot/configure-filter-prompt.mdand.ts-- prompt template for filter creationsrc/templates/copilot/configure-overrides-prompt.mdand.ts-- prompt template for override creation with token substitution guidancesrc/services/init-service.ts-- newgenerateCopilotConfigurationPrompts()method + conflict detection for the new filesdocs/commands/init.md,docs/guides/filtering-resources.md,docs/guides/environment-overrides.mdNotes
$schemacomment to work), but they are regenerated on every build from the canonical TypeScript types.extractor-config.schema.jsonfor consistency withconfiguration.extractor.yaml.$commentJSON Schema keyword carries the MIT license notice since JSON doesn't support traditional comments.