@embrace-ai/infra-api-schema-sync 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.0 (2025-06-19)
+
+
+### Bug Fixes
+
+* **commands:** remove unnecessary cli commands, update workflows, move bash to dispath-update ([14aa3a8](https://github.com/Embrace-AI/infra-api-schema-sync/commit/14aa3a82e142eb9c135bf6d409ad36d9cad5e20f))
+* **lockfile:** update lockfile ([706bf37](https://github.com/Embrace-AI/infra-api-schema-sync/commit/706bf372d80d49692db9159da6ff25593869064a))
+* **logging:** add globals for console logging in workflows ([fe00324](https://github.com/Embrace-AI/infra-api-schema-sync/commit/fe003249a5859b7769fce977556b71e610cb42d9))
+* **workflow:** move dispatch logic to js, and update consumer workflow ([b0ff4c1](https://github.com/Embrace-AI/infra-api-schema-sync/commit/b0ff4c14096d090a50a93795dc45f69e5f2a6d8e))
+* **workflows:** add issue_count and remove token in env ([662e8ad](https://github.com/Embrace-AI/infra-api-schema-sync/commit/662e8adae80cfc6a4f1ddfa389a28a94a7c04ac7))
+* **workflows:** only emit update on **/*schema.ts change, only show summary when issues are found ([2c2a589](https://github.com/Embrace-AI/infra-api-schema-sync/commit/2c2a589eff7192c833d008ac64e6bad6f5186acb))
+* **workflows:** restore workflow files ([63eb5ad](https://github.com/Embrace-AI/infra-api-schema-sync/commit/63eb5ad7e1a4f2e004f6fad3524d3d30bb0278aa))

package/README.md

@@ -0,0 +1,83 @@
+# CHANGEME
+
+## 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
+```
+
+## Releasing
+
+This project uses Github Actions to release to npmjs.

package/dist/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/dist/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":";AAEA,wBAyBG"}

package/dist/vitest.config.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("vitest/config");
+exports.default = (0, config_1.defineConfig)({
+    test: {
+        exclude: [
+            "**/node_modules/**",
+            "**/dist/**",
+            "**/.{idea,git,cache,output,temp}/**",
+            "**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*",
+        ],
+        chaiConfig: { truncateThreshold: 200 },
+        maxConcurrency: 20,
+        testTimeout: 20 * 1000, // 20 seconds
+        coverage: {
+            enabled: false,
+            exclude: [
+                "**/.idea/**",
+                "**/dist/**",
+                "**/node_modules/**",
+                "**/test-context.ts",
+            ],
+            reporter: ["text", "html"],
+        },
+    },
+    resolve: {
+        preserveSymlinks: true,
+    },
+});
+//# sourceMappingURL=vitest.config.js.map

package/dist/vitest.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.js","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":";;AAAA,0CAA6C;AAE7C,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE;QACJ,OAAO,EAAE;YACP,oBAAoB;YACpB,YAAY;YACZ,qCAAqC;YACrC,sFAAsF;SACvF;QACD,UAAU,EAAE,EAAE,iBAAiB,EAAE,GAAG,EAAE;QACtC,cAAc,EAAE,EAAE;QAClB,WAAW,EAAE,EAAE,GAAG,IAAI,EAAE,aAAa;QACrC,QAAQ,EAAE;YACR,OAAO,EAAE,KAAK;YACd,OAAO,EAAE;gBACP,aAAa;gBACb,YAAY;gBACZ,oBAAoB;gBACpB,oBAAoB;aACrB;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;SAC3B;KACF;IACD,OAAO,EAAE;QACP,gBAAgB,EAAE,IAAI;KACvB;CACF,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@embrace-ai/infra-api-schema-sync",
+  "version": "1.0.0",
+  "bin": {
+    "api-tool": "./dist/index.js"
+  },
+  "files": [
+    "src/",
+    "templates/",
+    "dist",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "description": "API schema synchronization tool for automated client validation and code generation across distributed repositories",
+  "author": "Embrace.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embrace-AI/infra-api-schema-sync"
+  },
+  "types": "dist/**/*.d.ts",
+  "keywords": [],
+  "type": "module",
+  "dependencies": {
+    "@graphql-codegen/cli": "^5.0.7",
+    "@graphql-codegen/typescript": "^4.1.6",
+    "@graphql-inspector/cli": "^5.0.8",
+    "commander": "^14.0.0",
+    "fs-extra": "^11.3.0",
+    "globals": "^16.2.0",
+    "graphql": "^16.11.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "1.3.0",
+    "@graphql-inspector/core": "6.2.1",
+    "@trivago/prettier-plugin-sort-imports": "5.2.2",
+    "@tsconfig/node20": "20.1.6",
+    "@types/node": "22.15.32",
+    "@typescript-eslint/eslint-plugin": "8.34.1",
+    "@typescript-eslint/parser": "8.34.1",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint": "9.29.0",
+    "eslint-config-prettier": "10.1.5",
+    "eslint-plugin-prefer-arrow": "1.2.3",
+    "eslint-plugin-prettier": "5.5.0",
+    "eslint-plugin-unused-imports": "4.1.4",
+    "prettier": "3.5.3",
+    "ts-pattern": "5.7.1",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "rebuild": "pnpm clean && pnpm build",
+    "types": "echo no types",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}

package/src/dispatch-update.js

@@ -0,0 +1,322 @@
+import { execSync } from "child_process";
+
+/**
+ * Dispatch schema update events to repositories
+ * @param {Object} options - Configuration options
+ * @param {string} options.schemaUrl - The schema URL to dispatch
+ * @param {string} options.sourceRepo - Source repository name
+ * @param {string} options.commit - Git commit SHA
+ * @param {string} options.branch - Git branch name
+ * @param {string} options.timestamp - ISO timestamp
+ * @param {string} options.token - GitHub token for API access
+ * @param {string} options.orgName - GitHub organization name
+ * @param {string} options.repoFilter - Regex pattern to filter repositories
+ * @param {boolean} options.dryRun - If true, only show what would be dispatched
+ */
+export const dispatchUpdate = async (options) => {
+  try {
+    const {
+      schemaUrl,
+      sourceRepo,
+      commit,
+      branch,
+      timestamp,
+      token,
+      orgName,
+      repoFilter = ".*",
+      dryRun = false,
+    } = options;
+
+    console.log("📡 Starting schema update dispatch...");
+    console.log(`🌐 Schema URL: ${schemaUrl}`);
+    console.log(`📁 Source Repository: ${sourceRepo}`);
+    console.log(`🔍 Organization: ${orgName}`);
+    console.log(`🎯 Repository Filter: ${repoFilter}`);
+
+    if (dryRun) {
+      console.log("DRY RUN MODE - No actual dispatches will be sent");
+    }
+
+    // Function to fetch repositories with pagination
+    const fetchAllRepos = async () => {
+      let page = 1;
+      const perPage = 100;
+      let allRepos = "";
+
+      while (true) {
+        console.log(`Fetching repos page ${page}...`);
+
+        // Fetch repositories for the organization
+        const response = await fetch(
+          `https://api.github.com/orgs/${orgName}/repos?page=${page}&per_page=${perPage}&type=all`,
+          {
+            headers: {
+              Authorization: `Bearer ${token}`,
+              Accept: "application/vnd.github.v3+json",
+            },
+          },
+        );
+
+        if (!response.ok) {
+          const errorData = await response.json();
+          throw new Error(
+            `GitHub API error: ${errorData.message || response.statusText}`,
+          );
+        }
+
+        const repos = await response.json();
+
+        // If no repos on this page, we're done
+        if (!repos || repos.length === 0) {
+          break;
+        }
+
+        // Extract repository names
+        const repoNames = repos.map((repo) => repo.full_name).join("\n");
+        allRepos += `${repoNames}\n`;
+
+        // Check if we got fewer than per_page results (last page)
+        if (repos.length < perPage) {
+          break;
+        }
+
+        page++;
+      }
+
+      return allRepos;
+    };
+
+    // Get all repositories
+    console.log("🔍 Fetching all organization repositories...");
+
+    // In dry-run mode with fake token, simulate some repositories
+    let allRepos;
+    if (dryRun && (token === "fake-token" || token.startsWith("fake"))) {
+      console.log("DRY RUN: Using simulated repositories");
+      allRepos = `${orgName}/repo1\n${orgName}/repo2\n${orgName}/frontend\n${sourceRepo}\n`;
+    } else {
+      allRepos = await fetchAllRepos();
+    }
+
+    // Filter repositories if pattern is provided
+    let filteredRepos;
+    if (repoFilter !== ".*") {
+      console.log(`🔍 Filtering repositories with pattern: ${repoFilter}`);
+      const repoList = allRepos.split("\n").filter((repo) => repo.trim());
+      const regex = new RegExp(repoFilter);
+      filteredRepos = repoList.filter((repo) => regex.test(repo)).join("\n");
+    } else {
+      filteredRepos = allRepos;
+    }
+
+    // Remove empty lines and current repository from the list
+    const targetRepos = filteredRepos
+      .split("\n")
+      .filter((repo) => repo.trim() && repo !== sourceRepo)
+      .filter((repo) => repo.length > 0);
+
+    if (targetRepos.length === 0) {
+      console.log("⚠️ No target repositories found to notify");
+      return { success: 0, errors: 0, total: 0 };
+    }
+
+    console.log(`Found ${targetRepos.length} repositories to notify:`);
+    targetRepos.forEach((repo) => console.log(`  - ${repo}`));
+    console.log("");
+
+    if (dryRun) {
+      console.log("DRY RUN: Would dispatch to the above repositories");
+      return {
+        success: targetRepos.length,
+        errors: 0,
+        total: targetRepos.length,
+        dryRun: true,
+      };
+    }
+
+    // Dispatch to each repository
+    let successCount = 0;
+    let errorCount = 0;
+
+    for (const repo of targetRepos) {
+      if (repo.trim()) {
+        console.log(`📡 Dispatching to repository: ${repo}`);
+
+        try {
+          const dispatchResponse = await fetch(
+            `https://api.github.com/repos/${repo}/dispatches`,
+            {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github.v3+json",
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                event_type: "graphql-schema-updated",
+                client_payload: {
+                  schemaUrl,
+                  sourceRepo,
+                  commit,
+                  branch,
+                  timestamp,
+                },
+              }),
+            },
+          );
+
+          if (dispatchResponse.status === 204) {
+            console.log("  ✅ Success");
+            successCount++;
+          } else {
+            console.log(`  ❌ Failed (HTTP ${dispatchResponse.status})`);
+            errorCount++;
+          }
+        } catch (error) {
+          console.log(`  ❌ Failed: ${error.message}`);
+          errorCount++;
+        }
+      }
+    }
+
+    console.log("");
+    console.log("📊 Dispatch Summary:");
+    console.log(`  ✅ Successful: ${successCount}`);
+    console.log(`  ❌ Failed: ${errorCount}`);
+    console.log(`  📋 Total: ${successCount + errorCount}`);
+
+    if (errorCount > 0) {
+      console.log(
+        "⚠️ Some dispatches failed. Check repository permissions and workflow file presence.",
+      );
+    }
+
+    return {
+      success: successCount,
+      errors: errorCount,
+      total: successCount + errorCount,
+    };
+  } catch (error) {
+    console.error(`❌ Failed to dispatch schema updates: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+/**
+ * Auto-detect values from environment or git
+ */
+const detectValues = () => {
+  const sourceRepo = process.env.GITHUB_REPOSITORY || detectRepositoryFromGit();
+  const commit = process.env.GITHUB_SHA || detectCommitFromGit();
+  const branch = process.env.GITHUB_REF_NAME || detectBranchFromGit();
+  const orgName =
+    process.env.GITHUB_REPOSITORY_OWNER || sourceRepo?.split("/")[0];
+  const timestamp = new Date().toISOString();
+
+  return { sourceRepo, commit, branch, orgName, timestamp };
+};
+
+const detectRepositoryFromGit = () => {
+  try {
+    const remoteUrl = execSync("git config --get remote.origin.url", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+
+    // Extract org/repo from various URL formats
+    const match = remoteUrl.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    return match ? match[1] : null;
+  } catch (error) {
+    console.warn("Failed to detect repository from git:", error.message);
+    return null;
+  }
+};
+
+const detectCommitFromGit = () => {
+  try {
+    return execSync("git rev-parse HEAD", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+  } catch (error) {
+    console.warn("Failed to detect commit from git:", error.message);
+    return null;
+  }
+};
+
+const detectBranchFromGit = () => {
+  try {
+    return execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+  } catch (error) {
+    console.warn("Failed to detect branch from git:", error.message);
+    return null;
+  }
+};
+
+/**
+ * CLI command handler
+ */
+export const dispatchUpdateCommand = async (opts) => {
+  const {
+    schemaUrl,
+    sourceRepo: providedSourceRepo,
+    commit: providedCommit,
+    branch: providedBranch,
+    token,
+    orgName: providedOrgName,
+    repoFilter,
+    dryRun,
+  } = opts;
+
+  // Auto-detect missing values
+  const detected = detectValues();
+
+  const sourceRepo = providedSourceRepo || detected.sourceRepo;
+  const commit = providedCommit || detected.commit;
+  const branch = providedBranch || detected.branch;
+  const orgName = providedOrgName || detected.orgName;
+  const timestamp = detected.timestamp;
+
+  // Validate required parameters
+  if (!schemaUrl) {
+    throw new Error("Schema URL is required (--schema-url)");
+  }
+  if (!token) {
+    throw new Error("GitHub token is required (--token)");
+  }
+  if (!sourceRepo) {
+    throw new Error(
+      "Source repository could not be detected. Please provide --source-repo",
+    );
+  }
+  if (!orgName) {
+    throw new Error(
+      "Organization name could not be detected. Please provide --org-name",
+    );
+  }
+
+  console.log("🔧 Preparing schema update dispatch...");
+  console.log(`📁 Source Repository: ${sourceRepo}`);
+  console.log(`🏷️  Commit: ${commit || "not detected"}`);
+  console.log(`🌿 Branch: ${branch || "not detected"}`);
+  console.log(`🏢 Organization: ${orgName}`);
+  console.log(`⏰ Timestamp: ${timestamp}`);
+
+  return dispatchUpdate({
+    schemaUrl,
+    sourceRepo,
+    commit,
+    branch,
+    timestamp,
+    token,
+    orgName,
+    repoFilter,
+    dryRun,
+  });
+};
+
+// Default export for CLI
+export default dispatchUpdateCommand;

package/src/fetch-schema.js

@@ -0,0 +1,65 @@
+import fs from "fs";
+import fse from "fs-extra";
+import { buildClientSchema, getIntrospectionQuery, printSchema } from "graphql";
+import path from "path";
+
+export const fetchSchema = async ({ url, output }) => {
+  try {
+    console.log(`🔄 Fetching GraphQL schema from ${url}...`);
+
+    // Prepare introspection query
+    const introspectionQuery = getIntrospectionQuery();
+
+    // Fetch schema using introspection
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        query: introspectionQuery,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const result = await response.json();
+
+    if (result.errors) {
+      throw new Error(
+        `GraphQL errors: ${result.errors.map((e) => e.message).join(", ")}`,
+      );
+    }
+
+    if (!result.data) {
+      throw new Error("No data returned from introspection query");
+    }
+
+    // Build schema from introspection result
+    const schema = buildClientSchema(result.data);
+
+    // Convert schema to SDL (Schema Definition Language)
+    const schemaSDL = printSchema(schema);
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(output);
+    fse.ensureDirSync(outputDir);
+
+    // Write schema to file
+    fs.writeFileSync(output, schemaSDL, "utf8");
+
+    console.log(`✅ Schema successfully saved to ${output}`);
+    console.log(
+      `📊 Schema contains ${Object.keys(schema.getTypeMap()).length} types`,
+    );
+  } catch (error) {
+    console.error(`❌ Failed to fetch schema: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+// Default export for CLI
+export default fetchSchema;

package/src/generate-schema-url.js

@@ -0,0 +1,165 @@
+import { execSync } from "child_process";
+import path from "path";
+
+/**
+ * Generate a dynamic GraphQL schema URL based on repository and deployment stage
+ * @param {Object} options - Configuration options
+ * @param {string} options.stage - Deployment stage (dev, prod, pr-*)
+ * @param {string} options.service - Service name (optional, auto-detected if not provided)
+ * @param {string} options.repo - Repository name (optional, auto-detected if not provided)
+ * @returns {string} The generated schema URL
+ */
+export const buildSchemaUrl = ({ stage = "dev", service, repo }) => {
+  // Auto-detect repository name if not provided
+  if (!repo) {
+    repo = detectRepositoryName();
+  }
+
+  // Auto-detect service name if not provided
+  if (!service) {
+    service = extractServiceName(repo);
+  }
+
+  // Special case for embrace repository - always use the main API URL
+  if (
+    service === "embrace" ||
+    repo === "embrace" ||
+    repo.endsWith("/embrace")
+  ) {
+    return buildEmbraceUrl(stage);
+  }
+
+  // Build URL for other services
+  return buildServiceUrl(service, stage);
+};
+
+/**
+ * Build URL for the main embrace service
+ * @param {string} stage - Deployment stage
+ * @returns {string} The embrace service URL
+ */
+const buildEmbraceUrl = (stage) => {
+  switch (stage) {
+    case "dev":
+      return "https://api.dev.embrace.ai/v2/graphql/schema";
+    default:
+      if (stage.startsWith("pr-")) {
+        return `https://api.${stage}.dev.embrace.ai/v2/graphql/schema`;
+      }
+      // Default to dev pattern for unknown stages
+      return "https://api.dev.embrace.ai/v2/graphql/schema";
+  }
+};
+
+/**
+ * Build URL for microservices
+ * @param {string} service - Service name
+ * @param {string} stage - Deployment stage
+ * @returns {string} The service URL
+ */
+const buildServiceUrl = (service, stage) => {
+  switch (stage) {
+    case "prod":
+      return `https://api.${service}.services.embrace.ai/graphql/schema`;
+    case "dev":
+      return `https://api.${service}.services.dev.embrace.ai/graphql/schema`;
+    default:
+      if (stage.startsWith("pr-")) {
+        return `https://api.${service}.${stage}.services.dev.embrace.ai/graphql/schema`;
+      }
+      // Default to dev pattern for unknown stages
+      return `https://api.${service}.services.dev.embrace.ai/graphql/schema`;
+  }
+};
+
+/**
+ * Detect the current repository name from git
+ * @returns {string} Repository name
+ */
+const detectRepositoryName = () => {
+  try {
+    // Try to get repository name from git remote
+    const remoteUrl = execSync("git config --get remote.origin.url", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+
+    // Extract repository name from various URL formats
+    // https://github.com/org/repo.git -> repo
+    // git@github.com:org/repo.git -> repo
+    // https://github.com/org/repo -> repo
+    const match = remoteUrl.match(/[/:]([^/]+?)(?:\.git)?$/);
+    if (match) {
+      return match[1];
+    }
+  } catch (error) {
+    // Fallback: try to get from current directory name
+    console.warn(
+      "⚠️ Could not detect repository from git, using directory name: ",
+      error.message,
+    );
+  }
+
+  // Fallback to current directory name
+  return path.basename(process.cwd());
+};
+
+/**
+ * Extract service name from repository name
+ * @param {string} repo - Repository name
+ * @returns {string} Service name
+ */
+const extractServiceName = (repo) => {
+  // Handle common repository naming patterns
+  // Remove common prefixes/suffixes but preserve the core service name
+  let serviceName = repo
+    .replace(/^(api-|service-|microservice-|ms-)/, "") // Remove API prefixes
+    .replace(/(-api|-service|-microservice|-ms)$/, "") // Remove API suffixes
+    .replace(/^embrace-/, ""); // Remove embrace prefix
+
+  // Handle special cases
+  if (serviceName === "embrace" || serviceName === "") {
+    return "embrace";
+  }
+
+  // Keep the full service name (e.g., "orgs-core", "integrations-plugins")
+  return serviceName;
+};
+
+/**
+ * CLI command handler
+ */
+export const generateSchemaUrl = (opts) => {
+  try {
+    const { stage, service, repo } = opts;
+
+    console.log("🔧 Generating schema URL...");
+
+    // Detect values if not provided
+    const detectedRepo = repo || detectRepositoryName();
+    const detectedService = service || extractServiceName(detectedRepo);
+
+    console.log(`📁 Repository: ${detectedRepo}`);
+    console.log(`🏷️  Service: ${detectedService}`);
+    console.log(`🚀 Stage: ${stage}`);
+
+    const url = buildSchemaUrl({
+      stage,
+      service: detectedService,
+      repo: detectedRepo,
+    });
+
+    console.log(`🌐 Generated URL: ${url}`);
+
+    // Output just the URL for easy consumption by scripts
+    process.stdout.write(url);
+
+    return url;
+  } catch (error) {
+    console.error(`❌ Failed to generate schema URL: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+// Default export for CLI
+export default generateSchemaUrl;

package/src/generate-summary.js

@@ -0,0 +1,61 @@
+import fs from "fs";
+
+export const generateSummaryFromReport = (report) => {
+  if (!report || report.length === 0) {
+    return "No GraphQL validation errors found.";
+  }
+
+  let output = "## 🚨 GraphQL Schema Validation Issues\n\n";
+
+  // Group issues by file
+  const grouped = report.reduce((acc, issue) => {
+    const file = issue.location?.file || "Unknown file";
+    if (!acc[file]) {
+      acc[file] = [];
+    }
+    acc[file].push(issue);
+    return acc;
+  }, {});
+
+  for (const [file, issues] of Object.entries(grouped)) {
+    output += `### \`${file}\`\n`;
+    issues.forEach(({ message, location, operation }) => {
+      const line = location?.line || "?";
+      output += `- ❌ \`${operation || "Unknown Operation"}\`: ${message} (line ${line})\n`;
+    });
+    output += "\n";
+  }
+
+  return output;
+};
+
+// CLI function that handles file I/O
+export const generateSummary = (opts) => {
+  const reportPath = opts.report;
+  const outputPath = opts.output;
+
+  const raw = fs.readFileSync(reportPath, "utf-8");
+  const report = JSON.parse(raw);
+
+  const summary = generateSummaryFromReport(report);
+
+  if (outputPath) {
+    fs.writeFileSync(outputPath, summary, "utf-8");
+    console.log(`✅ Summary written to ${outputPath}`);
+  } else {
+    console.log(summary);
+  }
+};
+
+// Support direct script usage (for backwards compatibility)
+if (process.argv[1] && process.argv[1].endsWith("generate-summary.js")) {
+  const reportPath = process.argv[2] || "report.json";
+  const raw = fs.readFileSync(reportPath, "utf-8");
+  const report = JSON.parse(raw);
+
+  const summary = generateSummaryFromReport(report);
+  console.log(summary);
+}
+
+// Default export for CLI
+export default generateSummary;

package/src/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+const program = new Command();
+
+program
+  .name("api-tool")
+  .description("CLI for API schema management")
+  .version("0.1.0");
+
+program
+  .command("fetch")
+  .description("Fetch GraphQL schema from a URL")
+  .requiredOption("--url <url>", "Schema URL")
+  .requiredOption("--output <file>", "Output file path")
+  .action(async (opts) => {
+    const { default: fetchSchema } = await import("./fetch-schema.js");
+    return fetchSchema(opts);
+  });
+
+program
+  .command("validate")
+  .description("Validate queries against schema")
+  .requiredOption("--schema <file>", "Schema file path")
+  .requiredOption("--queries <glob>", "Glob pattern to GraphQL query files")
+  .requiredOption("--output <file>", "JSON report output")
+  .action(async (opts) => {
+    const { default: validateSchema } = await import("./validate-schema.js");
+    return validateSchema(opts);
+  });
+
+program
+  .command("summarize")
+  .description("Generate markdown from a validation report")
+  .requiredOption("--report <file>", "Validation JSON report")
+  .requiredOption("--output <file>", "Markdown file path")
+  .action(async (opts) => {
+    const { default: generateSummary } = await import("./generate-summary.js");
+    return generateSummary(opts);
+  });
+
+program
+  .command("generate-schema-url")
+  .description("Generate dynamic schema URL based on repository and stage")
+  .option("--stage <stage>", "Deployment stage (dev, prod, pr-*)", "dev")
+  .option(
+    "--service <service>",
+    "Service name (auto-detected from repo if not provided)",
+  )
+  .option(
+    "--repo <repo>",
+    "Repository name (auto-detected from git if not provided)",
+  )
+  .action(async (opts) => {
+    const { default: generateSchemaUrl } = await import(
+      "./generate-schema-url.js"
+    );
+    return generateSchemaUrl(opts);
+  });
+
+program
+  .command("dispatch-update")
+  .description("Dispatch schema update events to organization repositories")
+  .requiredOption("--schema-url <url>", "Schema URL to dispatch")
+  .requiredOption("--token <token>", "GitHub token for API access")
+  .option(
+    "--source-repo <repo>",
+    "Source repository (auto-detected if not provided)",
+  )
+  .option("--commit <sha>", "Git commit SHA (auto-detected if not provided)")
+  .option(
+    "--branch <branch>",
+    "Git branch name (auto-detected if not provided)",
+  )
+  .option(
+    "--org-name <org>",
+    "GitHub organization name (auto-detected if not provided)",
+  )
+  .option(
+    "--repo-filter <pattern>",
+    "Regex pattern to filter repositories",
+    ".*",
+  )
+  .option("--dry-run", "Show what would be dispatched without sending", false)
+  .action(async (opts) => {
+    const { default: dispatchUpdate } = await import("./dispatch-update.js");
+    return dispatchUpdate(opts);
+  });
+
+program.parse();

package/src/validate-schema.js

@@ -0,0 +1,157 @@
+import { validate } from "@graphql-inspector/core";
+import fs from "fs";
+import fse from "fs-extra";
+import { buildSchema } from "graphql";
+import path from "path";
+
+export const validateSchema = async ({ schema, queries, output }) => {
+  try {
+    console.log(`🔄 Validating GraphQL queries against schema...`);
+    console.log(`📄 Schema: ${schema}`);
+    console.log(`🔍 Queries: ${queries}`);
+
+    // Validate input files exist
+    if (!fs.existsSync(schema)) {
+      throw new Error(`Schema file not found: ${schema}`);
+    }
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(output);
+    fse.ensureDirSync(outputDir);
+
+    // Load and parse the schema
+    const schemaContent = fs.readFileSync(schema, "utf8");
+    const graphqlSchema = buildSchema(schemaContent);
+
+    // Find and load query files based on the glob pattern
+    const queryFiles = findFiles(queries);
+
+    if (queryFiles.length === 0) {
+      console.log(`⚠️  No query files found matching pattern: ${queries}`);
+    }
+
+    // Create source objects for GraphQL Inspector
+    const sources = queryFiles.map((filePath) => ({
+      name: filePath,
+      body: fs.readFileSync(filePath, "utf8"),
+      location: filePath,
+    }));
+
+    console.log(
+      `🚀 Validating ${sources.length} query file(s) against schema...`,
+    );
+
+    // Run validation using GraphQL Inspector core
+    const invalidDocuments = validate(graphqlSchema, sources, {
+      strictDeprecated: false, // Don't fail on deprecated usage by default
+      strictFragments: true,
+      apollo: false,
+    });
+
+    // Transform the results to match expected output format
+    const validationReport = [];
+
+    for (const doc of invalidDocuments) {
+      // Add validation errors
+      for (const error of doc.errors) {
+        validationReport.push({
+          message: error.message,
+          location: {
+            file: doc.source.name,
+            line: error.locations?.[0]?.line || 1,
+            column: error.locations?.[0]?.column || 1,
+          },
+          operation: "validation",
+        });
+      }
+
+      // Add deprecated usage warnings
+      for (const deprecated of doc.deprecated) {
+        validationReport.push({
+          message: `Deprecated: ${deprecated.message}`,
+          location: {
+            file: doc.source.name,
+            line: deprecated.locations?.[0]?.line || 1,
+            column: deprecated.locations?.[0]?.column || 1,
+          },
+          operation: "deprecated",
+        });
+      }
+    }
+
+    // Write validation report to output file
+    fs.writeFileSync(output, JSON.stringify(validationReport, null, 2), "utf8");
+
+    // Log results
+    const errorCount = validationReport.length;
+    if (errorCount === 0) {
+      console.log(`✅ Validation completed successfully - no issues found`);
+      console.log(`📊 Report saved to ${output}`);
+    } else {
+      console.log(`⚠️  Validation completed with ${errorCount} issue(s) found`);
+      console.log(`📊 Report saved to ${output}`);
+
+      // Show summary of issues
+      const fileGroups = validationReport.reduce((acc, issue) => {
+        const file = issue.location?.file || "Unknown file";
+        acc[file] = (acc[file] || 0) + 1;
+        return acc;
+      }, {});
+
+      console.log(`📋 Issues by file:`);
+      Object.entries(fileGroups).forEach(([file, count]) => {
+        console.log(`   ${file}: ${count} issue(s)`);
+      });
+    }
+  } catch (error) {
+    console.error(`❌ Validation failed: ${error.message}`);
+    process.exit(1);
+  }
+};
+
+const findFiles = (pattern) => {
+  // Simple glob-like pattern matching for GraphQL files
+  // This handles basic patterns like "*.graphql", "**/*.graphql", etc.
+
+  if (fs.existsSync(pattern) && fs.statSync(pattern).isFile()) {
+    // If it's a direct file path, return it
+    return [pattern];
+  }
+
+  // Handle glob patterns
+  const files = [];
+
+  if (pattern.includes("*")) {
+    // Basic glob support - find all .graphql files in current directory
+    const dir = pattern.includes("/") ? path.dirname(pattern) : ".";
+    const searchDir = fs.existsSync(dir) ? dir : ".";
+
+    const searchDirectory = (dirPath, recursive = false) => {
+      const entries = fs.readdirSync(dirPath);
+
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry);
+        const stat = fs.statSync(fullPath);
+
+        if (stat.isDirectory() && recursive) {
+          searchDirectory(fullPath, true);
+        } else if (stat.isFile() && entry.endsWith(".graphql")) {
+          files.push(fullPath);
+        }
+      }
+    };
+
+    const recursive = pattern.includes("**");
+    searchDirectory(searchDir, recursive);
+  } else {
+    // Direct file or simple pattern
+    if (fs.existsSync(pattern)) {
+      files.push(pattern);
+    }
+  }
+
+  return files;
+};
+
+// Default export for CLI
+export default validateSchema;

package/templates/workflows/emit-schema-update.yml

@@ -0,0 +1,83 @@
+# .github/workflows/emit-schema-update.yml
+name: Emit GraphQL Schema Update Event
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**/*schema.ts'
+
+env:
+  # Configure these environment variables for your setup
+  # SCHEMA_URL will be dynamically generated based on repository and stage
+  # You can override this by setting a static URL if needed
+  # SCHEMA_URL: "https://api.dev.embrace.ai/v2/graphql/schema"
+
+  # Deployment stage - determines the environment URL pattern
+  DEPLOYMENT_STAGE: "dev"  # Options: dev, prod, pr-* (e.g., pr-123)
+  # Optional: Override service name (auto-detected from repository name if not set)
+  # SERVICE_NAME: "your-service-name"
+
+  # Optional: Filter repositories by name pattern (regex)
+  REPO_FILTER: ".*"  # Default: all repos. Example: "^(frontend|mobile|web)-.*" for specific patterns
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  emit-schema-update:
+    runs-on: ubuntu-latest
+    container:
+      image: node:22.16.0@sha256:71bcbb3b215b3fa84b5b167585675072f4c270855e37a599803f1a58141a0716
+      options: --privileged --user root
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+      - name: Setup node cache
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.16.0
+          cache: 'pnpm'
+      - name: Setup NPM
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm config set //registry.npmjs.org/:_authToken "${NPM_TOKEN}"
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: Install GraphQL schema sync tool
+        run: npm install @embrace-ai/infra-api-schema-sync
+      # Generate dynamic schema URL based on repository and stage
+      - name: Generate schema URL
+        id: schema-url
+        run: |
+          # Generate URL using the CLI tool
+          if [ -n "$SERVICE_NAME" ]; then
+            SCHEMA_URL=$(npx api-tool generate-schema-url --stage "$DEPLOYMENT_STAGE" --service "$SERVICE_NAME")
+          else
+            SCHEMA_URL=$(npx api-tool generate-schema-url --stage "$DEPLOYMENT_STAGE")
+          fi
+
+          # Set as output for use in later steps
+          echo "url=$SCHEMA_URL" >> $GITHUB_OUTPUT
+          echo "🌐 Generated schema URL: $SCHEMA_URL"
+
+
+      # Fetch all organization repositories and dispatch to each
+      - name: Dispatch schema update events to all org repositories
+        env:
+          # GitHub token with repo scope - defaults to GITHUB_TOKEN but can be overridden
+          # Use the dynamically generated schema URL
+          SCHEMA_URL: ${{ steps.schema-url.outputs.url }}
+        run: |
+          npx api-tool dispatch-update \
+            --schema-url "$SCHEMA_URL" \
+            --token "${{ secrets.GITHUB_TOKEN }}" \
+            --source-repo "${{ github.repository }}" \
+            --commit "${{ github.sha }}" \
+            --branch "${{ github.ref_name }}" \
+            --org-name "${{ github.repository_owner }}" \
+            --repo-filter "$REPO_FILTER"

package/templates/workflows/graphql-schema-validate.yml

@@ -0,0 +1,106 @@
+# .github/workflows/graphql-schema-validate.yml
+name: Validate GraphQL Schema Updates
+
+on:
+  repository_dispatch:
+    types: [graphql-schema-updated]
+
+
+jobs:
+  validate-schema:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup node cache
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.16.0
+          cache: 'pnpm'
+
+      - name: Setup NPM
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: pnpm config set //registry.npmjs.org/:_authToken "${NPM_TOKEN}"
+
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: Install GraphQL schema sync tool
+        run: npm install @embrace-ai/infra-api-schema-sync
+
+      - name: Configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v4.2.1
+        with:
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_DEV }}
+          aws-region: ${{ vars.AWS_REGION }}
+
+      - name: Display schema update context
+        run: |
+          echo "Schema update received from: ${{ github.event.client_payload.sourceRepo }}"
+          echo "Schema URL: ${{ github.event.client_payload.schemaUrl }}"
+          echo "Source commit: ${{ github.event.client_payload.commit }}"
+          echo "Source branch: ${{ github.event.client_payload.branch }}"
+          echo "Timestamp: ${{ github.event.client_payload.timestamp }}"
+
+      - name: Fetch updated schema
+        run: npx api-tool fetch --url ${{ github.event.client_payload.schemaUrl }} --output new-schema.graphql
+
+      - name: Validate queries against new schema
+        id: validate
+        run: npx api-tool validate --schema new-schema.graphql --queries 'src/**/*.graphql' --output report.json
+
+      - name: Check for issues
+        id: check-issues
+        run: |
+          if [ -s report.json ] && [ "$(jq '.issues | length' report.json)" -gt 0 ]; then
+            echo "has_issues=true" >> $GITHUB_OUTPUT
+            echo "issue_count=$(jq '.issues | length' report.json)" >> $GITHUB_OUTPUT
+          else
+            echo "has_issues=false" >> $GITHUB_OUTPUT
+            echo "issue_count=0" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Generate summary
+        id: gen-summary
+        if: steps.check-issues.outputs.has_issues == 'true'
+        run: npx api-tool summarize --report report.json --output GRAPHQL_ISSUES.md && echo "summary=$(cat GRAPHQL_ISSUES.md)" >> $GITHUB_OUTPUT
+
+      - name: Commit and create PR with issues
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore(api): GraphQL schema update from ${{ github.event.client_payload.sourceRepo }}"
+          branch: "graphql/schema-update-${{ github.run_id }}"
+          title: "GraphQL Schema Update (${{ steps.check-issues.outputs.issue_count }} issues)"
+          body: |
+            # GraphQL Schema Update Impact Report
+
+            **Schema Source:** ${{ github.event.client_payload.sourceRepo }}
+            **Schema URL:** ${{ github.event.client_payload.schemaUrl }}
+            **Source Commit:** ${{ github.event.client_payload.commit }}
+            **Source Branch:** ${{ github.event.client_payload.branch }}
+            **Update Time:** ${{ github.event.client_payload.timestamp }}
+
+            ---
+            ## ${{ steps.check-issues.outputs.has_issues == 'true' && 'Detected Issues' || '🎉 No Issues Found' }}
+            ${{
+              steps.check-issues.outputs.has_issues == 'true'
+                ? steps.gen-summary.outputs.summary
+                : 'The updated schema is compatible with your existing GraphQL queries. No changes are required.'
+            }}
+
+            ## Next Steps
+            1. Review the compatibility issues above
+            2. Update your GraphQL queries to match the new schema
+            3. Test your changes thoroughly
+            4. Merge this PR once all issues are resolved
+
+      - name: Create success comment
+        if: steps.check-issues.outputs.has_issues == 'false'
+        run: |
+          echo "✅ No GraphQL compatibility issues found!"
+          echo "Schema from ${{ github.event.client_payload.sourceRepo }} is compatible with existing queries."