Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
feat: add github utils and snapshot repo management (#37)
Hugodf91db205a55
diff --git a/README.md b/README.mdindex c2eec4b..30f6727 100644--- a/README.md+++ b/README.md@@ -145,8 +145,8 @@ AI_GATEWAY_API_KEY=... # Vercel AI Gateway API keyNUXT_ADMIN_USERS=user1,user2 # Comma-separated admin emails/usernames# Sandbox-NUXT_GITHUB_TOKEN=ghp_... # GitHub token for repo access-NUXT_GITHUB_SNAPSHOT_REPO=org/repo # Snapshot repository (owner/repo)+# NUXT_GITHUB_SNAPSHOT_REPO=org/repo # Optional default (can be set from admin sandbox UI)+# NUXT_GITHUB_TOKEN=ghp_... # Optional fallback override (GitHub App is the default path)# SiteNUXT_PUBLIC_SITE_URL=https://... # Public URL of your instancediff --git a/apps/chat/.env.example b/apps/chat/.env.exampleindex d8962da..7316539 100644--- a/apps/chat/.env.example+++ b/apps/chat/.env.example@@ -21,9 +21,10 @@ AI_GATEWAY_API_KEY= # Vercel AI Gateway API key# --- Sandbox & Sync -----------------------------------------------------------NUXT_GITHUB_TOKEN= # GitHub personal access token (for cloning repos)-NUXT_GITHUB_SNAPSHOT_REPO= # Snapshot repository (owner/repo format)-NUXT_GITHUB_SNAPSHOT_BRANCH=main+# NUXT_GITHUB_SNAPSHOT_REPO= # Default snapshot repository (owner/repo format)+# NUXT_GITHUB_SNAPSHOT_BRANCH=main+# NUXT_GITHUB_TOKEN= # Optional PAT override for snapshot git operations+# # If omitted, Savoir uses GitHub App installation tokens# --- GitHub Bot (optional) ---------------------------------------------------diff --git a/apps/chat/app/components/ModalConfirm.vue b/apps/chat/app/components/ModalConfirm.vueindex 5f4dbb3..0b239ab 100644--- a/apps/chat/app/components/ModalConfirm.vue+++ b/apps/chat/app/components/ModalConfirm.vue@@ -1,8 +1,13 @@<script setup lang="ts">-defineProps<{+withDefaults(defineProps<{title: stringdescription: string-}>()+ confirmLabel?: string+ cancelLabel?: string+}>(), {+ confirmLabel: 'Delete',+ cancelLabel: 'Cancel',+})const emit = defineEmits<{ close: [boolean] }>()</script>@@ -18,11 +23,11 @@ const emit = defineEmits<{ close: [boolean] }>():dismissible="false"><template #footer>- <UButton label="Delete" @click="emit('close', true)" />+ <UButton :label="confirmLabel" @click="emit('close', true)" /><UButtoncolor="neutral"variant="ghost"- label="Cancel"+ :label="cancelLabel"@click="emit('close', false)"/></template>diff --git a/apps/chat/app/components/UserMenu.vue b/apps/chat/app/components/UserMenu.vueindex abe40ab..e8ff0e7 100644--- a/apps/chat/app/components/UserMenu.vue+++ b/apps/chat/app/components/UserMenu.vue@@ -75,7 +75,7 @@ const items = computed<DropdownMenuItem[][]>(() => {<template #content-top="{ sub }"><div v-if="!sub" class="px-1.5 pt-1.5 pb-0.5"><div class="flex items-center gap-2 px-1 py-0.5">- <UAvatar :src="user?.image" :alt="user?.name ?? user?.username" size="sm" />+ <UAvatar :src="user?.image || undefined" :alt="user?.name ?? user?.username ?? undefined" size="sm" /><div class="min-w-0 flex-1"><p class="text-xs font-medium text-highlighted truncate">{{ user?.name ?? user?.username }}diff --git a/apps/chat/app/composables/useChatMode.ts b/apps/chat/app/composables/useChatMode.tsindex 31e9c92..4b9e624 100644--- a/apps/chat/app/composables/useChatMode.ts+++ b/apps/chat/app/composables/useChatMode.ts@@ -1,4 +1,4 @@-export type ChatMode = 'chat' | 'admin'+import type { ChatMode } from '#shared/types/chat'const mode = ref<ChatMode>('chat')diff --git a/apps/chat/app/composables/useMarkdownToc.ts b/apps/chat/app/composables/useMarkdownToc.tsindex b945177..38d9144 100644--- a/apps/chat/app/composables/useMarkdownToc.ts+++ b/apps/chat/app/composables/useMarkdownToc.ts@@ -11,8 +11,8 @@ export function useMarkdownToc(content: string): TocLink[] {let matchwhile ((match = headingRegex.exec(content)) !== null) {- const depth = match[1].length- const text = match[2].trim()+ const depth = match[1]?.length ?? 0+ const text = match[2]?.trim() ?? ''const id = text.toLowerCase().replace(/[^\w\s-]/g, '')@@ -23,7 +23,7 @@ export function useMarkdownToc(content: string): TocLink[] {if (depth === 2) {links.push({ ...link, children: [] })} else if (depth === 3 && links.length > 0) {- links[links.length - 1].children!.push(link)+ links[links.length - 1]?.children?.push(link)}}diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.mdindex 33b97b7..56d6244 100644--- a/apps/chat/app/content/docs/bot-setup.md+++ b/apps/chat/app/content/docs/bot-setup.md@@ -37,6 +37,13 @@ Users can also install the app from the sidebar suggestion card or from the **SeThe app uses [installation access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) to interact with repositories -- no personal access token needed for the bot.+If you also use the snapshot repository management features in Savoir admin, extend app permissions with:++- **Contents (Read & Write)** to push synced docs and marker files+- **Administration (Read & Write)** when you want Savoir to create repositories automatically++`NUXT_GITHUB_TOKEN` remains optional fallback only and is not required for normal GitHub App-based setup.+## Trigger the BotMention the bot in any issue comment:diff --git a/apps/chat/app/content/docs/getting-started.md b/apps/chat/app/content/docs/getting-started.mdindex 00c0b1c..8b84e45 100644--- a/apps/chat/app/content/docs/getting-started.md+++ b/apps/chat/app/content/docs/getting-started.md@@ -18,8 +18,10 @@ cp apps/chat/.env.example apps/chat/.env| `NUXT_ADMIN_USERS` | Comma-separated list of admin emails or GitHub usernames || `NUXT_PUBLIC_SITE_URL` | Public URL of your Savoir instance || `AI_GATEWAY_API_KEY` | [Vercel AI Gateway](https://ai-sdk.dev) API key |-| `NUXT_GITHUB_TOKEN` | GitHub personal access token for cloning repos and accessing the snapshot repository |-| `NUXT_GITHUB_SNAPSHOT_REPO` | Snapshot repository in `owner/repo` format |++`NUXT_GITHUB_SNAPSHOT_REPO` and `NUXT_GITHUB_TOKEN` are optional. You can configure the snapshot repository in the admin sandbox UI after startup, and Savoir uses a GitHub App installation access token automatically when app credentials are configured.++`NUXT_GITHUB_TOKEN` is only a fallback. Keep it unset unless you explicitly need to override GitHub App authentication.### Optional (for bots)@@ -59,6 +61,15 @@ Savoir uses a single **GitHub App** for both **user authentication** (OAuth logi| Issues | Read & Write | Bot needs to read issues and post replies || Metadata | Read-only | Required by GitHub for all apps |+If you want Savoir to manage the snapshot repository automatically from the admin UI (list repos, create repo if missing, write sync commits), add:++| Permission | Access | Why |+|------------|--------|-----|+| Contents | Read & Write | Push synced content and maintain the Savoir marker file |+| Administration | Read & Write* | Needed when creating repositories automatically |++\* Depending on your GitHub setup (user vs org ownership), repository creation can require elevated app permissions and org approval.+### EventsSubscribe to these webhook events:@@ -82,6 +93,8 @@ From the app settings page, collect:Then install the app on the repositories where you want the bot to be active: **Install App** tab > select your repositories.+For automatic snapshot repository management, make sure the app is installed on the target owner (user/org) with the updated permissions above.+For more details on the bot behavior, see the [GitHub Bot documentation](/admin/docs/github-bot).## First Launch@@ -124,7 +137,7 @@ The app will be available at `http://localhost:3000`. Sign in with GitHub using## Adding Sources-Sources define the knowledge base the app uses to answer questions. They are managed through the **admin interface**.+Sources define the knowledge base the app uses to answer questions. They are managed through the **admin interface**. Sources aren't limited to documentation — you can add any content that produces files (GitHub repos, YouTube transcripts, custom APIs). See the [Sources documentation](https://github.com/vercel-labs/savoir/blob/main/docs/SOURCES.md) for all available options.1. Navigate to the admin panel at `/admin`2. Go to the Sources section@@ -149,7 +162,7 @@ Savoir uses a **file-based search** approach -- no embeddings or vector database3. The AI agent uses `bash` and `bash_batch` tools (via the [AI SDK](https://ai-sdk.dev)) to run `grep`, `find`, `cat`, etc. in the sandbox4. Results are synthesized into a natural language answer with citations-You can also integrate Savoir into your own applications using the [SDK](/admin/docs/sdk).+You can also integrate Savoir into your own applications using the [SDK](/admin/docs/sdk). For the full technical architecture, see the [Architecture documentation](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) on GitHub.## Admin Paneldiff --git a/apps/chat/app/pages/admin/logs.vue b/apps/chat/app/pages/admin/logs.vueindex aa58579..4d8d76f 100644--- a/apps/chat/app/pages/admin/logs.vue+++ b/apps/chat/app/pages/admin/logs.vue@@ -166,6 +166,7 @@ async function deleteLogs() {const levelLabel = selectedLevel.value ? ` (level: ${selectedLevel.value})` : ''const instance = deleteModal.open({+ title: 'Confirm deletion',description: `This will permanently delete ${previewCount.value.toLocaleString()} log entries older than ${activeValue.value} ${unitLabel.value}${activeValue.value === 1 ? '' : 's'}${levelLabel}. This cannot be undone.`,})const confirmed = await instance.resultdiff --git a/apps/chat/app/pages/admin/sandbox.vue b/apps/chat/app/pages/admin/sandbox.vueindex ec7b07f..6ff94be 100644--- a/apps/chat/app/pages/admin/sandbox.vue+++ b/apps/chat/app/pages/admin/sandbox.vue@@ -1,8 +1,14 @@<script setup lang="ts">import { formatDistanceToNow } from 'date-fns'+import { LazyModalConfirm } from '#components'useSeoMeta({ title: 'Sandbox - Admin' })+const toast = useToast()+const overlay = useOverlay()+const { showError } = useErrorToast()+const confirmModal = overlay.create(LazyModalConfirm, { destroyOnClose: true })+const {status,needsSync,@@ -12,7 +18,37 @@ const {syncNow,} = useSnapshotSync()-const { data: sources } = useLazyFetch('/api/sources')+const { data: snapshotConfig, refresh: refreshSnapshotConfig } = useLazyFetch('/api/snapshot/config')+const { fetchRepos } = useGitHub()+const { data: repoCatalog, status: repoCatalogStatus } = await fetchRepos()++const snapshotRepoInput = ref('')+const snapshotBranchInput = ref('main')+const isSavingConfig = ref(false)+const isRefreshingRepos = ref(false)+const selectedSuggestion = ref('')++const snapshotRepoUrl = computed(() => {+ const repo = snapshotConfig.value?.snapshotRepo?.trim()+ return repo ? `https://github.com/${repo}` : null+})++const filteredRepositorySuggestions = computed(() => {+ const repos = repoCatalog.value?.repositories || []+ return repos+})++const repositoryOptions = computed(() => {+ return filteredRepositorySuggestions.value.map(repo => ({+ label: repo.fullName,+ value: repo.fullName,+ }))+})++watch(snapshotConfig, (value) => {+ snapshotRepoInput.value = value?.snapshotRepo || ''+ snapshotBranchInput.value = value?.snapshotBranch || 'main'+}, { immediate: true })const createdAgo = computed(() => {if (!status.value?.latestCreatedAt) return null@@ -20,6 +56,96 @@ const createdAgo = computed(() => {})const isInitialLoading = computed(() => status.value === null)++async function saveSnapshotConfig() {+ isSavingConfig.value = true+ try {+ await persistSnapshotConfig(false)++ await Promise.all([+ refreshSnapshotConfig(),+ checkStatus(),+ ])++ toast.add({+ title: 'Snapshot repository updated',+ description: 'Repository is ready. The active snapshot cache was reset; run sync to build the first snapshot.',+ icon: 'i-lucide-check',+ })+ } catch (error) {+ const status = getHttpStatus(error)+ if (status === 409) {+ const confirmed = await confirmModal.open({+ title: 'Use existing repository?',+ description: 'This repository already exists and is not marked as managed by Savoir. Confirm only if you want Savoir to adopt it.',+ confirmLabel: 'Adopt repository',+ cancelLabel: 'Cancel',+ })++ if (confirmed) {+ try {+ await persistSnapshotConfig(true)+ await Promise.all([+ refreshSnapshotConfig(),+ checkStatus(),+ ])+ toast.add({+ title: 'Repository adopted',+ description: 'Savoir will now use this existing repository for snapshots.',+ icon: 'i-lucide-check',+ })+ return+ } catch (secondError) {+ showError(secondError, { fallback: 'Failed to adopt existing repository' })+ return+ }+ }+ return+ }++ showError(error, { fallback: 'Failed to update snapshot repository' })+ } finally {+ isSavingConfig.value = false+ }+}++function getHttpStatus(error: unknown): number | null {+ const maybe = error as { statusCode?: number, response?: { status?: number } }+ return maybe.statusCode || maybe.response?.status || null+}++async function persistSnapshotConfig(allowExistingRepo: boolean) {+ await $fetch('/api/snapshot/config', {+ method: 'PUT',+ body: {+ snapshotRepo: snapshotRepoInput.value,+ snapshotBranch: snapshotBranchInput.value,+ allowExistingRepo,+ },+ })+}++function selectSuggestedRepo(fullName: string) {+ snapshotRepoInput.value = fullName+ selectedSuggestion.value = fullName+}++async function reloadRepositories() {+ isRefreshingRepos.value = true+ try {+ const fresh = await fetchRepos({ force: true })+ if (fresh.data.value) {+ repoCatalog.value = fresh.data.value+ }+ } finally {+ isRefreshingRepos.value = false+ }+}++watch(selectedSuggestion, (value) => {+ if (!value) return+ snapshotRepoInput.value = value+})</script><template>@@ -33,6 +159,105 @@ const isInitialLoading = computed(() => status.value === null)</p></header>+ <section class="mb-8">+ <p class="text-[10px] text-muted mb-3 font-pixel tracking-wide uppercase">+ Snapshot Repository+ </p>+ <div class="rounded-lg border border-default p-4 space-y-4">+ <p class="text-xs text-muted">+ This repository stores the aggregated docs that snapshots are created from. If it doesn't exist, Savoir creates it automatically.+ </p>++ <div class="grid grid-cols-3 gap-3">+ <div class="col-span-2 flex flex-col gap-1.5">+ <label class="text-xs text-muted">Repository (owner/repo)</label>+ <UInput+ v-model="snapshotRepoInput"+ placeholder="your-org/your-snapshot-repo"+ icon="i-simple-icons-github"+ />+ </div>+ <div class="flex flex-col gap-1.5">+ <label class="text-xs text-muted">Branch</label>+ <UInput+ v-model="snapshotBranchInput"+ placeholder="main"+ icon="i-lucide-git-branch"+ />+ </div>+ </div>++ <div class="rounded-lg border border-default bg-elevated/30 p-3">+ <div class="flex items-center justify-between gap-2 mb-2">+ <p class="text-xs text-highlighted">+ Repository suggestions+ </p>+ <UTooltip text="Refresh repository list" :delay-open="150">+ <UButton+ size="xs"+ square+ icon="i-lucide-refresh-cw"+ color="neutral"+ variant="ghost"+ :loading="isRefreshingRepos || repoCatalogStatus === 'pending'"+ @click="reloadRepositories"+ />+ </UTooltip>+ </div>++ <p class="text-xs text-muted mb-2">+ Choose one from your accessible repositories, or type a new name above and Savoir will create it automatically.+ </p>++ <p+ v-if="repositoryOptions.length > 0"+ class="text-xs text-muted mb-2"+ >+ {{ repositoryOptions.length }} repositories available+ </p>++ <USelectMenu+ v-if="repositoryOptions.length > 0"+ v-model="selectedSuggestion"+ value-key="value"+ :items="repositoryOptions"+ :search-input="{ placeholder: 'Search repositories...' }"+ :virtualize="{ overscan: 16, estimateSize: 36 }"+ placeholder="Select a repository..."+ icon="i-simple-icons-github"+ />++ <div+ v-else-if="repoCatalogStatus !== 'pending' && repoCatalogStatus !== 'idle'"+ class="text-xs text-muted rounded-md border border-default bg-default px-3 py-2"+ >+ No repositories found with current GitHub credentials. You can still type a new `owner/repo` and save.+ </div>+ </div>++ <div class="flex items-center gap-2">+ <UButton+ size="xs"+ :loading="isSavingConfig"+ @click="saveSnapshotConfig"+ >+ Save+ </UButton>+ <UButton+ v-if="snapshotRepoUrl"+ icon="i-simple-icons-github"+ color="neutral"+ variant="ghost"+ size="xs"+ :to="snapshotRepoUrl"+ target="_blank"+ >+ Open Repository+ </UButton>+ </div>+ </div>+ </section>+<section class="mb-8"><p class="text-[10px] text-muted mb-3 font-pixel tracking-wide uppercase">Current Snapshot@@ -54,13 +279,13 @@ const isInitialLoading = computed(() => status.value === null){{ status.currentSnapshotId }}</p><UButton- v-if="sources?.snapshotRepoUrl"+ v-if="snapshotRepoUrl"icon="i-simple-icons-github"color="neutral"variant="link"size="xs"class="-ml-1.5"- :to="sources.snapshotRepoUrl"+ :to="snapshotRepoUrl"target="_blank">Open Repository@@ -115,7 +340,7 @@ const isInitialLoading = computed(() => status.value === null)variant="ghost"size="xs":loading="isLoading"- @click="checkStatus"+ @click="() => checkStatus()">Refresh</UButton>@@ -123,7 +348,7 @@ const isInitialLoading = computed(() => status.value === null)v-if="needsSync"size="xs":loading="isSyncing"- @click="syncNow"+ @click="() => syncNow()">Sync now</UButton>diff --git a/apps/chat/app/pages/admin/users.vue b/apps/chat/app/pages/admin/users.vueindex fd2ba32..3c72a3f 100644--- a/apps/chat/app/pages/admin/users.vue+++ b/apps/chat/app/pages/admin/users.vue@@ -27,13 +27,13 @@ const draftRoles = ref<Record<string, UserRole>>({})const roleOptions = [{ label: 'User', value: 'user' },{ label: 'Admin', value: 'admin' },-] as const+]const filterOptions = [{ label: 'All roles', value: 'all' },{ label: 'Admins', value: 'admin' },{ label: 'Users', value: 'user' },-] as const+]const { data: users, refresh, status } = useLazyFetch<AdminUserRow[]>('/api/admin/users')diff --git a/apps/chat/nuxt.config.ts b/apps/chat/nuxt.config.tsindex 62b3512..24456e5 100644--- a/apps/chat/nuxt.config.ts+++ b/apps/chat/nuxt.config.ts@@ -1,5 +1,7 @@// https://nuxt.com/docs/api/configuration/nuxt-configexport default defineNuxtConfig({+ extends: ['../../packages/github'],+modules: ['@nuxt/ui','@nuxtjs/mdc',@@ -105,7 +107,8 @@ export default defineNuxtConfig({hub: {db: 'postgresql',kv: true,- blob: true+ blob: true,+ cache: true},ssr: false,@@ -122,7 +125,7 @@ export default defineNuxtConfig({// Webhook routes should never be cached'/api/webhooks/**': { isr: false, cache: false },// Admin pages are behind auth- '/admin/**': { auth: { user: { role: 'admin' } } },+ '/admin/**': { auth: { user: { role: 'admin' } as any } },},runtimeConfig: {diff --git a/apps/chat/package.json b/apps/chat/package.jsonindex d83a2b6..48a8307 100644--- a/apps/chat/package.json+++ b/apps/chat/package.json@@ -33,10 +33,9 @@"@nuxt/ui": "^4.4.0","@nuxthub/core": "^0.10.6","@nuxtjs/mdc": "^0.20.1",- "@octokit/auth-app": "^8.2.0",- "@octokit/rest": "^22.0.1","@onmax/nuxt-better-auth": "0.0.2-alpha.21","@savoir/agent": "workspace:*",+ "@savoir/github": "workspace:*","@savoir/sdk": "workspace:*","@shelve/cli": "^4.1.7","@upstash/redis": "^1.36.2",diff --git a/apps/chat/server/api/chats/[id].post.ts b/apps/chat/server/api/chats/[id].post.tsindex ad1da3f..b5a860d 100644--- a/apps/chat/server/api/chats/[id].post.ts+++ b/apps/chat/server/api/chats/[id].post.ts@@ -74,7 +74,7 @@ export default defineEventHandler(async (event) => {})}- const config = useRuntimeConfig()+ const config = useRuntimeConfig() as anylet stepCount = 0let toolCallCount = 0diff --git a/apps/chat/server/api/sandbox/snapshot.post.ts b/apps/chat/server/api/sandbox/snapshot.post.tsindex 5dc786f..6b43b19 100644--- a/apps/chat/server/api/sandbox/snapshot.post.ts+++ b/apps/chat/server/api/sandbox/snapshot.post.ts@@ -1,15 +1,17 @@import { start } from 'workflow/api'import { createSnapshot } from '../../workflows/create-snapshot'+import { getSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'export default defineEventHandler(async (event) => {const requestLog = useLogger(event)const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()await start(createSnapshot, [{- githubToken: config.github.token,- snapshotRepo: config.github.snapshotRepo,- snapshotBranch: config.github.snapshotBranch,+ githubToken: await getSnapshotToken(),+ snapshotRepo: snapshotConfig.snapshotRepo,+ snapshotBranch: snapshotConfig.snapshotBranch,}])diff --git a/apps/chat/server/api/shared/[token].get.ts b/apps/chat/server/api/shared/[token].get.tsindex fde3e03..946ff85 100644--- a/apps/chat/server/api/shared/[token].get.ts+++ b/apps/chat/server/api/shared/[token].get.ts@@ -30,10 +30,10 @@ export default defineCachedEventHandler(})}- const user = await db.select({+ const [user] = await db.select({name: schema.user.name,image: schema.user.image,- }).from(schema.user).where(eq(schema.user.id, chat.userId)).get()+ }).from(schema.user).where(eq(schema.user.id, chat.userId)).limit(1)setHeader(event, 'Cache-Control', 's-maxage=300, stale-while-revalidate=3600')diff --git a/apps/chat/server/api/snapshot/config.get.ts b/apps/chat/server/api/snapshot/config.get.tsnew file mode 100644index 0000000..187327a--- /dev/null+++ b/apps/chat/server/api/snapshot/config.get.ts@@ -0,0 +1,11 @@+import { getSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'+import { requireAdmin } from '../../utils/admin'++/**+ * GET /api/snapshot/config+ * Returns the configured snapshot repository (admin only).+ */+export default defineEventHandler(async (event) => {+ await requireAdmin(event)+ return await getSnapshotRepoConfig()+})diff --git a/apps/chat/server/api/snapshot/config.put.ts b/apps/chat/server/api/snapshot/config.put.tsnew file mode 100644index 0000000..2279794--- /dev/null+++ b/apps/chat/server/api/snapshot/config.put.ts@@ -0,0 +1,75 @@+import { kv } from '@nuxthub/kv'+import { z } from 'zod'+import { getSnapshotRepoConfig, setSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'+import { KV_KEYS } from '../../utils/sandbox/types'+import { requireAdmin } from '../../utils/admin'++const bodySchema = z.object({+ snapshotRepo: z.string().min(1),+ snapshotBranch: z.string().optional(),+ allowExistingRepo: z.boolean().optional(),+})++/**+ * PUT /api/snapshot/config+ * Updates snapshot repository settings (admin only).+ */+export default defineEventHandler(async (event) => {+ const requestLog = useLogger(event)+ await requireAdmin(event)+ const body = await readValidatedBody(event, data => bodySchema.parse(data))+ const config = useRuntimeConfig()++ const snapshotRepo = body.snapshotRepo.trim()+ const snapshotBranch = body.snapshotBranch?.trim() || 'main'++ const token = await getSnapshotToken()+ if (!token) {+ throw createError({+ statusCode: 400,+ message: 'GitHub token not found',+ })+ }++ const ensuredRepo = await ensureSnapshotRepo({+ repoPath: snapshotRepo,+ branch: snapshotBranch,+ allowExisting: body.allowExistingRepo === true,+ token,+ })++ const previous = await getSnapshotRepoConfig()+ const next = await setSnapshotRepoConfig({+ snapshotRepo,+ snapshotBranch,+ })++ const changed = previous.snapshotRepo !== next.snapshotRepo || previous.snapshotBranch !== next.snapshotBranch++ if (changed) {+ await Promise.all([+ kv.del(KV_KEYS.CURRENT_SNAPSHOT),+ kv.del(KV_KEYS.SNAPSHOT_STATUS_CACHE),+ kv.del(KV_KEYS.ACTIVE_SANDBOX_SESSION),+ ])+ }++ requestLog.set({+ snapshotRepo: next.snapshotRepo,+ snapshotBranch: next.snapshotBranch,+ repositoryEnsured: ensuredRepo.repository.fullName,+ repositoryCreated: ensuredRepo.created,+ repositoryAdoptedExisting: ensuredRepo.adoptedExisting,+ changed,+ })++ return {+ success: true,+ ...next,+ repositoryEnsured: ensuredRepo.repository.fullName,+ repositoryUrl: ensuredRepo.repository.htmlUrl,+ repositoryCreated: ensuredRepo.created,+ repositoryAdoptedExisting: ensuredRepo.adoptedExisting,+ changed,+ }+})diff --git a/apps/chat/server/api/sources/index.get.ts b/apps/chat/server/api/sources/index.get.tsindex 97cfb81..4f739aa 100644--- a/apps/chat/server/api/sources/index.get.ts+++ b/apps/chat/server/api/sources/index.get.ts@@ -2,6 +2,7 @@ import { kv } from '@nuxthub/kv'import { db, schema } from '@nuxthub/db'import { asc } from 'drizzle-orm'import { KV_KEYS } from '../../utils/sandbox/types'+import { getSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'/*** GET /api/sources@@ -13,21 +14,24 @@ export default defineEventHandler(async () => {const config = useRuntimeConfig()const hasYouTubeApiKey = !!config.youtube?.apiKey- const [allSources, lastSyncAt] = await Promise.all([+ const [allSources, lastSyncAt, snapshotConfig] = await Promise.all([db.select().from(schema.sources).orderBy(asc(schema.sources.label)),kv.get<number>(KV_KEYS.LAST_SOURCE_SYNC),+ getSnapshotRepoConfig(),])const github = allSources.filter(s => s.type === 'github')const youtube = hasYouTubeApiKey ? allSources.filter(s => s.type === 'youtube') : []- const snapshotRepo = config.github?.snapshotRepo || null+ const snapshotRepo = snapshotConfig.snapshotRepo || null+ const snapshotBranch = snapshotConfig.snapshotBranch || 'main'return {total: github.length + youtube.length,lastSyncAt,youtubeEnabled: hasYouTubeApiKey,snapshotRepo,+ snapshotBranch,snapshotRepoUrl: snapshotRepo ? `https://github.com/${snapshotRepo}` : null,github: {count: github.length,diff --git a/apps/chat/server/api/sync/[source].post.ts b/apps/chat/server/api/sync/[source].post.tsindex 82fff3b..e73d923 100644--- a/apps/chat/server/api/sync/[source].post.ts+++ b/apps/chat/server/api/sync/[source].post.ts@@ -4,6 +4,7 @@ import { eq } from 'drizzle-orm'import { db, schema } from '@nuxthub/db'import { syncDocumentation } from '../../workflows/sync-docs'import type { Source } from '../../workflows/sync-docs'+import { getSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'const paramsSchema = z.object({source: z.string().min(1),@@ -19,6 +20,7 @@ export default defineEventHandler(async (event) => {const { source: sourceId } = await getValidatedRouterParams(event, paramsSchema.parse)requestLog.set({ sourceId })const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()const dbSource = await db.query.sources.findFirst({where: eq(schema.sources.id, sourceId),@@ -60,10 +62,10 @@ export default defineEventHandler(async (event) => {}const syncConfig = {- githubToken: config.github.token,+ githubToken: await getSnapshotToken(),youtubeApiKey: config.youtube?.apiKey,- snapshotRepo: config.github.snapshotRepo,- snapshotBranch: config.github.snapshotBranch,+ snapshotRepo: snapshotConfig.snapshotRepo,+ snapshotBranch: snapshotConfig.snapshotBranch,}await start(syncDocumentation, [syncConfig, [source]])diff --git a/apps/chat/server/api/sync/index.post.ts b/apps/chat/server/api/sync/index.post.tsindex 659f6bd..464194a 100644--- a/apps/chat/server/api/sync/index.post.ts+++ b/apps/chat/server/api/sync/index.post.ts@@ -5,6 +5,7 @@ import { db } from '@nuxthub/db'import { syncDocumentation } from '../../workflows/sync-docs'import type { Source } from '../../workflows/sync-docs'import { KV_KEYS } from '../../utils/sandbox/types'+import { getSnapshotRepoConfig } from '../../utils/sandbox/snapshot-config'const bodySchema = z.object({@@ -24,6 +25,7 @@ export default defineEventHandler(async (event) => {await requireAdmin(event)const body = await readValidatedBody(event, data => bodySchema.parse(data))const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()requestLog.set({ sourceFilter: body?.sourceFilter })@@ -77,10 +79,10 @@ export default defineEventHandler(async (event) => {}const syncConfig = {- githubToken: config.github.token,+ githubToken: await getSnapshotToken(),youtubeApiKey: config.youtube?.apiKey,- snapshotRepo: config.github.snapshotRepo,- snapshotBranch: config.github.snapshotBranch,+ snapshotRepo: snapshotConfig.snapshotRepo,+ snapshotBranch: snapshotConfig.snapshotBranch,}await start(syncDocumentation, [syncConfig, sources])diff --git a/apps/chat/server/api/upload/[chatId].put.ts b/apps/chat/server/api/upload/[chatId].put.tsindex 256ac45..b6ef4d9 100644--- a/apps/chat/server/api/upload/[chatId].put.ts+++ b/apps/chat/server/api/upload/[chatId].put.ts@@ -80,7 +80,7 @@ export default defineEventHandler(async (event) => {filename: field.filename,})- const pathname = generatePathname(user.username, chatId, processed.filename)+ const pathname = generatePathname(user.username ?? user.id, chatId, processed.filename)const result = await blob.put(pathname, processed.buffer, { contentType: processed.type })return {diff --git a/apps/chat/server/auth.config.ts b/apps/chat/server/auth.config.tsindex 5ca5a3d..4ba21f3 100644--- a/apps/chat/server/auth.config.ts+++ b/apps/chat/server/auth.config.ts@@ -1,6 +1,7 @@import { admin, apiKey } from 'better-auth/plugins'import { schema } from '@nuxthub/db'import { eq } from 'drizzle-orm'+import { defineServerAuth } from '@onmax/nuxt-better-auth/config'export default defineServerAuth(({ runtimeConfig, db }) => {const adminUsers = runtimeConfig.adminUsers?.split(',').map((s: string) => s.trim().toLowerCase()).filter(Boolean) || []diff --git a/apps/chat/server/utils/bot/adapters/github.ts b/apps/chat/server/utils/bot/adapters/github.tsindex 837afe1..5890ed4 100644--- a/apps/chat/server/utils/bot/adapters/github.ts+++ b/apps/chat/server/utils/bot/adapters/github.ts@@ -1,5 +1,5 @@import { createHmac, timingSafeEqual } from 'node:crypto'-import { createAppAuth } from '@octokit/auth-app'+import { getAppTokenForRepo } from '@savoir/github/server/utils'import { Octokit } from '@octokit/rest'import { Message, parseMarkdown, stringifyMarkdown, type Adapter, type AdapterPostableMessage, type RawMessage, type WebhookOptions, type FetchResult, type ThreadInfo, type FormattedContent, type ChatInstance } from 'chat'import { createError, log } from 'evlog'@@ -114,27 +114,21 @@ export class SavoirGitHubAdapter implements Adapter<GitHubThreadId, GitHubRawMesreturn cached.octokit}- const auth = createAppAuth({+ const token = await getAppTokenForRepo({appId: this.appId,- privateKey: this.privateKey,+ appPrivateKey: this.privateKey,+ repoPath: cacheKey,})- const appOctokit = new Octokit({ authStrategy: createAppAuth, auth: { appId: this.appId, privateKey: this.privateKey } })-- let installation- try {- const result = await appOctokit.apps.getRepoInstallation({ owner, repo })- installation = result.data- } catch (error) {+ if (!token) {throw createError({+ status: 403,message: `GitHub App not installed on ${cacheKey}`,- why: error instanceof Error ? error.message : 'Failed to get installation',+ why: 'Failed to get installation token for this repository',fix: `Install the GitHub App on the repository ${cacheKey} from the app settings page`,})}- const { token } = await auth({ type: 'installation', installationId: installation.id })-const octokit = new Octokit({ auth: token })this.octokitCache.set(cacheKey, { octokit, expiresAt: Date.now() + 50 * 60 * 1000 })@@ -142,7 +136,6 @@ export class SavoirGitHubAdapter implements Adapter<GitHubThreadId, GitHubRawMeslog.info({event: 'github.octokit.created',repo: cacheKey,- installationId: installation.id,})return octokit@@ -522,9 +515,10 @@ export class SavoirGitHubAdapter implements Adapter<GitHubThreadId, GitHubRawMesconst match = threadId.match(/^github:([^/]+)\/([^:]+):issue:(\d+)$/)if (!match || !match[1] || !match[2] || !match[3]) {throw createError({- message: 'Invalid GitHub thread ID',status: 400,+ message: 'Invalid GitHub thread ID',why: `Thread ID "${threadId}" does not match expected format github:{owner}/{repo}:issue:{number}`,+ fix: 'Use a thread ID from a GitHub issue comment or issue webhook',})}diff --git a/apps/chat/server/utils/github-auth.ts b/apps/chat/server/utils/github-auth.tsnew file mode 100644index 0000000..8e9e57f--- /dev/null+++ b/apps/chat/server/utils/github-auth.ts@@ -0,0 +1,12 @@+import { getToken, resolveGitHubAuth } from '@savoir/github/server/utils'+import { getSnapshotRepoConfig } from './sandbox/snapshot-config'++export async function getSnapshotToken(): Promise<string | undefined> {+ const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()++ const auth = resolveGitHubAuth(config.github)+ if (!auth) return undefined++ return getToken(auth, snapshotConfig.snapshotRepo)+}diff --git a/apps/chat/server/utils/model-pricing.ts b/apps/chat/server/utils/model-pricing.tsindex 3ab7f9e..78e60c2 100644--- a/apps/chat/server/utils/model-pricing.ts+++ b/apps/chat/server/utils/model-pricing.ts@@ -10,7 +10,7 @@ type PricingRecord = Record<string, ModelPricing>export const getModelPricingMap = defineCachedFunction(async (): Promise<PricingRecord> => {try {- const config = useRuntimeConfig()+ const config = useRuntimeConfig() as anyconst gateway = createGateway({ apiKey: config.savoir?.apiKey })const { models } = await gateway.getAvailableModels()diff --git a/apps/chat/server/utils/sandbox/manager.ts b/apps/chat/server/utils/sandbox/manager.tsindex e7afe19..44e249a 100644--- a/apps/chat/server/utils/sandbox/manager.ts+++ b/apps/chat/server/utils/sandbox/manager.ts@@ -3,16 +3,18 @@ import { createError, log } from 'evlog'import type { ActiveSandbox, SandboxManagerConfig, SnapshotMetadata } from './types'import { getCurrentSnapshot, setCurrentSnapshot } from './snapshot'import { deleteSandboxSession, generateSessionId, getSandboxSession, setSandboxSession, touchSandboxSession } from './session'+import { getSnapshotRepoConfig } from './snapshot-config'const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000const SANDBOX_TIMEOUT_MS = 5 * 60 * 1000-function getConfig(): SandboxManagerConfig {+async function getConfig(): Promise<SandboxManagerConfig> {const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()return {- githubToken: config.github.token,- snapshotRepo: config.github.snapshotRepo,- snapshotBranch: config.github.snapshotBranch,+ githubToken: await getSnapshotToken(),+ snapshotRepo: snapshotConfig.snapshotRepo,+ snapshotBranch: snapshotConfig.snapshotBranch,sessionTtlMs: DEFAULT_SESSION_TTL_MS,}}@@ -62,7 +64,7 @@ async function getSandboxById(sandboxId: string): Promise<Sandbox | null> {}export async function createSnapshotFromRepo(repoUrl: string, branch: string = 'main'): Promise<string> {- const config = getConfig()+ const config = await getConfig()log.info('sandbox', `Creating sandbox from repo: ${repoUrl}#${branch}`)@@ -81,7 +83,7 @@ export async function createSnapshotFromRepo(repoUrl: string, branch: string = '}async function getOrCreateSnapshot(): Promise<string> {- const config = getConfig()+ const config = await getConfig()const snapshot = await getCurrentSnapshot()if (snapshot) {@@ -91,8 +93,8 @@ async function getOrCreateSnapshot(): Promise<string> {if (!config.snapshotRepo) {throw createError({message: 'No snapshot available',- why: 'NUXT_GITHUB_SNAPSHOT_REPO environment variable is not configured',- fix: 'Set NUXT_GITHUB_SNAPSHOT_REPO to your snapshot repository',+ why: 'No snapshot repository is configured',+ fix: 'Set the snapshot repository in the admin sandbox settings (or NUXT_GITHUB_SNAPSHOT_REPO)',})}@@ -126,7 +128,7 @@ async function findRunningSandbox(snapshotId: string): Promise<Sandbox | null> {}export async function getOrCreateSandbox(sessionId?: string): Promise<ActiveSandbox> {- const config = getConfig()+ const config = await getConfig()const startTime = Date.now()// 1. Try to reconnect via session ID (fastest path)diff --git a/apps/chat/server/utils/sandbox/snapshot-config.ts b/apps/chat/server/utils/sandbox/snapshot-config.tsnew file mode 100644index 0000000..08d89ff--- /dev/null+++ b/apps/chat/server/utils/sandbox/snapshot-config.ts@@ -0,0 +1,65 @@+import { kv } from '@nuxthub/kv'+import { createError } from 'evlog'+import { KV_KEYS } from './types'++export interface SnapshotRepoConfig {+ snapshotRepo: string+ snapshotBranch: string+}++const SNAPSHOT_REPO_REGEX = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/++function normalizeSnapshotRepo(value?: string | null): string {+ return (value || '').trim()+}++function normalizeSnapshotBranch(value?: string | null): string {+ const branch = (value || '').trim()+ return branch || 'main'+}++export function isValidSnapshotRepo(repo: string): boolean {+ return SNAPSHOT_REPO_REGEX.test(repo)+}++function validateSnapshotRepo(repo: string): void {+ if (!isValidSnapshotRepo(repo)) {+ throw createError({+ status: 400,+ message: 'Invalid snapshot repository format',+ why: `Expected "owner/repo", received "${repo}"`,+ fix: 'Use the owner/repository format (for example: vercel-labs/savoir-snapshot)',+ })+ }+}++export async function getSnapshotRepoConfig(): Promise<SnapshotRepoConfig> {+ const runtimeConfig = useRuntimeConfig()+ const stored = await kv.get<Partial<SnapshotRepoConfig>>(KV_KEYS.SNAPSHOT_REPO_CONFIG)++ const snapshotRepo = normalizeSnapshotRepo(stored?.snapshotRepo || runtimeConfig.github?.snapshotRepo)+ const snapshotBranch = normalizeSnapshotBranch(stored?.snapshotBranch || runtimeConfig.github?.snapshotBranch)++ return {+ snapshotRepo,+ snapshotBranch,+ }+}++export async function setSnapshotRepoConfig(input: {+ snapshotRepo: string+ snapshotBranch?: string+}): Promise<SnapshotRepoConfig> {+ const snapshotRepo = normalizeSnapshotRepo(input.snapshotRepo)+ const snapshotBranch = normalizeSnapshotBranch(input.snapshotBranch)++ validateSnapshotRepo(snapshotRepo)++ const nextConfig: SnapshotRepoConfig = {+ snapshotRepo,+ snapshotBranch,+ }++ await kv.set(KV_KEYS.SNAPSHOT_REPO_CONFIG, nextConfig)+ return nextConfig+}diff --git a/apps/chat/server/utils/sandbox/snapshot-repo.ts b/apps/chat/server/utils/sandbox/snapshot-repo.tsnew file mode 100644index 0000000..b440a1a--- /dev/null+++ b/apps/chat/server/utils/sandbox/snapshot-repo.ts@@ -0,0 +1,103 @@+import { createError } from 'evlog'+import { getRepo, createRepo, ensureBranch, getFile, createOrUpdateFile, isNotFoundError, type RepoInfo, parseRepoPath } from '@savoir/github/server/utils'++const SAVOIR_MARKER_PATH = '.savoir/snapshot-repo.json'+const SAVOIR_MARKER_VERSION = 1++export async function hasSavoirMarker(+ token: string,+ repoPath: string,+ branch: string,+): Promise<boolean> {+ const { owner, repo } = parseRepoPath(repoPath)+ const file = await getFile(owner, repo, SAVOIR_MARKER_PATH, token, { ref: branch })+ return file !== null+}++export async function ensureSavoirMarker(+ token: string,+ repoPath: string,+ branch: string,+): Promise<void> {+ const { owner, repo } = parseRepoPath(repoPath)+ const markerContent = {+ managedBy: 'savoir',+ version: SAVOIR_MARKER_VERSION,+ createdAt: new Date().toISOString(),+ }++ const existing = await getFile(owner, repo, SAVOIR_MARKER_PATH, token, { ref: branch })++ await createOrUpdateFile(+ owner,+ repo,+ SAVOIR_MARKER_PATH,+ JSON.stringify(markerContent, null, 2),+ token,+ {+ branch,+ message: existing+ ? 'chore: refresh savoir snapshot marker'+ : 'chore: initialize savoir snapshot marker',+ sha: existing?.sha,+ },+ )+}++export interface EnsureSnapshotRepoResult {+ repository: RepoInfo+ created: boolean+ adoptedExisting: boolean+}++export async function ensureSnapshotRepo(options: {+ repoPath: string+ branch?: string+ allowExisting?: boolean+ token: string+}): Promise<EnsureSnapshotRepoResult> {+ const repoPath = options.repoPath.trim()+ const branch = (options.branch || 'main').trim() || 'main'+ const allowExisting = options.allowExisting === true+ const { token } = options++ const { owner, repo } = parseRepoPath(repoPath)++ try {+ const repository = await getRepo(owner, repo, token)++ await ensureBranch(owner, repo, branch, token)+ const hasMarker = await hasSavoirMarker(token, repoPath, branch)++ if (!hasMarker && !allowExisting) {+ throw createError({+ status: 409,+ message: 'Repository already exists and is not managed by Savoir',+ why: `The repository ${repoPath} exists but has no ${SAVOIR_MARKER_PATH} marker`,+ fix: 'Confirm adoption explicitly, or choose a new repository name',+ })+ }++ if (!hasMarker) {+ await ensureSavoirMarker(token, repoPath, branch)+ }++ return {+ repository,+ created: false,+ adoptedExisting: !hasMarker,+ }+ } catch (error: unknown) {+ if (!isNotFoundError(error)) throw error+ }++ const createdRepo = await createRepo({ name: repo, owner }, token)+ await ensureBranch(owner, repo, branch, token)+ await ensureSavoirMarker(token, repoPath, branch)++ return {+ repository: createdRepo,+ created: true,+ adoptedExisting: false,+ }+}diff --git a/apps/chat/server/utils/sandbox/snapshot-sync.ts b/apps/chat/server/utils/sandbox/snapshot-sync.tsindex c5d19ee..d0020f5 100644--- a/apps/chat/server/utils/sandbox/snapshot-sync.ts+++ b/apps/chat/server/utils/sandbox/snapshot-sync.ts@@ -1,9 +1,11 @@import { kv } from '@nuxthub/kv'import { Snapshot } from '@vercel/sandbox'import { createError } from 'evlog'-import type { SnapshotMetadata, SnapshotSyncStatus } from './types'+import type { SnapshotMetadata } from './types'import { KV_KEYS } from './types'import { getCurrentSnapshot, setCurrentSnapshot } from './snapshot'+import { getSnapshotRepoConfig } from './snapshot-config'+import type { SnapshotSyncStatus } from '#shared/types/snapshot'const CACHE_TTL_MS = 60 * 1000@@ -83,6 +85,7 @@ export async function syncToSnapshot(snapshotId?: string): Promise<SnapshotMetadconst latest = await getLatestSnapshot()if (!latest) {throw createError({+ status: 503,message: 'No snapshots available to sync to',why: 'No valid snapshots exist on the Vercel sandbox platform',fix: 'Run the sync workflow to create a snapshot first',@@ -92,12 +95,12 @@ export async function syncToSnapshot(snapshotId?: string): Promise<SnapshotMetad}const snapshot = await Snapshot.get({ snapshotId: targetSnapshotId })- const config = useRuntimeConfig()+ const snapshotConfig = await getSnapshotRepoConfig()const metadata: SnapshotMetadata = {snapshotId: snapshot.snapshotId,createdAt: Date.now(),- sourceRepo: config.github.snapshotRepo || '',+ sourceRepo: snapshotConfig.snapshotRepo || '',}await setCurrentSnapshot(metadata)diff --git a/apps/chat/server/utils/sandbox/types.ts b/apps/chat/server/utils/sandbox/types.tsindex 4eb7690..8e692d9 100644--- a/apps/chat/server/utils/sandbox/types.ts+++ b/apps/chat/server/utils/sandbox/types.ts@@ -31,6 +31,7 @@ export interface ActiveSandbox {export const KV_KEYS = {CURRENT_SNAPSHOT: 'snapshot:current',SNAPSHOT_STATUS_CACHE: 'snapshot:status-cache',+ SNAPSHOT_REPO_CONFIG: 'snapshot:repo-config',LAST_SOURCE_SYNC: 'sources:last-sync',AGENT_CONFIG_CACHE: 'agent:config-cache',session: (sessionId: string) => `session:${sessionId}`,diff --git a/apps/chat/server/workflows/create-snapshot/workflow.ts b/apps/chat/server/workflows/create-snapshot/workflow.tsindex 8c3c356..3442dd0 100644--- a/apps/chat/server/workflows/create-snapshot/workflow.ts+++ b/apps/chat/server/workflows/create-snapshot/workflow.ts@@ -15,7 +15,7 @@ export async function createSnapshot(config: SnapshotConfig): Promise<SnapshotRe// Validation errors should not retryif (!config.snapshotRepo) {- throw new FatalError('NUXT_GITHUB_SNAPSHOT_REPO is not configured')+ throw new FatalError('Snapshot repository is not configured')}// Let the step execute - errors will propagate and trigger retriesdiff --git a/apps/chat/server/workflows/sync-docs/workflow.ts b/apps/chat/server/workflows/sync-docs/workflow.tsindex 7cf1fd7..f9a71c3 100644--- a/apps/chat/server/workflows/sync-docs/workflow.ts+++ b/apps/chat/server/workflows/sync-docs/workflow.ts@@ -30,7 +30,7 @@ export async function syncDocumentation(// Validate configurationif (!config.snapshotRepo) {- throw new FatalError('NUXT_GITHUB_SNAPSHOT_REPO is not configured')+ throw new FatalError('Snapshot repository is not configured')}if (!sources || sources.length === 0) {diff --git a/bun.lock b/bun.lockindex 20b62b8..c1bd249 100644--- a/bun.lock+++ b/bun.lock@@ -27,10 +27,9 @@"@nuxt/ui": "^4.4.0","@nuxthub/core": "^0.10.6","@nuxtjs/mdc": "^0.20.1",- "@octokit/auth-app": "^8.2.0",- "@octokit/rest": "^22.0.1","@onmax/nuxt-better-auth": "0.0.2-alpha.21","@savoir/agent": "workspace:*",+ "@savoir/github": "workspace:*","@savoir/sdk": "workspace:*","@shelve/cli": "^4.1.7","@upstash/redis": "^1.36.2",@@ -83,6 +82,18 @@"typescript": "^5.9.3",},},+ "packages/github": {+ "name": "@savoir/github",+ "version": "0.1.0",+ "dependencies": {+ "@octokit/auth-app": "^8.2.0",+ "@octokit/rest": "^22.0.1",+ "evlog": "^1.9.0",+ },+ "devDependencies": {+ "nuxt": "^4.3.1",+ },+ },"packages/sdk": {"name": "@savoir/sdk","version": "0.1.0-alpha.2",@@ -1045,6 +1056,8 @@"@savoir/chat": ["@savoir/chat@workspace:apps/chat"],+ "@savoir/github": ["@savoir/github@workspace:packages/github"],+"@savoir/sdk": ["@savoir/sdk@workspace:packages/sdk"],"@sec-ant/readable-stream": ["@sec-ant/[email protected]", "", {}, "sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg=="],diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.mdindex fe19dd1..8a58866 100644--- a/docs/ENVIRONMENT.md+++ b/docs/ENVIRONMENT.md@@ -30,8 +30,8 @@ All environment variables for the Savoir project, organized by category.| Variable | Required | Description ||----------|----------|-------------|-| `NUXT_GITHUB_TOKEN` | Yes | GitHub token for cloning repos and accessing the snapshot repository |-| `NUXT_GITHUB_SNAPSHOT_REPO` | Yes | Snapshot repository in `owner/repo` format |+| `NUXT_GITHUB_TOKEN` | No | Optional fallback override token for snapshot git operations. If omitted, Savoir uses GitHub App installation tokens by default. |+| `NUXT_GITHUB_SNAPSHOT_REPO` | No | Default snapshot repository in `owner/repo` format. Can be configured later from the admin sandbox UI. || `NUXT_GITHUB_SNAPSHOT_BRANCH` | No | Snapshot branch (default: `main`) |## GitHub Bot@@ -45,6 +45,18 @@ All environment variables for the Savoir project, organized by category.\* Required only if enabling the GitHub bot integration.+## GitHub App Permissions (Recommended)++Use a GitHub App as the primary auth mechanism. Keep PAT usage optional.++| Capability | Required permissions |+|----------|-----------------------|+| OAuth login + GitHub bot replies | `Issues: Read & Write`, `Metadata: Read-only`, account emails read |+| Snapshot repo sync (push docs/marker) | `Contents: Read & Write`, `Metadata: Read-only` |+| Auto-create snapshot repositories | `Administration: Read & Write` (plus org approval when applicable) |++`NUXT_GITHUB_TOKEN` should only be used as a fallback when GitHub App permissions are unavailable or temporarily misconfigured.+## Discord Bot| Variable | Required | Description |diff --git a/packages/github/composables/useGitHub.ts b/packages/github/composables/useGitHub.tsnew file mode 100644index 0000000..19a3307--- /dev/null+++ b/packages/github/composables/useGitHub.ts@@ -0,0 +1,16 @@+import type { RepoInfo } from '../server/utils'++interface ReposResponse {+ count: number+ repositories: RepoInfo[]+}++export function useGitHub() {+ const fetchRepos = (options: { force?: boolean } = {}) => {+ return useFetch<ReposResponse>('/api/github/repos', {+ query: { force: options.force },+ })+ }++ return { fetchRepos }+}diff --git a/packages/github/eslint.config.js b/packages/github/eslint.config.jsnew file mode 100644index 0000000..08255b4--- /dev/null+++ b/packages/github/eslint.config.js@@ -0,0 +1,7 @@+import { createConfig } from "@hrcd/eslint-config"++export default createConfig({}, {+ rules: {+ 'max-params': 'off',+ },+})diff --git a/packages/github/nuxt.config.ts b/packages/github/nuxt.config.tsnew file mode 100644index 0000000..f716d9f--- /dev/null+++ b/packages/github/nuxt.config.ts@@ -0,0 +1,3 @@+import { defineNuxtConfig } from 'nuxt/config'++export default defineNuxtConfig({})diff --git a/packages/github/package.json b/packages/github/package.jsonnew file mode 100644index 0000000..e22d8b7--- /dev/null+++ b/packages/github/package.json@@ -0,0 +1,23 @@+{+ "name": "@savoir/github",+ "version": "0.1.0",+ "private": true,+ "license": "MIT",+ "type": "module",+ "exports": {+ ".": "./nuxt.config.ts",+ "./server/utils": "./server/utils/index.ts"+ },+ "scripts": {+ "lint": "eslint .",+ "lint:fix": "eslint . --fix"+ },+ "dependencies": {+ "@octokit/auth-app": "^8.2.0",+ "@octokit/rest": "^22.0.1",+ "evlog": "^1.9.0"+ },+ "devDependencies": {+ "nuxt": "^4.3.1"+ }+}\ No newline at end of filediff --git a/packages/github/server/api/github/repos.get.ts b/packages/github/server/api/github/repos.get.tsnew file mode 100644index 0000000..5bc466c--- /dev/null+++ b/packages/github/server/api/github/repos.get.ts@@ -0,0 +1,69 @@+import { createHash } from 'node:crypto'+import { z } from 'zod'+import { listUserRepos, listAppRepos, type RepoInfo } from '../../utils'+import { resolveGitHubAuth, type GitHubAuth } from '../../utils/auth'++const listReposCached = defineCachedFunction(+ async (_fingerprint: string, auth: GitHubAuth): Promise<RepoInfo[]> => {+ return auth.type === 'pat'+ ? await listUserRepos(auth.token)+ : await listAppRepos(auth)+ },+ {+ name: 'github-repos',+ maxAge: 60,+ swr: true,+ getKey: (fingerprint: string) => fingerprint,+ },+)++function buildFingerprint(auth: GitHubAuth): string {+ const hasher = createHash('sha256')+ hasher.update(auth.type === 'pat' ? `pat|${auth.token}` : `app|${auth.appId}`)+ return hasher.digest('hex')+}++const querySchema = z.object({+ owner: z.string().optional(),+ force: z.coerce.boolean().optional(),+})++export default defineEventHandler(async (event) => {+ const requestLog = useLogger(event)+ await requireAdmin(event)+ const config = useRuntimeConfig()+ const query = await getValidatedQuery(event, querySchema.parse)++ const auth = resolveGitHubAuth(config.github)+ if (!auth) {+ throw createError({+ statusCode: 400,+ message: 'GitHub credentials not configured',+ data: {+ why: 'Missing NUXT_GITHUB_TOKEN or NUXT_GITHUB_APP_ID/NUXT_GITHUB_APP_PRIVATE_KEY',+ fix: 'Set one of these in your environment or nuxt.config',+ },+ })+ }++ const repos = query.force+ ? await (auth.type === 'pat' ? listUserRepos(auth.token) : listAppRepos(auth))+ : await listReposCached(buildFingerprint(auth), auth)++ const filtered = query.owner+ ? repos.filter(repo => repo.owner.toLowerCase() === query.owner?.toLowerCase())+ : repos++ requestLog.set({+ ownerFilter: query.owner || null,+ force: query.force === true,+ cacheMode: query.force ? 'bypass' : 'swr',+ totalRepos: repos.length,+ returnedRepos: filtered.length,+ })++ return {+ count: filtered.length,+ repositories: filtered,+ }+})diff --git a/packages/github/server/utils/auth.ts b/packages/github/server/utils/auth.tsnew file mode 100644index 0000000..3dde0c8--- /dev/null+++ b/packages/github/server/utils/auth.ts@@ -0,0 +1,182 @@+import { createAppAuth } from '@octokit/auth-app'+import { Octokit } from '@octokit/rest'++/** Credentials: either PAT or GitHub App */+export type GitHubAuth =+ | { type: 'pat'; token: string }+ | { type: 'app'; appId: string; appPrivateKey: string }++type TokenCacheEntry = {+ token: string+ expiresAt: number+}++const tokenCache = new Map<string, TokenCacheEntry>()+const DEFAULT_TOKEN_TTL_MS = 50 * 60 * 1000++export function decodeGitHubPrivateKey(rawKey: string): string {+ const normalized = rawKey.replace(/\\n/g, '\n').trim()+ if (normalized.includes('BEGIN')) {+ return normalized+ }++ try {+ const decoded = Buffer.from(normalized, 'base64').toString('utf8').trim()+ if (decoded.includes('BEGIN')) {+ return decoded+ }+ } catch {+ // Fall through to return raw key if it's not valid base64.+ }++ return normalized+}++function getCachedToken(cacheKey: string): string | null {+ const cached = tokenCache.get(cacheKey)+ if (cached && cached.expiresAt > Date.now()) {+ return cached.token+ }+ return null+}++function setCachedToken(cacheKey: string, token: string, ttlMs: number = DEFAULT_TOKEN_TTL_MS): void {+ tokenCache.set(cacheKey, {+ token,+ expiresAt: Date.now() + ttlMs,+ })+}++export function createAppOctokit(appId: string, appPrivateKey: string): Octokit | null {+ if (!appId || !appPrivateKey) {+ return null+ }++ return new Octokit({+ authStrategy: createAppAuth,+ auth: {+ appId,+ privateKey: decodeGitHubPrivateKey(appPrivateKey),+ },+ })+}++async function createInstallationTokenForId(appId: string, appPrivateKey: string, installationId: number): Promise<string> {+ const auth = createAppAuth({+ appId,+ privateKey: decodeGitHubPrivateKey(appPrivateKey),+ })++ const { token } = await auth({+ type: 'installation',+ installationId,+ })+ return token+}++export async function getAppInstallationToken(appId: string, appPrivateKey: string, installationId: number): Promise<string> {+ const cacheKey = `app-installation:${appId}:${installationId}`+ const cached = getCachedToken(cacheKey)+ if (cached) {+ return cached+ }++ const token = await createInstallationTokenForId(appId, appPrivateKey, installationId)+ setCachedToken(cacheKey, token)+ return token+}++async function getAppInstallationForRepo(+ appId: string,+ appPrivateKey: string,+ owner: string,+ repo: string,+): Promise<number | null> {+ const appOctokit = createAppOctokit(appId, appPrivateKey)+ if (!appOctokit) return null++ try {+ const installation = await appOctokit.apps.getRepoInstallation({ owner, repo })+ return installation.data.id+ } catch {+ return null+ }+}++export async function getAppInstallationForOwner(+ appId: string,+ appPrivateKey: string,+ owner: string,+): Promise<number | null> {+ const appOctokit = createAppOctokit(appId, appPrivateKey)+ if (!appOctokit) return null++ try {+ const orgInstallation = await appOctokit.apps.getOrgInstallation({ org: owner })+ return orgInstallation.data.id+ } catch {+ // Ignore and try user installation below.+ }++ try {+ const userInstallation = await appOctokit.apps.getUserInstallation({ username: owner })+ return userInstallation.data.id+ } catch {+ return null+ }+}++/**+ * Get an App installation token for a specific repo. Returns undefined if not installed.+ */+export async function getAppTokenForRepo(options: {+ appId: string+ appPrivateKey: string+ repoPath: string+}): Promise<string | undefined> {+ if (!options.appId || !options.appPrivateKey || !options.repoPath) {+ return undefined+ }++ const [owner, repo] = options.repoPath.split('/')+ if (!owner || !repo) return undefined++ const installationId = await getAppInstallationForRepo(options.appId, options.appPrivateKey, owner, repo)+ if (!installationId) {+ return undefined+ }++ return await getAppInstallationToken(options.appId, options.appPrivateKey, installationId)+}++/**+ * Build a GitHubAuth from runtime config values. Returns null if no credentials are configured.+ */+export function resolveGitHubAuth(config: { token?: string; appId?: string; appPrivateKey?: string }): GitHubAuth | null {+ if (config.token) {+ return { type: 'pat', token: config.token }+ }+ if (config.appId && config.appPrivateKey) {+ return { type: 'app', appId: config.appId, appPrivateKey: config.appPrivateKey }+ }+ return null+}++/**+ * Resolve a token for a given repo (for cloning, push, etc.). PAT returns as-is; App fetches installation token.+ */+export async function getToken(auth: GitHubAuth, repoPath?: string): Promise<string | undefined> {+ if (auth.type === 'pat') {+ return auth.token+ }++ if (auth.type === 'app' && repoPath) {+ return await getAppTokenForRepo({+ appId: auth.appId,+ appPrivateKey: auth.appPrivateKey,+ repoPath,+ })+ }++ return undefined+}diff --git a/packages/github/server/utils/index.ts b/packages/github/server/utils/index.tsnew file mode 100644index 0000000..224474b--- /dev/null+++ b/packages/github/server/utils/index.ts@@ -0,0 +1,2 @@+export * from './auth'+export * from './primitives'diff --git a/packages/github/server/utils/primitives/branches.ts b/packages/github/server/utils/primitives/branches.tsnew file mode 100644index 0000000..76bf7e7--- /dev/null+++ b/packages/github/server/utils/primitives/branches.ts@@ -0,0 +1,66 @@+import { isNotFoundError } from './repos'+import { createOctokit } from './utils'++export interface BranchInfo {+ name: string+ sha: string+}++export async function getBranch(owner: string, repo: string, branch: string, token: string): Promise<BranchInfo> {+ const octokit = createOctokit(token)+ const result = await octokit.repos.getBranch({ owner, repo, branch })+ return {+ name: result.data.name,+ sha: result.data.commit.sha,+ }+}++export async function createBranch(+ owner: string,+ repo: string,+ branch: string,+ token: string,+ options: { fromBranch?: string; fromSha?: string } = {},+): Promise<BranchInfo> {+ const octokit = createOctokit(token)++ let sha = options.fromSha+ if (!sha) {+ if (options.fromBranch) {+ const ref = await octokit.git.getRef({ owner, repo, ref: `heads/${options.fromBranch}` })+ ;({ sha } = ref.data.object)+ } else {+ const repoInfo = await octokit.repos.get({ owner, repo })+ const ref = await octokit.git.getRef({ owner, repo, ref: `heads/${repoInfo.data.default_branch}` })+ ;({ sha } = ref.data.object)+ }+ }++ const result = await octokit.git.createRef({+ owner,+ repo,+ ref: `refs/heads/${branch}`,+ sha,+ })++ return {+ name: branch,+ sha: result.data.object.sha,+ }+}++export async function ensureBranch(+ owner: string,+ repo: string,+ branch: string,+ token: string,+): Promise<BranchInfo> {+ try {+ return await getBranch(owner, repo, branch, token)+ } catch (error: unknown) {+ if (isNotFoundError(error)) {+ return await createBranch(owner, repo, branch, token)+ }+ throw error+ }+}diff --git a/packages/github/server/utils/primitives/files.ts b/packages/github/server/utils/primitives/files.tsnew file mode 100644index 0000000..4e54161--- /dev/null+++ b/packages/github/server/utils/primitives/files.ts@@ -0,0 +1,66 @@+import { isNotFoundError } from './repos'+import { createOctokit } from './utils'++export interface FileContent {+ content: string+ sha: string+ encoding: 'utf8'+}++export async function getFile(+ owner: string,+ repo: string,+ path: string,+ token: string,+ options: { ref?: string } = {},+): Promise<FileContent | null> {+ const octokit = createOctokit(token)++ try {+ const response = await octokit.repos.getContent({+ owner,+ repo,+ path,+ ref: options.ref,+ })++ if (Array.isArray(response.data) || response.data.type !== 'file') {+ return null+ }++ return {+ content: Buffer.from(response.data.content, 'base64').toString('utf8'),+ sha: response.data.sha,+ encoding: 'utf8',+ }+ } catch (error: unknown) {+ if (isNotFoundError(error)) return null+ throw error+ }+}++export async function createOrUpdateFile(+ owner: string,+ repo: string,+ path: string,+ content: string,+ token: string,+ options: { branch?: string; message?: string; sha?: string } = {},+): Promise<{ sha: string; committed: boolean }> {+ const octokit = createOctokit(token)++ const response = await octokit.repos.createOrUpdateFileContents({+ owner,+ repo,+ path,+ message: options.message || `Update ${path}`,+ content: Buffer.from(content).toString('base64'),+ branch: options.branch,+ sha: options.sha,+ })++ return {+ sha: response.data.content?.sha || '',+ committed: true,+ }+}diff --git a/packages/github/server/utils/primitives/index.ts b/packages/github/server/utils/primitives/index.tsnew file mode 100644index 0000000..912b3a2--- /dev/null+++ b/packages/github/server/utils/primitives/index.ts@@ -0,0 +1,3 @@+export * from './repos'+export * from './branches'+export * from './files'diff --git a/packages/github/server/utils/primitives/repos.ts b/packages/github/server/utils/primitives/repos.tsnew file mode 100644index 0000000..36669f1--- /dev/null+++ b/packages/github/server/utils/primitives/repos.ts@@ -0,0 +1,138 @@+import { createError } from 'evlog'+import { createAppOctokit, getAppInstallationToken } from '../auth'+import { createOctokit, paginateAll } from './utils'++export function isNotFoundError(error: unknown): boolean {+ return (+ typeof error === 'object'+ && error !== null+ && 'status' in error+ && (error as { status: unknown }).status === 404+ )+}++export interface RepoInfo {+ id: number+ name: string+ fullName: string+ owner: string+ private: boolean+ defaultBranch?: string+ htmlUrl: string+}++export function parseRepoPath(repoPath: string): { owner: string; repo: string } {+ const [owner, repo, ...rest] = repoPath.split('/')+ if (!owner || !repo || rest.length > 0) {+ throw createError({+ status: 400,+ message: 'Invalid repository format',+ why: `Expected "owner/repo", received "${repoPath}"`,+ fix: 'Use the "owner/repo" format',+ })+ }+ return { owner, repo }+}++export function mapRepository(repo: any): RepoInfo {+ return {+ id: repo.id,+ name: repo.name,+ fullName: repo.full_name,+ owner: repo.owner?.login || repo.full_name.split('/')[0] || '',+ private: repo.private,+ defaultBranch: repo.default_branch,+ htmlUrl: repo.html_url,+ }+}++export async function getRepo(owner: string, repo: string, token: string): Promise<RepoInfo> {+ const octokit = createOctokit(token)+ const existing = await octokit.repos.get({ owner, repo })+ return mapRepository(existing.data)+}++export async function createRepo(+ options: {+ name: string+ owner?: string+ private?: boolean+ autoInit?: boolean+ },+ token: string,+): Promise<RepoInfo> {+ const octokit = createOctokit(token)++ if (options.owner) {+ const me = await octokit.users.getAuthenticated()+ if (me.data.login.toLowerCase() === options.owner.toLowerCase()) {+ const created = await octokit.repos.createForAuthenticatedUser({+ name: options.name,+ private: options.private ?? true,+ auto_init: options.autoInit ?? true,+ })+ return mapRepository(created.data)+ }+ const created = await octokit.repos.createInOrg({+ org: options.owner,+ name: options.name,+ private: options.private ?? true,+ auto_init: options.autoInit ?? true,+ })+ return mapRepository(created.data)+ }+ const created = await octokit.repos.createForAuthenticatedUser({+ name: options.name,+ private: options.private ?? true,+ auto_init: options.autoInit ?? true,+ })+ return mapRepository(created.data)+}++function uniqueRepositories(repos: RepoInfo[]): RepoInfo[] {+ const byFullName = new Map<string, RepoInfo>()+ for (const repo of repos) {+ byFullName.set(repo.fullName, repo)+ }+ return [...byFullName.values()].sort((a, b) => a.fullName.localeCompare(b.fullName))+}++export async function listUserRepos(token: string): Promise<RepoInfo[]> {+ const octokit = createOctokit(token)+ const repos = await paginateAll(async (page) => {+ const result = await octokit.repos.listForAuthenticatedUser({+ affiliation: 'owner,collaborator,organization_member',+ per_page: 100,+ page,+ visibility: 'all',+ })+ return result.data+ })+ return uniqueRepositories(repos.map(mapRepository))+}++export async function listAppRepos(options: { appId: string; appPrivateKey: string }): Promise<RepoInfo[]> {+ const appOctokit = createAppOctokit(options.appId, options.appPrivateKey)+ if (!appOctokit) {+ return []+ }++ const installations = await paginateAll(async (page) => {+ const result = await appOctokit.apps.listInstallations({ per_page: 100, page })+ return result.data+ })++ const allRepos: RepoInfo[] = []++ for (const installation of installations) {+ const token = await getAppInstallationToken(options.appId, options.appPrivateKey, installation.id)+ const installationOctokit = createOctokit(token)+ const repos = await paginateAll(async (page) => {+ const result = await installationOctokit.apps.listReposAccessibleToInstallation({ per_page: 100, page })+ return result.data.repositories+ })+ allRepos.push(...repos.map(mapRepository))+ }++ return uniqueRepositories(allRepos)+}diff --git a/packages/github/server/utils/primitives/utils.ts b/packages/github/server/utils/primitives/utils.tsnew file mode 100644index 0000000..bc59aab--- /dev/null+++ b/packages/github/server/utils/primitives/utils.ts@@ -0,0 +1,25 @@+import { Octokit } from '@octokit/rest'++export function createOctokit(token: string): Octokit {+ return new Octokit({ auth: token })+}++export async function paginateAll<T>(+ fetchPage: (page: number) => Promise<T[]>,+ perPage: number = 100,+): Promise<T[]> {+ const items: T[] = []+ let page = 1++ while (true) {+ const currentPage = await fetchPage(page)+ items.push(...currentPage)++ if (currentPage.length < perPage) {+ break+ }+ page += 1+ }++ return items+}