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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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;