@despia/local 1.0.0

package/generate-offline-manifest.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone script to generate despia/local.json manifest
+ * Can be used with any build system by running after build completes
+ * 
+ * Usage:
+ *   node generate-offline-manifest.js [outputDir] [entryHtml]
+ * 
+ * Examples:
+ *   node generate-offline-manifest.js
+ *   node generate-offline-manifest.js dist
+ *   node generate-offline-manifest.js dist index.html
+ */
+
+import { generateManifest } from './src/core.js';
+import { resolve } from 'path';
+
+// Get command line arguments
+const outputDir = process.argv[2] || 'dist';
+const entryHtml = process.argv[3] || 'index.html';
+
+try {
+  console.log(`Scanning ${resolve(process.cwd(), outputDir)} for assets...`);
+  const paths = generateManifest({ outputDir, entryHtml });
+  
+  console.log(`✓ Generated despia/local.json`);
+  console.log(`✓ Included ${paths.length} assets`);
+  console.log(`✓ Entry HTML: /${entryHtml}`);
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('Please run this script after your build completes.');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@despia/local",
+  "version": "1.0.0",
+  "description": "Universal build plugin to generate despia/local.json manifest for offline caching in Despia web-native apps. Supports Vite, Webpack, Rollup, Next.js, Nuxt, SvelteKit, Astro, Remix, esbuild, Parcel, and more.",
+  "type": "module",
+  "main": "./src/core.js",
+  "bin": {
+    "despia-local": "generate-offline-manifest.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/core.js"
+    },
+    "./vite": {
+      "import": "./src/vite.js"
+    },
+    "./webpack": {
+      "import": "./src/webpack.js"
+    },
+    "./rollup": {
+      "import": "./src/rollup.js"
+    },
+    "./next": {
+      "import": "./src/next.js"
+    },
+    "./nuxt": {
+      "import": "./src/nuxt.js"
+    },
+    "./sveltekit": {
+      "import": "./src/sveltekit.js"
+    },
+    "./astro": {
+      "import": "./src/astro.js"
+    },
+    "./remix": {
+      "import": "./src/remix.js"
+    },
+    "./esbuild": {
+      "import": "./src/esbuild.js"
+    },
+    "./parcel": {
+      "import": "./src/parcel.js"
+    },
+    "./turbopack": {
+      "import": "./src/turbopack.js"
+    },
+    "./cli": {
+      "import": "./generate-offline-manifest.js"
+    }
+  },
+  "files": [
+    "src",
+    "generate-offline-manifest.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "generate-offline": "node generate-offline-manifest.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "despia",
+    "local",
+    "manifest",
+    "build",
+    "plugin",
+    "vite",
+    "webpack",
+    "rollup",
+    "nextjs",
+    "nuxt",
+    "sveltekit",
+    "astro",
+    "remix",
+    "esbuild",
+    "parcel",
+    "turbopack",
+    "bundler",
+    "pwa",
+    "caching"
+  ],
+  "author": "Despia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/despia-native/local.git"
+  },
+  "bugs": {
+    "url": "https://github.com/despia-native/local/issues"
+  },
+  "homepage": "https://github.com/despia-native/local#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/astro.js

@@ -0,0 +1,51 @@
+/**
+ * Astro integration for generating despia/local.json manifest
+ * 
+ * Usage in astro.config.mjs:
+ *   import { defineConfig } from 'astro/config';
+ *   import despiaOffline from '@despia/local/astro';
+ *   
+ *   export default defineConfig({
+ *     integrations: [
+ *       despiaOffline({ entryHtml: 'index.html' })
+ *     ]
+ *   });
+ */
+
+import { generateManifest } from './core.js';
+import { fileURLToPath } from 'url';
+
+export default function despiaOfflineIntegration(options = {}) {
+  const { entryHtml = 'index.html', outDir = 'dist' } = options;
+
+  return {
+    name: 'despia-offline',
+    hooks: {
+      'astro:build:done': async ({ dir }) => {
+        // Astro provides dir as a URL object, convert to path
+        let outputDir = outDir;
+        if (dir) {
+          // Handle both URL and string paths
+          if (typeof dir === 'string') {
+            outputDir = dir;
+          } else if (dir.pathname) {
+            outputDir = dir.pathname;
+          } else if (dir.href) {
+            // Convert file:// URL to path
+            outputDir = fileURLToPath(dir);
+          }
+        }
+        
+        try {
+          const paths = generateManifest({
+            outputDir,
+            entryHtml
+          });
+          console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+        } catch (error) {
+          console.error('Error generating despia/local.json:', error.message);
+        }
+      }
+    }
+  };
+}

