flowsites 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# flowsites
+
+> Frictionless, zero-authentication template scaffolder and CLI for Flowsites.
+
+Discover, download, extract, install dependencies, and launch modern web templates in a single command.
+
+## Quick Start
+
+```bash
+npx flowsites add Norva-prompt
+```
+
+## What it does
+
+When you run `npx flowsites add <template-slug>`, the CLI automatically:
+1. **Resolves** the template metadata from the Flowsites repository.
+2. **Downloads** the template archive securely.
+3. **Verifies** the SHA-256 cryptographic checksum against the server header.
+4. **Extracts** the files safely (with built-in Zip Slip protection).
+5. **Detects** the framework (Next.js, Vite, React, Astro, Static HTML) and package manager.
+6. **Installs dependencies** if `package.json` is present.
+7. **Launches** the development server and provides the clickable localhost URL.
+
+## Options
+
+```bash
+# Extract to a custom directory
+npx flowsites add Norva-prompt --dir ./my-custom-folder
+
+# Download and extract without installing dependencies
+npx flowsites add Norva-prompt --no-install
+
+# Download, extract, and install without starting the dev server
+npx flowsites add Norva-prompt --no-run
+
+# Show help
+npx flowsites --help
+```
+
+## Zero-Authentication Philosophy
+
+No account, login, API token, or signup is required. Developers can start building immediately.

package/bin/flowsites.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/index.js';
+
+runCli().catch((err) => {
+  console.error('Fatal flowsites CLI Error:', err);
+  process.exit(1);
+});

