Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

19.2 KB
Raw Blame
import { Router } from 'express';
import { writeFile, readdir, stat, rm } from 'fs/promises';
import { existsSync, realpathSync } from 'fs';
import { join, dirname, resolve, sep } from 'path';
import { fileURLToPath } from 'url';
import { exec } from '../lib/childProcess.js';
import { runCliBounded } from '../lib/runCliBounded.js';
import { promisify } from 'util';
import { platform } from 'os';
import { createApp, getReservedPorts, notifyAppsChanged } from '../services/apps.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest, scaffoldDirectoriesQuerySchema, scaffoldSchema, scaffoldTemplateCreateBodySchema } from '../lib/validation.js';
import { ensureDir, expandHome } from '../lib/fileUtils.js';
import { isWithinAllowedRoots, outsideAllowedRootsMessage } from '../lib/workspaceRoots.js';
import { scaffoldVite } from './scaffoldVite.js';
import { scaffoldExpress } from './scaffoldExpress.js';
import { scaffoldXcode } from '../services/xcodeScaffold.js';
import { toTargetName } from '../services/xcodeScripts.js';
import { scaffoldPortOS } from './scaffoldPortOS.js';

const execAsync = promisify(exec);

// Bound dependency installs so a stalled registry can't strand the request.
const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const router = Router();

// GET /api/scaffold/directories - Browse directories for directory picker.
// Operator-only (HOST_CONTROL_ROUTES): it enumerates any readable host
// directory, so the workspace roots that scope POST / below do not apply.
router.get('/directories', asyncHandler(async (req, res) => {
  const { path: dirPath, includeFiles } = validateRequest(scaffoldDirectoriesQuerySchema, req.query);

  // Default to parent of PortOS project if no path provided
  const defaultPath = resolve(join(__dirname, '../../..'));
  let targetPath;
  if (!dirPath) {
    targetPath = defaultPath;
  } else if (dirPath === '~' || dirPath.startsWith('~/') || dirPath.startsWith('~\\')) {
    // expandHome covers `~`, `~/foo`, and `~\foo` (Windows); embedded `~`
    // chars (e.g. `iCloud~md~obsidian`) fall through to the else branch.
    targetPath = resolve(expandHome(dirPath));
  } else {
    targetPath = resolve(dirPath);
  }

  // Validate path exists and is a directory
  if (!existsSync(targetPath)) {
    throw new ServerError('Directory does not exist', {
      status: 400,
      code: 'INVALID_PATH'
    });
  }

  const stats = await stat(targetPath);
  if (!stats.isDirectory()) {
    throw new ServerError('Path is not a directory', {
      status: 400,
      code: 'NOT_A_DIRECTORY'
    });
  }

  // Read directory contents
  const entries = await readdir(targetPath, { withFileTypes: true });
  const directories = entries
    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
    .map(entry => ({
      name: entry.name,
      path: join(targetPath, entry.name)
    }))
    .sort((a, b) => a.name.localeCompare(b.name));

  // Get parent directory info
  const parentPath = dirname(targetPath);
  const canGoUp = parentPath !== targetPath; // Can't go above root

  // On Windows, include available drive letters so users can navigate between drives
  let drives = null;
  if (platform() === 'win32') {
    // Only check common drive letters (C-Z) to avoid slow floppy/network drives (A-B)
    drives = [];
    for (let i = 67; i <= 90; i++) {
      const letter = String.fromCharCode(i);
      const drivePath = `${letter}:${sep}`;
      try { if (existsSync(drivePath)) drives.push(drivePath); } catch { /* skip inaccessible drives */ }
    }
  }

  res.json({
    currentPath: targetPath,
    parentPath: canGoUp ? parentPath : null,
    directories,
    ...(includeFiles === 'true' && { files: entries
      .filter(entry => (entry.isFile() || entry.isSymbolicLink()) && !entry.name.startsWith('.'))
      .map(entry => ({ name: entry.name, path: join(targetPath, entry.name) }))
      .sort((a, b) => a.name.localeCompare(b.name)) }),
    ...(drives && { drives })
  });
}));