package/src/core.js

@@ -0,0 +1,94 @@
+/**
+ * Core utility functions for generating despia/local.json manifest
+ * Shared across all build tool plugins
+ */
+
+import { readdirSync, statSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, relative, resolve } from 'path';
+
+/**
+ * Recursively collect all files in a directory
+ * @param {string} dir - Directory to scan
+ * @param {string} baseDir - Base directory for relative paths
+ * @returns {string[]} Array of root-relative paths
+ */
+export function collectFiles(dir, baseDir = dir) {
+  const files = [];
+  
+  try {
+    const entries = readdirSync(dir);
+    
+    for (const entry of entries) {
+      // Skip the despia directory itself to avoid recursion
+      if (entry === 'despia') {
+        continue;
+      }
+      
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        // Recursively scan subdirectories
+        files.push(...collectFiles(fullPath, baseDir));
+      } else if (stat.isFile()) {
+        // Get relative path from base directory
+        const relativePath = relative(baseDir, fullPath);
+        // Convert to root-relative path (starting with /)
+        const rootRelativePath = '/' + relativePath.replace(/\\/g, '/');
+        files.push(rootRelativePath);
+      }
+    }
+  } catch (error) {
+    // Silently skip directories that can't be read
+  }
+  
+  return files;
+}
+
+/**
+ * Generate the offline manifest file
+ * @param {Object} options
+ * @param {string} options.outputDir - Output directory path
+ * @param {string} options.entryHtml - Entry HTML filename (default: 'index.html')
+ * @param {string[]} options.additionalPaths - Additional paths to include
+ * @returns {string[]} Array of all asset paths
+ */
+export function generateManifest({ outputDir, entryHtml = 'index.html', additionalPaths = [] }) {
+  const outputPath = resolve(process.cwd(), outputDir);
+  const manifestPath = join(outputPath, 'despia', 'local.json');
+  
+  // Check if output directory exists
+  if (!existsSync(outputPath)) {
+    throw new Error(`Output directory "${outputPath}" does not exist.`);
+  }
+  
+  // Collect all files from the output directory
+  const assetPaths = new Set(collectFiles(outputPath, outputPath));
+  
+  // Add any additional paths provided
+  additionalPaths.forEach(path => {
+    const normalizedPath = path.startsWith('/') ? path : '/' + path.replace(/\\/g, '/');
+    assetPaths.add(normalizedPath);
+  });
+  
+  // Ensure entry HTML is included
+  const entryPath = entryHtml.startsWith('/') 
+    ? entryHtml 
+    : '/' + entryHtml;
+  assetPaths.add(entryPath);
+  
+  // Convert to sorted array
+  const sortedPaths = Array.from(assetPaths).sort();
+  
+  // Create despia directory if it doesn't exist
+  const despiaDir = join(outputPath, 'despia');
+  if (!existsSync(despiaDir)) {
+    mkdirSync(despiaDir, { recursive: true });
+  }
+  
+  // Write formatted JSON array
+  const jsonContent = JSON.stringify(sortedPaths, null, 2);
+  writeFileSync(manifestPath, jsonContent, 'utf-8');
+  
+  return sortedPaths;
+}

package/src/esbuild.js

