@otto-assistant/bridge 0.4.92

package/dist/forum-sync/discord-operations.js

@@ -0,0 +1,154 @@
+// Discord API operations for forum sync.
+// Resolves forum channels, fetches threads (active + archived) with pagination,
+// fetches thread messages, loads existing forum files from disk, and ensures directories.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ChannelType, } from 'discord.js';
+import { createLogger } from '../logger.js';
+import { parseFrontmatter, getStringValue } from './markdown.js';
+import { DEFAULT_RATE_LIMIT_DELAY_MS, ForumChannelResolveError, ForumSyncOperationError, delay, } from './types.js';
+const forumLogger = createLogger('FORUM');
+export function getCanonicalThreadFilePath({ outputDir, threadId, subfolder, }) {
+    if (subfolder) {
+        return path.join(outputDir, subfolder, `${threadId}.md`);
+    }
+    return path.join(outputDir, `${threadId}.md`);
+}
+export async function ensureDirectory({ directory }) {
+    const result = await fs.promises.mkdir(directory, { recursive: true }).catch((cause) => new ForumSyncOperationError({
+        forumChannelId: 'unknown',
+        reason: directory,
+        cause,
+    }));
+    if (result instanceof Error)
+        return result;
+}
+export async function resolveForumChannel({ discordClient, forumChannelId, }) {
+    const channel = await discordClient.channels
+        .fetch(forumChannelId)
+        .catch((cause) => new ForumChannelResolveError({ forumChannelId, cause }));
+    if (channel instanceof Error)
+        return channel;
+    if (!channel || channel.type !== ChannelType.GuildForum) {
+        return new ForumChannelResolveError({ forumChannelId });
+    }
+    return channel;
+}
+export async function fetchForumThreads({ forumChannel, }) {
+    const byId = new Map();
+    const active = await forumChannel.threads.fetchActive().catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: 'fetchActive failed',
+        cause,
+    }));
+    if (active instanceof Error)
+        return active;
+    for (const [id, thread] of active.threads) {
+        byId.set(id, thread);
+    }
+    let before;
+    while (true) {
+        const archived = await forumChannel.threads
+            .fetchArchived({ type: 'public', limit: 100, before })
+            .catch((cause) => new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: 'fetchArchived failed',
+            cause,
+        }));
+        if (archived instanceof Error)
+            return archived;
+        const threads = Array.from(archived.threads.values());
+        for (const thread of threads) {
+            byId.set(thread.id, thread);
+        }
+        if (!archived.hasMore || threads.length === 0)
+            break;
+        const timestamps = threads
+            .map((thread) => thread.archiveTimestamp ?? thread.createdTimestamp)
+            .filter((value) => value !== null);
+        const oldestTimestamp = Math.min(...timestamps);
+        if (!Number.isFinite(oldestTimestamp))
+            break;
+        before = new Date(oldestTimestamp - 1);
+        await delay({ ms: DEFAULT_RATE_LIMIT_DELAY_MS });
+    }
+    return Array.from(byId.values());
+}
+export async function fetchThreadMessages({ thread, }) {
+    const byId = new Map();
+    let before;
+    while (true) {
+        const fetched = await thread.messages.fetch({ limit: 100, before }).catch((cause) => new ForumSyncOperationError({
+            forumChannelId: thread.parentId || 'unknown',
+            reason: `message fetch failed for thread ${thread.id}`,
+            cause,
+        }));
+        if (fetched instanceof Error)
+            return fetched;
+        const messages = Array.from(fetched.values());
+        for (const message of messages) {
+            byId.set(message.id, message);
+        }
+        if (messages.length < 100 || messages.length === 0)
+            break;
+        // Find oldest message for cursor - messages are sorted by Discord, last is oldest
+        const oldest = messages[messages.length - 1];
+        if (!oldest)
+            break;
+        before = oldest.id;
+        await delay({ ms: DEFAULT_RATE_LIMIT_DELAY_MS });
+    }
+    return Array.from(byId.values()).sort((a, b) => a.createdTimestamp - b.createdTimestamp);
+}
+/**
+ * Recursively walks a directory collecting all .md files with their relative subfolder path.
+ */
+async function collectMarkdownFiles({ dir, outputDir, }) {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const relativeSub = path.relative(outputDir, dir);
+    const subfolder = relativeSub && relativeSub !== '.' ? relativeSub : undefined;
+    const mdFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => ({ filePath: path.join(dir, entry.name), subfolder }));
+    const subdirs = entries.filter((entry) => entry.isDirectory());
+    const nestedResults = await Promise.all(subdirs.map((subdir) => collectMarkdownFiles({
+        dir: path.join(dir, subdir.name),
+        outputDir,
+    })));
+    return [...mdFiles, ...nestedResults.flat()];
+}
+export async function loadExistingForumFiles({ outputDir, }) {
+    const markdownEntries = await collectMarkdownFiles({
+        dir: outputDir,
+        outputDir,
+    });
+    const loaded = await Promise.all(markdownEntries.map(async ({ filePath, subfolder }) => {
+        const content = await fs.promises
+            .readFile(filePath, 'utf8')
+            .catch((cause) => {
+            forumLogger.warn(`Failed to read forum file ${filePath}:`, cause);
+            return null;
+        });
+        if (content === null)
+            return null;
+        const parsed = parseFrontmatter({ markdown: content });
+        const threadIdFromFrontmatter = getStringValue({
+            value: parsed.frontmatter.threadId,
+        });
+        const threadIdFromFilename = path.basename(filePath, '.md');
+        const threadId = threadIdFromFrontmatter ||
+            (/^\d+$/.test(threadIdFromFilename) ? threadIdFromFilename : '');
+        if (!threadId)
+            return null;
+        const result = {
+            filePath,
+            threadId,
+            frontmatter: parsed.frontmatter,
+            subfolder,
+        };
+        return result;
+    }));
+    return loaded.filter((item) => item !== null);
+}

