Skip to content

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 Basu43a6c391ba4c
diff --git a/.github/workflows/docs-update-kb.yml b/.github/workflows/docs-update-kb.yml
index 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 Knowledge
on:
+ # 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-knowledge
token: ${{ steps.upstream-token.outputs.token }}
+ ref: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.source_commit || 'main' }}
path: .support-knowledge
persist-credentials: false
+ fetch-depth: 0
- name: Resolve upstream change
id: source
env:
SOURCE_ROOT: ${{ github.workspace }}/.support-knowledge
HAVE_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, Bun
uses: ./.github/actions/setup-node-pnpm-bun
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 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.md
index 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.ts
index 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.sh
new file mode 100644
index 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."
+fi
diff --git a/docs/tests/static/kb-import.test.ts b/docs/tests/static/kb-import.test.ts
index 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.ts
new file mode 100644
index 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.ts
index 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', () => {