@@ -0,0 +1,63 @@
+/**
+ * esbuild plugin for generating despia/local.json manifest
+ * 
+ * Usage:
+ *   import { build } from 'esbuild';
+ *   import { despiaOfflineEsbuild } from '@despia/local/esbuild';
+ *   
+ *   await build({
+ *     plugins: [despiaOfflineEsbuild({ outDir: 'dist' })]
+ *   });
+ */
+
+import { generateManifest } from './core.js';
+import { relative } from 'path';
+
+export function despiaOfflineEsbuild(options = {}) {
+  const { outDir = 'dist', entryHtml = 'index.html' } = options;
+
+  return {
+    name: 'despia-offline',
+    setup(build) {
+      build.onEnd(async (result) => {
+        if (result.errors.length > 0) {
+          return; // Don't generate manifest if build failed
+        }
+
+        const additionalPaths = [];
+        const actualOutDir = build.initialOptions.outdir || outDir;
+        const outDirPath = typeof actualOutDir === 'string' ? actualOutDir : outDir;
+        
+        // Collect output files from esbuild result
+        if (result.outputFiles) {
+          for (const file of result.outputFiles) {
+            const filePath = file.path;
+            // Get relative path from output directory
+            try {
+              const relativePath = relative(outDirPath, filePath);
+              const rootRelativePath = '/' + relativePath.replace(/\\/g, '/');
+              additionalPaths.push(rootRelativePath);
+            } catch (e) {
+              // If relative path calculation fails, use filename
+              const filename = filePath.split(/[/\\]/).pop();
+              if (filename) {
+                additionalPaths.push('/' + filename);
+              }
+            }
+          }
+        }
+
+        try {
+          const paths = generateManifest({
+            outputDir: outDirPath,
+            entryHtml,
+            additionalPaths
+          });
+          console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+        } catch (error) {
+          console.error('Error generating despia/local.json:', error.message);
+        }
+      });
+    }
+  };
+}

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * Main entry point for @despia/local
+ * Re-exports core functionality and all plugins
+ */
+
+export { generateManifest, collectFiles } from './core.js';
+export { despiaOfflinePlugin } from './vite.js';
+export { default as DespiaOfflinePlugin } from './webpack.js';
+export { despiaOffline } from './rollup.js';
+export { withDespiaOffline } from './next.js';
+export { default as DespiaOfflineModule } from './nuxt.js';
+export { despiaOfflineSvelteKit } from './sveltekit.js';
+export { default as despiaOfflineIntegration } from './astro.js';
+export { despiaOfflineRemix } from './remix.js';
+export { despiaOfflineEsbuild } from './esbuild.js';
+export { default as DespiaOfflineParcel } from './parcel.js';

package/src/next.js

@@ -0,0 +1,59 @@
+/**
+ * Next.js integration for generating despia/local.json manifest
+ * 
+ * Usage in next.config.js:
+ *   const withDespiaOffline = require('@despia/local/next');
+ *   module.exports = withDespiaOffline({
+ *     entryHtml: 'index.html',
+ *     outDir: '.next' // or 'out' for static export
+ *   })({
+ *     // your next config
+ *   });
+ * 
+ * Or use the webpack plugin approach:
+ *   const DespiaOfflinePlugin = require('@despia/local/webpack');
+ *   module.exports = {
+ *     webpack: (config) => {
+ *       config.plugins.push(new DespiaOfflinePlugin({ outDir: '.next' }));
+ *       return config;
+ *     }
+ *   };
+ */
+
+import { generateManifest } from './core.js';
+import DespiaOfflinePlugin from './webpack.js';
+
+export function withDespiaOffline(pluginOptions = {}) {
+  const offlineConfig = {
+    outDir: pluginOptions.outDir || '.next',
+    entryHtml: pluginOptions.entryHtml || 'index.html',
+    ...pluginOptions
+  };
+
+  return (nextConfig = {}) => {
+    const existingWebpack = nextConfig.webpack;
+
+    return {
+      ...nextConfig,
+      webpack: (config, options) => {
+        // Add Despia Offline plugin
+        config.plugins.push(
+          new DespiaOfflinePlugin({
+            outDir: offlineConfig.outDir,
+            entryHtml: offlineConfig.entryHtml
+          })
+        );
+
+        // Call existing webpack config if present
+        if (typeof existingWebpack === 'function') {
+          return existingWebpack(config, options);
+        }
+
+        return config;
+      }
+    };
+  };
+}
+
+// Also export as CommonJS for Next.js compatibility
+export default withDespiaOffline;

package/src/nuxt.js