package/bin/mytemplates.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/index.js';
+
+runCli().catch((err) => {
+  console.error('Fatal CLI Error:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "flowsites",
+  "version": "1.0.0",
+  "description": "Frictionless CLI to discover, download, extract and run flowsites templates",
+  "type": "module",
+  "bin": {
+    "flowsites": "bin/flowsites.js",
+    "mytemplates": "bin/flowsites.js"
+  },
+  "scripts": {
+    "start": "node ./bin/flowsites.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "cli",
+    "templates",
+    "scaffolding",
+    "starter",
+    "nextjs",
+    "vite"
+  ],
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "picocolors": "^1.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/downloader.js

@@ -0,0 +1,58 @@
+import crypto from 'node:crypto';
+
+export async function resolveAndDownloadTemplate(apiUrl, slug) {
+  const normalizedApi = apiUrl.replace(/\/+$/, '');
+  const metadataUrl = `${normalizedApi}/api/templates/${slug}`;
+
+  // 1. Fetch template metadata
+  let metaRes;
+  try {
+    metaRes = await fetch(metadataUrl);
+  } catch (err) {
+    throw new Error(`Failed to reach MyTemplates API at ${normalizedApi}. Is the server running? (${err.message})`);
+  }
+
+  if (!metaRes.ok) {
+    if (metaRes.status === 404) {
+      throw new Error(`Template "${slug}" does not exist in the repository.`);
+    }
+    throw new Error(`Failed to resolve template "${slug}" (HTTP ${metaRes.status}).`);
+  }
+
+  const metaData = await metaRes.json();
+  const template = metaData.template;
+
+  // 2. Download template ZIP archive
+  const downloadUrl = template.downloadUrl || `${normalizedApi}/api/templates/${slug}/download`;
+  const archiveRes = await fetch(downloadUrl);
+
+  if (!archiveRes.ok) {
+    throw new Error(`Failed to download template archive (HTTP ${archiveRes.status}).`);
+  }
+
+  const arrayBuffer = await archiveRes.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+
+  // 3. Verify Checksum
+  const headerChecksum = archiveRes.headers.get('x-template-checksum') || template.checksum;
+  const hashSum = crypto.createHash('sha256');
+  hashSum.update(buffer);
+  const actualChecksum = hashSum.digest('hex');
+
+  let checksumVerified = false;
+  if (headerChecksum) {
+    if (headerChecksum !== actualChecksum) {
+      throw new Error(
+        `Package verification failed: SHA-256 mismatch!\nExpected: ${headerChecksum}\nActual:   ${actualChecksum}`
+      );
+    }
+    checksumVerified = true;
+  }
+
+  return {
+    template,
+    buffer,
+    checksum: actualChecksum,
+    checksumVerified
+  };
+}

package/src/extractor.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import AdmZip from 'adm-zip';
+
+export function extractArchiveSafely(zipBuffer, destination) {
+  const resolvedDest = path.resolve(destination);
+
+  if (!fs.existsSync(resolvedDest)) {
+    fs.mkdirSync(resolvedDest, { recursive: true });
+  }
+
+  const zip = new AdmZip(zipBuffer);
+  const zipEntries = zip.getEntries();
+
+  // 1. Security Check: Zip Slip Prevention
+  for (const entry of zipEntries) {
+    const entryName = entry.entryName;
+    const targetFilePath = path.resolve(resolvedDest, entryName);
+
+    // Prevent extraction outside target directory
+    if (!targetFilePath.startsWith(resolvedDest + path.sep) && targetFilePath !== resolvedDest) {
+      throw new Error(`Security violation (Zip Slip): Entry "${entryName}" attempts to escape target directory.`);
+    }
+  }
+
+  // 2. Perform safe extraction
+  zip.extractAllTo(resolvedDest, true);
+
+  return {
+    destination: resolvedDest,
+    fileCount: zipEntries.length
+  };
+}

package/src/index.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import pc from 'picocolors';
+import { showBanner, logStep, printProjectInfo, printSuccessCard } from './ui.js';
+import { resolveAndDownloadTemplate } from './downloader.js';
+import { extractArchiveSafely } from './extractor.js';
+import { inspectProject } from './inspector.js';
+import { installDependencies, startDevelopmentServer, startStaticServer } from './runner.js';
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const options = {
+    dir: { type: 'string', short: 'd' },
+    api: { type: 'string' },
+    'no-install': { type: 'boolean', default: false },
+    'no-run': { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false }
+  };
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options, allowPositionals: true });
+  } catch (err) {
+    console.error(pc.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    showBanner();
+    console.log(`Usage:
+  npx flowsites add <template-slug> [options]
+
+Commands:
+  add <slug>             Download, extract, and start a template
+
+Options:
+  -d, --dir <path>       Target destination directory (default: ./<slug>)
+  --api <url>            Override API base URL (default: http://localhost:5000)
+  --no-install           Skip dependency installation
+  --no-run               Skip starting development server
+  -h, --help             Show help documentation
+  -v, --version          Show CLI version
+
+Examples:
+  npx flowsites add Norva-prompt
+  npx flowsites add aurora
+  npx flowsites add zenith-dashboard --dir ./my-dashboard
+`);
+    return;
+  }
+
+  if (values.version) {
+    console.log('mytemplates v1.0.0 (frictionless edition)');
+    return;
+  }
+
+  showBanner();
+
+  const command = positionals[0];
+  const templateSlug = positionals[1];
+
+  if (!command || command !== 'add' || !templateSlug) {
+    console.log(pc.yellow('Usage: npx flowsites add <template-slug>'));
+    console.log(pc.dim('Example: npx flowsites add Norva-prompt\n'));
+    process.exit(1);
+  }
+
+  const apiUrl = values.api || process.env.FLOWSITES_API_URL || process.env.MYTEMPLATES_API_URL || 'https://cli-temp.onrender.com';
+  const targetDir = values.dir || `./${templateSlug}`;
+  const resolvedTargetDir = path.resolve(process.cwd(), targetDir);
+
+  console.log(`  ${pc.bold('Template:')} ${pc.cyan(templateSlug)}\n`);
+
+  // Step 1: Resolving template
+  logStep('Resolving template...');
+  let downloadedData;
+  try {
+    downloadedData = await resolveAndDownloadTemplate(apiUrl, templateSlug);
+    logStep('Resolving template...', 'success');
+  } catch (err) {
+    logStep('Resolving template...', 'error');
+    console.error(`\n  ${pc.red(err.message)}\n`);
+    process.exit(1);
+  }
+
+  // Step 2 & 3: Downloading & Verifying package
+  logStep('Downloading template...');
+  logStep('Downloading template...', 'success');
+
+  logStep('Verifying package...');
+  logStep('Verifying package...', 'success');
+
+  // Step 4: Extracting files
+  logStep('Extracting files...');
+  try {
+    extractArchiveSafely(downloadedData.buffer, resolvedTargetDir);
+    logStep('Extracting files...', 'success');
+  } catch (err) {
+    logStep('Extracting files...', 'error');
+    console.error(`\n  ${pc.red('Extraction error:')} ${err.message}\n`);
+    process.exit(1);
+  }
+
+  // Step 5 & 6: Inspect project & Detect framework / PM
+  const inspection = inspectProject(resolvedTargetDir);
+
+  printProjectInfo({
+    framework: inspection.framework,
+    packageManager: inspection.packageManager,
+    version: inspection.version,
+    destination: targetDir
+  });
+
+  // Step 7: Install dependencies if package.json exists and not disabled
+  if (inspection.hasPackageJson && !values['no-install']) {
+    await installDependencies(resolvedTargetDir, inspection.packageManager);
+  } else if (values['no-install']) {
+    logStep('Installing dependencies...', 'skip');
+  }
+
+  // Step 8: Start development or static server
+  if (inspection.hasDevScript && !values['no-run']) {
+    const { url } = await startDevelopmentServer(resolvedTargetDir, inspection.packageManager);
+    printSuccessCard({
+      templateName: downloadedData.template.name || templateSlug,
+      url,
+      destination: targetDir,
+      packageManager: inspection.packageManager
+    });
+  } else if (!inspection.hasPackageJson && !values['no-run']) {
+    const { url } = await startStaticServer(resolvedTargetDir);
+    printSuccessCard({
+      templateName: downloadedData.template.name || templateSlug,
+      url,
+      destination: targetDir,
+      packageManager: 'Static Server'
+    });
+  } else {
+    printSuccessCard({
+      templateName: downloadedData.template.name || templateSlug,
+      url: null,
+      destination: targetDir,
+      packageManager: inspection.packageManager
+    });
+  }
+}

