synthos 0.8.0 → 0.9.0

package/src/service/useAgentRoutes.ts

@@ -12,10 +12,14 @@ import {
     disconnectAgent,
     getAgentStatus,
     getTunnelStatus,
+    setOpenClawDebug,
 } from '../agents';
 import { v4 as uuidv4 } from 'uuid';
+import { Customizer } from '../customizer';
 
-export function useAgentRoutes(config: SynthOSConfig, app: Application): void {
+export function useAgentRoutes(config: SynthOSConfig, app: Application, customizer?: Customizer): void {
+    // Enable OpenClaw debug logging only when --debug is passed
+    setOpenClawDebug(config.debug);
 
     /** Strip the token and sshTunnel.password fields, add connection/tunnel status for agent responses. */
     function toClientAgent(agent: AgentConfig): Record<string, unknown> {
@@ -41,6 +45,7 @@ export function useAgentRoutes(config: SynthOSConfig, app: Application): void {
             url: agent.url,
             token: agent.token,
             sshTunnel: agent.sshTunnel,
+            productName: customizer?.productName,
         })
             .then(() => console.log(`[Agents] Auto-connected OpenClaw agent "${agent.name}"`))
             .catch(err => console.warn(`[Agents] Auto-connect failed for "${agent.name}": ${err instanceof Error ? err.message : err}`));
@@ -241,7 +246,7 @@ export function useAgentRoutes(config: SynthOSConfig, app: Application): void {
                 return;
             }
 
-            await connectAgent({ id: agent.id, name: agent.name, url: agent.url, token: agent.token, sshTunnel: agent.sshTunnel });
+            await connectAgent({ id: agent.id, name: agent.name, url: agent.url, token: agent.token, sshTunnel: agent.sshTunnel, productName: customizer?.productName });
             const status = getAgentStatus(agent.id);
             res.json({ connected: status.connected, authenticated: status.authenticated });
         } catch (err: unknown) {

package/src/service/useApiRoutes.ts

@@ -1,8 +1,8 @@
 import path from "path";
 import fs from "fs/promises";
 import AdmZip from "adm-zip";
-import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, REQUIRED_PAGES, deletePage, copyPage, loadPageState, savePageState, PAGE_VERSION } from "../pages";
-import { checkIfExists, copyFile, copyFolderRecursive, deleteFile, ensureFolderExists, loadFile } from "../files";
+import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, deletePage, copyPage, loadPageState, savePageState, clearVersions, PAGE_VERSION } from "../pages";
+import { checkIfExists, copyFile, copyFolderRecursive, deleteFile, ensureFolderExists, findFileInFolders, listFolders, loadFile } from "../files";
 import {getModelEntry, loadSettings, saveSettings, ServicesConfig } from "../settings";
 import { Application } from 'express';
 import express from 'express';
@@ -12,9 +12,10 @@ import { generateDefaultImage, generateImage } from "./generateImage";
 import { chainOfThought } from "../models";
 import { requiresSettings } from "./requiresSettings";
 import { executeScript } from "../scripts";
-import { listThemes, loadTheme, loadThemeInfo } from "../themes";
+import { listThemes, loadTheme, loadThemeInfo, loadThemeVersion } from "../themes";
 import { migratePage } from "../migrations";
 import { loadPageWithFallback } from "./usePageRoutes";
+import { Customizer } from "../customizer";
 
 // ---------------------------------------------------------------------------
 // Service registry
@@ -48,10 +49,10 @@ const SERVICE_REGISTRY: ServiceDefinition[] = [
     }
 ];
 