@@ -0,0 +1,64 @@
+/**
+ * Nuxt module for generating despia/local.json manifest
+ * 
+ * Usage in nuxt.config.js:
+ *   export default {
+ *     modules: ['@despia/local/nuxt'],
+ *     despiaOffline: {
+ *       entryHtml: 'index.html'
+ *     }
+ *   }
+ * 
+ * Or use as a Nuxt module in modules/ directory:
+ *   // modules/despia-offline.js
+ *   import DespiaOfflineModule from '@despia/local/nuxt';
+ *   export default DespiaOfflineModule;
+ */
+
+import { generateManifest } from './core.js';
+
+export default function DespiaOfflineModule(moduleOptions) {
+  const options = {
+    entryHtml: 'index.html',
+    ...moduleOptions,
+    ...(this.options?.despiaOffline || {})
+  };
+
+  // Hook into Nuxt build completion
+  this.nuxt.hook('build:done', async (builder) => {
+    // Determine output directory based on Nuxt mode
+    let outputDir;
+    
+    if (this.options.generate) {
+      // Static site generation
+      outputDir = '.output/public';
+    } else if (this.options.target === 'static') {
+      outputDir = 'dist';
+    } else {
+      // SSR mode - assets are in .nuxt/dist/client
+      outputDir = '.nuxt/dist/client';
+    }
+    
+    // Try to generate manifest
+    const altDirs = [outputDir, '.output/public', 'dist', '.nuxt/dist'];
+    let generated = false;
+    
+    for (const dir of altDirs) {
+      try {
+        const paths = generateManifest({
+          outputDir: dir,
+          entryHtml: options.entryHtml
+        });
+        console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+        generated = true;
+        break;
+      } catch (e) {
+        // Continue to next directory
+      }
+    }
+    
+    if (!generated) {
+      console.warn('⚠ Could not find Nuxt build output directory');
+    }
+  });
+}

package/src/parcel.js

@@ -0,0 +1,50 @@
+/**
+ * Parcel plugin for generating despia/local.json manifest
+ * 
+ * Note: Parcel 2.x uses a different plugin system. For Parcel projects,
+ * we recommend using the standalone CLI script instead:
+ * 
+ *   "scripts": {
+ *     "build": "parcel build",
+ *     "postbuild": "despia-offline dist"
+ *   }
+ * 
+ * For Parcel 1.x, you can use this plugin, but the API may vary.
+ */
+
+import { generateManifest } from './core.js';
+
+// Parcel 2.x plugin format
+export default function(api) {
+  const { outDir = 'dist', entryHtml = 'index.html' } = api.options || {};
+
+  return {
+    name: 'despia-offline',
+    async bundleEnd({ bundleGraph }) {
+      const additionalPaths = [];
+      
+      // Collect all bundles
+      if (bundleGraph && bundleGraph.getBundles) {
+        bundleGraph.getBundles().forEach(bundle => {
+          const filePath = bundle.filePath || bundle.name;
+          if (filePath) {
+            const rootRelativePath = '/' + filePath.replace(/\\/g, '/');
+            additionalPaths.push(rootRelativePath);
+          }
+        });
+      }
+
+      try {
+        const paths = generateManifest({
+          outputDir: api.options?.outDir || outDir,
+          entryHtml,
+          additionalPaths
+        });
+        console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+      } catch (error) {
+        console.error('Error generating despia/local.json:', error.message);
+        console.warn('💡 Tip: For Parcel projects, use the standalone CLI: "despia-offline dist"');
+      }
+    }
+  };
+}

package/src/remix.js

@@ -0,0 +1,45 @@
+/**
+ * Remix integration for generating despia/local.json manifest
+ * 
+ * Usage in remix.config.js or vite.config.js:
+ *   import { remix } from '@remix-run/dev';
+ *   import { despiaOfflineRemix } from '@despia/local/remix';
+ *   
+ *   export default {
+ *     plugins: [
+ *       remix(),
+ *       despiaOfflineRemix({ entryHtml: 'index.html' })
+ *     ]
+ *   }
+ */
+
+import { generateManifest } from './core.js';
+
+export function despiaOfflineRemix(options = {}) {
+  const { entryHtml = 'index.html', outDir = 'build/client' } = options;
+
+  return {
+    name: 'despia-offline-remix',
+    apply: 'build',
+    buildEnd() {
+      // Remix outputs to build/client for client assets
+      const outputDirs = ['build/client', 'build', 'public/build'];
+      
+      for (const outputDir of outputDirs) {
+        try {
+          const paths = generateManifest({
+            outputDir,
+            entryHtml
+          });
+          console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+          return; // Success, exit
+        } catch (error) {
+          // Try next directory
+          continue;
+        }
+      }
+      
+      console.warn('⚠ Could not find Remix build output directory');
+    }
+  };
+}