// GET /api/scaffold/templates - List available templates
router.get('/templates', asyncHandler(async (req, res) => {
  const templates = [
    {
      id: 'portos-stack',
      name: 'PortOS Stack',
      description: 'Express + React + Vite with Tailwind, PM2, AI providers, and GitHub Actions CI/CD',
      type: 'portos-stack',
      icon: 'layers',
      builtIn: true,
      features: ['Express.js API', 'React + Vite frontend', 'Tailwind CSS', 'PM2 ecosystem', 'AI Provider Integration', 'GitHub Actions CI/CD', 'Collapsible nav layout'],
      ports: { ui: true, api: true }
    },
    {
      id: 'vite-express',
      name: 'Vite + Express',
      description: 'Full-stack with React frontend and Express API',
      type: 'vite+express',
      icon: 'code',
      features: ['React + Vite', 'Express.js API', 'CORS configured'],
      ports: { ui: true, api: true }
    },
    {
      id: 'vite-react',
      name: 'Vite + React',
      description: 'React app with Vite bundler',
      type: 'vite',
      icon: 'globe',
      features: ['React 18', 'Vite bundler', 'Fast HMR'],
      ports: { ui: true, api: false }
    },
    {
      id: 'express-api',
      name: 'Express API',
      description: 'Node.js Express API server',
      type: 'single-node-server',
      icon: 'server',
      features: ['Express.js', 'CORS', 'Health endpoint'],
      ports: { ui: false, api: true }
    },
    {
      id: 'ios-native',
      name: 'iOS Native App',
      description: 'SwiftUI + XcodeGen with TestFlight deploy script',
      type: 'ios-native',
      icon: 'smartphone',
      features: ['SwiftUI', 'SwiftData', 'XcodeGen', 'TestFlight CI/CD', 'On-device processing'],
      ports: { ui: false, api: false }
    },
    {
      id: 'xcode-multiplatform',
      name: 'Xcode Multi-Platform',
      description: 'SwiftUI app for iOS + macOS + watchOS with deploy & screenshot scripts',
      type: 'xcode',
      icon: 'monitor-smartphone',
      features: ['SwiftUI', 'iOS + macOS + watchOS', 'XcodeGen', 'TestFlight Deploy', 'Screenshot Automation', 'UI Tests'],
      ports: { ui: false, api: false }
    }
  ];

  res.json(templates);
}));

// POST /api/scaffold/templates/create - User-friendly template creation
router.post('/templates/create', asyncHandler(async (req, res) => {
  const { templateId, name, targetPath } = validateRequest(scaffoldTemplateCreateBodySchema, req.body);

  // Map to scaffold endpoint format
  const scaffoldData = {
    name,
    template: templateId,
    parentDir: targetPath
  };

  // Reuse scaffold logic
  req.body = scaffoldData;
  // Forward to scaffold endpoint logic (call the same handler)
  return scaffoldApp(req, res);
}));

/**
 * Find the next available ports starting from USER_APP_PORT_START
 * Returns { apiPort, uiPort } for the next contiguous pair
 */
const USER_APP_PORT_START = 5570;
const USER_APP_PORT_END = 5599;

async function findNextAvailablePorts(needsApi, needsUi) {
  const reservedPorts = await getReservedPorts();
  const reserved = new Set(reservedPorts);

  let apiPort = null;
  let uiPort = null;

  for (let port = USER_APP_PORT_START; port <= USER_APP_PORT_END; port++) {
    if (reserved.has(port)) continue;

    if (needsApi && !apiPort) {
      apiPort = port;
      reserved.add(port);
    } else if (needsUi && !uiPort) {
      uiPort = port;
      reserved.add(port);
    }

    if ((!needsApi || apiPort) && (!needsUi || uiPort)) break;
  }

  return { apiPort, uiPort };
}