package/dist/forum-sync/index.js

@@ -0,0 +1,5 @@
+// Forum sync module entry point.
+// Re-exports the public API for forum <-> markdown synchronization.
+export { startConfiguredForumSync, stopConfiguredForumSync, } from './watchers.js';
+export { syncForumToFiles } from './sync-to-files.js';
+export { syncFilesToForum } from './sync-to-discord.js';

package/dist/forum-sync/markdown.js

@@ -0,0 +1,113 @@
+// Markdown parsing, serialization, and section formatting for forum sync.
+// Handles frontmatter extraction, message section building, and
+// conversion between Discord messages and markdown format.
+import YAML from 'yaml';
+import * as errore from 'errore';
+import { ForumFrontmatterParseError, } from './types.js';
+export function toStringArray({ value }) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string');
+}
+export function getStringValue({ value }) {
+    if (typeof value !== 'string')
+        return '';
+    return value;
+}
+export function parseFrontmatter({ markdown, }) {
+    if (!markdown.startsWith('---\n')) {
+        return { frontmatter: {}, body: markdown.trim() };
+    }
+    const end = markdown.indexOf('\n---\n', 4);
+    if (end === -1) {
+        return { frontmatter: {}, body: markdown.trim() };
+    }
+    const rawFrontmatter = markdown.slice(4, end);
+    const body = markdown.slice(end + 5).trim();
+    const parsed = errore.try({
+        try: () => YAML.parse(rawFrontmatter),
+        catch: (cause) => new ForumFrontmatterParseError({ reason: 'yaml parse failed', cause }),
+    });
+    if (parsed instanceof Error || !parsed || typeof parsed !== 'object') {
+        return { frontmatter: {}, body };
+    }
+    return { frontmatter: parsed, body };
+}
+export function stringifyFrontmatter({ frontmatter, body, }) {
+    const yamlText = YAML.stringify(frontmatter, null, {
+        lineWidth: 120,
+    }).trim();
+    return `---\n${yamlText}\n---\n\n${body.trim()}\n`;
+}
+export function splitSections({ body }) {
+    return body
+        .split(/\r?\n---\r?\n/g)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+export function extractStarterContent({ body }) {
+    const sections = splitSections({ body });
+    const firstSection = sections[0] || '';
+    const match = firstSection.match(/^\*\*.+?\*\* \(\d+\) - .+?(?: \(edited .+?\))?\r?\n\r?\n([\s\S]*)$/);
+    if (!match)
+        return body.trim();
+    return (match[1] || '').trim();
+}
+export function buildMessageSections({ messages, }) {
+    return messages.map((message) => {
+        const attachmentLines = Array.from(message.attachments.values()).map((attachment) => `Attachment: ${attachment.url}`);
+        const contentParts = [];
+        const trimmedContent = message.content.trim();
+        if (trimmedContent) {
+            contentParts.push(trimmedContent);
+        }
+        if (attachmentLines.length > 0) {
+            contentParts.push(attachmentLines.join('\n'));
+        }
+        const content = contentParts.length > 0
+            ? contentParts.join('\n\n')
+            : '_(no text content)_';
+        return {
+            messageId: message.id,
+            authorName: message.author.username,
+            authorId: message.author.id,
+            createdAt: new Date(message.createdTimestamp).toISOString(),
+            editedAt: message.editedTimestamp
+                ? new Date(message.editedTimestamp).toISOString()
+                : null,
+            content,
+        };
+    });
+}
+export function formatMessageSection({ section, }) {
+    const editedSuffix = section.editedAt ? ` (edited ${section.editedAt})` : '';
+    return `**${section.authorName}** (${section.authorId}) - ${section.createdAt}${editedSuffix}\n\n${section.content}`;
+}
+// Channel mention footer stored in the Discord starter message so
+// projectChannelId survives a full re-sync from Discord (no local files).
+// Uses <#id> so Discord renders it as a clickable channel link.
+// Matches at start-of-string or after a newline so it works even when the
+// footer is the only content in the message (e.g. empty body).
+const PROJECT_CHANNEL_FOOTER_RE = /(?:^|\n)channel: <#(\d{17,20})>\s*$/;
+const MAX_STARTER_MESSAGE_LENGTH = 2_000;
+/** Append a channel mention footer, truncating the body so the total
+ *  never exceeds Discord's 2000-char starter message limit. */
+export function appendProjectChannelFooter({ content, projectChannelId, }) {
+    if (!projectChannelId)
+        return content;
+    const footer = `\nchannel: <#${projectChannelId}>`;
+    const maxContentLength = MAX_STARTER_MESSAGE_LENGTH - footer.length;
+    const truncated = content.length > maxContentLength
+        ? content.slice(0, maxContentLength)
+        : content;
+    return `${truncated}${footer}`;
+}
+export function extractProjectChannelFromContent({ content, }) {
+    const match = content.match(PROJECT_CHANNEL_FOOTER_RE);
+    if (!match)
+        return { cleanContent: content };
+    return {
+        cleanContent: content.replace(PROJECT_CHANNEL_FOOTER_RE, '').trim(),
+        projectChannelId: match[1],
+    };
+}

package/dist/forum-sync/sync-to-discord.js

@@ -0,0 +1,417 @@
+// Filesystem -> Discord sync.
+// Reads markdown files and creates/updates/deletes forum threads to match.
+// Handles upsert logic: new files create threads, existing files update them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { MessageFlags } from 'discord.js';
+import { createLogger } from '../logger.js';
+import { appendProjectChannelFooter, extractStarterContent, getStringValue, parseFrontmatter, toStringArray, } from './markdown.js';
+import { resolveForumChannel } from './discord-operations.js';
+import { syncSingleThreadToFile } from './sync-to-files.js';
+import { ForumSyncOperationError, shouldIgnorePath, } from './types.js';
+const forumLogger = createLogger('FORUM');
+// Fields managed by forum sync that should not be set by external writers (e.g. AI model).
+// If a file has never been synced (no lastSyncedAt), these fields are stripped to prevent
+// model-invented values from causing sync errors (e.g. fake threadId -> fetch fails,
+// future lastSyncedAt -> file permanently skipped).
+const SYSTEM_MANAGED_FIELDS = [
+    'threadId',
+    'forumChannelId',
+    'lastSyncedAt',
+    'lastMessageId',
+    'messageCount',
+    'author',
+    'authorId',
+    'createdAt',
+    'lastUpdated',
+    'project',
+    'projectChannelId',
+];
+/** Check that a value is a valid ISO date string that isn't in the future. */
+function isValidPastIsoDate({ value }) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return false;
+    return parsed <= Date.now();
+}
+function stripSystemFieldsFromUnsyncedFile({ frontmatter, }) {
+    if (isValidPastIsoDate({ value: frontmatter.lastSyncedAt }))
+        return frontmatter;
+    const cleaned = { ...frontmatter };
+    for (const field of SYSTEM_MANAGED_FIELDS) {
+        delete cleaned[field];
+    }
+    return cleaned;
+}
+function isValidDiscordSnowflake({ value }) {
+    return /^\d{17,20}$/.test(value);
+}
+async function collectMarkdownEntries({ dir, outputDir, }) {
+    const exists = await fs.promises
+        .access(dir)
+        .then(() => true)
+        .catch(() => false);
+    if (!exists)
+        return [];
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const relativeSub = path.relative(outputDir, dir);
+    const subfolder = relativeSub && relativeSub !== '.' ? relativeSub : undefined;
+    const markdownFiles = entries
+        .filter((entry) => {
+        return entry.isFile() && entry.name.endsWith('.md');
+    })
+        .map((entry) => {
+        return { filePath: path.join(dir, entry.name), subfolder };
+    });
+    const nestedEntries = await Promise.all(entries
+        .filter((entry) => {
+        return entry.isDirectory();
+    })
+        .map(async (entry) => {
+        return await collectMarkdownEntries({
+            dir: path.join(dir, entry.name),
+            outputDir,
+        });
+    }));
+    return [...markdownFiles, ...nestedEntries.flat()];
+}
+function resolveTagIds({ forumChannel, tagNames, }) {
+    if (tagNames.length === 0)
+        return [];
+    const normalizedWanted = new Set(tagNames.map((tag) => tag.toLowerCase().trim()));
+    return forumChannel.availableTags
+        .filter((tag) => normalizedWanted.has(tag.name.toLowerCase().trim()))
+        .map((tag) => tag.id);
+}
+/** Ensure all requested tag names exist on the forum channel, creating any missing ones. */
+async function ensureForumTags({ forumChannel, tagNames, }) {
+    if (tagNames.length === 0)
+        return;
+    const existingNames = new Set(forumChannel.availableTags.map((tag) => tag.name.toLowerCase().trim()));
+    const missing = tagNames.filter((name) => !existingNames.has(name.toLowerCase().trim()));
+    if (missing.length === 0)
+        return;
+    // Discord forums allow up to 20 tags
+    const available = forumChannel.availableTags;
+    if (available.length + missing.length > 20)
+        return;
+    await forumChannel
+        .setAvailableTags([...available, ...missing.map((name) => ({ name }))], `Auto-create tags: ${missing.join(', ')}`)
+        .catch((cause) => {
+        forumLogger.warn(`Failed to create forum tags [${missing.join(', ')}]: ${cause instanceof Error ? cause.message : cause}`);
+    });
+}
+function hasTagName({ tags, tagName }) {
+    return tags.some((tag) => tag.toLowerCase().trim() === tagName.toLowerCase().trim());
+}
+async function upsertThreadFromFile({ discordClient, forumChannel, filePath, runtimeState, subfolder, project, projectChannelId, }) {
+    if (!fs.existsSync(filePath))
+        return 'skipped';
+    const content = await fs.promises
+        .readFile(filePath, 'utf8')
+        .catch((cause) => {
+        return new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: `failed to read ${filePath}`,
+            cause,
+        });
+    });
+    if (content instanceof Error)
+        return content;
+    const parsed = parseFrontmatter({ markdown: content });
+    const frontmatter = stripSystemFieldsFromUnsyncedFile({
+        frontmatter: parsed.frontmatter,
+    });
+    const rawThreadId = getStringValue({ value: frontmatter.threadId });
+    const threadId = rawThreadId && isValidDiscordSnowflake({ value: rawThreadId })
+        ? rawThreadId
+        : '';
+    const title = getStringValue({ value: frontmatter.title }) ||
+        path.basename(filePath, '.md');
+    const tags = toStringArray({ value: frontmatter.tags });
+    const normalizedSubfolder = subfolder?.replaceAll('\\', '/').toLowerCase();
+    const isGlobalSubfolder = Boolean(normalizedSubfolder &&
+        (normalizedSubfolder === 'global' ||
+            normalizedSubfolder.startsWith('global/')));
+    const tagsWithScope = isGlobalSubfolder && !hasTagName({ tags, tagName: 'global' })
+        ? [...tags, 'global']
+        : tags;
+    // Add project name as a forum tag if derived from subfolder
+    const allTags = project && !hasTagName({ tags: tagsWithScope, tagName: project })
+        ? [...tagsWithScope, project]
+        : tagsWithScope;
+    const starterContent = extractStarterContent({ body: parsed.body });
+    // Resolve fallback BEFORE appending footer so an empty body doesn't
+    // produce a message that is just the channel footer.
+    const baseContent = starterContent || title || 'Untitled post';
+    const safeStarterContent = appendProjectChannelFooter({
+        content: baseContent,
+        projectChannelId,
+    });
+    const stat = await fs.promises.stat(filePath).catch((cause) => {
+        return new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: `failed to stat ${filePath}`,
+            cause,
+        });
+    });
+    if (stat instanceof Error)
+        return stat;
+    // Skip if file hasn't been modified since last sync
+    const lastSyncedAt = Date.parse(getStringValue({ value: frontmatter.lastSyncedAt }));
+    if (Number.isFinite(lastSyncedAt) && stat.mtimeMs <= lastSyncedAt)
+        return 'skipped';
+    await ensureForumTags({ forumChannel, tagNames: allTags });
+    const tagIds = resolveTagIds({ forumChannel, tagNames: allTags });
+    // No threadId in frontmatter -> create a new thread
+    if (!threadId) {
+        return await createNewThread({
+            forumChannel,
+            filePath,
+            title,
+            safeStarterContent,
+            tagIds,
+            runtimeState,
+            subfolder,
+            project,
+            projectChannelId,
+        });
+    }
+    // Thread exists -> update it
+    return await updateExistingThread({
+        discordClient,
+        forumChannel,
+        filePath,
+        threadId,
+        title,
+        safeStarterContent,
+        tagIds,
+        runtimeState,
+        subfolder,
+        project,
+        projectChannelId,
+    });
+}
+async function createNewThread({ forumChannel, filePath, title, safeStarterContent, tagIds, runtimeState, subfolder, project, projectChannelId, }) {
+    const created = await forumChannel.threads
+        .create({
+        name: title.slice(0, 100) || 'Untitled post',
+        message: {
+            content: safeStarterContent.slice(0, 2_000),
+            flags: MessageFlags.SuppressEmbeds,
+        },
+        appliedTags: tagIds,
+    })
+        .catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: `failed creating thread from ${filePath}`,
+        cause,
+    }));
+    if (created instanceof Error)
+        return created;
+    // Re-sync the file to get the new threadId in frontmatter.
+    // outputDir is path.dirname(filePath) which already includes the subfolder,
+    // so we don't pass subfolder again to avoid double-nesting.
+    const syncResult = await syncSingleThreadToFile({
+        thread: created,
+        forumChannel,
+        outputDir: path.dirname(filePath),
+        runtimeState,
+        previousFilePath: filePath,
+        project,
+        projectChannelId,
+    });
+    if (syncResult instanceof Error)
+        return syncResult;
+    return 'created';
+}
+async function updateExistingThread({ discordClient, forumChannel, filePath, threadId, title, safeStarterContent, tagIds, runtimeState, subfolder, project, projectChannelId, }) {
+    const fetchedChannel = await discordClient.channels.fetch(threadId).catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: `failed fetching thread ${threadId}`,
+        cause,
+    }));
+    if (fetchedChannel instanceof Error)
+        return fetchedChannel;
+    if (!fetchedChannel ||
+        !fetchedChannel.isThread() ||
+        fetchedChannel.parentId !== forumChannel.id) {
+        return new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: `thread ${threadId} not found in forum`,
+        });
+    }
+    const updateResult = await fetchedChannel
+        .edit({
+        name: title.slice(0, 100) || fetchedChannel.name,
+        appliedTags: tagIds,
+    })
+        .catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: `failed editing thread ${threadId}`,
+        cause,
+    }));
+    if (updateResult instanceof Error)
+        return updateResult;
+    const starterMessage = await fetchedChannel
+        .fetchStarterMessage()
+        .catch((cause) => {
+        return new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: `failed fetching starter message for ${threadId}`,
+            cause,
+        });
+    });
+    if (starterMessage instanceof Error)
+        return starterMessage;
+    if (starterMessage && starterMessage.content !== safeStarterContent) {
+        const editResult = await starterMessage
+            .edit({
+            content: safeStarterContent.slice(0, 2_000),
+            flags: MessageFlags.SuppressEmbeds,
+        })
+            .catch((cause) => new ForumSyncOperationError({
+            forumChannelId: forumChannel.id,
+            reason: `failed editing starter message for ${threadId}`,
+            cause,
+        }));
+        if (editResult instanceof Error)
+            return editResult;
+    }
+    // Re-sync the file to update frontmatter with latest state.
+    // outputDir is path.dirname(filePath) which already includes the subfolder.
+    const syncResult = await syncSingleThreadToFile({
+        thread: fetchedChannel,
+        forumChannel,
+        outputDir: path.dirname(filePath),
+        runtimeState,
+        project,
+        projectChannelId,
+    });
+    if (syncResult instanceof Error)
+        return syncResult;
+    return 'updated';
+}
+async function deleteThreadFromFilePath({ discordClient, forumChannel, filePath, }) {
+    const filename = path.basename(filePath, '.md');
+    if (!/^\d+$/.test(filename))
+        return;
+    const threadId = filename;
+    const fetchedChannel = await discordClient.channels.fetch(threadId).catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: `failed fetching deleted thread ${threadId}`,
+        cause,
+    }));
+    if (fetchedChannel instanceof Error)
+        return fetchedChannel;
+    if (!fetchedChannel ||
+        !fetchedChannel.isThread() ||
+        fetchedChannel.parentId !== forumChannel.id) {
+        return;
+    }
+    const deleteResult = await fetchedChannel
+        .delete('Deleted from forum sync markdown directory')
+        .catch((cause) => new ForumSyncOperationError({
+        forumChannelId: forumChannel.id,
+        reason: `failed deleting thread ${threadId}`,
+        cause,
+    }));
+    if (deleteResult instanceof Error)
+        return deleteResult;
+}
+export async function syncFilesToForum({ discordClient, forumChannelId, outputDir, runtimeState, changedFilePaths, deletedFilePaths, }) {
+    const forumChannel = await resolveForumChannel({
+        discordClient,
+        forumChannelId,
+    });
+    if (forumChannel instanceof Error)
+        return forumChannel;
+    // When changedFilePaths is provided (from file watcher), derive subfolder from path.
+    // Otherwise, recursively scan all markdown files in outputDir.
+    const changedEntries = changedFilePaths
+        ? changedFilePaths.map((filePath) => {
+            const rel = path.relative(outputDir, path.dirname(filePath));
+            const subfolder = rel && rel !== '.' ? rel : undefined;
+            return { filePath, subfolder };
+        })
+        : await collectMarkdownEntries({ dir: outputDir, outputDir });
+    // Resolve channel names for subfolders (each subfolder name is a Discord channel ID).
+    // Cache resolutions to avoid redundant API calls.
+    const channelNameCache = new Map();
+    const resolveChannelName = async (channelId) => {
+        if (channelNameCache.has(channelId))
+            return channelNameCache.get(channelId);
+        const channel = await discordClient.channels
+            .fetch(channelId)
+            .catch(() => null);
+        const name = channel && 'name' in channel && typeof channel.name === 'string'
+            ? channel.name
+            : null;
+        channelNameCache.set(channelId, name);
+        return name;
+    };
+    const result = {
+        created: 0,
+        updated: 0,
+        skipped: 0,
+        deleted: 0,
+    };
+    for (const { filePath, subfolder } of changedEntries) {
+        if (!filePath.endsWith('.md'))
+            continue;
+        if (runtimeState && shouldIgnorePath({ runtimeState, filePath })) {
+            result.skipped += 1;
+            continue;
+        }
+        // Derive project info from subfolder (subfolder name is the channel ID).
+        // Only use subfolder as channelId if it looks like a valid Discord snowflake
+        // to prevent nested paths or arbitrary folder names from being treated as IDs.
+        const projectChannelId = subfolder && isValidDiscordSnowflake({ value: subfolder })
+            ? subfolder
+            : undefined;
+        const project = projectChannelId
+            ? (await resolveChannelName(projectChannelId)) || undefined
+            : undefined;
+        const upsertResult = await upsertThreadFromFile({
+            discordClient,
+            forumChannel,
+            filePath,
+            runtimeState,
+            subfolder,
+            project,
+            projectChannelId,
+        });
+        // Keep syncing other files even if one file has stale/bad metadata
+        // (e.g. threadId that no longer exists). A single bad file should not
+        // block watcher startup for the whole memory directory.
+        if (upsertResult instanceof Error) {
+            forumLogger.warn(`Skipping ${filePath}: ${upsertResult.message}`);
+            result.skipped += 1;
+            continue;
+        }
+        if (upsertResult === 'created') {
+            result.created += 1;
+        }
+        else if (upsertResult === 'updated') {
+            result.updated += 1;
+        }
+        else {
+            result.skipped += 1;
+        }
+    }
+    for (const filePath of deletedFilePaths || []) {
+        const deleteResult = await deleteThreadFromFilePath({
+            discordClient,
+            forumChannel,
+            filePath,
+        });
+        if (deleteResult instanceof Error) {
+            forumLogger.warn(`Skipping delete ${filePath}: ${deleteResult.message}`);
+            continue;
+        }
+        result.deleted += 1;
+    }
+    return result;
+}