ci: Add format-code-sample-tabs to CI format workflow

Adds a codegen script that auto-fixes code sample tab order and titles
in guide and brand-guide markdown files. Runs as part of the Format CI
workflow, which auto-commits fixes on non-main branches.

The canonical tab order and title mapping are defined in a shared module
(codegen/lib/code-sample-tab-order.ts), imported by both the API
reference codegen and the tab formatter — single source of truth.

The script:
- Reorders tabs to match API reference canonical order
  (JavaScript → cURL → Python → Ruby → PHP → C# → Java → Go → Seam CLI)
- Normalizes tab titles ("cURL (bash)" → "cURL", "Javascript" → "JavaScript")
- Ensures GitBook tab syncing works across all code blocks on a page

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

.github/workflows/format.yml

@@ -29,6 +29,8 @@ jobs:
           passphrase: ${{ secrets.GPG_PASSPHRASE }}
       - name: Setup
         uses: ./.github/actions/setup
+      - name: Format code sample tabs
+        run: npm run format-code-sample-tabs
       - name: Format
         run: npm run format
       - name: Commit

codegen/format-code-sample-tabs.ts

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { globSync } from 'glob'
+
+import { tabTitleFixes, tabTitleOrder } from './lib/code-sample-tab-order.js'
+
+const tabsBlockPattern = /\{%\s*tabs\s*%\}[\s\S]*?\{%\s*endtabs\s*%\}/g
+
+const tabPattern =
+  /\{%\s*tab\s+title="([^"]+)"\s*%\}([\s\S]*?)\{%\s*endtab\s*%\}/g
+
+function canonicalIndex(title: string): number {
+  const normalized = tabTitleFixes[title] ?? title
+  return tabTitleOrder.get(normalized) ?? tabTitleOrder.size + 1
+}
+
+function formatTabsBlock(block: string): { result: string; changed: boolean } {
+  const tabs: Array<{ title: string; content: string }> = []
+  for (const match of block.matchAll(tabPattern)) {
+    tabs.push({ title: match[1] ?? '', content: match[2] ?? '' })
+  }
+
+  if (tabs.length < 2) return { result: block, changed: false }
+
+  const originalTitles = tabs.map((t) => t.title)
+  const sorted = [...tabs].sort(
+    (a, b) => canonicalIndex(a.title) - canonicalIndex(b.title),
+  )
+  const sortedTitles = sorted.map((t) => t.title)
+  const needsRename = originalTitles.some((t) => t in tabTitleFixes)
+  const needsReorder = originalTitles.some((t, i) => t !== sortedTitles[i])
+
+  if (!needsReorder && !needsRename) return { result: block, changed: false }
+
+  const lines = ['{% tabs %}']
+  for (const tab of sorted) {
+    const title = tabTitleFixes[tab.title] ?? tab.title
+    lines.push(`{% tab title="${title}" %}`)
+    lines.push(tab.content.trimEnd())
+    lines.push('{% endtab %}')
+    lines.push('')
+  }
+  while (lines.at(-1) === '') lines.pop()
+  lines.push('{% endtabs %}')
+
+  return { result: lines.join('\n'), changed: true }
+}
+
+const dirs = ['docs/guides', 'docs/brand-guides']
+const files = dirs.flatMap((dir) => globSync(join(dir, '**/*.md')))
+
+let totalChanged = 0
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8')
+  let changed = false
+
+  const updated = content.replace(tabsBlockPattern, (block) => {
+    const { result, changed: blockChanged } = formatTabsBlock(block)
+    if (blockChanged) changed = true
+    return result
+  })
+
+  if (changed) {
+    writeFileSync(file, updated)
+    totalChanged++
+  }
+}
+
+if (totalChanged > 0) {
+  // eslint-disable-next-line no-console
+  console.log(`Formatted tabs in ${String(totalChanged)} file(s).`)
+}

codegen/lib/code-sample-tab-order.ts

@@ -0,0 +1,47 @@
+import type { SdkName } from '@seamapi/blueprint'
+
+/**
+ * Canonical tab order for code samples across all documentation.
+ * Used by the API reference codegen (api-endpoint.ts) and the
+ * format-code-sample-tabs script to keep guide tabs in sync.
+ */
+export const supportedSdkOrder: SdkName[] = [
+  'javascript',
+  'curl',
+  'python',
+  'ruby',
+  'php',
+  'csharp',
+  'java',
+  'go',
+  'seam_cli',
+]
+
+/**
+ * Maps SdkName values to their canonical display titles as used in
+ * GitBook tab headers. Sourced from @seamapi/blueprint CodeSample titles.
+ */
+export const sdkDisplayTitle: Record<SdkName, string> = {
+  javascript: 'JavaScript',
+  curl: 'cURL',
+  python: 'Python',
+  ruby: 'Ruby',
+  php: 'PHP',
+  csharp: 'C#',
+  java: 'Java',
+  go: 'Go',
+  seam_cli: 'Seam CLI',
+}
+
+/** Reverse lookup: display title → canonical index. */
+export const tabTitleOrder: Map<string, number> = new Map(
+  supportedSdkOrder.map((sdk, i) => [sdkDisplayTitle[sdk], i]),
+)
+
+/** Known non-canonical title variants that should be normalized. */
+export const tabTitleFixes: Record<string, string> = {
+  'cURL (bash)': 'cURL',
+  Bash: 'cURL',
+  Javascript: 'JavaScript',
+  javascript: 'JavaScript',
+}

codegen/lib/layout/api-endpoint.ts

@@ -13,6 +13,7 @@ import type {
 } from '@seamapi/blueprint'
 import { capitalCase } from 'change-case'
 
+import { supportedSdkOrder } from '../code-sample-tab-order.js'
 import type { PathMetadata } from '../path-metadata.js'
 import {
   type ApiRouteResource,
@@ -23,14 +24,18 @@ import {
   resourceSampleFilter,
 } from './api-route.js'
 
-const supportedSdks: SdkName[] = [
+const apiReferenceSdks = new Set<SdkName>([
   'javascript',
   'curl',
   'python',
   'ruby',
   'php',
   'seam_cli',
-]
+])
+
+const supportedSdks = supportedSdkOrder.filter((sdk) =>
+  apiReferenceSdks.has(sdk),
+)
 
 export interface ApiEndpointLayoutContext {
   description: string

package.json

@@ -24,7 +24,8 @@
     "lint": "eslint .",
     "postlint": "prettier --check --ignore-path .prettierignore .",
     "format": "prettier --write --ignore-path .prettierignore .",
-    "preformat": "eslint --fix ."
+    "preformat": "eslint --fix .",
+    "format-code-sample-tabs": "tsx codegen/format-code-sample-tabs.ts"
   },
   "engines": {
     "node": ">=22.11.0",