create-claudeportal 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "create-claudeportal",
+  "version": "0.1.0",
+  "description": "Get from npx to a working app in under 5 minutes — Claude Code setup wizard",
+  "bin": {
+    "create-claudeportal": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "dev": "node bin/cli.js --dev",
+    "dev:frontend": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5.19",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
+    "chokidar": "^5.0.0",
+    "express": "^4.21.0",
+    "marked": "^17.0.4",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.2.0-beta.11"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-portal",
+    "claude-code",
+    "setup",
+    "developer-tools",
+    "ai"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "jsdom": "^29.0.0",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.1.0"
+  }
+}

package/server/index.js

@@ -0,0 +1,140 @@
+const express = require('express')
+const http = require('http')
+const path = require('path')
+const fs = require('fs')
+const os = require('os')
+const { WebSocketServer } = require('ws')
+const { createTerminal, attachToWebSocket, isPtyAvailable } = require('./lib/terminal')
+
+const detectRoutes = require('./routes/detect')
+const installRoutes = require('./routes/install')
+const githubRoutes = require('./routes/github')
+const scaffoldRoutes = require('./routes/scaffold')
+const { SSEManager } = require('./lib/sse-manager')
+const { FileWatcher } = require('./lib/file-watcher')
+const healthRoutes = require('./routes/health')
+const projectRoutes = require('./routes/project')
+const { createEventsRouter } = require('./routes/events')
+const { validateProjectPath } = require('./lib/validate-path')
+const folderRoutes = require('./routes/folder')
+const { createDocEventsRouter } = require('./routes/doc-events')
+
+function startServer(port) {
+  return new Promise((resolve) => {
+    const app = express()
+    const server = http.createServer(app)
+
+    // Ensure ~/Claude directory exists
+    const claudeDir = path.join(os.homedir(), 'Claude')
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true })
+    }
+
+    // WebSocket server for terminal
+    const wss = new WebSocketServer({ server, path: '/terminal' })
+
+    let activePty = null
+    let activeAttachment = null
+
+    wss.on('connection', (ws, req) => {
+      // Parse project directory from query string — validate it's safe
+      const url = new URL(req.url, `http://localhost:${port}`)
+      const rawCwd = url.searchParams.get('cwd') || ''
+      const resolvedCwd = rawCwd ? path.resolve(rawCwd) : claudeDir
+      const cwd = (resolvedCwd.startsWith(os.homedir()) && fs.existsSync(resolvedCwd))
+        ? resolvedCwd
+        : claudeDir
+
+      if (!isPtyAvailable()) {
+        try {
+          ws.send(JSON.stringify({
+            type: 'error',
+            message: 'Embedded terminal is not available. Please use your native terminal.',
+          }))
+        } catch {}
+        ws.close()
+        return
+      }
+
+      // Detach previous connection and kill previous PTY
+      if (activeAttachment) {
+        activeAttachment.detach()
+      }
+      if (activePty) {
+        try { activePty.kill() } catch {}
+      }
+
+      // Clear before creating new ones so a partial failure doesn't leave stale refs
+      activePty = null
+      activeAttachment = null
+
+      try {
+        const newPty = createTerminal(cwd)
+        const newAttachment = attachToWebSocket(ws, newPty)
+        activePty = newPty
+        activeAttachment = newAttachment
+      } catch (err) {
+        ws.send(JSON.stringify({ type: 'error', message: err.message }))
+        ws.close()
+      }
+    })
+
+    // Middleware
+    app.use(express.json())
+    const distPath = path.join(__dirname, '..', 'dist')
+    if (fs.existsSync(distPath)) {
+      app.use(express.static(distPath))
+    }
+    app.use(express.static(path.join(__dirname, '..', 'ui')))
+
+    // API info endpoint
+    app.get('/api/info', (req, res) => {
+      res.json({
+        version: require('../package.json').version,
+        ptyAvailable: isPtyAvailable(),
+      })
+    })
+
+    // Routes
+    app.use('/api', detectRoutes)
+    app.use('/api', installRoutes)
+    app.use('/api', githubRoutes)
+    app.use('/api', scaffoldRoutes)
+
+    // New services
+    const sseManager = new SSEManager()
+    const fileWatcher = new FileWatcher(sseManager)
+
+    // New routes
+    app.use('/api', healthRoutes)
+    app.use('/api', projectRoutes)
+    app.use('/api', createEventsRouter(sseManager, fileWatcher))
+    app.use('/api', folderRoutes)
+    app.use('/api', createDocEventsRouter(sseManager))
+
+    // Serve project files for live preview
+    app.use('/preview', (req, res) => {
+      const projectPath = validateProjectPath(req.query.projectPath) || path.join(os.homedir(), 'Claude')
+      const filePath = path.resolve(path.join(projectPath, req.path))
+      if (!filePath.startsWith(path.resolve(projectPath) + path.sep)) return res.status(403).end()
+      if (!fs.existsSync(filePath)) return res.status(404).end()
+      res.sendFile(filePath)
+    })
+
+    // Catch-all for SPA
+    app.get('*', (req, res) => {
+      const distIndex = path.join(__dirname, '..', 'dist', 'index.html')
+      if (fs.existsSync(distIndex)) {
+        res.sendFile(distIndex)
+      } else {
+        res.sendFile(path.join(__dirname, '..', 'ui', 'index.html'))
+      }
+    })
+
+    server.listen(port, () => {
+      resolve(server)
+    })
+  })
+}
+
+module.exports = { startServer }

