apollo-marketplace
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/apollographql--skills)HTML
<a href="/listings/apollographql--skills"><img src="/api/listings/apollographql--skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install skills using the [Skills CLI](https://skills.sh/docs/cli):
npx skills add apollographql/skills
The CLI guides you through an interactive installation:
1. **Select skills** - Choose which skills to install 2. **Select agents** - Pick target agents (Claude Code, Codex, Cursor, Gemini CLI, Goose, OpenCode) 3. **Installation scope** - Project (committed with your code) or Global 4. **Installation method** - Symlink (recommended) or Copy
◇ Found 11 skills │ ◆ Select skills to install │ ◼ apollo-client │ ◼ apollo-connectors │ ◼ apollo-server │ ○ ... └
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 17 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "apollo-marketplace",
- "owner": {
- "name": "Apollo GraphQL",
- "email": "opensource@apollographql.com"
- },
- "metadata": {
- "description": "Bundled plugins for GraphQL development with Apollo tools and technologies",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "apollo-skills",
- "source": "./"
- }
- ]
- }
README.md · README · 712 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Apollo GraphQL Agent Skills
- [](LICENSE)
- [](#skills)
- A collection of skills for AI coding agents working with Apollo GraphQL tools and technologies.
- Apollo Skills follow the [Agent Skills](https://agentskills.io/) format and are available on [skills.sh](https://skills.sh/).
- ## Installation
- Install skills using the [Skills CLI](https://skills.sh/docs/cli):
- ```bash
- npx skills add apollographql/skills
- ```
- The CLI guides you through an interactive installation:
- 1. **Select skills** - Choose which skills to install
- 2. **Select agents** - Pick target agents (Claude Code, Codex, Cursor, Gemini CLI, Goose, OpenCode)
- 3. **Installation scope** - Project (committed with your code) or Global
- 4. **Installation method** - Symlink (recommended) or Copy
- ```
- ◇ Found 11 skills
- │
- ◆ Select skills to install
- │ ◼ apollo-client
- │ ◼ apollo-connectors
- │ ◼ apollo-server
- │ ○ ...
- └
- ```
- ## Claude Code Plugin
- You can also install skills as a [Claude Code plugin](https://code.claude.com/docs/en/discover-plugins):
- First, add the marketplace:
- ```bash
- /plugin marketplace add apollographql/skills
- ```
- Then, install the plugin:
- ```bash
- /plugin install apollo-skills@apollo-marketplace
- ```
- Once installed, skills are available as namespaced slash commands:
- | Slash Command | Description |
- |---|---|
- | `/apollo-skills:apollo-client` | Apollo Client 4.x for React — queries, mutations, caching, local state |
- | `/apollo-skills:apollo-connectors` | **Deprecated** — use [`/apollo-skills:graphos-factory`](#graphos-factory) instead |
- | `/apollo-skills:apollo-ios` | Apollo iOS — GraphQL client for Swift (iOS, macOS, tvOS, watchOS, visionOS) |
- | `/apollo-skills:apollo-kotlin` | Apollo Kotlin — GraphQL client for Android and Kotlin |
- | `/apollo-skills:apollo-mcp-server` | Apollo MCP Server — connect AI agents with GraphQL APIs |
- | `/apollo-skills:apollo-server` | Apollo Server 4.x — schemas, resolvers, auth, plugins |
- | `/apollo-skills:graphos-factory` | GraphOS Factory — build and iterate on an Apollo Connectors subgraph from a REST API |
- | `/apollo-skills:graphql-operations` | GraphQL operations — queries, mutations, fragments |
- | `/apollo-skills:graphql-schema` | GraphQL schema design — types, naming, pagination, errors |
- | `/apollo-skills:rover` | Rover CLI — schema management and local supergraph development |
- | `/apollo-skills:rust-best-practices` | Rust best practices — idiomatic Rust following Apollo conventions |
- | `/apollo-skills:skill-creator` | Skill creator — guide for creating new Apollo skills |
- ## GitHub CLI
- You can also install skills with the [GitHub CLI](https://cli.github.com/) using `gh skill` (preview):
- ```bash
- # Install skills into the current project for Claude Code
- gh skill install apollographql/skills --agent claude-code
- # Install at user scope (available everywhere)
- gh skill install apollographql/skills --agent claude-code --scope user
- # Pin to a specific release (skipped during updates so it won't auto-upgrade)
- gh skill install apollographql/skills --pin v1.0.0 --agent claude-code
- # Preview skills before installing
- gh skill preview apollographql/skills
- ```
- `--agent` supports many hosts beyond Claude Code (Cursor, Codex, Gemini CLI, GitHub Copilot, and more); run `gh skill install --help` for the full list.
- ## Releases
- Releases are tagged with semver and published automatically whenever a content change is merged to `main`. The full list lives at [github.com/apollographql/skills/releases](https://github.com/apollographql/skills/releases).
- | Install path | What you get |
- |---|---|
- | `gh skill install apollographql/skills <name>` | Latest tagged release |
- | `gh skill install apollographql/skills <name> --pin v1.0.0` | Pinned to a specific release (skipped during updates) |
- | `npx skills add apollographql/skills@<name>` | Latest content from `main` (no tag) |
- | Claude Code plugin (`claude plugin install`) | Latest plugin version (auto-updates via `claude plugin update`) |
- If you need stability, pin via `gh skill install … --pin vX.Y.Z`. Pinned skills are skipped during `gh skill upgrade`, so you upgrade deliberately. For the freshest content, the other paths track `main` HEAD directly.
- ## Available Skills
- ### graphos-factory
- Build and iterate on an Apollo Connectors subgraph for a GraphOS supergraph from a REST API, with or without an OpenAPI or Swagger spec. It works with any agent that can run shell commands (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and others), and replaces the `apollo-connectors` skill. It is developed in [apollographql/graphos-factory](https://github.com/apollographql/graphos-factory); `skills/graphos-factory/` here is a read-only copy of its latest release, updated by that repository's release workflow.
- **Install:**
- ```bash
- npx skills add apollographql/skills@graphos-factory
- ```
- Or from its own repository, with either CLI:
- ```bash
- npx skills add apollographql/graphos-factory
- gh skill install apollographql/graphos-factory graphos-factory --agent claude-code # or codex, cursor, github-copilot, ...
- ```
- In Claude Code it is also part of the [`apollo-skills` plugin](#claude-code-plugin), as `/apollo-skills:graphos-factory`. The first time the agent uses it, the skill downloads its `graphos-factory` binary (about 3 MB) from the release it ships with.
- **Use when:**
- - Wrapping a REST API as a GraphQL subgraph for your supergraph
- - Adding or removing operations or fields on an existing connector subgraph
- - Refreshing a connector subgraph against a new version of its spec
- - Recording live API traffic as test fixtures
- **Categories covered:**
- - API discovery and spec intake (OpenAPI 3.x, Swagger 2.0, or no spec)
- - Operation and field selection, recorded in a dedicated git workspace
- - Connectors schema authoring, naming and mapping
- - Verification: composition, connector unit tests, mocked end-to-end and live runs
- - Design decisions and hand edits kept across regenerations
- **Examples:**
- - "Turn this REST API into a subgraph for my supergraph"
- - "Build a connector subgraph from this OpenAPI spec"
- - "Add the list-issues endpoint to my Gitea subgraph"
- **References:**
- [SKILL.md](skills/graphos-factory/SKILL.md) ·
- [README](https://github.com/apollographql/graphos-factory/blob/main/README.md) ·
- [Connectors Language](skills/graphos-factory/graphos-factory-core/references/connectors-language.md) ·
- [Mapping Language](skills/graphos-factory/graphos-factory-core/references/mapping-language.md) ·
- [Schema Authoring](skills/graphos-factory/graphos-factory-core/references/schema-authoring.md) ·
- [Testing](skills/graphos-factory/graphos-factory-core/references/testing.md) ·
- [Verification](skills/graphos-factory/references/verification.md)
- ---
- ### apollo-federation
- Author Apollo Federation subgraph schemas with entities, sharing, and cross-subgraph field resolution.
- **Install:**
- ```bash
- npx skills add apollographql/skills --skill apollo-federation
- ```
- **Use when:**
- - Creating new subgraph schemas for a federated supergraph
- - Defining or modifying entities with `@key`
- - Sharing types/fields across subgraphs with `@shareable`
- - Working with federation directives (`@external`, `@requires`, `@provides`, `@override`)
- - Troubleshooting composition errors
- **Categories covered:**
- - Entity definition and `@key` patterns (compound, multiple, differing)
- - Reference resolvers and computed fields
- - Value types with `@shareable`
- - Field migration with `@override` (including progressive rollout)
- - Entity interfaces with `@interfaceObject`
- - Common composition errors and fixes
- **Examples:**
- - "Create a federated subgraph for my products service"
- - "Add a computed field that requires data from another subgraph"
- - "Migrate this field from one subgraph to another"
- **References:**
- [SKILL.md](skills/apollo-federation/SKILL.md) ·
- [Directives](skills/apollo-federation/references/directives.md) ·
- [Schema Patterns](skills/apollo-federation/references/schema-patterns.md) ·
- [Composition](skills/apollo-federation/references/composition.md)
- ---
- ### apollo-mcp-server
- Configure and use Apollo MCP Server to connect AI agents with GraphQL APIs.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-mcp-server
- ```
- **Use when:**
- - Setting up Apollo MCP Server for Claude or other AI agents
- - Defining MCP tools from GraphQL operations
- - Using introspection tools (introspect, search, validate, execute)
- - Troubleshooting MCP server connectivity issues
- **Categories covered:**
- - Server configuration (endpoints, schemas, headers)
- - Built-in tools and compact notation
- - Operation sources (files, collections, persisted queries)
- - Authentication and security
- - Health checks and debugging
- **Examples:**
- - "Set up Apollo MCP Server for my GraphQL endpoint"
- - "Configure MCP tools from my GraphQL operations"
- - "Debug MCP server connection issues"
- **References:**
- [SKILL.md](skills/apollo-mcp-server/SKILL.md) ·
- [Tools](skills/apollo-mcp-server/references/tools.md) ·
- [Configuration](skills/apollo-mcp-server/references/configuration.md) ·
- [Troubleshooting](skills/apollo-mcp-server/references/troubleshooting.md)
- ---
- ### apollo-router
- Configure and run Apollo Router for federated GraphQL supergraphs.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-router
- ```
- **Use when:**
- - Setting up Apollo Router to run a supergraph
- - Configuring routing, headers, or CORS
- - Implementing custom plugins (Rhai scripts or coprocessors)
- - Configuring telemetry and observability
- - Troubleshooting Router performance or connectivity issues
- **Categories covered:**
- - Installation and quick start
- - Router configuration (YAML)
- - Header propagation and manipulation
- - CORS and authentication
- - Rhai scripts and coprocessors
- - Telemetry (tracing, metrics, logging)
- **Examples:**
- - "Set up Apollo Router for my supergraph"
- - "Configure CORS for my Router"
- - "Add header propagation for authentication"
- **References:**
- [SKILL.md](skills/apollo-router/SKILL.md) ·
- [Configuration](skills/apollo-router/references/configuration.md) ·
- [Headers](skills/apollo-router/references/headers.md) ·
- [Plugins](skills/apollo-router/references/plugins.md) ·
- [Telemetry](skills/apollo-router/references/telemetry.md) ·
- [Troubleshooting](skills/apollo-router/references/troubleshooting.md)
- ---
- ### apollo-server
- Build GraphQL servers with Apollo Server 4.x, including schemas, resolvers, authentication, and plugins.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-server
- ```
- **Use when:**
- - Setting up a new Apollo Server project
- - Writing resolvers or defining GraphQL schemas
- - Implementing authentication or authorization
- - Creating plugins or custom data sources
- - Troubleshooting Apollo Server errors or performance issues
- **Categories covered:**
- - Quick start setup (standalone and Express)
- - Schema definition and type system
- - Resolver patterns and best practices
- - Context and authentication
- - Plugins and lifecycle hooks
- - Data sources and DataLoader
- - Error handling and formatting
- **Examples:**
- - "Create an Apollo Server with user authentication"
- - "Write resolvers for my GraphQL schema"
- - "Add a custom plugin to log all queries"
- **References:**
- [SKILL.md](skills/apollo-server/SKILL.md) ·
- [Resolvers](skills/apollo-server/references/resolvers.md) ·
- [Context & Auth](skills/apollo-server/references/context-and-auth.md) ·
- [Plugins](skills/apollo-server/references/plugins.md) ·
- [Data Sources](skills/apollo-server/references/data-sources.md) ·
- [Error Handling](skills/apollo-server/references/error-handling.md) ·
- [Troubleshooting](skills/apollo-server/references/troubleshooting.md)
- ---
- ### apollo-client
- Build React applications with Apollo Client 4.x for GraphQL data management, caching, and local state.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-client
- ```
- **Use when:**
- - Setting up Apollo Client in a React project
- - Writing GraphQL queries or mutations with hooks
- - Configuring caching or cache policies
- - Managing local state with reactive variables
- - Troubleshooting Apollo Client errors or performance issues
- **Categories covered:**
- - Quick start setup (install, client, provider, query)
- - useQuery and useLazyQuery hooks
- - useMutation with optimistic UI
- - InMemoryCache and type policies
- - Reactive variables and local state
- - Error handling and error links
- - Performance optimization
- **Examples:**
- - "Set up Apollo Client in my React app"
- - "Implement optimistic UI for my mutation"
- - "Configure cache policies for my queries"
- **References:**
- [SKILL.md](skills/apollo-client/SKILL.md) ·
- [Queries](skills/apollo-client/references/queries.md) ·
- [Mutations](skills/apollo-client/references/mutations.md) ·
- [Caching](skills/apollo-client/references/caching.md) ·
- [State Management](skills/apollo-client/references/state-management.md) ·
- [Error Handling](skills/apollo-client/references/error-handling.md) ·
- [Troubleshooting](skills/apollo-client/references/troubleshooting.md)
- ---
- ### apollo-ios
- Build Apple-platform applications with Apollo iOS, the strongly-typed GraphQL client for Swift (iOS, macOS, tvOS, watchOS, visionOS).
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-ios
- ```
- **Use when:**
- - Adding Apollo iOS to a Swift Package Manager or Xcode project
- - Configuring `apollo-codegen-config.json` and running code generation
- - Configuring an `ApolloClient` with auth, interceptors, and caching
- - Writing queries, mutations, or subscriptions from SwiftUI views
- - Writing tests against generated operation mocks
- **Categories covered:**
- - SPM installation, product linking (`Apollo` vs `ApolloAPI`), and `apollo-ios-cli` setup
- - Code generation config (`apollo-codegen-config.json`) with the canonical `swiftPackage` + `relative` defaults
- - Custom scalars (default `String` typealias, when and how to replace it)
- - Queries, mutations, watchers, and cache policies with async/await
- - Normalized cache, `@typePolicy` cache keys, manual reads/writes
- - Interceptor architecture split across HTTP and GraphQL layers (auth token attachment + token refresh + retry)
- - Subscriptions over HTTP multipart and WebSocket, with scene-phase pause/resume
- - Testing with `ApolloTestSupport` and generated `Mock<Type>` fixtures (enabled lazily when tests need them)
- **Examples:**
- - "Set up Apollo iOS in a new SwiftUI app"
- - "Add an auth token to every GraphQL request"
- - "Subscribe to a GraphQL subscription from a SwiftUI view"
- **References:**
- [SKILL.md](skills/apollo-ios/SKILL.md) ·
- [Setup](skills/apollo-ios/references/setup.md) ·
- [Codegen](skills/apollo-ios/references/codegen.md) ·
- [Custom Scalars](skills/apollo-ios/references/custom-scalars.md) ·
- [Operations](skills/apollo-ios/references/operations.md) ·
- [Caching](skills/apollo-ios/references/caching.md) ·
- [Interceptors](skills/apollo-ios/references/interceptors.md) ·
- [Subscriptions](skills/apollo-ios/references/subscriptions.md) ·
- [Testing](skills/apollo-ios/references/testing.md)
- ---
- ### apollo-kotlin
- Build applications with Apollo Kotlin, the GraphQL client library for Android and Kotlin.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-kotlin
- ```
- **Use when:**
- - Setting up Apollo Kotlin in a Gradle project for Android, Kotlin/JVM, or KMP
- - Configuring schema download and codegen for GraphQL services
- - Configuring an `ApolloClient` with auth, interceptors, and caching
- - Writing queries, mutations, or subscriptions
- **Categories covered:**
- - Gradle plugin setup and service configuration
- - Schema management and code generation
- - ApolloClient configuration
- - Coroutines and Flow usage patterns
- - Normalized cache and cache policies
- **Examples:**
- - "Set up Apollo Kotlin in my Android app"
- - "Configure code generation for multiple GraphQL services"
- - "Add normalized caching for offline support"
- **References:**
- [SKILL.md](skills/apollo-kotlin/SKILL.md) ·
- [Setup](skills/apollo-kotlin/references/setup.md) ·
- [Operations](skills/apollo-kotlin/references/operations.md) ·
- [Caching](skills/apollo-kotlin/references/caching.md) ·
- ---
- ### rover
- Manage GraphQL schemas and run local supergraph development with Apollo Rover CLI.
- **Install:**
- ```bash
- npx skills add apollographql/skills@rover
- ```
- **Use when:**
- - Publishing or fetching subgraph schemas to/from GraphOS
- - Composing supergraph schemas locally
- - Running local supergraph development with rover dev
- - Validating schemas with check and lint commands
- **Categories covered:**
- - Subgraph commands (fetch, publish, check, lint)
- - Graph commands (monograph management)
- - Supergraph composition
- - Local development with rover dev
- - Authentication and configuration
- **Examples:**
- - "Publish my subgraph schema to GraphOS"
- - "Run rover dev to test my supergraph locally"
- - "Check my schema changes before deploying"
- **References:**
- [SKILL.md](skills/rover/SKILL.md) ·
- [Subgraphs](skills/rover/references/subgraphs.md) ·
- [Graphs](skills/rover/references/graphs.md) ·
- [Supergraphs](skills/rover/references/supergraphs.md) ·
- [Dev](skills/rover/references/dev.md) ·
- [Configuration](skills/rover/references/configuration.md)
- ---
- ### graphql-schema
- Design GraphQL schemas following industry best practices for type design, naming, pagination, errors, and security.
- **Install:**
- ```bash
- npx skills add apollographql/skills@graphql-schema
- ```
- **Use when:**
- - Designing a new GraphQL schema or API
- - Reviewing existing schema for improvements
- - Deciding on type structures or nullability
- - Implementing pagination or error patterns
- - Ensuring security in schema design
- **Categories covered:**
- - Type design patterns (interfaces, unions, custom scalars)
- - Naming conventions for types, fields, and arguments
- - Cursor-based pagination (Connection pattern)
- - Error modeling and result types
- - Security best practices (depth limiting, complexity, authorization)
- **Examples:**
- - "Design a GraphQL schema for my e-commerce API"
- - "Review my schema for best practices"
- - "Add cursor-based pagination to my queries"
- **References:**
- [SKILL.md](skills/graphql-schema/SKILL.md) ·
- [Types](skills/graphql-schema/references/types.md) ·
- [Naming](skills/graphql-schema/references/naming.md) ·
- [Pagination](skills/graphql-schema/references/pagination.md) ·
- [Errors](skills/graphql-schema/references/errors.md) ·
- [Security](skills/graphql-schema/references/security.md)
- ---
- ### graphql-operations
- Write GraphQL operations (queries, mutations, fragments) following best practices for client-side development.
- **Install:**
- ```bash
- npx skills add apollographql/skills@graphql-operations
- ```
- **Use when:**
- - Writing GraphQL queries or mutations
- - Organizing operations with fragments
- - Optimizing data fetching patterns
- - Setting up type generation or linting
- - Reviewing operations for efficiency
- **Categories covered:**
- - Query patterns and optimization
- - Mutation patterns and error handling
- - Fragment organization and colocation
- - Variable usage and types
- - Tooling (GraphQL Code Generator, ESLint, IDE extensions)
- **Examples:**
- - "Write a query with pagination"
- - "Organize my operations with fragments"
- - "Set up GraphQL Code Generator for type safety"
- **References:**
- [SKILL.md](skills/graphql-operations/SKILL.md) ·
- [Queries](skills/graphql-operations/references/queries.md) ·
- [Mutations](skills/graphql-operations/references/mutations.md) ·
- [Fragments](skills/graphql-operations/references/fragments.md) ·
- [Variables](skills/graphql-operations/references/variables.md) ·
- [Tooling](skills/graphql-operations/references/tooling.md)
- ---
- ### rust-best-practices
- Write idiomatic Rust code following Apollo GraphQL's best practices handbook.
- **Install:**
- ```bash
- npx skills add apollographql/skills@rust-best-practices
- ```
- **Use when:**
- - Writing new Rust code or functions
- - Reviewing or refactoring existing Rust code
- - Deciding between borrowing vs cloning or ownership patterns
- - Implementing error handling with Result types
- - Optimizing Rust code for performance
- - Writing tests or documentation for Rust projects
- **Categories covered:**
- - Coding style and idioms (borrowing, Option/Result, iterators)
- - Clippy and linting discipline
- - Performance optimization and profiling
- - Error handling with thiserror and anyhow
- - Testing strategies and snapshot testing
- - Generics, static and dynamic dispatch
- - Type state pattern for compile-time safety
- - Documentation best practices
- - Pointer types and thread safety
- **Examples:**
- - "Review this Rust code for best practices"
- - "Help me decide between cloning and borrowing here"
- - "Add proper error handling to this function"
- **References:**
- [SKILL.md](skills/rust-best-practices/SKILL.md) ·
- [Style](skills/rust-best-practices/references/style.md) ·
- [Errors](skills/rust-best-practices/references/errors.md) ·
- [Performance](skills/rust-best-practices/references/performance.md) ·
- [Testing](skills/rust-best-practices/references/testing.md) ·
- [Advanced](skills/rust-best-practices/references/advanced.md)
- ---
- ### skill-creator
- Guide for creating effective skills for Apollo GraphQL and GraphQL development.
- **Install:**
- ```bash
- npx skills add apollographql/skills@skill-creator
- ```
- **Use when:**
- - Creating a new skill for this repository
- - Updating an existing skill's structure or content
- - Learning skill best practices and patterns
- - Writing SKILL.md files or reference documentation
- **Categories covered:**
- - SKILL.md format and frontmatter fields
- - Directory structure and reference files
- - Description writing for agent activation triggers
- - Progressive disclosure and context optimization
- - Apollo Voice writing style guidelines
- - Validation checklist for new skills
- **Examples:**
- - "Create a new skill for Apollo Federation"
- - "Help me write a SKILL.md for my custom skill"
- - "Review my skill structure for best practices"
- **References:**
- [SKILL.md](skills/skill-creator/SKILL.md) ·
- [Apollo Skills](skills/skill-creator/references/apollo-skills.md)
- ---
- ### apollo-connectors
- > **Deprecated.** Superseded by [graphos-factory](#graphos-factory) (`npx skills add apollographql/skills@graphos-factory`). This skill will be removed in a future release.
- Write Apollo Connectors schemas to integrate REST APIs into GraphQL.
- **Install:**
- ```bash
- npx skills add apollographql/skills@apollo-connectors
- ```
- ---
- ## Usage
- Skills activate automatically once installed. The agent uses them when relevant tasks are detected.
- You can also explicitly invoke a skill depending on your tool:
- | Tool | Automatic | Explicit Invocation |
- | -------------- | --------- | ------------------------------------------------------- |
- | Claude Code | Yes | Slash command (e.g., `/graphql-schema` or `/apollo-skills:graphql-schema` via plugin) |
- | GitHub Copilot | Yes | `/agent` for custom agents, `@github` for GitHub skills |
- | Cursor | Yes | Rules matched by file patterns (no direct invocation) |
- | Windsurf | Yes | Slash command for workflows (e.g., `/workflow-name`) |
- ## Skill Structure
- Each skill contains:
- - `SKILL.md` - Instructions for the agent (required)
- - `references/` - Supporting documentation (optional)
- ## Resources
- - [Apollo Client Documentation](https://www.apollographql.com/docs/react/)
- - [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
- - [Apollo Connectors Documentation](https://www.apollographql.com/docs/graphos/schema-design/connectors/)
- - [Apollo Federation Documentation](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/)
- - [Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/)
- - [Apollo iOS Documentation](https://www.apollographql.com/docs/ios/)
- - [Rover CLI Documentation](https://www.apollographql.com/docs/rover/)
- - [Rust Best Practices Handbook](https://github.com/apollographql/rust-best-practices)
- ## Disclaimer
- The code in this repository is experimental and for reference purposes only. Community feedback is welcome but this project is not officially supported in the same way that repositories in the official [Apollo GraphQL GitHub organization](https://github.com/apollographql) are. If you need help you can file an issue on this repository, [contact Apollo](https://www.apollographql.com/contact-sales) to talk to an expert, or create a ticket directly in Apollo Studio.
skills/graphos-factory/graphos-factory-core/scripts/e2e.sh · Bundled script · 489 lines · 1 finding marked
- #!/usr/bin/env bash
- # e2e.sh — WireMock-backed cases through a real Apollo Router.
- #
- # e2e.sh [workspace-dir] [--generate] [--only PATTERN]
- #
- # Layer 3, and the only layer where a real router parses the real GraphQL
- # documents and sends real HTTP requests. WireMock runs from its standalone
- # JAR (Java), and unmatched upstream requests are printed WITH their
- # bodies, because "what did the connector actually send?" is the question
- # this layer is for.
- #
- # All-stubs-at-once loading (references/testing.md): every classified mapping
- # loads into WireMock once, before the first case runs, and stays loaded for
- # the whole suite — every stub is mounted flat, unlike this script's own
- # former per-case reset-and-reload. Two stubs whose
- # `request` matcher is identical can then only ever be answered by one of
- # them, WireMock's own tie-break deciding which; that is a fixture defect
- # any flat-mounting runner downstream would also hit, so it must fail here
- # first.
- # Only the request journal and WireMock's scenario state reset between
- # cases (`DELETE $ADMIN/requests`, `POST $ADMIN/scenarios/reset`; neither
- # touches loaded mappings), so per-case stub-hit accounting is unaffected
- # by every other case's stubs also being loaded. A case whose own stub
- # declares a `requiredScenarioState` other than `Started` (references/
- # testing.md — a WireMock Scenario, the only way to disambiguate a request
- # that is identical by definition, e.g. an operation with no body) has that
- # state set directly before its request fires. Every mapping must still be
- # classifiable — by `metadata."x-cases"`, by a basename matching a case
- # name (hyphens and underscores interchangeable), or by `metadata."x-shared"`
- # — or the run fails before any case executes.
- # Stub-hit accounting after each case: every upstream request matched a
- # loaded stub and at least one was made, unless the .graphql declares
- # `# expect-unmatched-upstream`. Every stub that answered must also be the
- # case's own (its case list or shared.list): with every stub loaded at once,
- # another case's stub can answer a request the connector got wrong (a
- # dropped query parameter matching a sibling's `absent` matcher), and that
- # must fail the case, as per-case loading did. The request
- # journal names the stub that answered each request (`stubMapping.name`,
- # the fixture's filename, set at load). A stub of the case's own marked
- # `metadata."x-required": true` must also have answered at least one request,
- # or the case fails naming it: a $batch case's lookup, which a
- # planner that resolves the fields locally never calls.
- #
- # Upstream status, before the snapshot diff: a case declaring
- # `# expect-upstream-status: CODE` fails unless one of its own stubs
- # answered CODE. A router that redacts subgraph errors renders every error
- # status alike, so the snapshot alone cannot tell a 401 case from a 404 one.
- # A case without the directive whose stub answered a non-2xx status, calling
- # a root field whose operation documents more than one, reports UNPROVEN:
- # counted apart, never as a pass, and not a failure of the run.
- #
- # --only PATTERN restricts which cases actually run (each is the 3-file unit
- # of tests/cases/NAME.graphql, its .expected.json, and its
- # mapping) to those whose NAME contains PATTERN as a literal substring,
- # hyphens and underscores interchangeable — same normalisation the mapping
- # classifier below already uses. Classification still runs over every
- # mapping regardless of --only, so a filtered run cannot mask an
- # unclassifiable fixture. A PATTERN matching no case fails closed (exit 1)
- # before WireMock or the router starts.
- #
- # Exit 127 = a tool is missing (java, curl, jq): the layer is `skipped` in
- # evidence with that reason, never `pass`. Exit 3 = the user has not accepted
- # the Elastic License v2 of the composition plugin and the Router
- # (APOLLO_ELV2_LICENSE, see elv2.sh): the layer is `not_run` with that
- # reason, never `pass`, and no Router is downloaded.
- set -euo pipefail
- WORKSPACE="."
- GENERATE=0
- ONLY=""
- while [ $# -gt 0 ]; do
- case "$1" in
- --generate) GENERATE=1; shift ;;
- --only)
- if [ $# -lt 2 ] || [ -z "$2" ]; then echo "e2e: --only requires a non-empty pattern" >&2; exit 1; fi
- ONLY="$2"; shift 2 ;;
- *) WORKSPACE="$1"; shift ;;
- esac
- done
- WIREMOCK_VERSION="${WIREMOCK_VERSION:-3.13.2}"
- ROUTER_VERSION="${ROUTER_VERSION:-2.17.0}"
- WIREMOCK_PORT="${WIREMOCK_PORT:-8080}"
- ROUTER_PORT="${ROUTER_PORT:-4000}"
- ROUTER_HEALTH_PORT="${ROUTER_HEALTH_PORT:-8088}"
- ADMIN="http://localhost:${WIREMOCK_PORT}/__admin"
- for tool in java curl jq; do
- command -v "$tool" >/dev/null 2>&1 || { echo "e2e: $tool is not installed" >&2; exit 127; }
- done
- command -v rover >/dev/null 2>&1 || { echo "e2e: rover is not installed" >&2; exit 127; }
- # shellcheck source=SCRIPTDIR/cache.sh
- . "$(dirname "$0")/cache.sh"
- CACHE="$GRAPHOS_FACTORY_CORE_CACHE_DIR"
- # The product binary, and a refusal (exit 78) when it is older than
- # the version these scripts pin — see resolve-bin.sh for the order and why.
- # shellcheck source=SCRIPTDIR/resolve-bin.sh
- . "$(dirname "$0")/resolve-bin.sh"
- # shellcheck source=SCRIPTDIR/elv2.sh
- . "$(dirname "$0")/elv2.sh"
- elv2_require e2e
- OUT="$(mktemp -d)"
- WIREMOCK_PID=""
- ROUTER_PID=""
- cleanup() {
- if [ -n "$ROUTER_PID" ]; then kill "$ROUTER_PID" 2>/dev/null || true; fi
- if [ -n "$WIREMOCK_PID" ]; then kill "$WIREMOCK_PID" 2>/dev/null || true; fi
- rm -rf "$OUT"
- }
- trap cleanup EXIT
- CASES_DIR="$WORKSPACE/tests/cases"
- MAPPINGS_DIR="$WORKSPACE/tests/fixtures/mappings"
- [ -f "$WORKSPACE/tests/router.yaml" ] || { echo "e2e: $WORKSPACE/tests/router.yaml is missing" >&2; exit 1; }
- shopt -s nullglob
- case_files=("$CASES_DIR"/*.graphql)
- mappings=("$MAPPINGS_DIR"/*.json)
- shopt -u nullglob
- # Byte order, never the shell's locale: a glob and `sort` collate
- # by LC_COLLATE, and under en_US.UTF-8 `X_minimal.json` sorts before
- # `X.json` while under C it sorts after. Stubs load in this order, and
- # WireMock answers a request two stubs match with the one loaded last, so
- # the locale once decided which stub answered. Only these sorts are pinned:
- # exporting LC_ALL=C would reach WireMock's JVM, whose default charset
- # before Java 18 follows it.
- if [ ${#case_files[@]} -gt 0 ]; then
- sorted=(); while IFS= read -r f; do sorted+=("$f"); done < <(printf '%s\n' "${case_files[@]}" | LC_ALL=C sort)
- case_files=("${sorted[@]}")
- fi
- if [ ${#mappings[@]} -gt 0 ]; then
- sorted=(); while IFS= read -r f; do sorted+=("$f"); done < <(printf '%s\n' "${mappings[@]}" | LC_ALL=C sort)
- mappings=("${sorted[@]}")
- fi
- [ ${#case_files[@]} -gt 0 ] || { echo "e2e: no tests/cases/*.graphql" >&2; exit 1; }
- run_cases=("${case_files[@]}")
- if [[ -n "$ONLY" ]]; then
- run_cases=()
- norm_only="$(printf '%s' "$ONLY" | tr '-' '_')"
- for f in "${case_files[@]}"; do
- norm_b="$(printf '%s' "$(basename "${f%.graphql}")" | tr '-' '_')"
- [[ "$norm_b" == *"$norm_only"* ]] && run_cases+=("$f")
- done
- if [[ ${#run_cases[@]} -eq 0 ]]; then
- echo "e2e: --only '$ONLY' matched no case in $CASES_DIR" >&2
- exit 1
- fi
- fi
- for port in "$WIREMOCK_PORT" "$ROUTER_PORT" "$ROUTER_HEALTH_PORT"; do
- if curl -s "http://localhost:$port/" >/dev/null 2>&1; then
- echo "e2e: port $port is already in use" >&2
- exit 1
- fi
- done
- # ── Toolchain: fetch once into the cache ─────────────────────────────────────
- mkdir -p "$CACHE"
- WIREMOCK_JAR="$CACHE/wiremock-standalone-$WIREMOCK_VERSION.jar"
- ROUTER_BIN="$CACHE/router-$ROUTER_VERSION"
- if [ ! -f "$WIREMOCK_JAR" ]; then
- echo "e2e: downloading WireMock $WIREMOCK_VERSION"
- curl -sfL "https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/$WIREMOCK_VERSION/wiremock-standalone-$WIREMOCK_VERSION.jar" -o "$WIREMOCK_JAR"
- Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
- Line 164 on GitHub
- fi
- # The Router is ELv2-licensed too: this download sits after elv2_require.
- if [ ! -x "$ROUTER_BIN" ]; then
- echo "e2e: downloading Apollo Router $ROUTER_VERSION"
- case "$(uname -s)-$(uname -m)" in
- Linux-x86_64) platform="x86_64-unknown-linux-gnu" ;;
- Linux-aarch64) platform="aarch64-unknown-linux-gnu" ;;
- Darwin-arm64) platform="aarch64-apple-darwin" ;;
- Darwin-x86_64) platform="x86_64-apple-darwin" ;;
- *) echo "e2e: unsupported platform $(uname -s)-$(uname -m)" >&2; exit 127 ;;
- esac
- curl -sfL "https://github.com/apollographql/router/releases/download/v$ROUTER_VERSION/router-v$ROUTER_VERSION-$platform.tar.gz" \
- | tar xzf - -C "$OUT" --strip-components=1 dist/router
- mv "$OUT/router" "$ROUTER_BIN"
- chmod +x "$ROUTER_BIN"
- fi
- # ── Classify every mapping before anything starts ────────────────────────────
- INDEX="$OUT/index"
- mkdir -p "$INDEX"
- for q in "${case_files[@]}"; do
- b="$(basename "$q" .graphql)"
- printf '%s\t%s\n' "$(printf '%s' "$b" | tr '-' '_')" "$b"
- done > "$INDEX/cases.tsv"
- case_for_name() {
- awk -F'\t' -v n="$(printf '%s' "$1" | tr '-' '_')" '$1==n{print $2; exit}' "$INDEX/cases.tsv"
- }
- unclassified=""
- for m in "${mappings[@]}"; do
- if jq -e '.persistent == true' "$m" >/dev/null 2>&1; then
- echo "e2e: $(basename "$m") sets \"persistent\": true — WireMock would restore it after every reset and it would answer other cases' requests. Remove it." >&2
- exit 1
- fi
- # A scenario's state is set through `PUT $ADMIN/scenarios/<name>/state`,
- # and WireMock 3.13.2 does not decode a percent-encoded name there
- # (measured: `%20`, `%23`, `%C3%A9` all 404). A name that needs encoding
- # could never be set, so refuse it before any case runs.
- scenario="$(jq -r '.scenarioName // empty' "$m")"
- # `.` and `..` alone are refused too: curl collapses them as path
- # dot-segments, so the PUT would never reach the scenario.
- if [[ -n "$scenario" && ( ! "$scenario" =~ ^[A-Za-z0-9._~-]+$ || "$scenario" == "." || "$scenario" == ".." ) ]]; then
- echo "e2e: $(basename "$m") scenarioName '$scenario' cannot be addressed in WireMock's scenario admin API (it does not decode URL-encoding, and '.' or '..' alone is a path dot-segment) — use only letters, digits, '.', '_', '~' and '-', and not '.' or '..' alone" >&2
- exit 1
- fi
- has_xcases="$(jq -r '(.metadata // {}) | has("x-cases")' "$m")"
- xcases="$(jq -r '(.metadata["x-cases"] // [])[]' "$m")"
- xshared="$(jq -r '.metadata["x-shared"] // false' "$m")"
- if [[ "$has_xcases" == "true" && -z "$xcases" ]]; then
- continue # recorded for an operation with no case yet: classified, loaded for nothing
- fi
- if [[ -n "$xcases" ]]; then
- while IFS= read -r c; do
- target="$(case_for_name "$c")"
- [[ -n "$target" ]] || { echo "e2e: $(basename "$m") metadata.x-cases names unknown case '$c'" >&2; exit 1; }
- echo "$m" >> "$INDEX/case-$target.list"
- done <<< "$xcases"
- elif [[ "$xshared" == "true" ]]; then
- echo "$m" >> "$INDEX/shared.list"
- else
- target="$(case_for_name "$(basename "$m" .json)")"
- if [[ -n "$target" ]]; then echo "$m" >> "$INDEX/case-$target.list"; else unclassified="$unclassified $(basename "$m")"; fi
- fi
- done
- if [[ -n "$unclassified" ]]; then
- echo "e2e: mappings not classifiable to any case:$unclassified" >&2
- echo "e2e: name the file after its case, list cases in metadata.\"x-cases\", or set metadata.\"x-shared\": true" >&2
- exit 1
- fi
- # Every classified mapping (shared plus every case's), once, deduplicated —
- # a mapping named in more than one case's `metadata."x-cases"` appears in
- # more than one list file but must still load only once.
- # A case whose own stub(s) declare `requiredScenarioState` (WireMock
- # Scenarios — the only way to answer two byte-identical requests
- # differently once every stub loads together) must be run from exactly
- # that state; scenarios reset to `Started` before every case, so a case
- # needing anything else sets it directly, derived from its own stub's own
- # `requiredScenarioState` — no separate case-file declaration exists or is
- # needed (references/testing.md).
- set_scenario_states() {
- local list="$INDEX/case-$1.list" m name state
- [[ -f "$list" ]] || return 0
- while IFS= read -r m; do
- name="$(jq -r '.scenarioName // empty' "$m")"
- state="$(jq -r '.requiredScenarioState // empty' "$m")"
- if [[ -n "$name" && -n "$state" && "$state" != "Started" ]]; then
- # The name is a URL path segment here; it needs no encoding because
- # names outside [A-Za-z0-9._~-] are refused before any case runs.
- curl -sf -X PUT "$ADMIN/scenarios/$name/state" -H 'Content-Type: application/json' \
- -d "$(jq -n --arg s "$state" '{state: $s}')" >/dev/null \
- || { echo "e2e: could not set scenario $name to $state" >&2; return 1; }
- fi
- done < "$list"
- }
- load_all_stubs() {
- curl -sf -X POST "$ADMIN/reset" >/dev/null || return 1
- local list m loaded=()
- for list in "$INDEX"/shared.list "$INDEX"/case-*.list; do
- [[ -f "$list" ]] || continue
- while IFS= read -r m; do loaded+=("$m"); done < "$list"
- done
- while IFS= read -r m; do
- [[ -n "$m" ]] || continue
- # Name each stub after its file: WireMock echoes `name` in the request
- # journal, which is the only stable way to see which fixture answered.
- jq -c --arg n "$(basename "$m")" '.name = $n' "$m" \
- | curl -sf -X POST "$ADMIN/mappings" -H 'Content-Type: application/json' --data-binary @- >/dev/null \
- || { echo "e2e: WireMock rejected stub $m" >&2; return 1; }
- done < <(printf '%s\n' "${loaded[@]-}" | LC_ALL=C sort -u)
- }
- # ── Render, credential, compose ──────────────────────────────────────────────
- # The rendered router config carries this run's ports, so two suites can run
- # side by side (WIREMOCK_PORT / ROUTER_PORT / ROUTER_HEALTH_PORT) without
- # touching the committed tests/router.yaml.
- eval "$("$RC" render "$WORKSPACE" --out "$OUT" --wiremock-port "$WIREMOCK_PORT" --router-port "$ROUTER_PORT" --health-port "$ROUTER_HEALTH_PORT")"
- [ -n "${ROUTER_CONFIG:-}" ] || { echo "e2e: render produced no ROUTER_CONFIG" >&2; exit 1; }
- # Fixtures assert the forwarded credential, so the router must see one. The
- # env var name comes from AUTH_EXPR's test_default; the value is fixed so
- # fixtures can match `… test-token` exactly.
- AUTH_VAR="$("$RC" auth-env "$WORKSPACE")"
- if [ -n "$AUTH_VAR" ]; then
- # Always the test token, even when the real credential is in the
- # environment (CI carries it for the live layer): WireMock's fixtures match
- # `… test-token` exactly, and a real secret must never reach a stub server
- # or its request log.
- export "$AUTH_VAR=test-token"
- fi
- SUPERGRAPH="$OUT/supergraph.graphql"
- NO_COLOR=1 rover supergraph compose --config "$COMPOSE_CONFIG" > "$SUPERGRAPH" 2> "$OUT/compose.err" \
- || { cat "$OUT/compose.err" >&2; echo "e2e: compose failed" >&2; exit 1; }
- # ── Start WireMock and the router ────────────────────────────────────────────
- WM_ROOT="$OUT/wiremock"
- mkdir -p "$WM_ROOT/mappings" "$WM_ROOT/__files"
- [ -d "$WORKSPACE/tests/fixtures/__files" ] && cp -r "$WORKSPACE/tests/fixtures/__files/." "$WM_ROOT/__files/"
- java -jar "$WIREMOCK_JAR" --port "$WIREMOCK_PORT" --root-dir "$WM_ROOT" --disable-banner > "$OUT/wiremock.log" 2>&1 &
- WIREMOCK_PID=$!
- deadline=$(( $(date +%s) + 30 ))
- until curl -sf "$ADMIN/" >/dev/null 2>&1; do
- [ "$(date +%s)" -ge "$deadline" ] && { echo "e2e: WireMock did not start"; tail -20 "$OUT/wiremock.log" >&2; exit 1; }
- sleep 0.5
- done
- env -u OTEL_EXPORTER_OTLP_ENDPOINT "$ROUTER_BIN" --supergraph "$SUPERGRAPH" --config "$ROUTER_CONFIG" > "$OUT/router.log" 2>&1 &
- ROUTER_PID=$!
- # A large supergraph takes the router longer than 30s to load (Databricks:
- # 152.6s to healthy); E2E_ROUTER_START_SECONDS raises the wait, the default
- # stays 30.
- router_wait=${E2E_ROUTER_START_SECONDS:-30}
- router_started=$(date +%s)
- deadline=$(( router_started + router_wait ))
- until curl -sf "http://localhost:${ROUTER_HEALTH_PORT}/health" >/dev/null 2>&1; do
- # A router that exits (a bad config, a supergraph it rejects) is not waited
- # out to the deadline.
- kill -0 "$ROUTER_PID" 2>/dev/null || { echo "e2e: router exited before it reported healthy"; tail -30 "$OUT/router.log" >&2; exit 1; }
- [ "$(date +%s)" -ge "$deadline" ] && { echo "e2e: router did not start within ${router_wait}s (set E2E_ROUTER_START_SECONDS to wait longer)"; tail -30 "$OUT/router.log" >&2; exit 1; }
- sleep 1
- done
- echo "e2e: WireMock $WIREMOCK_VERSION (java), Apollo Router $ROUTER_VERSION, $(rover --version | head -1), ${#run_cases[@]} cases"
- if [[ -n "$ONLY" ]]; then
- echo "e2e: --only '$ONLY' matched ${#run_cases[@]} of ${#case_files[@]} case(s)"
- fi
- load_all_stubs || { echo "e2e: could not load stubs" >&2; exit 1; }
- # One line per included operation, tab-separated, `-` for an empty column:
- # root field, the non-2xx statuses it documents, the ones a recorded run
- # already exercised (unused here), and the operation key (`get:/repos/{o}`).
- ERROR_STATUSES="$("$RC" error-statuses "$WORKSPACE")" || { echo "e2e: could not read the documented error statuses" >&2; exit 1; }
- # The statuses the journal shows answering the operation's OWN request: a
- # matched entry with the operation's method whose URL path (query dropped)
- # ends with its path template, segment by segment, a {parameter} standing
- # for exactly one non-empty segment. A status served to any other request
- # in the case (a nested lookup, a side call) is not the operation's.
- # shellcheck disable=SC2016
- OWN_STATUSES_JQ='
- def segs: split("/");
- def ends_with_template($t):
- segs as $p | ($t | ltrimstr("/") | segs) as $q
- | ($p | length) >= ($q | length)
- and ([range(0; $q | length) as $i
- | ($p[($p | length) - ($q | length) + $i]) as $ps
- | (if ($q[$i] | test("^\\{.*\\}$")) then ($ps | length) > 0 else $ps == $q[$i] end)]
- | all);
- [.requests[] | select(.wasMatched)
- | select((.request.method | ascii_upcase) == ($m | ascii_upcase))
- | select((.request.url | split("?")[0]) | ends_with_template($t))
- | .response.status | tostring] | unique | join(",")'
- # ── Cases ────────────────────────────────────────────────────────────────────
- PASS=0; FAIL=0; UNPROVEN=0
- for query_file in "${run_cases[@]}"; do
- name="$(basename "${query_file%.graphql}")"
- expected="${query_file%.graphql}.expected.json"
- # Only the journal and scenario state reset — every stub loaded above
- # stays in place for every case: every stub is mounted flat.
- if ! curl -sf -X POST "$ADMIN/scenarios/reset" >/dev/null; then echo "FAIL: $name — could not reset scenario state"; FAIL=$((FAIL+1)); continue; fi
- if ! curl -sf -X DELETE "$ADMIN/requests" >/dev/null; then echo "FAIL: $name — could not reset the request journal"; FAIL=$((FAIL+1)); continue; fi
- if ! set_scenario_states "$name"; then echo "FAIL: $name — could not set its stub's scenario state"; FAIL=$((FAIL+1)); continue; fi
- actual="$(curl -sf -X POST "http://localhost:${ROUTER_PORT}/" -H 'Content-Type: application/json' \
- -d "$(jq -n --rawfile query "$query_file" '{query: $query}')")" || { echo "FAIL: $name — router request failed"; FAIL=$((FAIL+1)); continue; }
- # One read of each journal per case, each guarded, so an admin API that
- # fails fails this case with a line saying so instead of aborting the run.
- journal="$(curl -sf "$ADMIN/requests")" || { echo "FAIL: $name — could not read the request journal"; FAIL=$((FAIL+1)); continue; }
- unmatched_journal="$(curl -sf "$ADMIN/requests/unmatched")" || { echo "FAIL: $name — could not read the unmatched-request journal"; FAIL=$((FAIL+1)); continue; }
- unmatched="$(jq '.requests | length' <<< "$unmatched_journal")"
- matched="$(jq '[.requests[] | select(.wasMatched)] | length' <<< "$journal")"
- if grep -q 'expect-unmatched-upstream' "$query_file"; then
- if [[ "$unmatched" == "0" ]]; then echo "FAIL: $name — expected an unmatched upstream request, saw none (matched: $matched)"; FAIL=$((FAIL+1)); continue; fi
- else
- if [[ "$unmatched" != "0" ]]; then
- echo "FAIL: $name — $unmatched upstream request(s) matched no loaded stub:"
- jq -r '.requests[] | " \(.method) \(.url)\(if .body != "" then "\n body: \(.body)" else "" end)"' <<< "$unmatched_journal"
- FAIL=$((FAIL+1)); continue
- fi
- if [[ "$matched" == "0" ]]; then echo "FAIL: $name — case made no upstream request (dead stubs?)"; FAIL=$((FAIL+1)); continue; fi
- fi
- own=""
- for list in "$INDEX/shared.list" "$INDEX/case-$name.list"; do
- [[ -f "$list" ]] || continue
- while IFS= read -r m; do own+="$(basename "$m")"$'\n'; done < "$list"
- done
- foreign="$(jq -r '.requests[] | select(.wasMatched) | (.stubMapping.name // "<unnamed stub>")' <<< "$journal" \
- | while IFS= read -r n; do grep -qxF -- "$n" <<< "$own" || echo "$n"; done | LC_ALL=C sort -u | paste -sd, -)"
- if [[ -n "$foreign" ]]; then
- echo "FAIL: $name — answered by another case's stub: $foreign (the connector's request matched a fixture this case does not own)"
- FAIL=$((FAIL+1)); continue
- fi
- # A stub of the case's own marked `metadata."x-required": true` must have
- # answered at least one request: "some stub matched" cannot tell a $batch
- # case whose lookup ran from one the planner resolved without it.
- answered="$(jq -r '.requests[] | select(.wasMatched) | (.stubMapping.name // empty)' <<< "$journal" | LC_ALL=C sort -u)"
- uncalled=""
- if [[ -f "$INDEX/case-$name.list" ]]; then
- while IFS= read -r m; do
- if jq -e '.metadata["x-required"] == true' "$m" >/dev/null 2>&1 \
- && ! grep -qxF -- "$(basename "$m")" <<< "$answered"; then
- uncalled="$uncalled $(basename "$m")"
- fi
- done < "$INDEX/case-$name.list"
- fi
- if [[ -n "$uncalled" ]]; then
- echo "FAIL: $name — required stub(s) never called:$uncalled (metadata.\"x-required\": the case passes only when the router sends that request)"
- FAIL=$((FAIL+1)); continue
- fi
- # Every answering stub is the case's own by now. A status counts for an
- # operation only when the journal shows it answering that operation's own
- # request: the statuses a nested lookup or side call was served
- # belong to no operation under test. `OWN` holds one line per operation
- # whose root field the case calls: key, own statuses, documented statuses.
- served="$(jq -r '[.requests[] | select(.wasMatched) | .response.status] | unique | map(tostring) | join(",")' <<< "$journal")"
- OWN=""
- while IFS=$'\t' read -r field statuses _executed opkey; do
- [[ -n "$field" && -n "$opkey" ]] || continue
- grep -qw -- "$field" "$query_file" || continue
- own="$(jq -r --arg m "${opkey%%:*}" --arg t "${opkey#*:}" "$OWN_STATUSES_JQ" <<< "$journal")" \
- || { own=""; echo "e2e: could not read $opkey's own statuses from the journal" >&2; }
- OWN+="$opkey"$'\t'"${own:--}"$'\t'"$statuses"$'\n'
- done <<< "$ERROR_STATUSES"
- expect_status="$(sed -n 's/^#[[:space:]]*expect-upstream-status:[[:space:]]*\([0-9][0-9][0-9]\).*/\1/p' "$query_file" | head -1)"
- unproven=""
- credit=""
- if [[ -n "$expect_status" ]]; then
- hit=""
- while IFS=$'\t' read -r opkey own _documented; do
- [[ -n "$opkey" ]] || continue
- if grep -qxF -- "$expect_status" <<< "${own//,/$'\n'}"; then hit=1; credit+="$opkey $expect_status"$'\n'; fi
- done <<< "$OWN"
- if [[ -z "$OWN" ]]; then
- # No root field of the case names an included operation: nothing to
- # attribute a status to, so the case's own stubs are all there is.
- if grep -qxF -- "$expect_status" <<< "${served//,/$'\n'}"; then hit=1; fi
- fi
- if [[ -z "$hit" ]]; then
- answered="$(awk -F'\t' 'NF && $1 != "" {printf "%s answered %s; ", $1, ($2 == "-" ? "nothing" : $2)}' <<< "$OWN")"
- echo "FAIL: $name — expected the operation's own request to answer $expect_status (expect-upstream-status); ${answered:-its stubs answered ${served:-nothing}}${served:+(every request in the case: $served)}"
- FAIL=$((FAIL+1)); continue
- fi
- else
- while IFS=$'\t' read -r opkey own documented; do
- [[ -n "$opkey" && "$own" != "-" ]] || continue
- nonok="$(tr ',' '\n' <<< "$own" | grep -E '^[13-9][0-9][0-9]$' | paste -sd, - || true)"
- [[ -n "$nonok" ]] || continue
- if [[ "$documented" == *,* ]]; then
- unproven="$opkey's own request was answered $nonok, and it documents $documented: add \`# expect-upstream-status: CODE\`"
- break
- fi
- for c in ${nonok//,/ }; do credit+="$opkey $c"$'\n'; done
- done <<< "$OWN"
- [[ -z "$unproven" ]] || credit=""
- fi
- if [[ "$GENERATE" -eq 1 ]]; then
- echo "$actual" | jq -S . > "$expected"
- echo "WROTE: $(basename "$expected")"; PASS=$((PASS+1))
- [[ -z "$unproven" ]] || echo " unproven: $unproven"
- elif [[ ! -f "$expected" ]]; then
- echo "FAIL: $name — no expected file (run with --generate, then audit the snapshot)"; FAIL=$((FAIL+1))
- elif diff <(echo "$actual" | jq -S .) <(jq -S . "$expected") > /dev/null; then
- if [[ -n "$unproven" ]]; then
- echo "UNPROVEN: $name — $unproven"; UNPROVEN=$((UNPROVEN+1))
- else
- echo "PASS: $name"; PASS=$((PASS+1))
- # What this passing case proved, for evidence's per-status coverage:
- # a status served to an operation's own request, never to a side call.
- while read -r opkey code; do
- if [[ -n "$opkey" ]]; then echo "SERVED: $name $opkey $code"; fi
- done <<< "$credit"
- fi
- else
- echo "FAIL: $name"; diff <(echo "$actual" | jq -S .) <(jq -S . "$expected") || true; FAIL=$((FAIL+1))
- fi
- done
- if [[ "$GENERATE" -eq 1 ]]; then
- echo "e2e: $PASS expected files written, $FAIL failed — audit every snapshot for \"redacted\", \"valueCompletion\" and errors before committing"
- else
- echo "e2e: $PASS passed, $FAIL failed$([[ "$UNPROVEN" -eq 0 ]] || echo ", $UNPROVEN unproven")"
- fi
- [ "$FAIL" -eq 0 ]
skills/graphos-factory/graphos-factory-core/scripts/toolchain.sh · Bundled script · 147 lines · 2 findings marked
- #!/usr/bin/env bash
- # toolchain.sh — install the tools the validation layers shell out to.
- #
- # toolchain.sh # rover + the pinned supergraph plugin, Apollo Router, WireMock
- # toolchain.sh --check # exit 0 if all four are present at the pinned versions, 1 otherwise
- #
- # The supergraph plugin and the Apollo Router are licensed under the Elastic
- # License v2, which only the user can accept: read it, then set
- # APOLLO_ELV2_LICENSE=accept (see elv2.sh). This script never sets it. Unset,
- # it installs rover and WireMock, downloads neither the plugin nor the
- # Router, says so, and exits 0; compose, unit, e2e and live then report
- # `not_run` until the variable is set. --check reports a missing plugin or
- # Router with the same instruction (exit 1), and both present with the
- # variable unset as a note (exit 0: the tools are installed).
- #
- # One source of truth for the pins and their install paths; the SessionStart
- # hook and CI both call this instead of carrying their own copy:
- # rover $ROVER_VERSION + supergraph-v$FEDERATION_VERSION -> $HOME/.rover/bin (compose.sh, unit.sh, e2e.sh, live.sh)
- # router-$ROUTER_VERSION -> $GRAPHOS_FACTORY_CORE_CACHE (e2e.sh, live.sh)
- # wiremock-standalone-$WIREMOCK_VERSION.jar -> $GRAPHOS_FACTORY_CORE_CACHE (e2e.sh)
- # FEDERATION_VERSION must match pilots/*/*/.factory/workspace.yaml; ROUTER_VERSION
- # and WIREMOCK_VERSION must match the defaults in e2e.sh and live.sh.
- #
- # Java is not installed here: e2e.sh and live.sh need it, but every host this
- # runs on (the web container, CI's setup-java) already provides it. The
- # product binary is bootstrap.sh's job. $GRAPHOS_FACTORY_CORE_CACHE defaults as cache.sh
- # says.
- #
- # Idempotent: every step is skipped when its version is already in place.
- # Exit codes: 0 installed · 1 a download failed · 127 no router build for this platform.
- set -euo pipefail
- ROVER_VERSION="${ROVER_VERSION:-0.41.0}"
- FEDERATION_VERSION="${FEDERATION_VERSION:-2.15.2}"
- ROUTER_VERSION="${ROUTER_VERSION:-2.17.0}"
- WIREMOCK_VERSION="${WIREMOCK_VERSION:-3.13.2}"
- # shellcheck source=SCRIPTDIR/cache.sh
- . "$(dirname "$0")/cache.sh"
- CACHE="$GRAPHOS_FACTORY_CORE_CACHE_DIR"
- ROVER_BIN="$HOME/.rover/bin"
- ROUTER="$CACHE/router-$ROUTER_VERSION"
- WIREMOCK_JAR="$CACHE/wiremock-standalone-$WIREMOCK_VERSION.jar"
- export PATH="$ROVER_BIN:$PATH"
- # shellcheck source=SCRIPTDIR/elv2.sh
- . "$(dirname "$0")/elv2.sh"
- MODE="install"
- for arg in "$@"; do
- case "$arg" in
- --check) MODE="check" ;;
- -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
- *) echo "toolchain: unknown argument $arg" >&2; exit 1 ;;
- esac
- done
- have_rover() { [ "$("$ROVER_BIN/rover" --version 2>/dev/null || true)" = "Rover $ROVER_VERSION" ]; }
- have_plugin() { [ -x "$ROVER_BIN/supergraph-v$FEDERATION_VERSION" ]; }
- have_router() { [ -x "$ROUTER" ]; }
- have_wiremock() { [ -f "$WIREMOCK_JAR" ]; }
- router_platform() {
- case "$(uname -s)-$(uname -m)" in
- Linux-x86_64) echo "x86_64-unknown-linux-gnu" ;;
- Linux-aarch64) echo "aarch64-unknown-linux-gnu" ;;
- Darwin-x86_64) echo "x86_64-apple-darwin" ;;
- Darwin-arm64) echo "aarch64-apple-darwin" ;;
- *) echo "" ;;
- esac
- }
- if [ "$MODE" = "check" ]; then
- missing=0
- have_rover || { echo "toolchain: rover $ROVER_VERSION is not at $ROVER_BIN" >&2; missing=1; }
- # The two ELv2-licensed pieces: a missing one fails, and the instruction
- # is printed once when the user has not accepted.
- elv2_missing=0
- have_plugin || { echo "toolchain: supergraph plugin v$FEDERATION_VERSION is not at $ROVER_BIN" >&2; missing=1; elv2_missing=1; }
- have_router || { echo "toolchain: Apollo Router $ROUTER_VERSION is not at $ROUTER" >&2; missing=1; elv2_missing=1; }
- have_wiremock || { echo "toolchain: WireMock $WIREMOCK_VERSION is not at $WIREMOCK_JAR" >&2; missing=1; }
- if ! elv2_accepted; then
- [ "$elv2_missing" -eq 1 ] \
- || echo "toolchain: note — the supergraph plugin and the Apollo Router are installed, but APOLLO_ELV2_LICENSE is not set to accept" >&2
- elv2_explain toolchain
- fi
- [ "$missing" -eq 0 ] && echo "toolchain: rover $ROVER_VERSION, supergraph v$FEDERATION_VERSION, router $ROUTER_VERSION, wiremock $WIREMOCK_VERSION present"
- exit "$missing"
- fi
- # ── rover + composition plugin ───────────────────────────────────────────────
- if have_rover; then
- echo "rover $ROVER_VERSION already installed"
- else
- echo "installing rover $ROVER_VERSION"
- curl -fsSL "https://rover.apollo.dev/nix/v${ROVER_VERSION}" | sh -s -- --force
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 94 on GitHub
- fi
- # What the user's missing ELv2 acceptance held back, explained once at the end.
- held=""
- plugin="supergraph v$FEDERATION_VERSION"
- if have_plugin; then
- echo "supergraph plugin v$FEDERATION_VERSION already installed"
- elif elv2_accepted; then
- # rover reads the user's own APOLLO_ELV2_LICENSE=accept; no flag here.
- echo "installing supergraph plugin v$FEDERATION_VERSION"
- "$ROVER_BIN/rover" install --plugin "supergraph@=$FEDERATION_VERSION"
- else
- held="supergraph plugin v$FEDERATION_VERSION"
- plugin="no supergraph plugin"
- fi
- # ── router + WireMock for the e2e and live layers ────────────────────────────
- mkdir -p "$CACHE"
- router="router $ROUTER_VERSION"
- if have_router; then
- echo "router $ROUTER_VERSION already cached"
- elif ! elv2_accepted; then
- held="${held:+$held and the }Apollo Router $ROUTER_VERSION"
- router="no router"
- else
- platform="$(router_platform)"
- if [ -z "$platform" ]; then
- echo "toolchain: no Apollo Router build for $(uname -s)-$(uname -m); e2e.sh and live.sh will report it as skipped" >&2
- exit 127
- fi
- echo "caching Apollo Router $ROUTER_VERSION ($platform)"
- tmp="$(mktemp -d)"
- trap 'rm -rf "$tmp"' EXIT
- curl -fsSL "https://github.com/apollographql/router/releases/download/v${ROUTER_VERSION}/router-v${ROUTER_VERSION}-${platform}.tar.gz" \
- | tar xzf - -C "$tmp" --strip-components=1 dist/router
- mv "$tmp/router" "$ROUTER" && chmod +x "$ROUTER"
- fi
- if have_wiremock; then
- echo "WireMock $WIREMOCK_VERSION already cached"
- else
- echo "caching WireMock $WIREMOCK_VERSION"
- curl -fsSL "https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/${WIREMOCK_VERSION}/wiremock-standalone-${WIREMOCK_VERSION}.jar" \
- Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
- Line 137 on GitHub
- -o "$WIREMOCK_JAR"
- fi
- note=""
- if [ -n "$held" ]; then
- echo "toolchain: not downloading the $held" >&2
- elv2_explain toolchain
- note=" (APOLLO_ELV2_LICENSE not set to accept)"
- fi
- echo "toolchain: rover $ROVER_VERSION, $plugin, $router, wiremock $WIREMOCK_VERSION ready$note"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.