package/src/rollup.js

@@ -0,0 +1,45 @@
+/**
+ * Rollup plugin for generating despia/local.json manifest
+ */
+
+import { generateManifest } from './core.js';
+
+/**
+ * Rollup plugin to generate despia/local.json manifest
+ * @param {Object} options
+ * @param {string} options.outDir - Output directory (default: 'dist')
+ * @param {string} options.entryHtml - Entry HTML file (default: 'index.html')
+ */
+export function despiaOffline(options = {}) {
+  const { outDir = 'dist', entryHtml = 'index.html' } = options;
+
+  return {
+    name: 'despia-offline',
+    writeBundle(outputOptions, bundle) {
+      const outputDir = outputOptions.dir || outDir;
+      const additionalPaths = [];
+      
+      // Collect paths from bundle
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type === 'asset' || chunk.type === 'chunk') {
+          const filePath = chunk.fileName || fileName;
+          const rootRelativePath = filePath.startsWith('/') 
+            ? filePath 
+            : '/' + filePath.replace(/\\/g, '/');
+          additionalPaths.push(rootRelativePath);
+        }
+      }
+      
+      try {
+        const paths = generateManifest({ 
+          outputDir, 
+          entryHtml,
+          additionalPaths 
+        });
+        console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+      } catch (error) {
+        console.error('Error generating despia/local.json:', error.message);
+      }
+    }
+  };
+}

package/src/sveltekit.js

@@ -0,0 +1,45 @@
+/**
+ * SvelteKit adapter for generating despia/local.json manifest
+ * 
+ * Usage in vite.config.js:
+ *   import { sveltekit } from '@sveltejs/kit/vite';
+ *   import { despiaOfflineSvelteKit } from '@despia/local/sveltekit';
+ *   
+ *   export default {
+ *     plugins: [
+ *       sveltekit(),
+ *       despiaOfflineSvelteKit({ entryHtml: 'index.html' })
+ *     ]
+ *   }
+ */
+
+import { generateManifest } from './core.js';
+
+export function despiaOfflineSvelteKit(options = {}) {
+  const { entryHtml = 'index.html' } = options;
+
+  return {
+    name: 'despia-offline-sveltekit',
+    apply: 'build',
+    buildEnd() {
+      // SvelteKit outputs to build directory
+      const outputDirs = ['build', '.svelte-kit', 'dist'];
+      
+      for (const outputDir of outputDirs) {
+        try {
+          const paths = generateManifest({
+            outputDir,
+            entryHtml
+          });
+          console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+          return; // Success, exit
+        } catch (error) {
+          // Try next directory
+          continue;
+        }
+      }
+      
+      console.warn('⚠ Could not find SvelteKit build output directory');
+    }
+  };
+}

package/src/turbopack.js

@@ -0,0 +1,20 @@
+/**
+ * Turbopack plugin for generating despia/local.json manifest
+ * Note: Turbopack is Next.js's new bundler. Use the Next.js integration instead.
+ * This is a placeholder for future Turbopack-specific optimizations.
+ */
+
+import { generateManifest } from './core.js';
+
+export function despiaOfflineTurbopack(options = {}) {
+  const { entryHtml = 'index.html', outDir = '.next' } = options;
+
+  // Turbopack is used by Next.js, so we recommend using the Next.js integration
+  // This is kept for potential future Turbopack-specific features
+  console.warn('⚠ Turbopack: Use @despia/local/next instead for Next.js projects');
+  
+  return {
+    name: 'despia-offline-turbopack',
+    // Implementation would go here when Turbopack plugin API is stable
+  };
+}