Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
ci(docs): refresh support knowledge from dispatches
Soham Basu43a6c391ba4c
diff --git a/.github/workflows/docs-update-kb.yml b/.github/workflows/docs-update-kb.ymlindex eff834189..d962d537b 100644--- a/.github/workflows/docs-update-kb.yml+++ b/.github/workflows/docs-update-kb.yml@@ -1,6 +1,8 @@name: Docs - Update Support Knowledgeon:+ # Dispatch is the primary path; this six-hour run reconciles missed events and+ # repairs semantic artifacts made stale by docs-side content changes.schedule:- cron: '17 */6 * * *'repository_dispatch:@@ -10,6 +12,10 @@ on:permissions:contents: read+concurrency:+ group: docs-support-knowledge-refresh+ cancel-in-progress: true+jobs:refresh:runs-on: ubuntu-latest@@ -49,31 +55,19 @@ jobs:with:repository: ComposioHQ/support-knowledgetoken: ${{ steps.upstream-token.outputs.token }}+ ref: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || 'main' }}path: .support-knowledgepersist-credentials: false+ fetch-depth: 0- name: Resolve upstream changeid: sourceenv:SOURCE_ROOT: ${{ github.workspace }}/.support-knowledgeHAVE_UPSTREAM: ${{ steps.upstream-token.outcome == 'success' }}- run: |- current_commit=$(jq -r '.source.commit' kb/manifest.json)- echo "commit=$current_commit" >> "$GITHUB_OUTPUT"- if [ "$HAVE_UPSTREAM" != "true" ]; then- echo "upstream_changed=false" >> "$GITHUB_OUTPUT"- echo "No upstream token; skipping support-knowledge sync check and treating upstream as unchanged."- exit 0- fi- source_commit=$(git -C "$SOURCE_ROOT" rev-parse HEAD)- echo "commit=$source_commit" >> "$GITHUB_OUTPUT"- if [ "$source_commit" = "$current_commit" ]; then- echo "upstream_changed=false" >> "$GITHUB_OUTPUT"- echo "Support knowledge is already current at $source_commit."- else- echo "upstream_changed=true" >> "$GITHUB_OUTPUT"- echo "Refreshing support knowledge from $current_commit to $source_commit."- fi+ EVENT_NAME: ${{ github.event_name }}+ REQUESTED_SOURCE_COMMIT: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || '' }}+ run: bash scripts/resolve-kb-refresh-source.sh- name: Setup Node.js, pnpm, Bunuses: ./.github/actions/setup-node-pnpm-bundiff --git a/docs/decisions/README.md b/docs/decisions/README.mdindex eb54bbbdb..8934f1ef3 100644--- a/docs/decisions/README.md+++ b/docs/decisions/README.md@@ -7,8 +7,8 @@ Read these when a docs change touches an existing architecture, generated-data p- `examples.md` - cookbook/examples restructuring plan.- `feedback.md` - feedback collection system.- `llm-guardrails.md` - LLM guardrail injection for markdown endpoints.-- `public-knowledge-base.md` - public support publication, unified search, and- Composio For You snapshot rules.+- `public-knowledge-base.md` - event-driven public support publication, unified+ search, and Composio For You snapshot rules.- `toolkit-page-availability.md` - docs-sync permissions, optional KB isolation,and snapshot-miss toolkit page fallback.- `toolkits.md` - toolkit page data and rendering decisions.diff --git a/docs/decisions/public-knowledge-base.md b/docs/decisions/public-knowledge-base.mdindex 0078ae24c..021d1b678 100644--- a/docs/decisions/public-knowledge-base.md+++ b/docs/decisions/public-knowledge-base.md@@ -1,288 +1,83 @@# Public Knowledge Base-## Decision--Host the Composio public knowledge base in the existing documentation site at-`docs.composio.dev/kb`. Add **Knowledge Base** as a top-level navigation item-between Docs and Examples.--`ComposioHQ/support-knowledge` is the canonical authoring repository for-support-specific KB prose. The docs site contains a pinned, manually reviewed-publication snapshot with source provenance and freshness metadata. A pull-only-importer validates an explicit local checkout and atomically refreshes that-snapshot; it never writes upstream. Canonical product documentation remains in-the docs repository, including the reviewed Composio For You client snapshot-defined below.--The `/kb/search` experience is a unified public-support search, not a KB-only-index. Every current public docs, KB, toolkit, example, reference, and changelog-record is eligible, with source-aware retrieval and ranking. Keyword search is-the fast path across the full corpus; semantic retrieval is reserved for-editorial docs and KB prose when lexical retrieval does not produce a strong-match.--## Context--Customer-shareable support knowledge is classified in `support-knowledge` as-either `public` or `customer-safe`. Only `public.md` leaves are eligible for the-hosted site, public search artifacts, and public agent skills. The first-implementation prototype rendered two reviewed guides inside the marketing-`landing` repository. That prototype proved the-publication gates and user experience, but the docs application is a better-runtime because it already provides:--- Fumadocs content collections and article layouts;-- navigation, responsive sidebars, and search;-- Algolia indexing with a local Fumadocs fallback;-- feedback collection, sitemap generation, and LLM-readable endpoints;-- a public GitHub repository and an established documentation review process.--Keeping the KB in `landing` would duplicate those systems and split technical-support content from the documentation audience.--Three locations were considered:--1. **Docs application (chosen):** native documentation UX and discovery with a- small amount of collection and route work.-2. **Marketing application:** strongest main-domain ownership, but duplicates- docs rendering, search, feedback, and discovery infrastructure.-3. **Separate repository or subdomain:** independent deployment, but creates a- third public content surface and the largest maintenance burden.--## Architecture--The system has three distinct responsibilities:--1. **Authoring:** support maintainers edit classified leaves in- `support-knowledge`; its validation, freshness, manifest, and human review- gates remain authoritative.-2. **Publication:** a maintainer runs the pull-only importer against an explicit- source checkout and commit. The staged snapshot records source provenance,- public routes, content hashes, verification dates, and review deadlines, and- replaces the previous valid snapshot only after validation succeeds.-3. **Rendering:** the `docs/` Fumadocs application renders only published pages- and includes them in navigation, search, sitemap, feedback, and LLM outputs.--The initial release keeps invocation and review manual. It automates the-mechanical copy so classification enforcement is reproducible, but it does not-fetch private repositories at application runtime, open pull requests, publish,-or write back to `support-knowledge`.--## Content Model--Every reviewed `public.md` file is eligible for the public corpus, but a source-file is not necessarily one web page. A self-contained level-two problem or-question can become an individual guide. Structural headings stay with their-parent guide.--The publication layer records:--- stable slug and aliases;-- title and description;-- source repository, commit, path, and selected heading;-- topics, tags, and related resources;-- updated and last-verified dates;-- freshness class and review deadline;-- `published`, `needs-review`, or `retired` state.--The docs-site snapshot imports every public leaf from a verified-`ComposioHQ/support-knowledge` commit. Customer-safe leaves remain excluded.-The manifest records both the exact commit and a deterministic hash of the-vendored public source bytes.--### Composio For You--Client setup content is maintained in the dashboard repository rather than-`support-knowledge`. The initial For You publication takes a one-time snapshot-of the client definitions and public-safe onboarding media at dashboard commit-`269ab875f5c2fb0f40b312328812e7cc068faaa9` and reconciles the canonical-`/docs/composio-connect` page with that snapshot.--The docs page, not a duplicated KB page, remains canonical for client setup.-Client sections use stable anchors and searchable aliases for renamed or-closely related clients. The snapshot contains placeholders and public setup-instructions only; personalized keys, sessions, connection state, logs,-organization identifiers, and account-specific URLs remain excluded.--Existing For You-tagged KB guides remain canonical for support-specific facts-and troubleshooting. New KB guides are added only for an identified knowledge-gap that is not already answered by current docs or a published KB guide.-Volatile pricing, entitlement, and security claims require an authoritative-public source and are not copied from dashboard FAQ prose by default.--### Identifier URLs--KB prose cites machine identifiers that happen to look like URLs: OAuth-scope URIs such as `https://www.googleapis.com/auth/…` and API surface roots-such as `https://api.ahrefs.com/v3`. These are not documents; fetching them-404s by design, so they can never survive the nightly external-link sweep as-links. The generation layer therefore demotes bare citations and `<url>`-autolinks of these two shapes to inline code spans. Explicit markdown links-keep their authored form — if one points at an identifier URL, the nightly-sweep flags it for an upstream fix instead of the pipeline silently rewriting-navigation the author wrote.--## Routes and Navigation--- `/kb` is the knowledge-base landing page.-- `/kb/<topic>` is a topic landing page when a topic has multiple guides.-- `/kb/<topic>/<guide-slug>` is the canonical guide route.-- aliases permanently redirect to the canonical route.--The header order is Docs, Knowledge Base, Examples, Toolkits, Reference. KB-pages use native Fumadocs layouts and components rather than maintaining a-second design system. The KB landing page may use a small custom MDX landing-page for search, featured guides, recently verified guides, and topic cards.--The marketing site may later redirect `composio.dev/kb` to-`docs.composio.dev/kb`; the unmerged marketing prototype does not establish a-public URL contract.--## Search and Discovery--`/kb/search` searches every current public record in the existing Algolia index:-docs, KB guides, toolkits, examples, current reference, and changelog. Legacy-reference records are eligible only for an exact identity match when no current-reference record answers the same query. Search results always link to the-canonical page or section; the search layer does not generate an answer or-create redirect-only KB copies of docs pages.--Retrieval is deliberately asymmetric by source:--1. Run keyword retrieval across the complete public index.-2. Treat an exact normalized title, keyword, slug, toolkit slug, tool slug, or- current reference identity as a strong lexical match and return it without- waiting for an embedding request.-3. When lexical confidence is weak, embed the query and search a checked-in- OpenAI `text-embedding-3-small` artifact containing public KB and docs prose.-4. Fuse the editorial semantic candidates with the full-corpus keyword- candidates using deterministic Reciprocal Rank Fusion, while preserving- exact identifier matches.--Natural-language support questions therefore favor KB and docs prose, while-exact toolkit, action, endpoint, and schema queries favor toolkit or reference-records. Toolkits, generated reference, examples, and changelog are not added-to the semantic artifact: their structured identifiers work better with-lexical retrieval, and embedding them would increase artifact size and scan-time without improving the common support path. This corpus does not justify-Algolia NeuralSearch, a vector database, or an approximate index.--The existing global Docs search remains keyword-only. If query embedding or the-semantic artifact is unavailable, `/kb/search` returns the complete keyword-result set. If Algolia is unavailable, it uses the local lexical index and may-combine those results with editorial semantic candidates. No failure path-widens discovery beyond records already classified for public indexing.--The initial `/kb/search?q=...` request runs through a shared server-side search-service during page rendering. The API route calls the same service for direct-agent access and subsequent client-side requests. The page hydrates with the-server result instead of waiting for React hydration before starting its first-search, avoiding a page-load-to-API waterfall without maintaining two ranking-implementations.--Preview deployments must represent the branch under review even though the-shared Algolia index synchronizes only from `next`. In Vercel preview and local-development, `/kb/search` overlays module-cached lexical results from the-branch's bundled docs and KB collections on the shared Algolia candidates.-Branch-local records replace shared records with the same canonical URL;-toolkits, examples, reference, and changelog continue to come from the shared-index. Production uses the synchronized Algolia corpus without this overlay.-Overlay failure falls back to the shared index and is reported as retrieval-degradation; it does not require a branch-specific Algolia index or database.--Semantic requests retain a configurable three-second safety timeout, an-eight-request concurrency ceiling, a 60-request-per-minute client budget, and a-generous 600-request-per-minute process ceiling. The timeout is a worst-case-guardrail, not a delay imposed on strong lexical searches. Hitting any semantic-guardrail is logged and returns keyword results rather than blocking search.--Mixed result cards show a concise source label such as Documentation, Knowledge-Base, Toolkit, Example, or API Reference. They do not show the redundant-`Guide` badge. Search analytics record total duration, keyword duration,-semantic duration when invoked, retrieval mode, result source types, clicked-source type and position, zero-result searches, and guardrail degradation.--The same read-only unified search and canonical-page contract is available to-the existing public `composio` skill as a fallback after its primary-documentation and CLI sources. The skill uses the unified endpoint rather than-hard-coding a KB-only filter. It retrieves evidence and lets its host agent-answer; it does not contain a duplicate fact corpus or run its own generation-service.-Authenticated retrieval of `customer-safe` content is a separate future design.--Published KB pages are also included in:--- the XML sitemap;-- `llms.txt`, `llms-full.txt`, and scoped `llms.mdx` routes;-- link validation;-- the existing feedback flow.--`needs-review` and retired entries are excluded from routes and every discovery-surface.--## Freshness and Privacy--Publication fails when a published entry:--- is not explicitly public;-- contains known private-data markers;-- has no verification or review deadline;-- has an expired review deadline;-- references an unknown topic, related guide, source section, or alias;-- collides with another canonical route or alias.--Default review windows remain 180 days for evergreen guidance, 30 days for-provider or OAuth setup, and 7 days for active incidents. These are publication-defaults in the docs application, not changes to the canonical source schema.--Guide pages show the last-verified date. Time-sensitive material is held by-default until its live behavior has been rechecked.--## Failure Handling--The KB validator runs before docs builds and reports the source path and reason-for invalid content. A failed or stale entry must not be silently omitted from-a supposedly successful publication. External resource failures must not make-the local KB unavailable; they may degrade to ordinary links.--## Testing and Verification--The implementation is complete when:--- parser and publication-gate unit tests pass;-- the importer verifies the upstream repository and exact checked-out commit;-- the validator reports the expected public guide count and no private leaves;-- `/kb`, topic pages, guide pages, and aliases render in a local docs build;-- held content is absent from routes, search, sitemap, and LLM outputs;-- current For You clients in the pinned dashboard snapshot have canonical,- searchable setup sections with no personalized values;-- representative natural-language, client-setup, toolkit, exact action-slug,- and API-reference queries return the expected source class without asserting- mutable prose claims;-- the initial search result is present in the server-rendered response and does- not depend on a post-hydration request;-- preview search prefers branch-local docs and KB records over shared Algolia- versions with the same canonical URL, while production does not apply the- overlay;-- strong lexical queries do not invoke semantic retrieval, while weak queries- can fuse editorial semantic results with full-corpus keyword results;-- semantic timeout, rate, capacity, artifact, and embedding failures return- keyword results and emit the expected analytics category;-- existing docs tests, type checks, lint, link validation, and production build- pass;-- the header exposes Knowledge Base in desktop and mobile navigation.--## Consequences--- The unmerged `landing` KB branch becomes a prototype, not the production- destination. Reusable publication logic and tests are ported; custom page- chrome is not.-- Public KB prose continues to be maintained in `support-knowledge`.-- Canonical For You client setup lives in docs from a reviewed, one-time- dashboard snapshot; automatic synchronization remains out of scope.-- The docs repository owns the deployed snapshot, route metadata, validation,- and presentation.-- No new repository, subdomain, or synchronization service is introduced.-- The hosted UI, API, and agent skills share one public-only, multi-source- retrieval contract; customer-safe and live operational evidence remain- separate boundaries.+## Purpose and ownership++- The public knowledge base is hosted with the documentation at+ `docs.composio.dev/kb`.+- `ComposioHQ/support-knowledge` is the source of support-specific public prose.+- The docs repository owns the reviewed publication snapshot, routes, search+ integration, and presentation.+- Product documentation remains canonical for product concepts and workflows;+ KB guides cover support questions and troubleshooting gaps.++## Content boundaries++- Only content explicitly classified for public use is eligible for import.+- Non-public classifications and account-specific information must never enter+ the snapshot, generated pages, search indexes, or agent-readable outputs.+- New guides should address a real knowledge gap rather than duplicate an+ existing documentation or KB page.+- Time-sensitive claims require an authoritative public source and current+ verification.+- A source document may produce multiple focused guides. Stable slugs and+ aliases preserve published URLs as the source evolves.++## Publication and maintenance++- A source change triggers a refresh after it reaches the source repository's+ main branch; periodic reconciliation catches missed events.+- The refresh validates the repository, source commit, and mainline ancestry+ before importing any content.+- Delayed events resolve to the newest mainline commit that changed public+ content. Non-public or repository-maintenance changes do not advance the+ published snapshot.+- Refreshes are serialized so overlapping runs cannot race.+- The importer treats upstream files as data, never executes upstream code, and+ never writes back to the source repository.+- Import, page generation, search-artifact generation, and validation complete+ before an automated refresh pull request is opened.+- A human review and merge remains the final publication gate.++## Rendering and discovery++- Published guides appear under `/kb` and use the docs site's existing+ navigation, layout, feedback, and canonical-link behavior.+- Knowledge search covers public docs, KB guides, toolkits, examples, current+ reference pages, and changelog entries.+- Search uses keyword matching first and semantic retrieval for public docs and+ KB prose when keyword confidence is weak.+- Semantic-search failures fall back to public keyword results; failure must+ never broaden the eligible corpus.+- Published guides are included in the sitemap and agent-readable documentation+ outputs.+- Content awaiting review or marked as retired is excluded from routes and all+ discovery surfaces.++## Freshness and safety++- The manifest records source provenance, a deterministic content hash,+ canonical routes, verification dates, review deadlines, and publication+ state.+- Publication rejects content that is not explicitly public, contains known+ private-data markers, is stale, has broken references, or conflicts with an+ existing route.+- Time-sensitive content stays unpublished until it has been reverified.+- The running docs application reads only the checked-in public snapshot; it+ does not access the source repository at runtime.++## Failure handling++- A candidate snapshot is validated before it replaces the current snapshot.+- A failed validation or import leaves the last valid public snapshot intact+ and surfaces the failure for follow-up.+- Invalid or stale guides must not be silently omitted from an otherwise+ successful publication.+- External-service failures may reduce search quality or link enrichment, but+ they must not make private content eligible.++## Verification++- Run `bun run test`, `bun run types:check`, `bun run lint`,+ `bun run lint:links`, and `bun run build` from `docs/`.+- Verify generated KB pages and the semantic artifact are current before+ merging a refresh.diff --git a/docs/lib/kb/support-knowledge.ts b/docs/lib/kb/support-knowledge.tsindex c38b458ee..b2bfaf530 100644--- a/docs/lib/kb/support-knowledge.ts+++ b/docs/lib/kb/support-knowledge.ts@@ -537,6 +537,14 @@ export function writeSupportKnowledgeSnapshot(input: {}cpSync(externalSources, join(stagedRoot, 'external-sources'), { recursive: true });}+ const semanticIndex = join(targetRoot, 'semantic-index.json');+ if (existsSync(semanticIndex)) {+ const semanticIndexStats = lstatSync(semanticIndex);+ if (semanticIndexStats.isSymbolicLink() || !semanticIndexStats.isFile()) {+ throw new Error('KB semantic-index.json must be a regular file');+ }+ cpSync(semanticIndex, join(stagedRoot, 'semantic-index.json'));+ }input.validate(stagedRoot);if (existsSync(targetRoot)) {renameSync(targetRoot, backupRoot);diff --git a/docs/scripts/resolve-kb-refresh-source.sh b/docs/scripts/resolve-kb-refresh-source.shnew file mode 100644index 000000000..3c34807df--- /dev/null+++ b/docs/scripts/resolve-kb-refresh-source.sh@@ -0,0 +1,61 @@+#!/usr/bin/env bash++set -euo pipefail++current_commit=$(jq -r '.source.commit' kb/manifest.json)+echo "commit=$current_commit" >> "$GITHUB_OUTPUT"++if [ "$EVENT_NAME" = "repository_dispatch" ] && [ -z "$REQUESTED_SOURCE_COMMIT" ]; then+ echo "::error::Dispatched support knowledge refresh is missing source_commit."+ exit 1+fi++if [ "$HAVE_UPSTREAM" != "true" ]; then+ if [ "$EVENT_NAME" = "repository_dispatch" ]; then+ echo "::error::Cannot process a dispatched support knowledge refresh without an upstream token."+ exit 1+ fi+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"+ echo "No upstream token; skipping support-knowledge sync check and treating upstream as unchanged."+ exit 0+fi++checkout_commit=$(git -C "$SOURCE_ROOT" rev-parse HEAD)+if [ -n "$REQUESTED_SOURCE_COMMIT" ] && [ "$checkout_commit" != "$REQUESTED_SOURCE_COMMIT" ]; then+ echo "::error::Support knowledge HEAD $checkout_commit does not match dispatched commit $REQUESTED_SOURCE_COMMIT."+ exit 1+fi++if ! upstream_tip=$(git -C "$SOURCE_ROOT" rev-parse --verify refs/remotes/origin/main 2>/dev/null); then+ echo "::error::Cannot resolve the support knowledge main branch."+ exit 1+fi++if [ -n "$REQUESTED_SOURCE_COMMIT" ] && \+ ! git -C "$SOURCE_ROOT" merge-base --is-ancestor "$REQUESTED_SOURCE_COMMIT" "$upstream_tip"; then+ echo "::error::Dispatched support knowledge commit $REQUESTED_SOURCE_COMMIT is not on upstream main."+ exit 1+fi++if [ "$upstream_tip" = "$current_commit" ]; then+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"+ echo "Support knowledge is already current at $upstream_tip."+elif ! git -C "$SOURCE_ROOT" cat-file -e "$current_commit^{commit}" 2>/dev/null; then+ echo "::error::Published support knowledge commit $current_commit is unavailable in the upstream history."+ exit 1+elif ! git -C "$SOURCE_ROOT" merge-base --is-ancestor "$current_commit" "$upstream_tip"; then+ echo "::error::Published support knowledge commit $current_commit is not on upstream main."+ exit 1+elif ! source_commit=$(git -C "$SOURCE_ROOT" log --first-parent -1 --format=%H \+ "$current_commit..$upstream_tip" -- ':(glob)**/public.md'); then+ echo "::error::Cannot inspect public support knowledge history."+ exit 1+elif [ -z "$source_commit" ]; then+ echo "upstream_changed=false" >> "$GITHUB_OUTPUT"+ echo "No public support knowledge changed between $current_commit and $upstream_tip."+else+ git -C "$SOURCE_ROOT" checkout --detach "$source_commit"+ echo "commit=$source_commit" >> "$GITHUB_OUTPUT"+ echo "upstream_changed=true" >> "$GITHUB_OUTPUT"+ echo "Refreshing support knowledge from $current_commit to $source_commit."+fidiff --git a/docs/tests/static/kb-import.test.ts b/docs/tests/static/kb-import.test.tsindex c5b8e6dbc..771b4c0df 100644--- a/docs/tests/static/kb-import.test.ts+++ b/docs/tests/static/kb-import.test.ts@@ -398,6 +398,11 @@ describe('support-knowledge snapshot import', () => {'{"preserve":true}\n','utf8',);+ writeFileSync(+ join(targetRoot, 'semantic-index.json'),+ '{"records":[{"id":"existing-vector"}]}\n',+ 'utf8',+ );expect(() => writeSupportKnowledgeSnapshot({snapshot,@@ -421,5 +426,8 @@ describe('support-knowledge snapshot import', () => {join(targetRoot, 'external-sources/auth-guides.json'),'utf8',)).toBe('{"preserve":true}\n');+ expect(readFileSync(join(targetRoot, 'semantic-index.json'), 'utf8')).toBe(+ '{"records":[{"id":"existing-vector"}]}\n',+ );});});diff --git a/docs/tests/static/kb-resolve-refresh-source.test.ts b/docs/tests/static/kb-resolve-refresh-source.test.tsnew file mode 100644index 000000000..fff989e89--- /dev/null+++ b/docs/tests/static/kb-resolve-refresh-source.test.ts@@ -0,0 +1,176 @@+import { describe, expect, test } from 'bun:test';+import { spawnSync } from 'node:child_process';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';++const resolverPath = resolve(process.cwd(), 'scripts', 'resolve-kb-refresh-source.sh');++function git(root: string, ...args: string[]): string {+ const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });+ if (result.status !== 0) throw new Error(result.stderr);+ return result.stdout.trim();+}++function runResolver(+ cwd: string,+ env: Record<string, string>,+): { status: number | null; output: string; stdout: string; stderr: string } {+ const outputPath = join(cwd, 'github-output.txt');+ writeFileSync(outputPath, '', 'utf8');+ const result = spawnSync('bash', [resolverPath], {+ cwd,+ encoding: 'utf8',+ env: { ...process.env, ...env, GITHUB_OUTPUT: outputPath },+ });+ return {+ status: result.status,+ output: readFileSync(outputPath, 'utf8'),+ stdout: result.stdout,+ stderr: result.stderr,+ };+}++function createFixture(): {+ root: string;+ sourceRoot: string;+ docsRoot: string;+ currentCommit: string;+} {+ const root = mkdtempSync(join(tmpdir(), 'kb-resolve-source-'));+ const sourceRoot = join(root, 'support-knowledge');+ const docsRoot = join(root, 'docs');+ mkdirSync(join(sourceRoot, 'toolkits', 'github'), { recursive: true });+ mkdirSync(join(docsRoot, 'kb'), { recursive: true });++ git(sourceRoot, 'init');+ git(sourceRoot, 'config', 'user.name', 'KB Workflow Test');+ git(sourceRoot, 'config', 'user.email', '[email protected]');+ writeFileSync(join(sourceRoot, 'toolkits/github/public.md'), 'public v1\n', 'utf8');+ writeFileSync(+ join(sourceRoot, 'toolkits/github/customer-safe.md'),+ 'customer-safe v1\n',+ 'utf8',+ );+ git(sourceRoot, 'add', '.');+ git(sourceRoot, 'commit', '-m', 'initial knowledge');+ const currentCommit = git(sourceRoot, 'rev-parse', 'HEAD');+ writeFileSync(+ join(docsRoot, 'kb/manifest.json'),+ `${JSON.stringify({ source: { commit: currentCommit } })}\n`,+ 'utf8',+ );++ return { root, sourceRoot, docsRoot, currentCommit };+}++describe('support knowledge refresh source resolver', () => {+ test('ignores customer-safe-only changes and coalesces delayed events to the newest public change', () => {+ const fixture = createFixture();++ try {+ writeFileSync(+ join(fixture.sourceRoot, 'toolkits/github/customer-safe.md'),+ 'customer-safe v2\n',+ 'utf8',+ );+ git(fixture.sourceRoot, 'add', '.');+ git(fixture.sourceRoot, 'commit', '-m', 'customer-safe only');+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');++ const privateOnly = runResolver(fixture.docsRoot, {+ SOURCE_ROOT: fixture.sourceRoot,+ HAVE_UPSTREAM: 'true',+ EVENT_NAME: 'schedule',+ REQUESTED_SOURCE_COMMIT: '',+ });+ expect(privateOnly.status).toBe(0);+ expect(privateOnly.output).toBe(+ `commit=${fixture.currentCommit}\nupstream_changed=false\n`,+ );++ writeFileSync(+ join(fixture.sourceRoot, 'toolkits/github/public.md'),+ 'public v2\n',+ 'utf8',+ );+ git(fixture.sourceRoot, 'add', '.');+ git(fixture.sourceRoot, 'commit', '-m', 'public knowledge');+ const publicCommit = git(fixture.sourceRoot, 'rev-parse', 'HEAD');+ writeFileSync(+ join(fixture.sourceRoot, 'toolkits/github/customer-safe.md'),+ 'customer-safe v3\n',+ 'utf8',+ );+ git(fixture.sourceRoot, 'add', '.');+ git(fixture.sourceRoot, 'commit', '-m', 'customer-safe after public knowledge');+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');++ const publicThenPrivate = runResolver(fixture.docsRoot, {+ SOURCE_ROOT: fixture.sourceRoot,+ HAVE_UPSTREAM: 'true',+ EVENT_NAME: 'schedule',+ REQUESTED_SOURCE_COMMIT: '',+ });+ expect(publicThenPrivate.status).toBe(0);+ expect(publicThenPrivate.output).toBe(+ `commit=${fixture.currentCommit}\ncommit=${publicCommit}\nupstream_changed=true\n`,+ );++ writeFileSync(+ join(fixture.sourceRoot, 'toolkits/github/public.md'),+ 'public v3\n',+ 'utf8',+ );+ git(fixture.sourceRoot, 'add', '.');+ git(fixture.sourceRoot, 'commit', '-m', 'newer public knowledge');+ const newestPublicCommit = git(fixture.sourceRoot, 'rev-parse', 'HEAD');+ git(fixture.sourceRoot, 'update-ref', 'refs/remotes/origin/main', 'HEAD');+ git(fixture.sourceRoot, 'checkout', '--detach', publicCommit);++ const delayedDispatch = runResolver(fixture.docsRoot, {+ SOURCE_ROOT: fixture.sourceRoot,+ HAVE_UPSTREAM: 'true',+ EVENT_NAME: 'repository_dispatch',+ REQUESTED_SOURCE_COMMIT: publicCommit,+ });+ expect(delayedDispatch.status).toBe(0);+ expect(delayedDispatch.output).toBe(+ `commit=${fixture.currentCommit}\ncommit=${newestPublicCommit}\nupstream_changed=true\n`,+ );+ expect(git(fixture.sourceRoot, 'rev-parse', 'HEAD')).toBe(newestPublicCommit);+ } finally {+ rmSync(fixture.root, { recursive: true, force: true });+ }+ });++ test('rejects dispatched refreshes without a pinned commit or upstream access', () => {+ const fixture = createFixture();++ try {+ const unpinned = runResolver(fixture.docsRoot, {+ SOURCE_ROOT: fixture.sourceRoot,+ HAVE_UPSTREAM: 'true',+ EVENT_NAME: 'repository_dispatch',+ REQUESTED_SOURCE_COMMIT: '',+ });+ expect(unpinned.status).toBe(1);+ expect(unpinned.stdout).toContain(+ 'Dispatched support knowledge refresh is missing source_commit.',+ );++ const unreadable = runResolver(fixture.docsRoot, {+ SOURCE_ROOT: fixture.sourceRoot,+ HAVE_UPSTREAM: 'false',+ EVENT_NAME: 'repository_dispatch',+ REQUESTED_SOURCE_COMMIT: fixture.currentCommit,+ });+ expect(unreadable.status).toBe(1);+ expect(unreadable.stdout).toContain(+ 'Cannot process a dispatched support knowledge refresh without an upstream token.',+ );+ } finally {+ rmSync(fixture.root, { recursive: true, force: true });+ }+ });+});diff --git a/docs/tests/static/kb-update-workflow.test.ts b/docs/tests/static/kb-update-workflow.test.tsindex 6bf18a5c9..787f73965 100644--- a/docs/tests/static/kb-update-workflow.test.ts+++ b/docs/tests/static/kb-update-workflow.test.ts@@ -252,12 +252,43 @@ echo "head_ref=$live_head_ref" >> "$GITHUB_OUTPUT"`);expect(workflow).toContain('actions/download-artifact@');});- test('can refresh immediately or discover upstream changes on a schedule', () => {- const workflow = readFileSync(workflowPath, 'utf8');+ test('passes dispatched source context to the tested resolver script', () => {+ const workflow = Bun.YAML.parse(readFileSync(workflowPath, 'utf8')) as {+ on?: {+ repository_dispatch?: { types?: string[] };+ workflow_dispatch?: unknown;+ };+ jobs?: Record<string, WorkflowJob>;+ };+ const steps = workflow.jobs?.refresh?.steps ?? [];+ const checkout = steps.find(step => step.name === 'Checkout support knowledge');+ const resolveSource = steps.find(step => step.name === 'Resolve upstream change');++ expect(workflow.on?.repository_dispatch?.types).toEqual(['support-knowledge-updated']);+ expect(workflow.on).toHaveProperty('workflow_dispatch');+ expect(checkout?.with?.ref).toBe(+ "${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || 'main' }}",+ );+ expect(resolveSource?.env?.REQUESTED_SOURCE_COMMIT).toBe(+ "${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || '' }}",+ );+ expect(resolveSource?.run).toBe('bash scripts/resolve-kb-refresh-source.sh');+ });- expect(workflow).toContain('support-knowledge-updated');- expect(workflow).toContain('schedule:');- expect(workflow).toContain('workflow_dispatch:');+ test('serializes refreshes and checks complete upstream history', () => {+ const workflow = Bun.YAML.parse(readFileSync(workflowPath, 'utf8')) as {+ concurrency?: { group?: string; 'cancel-in-progress'?: boolean };+ jobs?: Record<string, WorkflowJob>;+ };+ const checkout = workflow.jobs?.refresh?.steps?.find(+ step => step.name === 'Checkout support knowledge',+ );++ expect(workflow.concurrency).toEqual({+ group: 'docs-support-knowledge-refresh',+ 'cancel-in-progress': true,+ });+ expect(checkout?.with?.['fetch-depth']).toBe(0);});test('tracks failures until both refresh and PR proposal recover', () => {