Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'; |
| 2 | import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'; |
| 3 | import { buildKbCatalog } from './catalog'; |
| 4 | import type { KbCatalog, KbGuide, KbGuideDefinition, KbManifest } from './types'; |
| 5 | |
| 6 | const KB_ROOT = join(process.cwd(), 'kb'); |
| 7 | const KB_ARTICLES_ROOT = resolve(KB_ROOT, 'articles'); |
| 8 | let cachedCatalog: KbCatalog | null = null; |
| 9 | |
| 10 | /** |
| 11 | * Read the manifest (`kb/manifest.json`: schema version and topics) plus one |
| 12 | * definition per guide (`kb/guides/<slug>.json`). Guides live in their own files |
| 13 | * so publication PRs for different guides never touch the same file. |
| 14 | */ |
| 15 | export function readKbManifest(kbRoot = KB_ROOT): KbManifest { |
| 16 | const base = JSON.parse(readFileSync(join(kbRoot, 'manifest.json'), 'utf8')) as Omit<KbManifest, 'guides'>; |
| 17 | const guidesRoot = join(kbRoot, 'guides'); |
| 18 | const guides = readdirSync(guidesRoot) |
| 19 | .filter(name => name.endsWith('.json')) |
| 20 | .sort() |
| 21 | .map(name => { |
| 22 | const guide = JSON.parse(readFileSync(join(guidesRoot, name), 'utf8')) as KbGuideDefinition; |
| 23 | if (`${guide.slug}.json` !== name) throw new Error(`kb/guides/${name} defines ${guide.slug}`); |
| 24 | return guide; |
| 25 | }); |
| 26 | return { ...base, guides }; |
| 27 | } |
| 28 | |
| 29 | export function createKbArticleReader(articlesRoot: string): (articlePath: string) => string { |
| 30 | return articlePath => { |
| 31 | const articlesRootStats = lstatSync(articlesRoot); |
| 32 | if (articlesRootStats.isSymbolicLink()) { |
| 33 | throw new Error(`KB articles root must not be a symbolic link: ${articlesRoot}`); |
| 34 | } |
| 35 | if (!articlesRootStats.isDirectory()) { |
| 36 | throw new Error(`KB articles root must be a directory: ${articlesRoot}`); |
| 37 | } |
| 38 | |
| 39 | const realArticlesRoot = realpathSync(articlesRoot); |
| 40 | const target = resolve(realArticlesRoot, articlePath); |
| 41 | const pathFromRoot = relative(realArticlesRoot, target); |
| 42 | if ( |
| 43 | pathFromRoot === '' || |
| 44 | pathFromRoot === '..' || |
| 45 | pathFromRoot.startsWith(`..${sep}`) || |
| 46 | isAbsolute(pathFromRoot) |
| 47 | ) { |
| 48 | throw new Error(`KB article path escapes articles directory: ${articlePath}`); |
| 49 | } |
| 50 | if (lstatSync(target).isSymbolicLink()) { |
| 51 | throw new Error(`KB article must not be a symbolic link: ${articlePath}`); |
| 52 | } |
| 53 | |
| 54 | const realTarget = realpathSync(target); |
| 55 | if (dirname(realTarget) !== realArticlesRoot || !statSync(realTarget).isFile()) { |
| 56 | throw new Error( |
| 57 | `KB article must be a regular file directly under articles directory: ${articlePath}` |
| 58 | ); |
| 59 | } |
| 60 | return readFileSync(realTarget, 'utf8'); |
| 61 | }; |
| 62 | } |
| 63 | |
| 64 | export function createKbSourceReader(sourceRoot: string): (sourcePath: string) => string { |
| 65 | return sourcePath => { |
| 66 | const sourceRootStats = lstatSync(sourceRoot); |
| 67 | if (sourceRootStats.isSymbolicLink()) { |
| 68 | throw new Error(`KB source root must not be a symbolic link: ${sourceRoot}`); |
| 69 | } |
| 70 | if (!sourceRootStats.isDirectory()) { |
| 71 | throw new Error(`KB source root must be a directory: ${sourceRoot}`); |
| 72 | } |
| 73 | |
| 74 | const realSourceRoot = realpathSync(sourceRoot); |
| 75 | const target = resolve(realSourceRoot, sourcePath); |
| 76 | const pathFromRoot = relative(realSourceRoot, target); |
| 77 | if ( |
| 78 | pathFromRoot === '' || |
| 79 | pathFromRoot === '..' || |
| 80 | pathFromRoot.startsWith(`..${sep}`) || |
| 81 | isAbsolute(pathFromRoot) |
| 82 | ) { |
| 83 | throw new Error(`KB source path escapes source directory: ${sourcePath}`); |
| 84 | } |
| 85 | if (lstatSync(target).isSymbolicLink()) { |
| 86 | throw new Error(`KB source must not be a symbolic link: ${sourcePath}`); |
| 87 | } |
| 88 | |
| 89 | const realTarget = realpathSync(target); |
| 90 | const realPathFromRoot = relative(realSourceRoot, realTarget); |
| 91 | if ( |
| 92 | realPathFromRoot === '' || |
| 93 | realPathFromRoot === '..' || |
| 94 | realPathFromRoot.startsWith(`..${sep}`) || |
| 95 | isAbsolute(realPathFromRoot) || |
| 96 | !statSync(realTarget).isFile() |
| 97 | ) { |
| 98 | throw new Error(`KB source must be a regular file inside source directory: ${sourcePath}`); |
| 99 | } |
| 100 | return readFileSync(realTarget, 'utf8'); |
| 101 | }; |
| 102 | } |
| 103 | |
| 104 | export function getKbCatalog(): KbCatalog { |
| 105 | if (cachedCatalog) return cachedCatalog; |
| 106 | const manifest = readKbManifest(); |
| 107 | cachedCatalog = buildKbCatalog( |
| 108 | manifest, |
| 109 | createKbSourceReader(resolve(KB_ROOT, 'source')), |
| 110 | new Date(), |
| 111 | createKbArticleReader(KB_ARTICLES_ROOT) |
| 112 | ); |
| 113 | return cachedCatalog; |
| 114 | } |
| 115 | |
| 116 | export function getPublishedKbGuides(catalog = getKbCatalog()): KbGuide[] { |
| 117 | return catalog.guides.filter((guide) => guide.state === 'published'); |
| 118 | } |
| 119 | |
| 120 | export function getKbGuideUrl(guide: KbGuide): string { |
| 121 | return `/kb/guide/${guide.slug}`; |
| 122 | } |
| 123 | |
| 124 | export function getKbLegacySegments(catalog = getKbCatalog()): string[][] { |
| 125 | const paths = getPublishedKbGuides(catalog).flatMap((guide) => { |
| 126 | const primaryTopic = guide.topics[0]; |
| 127 | const primaryPath = primaryTopic ? [`/kb/${primaryTopic}/${guide.slug}`] : []; |
| 128 | return [...primaryPath, ...guide.aliases]; |
| 129 | }); |
| 130 | |
| 131 | return Array.from( |
| 132 | new Set( |
| 133 | paths |
| 134 | .map((path) => path.replace(/^\/+|\/+$/g, '')) |
| 135 | .filter((path) => path.startsWith('kb/') && !path.startsWith('kb/guide/')), |
| 136 | ), |
| 137 | ).map((path) => path.slice('kb/'.length).split('/')); |
| 138 | } |
| 139 | |
| 140 | export function resolveKbAlias(path: string, catalog = getKbCatalog()): string | null { |
| 141 | const normalized = path.replace(/^\/+|\/+$/g, '').toLowerCase(); |
| 142 | const guide = getPublishedKbGuides(catalog).find((candidate) => { |
| 143 | const primaryTopic = candidate.topics[0]; |
| 144 | const legacyPath = primaryTopic ? `kb/${primaryTopic}/${candidate.slug}` : null; |
| 145 | const canonicalPath = getKbGuideUrl(candidate).replace(/^\//, ''); |
| 146 | return ( |
| 147 | normalized === legacyPath || |
| 148 | normalized === canonicalPath || |
| 149 | candidate.aliases.some( |
| 150 | (alias) => alias.replace(/^\/+|\/+$/g, '').toLowerCase() === normalized, |
| 151 | ) |
| 152 | ); |
| 153 | }); |
| 154 | return guide ? getKbGuideUrl(guide) : null; |
| 155 | } |