launchpd 1.0.0 → 1.0.1

package/README.md

@@ -1,96 +1,99 @@
 # Launchpd
 
-Deploy static sites instantly to a live URL. No config, no complexity.
+**Deploy static sites instantly to a live URL. No config, no complexity.**
 
-## Quick Start
-
-```bash
-npm install -g launchpd
-launchpd deploy ./my-site
-```
+[![npm version](https://img.shields.io/npm/v/launchpd.svg)](https://www.npmjs.com/package/launchpd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/kents00/launchpd.svg?style=social)](https://github.com/kents00/launchpd)
 
-## Installation
-
-```bash
-npm install -g launchpd
-```
+---
 
-Requires Node.js 20 or higher.
+## Features
 
-## Usage
+*   **Blazing Fast**: Deploy folders in seconds with a single command.
+*   **Project-Based**: Link local folders to subdomains once and deploy without re-typing names.
+*   **Zero Config**: No complex setup; optionally use `.launchpd.json` for project persistence.
+*   **Version Control**: Every deployment is versioned with messages. Roll back instantly.
+*   **Static-Only Security**: Strict validation ensures only high-performance static assets are deployed.
+*   **Secure**: Private uploads with API key authentication or safe anonymous testing.
+*   **Auto-Expiration**: Set temporary deployments that delete themselves automatically.
 
-### Deploy a folder
-
-```bash
-launchpd deploy ./my-folder
-```
-
-### Use a custom subdomain
+## Quick Start
 
 ```bash
-launchpd deploy ./my-folder --name my-project
-```
-
-### Set expiration time
+# Install globally
+npm install -g launchpd
 
-```bash
-launchpd deploy ./my-folder --expires 2h
-# Auto-deletes after 2 hours
+# Deploy your current folder
+launchpd deploy .
 ```
 
+---
 
-
-### List your deployments
-
-```bash
-launchpd list
-```
-
-### View version history
+## Installation
 
 ```bash
-launchpd versions my-subdomain
+npm install -g launchpd
 ```
+*Requires **Node.js 20** or higher.*
 
-### Rollback to previous version
+---
 
-```bash
-launchpd rollback my-subdomain
-launchpd rollback my-subdomain --to 2
-```
+## Command Reference
 
-## Authentication
+### Deployment
+| Command | Description |
+| :--- | :--- |
+| `launchpd init` | Link current folder to a subdomain (persisted in `.launchpd.json`) |
+| `launchpd deploy <folder>` | Deploy a local folder (uses linked subdomain if available) |
+| `launchpd deploy . -m "Fix layout"` | Deploy with a message (like a git commit) |
+| `launchpd deploy . --name site` | Deploy with a custom subdomain explicitly |
+| `launchpd deploy . --expires 2h` | Set auto-deletion (e.g., `30m`, `1d`, `7d`) |
 
-### Register for a free account
+### Management
+| Command | Description |
+| :--- | :--- |
+| `launchpd status` | Show linked subdomain and latest deployment info |
+| `launchpd list` | View your active deployments |
+| `launchpd versions <subdomain>` | See version history with messages |
+| `launchpd rollback <subdomain>` | Rollback to the previous version |
+| `launchpd rollback <id> --to <v>` | Rollback to a specific version number |
 
-```bash
-launchpd register
-```
+### Identity & Auth
+| Command | Description |
+| :--- | :--- |
+| `launchpd register` | Open the dashboard to create an account |
+| `launchpd login` | Authenticate with your API key |
+| `launchpd whoami` | Show current account status |
+| `launchpd quota` | View storage and site limits |
+| `launchpd logout` | Remove stored credentials |
 
-### Login with your API key
+---
 
-```bash
-launchpd login
-```
+## Why Register?
 
-### Check current user and quota
+While anonymous deployments are great for testing, registered users get more power:
 
-```bash
-launchpd whoami
-launchpd quota
-```
+| Feature | Anonymous | Registered (Free) |
+| :--- | :--- | :--- |
+| **Max Sites** | 3 | 10+ |
+| **Storage** | 50MB | 100MB+ |
+| **Custom Names** | No | **Yes** |
+| **Retention** | 7 Days | **Permanent** |
+| **Versions** | 1 per site | 10 per site |
 
-### Logout
+Run `launchpd register` to unlock these benefits!
 
-```bash
-launchpd logout
-```
+---
 
 ## Support
 
-- [Report issues](https://github.com/kents00/launchpd/issues)
-- [Documentation](https://launchpd.cloud/docs)
+*   **Bugs & Feedback**: [GitHub Issues](https://github.com/kents00/launchpd/issues)
+*   **Website**: [launchpd.cloud](https://launchpd.cloud)
+*   **Docs**: [launchpd.cloud/docs](https://launchpd.cloud/docs)
+
+---
 
 ## License
 
-MIT
+[MIT](LICENSE) © [Kent Edoloverio](https://github.com/kents00)

package/bin/cli.js

@@ -1,11 +1,7 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { deploy } from '../src/commands/deploy.js';
-import { list } from '../src/commands/list.js';
-import { rollback } from '../src/commands/rollback.js';
-import { versions } from '../src/commands/versions.js';
-import { login, logout, register, whoami, quota } from '../src/commands/auth.js';
+import { deploy, list, rollback, versions, init, status, login, logout, register, whoami, quota } from '../src/commands/index.js';
 
 const program = new Command();
 
@@ -19,6 +15,7 @@ program
     .description('Deploy a folder to a live URL')
     .argument('<folder>', 'Path to the folder to deploy')
     .option('--name <subdomain>', 'Use a custom subdomain (optional)')
+    .option('-m, --message <text>', 'Deployment message (optional)')
     .option('--expires <time>', 'Auto-delete after time (e.g., 30m, 2h, 1d). Minimum: 30m')
     .option('--verbose', 'Show detailed error information')
     .action(async (folder, options) => {
@@ -55,6 +52,21 @@ program
         await rollback(subdomain, options);
     });
 
+program
+    .command('init')
+    .description('Initialize a new project in the current directory')
+    .option('--name <subdomain>', 'Subdomain to link to')
+    .action(async (options) => {
+        await init(options);
+    });
+
+program
+    .command('status')
+    .description('Show current project status')
+    .action(async () => {
+        await status();
+    });
+
 // Authentication commands
 program
     .command('login')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "launchpd",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Deploy static sites instantly to a live URL",
     "keywords": [
         "static",
@@ -51,15 +51,16 @@
     "dependencies": {
         "chalk": "^5.4.0",
         "commander": "^14.0.0",
+        "launchpd": "^1.0.0",
         "mime-types": "^2.1.35",
         "nanoid": "^5.1.0",
         "ora": "^8.0.1"
     },
     "devDependencies": {
         "@eslint/js": "^9.39.2",
-        "@vitest/coverage-v8": "^2.1.0",
+        "@vitest/coverage-v8": "^4.0.17",
         "eslint": "^9.0.0",
-        "vitest": "^2.1.0"
+        "vitest": "^4.0.17"
     },
     "engines": {
         "node": ">=20.0.0"

package/src/commands/deploy.js

@@ -1,15 +1,18 @@
 import { existsSync, statSync } from 'node:fs';
+import chalk from 'chalk';
 import { readdir } from 'node:fs/promises';
 import { resolve, basename, join } from 'node:path';
 import { generateSubdomain } from '../utils/id.js';
 import { uploadFolder, finalizeUpload } from '../utils/upload.js';
 import { getNextVersion } from '../utils/metadata.js';
 import { saveLocalDeployment } from '../utils/localConfig.js';
-import { getNextVersionFromAPI } from '../utils/api.js';
+import { getNextVersionFromAPI, checkSubdomainAvailable, listSubdomains } from '../utils/api.js';
+import { getProjectConfig, findProjectRoot } from '../utils/projectConfig.js';
 import { success, errorWithSuggestions, info, warning, spinner, formatSize } from '../utils/logger.js';
 import { calculateExpiresAt, formatTimeRemaining } from '../utils/expiration.js';
 import { checkQuota, displayQuotaWarnings } from '../utils/quota.js';
 import { getCredentials } from '../utils/credentials.js';
+import { validateStaticOnly } from '../utils/validator.js';
 
 /**
  * Calculate total size of a folder
@@ -87,6 +90,22 @@ export async function deploy(folder, options) {
     }
     scanSpinner.succeed(`Found ${fileCount} file(s)`);
 
+    // Static-Only Validation
+    const validationSpinner = spinner('Validating files...');
+    const validation = await validateStaticOnly(folderPath);
+    if (!validation.success) {
+        validationSpinner.fail('Deployment blocked: Non-static files detected');
+        errorWithSuggestions('Your project contains files that are not allowed.', [
+            'Launchpd only supports static files (HTML, CSS, JS, images, etc.)',
+            'Remove framework files, backend code, and build metadata:',
+            ...validation.violations.map(v => `   - ${v}`).slice(0, 10),
+            validation.violations.length > 10 ? `   - ...and ${validation.violations.length - 10} more` : '',
+            'If you use a framework (React, Vue, etc.), deploy the "dist" or "build" folder instead.'
+        ], { verbose });
+        process.exit(1);
+    }
+    validationSpinner.succeed('Project validated (Static files only)');
+
     // Generate or use provided subdomain
     // Anonymous users cannot use custom subdomains
     const creds = await getCredentials();
@@ -97,14 +116,28 @@ export async function deploy(folder, options) {
         console.log('');
     }
 
-    const subdomain = (options.name && creds?.email) ? options.name.toLowerCase() : generateSubdomain();
+    // Detect project config if no name provided
+    let subdomain = (options.name && creds?.email) ? options.name.toLowerCase() : null;
+
+    if (!subdomain) {
+        const projectRoot = findProjectRoot(folderPath);
+        const config = await getProjectConfig(projectRoot);
+        if (config?.subdomain) {
+            subdomain = config.subdomain;
+            info(`Using project subdomain: ${chalk.bold(subdomain)}`);
+        }
+    }
+
+    if (!subdomain) {
+        subdomain = generateSubdomain();
+    }
+
     const url = `https://${subdomain}.launchpd.cloud`;
 
-    // Check if custom subdomain is taken
-    if (options.name && creds?.email) {
+    // Check if custom subdomain is taken (only if explicitly provided or new)
+    if (options.name || !subdomain) {
         const checkSpinner = spinner('Checking subdomain availability...');
         try {
-            const { checkSubdomainAvailable, listSubdomains } = await import('../utils/api.js');
             const isAvailable = await checkSubdomainAvailable(subdomain);
 
             if (!isAvailable) {
@@ -183,7 +216,8 @@ export async function deploy(folder, options) {
             fileCount,
             totalBytes,
             folderName,
-            expiresAt?.toISOString() || null
+            expiresAt?.toISOString() || null,
+            options.message || null
         );
         finalizeSpinner.succeed('Deployment finalized');
 

package/src/commands/index.js

@@ -6,4 +6,6 @@ export { deploy } from './deploy.js';
 export { list } from './list.js';
 export { rollback } from './rollback.js';
 export { versions } from './versions.js';
+export { init } from './init.js';
+export { status } from './status.js';
 export { login, logout, register, whoami, quota } from './auth.js';

package/src/commands/init.js

@@ -0,0 +1,71 @@
+import { initProjectConfig, findProjectRoot } from '../utils/projectConfig.js';
+import { checkSubdomainAvailable, reserveSubdomain } from '../utils/api.js';
+import { isLoggedIn } from '../utils/credentials.js';
+import { success, errorWithSuggestions, info, spinner, warning } from '../utils/logger.js';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+/**
+ * Initialize a new project in the current directory
+ * @param {object} options - Command options
+ * @param {string} options.name - Optional subdomain name
+ */
+export async function init(options) {
+    const projectRoot = findProjectRoot();
+    if (projectRoot) {
+        warning('This directory is already part of a Launchpd project.');
+        info(`Project root: ${projectRoot}`);
+        return;
+    }
+
+    if (!await isLoggedIn()) {
+        errorWithSuggestions('You must be logged in to initialize a project.', [
+            'Run "launchpd login" to log in',
+            'Run "launchpd register" to create an account'
+        ]);
+        process.exit(1);
+    }
+
+    const rl = readline.createInterface({ input, output });
+    let subdomain = options.name;
+
+    if (!subdomain) {
+        info('Linking this directory to a Launchpd subdomain...');
+        subdomain = await rl.question('Enter subdomain name (e.g. my-awesome-site): ');
+    }
+
+    if (!subdomain || !/^[a-z0-9-]+$/.test(subdomain)) {
+        rl.close();
+        errorWithSuggestions('Invalid subdomain. Use lowercase alphanumeric and hyphens only.', [
+            'Example: my-site-123',
+            'No spaces or special characters'
+        ]);
+        process.exit(1);
+    }
+
+    const checkSpinner = spinner(`Checking if "${subdomain}" is available...`);
+    try {
+        const isAvailable = await checkSubdomainAvailable(subdomain);
+        if (!isAvailable) {
+            checkSpinner.fail(`Subdomain "${subdomain}" is already taken.`);
+            rl.close();
+            process.exit(1);
+        }
+        checkSpinner.succeed(`Subdomain "${subdomain}" is available!`);
+
+        const reserveStatus = await reserveSubdomain(subdomain);
+        if (reserveStatus) {
+            await initProjectConfig(subdomain);
+            success(`Project initialized! Linked to: ${subdomain}.launchpd.cloud`);
+            info('Now you can run "launchpd deploy" without specifying a name.');
+        }
+    } catch (err) {
+        checkSpinner.fail('Failed to initialize project');
+        errorWithSuggestions(err.message, [
+            'Check your internet connection',
+            'Try a different subdomain name'
+        ]);
+    } finally {
+        rl.close();
+    }
+}

package/src/commands/rollback.js

@@ -28,6 +28,7 @@ export async function rollback(subdomainInput, options) {
                 version: v.version,
                 timestamp: v.created_at,
                 fileCount: v.file_count,
+                message: v.message,
             }));
             currentActive = apiResult.activeVersion || 1;
             useAPI = true;
@@ -67,7 +68,8 @@ export async function rollback(subdomainInput, options) {
                 versions.forEach(v => {
                     const isActive = v.version === currentActive;
                     const marker = isActive ? chalk.green(' (active)') : '';
-                    console.log(`  ${chalk.cyan(`v${v.version}`)} - ${chalk.gray(v.timestamp)}${marker}`);
+                    const message = v.message ? ` - "${v.message}"` : '';
+                    console.log(`  ${chalk.cyan(`v${v.version}`)}${message} - ${chalk.gray(v.timestamp)}${marker}`);
                 });
                 process.exit(1);
             }
@@ -106,6 +108,9 @@ export async function rollback(subdomainInput, options) {
 
         rollbackSpinner.succeed(`Rolled back to ${chalk.cyan(`v${targetVersion}`)}`);
         console.log(`\n  🔄 https://${subdomain}.launchpd.cloud\n`);
+        if (targetDeployment?.message) {
+            info(`Version message: "${chalk.italic(targetDeployment.message)}"`);
+        }
         info(`Restored deployment from: ${chalk.gray(targetDeployment?.timestamp || 'unknown')}`);
 
     } catch (err) {

package/src/commands/status.js

@@ -0,0 +1,55 @@
+import { getProjectConfig, findProjectRoot } from '../utils/projectConfig.js';
+import { getDeployment } from '../utils/api.js';
+import { errorWithSuggestions, info, spinner, warning, formatSize } from '../utils/logger.js';
+import chalk from 'chalk';
+
+/**
+ * Show current project status
+ */
+export async function status(_options) {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+        warning('Not a Launchpd project (no .launchpd.json found)');
+        info('Run "launchpd init" to link this directory to a subdomain.');
+        return;
+    }
+
+    const config = await getProjectConfig(projectRoot);
+    if (!config || !config.subdomain) {
+        errorWithSuggestions('Invalid project configuration.', [
+            'Try deleting .launchpd.json and running "launchpd init" again'
+        ]);
+        return;
+    }
+
+    info(`Project root: ${chalk.cyan(projectRoot)}`);
+    info(`Linked subdomain: ${chalk.bold.green(config.subdomain)}.launchpd.cloud`);
+
+    const statusSpinner = spinner('Fetching latest deployment info...');
+    try {
+        const deploymentData = await getDeployment(config.subdomain);
+        statusSpinner.stop();
+
+        if (deploymentData && deploymentData.versions && deploymentData.versions.length > 0) {
+            const active = deploymentData.versions.find(v => v.version === deploymentData.activeVersion) || deploymentData.versions[0];
+
+            console.log('\nDeployment Status:');
+            console.log(`  Active Version:  ${chalk.cyan(`v${active.version}`)}`);
+            console.log(`  Deployed At:     ${new Date(active.created_at || active.timestamp).toLocaleString()}`);
+            if (active.message) {
+                console.log(`  Message:         ${chalk.italic(active.message)}`);
+            }
+            console.log(`  File Count:      ${active.file_count || active.fileCount}`);
+            console.log(`  Total Size:      ${formatSize(active.total_bytes || active.totalBytes)}`);
+            console.log(`  URL:             ${chalk.underline.blue(`https://${config.subdomain}.launchpd.cloud`)}`);
+            console.log('');
+        } else {
+            warning('\nNo deployments found for this project yet.');
+            info('Run "launchpd deploy <folder>" to push your first version.');
+        }
+    } catch {
+        statusSpinner.fail('Failed to fetch deployment status');
+        info(`Subdomain: ${config.subdomain}`);
+        // Don't exit, just show what we have
+    }
+}

package/src/commands/versions.js

@@ -34,9 +34,10 @@ export async function versions(subdomainInput, options) {
         if (apiResult && apiResult.versions) {
             versionList = apiResult.versions.map(v => ({
                 version: v.version,
-                timestamp: v.created_at,
-                fileCount: v.file_count,
-                totalBytes: v.total_bytes,
+                timestamp: v.created_at || v.timestamp,
+                fileCount: v.file_count || v.fileCount,
+                totalBytes: v.total_bytes || v.totalBytes,
+                message: v.message || '',
             }));
             activeVersion = apiResult.activeVersion || 1;
         } else {
@@ -67,6 +68,7 @@ export async function versions(subdomainInput, options) {
                     fileCount: v.fileCount,
                     totalBytes: v.totalBytes,
                     isActive: v.version === activeVersion,
+                    message: v.message,
                 })),
             }, null, 2));
             return;
@@ -77,8 +79,8 @@ export async function versions(subdomainInput, options) {
         console.log('');
 
         // Table header
-        console.log(chalk.gray('  Version   Date                     Files    Size         Status'));
-        console.log(chalk.gray('  ' + '─'.repeat(70)));
+        console.log(chalk.gray('  Version   Date                     Files    Size         Status       Message'));
+        console.log(chalk.gray('  ' + '─'.repeat(100)));
 
         for (const v of versionList) {
             const isActive = v.version === activeVersion;
@@ -95,13 +97,15 @@ export async function versions(subdomainInput, options) {
             const filesStr = chalk.white(filesRaw.padEnd(10));
             const sizeStr = chalk.white(sizeRaw.padEnd(12));
             const statusStr = isActive
-                ? chalk.green.bold('● active')
-                : chalk.gray('○ inactive');
+                ? chalk.green.bold('● active'.padEnd(12))
+                : chalk.gray('○ inactive'.padEnd(12));
 
-            console.log(`  ${versionStr}${dateStr}${filesStr}${sizeStr}${statusStr}`);
+            const messageStr = chalk.italic.gray(v.message || '');
+
+            console.log(`  ${versionStr}${dateStr}${filesStr}${sizeStr}${statusStr}${messageStr}`);
         }
 
-        console.log(chalk.gray('  ' + '─'.repeat(70)));
+        console.log(chalk.gray('  ' + '─'.repeat(100)));
         console.log('');
         info(`Use ${chalk.cyan(`launchpd rollback ${subdomain} --to <n>`)} to restore a version.`);
         console.log('');

package/src/utils/api.js

@@ -82,7 +82,7 @@ export async function getNextVersionFromAPI(subdomain) {
  * Record a new deployment in the API
  */
 export async function recordDeployment(deploymentData) {
-    const { subdomain, folderName, fileCount, totalBytes, version, expiresAt } = deploymentData;
+    const { subdomain, folderName, fileCount, totalBytes, version, expiresAt, message } = deploymentData;
 
     return apiRequest('/api/deployments', {
         method: 'POST',
@@ -94,6 +94,7 @@ export async function recordDeployment(deploymentData) {
             version,
             cliVersion: '0.1.0',
             expiresAt,
+            message,
         }),
     });
 }

package/src/utils/projectConfig.js

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const PROJECT_CONFIG_FILE = '.launchpd.json';
+
+/**
+ * Find project root by looking for .launchpd.json upwards
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, PROJECT_CONFIG_FILE))) {
+            return current;
+        }
+        const parent = resolve(current, '..');
+        if (parent === current) return null;
+        current = parent;
+    }
+}
+
+/**
+ * Get project configuration
+ */
+export async function getProjectConfig(projectDir = findProjectRoot()) {
+    if (!projectDir) return null;
+
+    const configPath = join(projectDir, PROJECT_CONFIG_FILE);
+    try {
+        if (existsSync(configPath)) {
+            const content = await readFile(configPath, 'utf8');
+            return JSON.parse(content);
+        }
+    } catch {
+        // Silently fail or handle corrupted config
+    }
+    return null;
+}
+
+/**
+ * Save project configuration
+ */
+export async function saveProjectConfig(config, projectDir = process.cwd()) {
+    const configPath = join(projectDir, PROJECT_CONFIG_FILE);
+    await writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
+    return configPath;
+}
+
+/**
+ * Initialize a new project config
+ */
+export async function initProjectConfig(subdomain, projectDir = process.cwd()) {
+    const config = {
+        subdomain,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+    };
+    return await saveProjectConfig(config, projectDir);
+}

package/src/utils/upload.js

@@ -72,7 +72,7 @@ async function uploadFile(content, subdomain, version, filePath, contentType) {
  * @param {string} folderName - Original folder name
  * @param {string|null} expiresAt - ISO expiration timestamp
  */
-async function completeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt) {
+async function completeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt, message) {
     const apiKey = await getApiKey();
     const apiSecret = await getApiSecret();
     const headers = {
@@ -87,6 +87,7 @@ async function completeUpload(subdomain, version, fileCount, totalBytes, folderN
         totalBytes,
         folderName,
         expiresAt,
+        message,
     });
 
     if (apiSecret) {
@@ -176,6 +177,6 @@ export async function uploadFolder(localPath, subdomain, version = 1, onProgress
  * @param {string} folderName - Folder name
  * @param {string|null} expiresAt - Expiration ISO timestamp
  */
-export async function finalizeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt = null) {
-    return completeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt);
+export async function finalizeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt = null, message = null) {
+    return completeUpload(subdomain, version, fileCount, totalBytes, folderName, expiresAt, message);
 }

package/src/utils/validator.js

@@ -0,0 +1,84 @@
+import { readdir } from 'node:fs/promises';
+import { extname } from 'node:path';
+
+// Allowed static file extensions
+const ALLOWED_EXTENSIONS = new Set([
+    '.html', '.htm',
+    '.css', '.scss', '.sass',
+    '.js', '.mjs', '.cjs',
+    '.json', '.jsonld',
+    '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.avif',
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.mp4', '.webm', '.ogg', '.mp3', '.wav', '.flac',
+    '.pdf', '.txt', '.md', '.xml', '.yaml', '.yml'
+]);
+
+// Forbidden indicators (frameworks, build tools, backend code)
+const FORBIDDEN_INDICATORS = [
+    // Build systems & Frameworks
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'node_modules',
+    'composer.json',
+    'vendor',
+    'requirements.txt',
+    'Gemfile',
+    'Makefile',
+    'tsconfig.json',
+    'next.config.js',
+    'nuxt.config.js',
+    'svelte.config.js',
+    'vite.config.js',
+    'webpack.config.js',
+    'rollup.config.js',
+    'angular.json',
+
+    // Backend/Source
+    '.jsx', '.tsx', '.ts', '.vue', '.svelte', '.php', '.py', '.rb', '.go', '.rs', '.java', '.cs', '.cpp', '.c',
+    '.env', '.env.local', '.env.production',
+    '.dockerfile', 'docker-compose.yml',
+
+    // Hidden/System
+    '.git', '.svn', '.hg'
+];
+
+/**
+ * Validates that a folder contains ONLY static files.
+ * @param {string} folderPath
+ * @returns {Promise<{success: boolean, violations: string[]}>}
+ */
+export async function validateStaticOnly(folderPath) {
+    const violations = [];
+
+    try {
+        const files = await readdir(folderPath, { recursive: true, withFileTypes: true });
+
+        for (const file of files) {
+            const fileName = file.name.toLowerCase();
+            const ext = extname(fileName);
+
+            // 1. Check if the file/dir itself is a forbidden indicator
+            if (FORBIDDEN_INDICATORS.includes(fileName) || FORBIDDEN_INDICATORS.includes(ext)) {
+                violations.push(file.name);
+                continue;
+            }
+
+            // 2. Check extension for non-allowed types (only for files)
+            if (file.isFile()) {
+                // Ignore files without extensions or if they start with a dot (but handle indicators above)
+                if (ext && !ALLOWED_EXTENSIONS.has(ext)) {
+                    violations.push(file.name);
+                }
+            }
+        }
+
+        return {
+            success: violations.length === 0,
+            violations: [...new Set(violations)] // Deduplicate
+        };
+    } catch (err) {
+        throw new Error(`Failed to validate folder: ${err.message}`);
+    }
+}