synthos 0.9.0 → 0.10.0

package/src/init.ts

@@ -1,9 +1,10 @@
 import * as fs from 'fs/promises';
 import path from "path";
-import { checkIfExists, copyFile, copyFolderRecursive, deleteFile, ensureFolderExists, findFileInFolders, listFiles, listFolders, saveFile } from "./files";
+import { checkIfExists, findFileInFolders, listFolders } from "./files";
 import { PAGE_VERSION, getRequiredPages } from "./pages";
 import { DefaultSettings } from "./settings";
 import { Customizer } from './customizer';
+import { StorageProvider, FsStorageProvider } from './storage';
 
 export interface SynthOSConfig {
     localFolder: string;
@@ -15,6 +16,7 @@ export interface SynthOSConfig {
     staticFilesFolders: string[];
     serviceConnectorsFolders: string[];
     requiredPages: string[];
+    storageProvider: StorageProvider;
     debug: boolean;
     debugPageUpdates: boolean;
 }
@@ -62,14 +64,17 @@ export async function createConfig(
             path.join(__dirname, '../service-connectors')
         ),
         requiredPages,
+        storageProvider: customizer?.storageProvider ?? new FsStorageProvider(),
         debug: options?.debug ?? false,
         debugPageUpdates: options?.debugPageUpdates ?? false
     };
 }
 
 export async function init(config: SynthOSConfig, includeDefaultPages: boolean = true): Promise<boolean> {
+    const sp = config.storageProvider;
+
     // Check for existing folder
-    if (await checkIfExists(config.pagesFolder)) {
+    if (await sp.checkIfExists(config.pagesFolder)) {
         await repairMissingFolders(config);
         return false;
     }
@@ -77,17 +82,17 @@ export async function init(config: SynthOSConfig, includeDefaultPages: boolean =
     console.log(`Initializing ${config.localFolder} folder...`);
 
     // Create pages folder
-    await ensureFolderExists(config.pagesFolder);
+    await sp.ensureFolderExists(config.pagesFolder);
 
     // Create mandatory files
-    await saveFile(path.join(config.pagesFolder, '.gitignore'), 'settings.json\n');
-    await saveFile(path.join(config.pagesFolder, 'settings.json'), JSON.stringify(DefaultSettings, null, 4));
-    await saveFile(path.join(config.pagesFolder, 'settings.json.example'), JSON.stringify(DefaultSettings, null, 4));
+    await sp.saveFile(path.join(config.pagesFolder, '.gitignore'), 'settings.json\n');
+    await sp.saveFile(path.join(config.pagesFolder, 'settings.json'), JSON.stringify(DefaultSettings, null, 4));
+    await sp.saveFile(path.join(config.pagesFolder, 'settings.json.example'), JSON.stringify(DefaultSettings, null, 4));
 
     // Setup default scripts
     console.log(`Copying default scripts to ${config.localFolder} folder...`);
     const scriptsFolder = path.join(config.pagesFolder, 'scripts');
-    await ensureFolderExists(scriptsFolder);
+    await sp.ensureFolderExists(scriptsFolder);
     const scriptFilename = ({
         win32: 'windows-terminal.json',
         darwin: 'mac-terminal.json',
@@ -95,30 +100,34 @@ export async function init(config: SynthOSConfig, includeDefaultPages: boolean =
     } as Record<string, string>)[process.platform] ?? 'linux-terminal.json';
     const scriptSrc = await findFileInFolders(config.defaultScriptsFolders, scriptFilename);
     if (scriptSrc) {
-        await copyFile(scriptSrc, scriptsFolder);
+        // Read from package (local fs), write to user storage (provider)
+        const data = await fs.readFile(scriptSrc);
+        await sp.saveBuffer(path.join(scriptsFolder, path.basename(scriptSrc)), data);
     }
 
-    await saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
+    await sp.saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
 
     // Create empty themes folder — default themes are served directly from
     // defaultThemesFolders; users can add custom themes here.
-    await ensureFolderExists(path.join(config.pagesFolder, 'themes'));
+    await sp.ensureFolderExists(path.join(config.pagesFolder, 'themes'));
 
     // Copy pages
     if (includeDefaultPages) {
         console.log(`Copying default pages to ${config.localFolder} folder...`);
-        await copyDefaultPages(config.defaultPagesFolders, config.pagesFolder);
+        await copyDefaultPages(config, config.defaultPagesFolders);
     }
 
     return true;
 }
 
 async function repairMissingFolders(config: SynthOSConfig): Promise<void> {
+    const sp = config.storageProvider;
+
     // Rebuild scripts folder from defaults if missing
     const scriptsFolder = path.join(config.pagesFolder, 'scripts');
-    if (!await checkIfExists(scriptsFolder)) {
+    if (!await sp.checkIfExists(scriptsFolder)) {
         console.log(`Restoring default scripts to ${config.localFolder} folder...`);
-        await ensureFolderExists(scriptsFolder);
+        await sp.ensureFolderExists(scriptsFolder);
         const scriptFilename = ({
             win32: 'windows-terminal.json',
             darwin: 'mac-terminal.json',
@@ -126,30 +135,31 @@ async function repairMissingFolders(config: SynthOSConfig): Promise<void> {
         } as Record<string, string>)[process.platform] ?? 'linux-terminal.json';
         const scriptSrc = await findFileInFolders(config.defaultScriptsFolders, scriptFilename);
         if (scriptSrc) {
-            await copyFile(scriptSrc, scriptsFolder);
+            const data = await fs.readFile(scriptSrc);
+            await sp.saveBuffer(path.join(scriptsFolder, path.basename(scriptSrc)), data);
         }
-        await saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
+        await sp.saveFile(path.join(scriptsFolder, 'example.sh'), `#!/bin/bash\n\n# This is an example script\n\n# You can run this script using the following command:\n# sh ${config.localFolder}/scripts/example.sh\n\n# This script will print "Hello, World!" to the console\n\necho "Hello, World!"\n`);
     }
 
     // Ensure themes folder exists — default themes are served directly from
     // defaultThemesFolders; this folder is for user-added custom themes only.
-    await ensureFolderExists(path.join(config.pagesFolder, 'themes'));
+    await sp.ensureFolderExists(path.join(config.pagesFolder, 'themes'));
 
     // Ensure pages/ subfolder exists
     const pagesSubdir = path.join(config.pagesFolder, 'pages');
-    if (!await checkIfExists(pagesSubdir)) {
+    if (!await sp.checkIfExists(pagesSubdir)) {
         // No pages folder and no flat files — rebuild from defaults
-        const htmlFiles = (await listFiles(config.pagesFolder)).filter(f => f.endsWith('.html'));
+        const htmlFiles = (await sp.listFiles(config.pagesFolder)).filter(f => f.endsWith('.html'));
         if (htmlFiles.length === 0) {
             console.log(`Restoring default pages to ${config.localFolder}/pages/ folder...`);
-            await copyDefaultPages(config.defaultPagesFolders, config.pagesFolder);
+            await copyDefaultPages(config, config.defaultPagesFolders);
         } else {
-            await ensureFolderExists(pagesSubdir);
+            await sp.ensureFolderExists(pagesSubdir);
         }
     }
 
     // Migrate any stray flat .html files from root into pages/<name>/
-    await migrateFlatPages(config.pagesFolder, config.localFolder);
+    await migrateFlatPages(config);
 }
 
 function toTitleCase(name: string): string {
@@ -160,13 +170,15 @@ function toTitleCase(name: string): string {
         .replace(/\b\w/g, c => c.toUpperCase());
 }
 
-async function migrateFlatPages(pagesFolder: string, localFolder: string): Promise<void> {
+async function migrateFlatPages(config: SynthOSConfig): Promise<void> {
+    const sp = config.storageProvider;
+    const pagesFolder = config.pagesFolder;
     const pagesSubdir = path.join(pagesFolder, 'pages');
-    const htmlFiles = (await listFiles(pagesFolder)).filter(f => f.endsWith('.html'));
+    const htmlFiles = (await sp.listFiles(pagesFolder)).filter(f => f.endsWith('.html'));
     if (htmlFiles.length === 0) return;
 
-    console.log(`Migrating ${htmlFiles.length} page(s) to ${localFolder}/pages/ folder...`);
-    await ensureFolderExists(pagesSubdir);
+    console.log(`Migrating ${htmlFiles.length} page(s) to ${config.localFolder}/pages/ folder...`);
+    await sp.ensureFolderExists(pagesSubdir);
     const now = new Date().toISOString();
 
     for (const file of htmlFiles) {
@@ -174,12 +186,11 @@ async function migrateFlatPages(pagesFolder: string, localFolder: string): Promi
         const category = pageName.startsWith('[') ? 'Builder' : 'Pages';
         const title = toTitleCase(pageName);
         const pageFolder = path.join(pagesSubdir, pageName);
-        await ensureFolderExists(pageFolder);
-        await fs.copyFile(
-            path.join(pagesFolder, file),
-            path.join(pageFolder, 'page.html')
-        );
-        await saveFile(
+        await sp.ensureFolderExists(pageFolder);
+        // Both source and destination are user storage
+        const content = await sp.loadFile(path.join(pagesFolder, file));
+        await sp.saveFile(path.join(pageFolder, 'page.html'), content);
+        await sp.saveFile(
             path.join(pageFolder, 'page.json'),
             JSON.stringify({
                 title,
@@ -192,19 +203,20 @@ async function migrateFlatPages(pagesFolder: string, localFolder: string): Promi
                 mode: 'unlocked',
             }, null, 4)
         );
-        await deleteFile(path.join(pagesFolder, file));
+        await sp.deleteFile(path.join(pagesFolder, file));
     }
 }
 
-async function copyDefaultPages(srcFolders: string[], destFolder: string): Promise<void> {
-    const pagesDir = path.join(destFolder, 'pages');
-    await ensureFolderExists(pagesDir);
+async function copyDefaultPages(config: SynthOSConfig, srcFolders: string[]): Promise<void> {
+    const sp = config.storageProvider;
+    const pagesDir = path.join(config.pagesFolder, 'pages');
+    await sp.ensureFolderExists(pagesDir);
     const now = new Date().toISOString();
     const seen = new Set<string>();
 
     for (const srcFolder of srcFolders) {
-        if (!await checkIfExists(srcFolder)) continue;
-        const dirs = await listFolders(srcFolder);
+        if (!await checkIfExists(srcFolder)) continue;  // source is always local fs
+        const dirs = await listFolders(srcFolder);       // source is always local fs
         for (const dir of dirs) {
             const srcPageDir = path.join(srcFolder, dir);
             if (!await checkIfExists(path.join(srcPageDir, 'page.html'))) continue;
@@ -212,8 +224,11 @@ async function copyDefaultPages(srcFolders: string[], destFolder: string): Promi
             seen.add(dir);
 
             const pageFolder = path.join(pagesDir, dir);
-            await ensureFolderExists(pageFolder);
-            await fs.copyFile(path.join(srcPageDir, 'page.html'), path.join(pageFolder, 'page.html'));
+            await sp.ensureFolderExists(pageFolder);
+
+            // Read from local fs, write via provider
+            const htmlData = await fs.readFile(path.join(srcPageDir, 'page.html'));
+            await sp.saveBuffer(path.join(pageFolder, 'page.html'), htmlData);
 
             // Read companion page.json metadata from source folder, fall back to defaults
             let metadata: Record<string, unknown> = {};
@@ -237,17 +252,38 @@ async function copyDefaultPages(srcFolders: string[], destFolder: string): Promi
                     : typeof metadata.uxVersion === 'number' ? metadata.uxVersion : PAGE_VERSION,
                 mode: metadata.mode === 'locked' ? 'locked' : 'unlocked',
             };
-            await saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(fullMetadata, null, 4));
+            await sp.saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(fullMetadata, null, 4));
 
             // Copy data subfolders (anything that isn't page.html/page.json)
+            // Read from local fs, write via provider using cross-provider copy
             const subEntries = await fs.readdir(srcPageDir, { withFileTypes: true });
             for (const entry of subEntries) {
                 if (!entry.isDirectory()) continue;
-                await copyFolderRecursive(
+                await crossProviderCopyFolder(
                     path.join(srcPageDir, entry.name),
-                    path.join(pageFolder, entry.name)
+                    path.join(pageFolder, entry.name),
+                    sp
                 );
             }
         }
     }
 }
+
+/**
+ * Copy a folder from local filesystem to the storage provider.
+ * Reads from local fs, writes via provider.
+ */
+async function crossProviderCopyFolder(srcFolder: string, destFolder: string, sp: StorageProvider): Promise<void> {
+    await sp.ensureFolderExists(destFolder);
+    const entries = await fs.readdir(srcFolder, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcFolder, entry.name);
+        const destPath = path.join(destFolder, entry.name);
+        if (entry.isDirectory()) {
+            await crossProviderCopyFolder(srcPath, destPath, sp);
+        } else {
+            const data = await fs.readFile(srcPath);
+            await sp.saveBuffer(destPath, data);
+        }
+    }
+}

package/src/pages.ts

@@ -1,5 +1,6 @@
-import {checkIfExists, copyFolderRecursive, deleteFile, deleteFolder, ensureFolderExists, listFiles, listFolders, loadFile, saveFile} from './files';
+import {checkIfExists, listFolders, loadFile} from './files';
 import path from 'path';
+import { SynthOSConfig } from './init';
 
 /**
  * Derive the list of required page names by scanning *.html files
@@ -38,12 +39,15 @@ export interface PageInfo {
 
 export type PageMetadata = Omit<PageInfo, 'name'>;
 
-export async function loadPageMetadata(pagesFolder: string, name: string, fallbackFolders?: string[]): Promise<PageMetadata | undefined> {
+export async function loadPageMetadata(config: SynthOSConfig, name: string, fallbackFolders?: string[]): Promise<PageMetadata | undefined> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
+
     // 1. Try user override: <localFolder>/pages/<name>/page.json
     const metadataPath = path.join(pagesFolder, 'pages', name, 'page.json');
-    if (await checkIfExists(metadataPath)) {
+    if (await sp.checkIfExists(metadataPath)) {
         try {
-            const raw = await loadFile(metadataPath);
+            const raw = await sp.loadFile(metadataPath);
             const parsed = JSON.parse(raw);
             return parseMetadata(parsed);
         } catch {
@@ -51,7 +55,7 @@ export async function loadPageMetadata(pagesFolder: string, name: string, fallba
         }
     }
 
-    // 2. Try fallback folders: fallbackFolder/<name>/page.json
+    // 2. Try fallback folders: fallbackFolder/<name>/page.json (package content, always local fs)
     if (fallbackFolders) {
         for (const folder of fallbackFolders) {
             const candidate = path.join(folder, name, 'page.json');
@@ -84,10 +88,11 @@ export function parseMetadata(parsed: Record<string, unknown>): PageMetadata {
     };
 }
 
-export async function savePageMetadata(pagesFolder: string, name: string, metadata: PageMetadata): Promise<void> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    await ensureFolderExists(pageFolder);
-    await saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(metadata, null, 4));
+export async function savePageMetadata(config: SynthOSConfig, name: string, metadata: PageMetadata): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, 'page.json'), JSON.stringify(metadata, null, 4));
 }
 
 const DEFAULT_METADATA: PageMetadata = {
@@ -101,16 +106,18 @@ const DEFAULT_METADATA: PageMetadata = {
     mode: 'unlocked',
 };
 
-export async function listPages(pagesFolder: string, fallbackPagesFolders: string[]): Promise<PageInfo[]> {
+export async function listPages(config: SynthOSConfig, fallbackPagesFolders: string[]): Promise<PageInfo[]> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
     const pageMap = new Map<string, PageInfo>();
 
     // Folder-based pages under pages/ subdirectory
     const pagesSubdir = path.join(pagesFolder, 'pages');
-    if (await checkIfExists(pagesSubdir)) {
-        const folders = await listFolders(pagesSubdir);
+    if (await sp.checkIfExists(pagesSubdir)) {
+        const folders = await sp.listFolders(pagesSubdir);
         for (const folder of folders) {
-            if (await checkIfExists(path.join(pagesSubdir, folder, 'page.html'))) {
-                const metadata = await loadPageMetadata(pagesFolder, folder);
+            if (await sp.checkIfExists(path.join(pagesSubdir, folder, 'page.html'))) {
+                const metadata = await loadPageMetadata(config, folder);
                 pageMap.set(folder, {
                     name: folder,
                     ...(metadata ?? DEFAULT_METADATA),
@@ -120,7 +127,7 @@ export async function listPages(pagesFolder: string, fallbackPagesFolders: strin
     }
 
     // Legacy flat .html files in root (v1 pages)
-    const flatFiles = (await listFiles(pagesFolder)).filter(file => file.endsWith('.html'));
+    const flatFiles = (await sp.listFiles(pagesFolder)).filter(file => file.endsWith('.html'));
     for (const file of flatFiles) {
         const name = file.replace(/\.html$/, '');
         if (!pageMap.has(name)) {
@@ -146,7 +153,7 @@ export async function listPages(pagesFolder: string, fallbackPagesFolders: strin
         }
     }
 
-    // Add pages from fallback (required) pages folders
+    // Add pages from fallback (required) pages folders (package content, always local fs)
     for (const folder of fallbackPagesFolders) {
         if (!await checkIfExists(folder)) continue;
         const dirs = await listFolders(folder);
@@ -154,7 +161,7 @@ export async function listPages(pagesFolder: string, fallbackPagesFolders: strin
             if (pageMap.has(name)) continue;
             if (!await checkIfExists(path.join(folder, name, 'page.html'))) continue;
             // System page not yet in map — check for user override, then fallback page.json
-            const metadata = await loadPageMetadata(pagesFolder, name, fallbackPagesFolders);
+            const metadata = await loadPageMetadata(config, name, fallbackPagesFolders);
             pageMap.set(name, {
                 name,
                 title: metadata?.title ?? '',
@@ -176,11 +183,14 @@ export async function listPages(pagesFolder: string, fallbackPagesFolders: strin
     return entries;
 }
 
-export async function loadPageState(pagesFolder: string, name: string): Promise<string|undefined> {
+export async function loadPageState(config: SynthOSConfig, name: string): Promise<string|undefined> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
+
     // Check for working-state version files first
-    const latestVersion = await getLatestVersion(pagesFolder, name);
+    const latestVersion = await getLatestVersion(config, name);
     if (latestVersion > 0) {
-        const versionHtml = await loadPageVersion(pagesFolder, name, latestVersion);
+        const versionHtml = await loadPageVersion(config, name, latestVersion);
         if (versionHtml) return versionHtml;
     }
 
@@ -189,12 +199,12 @@ export async function loadPageState(pagesFolder: string, name: string): Promise<
     const directFolderPath = path.join(pagesFolder, name, 'page.html');
     const flatPath = path.join(pagesFolder, `${name}.html`);
 
-    if (await checkIfExists(folderPath)) {
-        return loadFile(folderPath);
-    } else if (await checkIfExists(directFolderPath)) {
-        return loadFile(directFolderPath);
-    } else if (await checkIfExists(flatPath)) {
-        return loadFile(flatPath);
+    if (await sp.checkIfExists(folderPath)) {
+        return sp.loadFile(folderPath);
+    } else if (await sp.checkIfExists(directFolderPath)) {
+        return sp.loadFile(directFolderPath);
+    } else if (await sp.checkIfExists(flatPath)) {
+        return sp.loadFile(flatPath);
     }
     return undefined;
 }
@@ -203,14 +213,15 @@ export function normalizePageName(name: string|undefined): string|undefined {
     return typeof name == 'string' && name.length > 0 ? name.replace(/[^a-z0-9\-_\[\]\(\)\{\}@#\$%&]/gi, '_').toLowerCase() : undefined;
 }
 
-export async function savePageState(pagesFolder: string, name: string, content: string, title?: string, categories?: string[]): Promise<void> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    await ensureFolderExists(pageFolder);
-    await saveFile(path.join(pageFolder, 'page.html'), content);
+export async function savePageState(config: SynthOSConfig, name: string, content: string, title?: string, categories?: string[]): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, 'page.html'), content);
 
     // Create page.json with full metadata if it doesn't exist
     const metadataPath = path.join(pageFolder, 'page.json');
-    if (!(await checkIfExists(metadataPath))) {
+    if (!(await sp.checkIfExists(metadataPath))) {
         const now = new Date().toISOString();
         const metadata: PageMetadata = {
             title: title ?? '',
@@ -222,21 +233,24 @@ export async function savePageState(pagesFolder: string, name: string, content:
             pageVersion: PAGE_VERSION,
             mode: 'unlocked',
         };
-        await saveFile(metadataPath, JSON.stringify(metadata, null, 4));
+        await sp.saveFile(metadataPath, JSON.stringify(metadata, null, 4));
     }
 }
 
-export async function deletePage(pagesFolder: string, name: string): Promise<void> {
+export async function deletePage(config: SynthOSConfig, name: string): Promise<void> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
+
     // Delete folder-based page: <pagesFolder>/pages/<name>/
     const folderPath = path.join(pagesFolder, 'pages', name);
-    if (await checkIfExists(folderPath)) {
-        await deleteFolder(folderPath);
+    if (await sp.checkIfExists(folderPath)) {
+        await sp.deleteFolder(folderPath);
     }
 
     // Delete legacy flat file: <pagesFolder>/<name>.html
     const flatPath = path.join(pagesFolder, `${name}.html`);
-    if (await checkIfExists(flatPath)) {
-        await deleteFile(flatPath);
+    if (await sp.checkIfExists(flatPath)) {
+        await sp.deleteFile(flatPath);
     }
 
 }
@@ -248,28 +262,31 @@ export async function deletePage(pagesFolder: string, name: string): Promise<voi
 /**
  * Save a version snapshot: <pagesFolder>/pages/<name>/page.v<version>.html
  */
-export async function savePageVersion(pagesFolder: string, name: string, version: number, html: string): Promise<void> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    await ensureFolderExists(pageFolder);
-    await saveFile(path.join(pageFolder, `page.v${version}.html`), html);
+export async function savePageVersion(config: SynthOSConfig, name: string, version: number, html: string): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    await sp.ensureFolderExists(pageFolder);
+    await sp.saveFile(path.join(pageFolder, `page.v${version}.html`), html);
 }
 
 /**
  * Load a version snapshot (returns undefined if the file doesn't exist).
  */
-export async function loadPageVersion(pagesFolder: string, name: string, version: number): Promise<string | undefined> {
-    const filePath = path.join(pagesFolder, 'pages', name, `page.v${version}.html`);
-    if (!await checkIfExists(filePath)) return undefined;
-    return loadFile(filePath);
+export async function loadPageVersion(config: SynthOSConfig, name: string, version: number): Promise<string | undefined> {
+    const sp = config.storageProvider;
+    const filePath = path.join(config.pagesFolder, 'pages', name, `page.v${version}.html`);
+    if (!await sp.checkIfExists(filePath)) return undefined;
+    return sp.loadFile(filePath);
 }
 
 /**
  * Scan page.v*.html files and return the highest version number (0 if none).
  */
-export async function getLatestVersion(pagesFolder: string, name: string): Promise<number> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    if (!await checkIfExists(pageFolder)) return 0;
-    const files = await listFiles(pageFolder);
+export async function getLatestVersion(config: SynthOSConfig, name: string): Promise<number> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    if (!await sp.checkIfExists(pageFolder)) return 0;
+    const files = await sp.listFiles(pageFolder);
     let max = 0;
     for (const file of files) {
         const match = file.match(/^page\.v(\d+)\.html$/);
@@ -284,13 +301,14 @@ export async function getLatestVersion(pagesFolder: string, name: string): Promi
 /**
  * Delete all page.v*.html version files for a page.
  */
-export async function clearVersions(pagesFolder: string, name: string): Promise<void> {
-    const pageFolder = path.join(pagesFolder, 'pages', name);
-    if (!await checkIfExists(pageFolder)) return;
-    const files = await listFiles(pageFolder);
+export async function clearVersions(config: SynthOSConfig, name: string): Promise<void> {
+    const sp = config.storageProvider;
+    const pageFolder = path.join(config.pagesFolder, 'pages', name);
+    if (!await sp.checkIfExists(pageFolder)) return;
+    const files = await sp.listFiles(pageFolder);
     for (const file of files) {
         if (/^page\.v\d+\.html$/.test(file)) {
-            await deleteFile(path.join(pageFolder, file));
+            await sp.deleteFile(path.join(pageFolder, file));
         }
     }
 }
@@ -301,7 +319,7 @@ export interface CopyPageOptions {
 }
 
 export async function copyPage(
-    pagesFolder: string,
+    config: SynthOSConfig,
     sourceName: string,
     targetName: string,
     title: string,
@@ -309,13 +327,15 @@ export async function copyPage(
     requiredPagesFolders: string[],
     options?: CopyPageOptions
 ): Promise<void> {
+    const pagesFolder = config.pagesFolder;
+    const sp = config.storageProvider;
     const copyTables = options?.copyTables ?? false;
-    const copyFiles = options?.copyFiles ?? true;
+    const cpFiles = options?.copyFiles ?? true;
 
     // Resolve source page folder: user pages first, then required pages
     let sourceFolder: string | undefined;
     const userSourceFolder = path.join(pagesFolder, 'pages', sourceName);
-    if (await checkIfExists(path.join(userSourceFolder, 'page.html'))) {
+    if (await sp.checkIfExists(path.join(userSourceFolder, 'page.html'))) {
         sourceFolder = userSourceFolder;
     } else {
         for (const folder of requiredPagesFolders) {
@@ -330,12 +350,17 @@ export async function copyPage(
     // Load source HTML
     let html: string | undefined;
     if (sourceFolder) {
-        html = await loadFile(path.join(sourceFolder, 'page.html'));
+        // Source could be user storage or package — try user first, fall back to local fs
+        if (sourceFolder === userSourceFolder) {
+            html = await sp.loadFile(path.join(sourceFolder, 'page.html'));
+        } else {
+            html = await loadFile(path.join(sourceFolder, 'page.html'));
+        }
     } else {
         // Try legacy flat file
         const flatPath = path.join(pagesFolder, `${sourceName}.html`);
-        if (await checkIfExists(flatPath)) {
-            html = await loadFile(flatPath);
+        if (await sp.checkIfExists(flatPath)) {
+            html = await sp.loadFile(flatPath);
         }
     }
 
@@ -344,7 +369,7 @@ export async function copyPage(
     }
 
     // Save HTML to target (creates folder + page.html + page.json)
-    await savePageState(pagesFolder, targetName, html, title);
+    await savePageState(config, targetName, html, title);
 
     // Overwrite the generated metadata with provided title + categories
     const now = new Date().toISOString();
@@ -358,27 +383,33 @@ export async function copyPage(
         pageVersion: PAGE_VERSION,
         mode: 'unlocked',
     };
-    await savePageMetadata(pagesFolder, targetName, metadata);
+    await savePageMetadata(config, targetName, metadata);
 
     // Copy additional content from source if a folder was resolved
     if (sourceFolder) {
         const targetFolder = path.join(pagesFolder, 'pages', targetName);
 
         if (copyTables) {
-            const entries = await listFolders(sourceFolder);
+            // Source could be user or package folder — use appropriate listing
+            const entries = sourceFolder === userSourceFolder
+                ? await sp.listFolders(sourceFolder)
+                : await listFolders(sourceFolder);
             for (const entry of entries) {
                 if (entry === 'files') continue; // handled separately
-                await copyFolderRecursive(
+                await sp.copyFolderRecursive(
                     path.join(sourceFolder, entry),
                     path.join(targetFolder, entry)
                 );
             }
         }
 
-        if (copyFiles) {
+        if (cpFiles) {
             const filesDir = path.join(sourceFolder, 'files');
-            if (await checkIfExists(filesDir)) {
-                await copyFolderRecursive(filesDir, path.join(targetFolder, 'files'));
+            const filesDirExists = sourceFolder === userSourceFolder
+                ? await sp.checkIfExists(filesDir)
+                : await checkIfExists(filesDir);
+            if (filesDirExists) {
+                await sp.copyFolderRecursive(filesDir, path.join(targetFolder, 'files'));
             }
         }
     }

package/src/service/createCompletePrompt.ts

@@ -1,10 +1,11 @@
 import { anthropic, completePrompt, fireworksai, logCompletePrompt, openai } from '../models';
 import { getModelEntry, loadSettings } from '../settings';
 import { PROVIDERS } from '../models';
+import { SynthOSConfig } from '../init';
 
-export async function createCompletePrompt(pagesFolder: string, use: 'builder' | 'chat', modelOverride?: string): Promise<completePrompt> {
+export async function createCompletePrompt(config: SynthOSConfig, use: 'builder' | 'chat', modelOverride?: string): Promise<completePrompt> {
     // Get configuration settings
-    const settings = await loadSettings(pagesFolder);
+    const settings = await loadSettings(config);
     const entry = getModelEntry(settings, use);
 
     if (!entry.configuration.apiKey) {

package/src/service/requiresSettings.ts

@@ -1,17 +1,18 @@
 import { hasConfiguredSettings, loadSettings, SettingsV2 } from "../settings";
+import { SynthOSConfig } from "../init";
 
 
-export async function requiresSettings(res: any, folder: string, cb: (settings: SettingsV2) => Promise<void>) {
+export async function requiresSettings(res: any, config: SynthOSConfig, cb: (settings: SettingsV2) => Promise<void>) {
     try {
         // Ensure settings configured
-        const isConfigured = await hasConfiguredSettings(folder);
+        const isConfigured = await hasConfiguredSettings(config);
         if (!isConfigured) {
             res.status(400).send('Settings not configured');
             return;
         }
 
         // Load settings
-        const settings = await loadSettings(folder);
+        const settings = await loadSettings(config);
 
         // Call the callback
         await cb(settings);