// Shared scaffold logic
async function scaffoldApp(req, res) {
  // Validate + normalize the COMPLETE request before ANY filesystem write or
  // subprocess spawn: unknown templates and out-of-range ports are rejected
  // deterministically here, so no target directory or resource is allocated
  // for a request the route can't fulfill (issue #2390).
  const parsed = validateRequest(scaffoldSchema, req.body);
  const { name, template, parentDir, createGitHubRepo, githubOrg } = parsed;
  // uiPort/apiPort are reassigned by the auto-allocator below, so they need
  // their own mutable bindings.
  let { uiPort, apiPort } = parsed;

  // Auto-allocate ports if not provided
  const templateNeedsPorts = {
    'portos-stack': { api: true, ui: true },
    'vite-express': { api: true, ui: true },
    'vite-react': { api: false, ui: true },
    'express-api': { api: true, ui: false },
    'ios-native': { api: false, ui: false },
    'xcode-multiplatform': { api: false, ui: false }
  };

  const needs = templateNeedsPorts[template] || { api: false, ui: false };
  if ((needs.api && !apiPort) || (needs.ui && !uiPort)) {
    const allocated = await findNextAvailablePorts(needs.api && !apiPort, needs.ui && !uiPort);
    if (needs.api && !apiPort) apiPort = allocated.apiPort;
    if (needs.ui && !uiPort) uiPort = allocated.uiPort;
  }

  // Sanitize name for directory
  const dirName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
  const repoPath = join(parentDir, dirName);

  // Check parent exists
  if (!existsSync(parentDir)) {
    throw new ServerError('Parent directory does not exist', {
      status: 400,
      code: 'INVALID_PARENT'
    });
  }

  // Assert parentDir resolves within an allowed workspace root (mirrors commands.js pattern).
  // realpathSync throws on permission/TOCTOU edges — convert to a clean 400.
  let realParentDir;
  try {
    realParentDir = realpathSync(resolve(parentDir));
  } catch {
    throw new ServerError('parentDir is not accessible', { status: 400, code: 'INVALID_PARENT' });
  }
  if (!isWithinAllowedRoots(realParentDir)) {
    console.error(`❌ ${outsideAllowedRootsMessage(realParentDir, { field: 'parentDir' })}`);
    throw new ServerError('parentDir is outside allowed directories', { status: 403, code: 'FORBIDDEN' });
  }

  // Check target doesn't exist
  if (existsSync(repoPath)) {
    throw new ServerError('Directory already exists', {
      status: 400,
      code: 'DIR_EXISTS'
    });
  }

  const steps = [];
  const addStep = (name, status, error = null) => {
    steps.push({ name, status, error, timestamp: Date.now() });
  };

  // Create directory. Everything from here until the app is registered runs
  // under a rollback guard: a failed attempt must not leave a partial directory
  // behind, or a retry with the same name is blocked by DIR_EXISTS.
  await ensureDir(repoPath);
  addStep('Create directory', 'done');

  let app;
  try {
    app = await buildAndRegisterApp({ name, template, dirName, parentDir, repoPath, uiPort, apiPort, createGitHubRepo, githubOrg, addStep });
  } catch (err) {
    await rm(repoPath, { recursive: true, force: true })
      .catch(rmErr => console.error(`❌ Failed to clean up partial scaffold ${repoPath}: ${rmErr.message}`));
    console.error(`❌ Scaffold of ${dirName} failed, removed partial directory: ${err.message}`);
    throw err;
  }

  notifyAppsChanged('create', app.id);
  addStep('Register in PortOS', 'done');

  res.json({
    success: true,
    app,
    repoPath,
    steps
  });
}