-export function useApiRoutes(config: SynthOSConfig, app: Application): void {
+export function useApiRoutes(config: SynthOSConfig, app: Application, customizer?: Customizer): void {
     // List pages
     app.get('/api/pages', async (req, res) => {
-        const pages = await listPages(config.pagesFolder, config.requiredPagesFolder);
+        const pages = await listPages(config.pagesFolder, config.requiredPagesFolders);
         res.json(pages);
     });
 
@@ -149,7 +150,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     app.get('/api/pages/:name', async (req, res) => {
         try {
             const { name } = req.params;
-            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolders);
             if (metadata) {
                 res.json(metadata);
             } else {
@@ -200,7 +201,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             // Load existing metadata (or defaults)
-            const existing = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const existing = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolders);
             const metadata: PageMetadata = {
                 title: existing?.title ?? '',
                 categories: existing?.categories ?? [],
@@ -226,7 +227,11 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             if (metadata.mode !== 'locked') {
                 const userPagePath = path.join(config.pagesFolder, 'pages', name, 'page.html');
                 if (!(await checkIfExists(userPagePath))) {
-                    const html = await loadPageState(config.requiredPagesFolder, name, false);
+                    let html: string | undefined;
+                    for (const folder of config.requiredPagesFolders) {
+                        html = await loadPageState(folder, name);
+                        if (html) break;
+                    }
                     if (html) {
                         await savePageState(config.pagesFolder, name, html);
                     }
@@ -252,7 +257,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             }
 
             // Load existing metadata (user override → fallback .json → defaults)
-            let metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            let metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolders);
             if (!metadata) {
                 metadata = {
                     title: '',
@@ -281,7 +286,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             const { name } = req.params;
 
             // Cannot delete required pages
-            if (REQUIRED_PAGES.includes(name)) {
+            if (config.requiredPages.includes(name)) {
                 res.status(400).json({ error: `Cannot delete required page "${name}"` });
                 return;
             }
@@ -303,11 +308,56 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
         }
     });
 
+    // Discover what a page contains (tables + files)
+    app.get('/api/pages/:name/contents', async (req, res) => {
+        try {
+            const { name } = req.params;
+
+            // Resolve page folder: user pages first, then required pages
+            let pageFolder: string | undefined;
+            const userFolder = path.join(config.pagesFolder, 'pages', name);
+            if (await checkIfExists(path.join(userFolder, 'page.html'))) {
+                pageFolder = userFolder;
+            } else {
+                for (const folder of config.requiredPagesFolders) {
+                    const candidate = path.join(folder, name);
+                    if (await checkIfExists(path.join(candidate, 'page.html'))) {
+                        pageFolder = candidate;
+                        break;
+                    }
+                }
+            }
+
+            if (!pageFolder) {
+                res.status(404).json({ error: `Page "${name}" not found` });
+                return;
+            }
+
+            // List subdirectories, filtering out non-table entries
+            const EXCLUDED = new Set(['files']);
+            const subdirs = await listFolders(pageFolder);
+            const tables = subdirs.filter(d => !EXCLUDED.has(d));
+
+            // Check if files/ exists and has entries
+            const filesDir = path.join(pageFolder, 'files');
+            let hasFiles = false;
+            if (await checkIfExists(filesDir)) {
+                const entries = await fs.readdir(filesDir);
+                hasFiles = entries.length > 0;
+            }
+
+            res.json({ tables, hasFiles });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
     // Copy a page to a new name
     app.post('/api/pages/:name/copy', async (req, res) => {
         try {
             const sourceName = req.params.name;
-            const { name: targetName, title, categories } = req.body;
+            const { name: targetName, title, categories, copyTables, copyFiles } = req.body;
 
             // Validate target name
             if (!targetName || typeof targetName !== 'string') {
@@ -329,10 +379,14 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             // Check source exists (user pages → required pages)
             const sourceFolderPath = path.join(config.pagesFolder, 'pages', sourceName, 'page.html');
             const sourceFlatPath = path.join(config.pagesFolder, `${sourceName}.html`);
-            const sourceRequiredPath = path.join(config.requiredPagesFolder, `${sourceName}.html`);
+            let sourceRequiredPath: string | undefined;
+            for (const folder of config.requiredPagesFolders) {
+                const candidate = path.join(folder, sourceName, 'page.html');
+                if (await checkIfExists(candidate)) { sourceRequiredPath = candidate; break; }
+            }
             const sourceExists = await checkIfExists(sourceFolderPath)
                 || await checkIfExists(sourceFlatPath)
-                || await checkIfExists(sourceRequiredPath);
+                || !!sourceRequiredPath;
             if (!sourceExists) {
                 res.status(404).json({ error: `Source page "${sourceName}" not found` });
                 return;
@@ -352,7 +406,11 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
                 targetName,
                 typeof title === 'string' ? title : '',
                 Array.isArray(categories) ? categories : [],
-                config.requiredPagesFolder
+                config.requiredPagesFolders,
+                {
+                    copyTables: copyTables === true,
+                    copyFiles: copyFiles !== false, // default true
+                }
             );
 
             // Return the new page metadata
@@ -428,16 +486,18 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     });
 
     // Brainstorm endpoint
+    if (!customizer || customizer.isEnabled('brainstorm'))
     app.post('/api/brainstorm', async (req, res) => {
         await requiresSettings(res, config.pagesFolder, async (settings) => {
             const { context, messages } = req.body;
             const completePrompt = await createCompletePrompt(config.pagesFolder, 'chat');
 
+            const productName = customizer?.productName ?? 'SynthOS';
             const system: { role: 'system'; content: string } = {
                 role: 'system',
-                content: `You are a creative brainstorming assistant for SynthOS, a tool that builds pages through conversation.
-SynthOS is like a WIKI for vibe coding. Each page has a chat panel and a viewer panel. They are vibe coding what's displayed in that viewer panel. They can then save that as a page.
-The user is brainstorming — exploring ideas before building. Be concise, creative, and collaborative. 
+                content: `You are a creative brainstorming assistant for ${productName}, a tool that builds pages through conversation.
+${productName} is like a WIKI for vibe coding. Each page has a chat panel and a viewer panel. They are vibe coding what's displayed in that viewer panel. They can then save that as a page.
+The user is brainstorming — exploring ideas before building. Be concise, creative, and collaborative.
 They may say that they want to build an app or page that does XYZ but they're talking about what they expect to see in the viewer panel.
 The goal is to help them generate a prompt for the builder that captures their vision, along with suggestions for next steps.
 Suggest concrete approaches when you can, not complex visions for some ellaborate app.
@@ -448,14 +508,14 @@ ${context}
 
 <INSTRUCTIONS>
 Look at the <CHAT_HISTORY> and if it's empty it's the start of a new idea. Simply greet them and ask them what they're thinking of building. Suggestions could be help me decide, etc.
-If you see a conversation between SynthOS and the User. Asses what they're building and ask them what they'd like help with. Maybe offer a few good next steps.
+If you see a conversation between ${productName} and the User. Asses what they're building and ask them what they'd like help with. Maybe offer a few good next steps.
 
-SynthOS exposes table storage and chat completion api's that every page can use. If the user wants to store something or use AI, your prompt should suggest using table storage or make llm calls.
+${productName} exposes table storage and chat completion api's that every page can use. If the user wants to store something or use AI, your prompt should suggest using table storage or make llm calls.
 
 You MUST return your response as a JSON object with exactly these fields:
 {
   "response": "Your conversational reply — explanations, options, suggestions. Markdown OK.",
-  "prompt": "A clean, actionable instruction ready to paste into SynthOS chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state.",
+  "prompt": "A clean, actionable instruction ready to paste into ${productName} chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state.",
   "suggestions": ["Short clickable option A", "Short clickable option B", "Short clickable option C"]
 }
 
@@ -495,6 +555,7 @@ Return ONLY the JSON object.`};
     });
 
     // Define a route for running configured scripts
+    if (!customizer || customizer.isEnabled('scripts'))
     app.post('/api/scripts/:id', async (req, res) => {
         await requiresSettings(res, config.pagesFolder, async (settings) => {
             const { id } = req.params;
@@ -523,7 +584,13 @@ Return ONLY the JSON object.`};
                 res.status(404).send(`// Theme info for "${themeName}" not found`);
                 return;
             }
-            const js = `window.themeInfo=${JSON.stringify(info)};document.documentElement.classList.add(window.themeInfo.mode+"-mode");`;
+            const themeVersion = await loadThemeVersion(themeName, config);
+            const payload = { ...info, name: themeName, version: themeVersion };
+            let js = `window.themeInfo=${JSON.stringify(payload)};document.documentElement.classList.add(window.themeInfo.mode+"-mode");`;
+            if (themeVersion >= 3) {
+                js += `document.documentElement.classList.add(${JSON.stringify(themeName)});`;
+            }
+            js += `document.documentElement.setAttribute("data-toolbar",${JSON.stringify(settings.toolbarPosition || 'left')});`;
             res.set('Content-Type', 'application/javascript');
             res.send(js);
         } catch (err: unknown) {
@@ -540,21 +607,18 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Missing page query parameter');
                 return;
             }
-            const metadata = await loadPageMetadata(config.pagesFolder, page, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config.pagesFolder, page, config.requiredPagesFolders);
             const mode = metadata?.mode ?? 'unlocked';
             const title = metadata?.title ?? '';
             const categories = metadata?.categories ?? [];
-            const info = JSON.stringify({ name: page, mode, latestPageVersion: PAGE_VERSION, title, categories });
+            const isRequiredPage = config.requiredPages.includes(page);
+            const productName = customizer?.productName ?? 'SynthOS';
+            const info = JSON.stringify({ name: page, mode, latestPageVersion: PAGE_VERSION, title, categories, isRequiredPage, productName });
             const js = [
                 `window.pageInfo=${info};`,
                 `if(window.pageInfo.mode==="locked"){`,
                 `document.addEventListener("DOMContentLoaded",function(){`,
                 `var f=document.getElementById("chatForm");if(f)f.style.display="none";`,
-                `var s=document.getElementById("saveLink");if(s)s.textContent="Copy";`,
-                `var r=document.getElementById("resetLink");if(r){`,
-                `var c=r.cloneNode(true);c.textContent="Reload";`,
-                `c.addEventListener("click",function(e){e.preventDefault();window.location.href=window.location.pathname;});`,
-                `r.parentNode.replaceChild(c,r);}`,
                 `});`,
                 `}`,
             ].join('');
@@ -604,8 +668,8 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Invalid version parameter');
                 return;
             }
-            const scriptPath = path.join(config.pageScriptsFolder, `page-v${v}.js`);
-            if (!(await checkIfExists(scriptPath))) {
+            const scriptPath = await findFileInFolders(config.staticFilesFolders, `page.v${v}.js`);
+            if (!scriptPath) {
                 res.status(404).send(`// page-v${v}.js not found`);
                 return;
             }
@@ -627,8 +691,8 @@ Return ONLY the JSON object.`};
                 res.status(400).send('// Invalid version parameter');
                 return;
             }
-            const scriptPath = path.join(config.pageScriptsFolder, `helpers-v${v}.js`);
-            if (!(await checkIfExists(scriptPath))) {
+            const scriptPath = await findFileInFolders(config.staticFilesFolders, `helpers.v${v}.js`);
+            if (!scriptPath) {
                 res.status(404).send(`// helpers-v${v}.js not found`);
                 return;
             }
@@ -707,6 +771,7 @@ Return ONLY the JSON object.`};
     // Web Search (Brave Search API)
     // -----------------------------------------------------------------------
 
+    if (!customizer || customizer.isEnabled('search'))
     app.post('/api/search/web', async (req, res) => {
         try {
             const { query, count, country, freshness } = req.body;
@@ -761,7 +826,7 @@ Return ONLY the JSON object.`};
             const { name } = req.params;
 
             // Load current metadata
-            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolder);
+            const metadata = await loadPageMetadata(config.pagesFolder, name, config.requiredPagesFolders);
             if (!metadata) {
                 res.status(404).json({ error: `Page "${name}" not found` });
                 return;
@@ -790,19 +855,22 @@ Return ONLY the JSON object.`};
             // Backup original page to .migrated/ before overwriting
             const migratedFolder = path.join(config.pagesFolder, '.migrated');
 
-            // Handle legacy flat file (.synthos/pagename.html)
+            // Handle legacy flat file (<localFolder>/pagename.html)
             const flatPath = path.join(config.pagesFolder, `${name}.html`);
             if (await checkIfExists(flatPath)) {
                 await copyFile(flatPath, migratedFolder);
                 await deleteFile(flatPath);
             }
 
-            // Handle folder-based page (.synthos/pages/name/)
+            // Handle folder-based page (<localFolder>/pages/name/)
             const folderPath = path.join(config.pagesFolder, 'pages', name);
             if (await checkIfExists(folderPath)) {
                 await copyFolderRecursive(folderPath, path.join(migratedFolder, name));
             }
 
+            // Clear stale version files (undo snapshots from the old page version)
+            await clearVersions(config.pagesFolder, name);
+
             // Update metadata
             metadata.pageVersion = PAGE_VERSION;
             metadata.lastModified = new Date().toISOString();
@@ -822,21 +890,27 @@ Return ONLY the JSON object.`};
 
             // Try user pages folder first, then required pages
             const userPageDir = path.join(config.pagesFolder, 'pages', name);
-            const requiredPageFile = path.join(config.requiredPagesFolder, `${name}.html`);
+            let requiredPageDir: string | undefined;
+            for (const folder of config.requiredPagesFolders) {
+                if (await checkIfExists(path.join(folder, name, 'page.html'))) {
+                    requiredPageDir = path.join(folder, name);
+                    break;
+                }
+            }
             let sourceDir: string | null = null;
 
             if (await checkIfExists(path.join(userPageDir, 'page.html'))) {
                 sourceDir = userPageDir;
-            } else if (await checkIfExists(requiredPageFile)) {
+            } else if (requiredPageDir) {
                 // For required pages, create a temp-like zip with just the HTML
                 const zip = new AdmZip();
-                const html = await loadFile(requiredPageFile);
+                const html = await loadFile(path.join(requiredPageDir, 'page.html'));
                 zip.addFile(`${name}/page.html`, Buffer.from(html, 'utf-8'));
 
                 // Include page.json if it exists
-                const requiredMetaFile = path.join(config.requiredPagesFolder, `${name}.json`);
-                if (await checkIfExists(requiredMetaFile)) {
-                    const meta = await loadFile(requiredMetaFile);
+                const metaPath = path.join(requiredPageDir, 'page.json');
+                if (await checkIfExists(metaPath)) {
+                    const meta = await loadFile(metaPath);
                     zip.addFile(`${name}/page.json`, Buffer.from(meta, 'utf-8'));
                 }
 
@@ -863,4 +937,39 @@ Return ONLY the JSON object.`};
             res.status(500).json({ error: (err as Error).message });
         }
     });
+
+    // Ask a question about a page (with full page HTML context)
+    app.post('/api/pages/:name/ask', async (req, res) => {
+        await requiresSettings(res, config.pagesFolder, async (settings) => {
+            const { name } = req.params;
+            const { question } = req.body;
+            if (typeof question !== 'string' || !question.trim()) {
+                res.status(400).json({ error: 'question is required' });
+                return;
+            }
+
+            // Load the page HTML
+            const html = await loadPageWithFallback(name, config, false);
+            if (!html) {
+                res.status(404).json({ error: `Page "${name}" not found` });
+                return;
+            }
+
+            // Create completion (uses 'chat' model, not 'builder')
+            const complete = await createCompletePrompt(config.pagesFolder, 'chat', req.body.model);
+
+            const system = {
+                role: 'system' as const,
+                content: `You are a helpful assistant. The user will ask questions about a web page. Answer based on the page content provided.\n\n<PAGE_HTML>\n${html}`
+            };
+            const prompt = { role: 'user' as const, content: question };
+
+            const result = await complete({ system, prompt });
+            if (result.completed) {
+                res.json({ answer: result.value });
+            } else {
+                res.status(500).json({ error: result.error?.message || 'Completion failed' });
+            }
+        });
+    });
 }

package/src/service/useConnectorRoutes.ts

@@ -2,7 +2,7 @@ import { Application } from 'express';
 import { SynthOSConfig } from '../init';
 import { loadSettings, saveSettings } from '../settings';
 import {
-    CONNECTOR_REGISTRY,
+    getConnectorRegistry,
     ConnectorSummary,
     ConnectorDetail,
     ConnectorCallRequest,
@@ -21,7 +21,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
             const categoryFilter = req.query.category as string | undefined;
             const idFilter = req.query.id as string | undefined;
 
-            const list: ConnectorSummary[] = CONNECTOR_REGISTRY
+            const list: ConnectorSummary[] = getConnectorRegistry(config.serviceConnectorsFolders)
                 .filter(def => {
                     if (categoryFilter && def.category !== categoryFilter) return false;
                     if (idFilter && def.id !== idFilter) return false;
@@ -54,7 +54,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
     app.get('/api/connectors/:id', async (req, res) => {
         try {
             const { id } = req.params;
-            const def = CONNECTOR_REGISTRY.find(d => d.id === id);
+            const def = getConnectorRegistry(config.serviceConnectorsFolders).find(d => d.id === id);
             if (!def) {
                 res.status(404).json({ error: `Connector "${id}" not found` });
                 return;
@@ -88,7 +88,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
     app.post('/api/connectors/:id', async (req, res) => {
         try {
             const { id } = req.params;
-            const def = CONNECTOR_REGISTRY.find(d => d.id === id);
+            const def = getConnectorRegistry(config.serviceConnectorsFolders).find(d => d.id === id);
             if (!def) {
                 res.status(404).json({ error: `Connector "${id}" not found` });
                 return;
@@ -164,7 +164,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
     app.get('/api/connectors/:id/authorize', async (req, res) => {
         try {
             const { id } = req.params;
-            const def = CONNECTOR_REGISTRY.find(d => d.id === id);
+            const def = getConnectorRegistry(config.serviceConnectorsFolders).find(d => d.id === id);
             if (!def || def.authStrategy !== 'oauth2') {
                 res.status(400).json({ error: `Connector "${id}" is not an OAuth2 connector` });
                 return;
@@ -214,7 +214,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
             const state = JSON.parse(stateRaw) as { connector: string };
             const connectorId = state.connector;
 
-            const def = CONNECTOR_REGISTRY.find(d => d.id === connectorId);
+            const def = getConnectorRegistry(config.serviceConnectorsFolders).find(d => d.id === connectorId);
             if (!def || def.authStrategy !== 'oauth2') {
                 res.status(400).json({ error: `Unknown OAuth2 connector: ${connectorId}` });
                 return;
@@ -326,7 +326,7 @@ export function useConnectorRoutes(config: SynthOSConfig, app: Application): voi
                 return;
             }
 
-            const def = CONNECTOR_REGISTRY.find(d => d.id === request.connector);
+            const def = getConnectorRegistry(config.serviceConnectorsFolders).find(d => d.id === request.connector);
             if (!def) {
                 res.status(404).json({ error: `Connector "${request.connector}" not found` });
                 return;

package/src/service/useFileRoutes.ts

@@ -0,0 +1,127 @@
+import { Application } from 'express';
+import express from 'express';
+import fs from 'fs/promises';
+import path from 'path';
+import { SynthOSConfig } from '../init';
+import { checkIfExists, ensureFolderExists } from '../files';
+
+export function useFileRoutes(config: SynthOSConfig, app: Application): void {
+    // List files in a page's files/ folder
+    app.get('/api/files/:page', async (req, res) => {
+        try {
+            const folder = filesFolder(config, req.params.page);
+            if (!(await checkIfExists(folder))) {
+                res.json({ files: [] });
+                return;
+            }
+
+            const entries = await fs.readdir(folder);
+            const files: { name: string; size: number }[] = [];
+            for (const entry of entries) {
+                const stat = await fs.stat(path.join(folder, entry));
+                if (stat.isFile()) {
+                    files.push({ name: entry, size: stat.size });
+                }
+            }
+            res.json({ files });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // Download/serve a specific file
+    app.get('/api/files/:page/:filename', async (req, res) => {
+        try {
+            const filePath = safeFilePath(config, req.params.page, req.params.filename);
+            if (!filePath) {
+                res.status(400).json({ error: 'Invalid filename' });
+                return;
+            }
+
+            if (!(await checkIfExists(filePath))) {
+                res.status(404).json({ error: 'File not found' });
+                return;
+            }
+
+            res.sendFile(filePath);
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // Upload a file (raw body + x-filename header)
+    app.post('/api/files/:page', express.raw({ type: '*/*', limit: '50mb' }), async (req, res) => {
+        try {
+            const filename = req.headers['x-filename'] as string | undefined;
+            if (!filename || filename.trim().length === 0) {
+                res.status(400).json({ error: 'x-filename header is required' });
+                return;
+            }
+
+            const filePath = safeFilePath(config, req.params.page, filename);
+            if (!filePath) {
+                res.status(400).json({ error: 'Invalid filename' });
+                return;
+            }
+
+            const folder = filesFolder(config, req.params.page);
+            await ensureFolderExists(folder);
+            await fs.writeFile(filePath, req.body as Buffer);
+
+            const stat = await fs.stat(filePath);
+            res.status(201).json({ name: filename, size: stat.size });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // Delete a file
+    app.delete('/api/files/:page/:filename', async (req, res) => {
+        try {
+            const filePath = safeFilePath(config, req.params.page, req.params.filename);
+            if (!filePath) {
+                res.status(400).json({ error: 'Invalid filename' });
+                return;
+            }
+
+            if (!(await checkIfExists(filePath))) {
+                res.status(404).json({ error: 'File not found' });
+                return;
+            }
+
+            await fs.unlink(filePath);
+            res.json({ deleted: true });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function filesFolder(config: SynthOSConfig, page: string): string {
+    return path.join(config.pagesFolder, 'pages', page, 'files');
+}
+
+/**
+ * Resolve a filename inside the page's files/ folder with path-traversal protection.
+ * Returns the absolute path if safe, or null if the filename is invalid.
+ */
+function safeFilePath(config: SynthOSConfig, page: string, filename: string): string | null {
+    // Reject obviously bad filenames
+    if (!filename || filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+        return null;
+    }
+    const folder = filesFolder(config, page);
+    const resolved = path.resolve(folder, filename);
+    if (!resolved.startsWith(path.resolve(folder))) {
+        return null;
+    }
+    return resolved;
+}