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

next
ts 173 lines 7.27 KB
Raw
1 /**
2 * Apply one KB guide change proposed by the support portal: create, rewrite, or retire a guide.
3 * The pull request it lands in is the approval.
4 *
5 * Reads a JSON request from the path given as the first argument (the docs-kb-publish workflow writes
6 * it from the repository_dispatch payload), writes the guide's definition (kb/guides/<slug>.json), its
7 * article and, for a new guide, its public source page, and validates the result with the same catalog checks the site uses.
8 * Run `bun run generate:kb` afterwards.
9 */
10 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
11 import { dirname, join, resolve } from 'node:path';
12 import { buildKbCatalog } from '@/lib/kb/catalog';
13 import { createKbArticleReader, createKbSourceReader, readKbManifest } from '@/lib/kb/repository';
14 import type { KbGuideDefinition } from '@/lib/kb/types';
15 import { z } from 'zod';
16
17 const slugSchema = z.string().min(1).max(200).regex(/^[a-z0-9-]+$/)
18 .refine(value => value.split('-').every(Boolean), 'Invalid guide slug');
19 const requestSchema = z.object({
20 action: z.enum(['upsert', 'retire']),
21 slug: slugSchema,
22 area: z.enum(['consumer', 'dashboard', 'faqs', 'mcp', 'platform', 'sdk', 'toolkits']).optional(),
23 title: z.string().optional(),
24 description: z.string().optional(),
25 body: z.string().optional(),
26 topics: z.array(z.string()).optional(),
27 tags: z.array(z.string()).optional(),
28 });
29
30 const manifestSchema = z.object({
31 schemaVersion: z.literal(2),
32 topics: z.array(z.object({
33 slug: z.string(), title: z.string(), description: z.string(), featuredRank: z.number().nullable(),
34 })),
35 guides: z.array(z.object({
36 slug: slugSchema,
37 title: z.string(),
38 description: z.string(),
39 articlePath: z.string().optional(),
40 sources: z.array(z.object({ sourcePath: z.string(), sourceHeading: z.string().nullable() })),
41 topics: z.array(z.string()),
42 tags: z.array(z.string()),
43 aliases: z.array(z.string()),
44 relatedGuides: z.array(z.string()),
45 externalResources: z.array(z.string()),
46 updatedAt: z.string(),
47 lastVerifiedAt: z.string().nullable(),
48 reviewAfter: z.string().nullable(),
49 freshness: z.enum(['evergreen', 'time-sensitive']),
50 state: z.enum(['published', 'needs-review', 'retired']),
51 featured: z.boolean(),
52 verifyIgnoreToolSlugs: z.array(z.string()).optional(),
53 managedBy: z.literal('support-portal').optional(),
54 })),
55 });
56
57 const REVIEW_DAYS = 90;
58
59 export function publishKbGuide(input: unknown, docsRoot = process.cwd(), now = new Date()): void {
60 const request = requestSchema.parse(input);
61 const root = resolve(docsRoot, 'kb');
62 const manifest = manifestSchema.parse(readKbManifest(root));
63 const today = now.toISOString().slice(0, 10);
64 const reviewAfter = new Date(now.valueOf() + REVIEW_DAYS * 86_400_000).toISOString().slice(0, 10);
65 const existing = manifest.guides.find(guide => guide.slug === request.slug);
66 const writes: [string, string][] = [];
67
68 function text(value: string | undefined, name: string): string {
69 const trimmed = (value ?? '').trim();
70 if (!trimmed) throw new Error(`${name} is required`);
71 return trimmed;
72 }
73
74 function words(values: string[] | undefined): string[] {
75 return [...new Set((values ?? []).map(value => value.trim().toLowerCase()).filter(Boolean))].sort();
76 }
77
78 if (request.action === 'retire') {
79 if (!existing) throw new Error(`No guide ${request.slug} to retire`);
80 existing.state = 'retired';
81 existing.updatedAt = today;
82 existing.managedBy = 'support-portal';
83 } else if (request.action === 'upsert') {
84 const body = text(request.body, 'body');
85 if (body.startsWith('---')) throw new Error('The article must not contain frontmatter');
86 if (/^#\s/m.test(body.split('\n')[0] ?? '')) throw new Error('The article must not start with a top-level heading');
87 const title = existing && !request.title ? existing.title : text(request.title, 'title');
88 const description = existing && !request.description ? existing.description : text(request.description, 'description');
89 const topics = request.topics !== undefined ? words(request.topics) : existing?.topics ?? [];
90 const tags = request.tags !== undefined ? words(request.tags) : existing?.tags ?? [];
91 if (!topics.length) throw new Error('At least one topic is required');
92 let guide: KbGuideDefinition;
93 if (existing) {
94 guide = existing;
95 Object.assign(guide, { title, description, topics, tags });
96 } else {
97 const area = text(request.area, 'area');
98 if (!request.slug.startsWith(`${area}-`)) throw new Error(`A ${area} guide's slug starts with ${area}-`);
99 const sourcePath = `${area}/${request.slug.slice(area.length + 1)}/public.md`;
100 if (existsSync(join(root, 'source', sourcePath))) {
101 throw new Error(`${sourcePath} already exists`);
102 }
103 writes.push([join(root, 'source', sourcePath), [
104 '---',
105 'type: "guide"',
106 `title: ${JSON.stringify(title)}`,
107 `description: ${JSON.stringify(description)}`,
108 `category: ${JSON.stringify(topics[0])}`,
109 'visibility: "public"',
110 `timestamp: ${JSON.stringify(`${today}T00:00:00Z`)}`,
111 'tags:',
112 ...(tags.length ? tags : ['support-portal']).map(tag => ` - ${JSON.stringify(tag)}`),
113 '---',
114 `# ${title}`,
115 '',
116 body,
117 '',
118 ].join('\n')]);
119 const headings = body.split('\n').flatMap(line => {
120 const heading = line.match(/^##[ \t]+(.+)$/)?.[1]?.trim();
121 return heading ? [heading] : [];
122 });
123 guide = {
124 slug: request.slug,
125 title,
126 description,
127 articlePath: `${request.slug}.md`,
128 sources: (headings.length ? headings : [null])
129 .map(sourceHeading => ({ sourcePath, sourceHeading })),
130 topics,
131 tags,
132 aliases: [],
133 relatedGuides: [],
134 externalResources: [],
135 updatedAt: today,
136 lastVerifiedAt: today,
137 reviewAfter,
138 freshness: 'evergreen',
139 state: 'published',
140 featured: false,
141 };
142 manifest.guides.push(guide);
143 }
144 guide.managedBy = 'support-portal';
145 guide.articlePath = `${request.slug}.md`;
146 Object.assign(guide, { updatedAt: today, lastVerifiedAt: today, reviewAfter, state: 'published' });
147 writes.push([join(root, 'articles', guide.articlePath), `${body}\n`]);
148 }
149
150 const pending = new Map(writes);
151 const readStaged = (base: string, read: (path: string) => string) => (path: string) =>
152 pending.get(join(root, base, path)) ?? read(path);
153 buildKbCatalog(
154 manifest,
155 readStaged('source', createKbSourceReader(join(root, 'source'))),
156 now,
157 readStaged('articles', createKbArticleReader(join(root, 'articles'))),
158 );
159
160 for (const [path, content] of writes) {
161 mkdirSync(dirname(path), { recursive: true });
162 writeFileSync(path, content);
163 }
164 const definition = manifest.guides.find(guide => guide.slug === request.slug);
165 writeFileSync(join(root, 'guides', `${request.slug}.json`), `${JSON.stringify(definition, null, 2)}\n`);
166 console.log(`${request.action === 'retire' ? 'Retired' : existing ? 'Updated' : 'Created'} ${request.slug}.`);
167 }
168
169 if (import.meta.main) {
170 const requestPath = process.argv[2];
171 if (!requestPath) throw new Error('Usage: bun scripts/publish-kb-guide.ts <request.json>');
172 publishKbGuide(JSON.parse(readFileSync(requestPath, 'utf8')));
173 }