Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
ci(docs): refresh support knowledge from dispatches
Soham Basu committed
Aug 31, 2026 at 21:40 UTC
43a6c391ba4cd6dd8b7fc341ff4b8a28d1d24b57
8 files changed
+383
-310
.github/workflows/docs-update-kb.yml
+11
-17
@@ -1,6 +1,8 @@
1
name: Docs - Update Support Knowledge
2
3
on:
4
+ # Dispatch is the primary path; this six-hour run reconciles missed events and
5
+ # repairs semantic artifacts made stale by docs-side content changes.
6
schedule:
7
- cron: '17 */6 * * *'
8
repository_dispatch:
@@ -10,6 +12,10 @@ on:
12
permissions:
13
contents: read
14
15
+concurrency:
16
+ group: docs-support-knowledge-refresh
17
+ cancel-in-progress: true
18
+
19
jobs:
20
refresh:
21
runs-on: ubuntu-latest
@@ -49,31 +55,19 @@ jobs:
55
with:
56
repository: ComposioHQ/support-knowledge
57
token: ${{ steps.upstream-token.outputs.token }}
58
+ ref: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || 'main' }}
59
path: .support-knowledge
60
persist-credentials: false
61
+ fetch-depth: 0
62
63
- name: Resolve upstream change
64
id: source
65
env:
66
SOURCE_ROOT: ${{ github.workspace }}/.support-knowledge
67
HAVE_UPSTREAM: ${{ steps.upstream-token.outcome == 'success' }}
60
- run: |
61
- current_commit=$(jq -r '.source.commit' kb/manifest.json)
62
- echo "commit=$current_commit" >> "$GITHUB_OUTPUT"
63
- if [ "$HAVE_UPSTREAM" != "true" ]; then
64
- echo "upstream_changed=false" >> "$GITHUB_OUTPUT"
65
- echo "No upstream token; skipping support-knowledge sync check and treating upstream as unchanged."
66
- exit 0
67
- fi
68
- source_commit=$(git -C "$SOURCE_ROOT" rev-parse HEAD)
69
- echo "commit=$source_commit" >> "$GITHUB_OUTPUT"
70
- if [ "$source_commit" = "$current_commit" ]; then
71
- echo "upstream_changed=false" >> "$GITHUB_OUTPUT"
72
- echo "Support knowledge is already current at $source_commit."
73
- else
74
- echo "upstream_changed=true" >> "$GITHUB_OUTPUT"
75
- echo "Refreshing support knowledge from $current_commit to $source_commit."
76
- fi
68
+ EVENT_NAME: ${{ github.event_name }}
69
+ REQUESTED_SOURCE_COMMIT: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || '' }}
70
+ run: bash scripts/resolve-kb-refresh-source.sh
71
72
- name: Setup Node.js, pnpm, Bun
73
uses: ./.github/actions/setup-node-pnpm-bun
docs/decisions/README.md
+2
-2
@@ -7,8 +7,8 @@ Read these when a docs change touches an existing architecture, generated-data p
7
- `examples.md` - cookbook/examples restructuring plan.
8
- `feedback.md` - feedback collection system.
9
- `llm-guardrails.md` - LLM guardrail injection for markdown endpoints.
10
-- `public-knowledge-base.md` - public support publication, unified search, and
11
- Composio For You snapshot rules.
10
+- `public-knowledge-base.md` - event-driven public support publication, unified
11
+ search, and Composio For You snapshot rules.
12
- `toolkit-page-availability.md` - docs-sync permissions, optional KB isolation,
13
and snapshot-miss toolkit page fallback.
14
- `toolkits.md` - toolkit page data and rendering decisions.
docs/decisions/public-knowledge-base.md
+81
-286
@@ -1,288 +1,83 @@
1
# Public Knowledge Base
2
3
-## Decision
4
-
5
-Host the Composio public knowledge base in the existing documentation site at
6
-`docs.composio.dev/kb`. Add **Knowledge Base** as a top-level navigation item
7
-between Docs and Examples.
8
-
9
-`ComposioHQ/support-knowledge` is the canonical authoring repository for
10
-support-specific KB prose. The docs site contains a pinned, manually reviewed
11
-publication snapshot with source provenance and freshness metadata. A pull-only
12
-importer validates an explicit local checkout and atomically refreshes that
13
-snapshot; it never writes upstream. Canonical product documentation remains in
14
-the docs repository, including the reviewed Composio For You client snapshot
15
-defined below.
16
-
17
-The `/kb/search` experience is a unified public-support search, not a KB-only
18
-index. Every current public docs, KB, toolkit, example, reference, and changelog
19
-record is eligible, with source-aware retrieval and ranking. Keyword search is
20
-the fast path across the full corpus; semantic retrieval is reserved for
21
-editorial docs and KB prose when lexical retrieval does not produce a strong
22
-match.
23
-
24
-## Context
25
-
26
-Customer-shareable support knowledge is classified in `support-knowledge` as
27
-either `public` or `customer-safe`. Only `public.md` leaves are eligible for the
28
-hosted site, public search artifacts, and public agent skills. The first
29
-implementation prototype rendered two reviewed guides inside the marketing
30
-`landing` repository. That prototype proved the
31
-publication gates and user experience, but the docs application is a better
32
-runtime because it already provides:
33
-
34
-- Fumadocs content collections and article layouts;
35
-- navigation, responsive sidebars, and search;
36
-- Algolia indexing with a local Fumadocs fallback;
37
-- feedback collection, sitemap generation, and LLM-readable endpoints;
38
-- a public GitHub repository and an established documentation review process.
39
-
40
-Keeping the KB in `landing` would duplicate those systems and split technical
41
-support content from the documentation audience.
42
-
43
-Three locations were considered:
44
-
45
-1. **Docs application (chosen):** native documentation UX and discovery with a
46
- small amount of collection and route work.
47
-2. **Marketing application:** strongest main-domain ownership, but duplicates
48
- docs rendering, search, feedback, and discovery infrastructure.
49
-3. **Separate repository or subdomain:** independent deployment, but creates a
50
- third public content surface and the largest maintenance burden.
51
-
52
-## Architecture
53
-
54
-The system has three distinct responsibilities:
55
-
56
-1. **Authoring:** support maintainers edit classified leaves in
57
- `support-knowledge`; its validation, freshness, manifest, and human review
58
- gates remain authoritative.
59
-2. **Publication:** a maintainer runs the pull-only importer against an explicit
60
- source checkout and commit. The staged snapshot records source provenance,
61
- public routes, content hashes, verification dates, and review deadlines, and
62
- replaces the previous valid snapshot only after validation succeeds.
63
-3. **Rendering:** the `docs/` Fumadocs application renders only published pages
64
- and includes them in navigation, search, sitemap, feedback, and LLM outputs.
65
-
66
-The initial release keeps invocation and review manual. It automates the
67
-mechanical copy so classification enforcement is reproducible, but it does not
68
-fetch private repositories at application runtime, open pull requests, publish,
69
-or write back to `support-knowledge`.
70
-
71
-## Content Model
72
-
73
-Every reviewed `public.md` file is eligible for the public corpus, but a source
74
-file is not necessarily one web page. A self-contained level-two problem or
75
-question can become an individual guide. Structural headings stay with their
76
-parent guide.
77
-
78
-The publication layer records:
79
-
80
-- stable slug and aliases;
81
-- title and description;
82
-- source repository, commit, path, and selected heading;
83
-- topics, tags, and related resources;
84
-- updated and last-verified dates;
85
-- freshness class and review deadline;
86
-- `published`, `needs-review`, or `retired` state.
87
-
88
-The docs-site snapshot imports every public leaf from a verified
89
-`ComposioHQ/support-knowledge` commit. Customer-safe leaves remain excluded.
90
-The manifest records both the exact commit and a deterministic hash of the
91
-vendored public source bytes.
92
-
93
-### Composio For You
94
-
95
-Client setup content is maintained in the dashboard repository rather than
96
-`support-knowledge`. The initial For You publication takes a one-time snapshot
97
-of the client definitions and public-safe onboarding media at dashboard commit
98
-`269ab875f5c2fb0f40b312328812e7cc068faaa9` and reconciles the canonical
99
-`/docs/composio-connect` page with that snapshot.
100
-
101
-The docs page, not a duplicated KB page, remains canonical for client setup.
102
-Client sections use stable anchors and searchable aliases for renamed or
103
-closely related clients. The snapshot contains placeholders and public setup
104
-instructions only; personalized keys, sessions, connection state, logs,
105
-organization identifiers, and account-specific URLs remain excluded.
106
-
107
-Existing For You-tagged KB guides remain canonical for support-specific facts
108
-and troubleshooting. New KB guides are added only for an identified knowledge
109
-gap that is not already answered by current docs or a published KB guide.
110
-Volatile pricing, entitlement, and security claims require an authoritative
111
-public source and are not copied from dashboard FAQ prose by default.
112
-
113
-### Identifier URLs
114
-
115
-KB prose cites machine identifiers that happen to look like URLs: OAuth
116
-scope URIs such as `https://www.googleapis.com/auth/…` and API surface roots
117
-such as `https://api.ahrefs.com/v3`. These are not documents; fetching them
118
-404s by design, so they can never survive the nightly external-link sweep as
119
-links. The generation layer therefore demotes bare citations and `<url>`
120
-autolinks of these two shapes to inline code spans. Explicit markdown links
121
-keep their authored form — if one points at an identifier URL, the nightly
122
-sweep flags it for an upstream fix instead of the pipeline silently rewriting
123
-navigation the author wrote.
124
-
125
-## Routes and Navigation
126
-
127
-- `/kb` is the knowledge-base landing page.
128
-- `/kb/<topic>` is a topic landing page when a topic has multiple guides.
129
-- `/kb/<topic>/<guide-slug>` is the canonical guide route.
130
-- aliases permanently redirect to the canonical route.
131
-
132
-The header order is Docs, Knowledge Base, Examples, Toolkits, Reference. KB
133
-pages use native Fumadocs layouts and components rather than maintaining a
134
-second design system. The KB landing page may use a small custom MDX landing
135
-page for search, featured guides, recently verified guides, and topic cards.
136
-
137
-The marketing site may later redirect `composio.dev/kb` to
138
-`docs.composio.dev/kb`; the unmerged marketing prototype does not establish a
139
-public URL contract.
140
-
141
-## Search and Discovery
142
-
143
-`/kb/search` searches every current public record in the existing Algolia index:
144
-docs, KB guides, toolkits, examples, current reference, and changelog. Legacy
145
-reference records are eligible only for an exact identity match when no current
146
-reference record answers the same query. Search results always link to the
147
-canonical page or section; the search layer does not generate an answer or
148
-create redirect-only KB copies of docs pages.
149
-
150
-Retrieval is deliberately asymmetric by source:
151
-
152
-1. Run keyword retrieval across the complete public index.
153
-2. Treat an exact normalized title, keyword, slug, toolkit slug, tool slug, or
154
- current reference identity as a strong lexical match and return it without
155
- waiting for an embedding request.
156
-3. When lexical confidence is weak, embed the query and search a checked-in
157
- OpenAI `text-embedding-3-small` artifact containing public KB and docs prose.
158
-4. Fuse the editorial semantic candidates with the full-corpus keyword
159
- candidates using deterministic Reciprocal Rank Fusion, while preserving
160
- exact identifier matches.
161
-
162
-Natural-language support questions therefore favor KB and docs prose, while
163
-exact toolkit, action, endpoint, and schema queries favor toolkit or reference
164
-records. Toolkits, generated reference, examples, and changelog are not added
165
-to the semantic artifact: their structured identifiers work better with
166
-lexical retrieval, and embedding them would increase artifact size and scan
167
-time without improving the common support path. This corpus does not justify
168
-Algolia NeuralSearch, a vector database, or an approximate index.
169
-
170
-The existing global Docs search remains keyword-only. If query embedding or the
171
-semantic artifact is unavailable, `/kb/search` returns the complete keyword
172
-result set. If Algolia is unavailable, it uses the local lexical index and may
173
-combine those results with editorial semantic candidates. No failure path
174
-widens discovery beyond records already classified for public indexing.
175
-
176
-The initial `/kb/search?q=...` request runs through a shared server-side search
177
-service during page rendering. The API route calls the same service for direct
178
-agent access and subsequent client-side requests. The page hydrates with the
179
-server result instead of waiting for React hydration before starting its first
180
-search, avoiding a page-load-to-API waterfall without maintaining two ranking
181
-implementations.
182
-
183
-Preview deployments must represent the branch under review even though the
184
-shared Algolia index synchronizes only from `next`. In Vercel preview and local
185
-development, `/kb/search` overlays module-cached lexical results from the
186
-branch's bundled docs and KB collections on the shared Algolia candidates.
187
-Branch-local records replace shared records with the same canonical URL;
188
-toolkits, examples, reference, and changelog continue to come from the shared
189
-index. Production uses the synchronized Algolia corpus without this overlay.
190
-Overlay failure falls back to the shared index and is reported as retrieval
191
-degradation; it does not require a branch-specific Algolia index or database.
192
-
193
-Semantic requests retain a configurable three-second safety timeout, an
194
-eight-request concurrency ceiling, a 60-request-per-minute client budget, and a
195
-generous 600-request-per-minute process ceiling. The timeout is a worst-case
196
-guardrail, not a delay imposed on strong lexical searches. Hitting any semantic
197
-guardrail is logged and returns keyword results rather than blocking search.
198
-
199
-Mixed result cards show a concise source label such as Documentation, Knowledge
200
-Base, Toolkit, Example, or API Reference. They do not show the redundant
201
-`Guide` badge. Search analytics record total duration, keyword duration,
202
-semantic duration when invoked, retrieval mode, result source types, clicked
203
-source type and position, zero-result searches, and guardrail degradation.
204
-
205
-The same read-only unified search and canonical-page contract is available to
206
-the existing public `composio` skill as a fallback after its primary
207
-documentation and CLI sources. The skill uses the unified endpoint rather than
208
-hard-coding a KB-only filter. It retrieves evidence and lets its host agent
209
-answer; it does not contain a duplicate fact corpus or run its own generation
210
-service.
211
-Authenticated retrieval of `customer-safe` content is a separate future design.
212
-
213
-Published KB pages are also included in:
214
-
215
-- the XML sitemap;
216
-- `llms.txt`, `llms-full.txt`, and scoped `llms.mdx` routes;
217
-- link validation;
218
-- the existing feedback flow.
219
-
220
-`needs-review` and retired entries are excluded from routes and every discovery
221
-surface.
222
-
223
-## Freshness and Privacy
224
-
225
-Publication fails when a published entry:
226
-
227
-- is not explicitly public;
228
-- contains known private-data markers;
229
-- has no verification or review deadline;
230
-- has an expired review deadline;
231
-- references an unknown topic, related guide, source section, or alias;
232
-- collides with another canonical route or alias.
233
-
234
-Default review windows remain 180 days for evergreen guidance, 30 days for
235
-provider or OAuth setup, and 7 days for active incidents. These are publication
236
-defaults in the docs application, not changes to the canonical source schema.
237
-
238
-Guide pages show the last-verified date. Time-sensitive material is held by
239
-default until its live behavior has been rechecked.
240
-
241
-## Failure Handling
242
-
243
-The KB validator runs before docs builds and reports the source path and reason
244
-for invalid content. A failed or stale entry must not be silently omitted from
245
-a supposedly successful publication. External resource failures must not make
246
-the local KB unavailable; they may degrade to ordinary links.
247
-
248
-## Testing and Verification
249
-
250
-The implementation is complete when:
251
-
252
-- parser and publication-gate unit tests pass;
253
-- the importer verifies the upstream repository and exact checked-out commit;
254
-- the validator reports the expected public guide count and no private leaves;
255
-- `/kb`, topic pages, guide pages, and aliases render in a local docs build;
256
-- held content is absent from routes, search, sitemap, and LLM outputs;
257
-- current For You clients in the pinned dashboard snapshot have canonical,
258
- searchable setup sections with no personalized values;
259
-- representative natural-language, client-setup, toolkit, exact action-slug,
260
- and API-reference queries return the expected source class without asserting
261
- mutable prose claims;
262
-- the initial search result is present in the server-rendered response and does
263
- not depend on a post-hydration request;
264
-- preview search prefers branch-local docs and KB records over shared Algolia
265
- versions with the same canonical URL, while production does not apply the
266
- overlay;
267
-- strong lexical queries do not invoke semantic retrieval, while weak queries
268
- can fuse editorial semantic results with full-corpus keyword results;
269
-- semantic timeout, rate, capacity, artifact, and embedding failures return
270
- keyword results and emit the expected analytics category;
271
-- existing docs tests, type checks, lint, link validation, and production build
272
- pass;
273
-- the header exposes Knowledge Base in desktop and mobile navigation.
274
-
275
-## Consequences
276
-
277
-- The unmerged `landing` KB branch becomes a prototype, not the production
278
- destination. Reusable publication logic and tests are ported; custom page
279
- chrome is not.
280
-- Public KB prose continues to be maintained in `support-knowledge`.
281
-- Canonical For You client setup lives in docs from a reviewed, one-time
282
- dashboard snapshot; automatic synchronization remains out of scope.
283
-- The docs repository owns the deployed snapshot, route metadata, validation,
284
- and presentation.
285
-- No new repository, subdomain, or synchronization service is introduced.
286
-- The hosted UI, API, and agent skills share one public-only, multi-source
287
- retrieval contract; customer-safe and live operational evidence remain
288
- separate boundaries.
3
+## Purpose and ownership
4
+
5
+- The public knowledge base is hosted with the documentation at
6
+ `docs.composio.dev/kb`.
7
+- `ComposioHQ/support-knowledge` is the source of support-specific public prose.
8
+- The docs repository owns the reviewed publication snapshot, routes, search
9
+ integration, and presentation.
10
+- Product documentation remains canonical for product concepts and workflows;
11
+ KB guides cover support questions and troubleshooting gaps.
12
+
13
+## Content boundaries
14
+
15
+- Only content explicitly classified for public use is eligible for import.
16
+- Non-public classifications and account-specific information must never enter
17
+ the snapshot, generated pages, search indexes, or agent-readable outputs.
18
+- New guides should address a real knowledge gap rather than duplicate an
19
+ existing documentation or KB page.
20
+- Time-sensitive claims require an authoritative public source and current
21
+ verification.
22
+- A source document may produce multiple focused guides. Stable slugs and
23
+ aliases preserve published URLs as the source evolves.
24
+
25
+## Publication and maintenance
26
+
27
+- A source change triggers a refresh after it reaches the source repository's
28
+ main branch; periodic reconciliation catches missed events.
29
+- The refresh validates the repository, source commit, and mainline ancestry
30
+ before importing any content.
31
+- Delayed events resolve to the newest mainline commit that changed public
32
+ content. Non-public or repository-maintenance changes do not advance the
33
+ published snapshot.
34
+- Refreshes are serialized so overlapping runs cannot race.
35
+- The importer treats upstream files as data, never executes upstream code, and
36
+ never writes back to the source repository.
37
+- Import, page generation, search-artifact generation, and validation complete
38
+ before an automated refresh pull request is opened.
39
+- A human review and merge remains the final publication gate.
40
+
41
+## Rendering and discovery
42
+
43
+- Published guides appear under `/kb` and use the docs site's existing
44
+ navigation, layout, feedback, and canonical-link behavior.
45
+- Knowledge search covers public docs, KB guides, toolkits, examples, current
46
+ reference pages, and changelog entries.
47
+- Search uses keyword matching first and semantic retrieval for public docs and
48
+ KB prose when keyword confidence is weak.
49
+- Semantic-search failures fall back to public keyword results; failure must
50
+ never broaden the eligible corpus.
51
+- Published guides are included in the sitemap and agent-readable documentation
52
+ outputs.
53
+- Content awaiting review or marked as retired is excluded from routes and all
54
+ discovery surfaces.
55
+
56
+## Freshness and safety
57
+
58
+- The manifest records source provenance, a deterministic content hash,
59
+ canonical routes, verification dates, review deadlines, and publication
60
+ state.
61
+- Publication rejects content that is not explicitly public, contains known
62
+ private-data markers, is stale, has broken references, or conflicts with an
63
+ existing route.
64
+- Time-sensitive content stays unpublished until it has been reverified.
65
+- The running docs application reads only the checked-in public snapshot; it
66
+ does not access the source repository at runtime.
67
+
68
+## Failure handling
69
+
70
+- A candidate snapshot is validated before it replaces the current snapshot.
71
+- A failed validation or import leaves the last valid public snapshot intact
72
+ and surfaces the failure for follow-up.
73
+- Invalid or stale guides must not be silently omitted from an otherwise
74
+ successful publication.
75
+- External-service failures may reduce search quality or link enrichment, but
76
+ they must not make private content eligible.
77
+
78
+## Verification
79
+
80
+- Run `bun run test`, `bun run types:check`, `bun run lint`,
81
+ `bun run lint:links`, and `bun run build` from `docs/`.
82
+- Verify generated KB pages and the semantic artifact are current before
83
+ merging a refresh.
docs/lib/kb/support-knowledge.ts
+8
@@ -537,6 +537,14 @@ export function writeSupportKnowledgeSnapshot(input: {
537
}
538
cpSync(externalSources, join(stagedRoot, 'external-sources'), { recursive: true });
539
}
540
+ const semanticIndex = join(targetRoot, 'semantic-index.json');
541
+ if (existsSync(semanticIndex)) {
542
+ const semanticIndexStats = lstatSync(semanticIndex);
543
+ if (semanticIndexStats.isSymbolicLink() || !semanticIndexStats.isFile()) {
544
+ throw new Error('KB semantic-index.json must be a regular file');
545
+ }
546
+ cpSync(semanticIndex, join(stagedRoot, 'semantic-index.json'));
547
+ }
548
input.validate(stagedRoot);
549
if (existsSync(targetRoot)) {
550
renameSync(targetRoot, backupRoot);
docs/scripts/resolve-kb-refresh-source.sh
new
+61
@@ -0,0 +1,61 @@
1
+#!/usr/bin/env bash
2
+
3
+set -euo pipefail
4
+
5
+current_commit=$(jq -r '.source.commit' kb/manifest.json)
6
+echo "commit=$current_commit" >> "$GITHUB_OUTPUT"
7
+
8
+if [ "$EVENT_NAME" = "repository_dispatch" ] && [ -z "$REQUESTED_SOURCE_COMMIT" ]; then
9
+ echo "::error::Dispatched support knowledge refresh is missing source_commit."
10
+ exit 1
11
+fi
12
+
13
+if [ "$HAVE_UPSTREAM" != "true" ]; then
14
+ if [ "$EVENT_NAME" = "repository_dispatch" ]; then
15
+ echo "::error::Cannot process a dispatched support knowledge refresh without an upstream token."
16
+ exit 1
17
+ fi
18
+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"
19
+ echo "No upstream token; skipping support-knowledge sync check and treating upstream as unchanged."
20
+ exit 0
21
+fi
22
+
23
+checkout_commit=$(git -C "$SOURCE_ROOT" rev-parse HEAD)
24
+if [ -n "$REQUESTED_SOURCE_COMMIT" ] && [ "$checkout_commit" != "$REQUESTED_SOURCE_COMMIT" ]; then
25
+ echo "::error::Support knowledge HEAD $checkout_commit does not match dispatched commit $REQUESTED_SOURCE_COMMIT."
26
+ exit 1
27
+fi
28
+
29
+if ! upstream_tip=$(git -C "$SOURCE_ROOT" rev-parse --verify refs/remotes/origin/main 2>/dev/null); then
30
+ echo "::error::Cannot resolve the support knowledge main branch."
31
+ exit 1
32
+fi
33
+
34
+if [ -n "$REQUESTED_SOURCE_COMMIT" ] && \
35
+ ! git -C "$SOURCE_ROOT" merge-base --is-ancestor "$REQUESTED_SOURCE_COMMIT" "$upstream_tip"; then
36
+ echo "::error::Dispatched support knowledge commit $REQUESTED_SOURCE_COMMIT is not on upstream main."
37
+ exit 1
38
+fi
39
+
40
+if [ "$upstream_tip" = "$current_commit" ]; then
41
+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"
42
+ echo "Support knowledge is already current at $upstream_tip."
43
+elif ! git -C "$SOURCE_ROOT" cat-file -e "$current_commit^{commit}" 2>/dev/null; then
44
+ echo "::error::Published support knowledge commit $current_commit is unavailable in the upstream history."
45
+ exit 1
46
+elif ! git -C "$SOURCE_ROOT" merge-base --is-ancestor "$current_commit" "$upstream_tip"; then
47
+ echo "::error::Published support knowledge commit $current_commit is not on upstream main."
48
+ exit 1
49
+elif ! source_commit=$(git -C "$SOURCE_ROOT" log --first-parent -1 --format=%H \
50
+ "$current_commit..$upstream_tip" -- ':(glob)**/public.md'); then
51
+ echo "::error::Cannot inspect public support knowledge history."
52
+ exit 1
53
+elif [ -z "$source_commit" ]; then
54
+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"
55
+ echo "No public support knowledge changed between $current_commit and $upstream_tip."
56
+else
57
+ git -C "$SOURCE_ROOT" checkout --detach "$source_commit"
58
+ echo "commit=$source_commit" >> "$GITHUB_OUTPUT"
59
+ echo "upstream_changed=true" >> "$GITHUB_OUTPUT"
60
+ echo "Refreshing support knowledge from $current_commit to $source_commit."
61
+fi
docs/tests/static/kb-import.test.ts
+8
@@ -398,6 +398,11 @@ describe('support-knowledge snapshot import', () => {
398
'{"preserve":true}\n',
399
'utf8',
400
);
401
+ writeFileSync(
402
+ join(targetRoot, 'semantic-index.json'),
403
+ '{"records":[{"id":"existing-vector"}]}\n',
404
+ 'utf8',
405
+ );
406
407
expect(() => writeSupportKnowledgeSnapshot({
408
snapshot,
@@ -421,5 +426,8 @@ describe('support-knowledge snapshot import', () => {
426
join(targetRoot, 'external-sources/auth-guides.json'),
427
'utf8',
428
)).toBe('{"preserve":true}\n');
429
+ expect(readFileSync(join(targetRoot, 'semantic-index.json'), 'utf8')).toBe(
430
+ '{"records":[{"id":"existing-vector"}]}\n',
431
+ );
432
});
433
});
docs/tests/static/kb-resolve-refresh-source.test.ts
new
+176
@@ -0,0 +1,176 @@
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
+
7
+const resolverPath = resolve(process.cwd(), 'scripts', 'resolve-kb-refresh-source.sh');
8
+
9
+function git(root: string, ...args: string[]): string {
10
+ const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
11
+ if (result.status !== 0) throw new Error(result.stderr);
12
+ return result.stdout.trim();
13
+}
14
+
15
+function runResolver(
16
+ cwd: string,
17
+ env: Record<string, string>,
18
+): { status: number | null; output: string; stdout: string; stderr: string } {
19
+ const outputPath = join(cwd, 'github-output.txt');
20
+ writeFileSync(outputPath, '', 'utf8');
21
+ const result = spawnSync('bash', [resolverPath], {
22
+ cwd,
23
+ encoding: 'utf8',
24
+ env: { ...process.env, ...env, GITHUB_OUTPUT: outputPath },
25
+ });
26
+ return {
27
+ status: result.status,
28
+ output: readFileSync(outputPath, 'utf8'),
29
+ stdout: result.stdout,
30
+ stderr: result.stderr,
31
+ };
32
+}
33
+
34
+function createFixture(): {
35
+ root: string;
36
+ sourceRoot: string;
37
+ docsRoot: string;
38
+ currentCommit: string;
39
+} {
40
+ const root = mkdtempSync(join(tmpdir(), 'kb-resolve-source-'));
41
+ const sourceRoot = join(root, 'support-knowledge');
42
+ const docsRoot = join(root, 'docs');
43
+ mkdirSync(join(sourceRoot, 'toolkits', 'github'), { recursive: true });
44
+ mkdirSync(join(docsRoot, 'kb'), { recursive: true });
45
+
46
+ git(sourceRoot, 'init');
47
+ git(sourceRoot, 'config', 'user.name', 'KB Workflow Test');
48
+ git(sourceRoot, 'config', 'user.email', 'kb-workflow@example.com');
49
+ writeFileSync(join(sourceRoot, 'toolkits/github/public.md'), 'public v1\n', 'utf8');
50
+ writeFileSync(
51
+ join(sourceRoot, 'toolkits/github/customer-safe.md'),
52
+ 'customer-safe v1\n',
53
+ 'utf8',
54
+ );
55
+ git(sourceRoot, 'add', '.');
56
+ git(sourceRoot, 'commit', '-m', 'initial knowledge');
57
+ const currentCommit = git(sourceRoot, 'rev-parse', 'HEAD');
58
+ writeFileSync(
59
+ join(docsRoot, 'kb/manifest.json'),
60
+ `${JSON.stringify({ source: { commit: currentCommit } })}\n`,
61
+ 'utf8',
62
+ );
63
+
64
+ return { root, sourceRoot, docsRoot, currentCommit };
65
+}
66
+
67
+describe('support knowledge refresh source resolver', () => {
68
+ test('ignores customer-safe-only changes and coalesces delayed events to the newest public change', () => {
69
+ const fixture = createFixture();
70
+
71
+ try {
72
+ writeFileSync(
73
+ join(fixture.sourceRoot, 'toolkits/github/customer-safe.md'),
74
+ 'customer-safe v2\n',
75
+ 'utf8',
76
+ );
77
+ git(fixture.sourceRoot, 'add', '.');
78
+ git(fixture.sourceRoot, 'commit', '-m', 'customer-safe only');
79
+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');
80
+
81
+ const privateOnly = runResolver(fixture.docsRoot, {
82
+ SOURCE_ROOT: fixture.sourceRoot,
83
+ HAVE_UPSTREAM: 'true',
84
+ EVENT_NAME: 'schedule',
85
+ REQUESTED_SOURCE_COMMIT: '',
86
+ });
87
+ expect(privateOnly.status).toBe(0);
88
+ expect(privateOnly.output).toBe(
89
+ `commit=${fixture.currentCommit}\nupstream_changed=false\n`,
90
+ );
91
+
92
+ writeFileSync(
93
+ join(fixture.sourceRoot, 'toolkits/github/public.md'),
94
+ 'public v2\n',
95
+ 'utf8',
96
+ );
97
+ git(fixture.sourceRoot, 'add', '.');
98
+ git(fixture.sourceRoot, 'commit', '-m', 'public knowledge');
99
+ const publicCommit = git(fixture.sourceRoot, 'rev-parse', 'HEAD');
100
+ writeFileSync(
101
+ join(fixture.sourceRoot, 'toolkits/github/customer-safe.md'),
102
+ 'customer-safe v3\n',
103
+ 'utf8',
104
+ );
105
+ git(fixture.sourceRoot, 'add', '.');
106
+ git(fixture.sourceRoot, 'commit', '-m', 'customer-safe after public knowledge');
107
+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');
108
+
109
+ const publicThenPrivate = runResolver(fixture.docsRoot, {
110
+ SOURCE_ROOT: fixture.sourceRoot,
111
+ HAVE_UPSTREAM: 'true',
112
+ EVENT_NAME: 'schedule',
113
+ REQUESTED_SOURCE_COMMIT: '',
114
+ });
115
+ expect(publicThenPrivate.status).toBe(0);
116
+ expect(publicThenPrivate.output).toBe(
117
+ `commit=${fixture.currentCommit}\ncommit=${publicCommit}\nupstream_changed=true\n`,
118
+ );
119
+
120
+ writeFileSync(
121
+ join(fixture.sourceRoot, 'toolkits/github/public.md'),
122
+ 'public v3\n',
123
+ 'utf8',
124
+ );
125
+ git(fixture.sourceRoot, 'add', '.');
126
+ git(fixture.sourceRoot, 'commit', '-m', 'newer public knowledge');
127
+ const newestPublicCommit = git(fixture.sourceRoot, 'rev-parse', 'HEAD');
128
+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');
129
+ git(fixture.sourceRoot, 'checkout', '--detach', publicCommit);
130
+
131
+ const delayedDispatch = runResolver(fixture.docsRoot, {
132
+ SOURCE_ROOT: fixture.sourceRoot,
133
+ HAVE_UPSTREAM: 'true',
134
+ EVENT_NAME: 'repository_dispatch',
135
+ REQUESTED_SOURCE_COMMIT: publicCommit,
136
+ });
137
+ expect(delayedDispatch.status).toBe(0);
138
+ expect(delayedDispatch.output).toBe(
139
+ `commit=${fixture.currentCommit}\ncommit=${newestPublicCommit}\nupstream_changed=true\n`,
140
+ );
141
+ expect(git(fixture.sourceRoot, 'rev-parse', 'HEAD')).toBe(newestPublicCommit);
142
+ } finally {
143
+ rmSync(fixture.root, { recursive: true, force: true });
144
+ }
145
+ });
146
+
147
+ test('rejects dispatched refreshes without a pinned commit or upstream access', () => {
148
+ const fixture = createFixture();
149
+
150
+ try {
151
+ const unpinned = runResolver(fixture.docsRoot, {
152
+ SOURCE_ROOT: fixture.sourceRoot,
153
+ HAVE_UPSTREAM: 'true',
154
+ EVENT_NAME: 'repository_dispatch',
155
+ REQUESTED_SOURCE_COMMIT: '',
156
+ });
157
+ expect(unpinned.status).toBe(1);
158
+ expect(unpinned.stdout).toContain(
159
+ 'Dispatched support knowledge refresh is missing source_commit.',
160
+ );
161
+
162
+ const unreadable = runResolver(fixture.docsRoot, {
163
+ SOURCE_ROOT: fixture.sourceRoot,
164
+ HAVE_UPSTREAM: 'false',
165
+ EVENT_NAME: 'repository_dispatch',
166
+ REQUESTED_SOURCE_COMMIT: fixture.currentCommit,
167
+ });
168
+ expect(unreadable.status).toBe(1);
169
+ expect(unreadable.stdout).toContain(
170
+ 'Cannot process a dispatched support knowledge refresh without an upstream token.',
171
+ );
172
+ } finally {
173
+ rmSync(fixture.root, { recursive: true, force: true });
174
+ }
175
+ });
176
+});
docs/tests/static/kb-update-workflow.test.ts
+36
-5
@@ -252,12 +252,43 @@ echo "head_ref=$live_head_ref" >> "$GITHUB_OUTPUT"`);
252
expect(workflow).toContain('actions/download-artifact@');
253
});
254
255
- test('can refresh immediately or discover upstream changes on a schedule', () => {
256
- const workflow = readFileSync(workflowPath, 'utf8');
255
+ test('passes dispatched source context to the tested resolver script', () => {
256
+ const workflow = Bun.YAML.parse(readFileSync(workflowPath, 'utf8')) as {
257
+ on?: {
258
+ repository_dispatch?: { types?: string[] };
259
+ workflow_dispatch?: unknown;
260
+ };
261
+ jobs?: Record<string, WorkflowJob>;
262
+ };
263
+ const steps = workflow.jobs?.refresh?.steps ?? [];
264
+ const checkout = steps.find(step => step.name === 'Checkout support knowledge');
265
+ const resolveSource = steps.find(step => step.name === 'Resolve upstream change');
266
+
267
+ expect(workflow.on?.repository_dispatch?.types).toEqual(['support-knowledge-updated']);
268
+ expect(workflow.on).toHaveProperty('workflow_dispatch');
269
+ expect(checkout?.with?.ref).toBe(
270
+ "${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || 'main' }}",
271
+ );
272
+ expect(resolveSource?.env?.REQUESTED_SOURCE_COMMIT).toBe(
273
+ "${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || '' }}",
274
+ );
275
+ expect(resolveSource?.run).toBe('bash scripts/resolve-kb-refresh-source.sh');
276
+ });
277
258
- expect(workflow).toContain('support-knowledge-updated');
259
- expect(workflow).toContain('schedule:');
260
- expect(workflow).toContain('workflow_dispatch:');
278
+ test('serializes refreshes and checks complete upstream history', () => {
279
+ const workflow = Bun.YAML.parse(readFileSync(workflowPath, 'utf8')) as {
280
+ concurrency?: { group?: string; 'cancel-in-progress'?: boolean };
281
+ jobs?: Record<string, WorkflowJob>;
282
+ };
283
+ const checkout = workflow.jobs?.refresh?.steps?.find(
284
+ step => step.name === 'Checkout support knowledge',
285
+ );
286
+
287
+ expect(workflow.concurrency).toEqual({
288
+ group: 'docs-support-knowledge-refresh',
289
+ 'cancel-in-progress': true,
290
+ });
291
+ expect(checkout?.with?.['fetch-depth']).toBe(0);
292
});
293
294
test('tracks failures until both refresh and PR proposal recover', () => {