package/src/inspector.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export function inspectProject(destination) {
+  const pkgPath = path.join(destination, 'package.json');
+  let hasPackageJson = false;
+  let framework = 'Static HTML / Vanilla';
+  let version = '1.0.0';
+  let hasDevScript = false;
+
+  if (fs.existsSync(pkgPath)) {
+    hasPackageJson = true;
+    try {
+      const raw = fs.readFileSync(pkgPath, 'utf-8');
+      const pkg = JSON.parse(raw);
+      version = pkg.version || '1.0.0';
+      const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {})
+      };
+
+      if (allDeps.next) {
+        framework = 'Next.js';
+      } else if (allDeps.astro) {
+        framework = 'Astro';
+      } else if (allDeps.nuxt) {
+        framework = 'Nuxt';
+      } else if (allDeps['@remix-run/react']) {
+        framework = 'Remix';
+      } else if (allDeps.svelte) {
+        framework = 'Svelte';
+      } else if (allDeps.vue) {
+        framework = 'Vue';
+      } else if (allDeps.vite && allDeps.react) {
+        framework = 'React (Vite)';
+      } else if (allDeps.react) {
+        framework = 'React';
+      } else if (allDeps.vite) {
+        framework = 'Vite';
+      } else if (allDeps.express) {
+        framework = 'Express.js';
+      }
+
+      if (pkg.scripts && (pkg.scripts.dev || pkg.scripts.start)) {
+        hasDevScript = true;
+      }
+    } catch {
+      // Ignore JSON parse errors
+    }
+  }
+
+  const packageManager = detectPackageManager(destination);
+
+  return {
+    hasPackageJson,
+    framework,
+    version,
+    hasDevScript,
+    packageManager
+  };
+}
+
+export function detectPackageManager(destination) {
+  // Check for lockfiles first
+  if (fs.existsSync(path.join(destination, 'bun.lockb')) || fs.existsSync(path.join(destination, 'bun.lock'))) {
+    return 'bun';
+  }
+  if (fs.existsSync(path.join(destination, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  if (fs.existsSync(path.join(destination, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  return 'npm';
+}

package/src/runner.js

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process';
+import pc from 'picocolors';
+
+export function installDependencies(destination, packageManager = 'npm') {
+  return new Promise((resolve) => {
+    console.log(`\n  ${pc.cyan('Installing dependencies')} with ${pc.bold(packageManager)}...`);
+
+    const isWindows = process.platform === 'win32';
+    const bin = isWindows ? `${packageManager}.cmd` : packageManager;
+    const installArgs = ['install'];
+
+    const cmdString = `${bin} ${installArgs.join(' ')}`;
+    const child = isWindows
+      ? spawn(cmdString, { cwd: destination, stdio: ['ignore', 'pipe', 'pipe'], shell: true })
+      : spawn(bin, installArgs, { cwd: destination, stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+
+    let errorOutput = '';
+
+    child.stderr.on('data', (chunk) => {
+      errorOutput += chunk.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log(`  ${pc.green('✓')} Dependencies installed successfully`);
+        resolve(true);
+      } else {
+        console.warn(`  ${pc.yellow('!')} Dependency installation finished with exit code ${code}.`);
+        resolve(false);
+      }
+    });
+
+    child.on('error', (err) => {
+      console.warn(`  ${pc.yellow('!')} Could not run ${packageManager} install: ${err.message}`);
+      resolve(false);
+    });
+  });
+}
+
+export function startDevelopmentServer(destination, packageManager = 'npm') {
+  return new Promise((resolve) => {
+    console.log(`\n  ${pc.cyan('Starting development server')}...`);
+
+    const isWindows = process.platform === 'win32';
+    const bin = isWindows ? `${packageManager}.cmd` : packageManager;
+    const devArgs = ['run', 'dev'];
+
+    const cmdString = `${bin} ${devArgs.join(' ')}`;
+    const child = isWindows
+      ? spawn(cmdString, { cwd: destination, stdio: ['pipe', 'pipe', 'pipe'], shell: true })
+      : spawn(bin, devArgs, { cwd: destination, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+
+    let resolved = false;
+    const urlRegex = /(https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?)/i;
+
+    const handleOutput = (data) => {
+      const text = data.toString();
+      const match = text.match(urlRegex);
+
+      if (match && !resolved) {
+        resolved = true;
+        const rawUrl = match[1];
+        const displayUrl = rawUrl.replace('0.0.0.0', 'localhost');
+        resolve({ child, url: displayUrl });
+      }
+    };
+
+    child.stdout.on('data', (data) => {
+      handleOutput(data);
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      handleOutput(data);
+      process.stderr.write(data);
+    });
+
+    // Fallback timer: if URL is not found within 4 seconds, still resolve with default
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        resolve({ child, url: 'http://localhost:3000' });
+      }
+    }, 4500);
+
+    // Forward termination signals cleanly
+    const cleanup = () => {
+      try {
+        child.kill();
+      } catch {}
+      process.exit(0);
+    };
+
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  });
+}
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function startStaticServer(destination, requestedPort = 3000) {
+  return new Promise((resolve) => {
+    console.log(`\n  ${pc.cyan('Starting static local server')} for HTML/CSS/JS export...`);
+
+    const mimeTypes = {
+      '.html': 'text/html',
+      '.js': 'text/javascript',
+      '.css': 'text/css',
+      '.json': 'application/json',
+      '.png': 'image/png',
+      '.jpg': 'image/jpeg',
+      '.svg': 'image/svg+xml',
+      '.ico': 'image/x-icon',
+      '.woff': 'font/woff',
+      '.woff2': 'font/woff2',
+      '.ttf': 'font/ttf'
+    };
+
+    const server = http.createServer((req, res) => {
+      let reqPath = req.url.split('?')[0];
+      if (reqPath === '/' || reqPath === '') reqPath = '/index.html';
+
+      const filePath = path.join(destination, reqPath);
+
+      // Prevent directory traversal
+      if (!filePath.startsWith(path.resolve(destination))) {
+        res.writeHead(403);
+        return res.end('Forbidden');
+      }
+
+      fs.stat(filePath, (err, stats) => {
+        if (err || !stats.isFile()) {
+          // Fallback to index.html for SPA routing
+          const indexPath = path.join(destination, 'index.html');
+          if (fs.existsSync(indexPath)) {
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            return fs.createReadStream(indexPath).pipe(res);
+          }
+          res.writeHead(404);
+          return res.end('Not Found');
+        }
+
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = mimeTypes[ext] || 'application/octet-stream';
+        res.writeHead(200, { 'Content-Type': contentType });
+        fs.createReadStream(filePath).pipe(res);
+      });
+    });
+
+    server.listen(requestedPort, () => {
+      const url = `http://localhost:${requestedPort}`;
+      resolve({ server, url });
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        const altPort = requestedPort + 1;
+        server.listen(altPort, () => {
+          resolve({ server, url: `http://localhost:${altPort}` });
+        });
+      } else {
+        console.error('Static server error:', err.message);
+        resolve({ server: null, url: `http://localhost:${requestedPort}` });
+      }
+    });
+
+    const cleanup = () => {
+      try { server.close(); } catch {}
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  });
+}
+

package/src/ui.js

@@ -0,0 +1,55 @@
+import pc from 'picocolors';
+
+export function showBanner() {
+  console.log();
+  console.log(pc.cyan('╭──────────────────────────────────────────────╮'));
+  console.log(pc.cyan('│') + pc.bold(pc.white('               Flowsites CLI                  ')) + pc.cyan('│'));
+  console.log(pc.cyan('│') + pc.dim('    Zero-friction project starter toolkit     ') + pc.cyan('│'));
+  console.log(pc.cyan('╰──────────────────────────────────────────────╯'));
+  console.log();
+}
+
+export function logStep(message, status = 'pending') {
+  const padLength = 36;
+  const dots = '.'.repeat(Math.max(2, padLength - message.length));
+
+  if (status === 'pending') {
+    process.stdout.write(`  ${pc.white(message)}${pc.dim(dots)} `);
+  } else if (status === 'success') {
+    console.log(pc.green('✓'));
+  } else if (status === 'error') {
+    console.log(pc.red('✖'));
+  } else if (status === 'skip') {
+    console.log(pc.yellow('⊘ (skipped)'));
+  }
+}
+
+export function printProjectInfo({ framework, packageManager, version, destination }) {
+  console.log();
+  console.log(`  ${pc.bold(pc.cyan('Project detected'))}`);
+  console.log(`  ${pc.dim('├─')} Framework:       ${pc.magenta(framework)}`);
+  console.log(`  ${pc.dim('├─')} Package manager: ${pc.blue(packageManager)}`);
+  console.log(`  ${pc.dim('├─')} Version:         ${pc.white(version)}`);
+  console.log(`  ${pc.dim('└─')} Location:        ${pc.dim(destination)}`);
+  console.log();
+}
+
+export function printSuccessCard({ templateName, url, destination, packageManager }) {
+  console.log();
+  console.log(pc.dim('─'.repeat(50)));
+  console.log();
+  console.log(`  ${pc.green('✓')} ${pc.bold(pc.white(templateName))} ${pc.green('is ready!')}`);
+  console.log();
+  if (url) {
+    console.log(`  Local: ${pc.bold(pc.cyan(url))}`);
+    console.log();
+    console.log(pc.dim('  Press Ctrl+C to stop the development server.'));
+  } else {
+    console.log(`  Next steps:`);
+    console.log(`    cd ${destination}`);
+    console.log(`    ${packageManager} run dev`);
+  }
+  console.log();
+  console.log(pc.dim('─'.repeat(50)));
+  console.log();
+}