Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

add @savoir/config

Hugo Richard2f6c108f32c8
diff --git a/apps/api/lib/github.ts b/apps/api/lib/github.ts
deleted file mode 100644
index d376a5f..0000000
--- a/apps/api/lib/github.ts
+++ /dev/null
@@ -1,175 +0,0 @@
-import { mkdir, rm, writeFile, readdir, stat, unlink, rmdir } from 'node:fs/promises'
-import { resolve, join, extname } from 'pathe'
-import { downloadTemplate } from 'giget'
-import type { GitHubSource, SyncResult, ContentFile } from './types'
-
-const ALLOWED_EXTENSIONS = new Set(['.md', '.mdx', '.yml', '.yaml', '.json'])
-
-const EXCLUDED_FILES = new Set([
- 'package-lock.json',
- 'yarn.lock',
- 'pnpm-lock.yaml',
- 'bun.lockb',
- 'composer.lock',
- 'Gemfile.lock',
- 'Cargo.lock',
- 'Pipfile.lock',
- 'poetry.lock',
- 'uv.lock',
- 'go.sum',
-])
-
-function isAllowedFile(filename: string): boolean {
- if (EXCLUDED_FILES.has(filename)) return false
- return ALLOWED_EXTENSIONS.has(extname(filename).toLowerCase())
-}
-
-export async function cleanupNonDocFiles(dir: string): Promise<number> {
- let mdCount = 0
-
- async function processDir(currentDir: string): Promise<void> {
- let entries: string[]
- try {
- entries = await readdir(currentDir)
- } catch {
- return
- }
-
- for (const entry of entries) {
- const fullPath = join(currentDir, entry)
- let stats
- try {
- stats = await stat(fullPath)
- } catch {
- continue
- }
-
- if (stats.isDirectory()) {
- await processDir(fullPath)
- try {
- const remaining = await readdir(fullPath)
- if (remaining.length === 0) await rmdir(fullPath)
- } catch {}
- } else if (stats.isFile()) {
- if (isAllowedFile(entry)) {
- if (entry.endsWith('.md') || entry.endsWith('.mdx')) mdCount++
- } else {
- try {
- await unlink(fullPath)
- } catch {}
- }
- }
- }
- }
-
- await processDir(dir)
- return mdCount
-}
-
-export async function fetchReadme(repo: string, branch: string): Promise<string> {
- const response = await fetch(
- `https://raw.githubusercontent.com/${repo}/${branch}/README.md`
- )
- if (!response.ok) {
- throw new Error(`Failed to fetch README from ${repo}: ${response.statusText}`)
- }
- return response.text()
-}
-
-export async function syncGitHubSource(
- source: GitHubSource,
- outputDir: string
-): Promise<SyncResult> {
- const startTime = Date.now()
- const outputFolder = source.outputPath || source.id
- const targetDir = resolve(outputDir, 'docs', outputFolder)
-
- try {
- await mkdir(targetDir, { recursive: true })
-
- if (source.readmeOnly) {
- const content = await fetchReadme(source.repo, source.branch)
- await writeFile(resolve(targetDir, 'README.md'), content, 'utf-8')
- return {
- sourceId: source.id,
- success: true,
- fileCount: 1,
- duration: Date.now() - startTime,
- }
- }
-
- const template = `gh:${source.repo}/${source.contentPath}#${source.branch}`
- await downloadTemplate(template, { dir: targetDir, force: true })
-
- const mdCount = await cleanupNonDocFiles(targetDir)
-
- if (source.additionalSyncs) {
- for (const additional of source.additionalSyncs) {
- const additionalTemplate = `gh:${additional.repo}/${additional.contentPath}#${additional.branch}`
- try {
- await downloadTemplate(additionalTemplate, { dir: targetDir, force: false })
- await cleanupNonDocFiles(targetDir)
- } catch (error) {
- console.warn(`[${source.id}] Additional sync failed for ${additional.repo}:`, error)
- }
- }
- }
-
- return {
- sourceId: source.id,
- success: true,
- fileCount: mdCount,
- duration: Date.now() - startTime,
- }
- } catch (error) {
- return {
- sourceId: source.id,
- success: false,
- error: error instanceof Error ? error.message : String(error),
- duration: Date.now() - startTime,
- }
- }
-}
-
-export async function resetSourceDir(source: GitHubSource, outputDir: string): Promise<void> {
- const targetDir = resolve(outputDir, 'docs', source.outputPath || source.id)
- try {
- await rm(targetDir, { recursive: true, force: true })
- } catch {}
-}
-
-export async function collectFiles(dir: string, basePath = ''): Promise<ContentFile[]> {
- const files: ContentFile[] = []
-
- async function processDir(currentDir: string, relativePath: string): Promise<void> {
- let entries: string[]
- try {
- entries = await readdir(currentDir)
- } catch {
- return
- }
-
- for (const entry of entries) {
- const fullPath = join(currentDir, entry)
- const relPath = relativePath ? `${relativePath}/${entry}` : entry
-
- let stats
- try {
- stats = await stat(fullPath)
- } catch {
- continue
- }
-
- if (stats.isDirectory()) {
- await processDir(fullPath, relPath)
- } else if (stats.isFile() && isAllowedFile(entry)) {
- const { readFile } = await import('node:fs/promises')
- const content = await readFile(fullPath, 'utf-8')
- files.push({ path: relPath, content })
- }
- }
- }
-
- await processDir(dir, basePath)
- return files
-}
diff --git a/apps/api/lib/index.ts b/apps/api/lib/index.ts
deleted file mode 100644
index ae4429e..0000000
--- a/apps/api/lib/index.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// Types
-export type {
- Source,
- GitHubSource,
- YouTubeSource,
- CustomSource,
- ContentFile,
- SyncResult,
- SnapshotConfig,
- SyncConfig,
- SyncOptions,
- PushResult,
-} from './types'
-
-// Sources
-export {
- SOURCES,
- GITHUB_SOURCES,
- YOUTUBE_SOURCES,
- getSourceById,
- getGitHubSources,
- getYouTubeSources,
- getSourcesByType,
-} from './sources'
-
-// GitHub sync
-export {
- syncGitHubSource,
- resetSourceDir,
- cleanupNonDocFiles,
- fetchReadme,
- collectFiles,
-} from './github'
-
-// Snapshot
-export { pushToSnapshot } from './snapshot'
diff --git a/apps/api/lib/snapshot.ts b/apps/api/lib/snapshot.ts
deleted file mode 100644
index 061a02b..0000000
--- a/apps/api/lib/snapshot.ts
+++ /dev/null
@@ -1,198 +0,0 @@
-import { readdir, stat, readFile } from 'node:fs/promises'
-import { join } from 'pathe'
-import type { PushResult } from './types'
-
-interface GitHubTreeItem {
- path: string
- mode: '100644' | '100755' | '040000' | '160000' | '120000'
- type: 'blob' | 'tree' | 'commit'
- sha?: string
- content?: string
-}
-
-interface GitHubCommit {
- sha: string
- tree: { sha: string }
-}
-
-async function collectAllFiles(
- dir: string,
- basePath = ''
-): Promise<Array<{ path: string; content: string }>> {
- const files: Array<{ path: string; content: string }> = []
-
- async function processDir(currentDir: string, relativePath: string): Promise<void> {
- let entries: string[]
- try {
- entries = await readdir(currentDir)
- } catch {
- return
- }
-
- for (const entry of entries) {
- const fullPath = join(currentDir, entry)
- const relPath = relativePath ? `${relativePath}/${entry}` : entry
-
- let stats
- try {
- stats = await stat(fullPath)
- } catch {
- continue
- }
-
- if (stats.isDirectory()) {
- await processDir(fullPath, relPath)
- } else if (stats.isFile()) {
- try {
- const content = await readFile(fullPath, 'utf-8')
- files.push({ path: relPath, content })
- } catch {}
- }
- }
- }
-
- await processDir(dir, basePath)
- return files
-}
-
-export async function pushToSnapshot(
- contentDir: string,
- options: {
- repo: string
- branch: string
- token: string
- message?: string
- }
-): Promise<PushResult> {
- const { repo, branch, token, message = 'chore: sync content' } = options
- const apiBase = 'https://api.github.com'
-
- const headers = {
- Authorization: `Bearer ${token}`,
- Accept: 'application/vnd.github.v3+json',
- 'Content-Type': 'application/json',
- 'X-GitHub-Api-Version': '2022-11-28',
- }
-
- try {
- const files = await collectAllFiles(contentDir)
-
- if (files.length === 0) {
- return { success: false, error: 'No files to push' }
- }
-
- let baseSha: string | null = null
- let baseTreeSha: string | null = null
-
- try {
- const refResponse = await fetch(
- `${apiBase}/repos/${repo}/git/refs/heads/${branch}`,
- { headers }
- )
-
- if (refResponse.ok) {
- const refData = await refResponse.json()
- baseSha = refData.object.sha
-
- const commitResponse = await fetch(
- `${apiBase}/repos/${repo}/git/commits/${baseSha}`,
- { headers }
- )
- if (commitResponse.ok) {
- const commitData: GitHubCommit = await commitResponse.json()
- baseTreeSha = commitData.tree.sha
- }
- }
- } catch {}
-
- const treeItems: GitHubTreeItem[] = []
-
- for (const file of files) {
- if (file.content.length < 1024 * 100) {
- treeItems.push({
- path: file.path,
- mode: '100644',
- type: 'blob',
- content: file.content,
- })
- } else {
- const blobResponse = await fetch(`${apiBase}/repos/${repo}/git/blobs`, {
- method: 'POST',
- headers,
- body: JSON.stringify({
- content: Buffer.from(file.content).toString('base64'),
- encoding: 'base64',
- }),
- })
-
- if (!blobResponse.ok) {
- throw new Error(`Failed to create blob for ${file.path}`)
- }
-
- const blobData = await blobResponse.json()
- treeItems.push({
- path: file.path,
- mode: '100644',
- type: 'blob',
- sha: blobData.sha,
- })
- }
- }
-
- const treeResponse = await fetch(`${apiBase}/repos/${repo}/git/trees`, {
- method: 'POST',
- headers,
- body: JSON.stringify({ base_tree: baseTreeSha, tree: treeItems }),
- })
-
- if (!treeResponse.ok) {
- throw new Error(`Failed to create tree: ${await treeResponse.text()}`)
- }
-
- const treeData = await treeResponse.json()
-
- const commitPayload: Record<string, unknown> = { message, tree: treeData.sha }
- if (baseSha) commitPayload.parents = [baseSha]
-
- const commitResponse = await fetch(`${apiBase}/repos/${repo}/git/commits`, {
- method: 'POST',
- headers,
- body: JSON.stringify(commitPayload),
- })
-
- if (!commitResponse.ok) {
- throw new Error(`Failed to create commit: ${await commitResponse.text()}`)
- }
-
- const commitData = await commitResponse.json()
-
- const refPath = baseSha
- ? `${apiBase}/repos/${repo}/git/refs/heads/${branch}`
- : `${apiBase}/repos/${repo}/git/refs`
-
- const refPayload = baseSha
- ? { sha: commitData.sha, force: false }
- : { ref: `refs/heads/${branch}`, sha: commitData.sha }
-
- const refUpdateResponse = await fetch(refPath, {
- method: baseSha ? 'PATCH' : 'POST',
- headers,
- body: JSON.stringify(refPayload),
- })
-
- if (!refUpdateResponse.ok) {
- throw new Error(`Failed to update ref: ${await refUpdateResponse.text()}`)
- }
-
- return {
- success: true,
- commitSha: commitData.sha,
- filesChanged: files.length,
- }
- } catch (error) {
- return {
- success: false,
- error: error instanceof Error ? error.message : String(error),
- }
- }
-}
diff --git a/apps/api/lib/sources.ts b/apps/api/lib/sources.ts
deleted file mode 100644
index 628b0c7..0000000
--- a/apps/api/lib/sources.ts
+++ /dev/null
@@ -1,258 +0,0 @@
-import type { GitHubSource, YouTubeSource, Source } from './types'
-
-export const GITHUB_SOURCES: GitHubSource[] = [
- // Nuxt Core
- {
- id: 'nuxt',
- label: 'Nuxt',
- type: 'github',
- repo: 'nuxt/nuxt',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'nuxt',
- additionalSyncs: [
- { repo: 'nuxt/nuxt.com', branch: 'main', contentPath: 'content' },
- ],
- },
- {
- id: 'nitro',
- label: 'Nitro',
- type: 'github',
- repo: 'nitrojs/nitro',
- branch: 'v3',
- contentPath: 'docs',
- outputPath: 'nitro',
- },
-
- // Nuxt Modules
- {
- id: 'nuxt-ui',
- label: 'Nuxt UI',
- type: 'github',
- repo: 'nuxt/ui',
- branch: 'v4',
- contentPath: 'docs/content',
- outputPath: 'nuxt-ui',
- },
- {
- id: 'nuxt-hub',
- label: 'NuxtHub',
- type: 'github',
- repo: 'nuxt-hub/core',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-hub',
- },
- {
- id: 'nuxt-content',
- label: 'Nuxt Content',
- type: 'github',
- repo: 'nuxt/content',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-content',
- },
- {
- id: 'nuxt-image',
- label: 'Nuxt Image',
- type: 'github',
- repo: 'nuxt/image',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-image',
- },
- {
- id: 'nuxt-i18n',
- label: 'Nuxt i18n',
- type: 'github',
- repo: 'nuxt-modules/i18n',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-i18n',
- },
- {
- id: 'nuxt-scripts',
- label: 'Nuxt Scripts',
- type: 'github',
- repo: 'nuxt/scripts',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-scripts',
- },
- {
- id: 'nuxt-fonts',
- label: 'Nuxt Fonts',
- type: 'github',
- repo: 'nuxt/fonts',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-fonts',
- },
- {
- id: 'nuxt-eslint',
- label: 'Nuxt ESLint',
- type: 'github',
- repo: 'nuxt/eslint',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-eslint',
- },
- {
- id: 'nuxt-devtools',
- label: 'Nuxt DevTools',
- type: 'github',
- repo: 'nuxt/devtools',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-devtools',
- },
-
- // README-only
- {
- id: 'nuxt-icon',
- label: 'Nuxt Icon',
- type: 'github',
- repo: 'nuxt/icon',
- branch: 'main',
- contentPath: '',
- outputPath: 'nuxt-icon',
- readmeOnly: true,
- },
- {
- id: 'nuxt-auth-utils',
- label: 'Nuxt Auth Utils',
- type: 'github',
- repo: 'atinux/nuxt-auth-utils',
- branch: 'main',
- contentPath: '',
- outputPath: 'nuxt-auth-utils',
- readmeOnly: true,
- },
- {
- id: 'ofetch',
- label: 'ofetch',
- type: 'github',
- repo: 'unjs/ofetch',
- branch: 'main',
- contentPath: '',
- outputPath: 'ofetch',
- readmeOnly: true,
- },
-
- // UnJS
- {
- id: 'h3',
- label: 'H3',
- type: 'github',
- repo: 'unjs/h3',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'h3',
- },
- {
- id: 'unstorage',
- label: 'unstorage',
- type: 'github',
- repo: 'unjs/unstorage',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'unstorage',
- },
- {
- id: 'unhead',
- label: 'Unhead',
- type: 'github',
- repo: 'unjs/unhead',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'unhead',
- },
-
- // SEO
- {
- id: 'nuxt-og-image',
- label: 'Nuxt OG Image',
- type: 'github',
- repo: 'nuxt-modules/og-image',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-og-image',
- },
- {
- id: 'nuxt-sitemap',
- label: 'Nuxt Sitemap',
- type: 'github',
- repo: 'nuxt-modules/sitemap',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-sitemap',
- },
- {
- id: 'nuxt-robots',
- label: 'Nuxt Robots',
- type: 'github',
- repo: 'nuxt-modules/robots',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-robots',
- },
-
- // Other
- {
- id: 'mcp-toolkit',
- label: 'MCP Toolkit',
- type: 'github',
- repo: 'nuxt-modules/mcp-toolkit',
- branch: 'main',
- contentPath: 'apps/docs/content',
- outputPath: 'mcp-toolkit',
- },
- {
- id: 'nuxt-studio',
- label: 'Nuxt Studio',
- type: 'github',
- repo: 'nuxt-content/nuxt-studio',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'nuxt-studio',
- },
-]
-
-export const YOUTUBE_SOURCES: YouTubeSource[] = [
- {
- id: 'alex-lichter',
- label: 'Alexander Lichter',
- type: 'youtube',
- channelId: 'UCqFPgMzGbLjd-MX-h3Z5aQA',
- handle: '@TheAlexLichter',
- maxVideos: 100,
- },
- {
- id: 'learn-vue',
- label: 'LearnVue',
- type: 'youtube',
- channelId: 'UCGwuxdEeCf0TIA2RbPOj-8g',
- handle: '@LearnVue',
- maxVideos: 50,
- },
-]
-
-export const SOURCES: Source[] = [...GITHUB_SOURCES, ...YOUTUBE_SOURCES]
-
-export function getSourceById(id: string): Source | undefined {
- return SOURCES.find((s) => s.id === id)
-}
-
-export function getGitHubSources(): GitHubSource[] {
- return GITHUB_SOURCES
-}
-
-export function getYouTubeSources(): YouTubeSource[] {
- return YOUTUBE_SOURCES
-}
-
-export function getSourcesByType<T extends Source['type']>(
- type: T
-): Extract<Source, { type: T }>[] {
- return SOURCES.filter((s) => s.type === type) as Extract<Source, { type: T }>[]
-}
diff --git a/apps/api/package.json b/apps/api/package.json
index 505d621..5820dcf 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -13,6 +13,7 @@
"lint:fix": "eslint . --fix"
},
"dependencies": {
+ "@savoir/config": "workspace:*",
"@savoir/logger": "workspace:*",
"@types/node": "^25.0.9",
"giget": "^2.0.0",
diff --git a/apps/api/plugins/config.ts b/apps/api/plugins/config.ts
new file mode 100644
index 0000000..414c4ad
--- /dev/null
+++ b/apps/api/plugins/config.ts
@@ -0,0 +1,10 @@
+import { definePlugin } from 'nitro'
+import { setConfigCwd } from '@savoir/config'
+
+/**
+ * Set the config directory at startup.
+ */
+export default definePlugin(() => {
+ // Config is at the project root (parent of apps/api)
+ setConfigCwd(process.cwd().replace(/\/apps\/api$/, ''))
+})
diff --git a/apps/api/routes/api/index.ts b/apps/api/routes/api/index.ts
index 947c4c7..f46cd9b 100644
--- a/apps/api/routes/api/index.ts
+++ b/apps/api/routes/api/index.ts
@@ -9,9 +9,13 @@ export default defineHandler(() => {
name: 'Savoir API',
version: '0.1.0',
endpoints: {
- sources: 'GET /api/sources',
- syncAll: 'POST /api/sync',
- syncOne: 'POST /api/sync/:source',
+ sources: {
+ list: 'GET /api/sources',
+ },
+ sync: {
+ all: 'POST /api/sync',
+ one: 'POST /api/sync/:source',
+ },
},
}
})
diff --git a/apps/api/routes/api/sources.get.ts b/apps/api/routes/api/sources/index.get.ts
similarity index 66%
rename from apps/api/routes/api/sources.get.ts
rename to apps/api/routes/api/sources/index.get.ts
index 00a270e..fa5bd7c 100644
--- a/apps/api/routes/api/sources.get.ts
+++ b/apps/api/routes/api/sources/index.get.ts
@@ -1,12 +1,12 @@
import { defineHandler } from 'nitro/h3'
-import { SOURCES, getGitHubSources, getYouTubeSources } from '~/workflows/sync-docs'
+import { getSources, getGitHubSources, getYouTubeSources } from '~/workflows/sync-docs'
/**
* GET /api/sources
* Returns the list of configured content sources
*/
-export default defineHandler(() => {
- const github = getGitHubSources().map((s) => ({
+export default defineHandler(async () => {
+ const github = (await getGitHubSources()).map((s) => ({
id: s.id,
label: s.label,
type: s.type,
@@ -16,7 +16,7 @@ export default defineHandler(() => {
readmeOnly: s.readmeOnly || false,
}))
- const youtube = getYouTubeSources().map((s) => ({
+ const youtube = (await getYouTubeSources()).map((s) => ({
id: s.id,
label: s.label,
type: s.type,
@@ -25,7 +25,7 @@ export default defineHandler(() => {
}))
return {
- total: SOURCES.length,
+ total: (await getSources()).length,
github: {
count: github.length,
sources: github,
diff --git a/apps/api/routes/api/sync/[source].post.ts b/apps/api/routes/api/sync/[source].post.ts
index 222e4a0..da296d0 100644
--- a/apps/api/routes/api/sync/[source].post.ts
+++ b/apps/api/routes/api/sync/[source].post.ts
@@ -1,137 +1,54 @@
-import { mkdir, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { defineHandler, getValidatedRouterParams, readValidatedBody, HTTPError } from 'nitro/h3'
-import { resolve } from 'pathe'
-import { z } from 'zod'
-import {
- getSourceById,
- syncGitHubSource,
- pushToSnapshot,
- type GitHubSource,
-} from '~/workflows/sync-docs'
+import { start } from 'workflow/api'
+import { defineHandler, readValidatedBody, getValidatedRouterParams } from 'nitro/h3'
import { useRuntimeConfig } from 'nitro/runtime-config'
+import { z } from 'zod'
+import { syncDocumentation } from '~/workflows/sync-docs'
const paramsSchema = z.object({
- source: z.string().min(1, 'Source ID is required'),
+ source: z.string().min(1),
})
-const bodySchema = z.object({
- reset: z.boolean().default(false),
- push: z.boolean().default(true),
-}).optional()
+const bodySchema = z
+ .object({
+ reset: z.boolean().default(false),
+ push: z.boolean().default(true),
+ })
+ .optional()
/**
* POST /api/sync/:source
- * Triggers sync for a specific source
+ * Sync a specific source.
*
* Params:
* - source: Source ID to sync
*
* Body (optional):
- * - reset: boolean - Clear source content before sync (default: false)
+ * - reset: boolean - Clear content before sync (default: false)
* - push: boolean - Push to snapshot repo after sync (default: true)
*/
export default defineHandler(async (event) => {
+ const { source } = await getValidatedRouterParams(event, paramsSchema.parse)
+ const body = await readValidatedBody(event, data => bodySchema.parse(data))
const config = useRuntimeConfig()
- const { source: sourceId } = await getValidatedRouterParams(event, paramsSchema.parse)
-
- // Validate required environment variables
- if (!config.githubToken) {
- throw HTTPError.status(500, 'GITHUB_TOKEN is not configured')
- }
-
- if (!config.snapshotRepo) {
- throw HTTPError.status(500, 'GITHUB_SNAPSHOT_REPO is not configured')
- }
-
- // Find the source
- const source = getSourceById(sourceId)
-
- if (!source) {
- throw HTTPError.status(404, `Source not found: ${sourceId}`)
+ const syncConfig = {
+ githubToken: config.githubToken,
+ snapshotRepo: config.snapshotRepo,
+ snapshotBranch: config.snapshotBranch,
}
- if (source.type !== 'github') {
- throw HTTPError.status(400, `Source type '${source.type}' is not supported yet`)
+ const options = {
+ reset: body?.reset ?? false,
+ push: body?.push ?? true,
+ sourceFilter: source,
}
- const body = await readValidatedBody(event, bodySchema.parse)
- const shouldReset = body?.reset ?? false
- const shouldPush = body?.push ?? true
-
- // Use a temporary directory for sync
- const syncDir = resolve(tmpdir(), 'savoir-sync', Date.now().toString())
- await mkdir(syncDir, { recursive: true })
-
- try {
- // Reset if requested
- if (shouldReset) {
- const outputPath = (source as GitHubSource).outputPath || source.id
- await rm(resolve(syncDir, 'docs', outputPath), { recursive: true, force: true })
- }
-
- const log = event.context.log
- const result = await syncGitHubSource(source as GitHubSource, syncDir)
-
- // Push to snapshot repository if enabled
- let pushResult = null
- if (shouldPush && result.success) {
- pushResult = await pushToSnapshot(syncDir, {
- repo: config.snapshotRepo,
- branch: config.snapshotBranch || 'main',
- token: config.githubToken,
- message: `chore: sync ${source.label} (${result.fileCount} files)`,
- })
- }
-
- log.set({
- source: {
- id: source.id,
- label: source.label,
- type: source.type,
- },
- sync: {
- success: result.success,
- fileCount: result.fileCount,
- syncDurationMs: result.duration,
- error: result.error,
- },
- push: pushResult ? {
- success: pushResult.success,
- filesChanged: pushResult.filesChanged,
- commitSha: pushResult.commitSha,
- error: pushResult.error,
- } : null,
- })
-
- // Cleanup temp directory
- await rm(syncDir, { recursive: true, force: true }).catch(() => {})
-
- return {
- success: result.success,
- source: {
- id: source.id,
- label: source.label,
- },
- sync: {
- fileCount: result.fileCount,
- duration: result.duration,
- error: result.error,
- },
- push: pushResult
- ? {
- success: pushResult.success,
- commitSha: pushResult.commitSha,
- filesChanged: pushResult.filesChanged,
- error: pushResult.error,
- }
- : null,
- }
- } catch (error) {
- // Cleanup on error
- await rm(syncDir, { recursive: true, force: true }).catch(() => {})
+ await start(syncDocumentation, [syncConfig, options])
- throw HTTPError.status(500, 'Sync failed')
+ return {
+ status: 'started',
+ message: `Sync workflow started for source "${source}". Use \`pnpm workflow:web\` to monitor.`,
+ source,
+ options,
}
})
diff --git a/apps/api/routes/api/sync/index.post.ts b/apps/api/routes/api/sync/index.post.ts
index e4a81e5..d7883ac 100644
--- a/apps/api/routes/api/sync/index.post.ts
+++ b/apps/api/routes/api/sync/index.post.ts
@@ -1,127 +1,44 @@
-import { mkdir, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { defineHandler, readValidatedBody, HTTPError } from 'nitro/h3'
-import { resolve } from 'pathe'
-import { z } from 'zod'
-import {
- getGitHubSources,
- syncGitHubSource,
- pushToSnapshot,
- type SyncResult,
-} from '~/workflows/sync-docs'
+import { start } from 'workflow/api'
+import { defineHandler, readValidatedBody } from 'nitro/h3'
import { useRuntimeConfig } from 'nitro/runtime-config'
+import { z } from 'zod'
+import { syncDocumentation } from '~/workflows/sync-docs'
-const bodySchema = z.object({
- reset: z.boolean().default(false),
- push: z.boolean().default(true),
-}).optional()
+const bodySchema = z
+ .object({
+ reset: z.boolean().default(false),
+ push: z.boolean().default(true),
+ })
+ .optional()
/**
* POST /api/sync
- * Triggers a full content synchronization
+ * Sync all sources.
*
* Body (optional):
* - reset: boolean - Clear all content before sync (default: false)
* - push: boolean - Push to snapshot repo after sync (default: true)
*/
export default defineHandler(async (event) => {
+ const body = await readValidatedBody(event, data => bodySchema.parse(data))
const config = useRuntimeConfig()
- // Validate required environment variables
- if (!config.githubToken) {
- throw HTTPError.status(500, 'GITHUB_TOKEN is not configured')
+ const syncConfig = {
+ githubToken: config.githubToken,
+ snapshotRepo: config.snapshotRepo,
+ snapshotBranch: config.snapshotBranch,
}
- if (!config.snapshotRepo) {
- throw HTTPError.status(500, 'GITHUB_SNAPSHOT_REPO is not configured')
+ const options = {
+ reset: body?.reset ?? false,
+ push: body?.push ?? true,
}
- const body = await readValidatedBody(event, bodySchema.parse)
- const shouldReset = body?.reset ?? false
- const shouldPush = body?.push ?? true
-
- // Use a temporary directory for sync
- const syncDir = resolve(tmpdir(), 'savoir-sync', Date.now().toString())
- await mkdir(syncDir, { recursive: true })
-
- try {
- // Reset if requested
- if (shouldReset) {
- await rm(resolve(syncDir, 'docs'), { recursive: true, force: true })
- await mkdir(resolve(syncDir, 'docs'), { recursive: true })
- }
-
- // Sync all GitHub sources
- const sources = getGitHubSources()
- const results: SyncResult[] = []
-
- const log = event.context.log
-
- for (const source of sources) {
- const result = await syncGitHubSource(source, syncDir)
- results.push(result)
- }
-
- const successCount = results.filter((r) => r.success).length
- const failCount = results.filter((r) => !r.success).length
- const totalFiles = results.reduce((sum, r) => sum + (r.fileCount || 0), 0)
-
- // Push to snapshot repository if enabled
- let pushResult = null
- if (shouldPush && successCount > 0) {
- pushResult = await pushToSnapshot(syncDir, {
- repo: config.snapshotRepo,
- branch: config.snapshotBranch || 'main',
- token: config.githubToken,
- message: `chore: sync ${successCount} sources (${totalFiles} files)`,
- })
- }
-
- log.set({
- sync: {
- sourcesTotal: sources.length,
- sourcesSuccess: successCount,
- sourcesFailed: failCount,
- filesTotal: totalFiles,
- },
- push: pushResult ? {
- success: pushResult.success,
- filesChanged: pushResult.filesChanged,
- commitSha: pushResult.commitSha,
- } : null,
- })
-
- // Cleanup temp directory
- await rm(syncDir, { recursive: true, force: true }).catch(() => {})
-
- return {
- success: failCount === 0,
- summary: {
- total: sources.length,
- success: successCount,
- failed: failCount,
- files: totalFiles,
- },
- push: pushResult
- ? {
- success: pushResult.success,
- commitSha: pushResult.commitSha,
- filesChanged: pushResult.filesChanged,
- error: pushResult.error,
- }
- : null,
- results: results.map((r) => ({
- sourceId: r.sourceId,
- success: r.success,
- fileCount: r.fileCount,
- duration: r.duration,
- error: r.error,
- })),
- }
- } catch (error) {
- // Cleanup on error
- await rm(syncDir, { recursive: true, force: true }).catch(() => {})
+ await start(syncDocumentation, [syncConfig, options])
- throw HTTPError.status(500, 'Sync failed')
+ return {
+ status: 'started',
+ message: 'Sync workflow started. Use `pnpm workflow:web` to monitor.',
+ options,
}
})
diff --git a/apps/api/routes/api/sync/workflow.post.ts b/apps/api/routes/api/sync/workflow.post.ts
deleted file mode 100644
index ef292b7..0000000
--- a/apps/api/routes/api/sync/workflow.post.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { start } from 'workflow/api'
-import { defineHandler, readValidatedBody } from 'nitro/h3'
-import { useRuntimeConfig } from 'nitro/runtime-config'
-import { z } from 'zod'
-import { syncDocumentation } from '~/workflows/sync-docs'
-
-const bodySchema = z
- .object({
- reset: z.boolean().default(false),
- push: z.boolean().default(true),
- source: z.string().optional(),
- })
- .optional()
-
-/**
- * POST /api/sync/workflow
- * Triggers the sync workflow asynchronously.
- *
- * Body (optional):
- * - reset: boolean - Clear all content before sync (default: false)
- * - push: boolean - Push to snapshot repo after sync (default: true)
- * - source: string - Sync only this source ID (optional)
- */
-export default defineHandler(async (event) => {
- const body = await readValidatedBody(event, (data) => bodySchema.parse(data))
- const config = useRuntimeConfig()
-
- const syncConfig = {
- githubToken: config.githubToken,
- snapshotRepo: config.snapshotRepo,
- snapshotBranch: config.snapshotBranch,
- }
-
- const options = {
- reset: body?.reset ?? false,
- push: body?.push ?? true,
- sourceFilter: body?.source,
- }
-
- await start(syncDocumentation, [syncConfig, options])
-
- return {
- status: 'started',
- message: 'Sync workflow started. Use `pnpm workflow:web` to monitor.',
- options,
- }
-})
diff --git a/apps/api/workflows/sync-docs/steps/get-sources.ts b/apps/api/workflows/sync-docs/steps/get-sources.ts
index 670c361..0848146 100644
--- a/apps/api/workflows/sync-docs/steps/get-sources.ts
+++ b/apps/api/workflows/sync-docs/steps/get-sources.ts
@@ -7,10 +7,10 @@ export async function getSourcesToSync(sourceFilter?: string): Promise<GitHubSou
'use step'
const logger = getLogger()
- let sources = getGitHubSources()
+ let sources = await getGitHubSources()
if (sourceFilter) {
- const source = getSourceById(sourceFilter)
+ const source = await getSourceById(sourceFilter)
if (!source || source.type !== 'github') {
throw new FatalError(`Source not found: ${sourceFilter}`)
}
diff --git a/apps/api/workflows/sync-docs/steps/sync-source.ts b/apps/api/workflows/sync-docs/steps/sync-source.ts
index f01b5a8..104601d 100644
--- a/apps/api/workflows/sync-docs/steps/sync-source.ts
+++ b/apps/api/workflows/sync-docs/steps/sync-source.ts
@@ -18,7 +18,7 @@ export async function syncSingleSource(
const result = await syncGitHubSource(source, syncDir)
if (result.success) {
- logger.log('sync', `${source.id}: ${result.fileCount} files in ${formatDuration(result.duration)}`)
+ logger.log('sync', `${source.id}: ${result.fileCount} files in ${formatDuration(result.duration ?? 0)}`)
} else {
logger.error({ source: source.id, error: result.error, message: 'Sync failed' })
throw new Error(`Failed to sync ${source.id}: ${result.error}`)
diff --git a/apps/api/workflows/sync-docs/utils/github.ts b/apps/api/workflows/sync-docs/utils/github.ts
index 5e9863f..df401c0 100644
--- a/apps/api/workflows/sync-docs/utils/github.ts
+++ b/apps/api/workflows/sync-docs/utils/github.ts
@@ -1,7 +1,7 @@
import { mkdir, rm, writeFile, readdir, stat, unlink, rmdir } from 'node:fs/promises'
import { resolve, join, extname } from 'pathe'
import { downloadTemplate } from 'giget'
-import type { GitHubSource, SyncResult, ContentFile } from './types.js'
+import type { GitHubSource, SyncResult, ContentFile } from '@savoir/config'
const ALLOWED_EXTENSIONS = new Set(['.md', '.mdx', '.yml', '.yaml', '.json'])
diff --git a/apps/api/workflows/sync-docs/utils/index.ts b/apps/api/workflows/sync-docs/utils/index.ts
index 5e39a7e..3ef91b1 100644
--- a/apps/api/workflows/sync-docs/utils/index.ts
+++ b/apps/api/workflows/sync-docs/utils/index.ts
@@ -1,4 +1,4 @@
-// Types
+// Types and sources from @savoir/config
export type {
Source,
GitHubSource,
@@ -10,20 +10,17 @@ export type {
SyncConfig,
SyncOptions,
PushResult,
-} from './types.js'
+} from '@savoir/config'
-// Sources
export {
- SOURCES,
- GITHUB_SOURCES,
- YOUTUBE_SOURCES,
- getSourceById,
+ getSources,
getGitHubSources,
getYouTubeSources,
+ getSourceById,
getSourcesByType,
-} from './sources.js'
+} from '@savoir/config'
-// GitHub
+// GitHub sync functions
export {
syncGitHubSource,
resetSourceDir,
diff --git a/apps/api/workflows/sync-docs/utils/snapshot.ts b/apps/api/workflows/sync-docs/utils/snapshot.ts
index abe7ad7..b3be82f 100644
--- a/apps/api/workflows/sync-docs/utils/snapshot.ts
+++ b/apps/api/workflows/sync-docs/utils/snapshot.ts
@@ -1,6 +1,6 @@
import { readdir, stat, readFile } from 'node:fs/promises'
import { join } from 'pathe'
-import type { PushResult } from './types.js'
+import type { PushResult } from '@savoir/config'
interface GitHubTreeItem {
path: string
diff --git a/apps/api/workflows/sync-docs/utils/sources.ts b/apps/api/workflows/sync-docs/utils/sources.ts
deleted file mode 100644
index 15f4486..0000000
--- a/apps/api/workflows/sync-docs/utils/sources.ts
+++ /dev/null
@@ -1,258 +0,0 @@
-import type { GitHubSource, YouTubeSource, Source } from './types.js'
-
-export const GITHUB_SOURCES: GitHubSource[] = [
- // Nuxt Core
- {
- id: 'nuxt',
- label: 'Nuxt',
- type: 'github',
- repo: 'nuxt/nuxt',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'nuxt',
- additionalSyncs: [
- { repo: 'nuxt/nuxt.com', branch: 'main', contentPath: 'content' },
- ],
- },
- {
- id: 'nitro',
- label: 'Nitro',
- type: 'github',
- repo: 'nitrojs/nitro',
- branch: 'v3',
- contentPath: 'docs',
- outputPath: 'nitro',
- },
-
- // Nuxt Modules
- {
- id: 'nuxt-ui',
- label: 'Nuxt UI',
- type: 'github',
- repo: 'nuxt/ui',
- branch: 'v4',
- contentPath: 'docs/content',
- outputPath: 'nuxt-ui',
- },
- {
- id: 'nuxt-hub',
- label: 'NuxtHub',
- type: 'github',
- repo: 'nuxt-hub/core',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-hub',
- },
- {
- id: 'nuxt-content',
- label: 'Nuxt Content',
- type: 'github',
- repo: 'nuxt/content',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-content',
- },
- {
- id: 'nuxt-image',
- label: 'Nuxt Image',
- type: 'github',
- repo: 'nuxt/image',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-image',
- },
- {
- id: 'nuxt-i18n',
- label: 'Nuxt i18n',
- type: 'github',
- repo: 'nuxt-modules/i18n',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-i18n',
- },
- {
- id: 'nuxt-scripts',
- label: 'Nuxt Scripts',
- type: 'github',
- repo: 'nuxt/scripts',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-scripts',
- },
- {
- id: 'nuxt-fonts',
- label: 'Nuxt Fonts',
- type: 'github',
- repo: 'nuxt/fonts',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-fonts',
- },
- {
- id: 'nuxt-eslint',
- label: 'Nuxt ESLint',
- type: 'github',
- repo: 'nuxt/eslint',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-eslint',
- },
- {
- id: 'nuxt-devtools',
- label: 'Nuxt DevTools',
- type: 'github',
- repo: 'nuxt/devtools',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-devtools',
- },
-
- // README-only
- {
- id: 'nuxt-icon',
- label: 'Nuxt Icon',
- type: 'github',
- repo: 'nuxt/icon',
- branch: 'main',
- contentPath: '',
- outputPath: 'nuxt-icon',
- readmeOnly: true,
- },
- {
- id: 'nuxt-auth-utils',
- label: 'Nuxt Auth Utils',
- type: 'github',
- repo: 'atinux/nuxt-auth-utils',
- branch: 'main',
- contentPath: '',
- outputPath: 'nuxt-auth-utils',
- readmeOnly: true,
- },
- {
- id: 'ofetch',
- label: 'ofetch',
- type: 'github',
- repo: 'unjs/ofetch',
- branch: 'main',
- contentPath: '',
- outputPath: 'ofetch',
- readmeOnly: true,
- },
-
- // UnJS
- {
- id: 'h3',
- label: 'H3',
- type: 'github',
- repo: 'unjs/h3',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'h3',
- },
- {
- id: 'unstorage',
- label: 'unstorage',
- type: 'github',
- repo: 'unjs/unstorage',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'unstorage',
- },
- {
- id: 'unhead',
- label: 'Unhead',
- type: 'github',
- repo: 'unjs/unhead',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'unhead',
- },
-
- // SEO
- {
- id: 'nuxt-og-image',
- label: 'Nuxt OG Image',
- type: 'github',
- repo: 'nuxt-modules/og-image',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-og-image',
- },
- {
- id: 'nuxt-sitemap',
- label: 'Nuxt Sitemap',
- type: 'github',
- repo: 'nuxt-modules/sitemap',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-sitemap',
- },
- {
- id: 'nuxt-robots',
- label: 'Nuxt Robots',
- type: 'github',
- repo: 'nuxt-modules/robots',
- branch: 'main',
- contentPath: 'docs/content',
- outputPath: 'nuxt-robots',
- },
-
- // Other
- {
- id: 'mcp-toolkit',
- label: 'MCP Toolkit',
- type: 'github',
- repo: 'nuxt-modules/mcp-toolkit',
- branch: 'main',
- contentPath: 'apps/docs/content',
- outputPath: 'mcp-toolkit',
- },
- {
- id: 'nuxt-studio',
- label: 'Nuxt Studio',
- type: 'github',
- repo: 'nuxt-content/nuxt-studio',
- branch: 'main',
- contentPath: 'docs',
- outputPath: 'nuxt-studio',
- },
-]
-
-export const YOUTUBE_SOURCES: YouTubeSource[] = [
- {
- id: 'alex-lichter',
- label: 'Alexander Lichter',
- type: 'youtube',
- channelId: 'UCqFPgMzGbLjd-MX-h3Z5aQA',
- handle: '@TheAlexLichter',
- maxVideos: 100,
- },
- {
- id: 'learn-vue',
- label: 'LearnVue',
- type: 'youtube',
- channelId: 'UCGwuxdEeCf0TIA2RbPOj-8g',
- handle: '@LearnVue',
- maxVideos: 50,
- },
-]
-
-export const SOURCES: Source[] = [...GITHUB_SOURCES, ...YOUTUBE_SOURCES]
-
-export function getSourceById(id: string): Source | undefined {
- return SOURCES.find((s) => s.id === id)
-}
-
-export function getGitHubSources(): GitHubSource[] {
- return GITHUB_SOURCES
-}
-
-export function getYouTubeSources(): YouTubeSource[] {
- return YOUTUBE_SOURCES
-}
-
-export function getSourcesByType<T extends Source['type']>(
- type: T
-): Extract<Source, { type: T }>[] {
- return SOURCES.filter((s) => s.type === type) as Extract<Source, { type: T }>[]
-}
diff --git a/apps/api/workflows/sync-docs/utils/types.ts b/apps/api/workflows/sync-docs/utils/types.ts
deleted file mode 100644
index 4f7cd95..0000000
--- a/apps/api/workflows/sync-docs/utils/types.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-/**
- * Base source interface
- */
-interface BaseSource {
- id: string
- label: string
- type: 'github' | 'youtube' | 'custom'
-}
-
-/**
- * GitHub documentation source
- */
-export interface GitHubSource extends BaseSource {
- type: 'github'
- repo: string
- branch: string
- contentPath: string
- outputPath?: string
- readmeOnly?: boolean
- additionalSyncs?: Array<{
- repo: string
- branch: string
- contentPath: string
- }>
-}
-
-/**
- * YouTube channel source
- */
-export interface YouTubeSource extends BaseSource {
- type: 'youtube'
- channelId: string
- handle?: string
- maxVideos?: number
-}
-
-/**
- * Custom source
- */
-export interface CustomSource extends BaseSource {
- type: 'custom'
- fetchFn: () => Promise<ContentFile[]>
-}
-
-export type Source = GitHubSource | YouTubeSource | CustomSource
-
-export interface ContentFile {
- path: string
- content: string
-}
-
-export interface SyncResult {
- sourceId: string
- success: boolean
- fileCount?: number
- error?: string
- duration?: number
-}
-
-export interface SnapshotConfig {
- repo: string
- branch: string
- token: string
- commitMessage?: string
-}
-
-export interface SyncConfig {
- githubToken: string
- snapshotRepo: string
- snapshotBranch: string
-}
-
-export interface SyncOptions {
- reset?: boolean
- push?: boolean
- sourceFilter?: string
-}
-
-export interface PushResult {
- success: boolean
- commitSha?: string
- filesChanged?: number
- error?: string
-}
diff --git a/packages/config/package.json b/packages/config/package.json
new file mode 100644
index 0000000..70630d2
--- /dev/null
+++ b/packages/config/package.json
@@ -0,0 +1,33 @@
+{
+ "name": "@savoir/config",
+ "version": "0.0.1",
+ "description": "Configuration loader and types for Savoir",
+ "type": "module",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "sideEffects": false,
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "tsdown",
+ "dev": "tsdown --watch",
+ "typecheck": "tsc --noEmit",
+ "prepublishOnly": "pnpm build"
+ },
+ "dependencies": {
+ "c12": "^3.0.4",
+ "zod": "^4.3.5"
+ },
+ "devDependencies": {
+ "@types/node": "^22.15.21",
+ "tsdown": "^0.12.4",
+ "typescript": "^5.8.3"
+ }
+}
diff --git a/packages/config/src/define.ts b/packages/config/src/define.ts
new file mode 100644
index 0000000..5a98668
--- /dev/null
+++ b/packages/config/src/define.ts
@@ -0,0 +1,9 @@
+import type { SavoirConfigInput } from './types'
+
+/**
+ * Define the Savoir configuration.
+ * Provides type safety and autocompletion in savoir.config.ts
+ */
+export function defineConfig(config: SavoirConfigInput): SavoirConfigInput {
+ return config
+}
diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts
new file mode 100644
index 0000000..43fc850
--- /dev/null
+++ b/packages/config/src/index.ts
@@ -0,0 +1,37 @@
+// Define helper
+export { defineConfig } from './define'
+
+// Loader
+export {
+ loadSavoirConfig,
+ setConfigCwd,
+ getSources,
+ getGitHubSources,
+ getYouTubeSources,
+ getCustomSources,
+ getSourceById,
+ getSourcesByType,
+} from './loader'
+export type { LoadOptions } from './loader'
+
+// Types
+export type {
+ // Input types (for config files)
+ SavoirConfigInput,
+ GitHubSourceInput,
+ YouTubeSourceInput,
+ CustomSourceInput,
+ // Normalized types (for runtime)
+ Source,
+ GitHubSource,
+ YouTubeSource,
+ CustomSource,
+ ContentFile,
+ LoadedConfig,
+ // Sync types
+ SyncResult,
+ SyncConfig,
+ SyncOptions,
+ PushResult,
+ SnapshotConfig,
+} from './types'
diff --git a/packages/config/src/loader.ts b/packages/config/src/loader.ts
new file mode 100644
index 0000000..13fba23
--- /dev/null
+++ b/packages/config/src/loader.ts
@@ -0,0 +1,110 @@
+import { loadConfig } from 'c12'
+import type {
+ SavoirConfigInput,
+ CustomSourceInput,
+ LoadedConfig,
+ Source,
+ GitHubSource,
+ YouTubeSource,
+ CustomSource,
+} from './types'
+import { validateConfig } from './validation'
+import { normalizeGitHubSource, normalizeYouTubeSource, normalizeCustomSource } from './normalize'
+
+let configCwd: string | undefined
+
+export interface LoadOptions {
+ cwd?: string
+}
+
+/**
+ * Load the Savoir configuration from savoir.config.{ts,js,json,yaml}
+ */
+export async function loadSavoirConfig(options?: LoadOptions): Promise<LoadedConfig> {
+ if (options?.cwd) {
+ configCwd = options.cwd
+ }
+
+ const { config } = await loadConfig<SavoirConfigInput>({
+ name: 'savoir',
+ cwd: configCwd,
+ defaults: {
+ sources: {
+ github: [],
+ youtube: [],
+ custom: [],
+ },
+ },
+ })
+
+ const validated = validateConfig(config)
+
+ const github = (validated.sources?.github ?? []).map(normalizeGitHubSource)
+ const youtube = (validated.sources?.youtube ?? []).map(normalizeYouTubeSource)
+ const custom = ((validated.sources?.custom ?? []) as CustomSourceInput[]).map(normalizeCustomSource)
+
+ return {
+ config: validated as SavoirConfigInput,
+ sources: [...github, ...youtube, ...custom] as Source[],
+ github,
+ youtube,
+ custom,
+ }
+}
+
+/**
+ * Set the config directory (call once at startup)
+ */
+export function setConfigCwd(cwd: string): void {
+ configCwd = cwd
+}
+
+/**
+ * Get all sources
+ */
+export async function getSources(): Promise<Source[]> {
+ const config = await loadSavoirConfig()
+ return config.sources
+}
+
+/**
+ * Get GitHub sources only
+ */
+export async function getGitHubSources(): Promise<GitHubSource[]> {
+ const config = await loadSavoirConfig()
+ return config.github
+}
+
+/**
+ * Get YouTube sources only
+ */
+export async function getYouTubeSources(): Promise<YouTubeSource[]> {
+ const config = await loadSavoirConfig()
+ return config.youtube
+}
+
+/**
+ * Get custom sources only
+ */
+export async function getCustomSources(): Promise<CustomSource[]> {
+ const config = await loadSavoirConfig()
+ return config.custom
+}
+
+/**
+ * Get a source by its ID
+ */
+export async function getSourceById(id: string): Promise<Source | undefined> {
+ const config = await loadSavoirConfig()
+ return config.sources.find(s => s.id === id)
+}
+
+/**
+ * Get sources filtered by type
+ */
+export async function getSourcesByType<T extends Source['type']>(
+ type: T
+): Promise<Extract<Source, { type: T }>[]> {
+ const config = await loadSavoirConfig()
+ return config.sources.filter(s => s.type === type) as Extract<Source, { type: T }>[]
+}
diff --git a/packages/config/src/normalize.ts b/packages/config/src/normalize.ts
new file mode 100644
index 0000000..aebb6a7
--- /dev/null
+++ b/packages/config/src/normalize.ts
@@ -0,0 +1,65 @@
+import type {
+ GitHubSourceInput,
+ YouTubeSourceInput,
+ CustomSourceInput,
+ GitHubSource,
+ YouTubeSource,
+ CustomSource,
+} from './types'
+
+/**
+ * Capitalize the first letter of each word
+ */
+function capitalize(str: string): string {
+ return str
+ .split('-')
+ .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+ .join(' ')
+}
+
+/**
+ * Normalize a GitHub source input by applying defaults
+ */
+export function normalizeGitHubSource(input: GitHubSourceInput): GitHubSource {
+ return {
+ type: 'github',
+ id: input.id,
+ label: input.label ?? capitalize(input.id),
+ repo: input.repo,
+ branch: input.branch ?? 'main',
+ contentPath: input.contentPath ?? 'docs',
+ outputPath: input.outputPath ?? input.id,
+ readmeOnly: input.readmeOnly ?? false,
+ additionalSyncs: (input.additionalSyncs ?? []).map(sync => ({
+ repo: sync.repo,
+ branch: sync.branch ?? 'main',
+ contentPath: sync.contentPath ?? '',
+ })),
+ }
+}
+
+/**
+ * Normalize a YouTube source input by applying defaults
+ */
+export function normalizeYouTubeSource(input: YouTubeSourceInput): YouTubeSource {
+ return {
+ type: 'youtube',
+ id: input.id,
+ label: input.label ?? capitalize(input.id),
+ channelId: input.channelId,
+ handle: input.handle,
+ maxVideos: input.maxVideos ?? 50,
+ }
+}
+
+/**
+ * Normalize a custom source input by applying defaults
+ */
+export function normalizeCustomSource(input: CustomSourceInput): CustomSource {
+ return {
+ type: 'custom',
+ id: input.id,
+ label: input.label ?? capitalize(input.id),
+ fetchFn: input.fetchFn,
+ }
+}
diff --git a/apps/api/lib/types.ts b/packages/config/src/types.ts
similarity index 56%
rename from apps/api/lib/types.ts
rename to packages/config/src/types.ts
index 4f7cd95..f0a65fe 100644
--- a/apps/api/lib/types.ts
+++ b/packages/config/src/types.ts
@@ -1,42 +1,75 @@
/**
- * Base source interface
+ * Input types for configuration (what users write in savoir.config.ts)
*/
+
+export interface GitHubSourceInput {
+ id: string
+ label?: string
+ repo: string
+ branch?: string
+ contentPath?: string
+ outputPath?: string
+ readmeOnly?: boolean
+ additionalSyncs?: Array<{
+ repo: string
+ branch?: string
+ contentPath?: string
+ }>
+}
+
+export interface YouTubeSourceInput {
+ id: string
+ label?: string
+ channelId: string
+ handle?: string
+ maxVideos?: number
+}
+
+export interface CustomSourceInput {
+ id: string
+ label?: string
+ fetchFn: () => Promise<ContentFile[]>
+}
+
+export interface SavoirConfigInput {
+ sources?: {
+ github?: GitHubSourceInput[]
+ youtube?: YouTubeSourceInput[]
+ custom?: CustomSourceInput[]
+ }
+}
+
+/**
+ * Normalized types (after defaults are applied)
+ */
+
interface BaseSource {
id: string
label: string
type: 'github' | 'youtube' | 'custom'
}
-/**
- * GitHub documentation source
- */
export interface GitHubSource extends BaseSource {
type: 'github'
repo: string
branch: string
contentPath: string
- outputPath?: string
- readmeOnly?: boolean
- additionalSyncs?: Array<{
+ outputPath: string
+ readmeOnly: boolean
+ additionalSyncs: Array<{
repo: string
branch: string
contentPath: string
}>
}
-/**
- * YouTube channel source
- */
export interface YouTubeSource extends BaseSource {
type: 'youtube'
channelId: string
handle?: string
- maxVideos?: number
+ maxVideos: number
}
-/**
- * Custom source
- */
export interface CustomSource extends BaseSource {
type: 'custom'
fetchFn: () => Promise<ContentFile[]>
@@ -49,6 +82,20 @@ export interface ContentFile {
content: string
}
+/**
+ * Loaded config result
+ */
+export interface LoadedConfig {
+ config: SavoirConfigInput
+ sources: Source[]
+ github: GitHubSource[]
+ youtube: YouTubeSource[]
+ custom: CustomSource[]
+}
+
+/**
+ * Sync-related types (re-exported for convenience)
+ */
export interface SyncResult {
sourceId: string
success: boolean
@@ -57,13 +104,6 @@ export interface SyncResult {
duration?: number
}
-export interface SnapshotConfig {
- repo: string
- branch: string
- token: string
- commitMessage?: string
-}
-
export interface SyncConfig {
githubToken: string
snapshotRepo: string
@@ -82,3 +122,10 @@ export interface PushResult {
filesChanged?: number
error?: string
}
+
+export interface SnapshotConfig {
+ repo: string
+ branch: string
+ token: string
+ commitMessage?: string
+}
diff --git a/packages/config/src/validation.ts b/packages/config/src/validation.ts
new file mode 100644
index 0000000..4b6a9de
--- /dev/null
+++ b/packages/config/src/validation.ts
@@ -0,0 +1,46 @@
+import { z } from 'zod'
+
+const AdditionalSyncSchema = z.object({
+ repo: z.string().min(1),
+ branch: z.string().optional(),
+ contentPath: z.string().optional(),
+})
+
+const GitHubSourceSchema = z.object({
+ id: z.string().min(1),
+ label: z.string().optional(),
+ repo: z.string().regex(/^[\w.-]+\/[\w.-]+$/, 'Must be in format owner/repo'),
+ branch: z.string().optional(),
+ contentPath: z.string().optional(),
+ outputPath: z.string().optional(),
+ readmeOnly: z.boolean().optional(),
+ additionalSyncs: z.array(AdditionalSyncSchema).optional(),
+})
+
+const YouTubeSourceSchema = z.object({
+ id: z.string().min(1),
+ label: z.string().optional(),
+ channelId: z.string().min(1),
+ handle: z.string().optional(),
+ maxVideos: z.number().int().positive().optional(),
+})
+
+const CustomSourceSchema = z.object({
+ id: z.string().min(1),
+ label: z.string().optional(),
+ fetchFn: z.any(),
+})
+
+const SavoirConfigSchema = z.object({
+ sources: z.object({
+ github: z.array(GitHubSourceSchema).optional(),
+ youtube: z.array(YouTubeSourceSchema).optional(),
+ custom: z.array(CustomSourceSchema).optional(),
+ }).optional(),
+})
+
+export type ValidatedConfig = z.infer<typeof SavoirConfigSchema>
+
+export function validateConfig(config: unknown): ValidatedConfig {
+ return SavoirConfigSchema.parse(config)
+}
diff --git a/packages/config/tsconfig.json b/packages/config/tsconfig.json
new file mode 100644
index 0000000..cb6ef60
--- /dev/null
+++ b/packages/config/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "declaration": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "noEmit": true
+ },
+ "include": ["src"]
+}
diff --git a/packages/config/tsdown.config.ts b/packages/config/tsdown.config.ts
new file mode 100644
index 0000000..03c2d29
--- /dev/null
+++ b/packages/config/tsdown.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+ entry: ['src/index.ts'],
+ format: ['esm'],
+ dts: {
+ sourcemap: false,
+ },
+ clean: true,
+ hash: false,
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fc5a327..d32e428 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -20,6 +20,9 @@ importers:
apps/api:
dependencies:
+ '@savoir/config':
+ specifier: workspace:*
+ version: link:../../packages/config
'@savoir/logger':
specifier: workspace:*
version: link:../../packages/logger
@@ -49,6 +52,25 @@ importers:
specifier: ^5.8.3
version: 5.9.3
+ packages/config:
+ dependencies:
+ c12:
+ specifier: ^3.0.4
+ version: 3.3.3
+ zod:
+ specifier: ^4.3.5
+ version: 4.3.5
+ devDependencies:
+ '@types/node':
+ specifier: ^22.15.21
+ version: 22.19.7
+ tsdown:
+ specifier: ^0.12.4
+ version: 0.12.9([email protected])
+ typescript:
+ specifier: ^5.8.3
+ version: 5.9.3
+
packages/logger:
devDependencies:
'@types/node':
diff --git a/savoir.config.ts b/savoir.config.ts
new file mode 100644
index 0000000..793b6ff
--- /dev/null
+++ b/savoir.config.ts
@@ -0,0 +1,58 @@
+import { defineConfig } from '@savoir/config'
+
+export default defineConfig({
+ sources: {
+ github: [
+ // Nuxt Core
+ {
+ id: 'nuxt',
+ label: 'Nuxt',
+ repo: 'nuxt/nuxt',
+ additionalSyncs: [
+ { repo: 'nuxt/nuxt.com', contentPath: 'content' },
+ ],
+ },
+ {
+ id: 'nitro',
+ label: 'Nitro',
+ repo: 'nitrojs/nitro',
+ branch: 'v3',
+ },
+
+ // Nuxt Modules
+ { id: 'nuxt-ui', label: 'Nuxt UI', repo: 'nuxt/ui', branch: 'v4', contentPath: 'docs/content' },
+ { id: 'nuxt-hub', label: 'NuxtHub', repo: 'nuxt-hub/core', contentPath: 'docs/content' },
+ { id: 'nuxt-content', label: 'Nuxt Content', repo: 'nuxt/content', contentPath: 'docs/content' },
+ { id: 'nuxt-image', label: 'Nuxt Image', repo: 'nuxt/image', contentPath: 'docs/content' },
+ { id: 'nuxt-i18n', label: 'Nuxt i18n', repo: 'nuxt-modules/i18n', contentPath: 'docs/content' },
+ { id: 'nuxt-scripts', label: 'Nuxt Scripts', repo: 'nuxt/scripts', contentPath: 'docs/content' },
+ { id: 'nuxt-fonts', label: 'Nuxt Fonts', repo: 'nuxt/fonts', contentPath: 'docs/content' },
+ { id: 'nuxt-eslint', label: 'Nuxt ESLint', repo: 'nuxt/eslint', contentPath: 'docs/content' },
+ { id: 'nuxt-devtools', label: 'Nuxt DevTools', repo: 'nuxt/devtools', contentPath: 'docs/content' },
+ { id: 'mcp-toolkit', label: 'MCP Toolkit', repo: 'nuxt-modules/mcp-toolkit', contentPath: 'apps/docs/content' },
+ { id: 'nuxt-studio', label: 'Nuxt Studio', repo: 'nuxt-content/nuxt-studio' },
+
+ // README-only
+ { id: 'nuxt-icon', label: 'Nuxt Icon', repo: 'nuxt/icon', readmeOnly: true },
+ { id: 'nuxt-auth-utils', label: 'Nuxt Auth Utils', repo: 'atinux/nuxt-auth-utils', readmeOnly: true },
+ { id: 'ofetch', label: 'ofetch', repo: 'unjs/ofetch', readmeOnly: true },
+ { id: 'nuxt-a11y', label: 'Nuxt a11y', repo: 'nuxt/a11y', readmeOnly: true },
+ { id: 'nuxt-hints', label: 'Nuxt Hints', repo: 'nuxt/hints', readmeOnly: true },
+
+ // UnJS
+ { id: 'h3', label: 'H3', repo: 'unjs/h3' },
+ { id: 'unstorage', label: 'unstorage', repo: 'unjs/unstorage' },
+ { id: 'unhead', label: 'Unhead', repo: 'unjs/unhead' },
+
+ // SEO
+ { id: 'nuxt-og-image', label: 'Nuxt OG Image', repo: 'nuxt-modules/og-image', contentPath: 'docs/content' },
+ { id: 'nuxt-sitemap', label: 'Nuxt Sitemap', repo: 'nuxt-modules/sitemap', contentPath: 'docs/content' },
+ { id: 'nuxt-robots', label: 'Nuxt Robots', repo: 'nuxt-modules/robots', contentPath: 'docs/content' },
+ ],
+
+ youtube: [
+ { id: 'alex-lichter', label: 'Alexander Lichter', channelId: 'UCqFPgMzGbLjd-MX-h3Z5aQA', handle: '@TheAlexLichter', maxVideos: 100 },
+ { id: 'learn-vue', label: 'LearnVue', channelId: 'UCGwuxdEeCf0TIA2RbPOj-8g', handle: '@LearnVue', maxVideos: 50 },
+ ],
+ },
+})