@devries-cameron20 / composio-1 / commits / 43a6c391b
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.

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', () => {