package/server/lib/detect-tools.js

@@ -0,0 +1,93 @@
+const { execSync } = require('child_process')
+const { getPlatform } = require('./platform')
+
+const TOOLS = [
+  {
+    id: 'node',
+    name: 'Node.js',
+    command: 'node --version',
+    parse: (out) => out.trim(),
+    required: true,
+  },
+  {
+    id: 'npm',
+    name: 'npm',
+    command: 'npm --version',
+    parse: (out) => `v${out.trim()}`,
+    required: true,
+  },
+  {
+    id: 'claude',
+    name: 'Claude Code',
+    command: 'claude --version',
+    parse: (out) => {
+      const match = out.match(/(\d+\.\d+\.\d+)/)
+      return match ? `v${match[1]}` : out.trim()
+    },
+    required: true,
+  },
+]
+
+function detectTool(tool) {
+  try {
+    const output = execSync(tool.command, {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, PATH: getExpandedPath() },
+    })
+    const version = tool.parse(output)
+    return {
+      id: tool.id,
+      name: tool.name,
+      installed: !!version,
+      version: version || null,
+      required: tool.required || false,
+    }
+  } catch {
+    return {
+      id: tool.id,
+      name: tool.name,
+      installed: false,
+      version: null,
+      required: tool.required || false,
+    }
+  }
+}
+
+function detectAll() {
+  const platform = getPlatform()
+  const results = TOOLS.map(detectTool)
+  return { platform, tools: results }
+}
+
+// Expand PATH to include common install locations
+function getExpandedPath() {
+  const os = require('os')
+  const path = require('path')
+  const fs = require('fs')
+  const home = os.homedir()
+  const existing = process.env.PATH || ''
+
+  const extraPaths = [
+    path.join(home, '.npm-global', 'bin'),
+    '/usr/local/bin',
+    '/opt/homebrew/bin',
+    path.join(home, '.local', 'bin'),
+  ]
+
+  // Expand NVM paths — binaries are in versioned subdirectories
+  const nvmVersionsDir = path.join(home, '.nvm', 'versions', 'node')
+  try {
+    if (fs.existsSync(nvmVersionsDir)) {
+      const versions = fs.readdirSync(nvmVersionsDir)
+      versions.forEach((v) => extraPaths.push(path.join(nvmVersionsDir, v, 'bin')))
+    }
+  } catch {
+    // NVM not installed — skip
+  }
+
+  return [...extraPaths, existing].join(path.delimiter)
+}
+
+module.exports = { detectAll, detectTool, TOOLS, getExpandedPath }

