# GraphQL API Schema Sync Tool

A CLI tool and GitHub Actions workflow templates for synchronizing GraphQL schema changes across multiple repositories in an organization.

## Features

- **Schema Fetching**: Download GraphQL schema SDL over an AWS-signed GET request
- **Schema Validation**: Validate GraphQL queries against a schema
- **Smart Dispatch**: Automatically notify repositories that have the schema validation workflow
- **Workflow Templates**: Ready-to-use GitHub Actions workflows for emitting and consuming schema updates

## Key Capabilities

### Intelligent Repository Discovery

The `dispatch-update` command automatically:

- Scans all repositories in your organization
- Checks each repository for the `graphql-schema-updated` workflow
- Only dispatches to repositories that can handle the event
- Skips repositories without the workflow (avoiding 403 errors)

This ensures that:

- The main `embrace` repository receives schema updates
- Repositories without GraphQL dependencies are not notified
- You get clear feedback about which repos were notified vs. skipped

## Setup

### Node

This project uses `nvm` ([Node Version Manager](https://github.com/nvm-sh/nvm))
and `pnpm` ([Package Node Modules](https://pnpm.js.org/)).

1.  Install `nvm`
2.  `cd` to the project directory and execute the following:
    ```
    nvm install
    nvm use
    ```
3.  Install `pnpm`
    ```
    npm install -g pnpm
    ```
4.  Install dependencies
    ```
    pnpm install
    ```

### IDE Setup

This project uses [EditorConfig](https://editorconfig.org/) for IDE configuration.

See `.editorconfig` for settings.

Many popular IDEs and editors support this out of the box or with a plugin.

## Development

### Prettier

This project uses [Prettier](https://prettier.io/), so please run it before checking in:

```
pnpm prettier-format
```

See `.prettierrc` for settings.

Some IDEs and editors have plugins for running Prettier.

### Linting

This project uses [ESLint](https://eslint.org/). Check linting before checking in:

```
pnpm lint
```

See `eslint.config.mjs` for settings.

Many IDEs and editors support ESLint.

### Typechecking

In addition, running typecheck is recommended before checking in:

```
pnpm -R typecheck
```

## Testing

This project uses [Vitest](https://vitest.dev/) for testing. Run tests before checking in.

```
pnpm test
```

## Building

```
pnpm build
```

## Usage

### CLI Commands

#### `dispatch-update`

Dispatch schema update events to repositories in your organization:

```bash
pnpm exec api-tool dispatch-update \
  --schema-url "https://api.dev.embrace.ai/v2/graphql/schema" \
  --token "$GITHUB_TOKEN" \
  --source-repo "Embrace-AI/my-api" \
  --commit "$GITHUB_SHA" \
  --branch "$GITHUB_REF_NAME" \
  --org-name "Embrace-AI"
```

**How it works:**

1. Fetches all repositories in the organization
2. Checks each repository for `.github/workflows/*.yml` files
3. Looks for workflows with `repository_dispatch` trigger and `graphql-schema-updated` event type
4. Only dispatches to repositories that have the workflow configured
5. Reports which repositories were notified and which were skipped

**Example output:**

```
🔍 Checking 50 repositories for workflow files...

✅ Found 2 repositories with workflow:
  - Embrace-AI/embrace
  - Embrace-AI/frontend

⏭️  Skipped 48 repositories without workflow:
  - Embrace-AI/sse.js
  - Embrace-AI/terraboard
  ...
```

#### Other Commands

- `fetch` - Fetch GraphQL schema from a URL
- `validate` - Validate queries against schema
- `summarize` - Generate markdown from validation report
- `generate-schema-url` - Generate dynamic schema URL

See workflow templates in `templates/workflows/` for complete examples.

## Releasing

This project uses Github Actions to release to npmjs.