<!-- markdownlint-disable MD025 -->

Overview

Generate or update a deterministic Insomnia collection for NestJS GraphQL repos. Analyze schema and resolvers, maintain insomnia/generate-insomnia.js using the skill template as the starting point, and produce insomnia/Insomnia_YYYY-MM-DD.yaml.

The target repo's insomnia/ folder should contain only these generated files:

1. insomnia/generate-insomnia.js
2. insomnia/Insomnia_YYYY-MM-DD.yaml

Do not create or persist generate-insomnia.template.js, example-insomnia-collection.yaml, or any other support files outside the skill templates directory.

Templates

Supporting templates are provided in .codex/skills/insomnia-collection-generator/templates/ for agent use during generation:

Template	Purpose
generate-insomnia.template.js	Starting implementation for the collection generator script. Contains CONFIG block and customization points that the agent adapts to the target repo.
example-insomnia-collection.yaml	YAML structure source of truth that defines the expected output format including environments, folders, and request structure.
tasks.template.json	Template VS Code tasks configuration for running the generator. Optionally mirror into the target repo's .vscode/tasks.json when the repo does not already have an equivalent task.

Usage

1. Read .codex/skills/insomnia-collection-generator/templates/generate-insomnia.template.js as the starting point for script generation.
2. Read .codex/skills/insomnia-collection-generator/templates/example-insomnia-collection.yaml as the YAML structure source of truth.
3. Optionally mirror .codex/skills/insomnia-collection-generator/templates/tasks.template.json into the target repo's .vscode/tasks.json when the repo does not already have an equivalent task.
4. Use the Insomnia Collection Generator agent to analyze the repo and produce the collection.

Configuration

Edit only this block for repo-specific values.

COLLECTION_NAME: GraphQL API Collection
TOP_LEVEL_FOLDER: GraphQL Operations
OUTPUT_PATH_TEMPLATE: insomnia/Insomnia_YYYY-MM-DD.yaml
EXAMPLE_COLLECTION_PATH: .codex/skills/insomnia-collection-generator/templates/example-insomnia-collection.yaml
SCHEMA_CANDIDATES: [src/schema.gql, schema.gql]
RESOLVER_ROOTS: [src/modules, src]        # more-specific paths first
RESOLVER_FILE_PATTERN: "**/*.resolver.ts"
SCRIPT_PATH: insomnia/generate-insomnia.js
TEMPLATE_PATH: .codex/skills/insomnia-collection-generator/templates/generate-insomnia.template.js
REQUIRE_RESOLVER_ANALYSIS: true
FAIL_ON_UNMAPPED_SCHEMA_OPERATIONS: true
PACKAGE_MANAGER: auto
FIELD_VALUE_OVERRIDES: {}                  # hard-code specific field values here

ENVIRONMENTS:
  - { key: LOCAL,  label: Local,  base_url_var: BASE_URL_LOCAL,  client_id_var: CLIENT_ID_LOCAL,  client_secret_var: CLIENT_SECRET_LOCAL,  graphql_path: /graphql,               token_path: /auth/oauth/token }
  - { key: DEV,    label: Dev,    base_url_var: BASE_URL_DEV,    client_id_var: CLIENT_ID_DEV,    client_secret_var: CLIENT_SECRET_DEV,    graphql_path: /{REPO_NAME}/graphql,   token_path: /auth/oauth/token }
  - { key: TEST,   label: Test,   base_url_var: BASE_URL_TEST,   client_id_var: CLIENT_ID_TEST,   client_secret_var: CLIENT_SECRET_TEST,   graphql_path: /{REPO_NAME}/graphql,   token_path: /auth/oauth/token }
  - { key: STAGE,  label: Stage,  base_url_var: BASE_URL_STAGE,  client_id_var: CLIENT_ID_STAGE,  client_secret_var: CLIENT_SECRET_STAGE,  graphql_path: /{REPO_NAME}/graphql,   token_path: /auth/oauth/token }

REQUEST_HEADERS:
  correlation_id_var: X_CORRELATION_ID
  content_type: application/json

Required inputs

1. .codex/skills/insomnia-collection-generator/templates/example-insomnia-collection.yaml - YAML structure source of truth (required skill input).
2. All resolver files matching RESOLVER_FILE_PATTERN under RESOLVER_ROOTS - mandatory, re-parsed every run.
3. Schema from first existing SCHEMA_CANDIDATES - required.

Schema is source of truth for operation shape; resolvers are source of truth for domain mapping.

Script maintenance

When insomnia/generate-insomnia.js is missing:

1. Read .codex/skills/insomnia-collection-generator/templates/generate-insomnia.template.js as the starting implementation.
2. Analyze the repo (schema, resolvers, package.json) and update the CONFIG block and any functions marked // CUSTOMIZATION: to match the repo's structure.
3. Write the result to insomnia/generate-insomnia.js.
4. Verify required npm dependencies (graphql, yaml) are installed; install missing ones with the detected package manager.

When insomnia/generate-insomnia.js exists: validate it aligns with these instructions and update only if misaligned.

Resolver analysis (mandatory every run)

• Parse all resolver files under RESOLVER_ROOTS on every run.
• Build an operation index: { name, type (query|mutation), file, domain } per operation.
• Support explicit decorator name overrides (@Query('name') / name: in options object); fall back to method name, skipping any leading modifiers (async, public, etc.).
• Derive domain from the resolver file path (prefer src/modules/<domain> segment).
• Abort if REQUIRE_RESOLVER_ANALYSIS is true and analysis returns zero operations.

Collection structure

• One root folder (TOP_LEVEL_FOLDER) -> one child folder per environment -> one child folder per domain (alphabetical) -> one request per operation (alphabetical).
• Request name: {EnvironmentLabel} - {OperationName}.
• Each environment folder carries OAuth2 client_credentials auth; child requests inherit it.
• Each request: POST, application/graphql body, x-correlation-id and Content-Type headers.
• Variables: include all args (required + optional) and all nested input fields, populated with realistic sample values from baseSampleForField. No fields may be omitted.
• Selection set: include all scalar fields; recurse into nested object types (max depth 4).
• {REPO_NAME} in graphql_path is replaced with the name from package.json (fallback: folder name).
• Base environment contains all env-var placeholders set to <UPDATE_ME>; no secrets.

Output

• File: insomnia/Insomnia_YYYY-MM-DD.yaml using local date (create directory if missing).
• Block-style YAML, 2-space indent, quoted templated strings and URLs.
• Validate before writing: parse YAML cleanly; confirm type, schema_version, collection (array), and environments (object) match .codex/skills/insomnia-collection-generator/templates/example-insomnia-collection.yaml. Do not write on validation failure.

Execution (required every run)

1. Run VS Code task Insomnia: Regenerate Schema + Collection.
2. If the task fails to launch or the repo has no schema generation script, fall back to running the generator directly: node insomnia/generate-insomnia.js.

Quality gates (must pass before writing)

1. Resolver files scanned > 0 and operation index count > 0.
2. Every schema operation resolves to a domain, or is listed as unresolved.
3. If FAIL_ON_UNMAPPED_SCHEMA_OPERATIONS is true and unresolved operations exist, abort.
4. YAML parses without errors; structure matches .codex/skills/insomnia-collection-generator/templates/example-insomnia-collection.yaml.
5. No secrets in output.

Run summary (always return)

Output file path - total operations - total requests - by-environment and by-domain counts - unresolved operations - whether script was created/updated/reused - whether the VS Code task ran or fallback was used.