@devries-cameron20 / composio-1 / commits / 03e4684e4
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(kb): publish KB guides approved in the support portal (#5099)

## Why The KB on docs.composio.dev/kb only changes when someone edits `docs/kb` by hand. The support portal now has Front Desk draft KB changes (new guides, rewrites, retirements) when the team announces a feature or removal, or when an issue group gets crowded or fixed. People review and edit each draft on a preview page in the portal. This PR is the publishing half: approving a draft there turns it into a docs PR here. Portal side: [Knowledge base: Front Desk drafts KB changes, reviewed in the portal](https://github.com/ComposioHQ/support-portal/pull/237). ## What - **`.github/workflows/docs-kb-publish.yml`**: runs on a `kb-guide-approved` repository dispatch. It applies the guide, runs `generate:kb` and `check:kb`, opens a PR on `next` from `docs/kb-front-desk-<draft id>` with the Release Bot app token (the same one `docs-update-kb.yml` uses), and turns on auto-merge (squash). Payload values only reach the shell through env vars, and `draft_id` must be a number. - **`docs/scripts/publish-kb-guide.ts`**: applies one guide request to `kb/manifest.json`, `kb/articles/<slug>.md` and, for a new guide, `kb/source/<area>/<name>/public.md` (each `##` section becomes a source, which is what the catalog requires). It sets `updatedAt`, `lastVerifiedAt` and `reviewAfter` (+90 days), and validates with `buildKbCatalog` before writing anything. `retire` sets `state: retired`. The semantic index is left to the existing 6-hourly `docs-update-kb` refresh, as `docs-tests` already allows a stale one. ## Needs - The portal needs a token that can send the dispatch: contents write on this repo (`KB_GITHUB_TOKEN` there). - If rulesets require a code-owner review on `docs/`, these PRs wait for one before auto-merge goes through. ## Testing Ran locally against `next`: creating a guide, updating `dashboard-org-members` and retiring a guide, each followed by `bun run generate:kb` and `bun run check:kb`, all passed. A bad slug and an unknown area are rejected before anything is written. The workflow itself has not run yet; it needs a real dispatch. No UI change in this repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Search: turn on hybrid retrieval Not code, deploy config: `KB_HYBRID_SEARCH_ENABLED=true` and an `OPENAI_API_KEY` on the docs Vercel project turn on the semantic half of `/api/knowledge-search`. In production it currently answers in keyword mode only, so a question like "why can't I use the perplexity tool" misses guides that describe the problem in other words. The dashboard's new-ticket suggestions and the portal's drafting both call this endpoint. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: jkomyno <alberto@composio.dev>

akram-composio committed Oct 27, 2026 at 01:31 UTC 03e4684e4779c4740c22dd10de95ff6e8206971d
9 files changed +787 -10
.github/workflows/docs-kb-publish.yml new
+134
@@ -0,0 +1,134 @@
1 +name: Docs - Publish KB Guide
2 +
3 +# The support portal sends this when someone approves a KB guide that Front Desk drafted: a new guide, a
4 +# rewrite or a retirement. It becomes one PR on next that merges itself once checks pass.
5 +on:
6 + repository_dispatch:
7 + types: [kb-guide-approved]
8 +
9 +permissions:
10 + contents: read
11 +
12 +concurrency:
13 + # Shared with docs-update-kb: both workflows replace the KB snapshot.
14 + group: docs-kb-publication
15 + cancel-in-progress: false
16 + queue: max
17 +
18 +jobs:
19 + publish:
20 + runs-on: ubuntu-latest
21 + permissions:
22 + contents: read
23 + pull-requests: read
24 + defaults:
25 + run:
26 + shell: bash
27 + working-directory: ./docs
28 +
29 + steps:
30 + - name: Check request
31 + env:
32 + DRAFT_ID: ${{ github.event.client_payload.draft_id }}
33 + run: |
34 + if ! [[ "$DRAFT_ID" =~ ^[0-9]+$ ]]; then
35 + echo "draft_id must be a number" >&2
36 + exit 1
37 + fi
38 + working-directory: .
39 +
40 + # A finished workflow may still have a PR waiting on checks or review.
41 + # Wait before checkout so each approval starts from the preceding merge.
42 + - name: Wait for earlier KB publications
43 + timeout-minutes: 31
44 + working-directory: .
45 + env:
46 + GH_TOKEN: ${{ github.token }}
47 + GH_REPO: ${{ github.repository }}
48 + PUBLISH_BRANCH: docs/kb-front-desk-${{ github.event.client_payload.draft_id }}
49 + run: |
50 + for ((attempt = 1; attempt <= 60; attempt++)); do
51 + pending=$(gh api --paginate "repos/$GH_REPO/pulls?state=open&base=next&per_page=100" \
52 + --jq '.[] | select(.head.repo.full_name == env.GH_REPO) | select(.head.ref == "docs/auto-update-kb" or (.head.ref | startswith("docs/kb-front-desk-"))) | select(.head.ref != env.PUBLISH_BRANCH) | .html_url')
53 + if [ -z "$pending" ]; then
54 + exit 0
55 + fi
56 + echo "Waiting for earlier KB publications to merge or close:"
57 + echo "$pending"
58 + if [ "$attempt" -lt 60 ]; then
59 + sleep 30
60 + fi
61 + done
62 + echo "Earlier KB publications are still open. Merge or close them, then rerun this workflow." >&2
63 + exit 1
64 +
65 + - name: Checkout docs repository
66 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
67 + with:
68 + ref: next
69 + persist-credentials: false
70 +
71 + - name: Setup Node.js, pnpm, Bun
72 + uses: ./.github/actions/setup-node-pnpm-bun
73 +
74 + - name: Install dependencies
75 + run: bun install --frozen-lockfile --ignore-scripts
76 +
77 + - name: Apply the approved guide
78 + env:
79 + GUIDE: ${{ toJSON(github.event.client_payload.guide) }}
80 + run: |
81 + printf '%s' "$GUIDE" > "$RUNNER_TEMP/kb-guide.json"
82 + bun scripts/publish-kb-guide.ts "$RUNNER_TEMP/kb-guide.json"
83 +
84 + - name: Regenerate KB pages
85 + env:
86 + GUIDE_SLUG: ${{ github.event.client_payload.guide.slug }}
87 + run: |
88 + bun run generate:kb
89 + bun run check:kb
90 + bun run verify:kb --json | tee "$RUNNER_TEMP/kb-verify.json"
91 + if ! jq -e '[.findings[] | select(.kind == "unedited-support-prose" and .guideSlug == env.GUIDE_SLUG)] | length == 0' "$RUNNER_TEMP/kb-verify.json"; then
92 + echo "KB publication contains support-facing prose. Rewrite it for public readers before approving again." >&2
93 + exit 1
94 + fi
95 +
96 + - name: Generate composio PR token
97 + id: write-token
98 + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
99 + with:
100 + client-id: ${{ vars.RELEASE_BOT_CLIENT_ID }}
101 + private-key: ${{ secrets.RELEASE_BOT_APP_PRIVATE_KEY }}
102 + owner: ComposioHQ
103 + repositories: composio
104 + permission-contents: write
105 + permission-pull-requests: write
106 +
107 + - name: Create pull request
108 + id: pr
109 + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
110 + with:
111 + token: ${{ steps.write-token.outputs.token }}
112 + commit-message: 'docs(kb): ${{ github.event.client_payload.summary }}'
113 + title: 'docs(kb): ${{ github.event.client_payload.summary }}'
114 + body: |
115 + KB guide approved in the support portal by ${{ github.event.client_payload.approved_by }}.
116 +
117 + - Guide: `${{ github.event.client_payload.guide.slug }}` (${{ github.event.client_payload.guide.action }})
118 + - Draft: ${{ github.event.client_payload.portal_url }}
119 +
120 + Front Desk drafted it; the approver reviewed and edited it in the portal. This PR merges itself
121 + once checks pass.
122 + branch: docs/kb-front-desk-${{ github.event.client_payload.draft_id }}
123 + base: next
124 + add-paths: |
125 + docs/kb/
126 + docs/content/kb/
127 +
128 + - name: Merge once checks pass
129 + if: steps.pr.outputs.pull-request-number
130 + env:
131 + GH_TOKEN: ${{ steps.write-token.outputs.token }}
132 + GH_REPO: ${{ github.repository }}
133 + PR: ${{ steps.pr.outputs.pull-request-number }}
134 + run: gh pr merge "$PR" --auto --squash
.github/workflows/docs-update-kb.yml
+40 -2
@@ -13,15 +13,19 @@ permissions:
13 contents: read
14
15 concurrency:
16 - group: docs-support-knowledge-refresh
17 - cancel-in-progress: true
16 + # Shared with portal publications so neither snapshots an outdated KB.
17 + group: docs-kb-publication
18 + cancel-in-progress: false
19 + queue: max
20
21 jobs:
22 refresh:
23 runs-on: ubuntu-latest
24 permissions:
25 contents: read
26 + pull-requests: read
27 outputs:
28 + docs_base_sha: ${{ steps.docs-base.outputs.sha }}
29 changed: ${{ steps.rebuild.outputs.changed }}
30 upstream_changed: ${{ steps.source.outputs.upstream_changed }}
31 commit: ${{ steps.source.outputs.commit }}
@@ -30,6 +34,31 @@ jobs:
34 working-directory: ./docs
35
36 steps:
37 + # A finished workflow may still have a PR waiting on checks or review.
38 + # Wait before checkout so each approval starts from the preceding merge.
39 + - name: Wait for earlier KB publications
40 + timeout-minutes: 31
41 + working-directory: .
42 + env:
43 + GH_TOKEN: ${{ github.token }}
44 + GH_REPO: ${{ github.repository }}
45 + PUBLISH_BRANCH: docs/auto-update-kb
46 + run: |
47 + for ((attempt = 1; attempt <= 60; attempt++)); do
48 + pending=$(gh api --paginate "repos/$GH_REPO/pulls?state=open&base=next&per_page=100" \
49 + --jq '.[] | select(.head.repo.full_name == env.GH_REPO) | select(.head.ref == "docs/auto-update-kb" or (.head.ref | startswith("docs/kb-front-desk-"))) | select(.head.ref != env.PUBLISH_BRANCH) | .html_url')
50 + if [ -z "$pending" ]; then
51 + exit 0
52 + fi
53 + echo "Waiting for earlier KB publications to merge or close:"
54 + echo "$pending"
55 + if [ "$attempt" -lt 60 ]; then
56 + sleep 30
57 + fi
58 + done
59 + echo "Earlier KB publications are still open. Merge or close them, then rerun this workflow." >&2
60 + exit 1
61 +
62 # If the app has no installation on support-knowledge, this fails
63 # with 404. Degrade to an upstream-sync skip instead of killing the
64 # whole job: the stale-artifact rebuild below needs only this repo.
@@ -47,8 +76,15 @@ jobs:
76 - name: Checkout docs repository
77 uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
78 with:
79 + ref: next
80 persist-credentials: false
81
82 + - name: Record docs base
83 + id: docs-base
84 + run: |
85 + docs_base_sha=$(git rev-parse HEAD)
86 + echo "sha=$docs_base_sha" >> "$GITHUB_OUTPUT"
87 +
88 - name: Checkout support knowledge
89 if: steps.upstream-token.outcome == 'success'
90 uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -151,6 +187,8 @@ jobs:
187 - name: Checkout docs repository
188 uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
189 with:
190 + # Apply the artifacts relative to the exact tree that produced them.
191 + ref: ${{ needs.refresh.outputs.docs_base_sha }}
192 persist-credentials: false
193
194 - name: Download verified KB artifacts
docs/lib/kb/support-knowledge.ts
+29 -2
@@ -447,7 +447,12 @@ export function buildSupportKnowledgeSnapshot(input: {
447 const sourceFiles = new Map<string, string>();
448 const articleFiles = new Map<string, string>();
449 const previousAliases = previousAliasesBySource(publicDocuments, input.previousManifest);
450 - const guides = publicDocuments.map(document => {
450 + const portalGuides = input.previousManifest?.guides
451 + .filter(guide => guide.managedBy === 'support-portal') ?? [];
452 + const portalSlugs = new Set(portalGuides.map(guide => guide.slug));
453 + const guides = publicDocuments.filter(document => !portalSlugs.has(
454 + slugify(document.relativePath.replace(/\/public\.md$/, '')),
455 + )).map(document => {
456 const previousGuide = previousGuideForSource(document, input.previousManifest);
457 const source = normalizedSource(document);
458 const sourceIsUnchanged = input.previousSourceFiles?.get(document.relativePath) === source;
@@ -476,6 +481,28 @@ export function buildSupportKnowledgeSnapshot(input: {
481 return guide;
482 });
483
484 + // An approval takes ownership of the complete guide, including its source snapshot.
485 + // Missing bytes are an error rather than permission to discard an approved edit.
486 + for (const guide of portalGuides) {
487 + for (const reference of guide.sources) {
488 + const source = input.previousSourceFiles?.get(reference.sourcePath);
489 + if (source === undefined) throw new Error(`Missing portal source: ${reference.sourcePath}`);
490 + sourceFiles.set(reference.sourcePath, source);
491 + }
492 + if (guide.articlePath) {
493 + const article = input.previousArticleFiles?.get(guide.articlePath);
494 + if (article === undefined) throw new Error(`Missing portal article: ${guide.articlePath}`);
495 + articleFiles.set(guide.articlePath, article);
496 + }
497 + guides.push(guide);
498 + }
499 + const topics = topicDefinitions(publicDocuments, input.previousManifest);
500 + const topicSlugs = new Set(topics.map(topic => topic.slug));
501 + const portalTopics = new Set(portalGuides.flatMap(guide => guide.topics));
502 + for (const topic of input.previousManifest?.topics ?? []) {
503 + if (portalTopics.has(topic.slug) && !topicSlugs.has(topic.slug)) topics.push(topic);
504 + }
505 +
506 return {
507 manifest: {
508 schemaVersion: 2,
@@ -485,7 +512,7 @@ export function buildSupportKnowledgeSnapshot(input: {
512 capturedAt: input.now.toISOString().slice(0, 10),
513 contentHash: sourceContentHash(sourceFiles),
514 },
488 - topics: topicDefinitions(publicDocuments, input.previousManifest),
515 + topics,
516 guides,
517 },
518 sourceFiles,
docs/lib/kb/types.ts
+2
@@ -29,6 +29,8 @@ export interface KbSourceReference {
29 }
30
31 export interface KbGuideDefinition {
32 + /** Portal approvals own this guide across upstream refreshes. */
33 + managedBy?: 'support-portal';
34 slug: string;
35 title: string;
36 description: string;
docs/scripts/publish-kb-guide.ts new
+175
@@ -0,0 +1,175 @@
1 +/**
2 + * Publish one KB guide approved in the support portal: create it, rewrite it, or retire it.
3 + *
4 + * Reads a JSON request from the path given as the first argument (the docs-kb-publish workflow writes
5 + * it from the repository_dispatch payload), updates kb/manifest.json, the guide's article and, for a new
6 + * guide, its public source page, and validates the result with the same catalog checks the site uses.
7 + * Run `bun run generate:kb` afterwards.
8 + */
9 +import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
10 +import { dirname, join, resolve } from 'node:path';
11 +import { buildKbCatalog } from '@/lib/kb/catalog';
12 +import { createKbArticleReader, createKbSourceReader } from '@/lib/kb/repository';
13 +import type { KbGuideDefinition } from '@/lib/kb/types';
14 +import { z } from 'zod';
15 +
16 +const slugSchema = z.string().min(1).max(200).regex(/^[a-z0-9-]+$/)
17 + .refine(value => value.split('-').every(Boolean), 'Invalid guide slug');
18 +const requestSchema = z.object({
19 + action: z.enum(['upsert', 'retire']),
20 + slug: slugSchema,
21 + area: z.enum(['consumer', 'dashboard', 'faqs', 'mcp', 'platform', 'sdk', 'toolkits']).optional(),
22 + title: z.string().optional(),
23 + description: z.string().optional(),
24 + body: z.string().optional(),
25 + topics: z.array(z.string()).optional(),
26 + tags: z.array(z.string()).optional(),
27 +});
28 +
29 +const manifestSchema = z.object({
30 + schemaVersion: z.literal(2),
31 + source: z.object({
32 + repository: z.string(), commit: z.string(), capturedAt: z.string(), contentHash: z.string(),
33 + }),
34 + topics: z.array(z.object({
35 + slug: z.string(), title: z.string(), description: z.string(), featuredRank: z.number().nullable(),
36 + })),
37 + guides: z.array(z.object({
38 + slug: slugSchema,
39 + title: z.string(),
40 + description: z.string(),
41 + articlePath: z.string().optional(),
42 + sources: z.array(z.object({ sourcePath: z.string(), sourceHeading: z.string().nullable() })),
43 + topics: z.array(z.string()),
44 + tags: z.array(z.string()),
45 + aliases: z.array(z.string()),
46 + relatedGuides: z.array(z.string()),
47 + externalResources: z.array(z.string()),
48 + updatedAt: z.string(),
49 + lastVerifiedAt: z.string().nullable(),
50 + reviewAfter: z.string().nullable(),
51 + freshness: z.enum(['evergreen', 'time-sensitive']),
52 + state: z.enum(['published', 'needs-review', 'retired']),
53 + featured: z.boolean(),
54 + verifyIgnoreToolSlugs: z.array(z.string()).optional(),
55 + managedBy: z.literal('support-portal').optional(),
56 + })),
57 +});
58 +
59 +const REVIEW_DAYS = 90;
60 +
61 +export function publishKbGuide(input: unknown, docsRoot = process.cwd(), now = new Date()): void {
62 + const request = requestSchema.parse(input);
63 + const root = resolve(docsRoot, 'kb');
64 + const manifestPath = join(root, 'manifest.json');
65 + const manifest = manifestSchema.parse(JSON.parse(readFileSync(manifestPath, 'utf8')));
66 + const today = now.toISOString().slice(0, 10);
67 + const reviewAfter = new Date(now.valueOf() + REVIEW_DAYS * 86_400_000).toISOString().slice(0, 10);
68 + const existing = manifest.guides.find(guide => guide.slug === request.slug);
69 + const writes: [string, string][] = [];
70 +
71 + function text(value: string | undefined, name: string): string {
72 + const trimmed = (value ?? '').trim();
73 + if (!trimmed) throw new Error(`${name} is required`);
74 + return trimmed;
75 + }
76 +
77 + function words(values: string[] | undefined): string[] {
78 + return [...new Set((values ?? []).map(value => value.trim().toLowerCase()).filter(Boolean))].sort();
79 + }
80 +
81 + if (request.action === 'retire') {
82 + if (!existing) throw new Error(`No guide ${request.slug} to retire`);
83 + existing.state = 'retired';
84 + existing.updatedAt = today;
85 + existing.managedBy = 'support-portal';
86 + } else if (request.action === 'upsert') {
87 + const body = text(request.body, 'body');
88 + if (body.startsWith('---')) throw new Error('The article must not contain frontmatter');
89 + if (/^#\s/m.test(body.split('\n')[0] ?? '')) throw new Error('The article must not start with a top-level heading');
90 + const title = existing && !request.title ? existing.title : text(request.title, 'title');
91 + const description = existing && !request.description ? existing.description : text(request.description, 'description');
92 + const topics = request.topics !== undefined ? words(request.topics) : existing?.topics ?? [];
93 + const tags = request.tags !== undefined ? words(request.tags) : existing?.tags ?? [];
94 + if (!topics.length) throw new Error('At least one topic is required');
95 + let guide: KbGuideDefinition;
96 + if (existing) {
97 + guide = existing;
98 + Object.assign(guide, { title, description, topics, tags });
99 + } else {
100 + const area = text(request.area, 'area');
101 + if (!request.slug.startsWith(`${area}-`)) throw new Error(`A ${area} guide's slug starts with ${area}-`);
102 + const sourcePath = `${area}/${request.slug.slice(area.length + 1)}/public.md`;
103 + if (existsSync(join(root, 'source', sourcePath))) {
104 + throw new Error(`${sourcePath} already exists`);
105 + }
106 + writes.push([join(root, 'source', sourcePath), [
107 + '---',
108 + 'type: "guide"',
109 + `title: ${JSON.stringify(title)}`,
110 + `description: ${JSON.stringify(description)}`,
111 + `category: ${JSON.stringify(topics[0])}`,
112 + 'visibility: "public"',
113 + `timestamp: ${JSON.stringify(`${today}T00:00:00Z`)}`,
114 + 'tags:',
115 + ...(tags.length ? tags : ['support-portal']).map(tag => ` - ${JSON.stringify(tag)}`),
116 + '---',
117 + `# ${title}`,
118 + '',
119 + body,
120 + '',
121 + ].join('\n')]);
122 + const headings = body.split('\n').flatMap(line => {
123 + const heading = line.match(/^##[ \t]+(.+)$/)?.[1]?.trim();
124 + return heading ? [heading] : [];
125 + });
126 + guide = {
127 + slug: request.slug,
128 + title,
129 + description,
130 + articlePath: `${request.slug}.md`,
131 + sources: (headings.length ? headings : [null])
132 + .map(sourceHeading => ({ sourcePath, sourceHeading })),
133 + topics,
134 + tags,
135 + aliases: [],
136 + relatedGuides: [],
137 + externalResources: [],
138 + updatedAt: today,
139 + lastVerifiedAt: today,
140 + reviewAfter,
141 + freshness: 'evergreen',
142 + state: 'published',
143 + featured: false,
144 + };
145 + manifest.guides.push(guide);
146 + }
147 + guide.managedBy = 'support-portal';
148 + guide.articlePath = `${request.slug}.md`;
149 + Object.assign(guide, { updatedAt: today, lastVerifiedAt: today, reviewAfter, state: 'published' });
150 + writes.push([join(root, 'articles', guide.articlePath), `${body}\n`]);
151 + }
152 +
153 + const pending = new Map(writes);
154 + const readStaged = (base: string, read: (path: string) => string) => (path: string) =>
155 + pending.get(join(root, base, path)) ?? read(path);
156 + buildKbCatalog(
157 + manifest,
158 + readStaged('source', createKbSourceReader(join(root, 'source'))),
159 + now,
160 + readStaged('articles', createKbArticleReader(join(root, 'articles'))),
161 + );
162 +
163 + for (const [path, content] of writes) {
164 + mkdirSync(dirname(path), { recursive: true });
165 + writeFileSync(path, content);
166 + }
167 + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
168 + console.log(`${request.action === 'retire' ? 'Retired' : existing ? 'Updated' : 'Created'} ${request.slug}.`);
169 +}
170 +
171 +if (import.meta.main) {
172 + const requestPath = process.argv[2];
173 + if (!requestPath) throw new Error('Usage: bun scripts/publish-kb-guide.ts <request.json>');
174 + publishKbGuide(JSON.parse(readFileSync(requestPath, 'utf8')));
175 +}
docs/tests/static/kb-import.test.ts
+72
@@ -10,6 +10,9 @@ import {
10 writeSupportKnowledgeSnapshot,
11 } from '@/lib/kb/support-knowledge';
12 import type { KbManifest } from '@/lib/kb/types';
13 +import { buildKbCatalog } from '@/lib/kb/catalog';
14 +import { createKbArticleReader, createKbSourceReader } from '@/lib/kb/repository';
15 +import { publishKbGuide } from '../../scripts/publish-kb-guide';
16
17 const publicDocument = `---
18 type: "reference"
@@ -109,6 +112,75 @@ function previousManifest(): KbManifest {
112 }
113
114 describe('support-knowledge snapshot import', () => {
115 + test('preserves portal creations, rewrites and retirements through repeated upstream refreshes', () => {
116 + const sourceRoot = mkdtempSync(join(tmpdir(), 'support-knowledge-portal-'));
117 + const docsRoot = mkdtempSync(join(tmpdir(), 'kb-publish-'));
118 + const targetRoot = join(docsRoot, 'kb');
119 + const now = new Date('2026-08-18T00:00:00Z');
120 + const validate = (stagedRoot: string) => buildKbCatalog(
121 + JSON.parse(readFileSync(join(stagedRoot, 'manifest.json'), 'utf8')),
122 + createKbSourceReader(join(stagedRoot, 'source')),
123 + now,
124 + createKbArticleReader(join(stagedRoot, 'articles')),
125 + );
126 + try {
127 + writeDocument(sourceRoot, 'toolkits/github/public.md', publicDocument);
128 + writeDocument(sourceRoot, 'toolkits/slack/public.md', publicDocument.replaceAll('GitHub', 'Slack'));
129 + writeDocument(sourceRoot, 'toolkits/gitlab/public.md', publicDocument.replaceAll('GitHub', 'GitLab'));
130 + const initial = buildSupportKnowledgeSnapshot({ sourceRoot, sourceCommit: 'initial', now });
131 + writeSupportKnowledgeSnapshot({ snapshot: initial, targetRoot, validate });
132 +
133 + publishKbGuide({
134 + action: 'upsert', slug: 'toolkits-github', title: 'Approved GitHub title',
135 + description: 'Approved description.', topics: ['authentication'], tags: [],
136 + body: '## Approved answer\n\nUse the approved instructions.',
137 + }, docsRoot, now);
138 + publishKbGuide({ action: 'retire', slug: 'toolkits-slack' }, docsRoot, now);
139 + publishKbGuide({
140 + action: 'upsert', slug: 'sdk-portal-guide', area: 'sdk', title: 'Portal guide',
141 + description: 'A guide created in the portal.', topics: ['authentication'], tags: [],
142 + body: '## Setup\n\nFollow these setup instructions.',
143 + }, docsRoot, now);
144 + const approved = validate(targetRoot);
145 +
146 + // Upstream changes metadata and headings, removes a retired source, and drops a topic.
147 + writeDocument(sourceRoot, 'toolkits/github/public.md', publicDocument
148 + .replaceAll('authentication', 'errors-and-troubleshooting')
149 + .replaceAll('Tokens are redacted', 'Changed upstream heading'));
150 + rmSync(join(sourceRoot, 'toolkits/slack'), { recursive: true });
151 + writeDocument(sourceRoot, 'toolkits/gitlab/public.md', publicDocument
152 + .replaceAll('GitHub', 'Updated GitLab')
153 + .replaceAll('authentication', 'errors-and-troubleshooting'));
154 +
155 + for (const sourceCommit of ['refresh-one', 'refresh-two']) {
156 + const previous = validate(targetRoot);
157 + const snapshot = buildSupportKnowledgeSnapshot({
158 + sourceRoot, sourceCommit, previousManifest: previous.manifest,
159 + previousSourceFiles: new Map(previous.guides.flatMap(guide => guide.sources.map(source => [
160 + source.sourcePath, readFileSync(join(targetRoot, 'source', source.sourcePath), 'utf8'),
161 + ]))),
162 + previousArticleFiles: new Map(previous.guides.map(guide => [
163 + guide.articlePath!, readFileSync(join(targetRoot, 'articles', guide.articlePath!), 'utf8'),
164 + ])),
165 + now,
166 + });
167 + writeSupportKnowledgeSnapshot({ snapshot, targetRoot, validate });
168 + const refreshed = validate(targetRoot);
169 + for (const slug of ['toolkits-github', 'toolkits-slack', 'sdk-portal-guide']) {
170 + expect(refreshed.guides.find(guide => guide.slug === slug))
171 + .toEqual(approved.guides.find(guide => guide.slug === slug));
172 + }
173 + expect(refreshed.guides.find(guide => guide.slug === 'toolkits-gitlab')?.title)
174 + .toBe('Updated GitLab');
175 + expect(refreshed.topics.some(topic => topic.slug === 'authentication')).toBe(true);
176 + expect(refreshed.manifest.source.commit).toBe(sourceCommit);
177 + }
178 + } finally {
179 + rmSync(sourceRoot, { recursive: true, force: true });
180 + rmSync(docsRoot, { recursive: true, force: true });
181 + }
182 + });
183 +
184 test('keeps a retired guide unpublished when its public source is refreshed', () => {
185 const sourceRoot = mkdtempSync(join(tmpdir(), 'support-knowledge-retired-'));
186 try {
docs/tests/static/kb-publish-workflow.test.ts new
+216
@@ -0,0 +1,216 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { spawnSync } from 'node:child_process';
3 +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
4 +import { tmpdir } from 'node:os';
5 +import { join, resolve } from 'node:path';
6 +import { z } from 'zod';
7 +
8 +const workflowSchema = z.object({
9 + jobs: z.record(z.string(), z.object({
10 + defaults: z.object({ run: z.object({ shell: z.string().optional() }) }).optional(),
11 + steps: z.array(z.object({ name: z.string(), run: z.string().optional(), shell: z.string().optional() })),
12 + })),
13 +});
14 +const workflows = {
15 + publish: workflowSchema.parse(Bun.YAML.parse(readFileSync(
16 + resolve(process.cwd(), '..', '.github/workflows/docs-kb-publish.yml'), 'utf8',
17 + ))),
18 + refresh: workflowSchema.parse(Bun.YAML.parse(readFileSync(
19 + resolve(process.cwd(), '..', '.github/workflows/docs-update-kb.yml'), 'utf8',
20 + ))),
21 +};
22 +
23 +function runStep(
24 + name: string, root: string, env: Record<string, string> = {}, job: 'publish' | 'refresh' = 'publish',
25 +) {
26 + const definition = workflows[job].jobs[job]!;
27 + const step = definition.steps.find(step => step.name === name);
28 + const script = step?.run;
29 + if (!script) throw new Error(`Missing workflow step: ${name}`);
30 + // Match the Actions runner: implicit bash omits pipefail; explicit bash enables it.
31 + const shell = step?.shell ?? definition.defaults?.run.shell;
32 + const shellFlags = shell === 'bash' ? ['--noprofile', '--norc', '-e', '-o', 'pipefail'] : ['-e'];
33 + return spawnSync('bash', [...shellFlags, '-c', script], {
34 + cwd: root,
35 + encoding: 'utf8',
36 + env: {
37 + ...process.env,
38 + PATH: `${join(root, 'bin')}:${process.env.PATH}`,
39 + FIXTURE_ROOT: root,
40 + RUNNER_TEMP: root,
41 + GH_REPO: 'ComposioHQ/composio',
42 + PUBLISH_BRANCH: job === 'publish' ? 'docs/kb-front-desk-2' : 'docs/auto-update-kb',
43 + GUIDE_SLUG: 'sdk-example',
44 + ...env,
45 + },
46 + });
47 +}
48 +
49 +function fixture() {
50 + const root = mkdtempSync(join(tmpdir(), 'kb-publication-'));
51 + mkdirSync(join(root, 'bin'));
52 + writeFileSync(join(root, 'calls'), '');
53 + writeFileSync(join(root, 'sleeps'), '');
54 + writeFileSync(join(root, 'bin/gh'), `#!/bin/bash
55 +set -euo pipefail
56 +echo called >> "$FIXTURE_ROOT/calls"
57 +if [ "\${FAIL_API:-false}" = true ]; then exit 1; fi
58 +if [[ " $* " == *" --paginate "* ]]; then
59 + cat "$FIXTURE_ROOT/current.jsonl"
60 +else
61 + head -n 1 "$FIXTURE_ROOT/current.jsonl"
62 +fi | jq -r "\${@: -1}"
63 +`, { mode: 0o755 });
64 + writeFileSync(join(root, 'bin/sleep'), `#!/bin/bash
65 +set -euo pipefail
66 +echo slept >> "$FIXTURE_ROOT/sleeps"
67 +if [ -f "$FIXTURE_ROOT/after.jsonl" ]; then
68 + cp "$FIXTURE_ROOT/after.jsonl" "$FIXTURE_ROOT/current.jsonl"
69 +fi
70 +`, { mode: 0o755 });
71 + writeFileSync(join(root, 'bin/bun'), `#!/bin/bash
72 +set -euo pipefail
73 +if [ "$2" = verify:kb ]; then
74 + cat "$FIXTURE_ROOT/report.json"
75 + exit "\${VERIFY_EXIT:-0}"
76 +fi
77 +`, { mode: 0o755 });
78 + return root;
79 +}
80 +
81 +const earlierPublication = {
82 + head: { ref: 'docs/kb-front-desk-1', repo: { full_name: 'ComposioHQ/composio' } },
83 + html_url: 'https://github.com/ComposioHQ/composio/pull/1',
84 +};
85 +
86 +describe('KB publication workflow', () => {
87 + test('waits for an earlier publication across pages while allowing the current draft and unrelated PRs', () => {
88 + const root = fixture();
89 + try {
90 + const unrelated = { head: { ref: 'docs/unrelated' }, html_url: 'unrelated' };
91 + const currentDraft = { head: { ref: 'docs/kb-front-desk-2', repo: { full_name: 'ComposioHQ/composio' } }, html_url: 'current' };
92 + writeFileSync(join(root, 'current.jsonl'),
93 + `${JSON.stringify([unrelated, currentDraft])}\n${JSON.stringify([earlierPublication])}\n`);
94 + writeFileSync(join(root, 'after.jsonl'), `${JSON.stringify([unrelated, currentDraft])}\n`);
95 +
96 + const result = runStep('Wait for earlier KB publications', root);
97 +
98 + expect(result.status).toBe(0);
99 + expect(result.stdout).toContain(earlierPublication.html_url);
100 + expect(result.stdout).not.toContain('unrelated');
101 + expect(result.stdout).not.toContain('current');
102 + expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(2);
103 + expect(readFileSync(join(root, 'sleeps'), 'utf8').trim().split('\n')).toHaveLength(1);
104 + } finally {
105 + rmSync(root, { recursive: true, force: true });
106 + }
107 + });
108 +
109 + test.each(['publish', 'refresh'] as const)('%s ignores fork PRs that imitate publication branches', job => {
110 + const root = fixture();
111 + try {
112 + const forkPrs = ['docs/kb-front-desk-hold', 'docs/auto-update-kb'].map(ref => ({
113 + head: { ref, repo: { full_name: 'outsider/composio' } }, html_url: 'fork-pr',
114 + }));
115 + writeFileSync(join(root, 'current.jsonl'), JSON.stringify(forkPrs));
116 + const result = runStep('Wait for earlier KB publications', root, {}, job);
117 + expect(result.status).toBe(0);
118 + expect(result.stdout).not.toContain('fork-pr');
119 + expect(readFileSync(join(root, 'sleeps'), 'utf8')).toBe('');
120 + } finally {
121 + rmSync(root, { recursive: true, force: true });
122 + }
123 + });
124 +
125 + test.each([
126 + ['publish', 'docs/auto-update-kb'],
127 + ['refresh', 'docs/kb-front-desk-1'],
128 + ] as const)('%s waits for the other publication path to merge', (job, ref) => {
129 + const root = fixture();
130 + try {
131 + writeFileSync(join(root, 'current.jsonl'), JSON.stringify([{
132 + head: { ref, repo: { full_name: 'ComposioHQ/composio' } }, html_url: 'earlier-kb-publication',
133 + }]));
134 + writeFileSync(join(root, 'after.jsonl'), '[]');
135 + const result = runStep('Wait for earlier KB publications', root, {}, job);
136 + expect(result.status).toBe(0);
137 + expect(result.stdout).toContain('earlier-kb-publication');
138 + expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(2);
139 + } finally {
140 + rmSync(root, { recursive: true, force: true });
141 + }
142 + });
143 +
144 + test('fails with a recovery instruction when an earlier publication stays open', () => {
145 + const root = fixture();
146 + try {
147 + writeFileSync(join(root, 'current.jsonl'), `${JSON.stringify([earlierPublication])}\n`);
148 +
149 + const result = runStep('Wait for earlier KB publications', root);
150 +
151 + expect(result.status).toBe(1);
152 + expect(result.stderr).toContain('Merge or close them, then rerun this workflow.');
153 + expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(60);
154 + } finally {
155 + rmSync(root, { recursive: true, force: true });
156 + }
157 + });
158 +
159 + test('stops on an API failure instead of assuming no earlier publication exists', () => {
160 + const root = fixture();
161 + try {
162 + const result = runStep('Wait for earlier KB publications', root, { FAIL_API: 'true' });
163 +
164 + expect(result.status).toBe(1);
165 + expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(1);
166 + expect(readFileSync(join(root, 'sleeps'), 'utf8')).toBe('');
167 + } finally {
168 + rmSync(root, { recursive: true, force: true });
169 + }
170 + });
171 +
172 + test('blocks support-facing prose even when verification reports it as a warning', () => {
173 + const root = fixture();
174 + try {
175 + writeFileSync(join(root, 'report.json'), JSON.stringify({
176 + findings: [{ severity: 'warning', kind: 'unedited-support-prose', guideSlug: 'sdk-example' }],
177 + }));
178 +
179 + const result = runStep('Regenerate KB pages', root);
180 +
181 + expect(result.status).toBe(1);
182 + expect(result.stderr).toContain('Rewrite it for public readers');
183 + } finally {
184 + rmSync(root, { recursive: true, force: true });
185 + }
186 + });
187 +
188 + test('allows an approval when only another guide has support-facing prose', () => {
189 + const root = fixture();
190 + try {
191 + writeFileSync(join(root, 'report.json'), JSON.stringify({
192 + findings: [{ severity: 'warning', kind: 'unedited-support-prose', guideSlug: 'other-guide' }],
193 + }));
194 + expect(runStep('Regenerate KB pages', root).status).toBe(0);
195 + } finally {
196 + rmSync(root, { recursive: true, force: true });
197 + }
198 + });
199 +
200 + test('allows advisory review cohorts while retaining verification errors', () => {
201 + const root = fixture();
202 + try {
203 + writeFileSync(join(root, 'report.json'), JSON.stringify({
204 + findings: [{ severity: 'warning', kind: 'review-window-cliff' }],
205 + }));
206 + expect(runStep('Regenerate KB pages', root).status).toBe(0);
207 +
208 + writeFileSync(join(root, 'report.json'), JSON.stringify({
209 + findings: [{ severity: 'error', kind: 'unknown-tool-slug' }],
210 + }));
211 + expect(runStep('Regenerate KB pages', root, { VERIFY_EXIT: '1' }).status).toBe(1);
212 + } finally {
213 + rmSync(root, { recursive: true, force: true });
214 + }
215 + });
216 +});
docs/tests/static/kb-publish.test.ts new
+98
@@ -0,0 +1,98 @@
1 +import { afterEach, describe, expect, test } from 'bun:test';
2 +import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
3 +import { tmpdir } from 'node:os';
4 +import { join } from 'node:path';
5 +import { publishKbGuide } from '../../scripts/publish-kb-guide';
6 +
7 +const roots: string[] = [];
8 +const now = new Date('2026-08-18T00:00:00Z');
9 +const request = {
10 + action: 'upsert', slug: 'sdk-example', area: 'sdk', title: 'Example',
11 + description: 'Public example.', body: '## Setup\n\nFollow these steps.',
12 + topics: ['authentication'], tags: ['old-tag'],
13 +};
14 +
15 +function fixture(): string {
16 + const root = mkdtempSync(join(tmpdir(), 'kb-publish-'));
17 + roots.push(root);
18 + mkdirSync(join(root, 'kb/source'), { recursive: true });
19 + mkdirSync(join(root, 'kb/articles'));
20 + writeFileSync(join(root, 'kb/manifest.json'), JSON.stringify({
21 + schemaVersion: 2,
22 + source: { repository: 'ComposioHQ/support-knowledge', commit: 'initial', capturedAt: '2026-08-18', contentHash: 'sha256:fixture' },
23 + topics: [{ slug: 'authentication', title: 'Authentication', description: 'Authentication guidance.', featuredRank: 1 }],
24 + guides: [],
25 + }));
26 + return root;
27 +}
28 +
29 +function guide(root: string) {
30 + return JSON.parse(readFileSync(join(root, 'kb/manifest.json'), 'utf8')).guides[0];
31 +}
32 +
33 +function contents(root: string): Map<string, string> {
34 + return new Map(readdirSync(join(root, 'kb'), { recursive: true, withFileTypes: true })
35 + .filter(entry => entry.isFile())
36 + .map(entry => {
37 + const path = join(entry.parentPath, entry.name);
38 + return [path, readFileSync(path, 'utf8')];
39 + }));
40 +}
41 +
42 +afterEach(() => {
43 + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
44 +});
45 +
46 +describe('approved KB guide publishing', () => {
47 + test('clears explicit empty tags and retains omitted tags', () => {
48 + const root = fixture();
49 + publishKbGuide(request, root, now);
50 + publishKbGuide({ action: 'upsert', slug: request.slug, body: request.body }, root, now);
51 + expect(guide(root).tags).toEqual(['old-tag']);
52 + publishKbGuide({ action: 'upsert', slug: request.slug, body: request.body, tags: [] }, root, now);
53 + expect(guide(root).tags).toEqual([]);
54 + expect(guide(root).managedBy).toBe('support-portal');
55 + });
56 +
57 + test('creates a valid guide with no tags', () => {
58 + const root = fixture();
59 + publishKbGuide({ ...request, tags: [] }, root, now);
60 + expect(guide(root).tags).toEqual([]);
61 + expect(readFileSync(join(root, 'kb/articles/sdk-example.md'), 'utf8')).toBe(`${request.body}\n`);
62 + });
63 +
64 + test('rejects explicitly empty topics without writing', () => {
65 + const root = fixture();
66 + publishKbGuide(request, root, now);
67 + const before = contents(root);
68 + expect(() => publishKbGuide({ ...request, topics: [] }, root, now))
69 + .toThrow('At least one topic is required');
70 + expect(contents(root)).toEqual(before);
71 + });
72 +
73 + test.each([
74 + ['path traversal', { slug: '../escape' }],
75 + ['leading hyphen', { slug: '-sdk-example' }],
76 + ['empty segment', { slug: 'sdk--example' }],
77 + ['trailing hyphen', { slug: 'sdk-example-' }],
78 + ['oversized slug', { slug: `${'a'.repeat(60_000)}!` }],
79 + ['null slug', { slug: null }],
80 + ['unknown action', { action: 'unsupported' }],
81 + ['invalid tags', { tags: 'not-an-array' }],
82 + ['invalid topics', { topics: [123] }],
83 + ])('rejects %s before changing files', (_label, change) => {
84 + const root = fixture();
85 + const before = contents(root);
86 + expect(() => publishKbGuide({ ...request, ...change }, root, now)).toThrow();
87 + expect(contents(root)).toEqual(before);
88 + });
89 +
90 + test('validates staged content before changing an existing guide', () => {
91 + const root = fixture();
92 + publishKbGuide(request, root, now);
93 + const before = contents(root);
94 + expect(() => publishKbGuide({ ...request, body: 'See T-12345 for details.' }, root, now))
95 + .toThrow('Plain thread reference');
96 + expect(contents(root)).toEqual(before);
97 + });
98 +});
docs/tests/static/kb-update-workflow.test.ts
+21 -6
@@ -284,20 +284,35 @@ echo "head_ref=$live_head_ref" >> "$GITHUB_OUTPUT"`);
284 expect(resolveSource?.run).toBe('bash scripts/resolve-kb-refresh-source.sh');
285 });
286
287 - test('serializes refreshes and checks complete upstream history', () => {
287 + test('serializes both KB writers before checkout and pins artifacts to their docs base', () => {
288 const workflow = Bun.YAML.parse(readFileSync(workflowPath, 'utf8')) as {
289 - concurrency?: { group?: string; 'cancel-in-progress'?: boolean };
289 + concurrency?: { group?: string; 'cancel-in-progress'?: boolean; queue?: string };
290 jobs?: Record<string, WorkflowJob>;
291 };
292 const checkout = workflow.jobs?.refresh?.steps?.find(
293 step => step.name === 'Checkout support knowledge',
294 );
295
296 - expect(workflow.concurrency).toEqual({
297 - group: 'docs-support-knowledge-refresh',
298 - 'cancel-in-progress': true,
299 - });
296 + const publish = Bun.YAML.parse(readFileSync(
297 + resolve(process.cwd(), '..', '.github/workflows/docs-kb-publish.yml'), 'utf8',
298 + )) as { concurrency: { group: string }; jobs: Record<string, WorkflowJob> };
299 + expect(workflow.concurrency?.group).toBe(publish.concurrency.group);
300 + expect(workflow.concurrency?.['cancel-in-progress']).toBe(false);
301 + expect(workflow.concurrency?.queue).toBe('max');
302 expect(checkout?.with?.['fetch-depth']).toBe(0);
303 + for (const job of [workflow.jobs?.refresh, publish.jobs.publish]) {
304 + const steps = job?.steps ?? [];
305 + const waitIndex = steps.findIndex(step => step.name === 'Wait for earlier KB publications');
306 + const checkoutIndex = steps.findIndex(step => step.name === 'Checkout docs repository');
307 + expect(waitIndex).toBeGreaterThanOrEqual(0);
308 + expect(waitIndex).toBeLessThan(checkoutIndex);
309 + expect(steps[checkoutIndex]?.with?.ref).toBe('next');
310 + }
311 + const proposalCheckout = workflow.jobs?.propose?.steps?.find(
312 + step => step.name === 'Checkout docs repository',
313 + );
314 + expect(workflow.jobs?.refresh?.outputs?.docs_base_sha).toBe('${{ steps.docs-base.outputs.sha }}');
315 + expect(proposalCheckout?.with?.ref).toBe('${{ needs.refresh.outputs.docs_base_sha }}');
316 });
317
318 test('tracks failures until both refresh and PR proposal recover', () => {