Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 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 | } |