getcargohq__cargo-skills/.github/scripts/sync-trigger-slugs.ts

/**
 * Keeps the integration/provider name lists inside SKILL.md descriptions in
 * sync with what the workspace actually supports.
 *
 * Proper nouns are the highest-precision routing tokens an agent has: a user
 * who says "enrich this with FullEnrich" or "connect my HubSpot" names
 * something Cargo supports, and the description is the only text the agent
 * weighs before loading a skill. Hand-maintaining those lists guarantees
 * drift, so they are generated:
 *
 *   cargo-gtm         `Providers: …`     ← cargo-gtm/provider-playbooks/*.md
 *   cargo-connection  `Integrations: …`  ← .github/data/integrations.json
 *                                          (systems-of-record categories)
 *
 * Usage:
 *   node .github/scripts/sync-trigger-slugs.ts           # rewrite descriptions
 *   node .github/scripts/sync-trigger-slugs.ts --check   # CI: fail if stale
 *   node .github/scripts/sync-trigger-slugs.ts --refresh # re-pull the catalog
 *                                                          (needs a logged-in
 *                                                           cargo-ai CLI)
 *
 * Requires Node >= 22.18 (run as .ts via native type-stripping).
 */

import { readdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
import { execFileSync } from "node:child_process";
import { join, dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
const catalogPath = join(repoRoot, ".github/data/integrations.json");

/**
 * Integrations that must never reach a skill, a description, or the committed
 * catalog, whatever the API returns.
 *
 * This is a product decision, not a technical one, so it is enforced in code
 * rather than left to whoever next runs `--refresh`. The catalog is generated,
 * so deleting an entry by hand lasts exactly until the next refresh puts it
 * back; the filter below is what makes the removal stick.
 *
 * `datachimp` — excluded on Aurelien's instruction, 2026-08-15. It is also an
 * integration with **zero callable actions**, so nothing was lost.
 */
const DENIED_INTEGRATIONS = new Set(["datachimp"]);

/**
 * Categories whose integrations are systems a user *names* when they want to
 * connect Cargo to something they already run — CRMs, sequencers, warehouses,
 * ad platforms, support desks. The `enrichment` category is deliberately
 * excluded: those are routed by cargo-gtm via provider playbooks, and listing
 * ~73 of them twice would blunt both descriptions.
 */
const OPS_CATEGORIES = new Set([
  "sales",
  "marketing",
  "storage",
  "analytics",
  "support",
  "finance",
]);

/** Freeform-category integrations that are still recognizable destinations. */
const OPS_EXTRAS = ["slack", "microsoftTeams", "notionMcp", "http"];

interface Integration {
  slug: string;
  name: string;
  category: string;
  actions: number;
  credits: boolean;
}

function refreshCatalog(): void {
  const raw = execFileSync("cargo-ai", ["connection", "integration", "list"], {
    encoding: "utf8",
    maxBuffer: 64 * 1024 * 1024,
  });
  const parsed = JSON.parse(raw) as { integrations?: unknown[] };
  const list = parsed.integrations ?? [];
  const integrations: Integration[] = list
    .filter((raw) => !DENIED_INTEGRATIONS.has(String((raw as Record<string, any>).slug)))
    .map((raw) => {
      const i = raw as Record<string, any>;
      return {
        slug: String(i.slug),
        name: String(i.name ?? i.slug),
        category: String(i.category ?? "other"),
        actions: Object.keys(i.actions ?? {}).length,
        credits: Boolean(i.connector?.credits?.isCompatible),
      };
    })
    .sort((a, b) => a.slug.localeCompare(b.slug));

  writeFileSync(
    catalogPath,
    JSON.stringify(
      {
        $comment:
          "Generated by .github/scripts/sync-trigger-slugs.ts --refresh — do not hand-edit.",
        generatedFrom: "cargo-ai connection integration list",
        count: integrations.length,
        creditsBasedCount: integrations.filter((i) => i.credits).length,
        integrations,
      },
      null,
      2,
    ) + "\n",
  );
  console.log(`Wrote ${catalogPath} (${integrations.length} integrations)`);
}

function loadCatalog(): Integration[] {
  if (!existsSync(catalogPath)) {
    throw new Error(
      `${catalogPath} is missing — regenerate it with: node .github/scripts/sync-trigger-slugs.ts --refresh`,
    );
  }
  // Filtered on read as well as on refresh: a hand-edited catalog is still a
  // catalog, and this list must hold however the file got there.
  return (JSON.parse(readFileSync(catalogPath, "utf8")) as { integrations: Integration[] })
    .integrations;
}

function gtmProviderSlugs(): string[] {
  const dir = join(repoRoot, "cargo-gtm/provider-playbooks");
  return readdirSync(dir)
    .filter((f) => f.endsWith(".md"))
    .map((f) => f.replace(/\.md$/, ""))
    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
}

function opsIntegrationSlugs(catalog: Integration[]): string[] {
  const slugs = catalog
    .filter((i) => OPS_CATEGORIES.has(i.category))
    .map((i) => i.slug);
  for (const extra of OPS_EXTRAS) {
    if (catalog.some((i) => i.slug === extra)) slugs.push(extra);
  }
  return [...new Set(slugs)].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
}

/** Replace `<label>: a, b, c.` inside a SKILL.md description line. */
function rewriteDescription(
  skillDir: string,
  label: string,
  slugs: string[],
  suffix = "",
): { path: string; before: string; after: string } {
  const path = join(repoRoot, skillDir, "SKILL.md");
  const before = readFileSync(path, "utf8");
  const list = slugs.join(", ") + suffix;
  const pattern = new RegExp(`(^description:.*?${label}: )[^.]*\\.`, "m");
  if (!pattern.test(before)) {
    throw new Error(
      `${skillDir}/SKILL.md description has no \`${label}: … .\` sentence for the generator to fill.`,
    );
  }
  const after = before.replace(pattern, `$1${list}.`);
  return { path, before, after };
}

function main(): void {
  if (process.argv.includes("--refresh")) {
    refreshCatalog();
  }

  const catalog = loadCatalog();
  const ops = opsIntegrationSlugs(catalog);
  const edits = [
    rewriteDescription("cargo-gtm", "Providers", gtmProviderSlugs()),
    rewriteDescription(
      "cargo-connection",
      "Integrations",
      ops,
      `, and ${catalog.length - ops.length} more`,
    ),
  ];

  const stale = edits.filter((e) => e.before !== e.after);
  if (process.argv.includes("--check")) {
    if (stale.length) {
      for (const e of stale) console.error(`stale slug list: ${e.path}`);
      console.error(
        "Regenerate with: node .github/scripts/sync-trigger-slugs.ts",
      );
      process.exit(1);
    }
    console.log(
      `Trigger slug lists are up to date (${gtmProviderSlugs().length} providers, ${ops.length} integrations).`,
    );
    return;
  }

  for (const e of stale) {
    writeFileSync(e.path, e.after);
    console.log(`Updated ${e.path}`);
  }
  console.log(
    `${gtmProviderSlugs().length} GTM providers, ${ops.length} named integrations (of ${catalog.length} in the catalog).`,
  );
}

main();