synthos 0.7.1 → 0.8.0

package/src/service/useAgentRoutes.ts

@@ -0,0 +1,423 @@
+import { Application } from 'express';
+import { SynthOSConfig } from '../init';
+import { loadSettings, saveSettings } from '../settings';
+import {
+    AgentConfig,
+    AgentProvider,
+    a2aProvider,
+    openclawProvider,
+    discoverA2AAgent,
+    discoverOpenClawAgent,
+    connectAgent,
+    disconnectAgent,
+    getAgentStatus,
+    getTunnelStatus,
+} from '../agents';
+import { v4 as uuidv4 } from 'uuid';
+
+export function useAgentRoutes(config: SynthOSConfig, app: Application): void {
+
+    /** Strip the token and sshTunnel.password fields, add connection/tunnel status for agent responses. */
+    function toClientAgent(agent: AgentConfig): Record<string, unknown> {
+        const { token: _, sshTunnel, ...rest } = agent;
+        const status = agent.provider === 'openclaw' ? getAgentStatus(agent.id) : undefined;
+        const tunnelStatus = sshTunnel?.enabled ? getTunnelStatus(agent.id) : undefined;
+        // Expose sshTunnel config without the password
+        const sshTunnelClient = sshTunnel ? { enabled: sshTunnel.enabled, command: sshTunnel.command } : undefined;
+        return {
+            ...rest,
+            ...(sshTunnelClient ? { sshTunnel: sshTunnelClient } : {}),
+            ...(status ? { connected: status.connected && status.authenticated } : {}),
+            ...(tunnelStatus ? { tunnelStatus } : {}),
+        };
+    }
+
+    /** Try to connect an OpenClaw agent (fire-and-forget, logs errors). */
+    function tryConnectAgent(agent: AgentConfig): void {
+        if (agent.provider !== 'openclaw' || !agent.token || !agent.enabled) return;
+        connectAgent({
+            id: agent.id,
+            name: agent.name,
+            url: agent.url,
+            token: agent.token,
+            sshTunnel: agent.sshTunnel,
+        })
+            .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}`));
+    }
+
+    // Auto-connect all enabled OpenClaw agents on startup
+    (async () => {
+        try {
+            const settings = await loadSettings(config.pagesFolder);
+            for (const agent of settings.agents ?? []) {
+                tryConnectAgent(agent);
+            }
+        } catch (err) {
+            console.warn('[Agents] Failed to auto-connect agents on startup:', err);
+        }
+    })();
+
+    // GET /api/agents — List configured agents (with optional filters)
+    app.get('/api/agents', async (req, res) => {
+        try {
+            const settings = await loadSettings(config.pagesFolder);
+            let agents = settings.agents ?? [];
+
+            // Filter by enabled
+            if (req.query.enabled === 'true') {
+                agents = agents.filter(a => a.enabled);
+            }
+
+            // Filter by provider
+            if (typeof req.query.provider === 'string') {
+                agents = agents.filter(a => a.provider === req.query.provider);
+            }
+
+            res.json(agents.map(toClientAgent));
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/discover — Discover agent by URL + type
+    app.post('/api/agents/discover', async (req, res) => {
+        try {
+            const { url, type, token } = req.body;
+            if (!url || typeof url !== 'string') {
+                res.status(400).json({ error: 'url is required' });
+                return;
+            }
+
+            if (type === 'openclaw') {
+                if (!token || typeof token !== 'string') {
+                    res.status(400).json({ error: 'token is required for OpenClaw discovery' });
+                    return;
+                }
+                const result = await discoverOpenClawAgent(url, token);
+                res.json(result);
+            } else {
+                // Default to A2A
+                const card = await discoverA2AAgent(url);
+                res.json(card);
+            }
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(502).json({ error: `Failed to discover agent: ${(err as Error).message}` });
+        }
+    });
+
+    // POST /api/agents — Upsert agent config
+    app.post('/api/agents', async (req, res) => {
+        try {
+            const body = req.body as Partial<AgentConfig>;
+            if (!body.url || !body.name) {
+                res.status(400).json({ error: 'url and name are required' });
+                return;
+            }
+
+            const settings = await loadSettings(config.pagesFolder);
+            const agents = settings.agents ? [...settings.agents] : [];
+
+            const agentConfig: AgentConfig = {
+                id: body.id || uuidv4(),
+                url: body.url,
+                name: body.name,
+                description: body.description || '',
+                iconUrl: body.iconUrl,
+                enabled: body.enabled ?? true,
+                provider: body.provider ?? 'a2a',
+                token: body.token,
+                sessionKey: body.sessionKey,
+                capabilities: body.capabilities,
+                skills: body.skills,
+                sshTunnel: body.sshTunnel,
+            };
+
+            // Upsert: replace if same id exists, otherwise append
+            const idx = agents.findIndex(a => a.id === agentConfig.id);
+            if (idx !== -1) {
+                // Preserve existing token/sessionKey if not provided in update
+                if (!agentConfig.token && agents[idx].token) {
+                    agentConfig.token = agents[idx].token;
+                }
+                if (!agentConfig.sessionKey && agents[idx].sessionKey) {
+                    agentConfig.sessionKey = agents[idx].sessionKey;
+                }
+                // Preserve existing sshTunnel if not provided in update
+                if (!agentConfig.sshTunnel && agents[idx].sshTunnel) {
+                    agentConfig.sshTunnel = agents[idx].sshTunnel;
+                }
+                agents[idx] = agentConfig;
+            } else {
+                agents.push(agentConfig);
+            }
+
+            await saveSettings(config.pagesFolder, { agents });
+
+            // Auto-connect OpenClaw agents after save
+            tryConnectAgent(agentConfig);
+
+            res.json(toClientAgent(agentConfig));
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // PATCH /api/agents/:id — Toggle enabled/disabled or partial update
+    app.patch('/api/agents/:id', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const settings = await loadSettings(config.pagesFolder);
+            const agents = settings.agents ? [...settings.agents] : [];
+            const idx = agents.findIndex(a => a.id === id);
+            if (idx === -1) {
+                res.status(404).json({ error: `Agent "${id}" not found` });
+                return;
+            }
+
+            const body = req.body as Partial<AgentConfig>;
+            if (typeof body.enabled === 'boolean') agents[idx].enabled = body.enabled;
+            if (typeof body.name === 'string') agents[idx].name = body.name;
+            if (typeof body.description === 'string') agents[idx].description = body.description;
+
+            await saveSettings(config.pagesFolder, { agents });
+
+            // Connect or disconnect based on enabled state
+            if (agents[idx].provider === 'openclaw') {
+                if (agents[idx].enabled) {
+                    tryConnectAgent(agents[idx]);
+                } else {
+                    disconnectAgent(agents[idx].id);
+                }
+            }
+
+            res.json(toClientAgent(agents[idx]));
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // DELETE /api/agents/:id — Remove agent
+    app.delete('/api/agents/:id', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const settings = await loadSettings(config.pagesFolder);
+            const agent = (settings.agents ?? []).find(a => a.id === id);
+
+            // Disconnect if OpenClaw
+            if (agent?.provider === 'openclaw') {
+                disconnectAgent(id);
+            }
+
+            const agents = (settings.agents ?? []).filter(a => a.id !== id);
+            await saveSettings(config.pagesFolder, { agents });
+            res.json({ deleted: true });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/connect — Manually trigger WebSocket connection
+    app.post('/api/agents/:id/connect', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const settings = await loadSettings(config.pagesFolder);
+            const agent = (settings.agents ?? []).find(a => a.id === id);
+            if (!agent) {
+                res.status(404).json({ error: `Agent "${id}" not found` });
+                return;
+            }
+            if (agent.provider !== 'openclaw') {
+                res.status(400).json({ error: 'Only OpenClaw agents support WebSocket connections' });
+                return;
+            }
+            if (!agent.token) {
+                res.status(400).json({ error: 'Agent has no token configured' });
+                return;
+            }
+
+            await connectAgent({ id: agent.id, name: agent.name, url: agent.url, token: agent.token, sshTunnel: agent.sshTunnel });
+            const status = getAgentStatus(agent.id);
+            res.json({ connected: status.connected, authenticated: status.authenticated });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/disconnect — Disconnect WebSocket
+    app.post('/api/agents/:id/disconnect', async (req, res) => {
+        try {
+            const { id } = req.params;
+            disconnectAgent(id);
+            res.json({ disconnected: true });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/send — Send message to agent (dispatches by provider)
+    app.post('/api/agents/:id/send', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const { message, attachments } = req.body;
+            if (!message || typeof message !== 'string') {
+                res.status(400).json({ error: 'message is required' });
+                return;
+            }
+
+            const settings = await loadSettings(config.pagesFolder);
+            const agent = (settings.agents ?? []).find(a => a.id === id);
+            if (!agent) {
+                res.status(404).json({ error: `Agent "${id}" not found` });
+                return;
+            }
+
+            if (!agent.enabled) {
+                res.status(400).json({ error: `Agent "${agent.name}" is disabled` });
+                return;
+            }
+
+            // Dispatch to the correct provider
+            const provider = agent.provider === 'openclaw' ? openclawProvider : a2aProvider;
+            const result = await provider.send(agent, message, attachments);
+            res.json(result);
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // -----------------------------------------------------------------------
+    // Helper: load agent + resolve provider, return 404/400 on failure
+    // -----------------------------------------------------------------------
+    async function withAgent(
+        id: string,
+        res: import('express').Response,
+        fn: (agent: AgentConfig, provider: AgentProvider) => Promise<void>,
+    ): Promise<void> {
+        const settings = await loadSettings(config.pagesFolder);
+        const agent = (settings.agents ?? []).find(a => a.id === id);
+        if (!agent) {
+            res.status(404).json({ error: `Agent "${id}" not found` });
+            return;
+        }
+        if (!agent.enabled) {
+            res.status(400).json({ error: `Agent "${agent.name}" is disabled` });
+            return;
+        }
+        const provider: AgentProvider = agent.provider === 'openclaw' ? openclawProvider : a2aProvider;
+        await fn(agent, provider);
+    }
+
+    // -----------------------------------------------------------------------
+    // Chat lifecycle routes (Phase 1)
+    // -----------------------------------------------------------------------
+
+    // POST /api/agents/:id/chat/history — Get chat history
+    app.post('/api/agents/:id/chat/history', async (req, res) => {
+        try {
+            await withAgent(req.params.id, res, async (agent, provider) => {
+                if (!provider.getHistory) {
+                    res.status(501).json({ error: 'Operation not supported by this agent provider' });
+                    return;
+                }
+                const messages = await provider.getHistory(agent);
+                res.json({ messages });
+            });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/chat/abort — Abort in-flight chat
+    app.post('/api/agents/:id/chat/abort', async (req, res) => {
+        try {
+            await withAgent(req.params.id, res, async (agent, provider) => {
+                if (!provider.abortChat) {
+                    res.status(501).json({ error: 'Operation not supported by this agent provider' });
+                    return;
+                }
+                await provider.abortChat(agent);
+                res.json({ ok: true });
+            });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/chat/clear — Clear/reset chat session
+    app.post('/api/agents/:id/chat/clear', async (req, res) => {
+        try {
+            await withAgent(req.params.id, res, async (agent, provider) => {
+                if (!provider.clearSession) {
+                    res.status(501).json({ error: 'Operation not supported by this agent provider' });
+                    return;
+                }
+                await provider.clearSession(agent);
+                res.json({ ok: true });
+            });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // POST /api/agents/:id/stream — SSE streaming endpoint
+    app.post('/api/agents/:id/stream', async (req, res) => {
+        try {
+            const { id } = req.params;
+            const { message, attachments } = req.body;
+            if (!message || typeof message !== 'string') {
+                res.status(400).json({ error: 'message is required' });
+                return;
+            }
+
+            const settings = await loadSettings(config.pagesFolder);
+            const agent = (settings.agents ?? []).find(a => a.id === id);
+            if (!agent) {
+                res.status(404).json({ error: `Agent "${id}" not found` });
+                return;
+            }
+
+            if (!agent.enabled) {
+                res.status(400).json({ error: `Agent "${agent.name}" is disabled` });
+                return;
+            }
+
+            // Set up SSE headers
+            res.setHeader('Content-Type', 'text/event-stream');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            res.flushHeaders();
+
+            // Dispatch to the correct provider's streaming method
+            const provider = agent.provider === 'openclaw' ? openclawProvider : a2aProvider;
+
+            for await (const event of provider.sendStream(agent, message, attachments)) {
+                res.write(`data: ${JSON.stringify(event)}\n\n`);
+                if (event.kind === 'done' || event.kind === 'error') break;
+            }
+
+            res.write('data: [DONE]\n\n');
+            res.end();
+        } catch (err: unknown) {
+            console.error(err);
+            // If headers already sent, just end the stream
+            if (res.headersSent) {
+                res.write(`data: ${JSON.stringify({ kind: 'error', data: (err as Error).message })}\n\n`);
+                res.end();
+            } else {
+                res.status(500).json({ error: (err as Error).message });
+            }
+        }
+    });
+}

package/src/service/useApiRoutes.ts

@@ -1,12 +1,15 @@
 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, deleteFile, loadFile } from "../files";
+import { checkIfExists, copyFile, copyFolderRecursive, deleteFile, ensureFolderExists, loadFile } from "../files";
 import {getModelEntry, loadSettings, saveSettings, ServicesConfig } from "../settings";
 import { Application } from 'express';
+import express from 'express';
 import { SynthOSConfig } from "../init";
 import { createCompletePrompt, PROVIDERS } from "./createCompletePrompt";
 import { generateDefaultImage, generateImage } from "./generateImage";
-import { chainOfThought } from "agentm-core";
+import { chainOfThought } from "../models";
 import { requiresSettings } from "./requiresSettings";
 import { executeScript } from "../scripts";
 import { listThemes, loadTheme, loadThemeInfo } from "../themes";
@@ -52,6 +55,96 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
         res.json(pages);
     });
 
+    // Import a page from a zip file
+    app.post('/api/pages/import', express.raw({ type: 'application/zip', limit: '50mb' }), async (req, res) => {
+        try {
+            const zipBuffer = req.body as Buffer;
+            if (!zipBuffer || zipBuffer.length === 0) {
+                res.status(400).json({ error: 'Empty request body' });
+                return;
+            }
+
+            let zip: AdmZip;
+            try {
+                zip = new AdmZip(zipBuffer);
+            } catch {
+                res.status(400).json({ error: 'Invalid zip file' });
+                return;
+            }
+
+            const entries = zip.getEntries();
+            if (entries.length === 0) {
+                res.status(400).json({ error: 'Zip file is empty' });
+                return;
+            }
+
+            // Determine top-level folder name and validate structure
+            const firstEntry = entries[0].entryName;
+            const topFolder = firstEntry.split('/')[0];
+            const hasPageHtml = entries.some(e => e.entryName === `${topFolder}/page.html`);
+            if (!hasPageHtml) {
+                res.status(400).json({ error: 'Zip must contain a <folder>/page.html entry' });
+                return;
+            }
+
+            // Sanitize page name from folder name
+            let pageName = topFolder.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+            if (!pageName) {
+                res.status(400).json({ error: 'Could not derive a valid page name from zip contents' });
+                return;
+            }
+
+            // Auto-append _1, _2, etc. on name conflicts
+            let finalName = pageName;
+            let suffix = 0;
+            while (await checkIfExists(path.join(config.pagesFolder, 'pages', finalName))) {
+                suffix++;
+                finalName = `${pageName}_${suffix}`;
+            }
+
+            const targetDir = path.join(config.pagesFolder, 'pages', finalName);
+            await ensureFolderExists(targetDir);
+
+            // Extract entries with path traversal protection
+            for (const entry of entries) {
+                if (entry.isDirectory) continue;
+
+                // Strip the top-level folder prefix to get relative path
+                const relativePath = entry.entryName.substring(topFolder.length + 1);
+                if (!relativePath) continue;
+
+                const resolvedPath = path.resolve(targetDir, relativePath);
+                if (!resolvedPath.startsWith(path.resolve(targetDir))) {
+                    // Path traversal — skip this entry
+                    continue;
+                }
+
+                await ensureFolderExists(path.dirname(resolvedPath));
+                await fs.writeFile(resolvedPath, entry.getData());
+            }
+
+            // Update metadata: set createdDate and lastModified to now
+            const now = new Date().toISOString();
+            const existingMeta = await loadPageMetadata(config.pagesFolder, finalName);
+            const metadata: PageMetadata = {
+                title: existingMeta?.title ?? '',
+                categories: existingMeta?.categories ?? [],
+                pinned: existingMeta?.pinned ?? false,
+                showInAll: existingMeta?.showInAll ?? true,
+                createdDate: now,
+                lastModified: now,
+                pageVersion: existingMeta?.pageVersion ?? PAGE_VERSION,
+                mode: existingMeta?.mode ?? 'unlocked',
+            };
+            await savePageMetadata(config.pagesFolder, finalName, metadata);
+
+            res.status(201).json({ name: finalName, title: metadata.title });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
     // Get page metadata
     app.get('/api/pages/:name', async (req, res) => {
         try {
@@ -286,9 +379,6 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
             if (Array.isArray(settings.models)) {
                 for (const entry of settings.models) {
                     if (entry.configuration) {
-                        if (typeof entry.configuration.maxTokens === 'string') {
-                            entry.configuration.maxTokens = parseInt(entry.configuration.maxTokens);
-                        }
                     }
                     if (typeof entry.logCompletions === 'string') {
                         entry.logCompletions = entry.logCompletions === 'true';
@@ -326,9 +416,8 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     app.post('/api/generate/completion', async (req, res) => {
         await requiresSettings(res, config.pagesFolder, async (settings) => {
             const { prompt, temperature } = req.body;
-            const maxTokens = getModelEntry(settings, 'chat').configuration.maxTokens;
             const completePrompt = await createCompletePrompt(config.pagesFolder, 'chat', req.body.model);
-            const response = await chainOfThought({ question: prompt, temperature, maxTokens, completePrompt });
+            const response = await chainOfThought({ question: prompt, temperature, completePrompt });
             if (response.completed) {
                 res.json(response.value ?? {});
             } else {
@@ -342,12 +431,26 @@ export function useApiRoutes(config: SynthOSConfig, app: Application): void {
     app.post('/api/brainstorm', async (req, res) => {
         await requiresSettings(res, config.pagesFolder, async (settings) => {
             const { context, messages } = req.body;
-            const maxTokens = getModelEntry(settings, 'chat').configuration.maxTokens;
             const completePrompt = await createCompletePrompt(config.pagesFolder, 'chat');
 
             const system: { role: 'system'; content: string } = {
                 role: 'system',
-                content: `You are a creative brainstorming assistant for SynthOS, a tool that builds web pages through conversation. The user is brainstorming — exploring ideas before building. Be concise, creative, and collaborative. Suggest concrete approaches when you can.
+                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. 
+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.
+Just help expand their thoughts into a great next prompt.
+
+<CONTEXT>
+${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.
+
+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.
 
 You MUST return your response as a JSON object with exactly these fields:
 {
@@ -358,12 +461,7 @@ You MUST return your response as a JSON object with exactly these fields:
 
 suggestions — 2-4 short phrases the user can click to continue the conversation. These are next-step options: directions to explore, questions to answer, or choices to make. Keep each under 60 characters. Always provide suggestions.
 
-Return ONLY the JSON object. No markdown fences.
-
-<CONTEXT>
-${context}
-</CONTEXT>`
-            };
+Return ONLY the JSON object.`};
 
             // Format multi-turn conversation into a single prompt
             const formatted = (messages as { role: string; content: string }[]).map(m =>
@@ -372,7 +470,7 @@ ${context}
 
             const prompt: { role: 'user'; content: string } = { role: 'user', content: formatted };
 
-            const result = await completePrompt({ prompt, system, maxTokens, jsonMode: true });
+            const result = await completePrompt({ prompt, system, jsonMode: true });
             if (result.completed) {
                 let response = result.value || '';
                 let brainstormPrompt = '';
@@ -689,14 +787,22 @@ ${context}
             // Save upgraded HTML to v2 folder structure
             await savePageState(config.pagesFolder, name, migratedHtml);
 
-            // Move legacy flat file to .migrated folder instead of deleting
+            // Backup original page to .migrated/ before overwriting
+            const migratedFolder = path.join(config.pagesFolder, '.migrated');
+
+            // Handle legacy flat file (.synthos/pagename.html)
             const flatPath = path.join(config.pagesFolder, `${name}.html`);
             if (await checkIfExists(flatPath)) {
-                const migratedFolder = path.join(config.pagesFolder, '.migrated');
                 await copyFile(flatPath, migratedFolder);
                 await deleteFile(flatPath);
             }
 
+            // Handle folder-based page (.synthos/pages/name/)
+            const folderPath = path.join(config.pagesFolder, 'pages', name);
+            if (await checkIfExists(folderPath)) {
+                await copyFolderRecursive(folderPath, path.join(migratedFolder, name));
+            }
+
             // Update metadata
             metadata.pageVersion = PAGE_VERSION;
             metadata.lastModified = new Date().toISOString();
@@ -708,4 +814,53 @@ ${context}
             res.status(500).json({ error: (err as Error).message });
         }
     });
+
+    // Export a page as a zip file
+    app.get('/api/pages/:name/export', async (req, res) => {
+        try {
+            const { name } = req.params;
+
+            // 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 sourceDir: string | null = null;
+
+            if (await checkIfExists(path.join(userPageDir, 'page.html'))) {
+                sourceDir = userPageDir;
+            } else if (await checkIfExists(requiredPageFile)) {
+                // For required pages, create a temp-like zip with just the HTML
+                const zip = new AdmZip();
+                const html = await loadFile(requiredPageFile);
+                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);
+                    zip.addFile(`${name}/page.json`, Buffer.from(meta, 'utf-8'));
+                }
+
+                const zipBuffer = zip.toBuffer();
+                res.set('Content-Type', 'application/zip');
+                res.set('Content-Disposition', `attachment; filename="${name}.zip"`);
+                res.send(zipBuffer);
+                return;
+            } else {
+                res.status(404).json({ error: `Page "${name}" not found` });
+                return;
+            }
+
+            // Zip the entire page folder
+            const zip = new AdmZip();
+            zip.addLocalFolder(sourceDir, name);
+            const zipBuffer = zip.toBuffer();
+
+            res.set('Content-Type', 'application/zip');
+            res.set('Content-Disposition', `attachment; filename="${name}.zip"`);
+            res.send(zipBuffer);
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
 }