// Generate template files, install, git-init, and register the app. Returns the
// registered app; throws before registration on any failure so the caller can
// roll back the directory.
async function buildAndRegisterApp({ name, template, dirName, parentDir, repoPath, uiPort, apiPort, createGitHubRepo, githubOrg, addStep }) {

  // Generate project files based on template
  if (template === 'vite-react' || template === 'vite-express') {
    await scaffoldVite({ repoPath, dirName, parentDir, template, uiPort, apiPort, addStep });
  } else if (template === 'express-api') {
    await scaffoldExpress(repoPath, dirName, apiPort, addStep);
  } else if (template === 'ios-native') {
    await scaffoldXcode(repoPath, name, dirName, addStep, { platforms: ['ios'] });
  } else if (template === 'xcode-multiplatform') {
    await scaffoldXcode(repoPath, name, dirName, addStep);
  } else if (template === 'portos-stack') {
    await scaffoldPortOS({ repoPath, name, dirName, uiPort, apiPort, addStep });
  }

  // Create .env file
  const envContent = [
    uiPort && `VITE_PORT=${uiPort}`,
    apiPort && `PORT=${apiPort}`
  ].filter(Boolean).join('\n');

  if (envContent) {
    await writeFile(join(repoPath, '.env'), envContent + '\n');
    addStep('Create .env', 'done');
  }

  // Create PM2 ecosystem file with proper PORTS constant pattern
  let ecosystemContent;

  if (template === 'portos-stack') {
    ecosystemContent = `// =============================================================================
// Port Configuration - All ports defined here as single source of truth
// =============================================================================
const PORTS = {
  API: ${apiPort},    // Express API server
  UI: ${uiPort}       // Vite dev server (client)
};

module.exports = {
  PORTS, // Export for other configs to reference

  apps: [
    {
      name: '${dirName}-server',
      script: 'server/index.js',
      cwd: __dirname,
      interpreter: 'node',
      env: {
        NODE_ENV: 'development',
        PORT: PORTS.API,
        HOST: '0.0.0.0'
      },
      watch: false
    },
    {
      name: '${dirName}-ui',
      script: 'node_modules/.bin/vite',
      cwd: \`\${__dirname}/client\`,
      args: \`--host 0.0.0.0 --port \${PORTS.UI}\`,
      env: {
        NODE_ENV: 'development',
        VITE_PORT: PORTS.UI
      },
      watch: false
    }
  ]
};
`;
  } else if (template === 'vite-express') {
    ecosystemContent = `// =============================================================================
// Port Configuration - All ports defined here as single source of truth
// =============================================================================
const PORTS = {
  API: ${apiPort},    // Express API server
  UI: ${uiPort}       // Vite dev server
};

module.exports = {
  PORTS,

  apps: [
    {
      name: '${dirName}-ui',
      script: 'npm',
      args: 'run dev',
      cwd: __dirname,
      env: {
        VITE_PORT: PORTS.UI
      }
    },
    {
      name: '${dirName}-api',
      script: 'server/index.js',
      cwd: __dirname,
      env: {
        PORT: PORTS.API
      }
    }
  ]
};
`;
  } else if (template === 'vite-react') {
    ecosystemContent = `// =============================================================================
// Port Configuration - All ports defined here as single source of truth
// =============================================================================
const PORTS = {
  UI: ${uiPort}       // Vite dev server
};

module.exports = {
  PORTS,

  apps: [
    {
      name: '${dirName}',
      script: 'npm',
      args: 'run dev',
      cwd: __dirname,
      env: {
        VITE_PORT: PORTS.UI
      }
    }
  ]
};
`;
  } else if (template === 'express-api') {
    ecosystemContent = `// =============================================================================
// Port Configuration - All ports defined here as single source of truth
// =============================================================================
const PORTS = {
  API: ${apiPort}     // Express API server
};

module.exports = {
  PORTS,

  apps: [
    {
      name: '${dirName}',
      script: 'index.js',
      cwd: __dirname,
      env: {
        PORT: PORTS.API
      }
    }
  ]
};
`;
  }

  if (ecosystemContent) {
    await writeFile(join(repoPath, 'ecosystem.config.cjs'), ecosystemContent);
    addStep('Create PM2 config', 'done');
  }

  // Run npm install (skip for Xcode projects — no npm)
  if (template !== 'ios-native' && template !== 'xcode-multiplatform') {
    const installCmd = template === 'portos-stack' ? 'npm run install:all' : 'npm install';
    const { stderr: installErr } = await execAsync(installCmd, { cwd: repoPath, timeout: INSTALL_TIMEOUT_MS })
      .catch(err => ({ stderr: err.message }));

    if (installErr && !installErr.includes('npm warn')) {
      addStep('npm install', 'error', installErr);
    } else {
      addStep('npm install', 'done');
    }
  }

  // Initialize git
  const runGit = async (args) => {
    const result = await runCliBounded('git', args, {
      cwd: repoPath,
      timeoutMs: 30_000,
      stdio: ['ignore', 'pipe', 'pipe'],
      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
    });
    if (result.code !== 0) {
      throw new Error(`git ${args[0]} failed: ${result.stderr.trim() || result.stdout.trim() || `exited with code ${result.code}`}`);
    }
  };
  await runGit(['init']);

  // Create .gitignore
  let gitignoreContent;
  if (template === 'ios-native' || template === 'xcode-multiplatform') {
    gitignoreContent = `# Build output
build/
.build/
DerivedData/

# Environment files
.env

# Screenshots config (generated by take_screenshots.sh)
.screenshot_config.json

# OS files
.DS_Store

# IDE
*.swp
*.swo
xcuserdata/
*.xcworkspace
`;
  } else if (template === 'portos-stack') {
    gitignoreContent = `# Dependencies
node_modules/

# Build output
dist/
build/

# Environment files
.env
.env.local
.env.*.local

# Logs
logs/
*.log
npm-debug.log*

# OS files
.DS_Store
Thumbs.db

# IDE
.idea/
.vscode/
*.swp
*.swo

# PM2
.pm2/
`;
  } else {
    gitignoreContent = 'node_modules\n.env\ndist\n';
  }

  await writeFile(join(repoPath, '.gitignore'), gitignoreContent);
  await runGit(['add', '-A']);
  await runGit(['commit', '-m', 'Initial commit']);
  addStep('Initialize git', 'done');

  // Create GitHub repo if requested
  if (createGitHubRepo) {
    // Security: Use spawn with array args to prevent shell injection from githubOrg/dirName
    const repoName = githubOrg ? `${githubOrg}/${dirName}` : dirName;
    const ghArgs = ['repo', 'create', repoName, '--source=.', '--push', '--private'];

    const result = await runCliBounded('gh', ghArgs, {
      cwd: repoPath,
      timeoutMs: 60_000,
      stdio: ['ignore', 'pipe', 'pipe'],
      env: { ...process.env, GH_PROMPT_DISABLED: '1', GIT_TERMINAL_PROMPT: '0' },
    });

    if (result.code !== 0) {
      addStep('Create GitHub repo', 'error', result.stderr.trim() || result.stdout.trim() || `gh repo create exited with code ${result.code}`);
    } else {
      addStep('Create GitHub repo', 'done');
    }
  }

  // Register in PortOS
  const templateToType = {
    'portos-stack': 'portos-stack',
    'vite-react': 'vite',
    'vite-express': 'vite+express',
    'express-api': 'single-node-server',
    'ios-native': 'ios-native',
    'xcode-multiplatform': 'xcode'
  };

  let pm2Names;
  let startCmds;
  let buildCmd;

  if (template === 'portos-stack') {
    pm2Names = [`${dirName}-server`, `${dirName}-ui`];
    startCmds = ['npm run dev'];
  } else if (template === 'vite-express') {
    pm2Names = [`${dirName}-ui`, `${dirName}-api`];
    startCmds = ['npm run dev:all'];
  } else if (template === 'ios-native' || template === 'xcode-multiplatform') {
    const tn = toTargetName(name);
    pm2Names = [];
    startCmds = [`open ${tn}.xcodeproj`];
    buildCmd = `xcodebuild build -project ${tn}.xcodeproj -scheme ${tn} -destination 'platform=iOS Simulator,name=iPhone 16' CODE_SIGNING_ALLOWED=NO`;
  } else {
    pm2Names = [dirName];
    startCmds = ['npm run dev'];
  }

  const app = await createApp({
    name,
    repoPath,
    type: templateToType[template] || 'unknown',
    uiPort: uiPort || null,
    apiPort: apiPort || null,
    buildCommand: buildCmd,
    startCommands: startCmds,
    pm2ProcessNames: pm2Names,
    envFile: '.env'
  });

  return app;
}

// POST /api/scaffold - Create a new app from template
router.post('/', asyncHandler(scaffoldApp));

export default router;