package/server/lib/file-scanner.js

@@ -0,0 +1,46 @@
+const fs = require('fs')
+const path = require('path')
+
+const HEALTH_CHECKS = [
+  {
+    id: 'claude-md',
+    label: 'CLAUDE.md',
+    description: 'Claude works better when it understands your project',
+    path: 'CLAUDE.md',
+    fixPrompt: 'Create a CLAUDE.md file for this project. Scan the codebase and document: project overview, quick reference commands (install, dev, build, test, lint), tech stack, project structure, key conventions, environment variables, and database setup if applicable.',
+  },
+  {
+    id: 'readme',
+    label: 'README.md',
+    description: 'Helps Claude and others understand what this project does',
+    path: 'README.md',
+    fixPrompt: 'Create a README.md for this project with: project name and description, installation instructions, how to run in development, how to build for production, and key features.',
+  },
+  {
+    id: 'gitignore',
+    label: '.gitignore',
+    description: 'Prevents accidentally sharing sensitive files',
+    path: '.gitignore',
+    fixPrompt: 'Create a .gitignore file appropriate for this project. Include common patterns for the detected language/framework, node_modules, .env files, build artifacts, and IDE files.',
+  },
+]
+
+function scanProject(projectPath) {
+  return HEALTH_CHECKS.map(check => {
+    if (check.condition && !check.condition(projectPath)) return null
+
+    const paths = check.paths || [check.path]
+    const found = paths.some(p => fs.existsSync(path.join(projectPath, p)))
+
+    return {
+      id: check.id,
+      label: check.label,
+      description: check.description,
+      path: check.path || check.paths?.[0],
+      status: found ? 'pass' : 'fail',
+      fixPrompt: found ? undefined : check.fixPrompt,
+    }
+  }).filter(Boolean)
+}
+
+module.exports = { scanProject }

package/server/lib/file-watcher.js

@@ -0,0 +1,45 @@
+const chokidar = require('chokidar')
+const path = require('path')
+
+class FileWatcher {
+  constructor(sseManager) {
+    this.sseManager = sseManager
+    this.watchers = new Map()
+  }
+
+  watch(projectPath) {
+    if (this.watchers.has(projectPath)) return
+
+    const watcher = chokidar.watch(projectPath, {
+      ignoreInitial: true,
+      depth: 2,
+      ignored: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+    })
+
+    watcher.on('add', (fp) => this._emit(projectPath, fp, 'add'))
+    watcher.on('unlink', (fp) => this._emit(projectPath, fp, 'unlink'))
+    watcher.on('change', (fp) => this._emit(projectPath, fp, 'change'))
+    watcher.on('error', (err) => console.error(`FileWatcher error [${projectPath}]:`, err.message))
+
+    this.watchers.set(projectPath, watcher)
+  }
+
+  _emit(projectPath, filePath, eventType) {
+    const relative = path.relative(projectPath, filePath)
+    this.sseManager.send(projectPath, 'health-changed', { file: relative, eventType })
+
+    if (relative.startsWith('docs' + path.sep + 'plans') || relative.startsWith('docs/plans')) {
+      this.sseManager.send(projectPath, 'plan-changed', { file: relative, eventType })
+    }
+  }
+
+  unwatch(projectPath) {
+    const watcher = this.watchers.get(projectPath)
+    if (watcher) {
+      watcher.close()
+      this.watchers.delete(projectPath)
+    }
+  }
+}
+
+module.exports = { FileWatcher }

package/server/lib/fix-npm-prefix.js

