webspresso 0.0.96 → 0.0.98

package/bin/commands/new.js

@@ -46,6 +46,8 @@ function registerCommand(program) {
     .description('Create a new Webspresso project')
     .option('-t, --template <template>', 'Template to use (minimal, full)', 'minimal')
     .option('--no-tailwind', 'Skip Tailwind CSS setup')
+    .option('--tailwind-v4', 'Use Tailwind CSS v4 (Oxide engine, zero-config)')
+    .option('--tailwind-version <version>', 'Tailwind version (3 or 4)', '3')
     .option('--no-agents', 'Skip AI Agent guidelines setup (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)')
     .option('-i, --install', 'Auto install dependencies and build CSS')
     .option('-y, --yes', 'Non-interactive: no database, skip install unless -i/--install, skip dev server')
@@ -657,20 +659,43 @@ Visit http://localhost:3000
       
       // Add Tailwind if requested (default: true)
       if (useTailwind) {
-        console.log('\n🎨 Setting up Tailwind CSS...\n');
+        const isV4 = Boolean(options.tailwindV4 || options.tailwindVersion === '4');
+        console.log(`\n🎨 Setting up Tailwind CSS ${isV4 ? 'v4 (Oxide engine, zero-config)' : 'v3'}...\n`);
         
         // Create src directory
         fs.mkdirSync(path.join(projectPath, 'src'), { recursive: true });
         
-        // Create input.css
-        const inputCss = `@tailwind base;
+        // Create public/css directory
+        fs.mkdirSync(path.join(projectPath, 'public', 'css'), { recursive: true });
+        fs.writeFileSync(path.join(projectPath, 'public', 'css', 'style.css'), '/* Run npm run build:css */\n');
+        
+        // Update package.json
+        const updatedPackageJson = JSON.parse(fs.readFileSync(path.join(projectPath, 'package.json'), 'utf-8'));
+        updatedPackageJson.devDependencies = updatedPackageJson.devDependencies || {};
+        updatedPackageJson.scripts = updatedPackageJson.scripts || {};
+
+        if (isV4) {
+          const inputCss = `@import "tailwindcss";
+
+@source "../pages/**/*.{njk,js}";
+@source "../views/**/*.njk";
+@source "../src/**/*.js";
+`;
+          fs.writeFileSync(path.join(projectPath, 'src', 'input.css'), inputCss);
+
+          updatedPackageJson.devDependencies['@tailwindcss/cli'] = '^4.0.0';
+          updatedPackageJson.devDependencies['tailwindcss'] = '^4.0.0';
+
+          updatedPackageJson.scripts['build:css'] = '@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --minify';
+          updatedPackageJson.scripts['watch:css'] = '@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --watch';
+        } else {
+          const inputCss = `@tailwind base;
 @tailwind components;
 @tailwind utilities;
 `;
-        fs.writeFileSync(path.join(projectPath, 'src', 'input.css'), inputCss);
-        
-        // Create tailwind.config.js
-        const tailwindConfig = `/** @type {import('tailwindcss').Config} */
+          fs.writeFileSync(path.join(projectPath, 'src', 'input.css'), inputCss);
+          
+          const tailwindConfig = `/** @type {import('tailwindcss').Config} */
 module.exports = {
   content: [
     './pages/**/*.{njk,js}',
@@ -683,33 +708,25 @@ module.exports = {
   plugins: [],
 }
 `;
-        fs.writeFileSync(path.join(projectPath, 'tailwind.config.js'), tailwindConfig);
-        
-        // Create postcss.config.js
-        const postcssConfig = `module.exports = {
+          fs.writeFileSync(path.join(projectPath, 'tailwind.config.js'), tailwindConfig);
+          
+          const postcssConfig = `module.exports = {
   plugins: {
     tailwindcss: {},
     autoprefixer: {},
   },
 }
 `;
-        fs.writeFileSync(path.join(projectPath, 'postcss.config.js'), postcssConfig);
-        
-        // Create public/css directory
-        fs.mkdirSync(path.join(projectPath, 'public', 'css'), { recursive: true });
-        
-        // Create placeholder CSS (will be replaced by build)
-        fs.writeFileSync(path.join(projectPath, 'public', 'css', 'style.css'), '/* Run npm run build:css */\n');
-        
-        // Update package.json
-        const updatedPackageJson = JSON.parse(fs.readFileSync(path.join(projectPath, 'package.json'), 'utf-8'));
-        updatedPackageJson.devDependencies = updatedPackageJson.devDependencies || {};
-        updatedPackageJson.devDependencies['tailwindcss'] = '^3.4.1';
-        updatedPackageJson.devDependencies['postcss'] = '^8.4.35';
-        updatedPackageJson.devDependencies['autoprefixer'] = '^10.4.17';
+          fs.writeFileSync(path.join(projectPath, 'postcss.config.js'), postcssConfig);
+          
+          updatedPackageJson.devDependencies['tailwindcss'] = '^3.4.1';
+          updatedPackageJson.devDependencies['postcss'] = '^8.4.35';
+          updatedPackageJson.devDependencies['autoprefixer'] = '^10.4.17';
+          
+          updatedPackageJson.scripts['build:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --minify';
+          updatedPackageJson.scripts['watch:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --watch';
+        }
         
-        updatedPackageJson.scripts['build:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --minify';
-        updatedPackageJson.scripts['watch:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --watch';
         updatedPackageJson.scripts.dev = 'webspresso dev';
         updatedPackageJson.scripts.start = 'npm run build:css && NODE_ENV=production node server.js';
         
@@ -718,7 +735,7 @@ module.exports = {
           JSON.stringify(updatedPackageJson, null, 2) + '\n'
         );
         
-        console.log('✅ Tailwind CSS setup complete!');
+        console.log(`✅ Tailwind CSS ${isV4 ? 'v4' : 'v3'} setup complete!`);
       }
 
       // Scaffold AI Agent guidelines unless --no-agents is specified

package/bin/commands/openapi.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Webspresso CLI - openapi / api:docs Command
+ * Generate and export OpenAPI 3 specification from application routes
+ * @module bin/commands/openapi
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanRoutes } = require('../../src/discovery/scan-routes');
+const { compileRouteTable } = require('../../src/routing/route-table');
+const { buildOpenApiDocument } = require('../../core/openapi/build-from-api-routes');
+
+function registerCommand(program) {
+  program
+    .command('openapi')
+    .alias('api:docs')
+    .description('Generate and export OpenAPI 3 specification from application routes')
+    .option('-o, --out <file>', 'Output JSON file path (e.g. openapi.json or public/openapi.json)')
+    .option('-r, --root <dir>', 'Root directory of the project', process.cwd())
+    .option('--pages <dir>', 'Pages directory relative to root', 'pages')
+    .option('--title <title>', 'OpenAPI specification title override')
+    .option('--api-version <version>', 'OpenAPI specification version override')
+    .option('--description <desc>', 'OpenAPI specification description override')
+    .option('--server <url>', 'Default server URL in spec', 'http://localhost:3000')
+    .option('--include-orm', 'Include ORM model schemas in components', false)
+    .option('--indent <spaces>', 'JSON indentation spaces', '2')
+    .option('-p, --print', 'Print specification JSON to stdout', false)
+    .action((options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+      const pagesRelDir = options.pages || 'pages';
+      const pagesDir = path.resolve(rootDir, pagesRelDir);
+      const apiDir = path.resolve(pagesDir, 'api');
+
+      if (!fs.existsSync(pagesDir) && !fs.existsSync(apiDir)) {
+        console.warn(`[webspresso] Warning: Pages directory not found at: ${pagesDir}`);
+      }
+
+      // Discover routes
+      const descriptors = scanRoutes({
+        rootDir,
+        pages: fs.existsSync(pagesDir) ? { dir: pagesRelDir } : true,
+        api: fs.existsSync(apiDir) ? { dir: path.join(pagesRelDir, 'api') } : true,
+      });
+
+      const routeTable = compileRouteTable(descriptors, { isDev: true });
+      const routes = routeTable.list();
+
+      // Read package.json metadata if available
+      let pkg = {};
+      const pkgPath = path.join(rootDir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        } catch {
+          // ignore invalid json
+        }
+      }
+
+      const docTitle = options.title || pkg.name || 'Webspresso API';
+      const docVersion = options.apiVersion || pkg.version || '1.0.0';
+      const docDescription =
+        options.description ||
+        pkg.description ||
+        'OpenAPI 3.0 specification generated from Webspresso file-based API routes.';
+
+      const doc = buildOpenApiDocument({
+        routes,
+        pagesDir,
+        includeOrmSchemas: Boolean(options.includeOrm),
+        info: {
+          title: docTitle,
+          version: docVersion,
+          description: docDescription,
+        },
+        servers: [{ url: String(options.server).replace(/\/$/, '') }],
+      });
+
+      const indent = parseInt(options.indent, 10) || 2;
+      const formattedJson = JSON.stringify(doc, null, indent);
+
+      if (options.out) {
+        const targetPath = path.resolve(rootDir, options.out);
+        const targetDir = path.dirname(targetPath);
+        if (!fs.existsSync(targetDir)) {
+          fs.mkdirSync(targetDir, { recursive: true });
+        }
+        fs.writeFileSync(targetPath, formattedJson, 'utf8');
+
+        const relPath = path.relative(rootDir, targetPath);
+        const pathCount = Object.keys(doc.paths || {}).length;
+        console.log(`\x1b[32m✔\x1b[0m Generated OpenAPI 3 specification with ${pathCount} path(s) -> \x1b[1m${relPath}\x1b[0m`);
+      }
+
+      if (!options.out || options.print) {
+        console.log(formattedJson);
+      }
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/orm-map.js

@@ -6,10 +6,6 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { getWebspressoOrmForProject } = require('../utils/resolve-webspresso-orm');
-const { loadProjectModels } = require('../utils/orm-map-load');
-const { buildSnapshot, buildMermaidErDiagram } = require('../utils/orm-map-snapshot');
-const { buildOrmMapHtml, readPackageName } = require('../utils/orm-map-html');
 
 function ensureOpenInsideTrustedRoots(absFile, cwd) {
   if (!fs.existsSync(absFile)) {
@@ -72,6 +68,11 @@ function registerCommand(program) {
     .option('-e, --env <environment>', 'Config environment', 'development')
     .option('-m, --models <dir>', 'Models directory (overrides config default ./models)')
     .action((options) => {
+      const { getWebspressoOrmForProject } = require('../utils/resolve-webspresso-orm');
+      const { loadProjectModels } = require('../utils/orm-map-load');
+      const { buildSnapshot, buildMermaidErDiagram } = require('../utils/orm-map-snapshot');
+      const { buildOrmMapHtml, readPackageName } = require('../utils/orm-map-html');
+
       const cwd = process.cwd();
       const { modelsDir, loaded, errors } = loadProjectModels(cwd, {
         modelsOverride: options.models,

package/bin/commands/page.js

@@ -19,14 +19,17 @@ const path = require('path');
 function registerCommand(program) {
   program
     .command('page [route]')
+    .alias('make:page')
+    .alias('page:make')
     .description('Add a new SSR page (Nunjucks template + companion load() loader)')
     .option('--no-loader', 'Skip creating companion .js loader file')
     .option('--locales', 'Create page-level locale files')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
     .action(async (routeArg, options) => {
-      const pagesDir = path.resolve(process.cwd(), 'pages');
+      const rootDir = path.resolve(options.root || process.cwd());
+      const pagesDir = path.join(rootDir, 'pages');
       if (!fs.existsSync(pagesDir)) {
-        console.error('❌ Not a Webspresso project! (pages/ directory not found)');
-        process.exit(1);
+        fs.mkdirSync(pagesDir, { recursive: true });
       }
 
       let route = routeArg ? String(routeArg).trim() : '';

package/bin/commands/polar-migrate.js

@@ -7,7 +7,6 @@
 const fs = require('fs');
 const path = require('path');
 const { loadDbConfig } = require('../utils/db');
-const { generatePolarMigration } = require('../../plugins/polar/src/migration');
 
 function registerCommand(program) {
   program
@@ -40,6 +39,7 @@ function registerCommand(program) {
         filepath = path.join(migrationDir, `${timestamp}_polar_billing.js`);
       }
 
+      const { generatePolarMigration } = require('../../plugins/polar/src/migration');
       const content = generatePolarMigration({ tableName: options.table });
       fs.writeFileSync(filepath, content, 'utf8');
       console.log(`✅ Polar migration written: ${filepath}`);

package/bin/commands/queue-prune.js

@@ -0,0 +1,59 @@
+/**
+ * Prune old background queue jobs (CLI)
+ */
+
+'use strict';
+
+const { loadDbConfig, createDbInstance } = require('../utils/db');
+
+function registerCommand(program) {
+  program
+    .command('queue:prune')
+    .description('Delete completed or failed queue jobs older than the given retention window')
+    .option('--days <n>', 'Delete jobs older than this many days', '7')
+    .option('--status <statuses>', 'Comma-separated statuses to delete (e.g. completed, failed)', 'completed')
+    .option('--table <name>', 'Queue table name', 'webspresso_jobs')
+    .option('-e, --env <environment>', 'Environment (development, production)', 'development')
+    .option('-c, --config <path>', 'Path to database config file')
+    .action(async (options) => {
+      const days = parseInt(options.days, 10);
+      if (Number.isNaN(days) || days < 0) {
+        console.error('❌ --days must be a non-negative integer');
+        process.exit(1);
+      }
+
+      const statuses = (options.status || 'completed')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+      const { config, path: configPath } = loadDbConfig(options.config);
+      console.log(`\n📦 Using config: ${configPath}`);
+      console.log(`   Environment: ${options.env}\n`);
+
+      const knex = await createDbInstance(config, options.env);
+      const olderThan = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+
+      try {
+        const { DatabaseQueueAdapter } = require('../../core/queue/adapters/database');
+        const adapter = new DatabaseQueueAdapter({
+          knex,
+          tableName: options.table,
+        });
+
+        const deleted = await adapter.clean({
+          status: statuses,
+          olderThan,
+        });
+
+        console.log(`✅ Deleted ${deleted} job(s) [status: ${statuses.join(', ')}] with timestamp before ${olderThan.toISOString()}.\n`);
+      } catch (err) {
+        console.error('❌ queue:prune failed:', err.message);
+        process.exit(1);
+      } finally {
+        await knex.destroy();
+      }
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/routes.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Webspresso CLI - routes Command
+ * Inspect and display compiled application routes
+ * @module bin/commands/routes
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { scanRoutes } = require('../../src/discovery/scan-routes');
+const { compileRouteTable } = require('../../src/routing/route-table');
+const { formatRouteTable } = require('../../src/dev/banner');
+
+function registerCommand(program) {
+  program
+    .command('routes')
+    .description('List and inspect all discovered application routes')
+    .option('-a, --api', 'Filter to only API endpoints')
+    .option('-p, --pages', 'Filter to only SSR page routes')
+    .option('-j, --json', 'Output routes as JSON')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
+    .action((options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+
+      const descriptors = scanRoutes({
+        rootDir,
+        pages: fs.existsSync(path.join(rootDir, 'pages')) ? { dir: 'pages' } : true,
+        api: fs.existsSync(path.join(rootDir, 'pages', 'api')) ? { dir: 'pages/api' } : true,
+      });
+
+      const routeTable = compileRouteTable(descriptors, { isDev: true });
+      let routes = routeTable.list();
+
+      if (options.api) {
+        routes = routes.filter((r) => r.type === 'api' || (r.path && r.path.startsWith('/api')));
+      } else if (options.pages) {
+        routes = routes.filter((r) => r.type === 'page' && (!r.path || !r.path.startsWith('/api')));
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify(routes, null, 2));
+        return;
+      }
+
+      console.log('');
+      console.log(formatRouteTable(routes, { limit: 200 }));
+      console.log('');
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/seed.js

@@ -14,7 +14,6 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { loadDbConfig } = require('../utils/db');
-const { getSeedFileTemplate } = require('../utils/seed');
 
 function registerCommand(program) {
   program
@@ -136,6 +135,7 @@ function registerCommand(program) {
           }
           
           // Create seed index file
+          const { getSeedFileTemplate } = require('../utils/seed');
           const seedIndex = getSeedFileTemplate();
           
           fs.writeFileSync(seedIndexPath, seedIndex);

package/bin/commands/service.js

@@ -199,6 +199,7 @@ function registerCommand(program) {
     .description('Scaffold a new service in services/<domain>/<action>.js')
     .option('-t, --transaction', 'Enable ACID transaction wrapper (transaction: true)')
     .option('-a, --auth <role>', 'Require authentication or specific role')
+    .option('--root <dir>', 'Root directory of the project', process.cwd())
     .action(async (nameArg, options) => {
       const fs = require('fs');
       let serviceName = nameArg ? String(nameArg).trim() : '';
@@ -223,7 +224,8 @@ function registerCommand(program) {
       const actionName = parts.pop();
       const domainPath = parts.join(path.sep);
 
-      const servicesDir = path.resolve(process.cwd(), 'services');
+      const rootDir = path.resolve(options.root || process.cwd());
+      const servicesDir = path.resolve(rootDir, 'services');
       const targetDir = path.join(servicesDir, domainPath);
       fs.mkdirSync(targetDir, { recursive: true });
 
@@ -241,13 +243,14 @@ function registerCommand(program) {
 
       const content = `'use strict';
 
+const { defineService } = require('webspresso');
 const { z } = require('zod');
 
 /**
  * Service: ${serviceName}
  * @type {import('webspresso').ServiceDefinition}
  */
-module.exports = {
+module.exports = defineService({
   // Input validation schema (Zod)
   schema: z.object({
     // Define input properties here
@@ -262,7 +265,7 @@ module.exports = {
       data: input,
     };
   },
-};
+});
 `;
 
       fs.writeFileSync(serviceFile, content, 'utf8');

package/bin/commands/typegen.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Webspresso CLI - typegen / types Command
+ * Generate TypeScript type definitions and IDE auto-complete for models, services, and routes
+ * @module bin/commands/typegen
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { generateTypes } = require('../../src/dev/typegen');
+
+function registerCommand(program) {
+  program
+    .command('typegen')
+    .alias('types')
+    .alias('generate:types')
+    .description('Generate TypeScript type definitions and IDE auto-complete for models, services, and routes')
+    .option('-o, --out <file>', 'Output declaration file path (default: .webspresso/types.d.ts)')
+    .option('-r, --root <dir>', 'Root directory of the project', process.cwd())
+    .option('--models <dir>', 'Models directory relative to root')
+    .option('--services <dir>', 'Services directory relative to root')
+    .option('--pages <dir>', 'Pages directory relative to root', 'pages')
+    .option('--no-env-file', 'Skip generating webspresso-env.d.ts at project root')
+    .option('-w, --watch', 'Watch models, services, and pages directories for changes')
+    .option('-s, --silent', 'Suppress console output', false)
+    .action((options) => {
+      const rootDir = path.resolve(options.root || process.cwd());
+
+      const runOnce = () => {
+        const startTime = Date.now();
+        const result = generateTypes({
+          rootDir,
+          modelsDir: options.models,
+          servicesDir: options.services,
+          pagesDir: options.pages,
+          outFile: options.out,
+          createEnvFile: options.envFile !== false,
+          silent: true,
+        });
+
+        const elapsed = Date.now() - startTime;
+        if (!options.silent) {
+          const relOut = path.relative(rootDir, result.outFile);
+          console.log(`\n⚡ [Webspresso TypeGen] Completed in ${elapsed}ms`);
+          console.log(`   ✓ Models:   ${result.modelsCount}`);
+          console.log(`   ✓ Services: ${result.servicesCount}`);
+          console.log(`   ✓ Routes:   ${result.routesCount}`);
+          console.log(`   → Output:   ${relOut}`);
+          if (result.envFile) {
+            console.log(`   → Env Ref:  ${path.relative(rootDir, result.envFile)}`);
+          }
+          console.log('');
+        }
+        return result;
+      };
+
+      runOnce();
+
+      // Watch mode
+      if (options.watch) {
+        if (!options.silent) {
+          console.log('👀 Watching models, services, and pages for changes... (Press Ctrl+C to stop)\n');
+        }
+
+        const watchDirs = [
+          options.models || 'models',
+          options.models || 'src/models',
+          options.services || 'services',
+          options.services || 'src/services',
+          options.pages || 'pages',
+          options.pages || 'src/pages',
+        ]
+          .map((d) => path.resolve(rootDir, d))
+          .filter((d) => fs.existsSync(d));
+
+        const uniqueDirs = Array.from(new Set(watchDirs));
+        let debounceTimer = null;
+
+        for (const dir of uniqueDirs) {
+          try {
+            fs.watch(dir, { recursive: true }, (eventType, filename) => {
+              if (
+                filename &&
+                (filename.endsWith('.js') || filename.endsWith('.ts') || filename.endsWith('.njk'))
+              ) {
+                if (debounceTimer) clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(() => {
+                  if (!options.silent) {
+                    console.log(`🔄 Detected change in ${filename}, regenerating types...`);
+                  }
+                  runOnce();
+                }, 150);
+              }
+            });
+          } catch {
+            // Watch unsupported on platform or directory
+          }
+        }
+      }
+    });
+}
+
+module.exports = {
+  registerCommand,
+};

package/bin/commands/upload-prune.js

@@ -0,0 +1,79 @@
+/**
+ * Prune unreferenced / orphaned uploaded files (CLI)
+ */
+
+'use strict';
+
+const path = require('path');
+const { loadDbConfig, createDbInstance } = require('../utils/db');
+const { pruneOrphanedUploads } = require('../../plugins/upload/orphan-pruner');
+
+function registerCommand(program) {
+  program
+    .command('upload:prune')
+    .description('Scan and delete orphaned files in the uploads directory not referenced by any database model')
+    .option('--dir <path>', 'Custom uploads directory path (default: public/uploads)')
+    .option('--url-base <path>', 'Public URL base path (default: /uploads)', '/uploads')
+    .option('--dry-run', 'Scan and list orphaned files without deleting them', false)
+    .option('-e, --env <environment>', 'Environment (development, production)', 'development')
+    .option('-c, --config <path>', 'Path to database config file')
+    .action(async (options) => {
+      const { config, path: configPath } = loadDbConfig(options.config);
+      console.log(`\n📦 Using config: ${configPath}`);
+      console.log(`   Environment: ${options.env}\n`);
+
+      const knex = await createDbInstance(config, options.env);
+      const db = { knex };
+
+      try {
+        const destDir = options.dir
+          ? path.resolve(process.cwd(), options.dir)
+          : path.resolve(process.cwd(), 'public', 'uploads');
+
+        console.log(`🔍 Scanning directory: ${destDir}`);
+        console.log(`   Public URL base: ${options.urlBase}`);
+        if (options.dryRun) {
+          console.log(`   Mode: DRY RUN (no files will be deleted)\n`);
+        } else {
+          console.log(`   Mode: PRUNE & DELETE\n`);
+        }
+
+        const result = await pruneOrphanedUploads({
+          db,
+          destDir,
+          publicBasePath: options.urlBase,
+          dryRun: options.dryRun,
+        });
+
+        console.log(`📊 Scan Summary:`);
+        console.log(`   Total files on disk: ${result.totalFiles} (${result.totalBytesFormatted})`);
+        console.log(`   Referenced by DB:   ${result.referencedCount}`);
+        console.log(`   Orphaned files:     ${result.orphanedCount} (${result.orphanedBytesFormatted})\n`);
+
+        if (result.orphanedCount === 0) {
+          console.log(`✅ No orphaned files found. Storage is clean!\n`);
+          return;
+        }
+
+        if (options.dryRun) {
+          console.log(`ℹ️ [DRY RUN] The following ${result.orphanedCount} file(s) would be deleted:`);
+          for (const file of result.orphanedFiles.slice(0, 20)) {
+            console.log(`   - ${file.relativePath} (${file.publicUrl})`);
+          }
+          if (result.orphanedFiles.length > 20) {
+            console.log(`   ... and ${result.orphanedFiles.length - 20} more file(s)`);
+          }
+          console.log(`\n💡 To permanently delete these files, run without --dry-run.\n`);
+        } else {
+          console.log(`🗑️ Successfully deleted ${result.deletedCount} orphaned file(s) (${result.deletedBytesFormatted} reclaimed).\n`);
+        }
+      } catch (err) {
+        console.error('❌ upload:prune failed:', err.message);
+        process.exit(1);
+      } finally {
+        await knex.destroy();
+      }
+    });
+}
+
+module.exports = { registerCommand };