@@ -0,0 +1,61 @@
+const os = require('os')
+const path = require('path')
+const fs = require('fs')
+const { execSync, execFileSync } = require('child_process')
+
+/**
+ * Fix npm global prefix on Mac to avoid sudo.
+ * When Node is installed via .pkg from nodejs.org, global packages
+ * go to /usr/local/lib/node_modules (owned by root) which requires sudo.
+ * This fixes it by redirecting to ~/.npm-global (user-owned).
+ */
+function fixNpmPrefix() {
+  if (process.platform !== 'darwin') {
+    return { fixed: false, reason: 'not-mac', prefix: null }
+  }
+
+  try {
+    const currentPrefix = execSync('npm config get prefix', {
+      encoding: 'utf8',
+    }).trim()
+
+    // Only fix if prefix is /usr/local (the problematic default)
+    if (currentPrefix !== '/usr/local') {
+      return { fixed: false, reason: 'already-ok', prefix: currentPrefix }
+    }
+
+    const newPrefix = path.join(os.homedir(), '.npm-global')
+
+    // Create the directory
+    fs.mkdirSync(newPrefix, { recursive: true })
+    fs.mkdirSync(path.join(newPrefix, 'bin'), { recursive: true })
+    fs.mkdirSync(path.join(newPrefix, 'lib'), { recursive: true })
+
+    // Set npm prefix (use execFileSync to avoid shell interpolation issues with spaces)
+    execFileSync('npm', ['config', 'set', 'prefix', newPrefix])
+
+    // Add to PATH in .zshrc (macOS default shell)
+    const zshrc = path.join(os.homedir(), '.zshrc')
+    const pathLine = `export PATH="$HOME/.npm-global/bin:$PATH"`
+
+    const existing = fs.existsSync(zshrc)
+      ? fs.readFileSync(zshrc, 'utf8')
+      : ''
+
+    if (!existing.includes('.npm-global')) {
+      fs.appendFileSync(
+        zshrc,
+        `\n# Added by Greenhouse Setup\n${pathLine}\n`
+      )
+    }
+
+    // Update current process PATH so subsequent installs work immediately
+    process.env.PATH = `${path.join(newPrefix, 'bin')}:${process.env.PATH}`
+
+    return { fixed: true, reason: 'prefix-updated', prefix: newPrefix }
+  } catch (err) {
+    return { fixed: false, reason: 'error', error: err.message, prefix: null }
+  }
+}
+
+module.exports = { fixNpmPrefix }

package/server/lib/folder-scanner.js

@@ -0,0 +1,43 @@
+const fs = require('fs')
+const path = require('path')
+
+const SUPPORTED_TYPES = new Set([
+  'pdf', 'docx', 'doc', 'xlsx', 'xls', 'csv', 'tsv',
+  'txt', 'md', 'json', 'html', 'pptx', 'rtf', 'odt'
+])
+
+const MAX_FILES = 500
+
+function scanFolder(folderPath) {
+  const entries = fs.readdirSync(folderPath)
+  const supported = []
+
+  for (const entry of entries) {
+    const ext = path.extname(entry).slice(1).toLowerCase()
+    if (!SUPPORTED_TYPES.has(ext)) continue
+    const filePath = path.join(folderPath, entry)
+    try {
+      const stat = fs.statSync(filePath)
+      if (!stat.isFile()) continue
+      supported.push({ name: entry, type: ext, size: stat.size })
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const total = supported.length
+  const byType = {}
+  for (const file of supported) {
+    byType[file.type] = (byType[file.type] || 0) + 1
+  }
+
+  const files = supported.slice(0, MAX_FILES)
+
+  return {
+    path: folderPath,
+    files,
+    summary: { total, byType }
+  }
+}
+
+module.exports = { scanFolder }

package/server/lib/install-tools.js

@@ -0,0 +1,122 @@
+const { spawn } = require('child_process')
+const { getPlatform } = require('./platform')
+const { getExpandedPath } = require('./detect-tools')
+
+const INSTALL_COMMANDS = {
+  claude: {
+    mac: { type: 'npm', package: '@anthropic-ai/claude-code' },
+    windows: { type: 'npm', package: '@anthropic-ai/claude-code' },
+    linux: { type: 'npm', package: '@anthropic-ai/claude-code' },
+  },
+}
+
+/**
+ * Install a single tool. Returns a promise that resolves with the result.
+ * Calls onProgress(message) with status updates.
+ */
+async function installTool(toolId, onProgress) {
+  const platform = getPlatform()
+  const config = INSTALL_COMMANDS[toolId]
+
+  if (!config) {
+    return { success: false, error: `Unknown tool: ${toolId}` }
+  }
+
+  const osConfig = config[platform.os]
+  if (!osConfig) {
+    return { success: false, error: `No install method for ${toolId} on ${platform.os}` }
+  }
+
+  try {
+    switch (osConfig.type) {
+      case 'npm':
+        return await installViaNpm(osConfig.package, onProgress)
+
+      case 'shell':
+        return await installViaShell(osConfig.command, onProgress)
+
+      default:
+        return { success: false, error: `Unknown install type: ${osConfig.type}` }
+    }
+  } catch (err) {
+    return { success: false, error: err.message }
+  }
+}
+
+async function installViaNpm(packageName, onProgress) {
+  onProgress(`Installing ${packageName} via npm...`)
+
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['install', '-g', packageName], {
+      env: { ...process.env, PATH: getExpandedPath() },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 120000,
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString()
+    })
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString()
+      // npm outputs progress info to stderr
+      const line = data.toString().trim()
+      if (line) onProgress(line)
+    })
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true })
+      } else {
+        resolve({
+          success: false,
+          error: stderr || `npm install exited with code ${code}`,
+        })
+      }
+    })
+
+    child.on('error', (err) => {
+      resolve({ success: false, error: err.message })
+    })
+  })
+}
+
+async function installViaShell(command, onProgress) {
+  onProgress(`Running: ${command}`)
+
+  return new Promise((resolve) => {
+    const parts = command.split(' ')
+    const child = spawn(parts[0], parts.slice(1), {
+      env: { ...process.env, PATH: getExpandedPath() },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 120000,
+    })
+
+    let stderr = ''
+
+    child.stdout.on('data', (data) => {
+      onProgress(data.toString().trim())
+    })
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString()
+    })
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true })
+      } else {
+        resolve({ success: false, error: stderr || `Exited with code ${code}` })
+      }
+    })
+
+    child.on('error', (err) => {
+      resolve({ success: false, error: err.message })
+    })
+  })
+}
+
+module.exports = { installTool, INSTALL_COMMANDS }

package/server/lib/platform.js

@@ -0,0 +1,18 @@
+const os = require('os')
+
+function getPlatform() {
+  const platform = process.platform
+  const arch = os.arch()
+
+  return {
+    os: platform === 'darwin' ? 'mac' : platform === 'win32' ? 'windows' : 'linux',
+    arch: arch === 'arm64' ? 'arm64' : 'amd64',
+    shell: platform === 'win32'
+      ? 'powershell.exe'
+      : (process.env.SHELL || (platform === 'darwin' ? 'zsh' : 'bash')),
+    homeDir: os.homedir(),
+    raw: { platform, arch },
+  }
+}
+
+module.exports = { getPlatform }

package/server/lib/sse-manager.js

@@ -0,0 +1,36 @@
+class SSEManager {
+  constructor() {
+    this.connections = new Map()
+  }
+
+  addConnection(projectPath, res) {
+    if (!this.connections.has(projectPath)) {
+      this.connections.set(projectPath, new Set())
+    }
+    this.connections.get(projectPath).add(res)
+
+    res.on('close', () => {
+      const set = this.connections.get(projectPath)
+      if (set) {
+        set.delete(res)
+        if (set.size === 0) this.connections.delete(projectPath)
+      }
+    })
+  }
+
+  send(projectPath, event, data) {
+    const set = this.connections.get(projectPath)
+    if (!set) return
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+    for (const res of set) {
+      try { res.write(payload) } catch {}
+    }
+  }
+
+  hasConnections(projectPath) {
+    const set = this.connections.get(projectPath)
+    return !!(set && set.size > 0)
+  }
+}
+
+module.exports = { SSEManager }