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

18.5 KB
Raw Blame
import { writeFile } from 'fs/promises';
import { join } from 'path';
import { atomicWrite, ensureDir, ensureDirs } from '../lib/fileUtils.js';
import { writeAgentInstructions } from '../lib/agentInstructionsFile.js';
import { CORS_SNIPPET } from '../lib/scaffoldSnippets.js';

export async function scaffoldPortOS({ repoPath, name, dirName, uiPort, apiPort, addStep }) {
  const clientDir = join(repoPath, 'client');
  const serverDir = join(repoPath, 'server');
  const workflowsDir = join(repoPath, '.github/workflows');

  await ensureDirs([clientDir, serverDir, workflowsDir]);

  // === Root package.json ===
  const rootPkg = {
    name: dirName,
    version: '0.1.0',
    private: true,
    description: `${name} - built with PortOS Stack`,
    type: 'module',
    scripts: {
      'dev': 'concurrently "npm run dev:server" "npm run dev:client"',
      'dev:server': 'cd server && npm run dev',
      'dev:client': 'cd client && npm run dev',
      'build': 'cd client && npm run build',
      'start': 'cd server && npm start',
      'install:all': 'npm install && cd client && npm install && cd ../server && npm install',
      'test': 'cd server && npm test'
    },
    devDependencies: {
      'concurrently': '^8.2.2'
    }
  };
  await atomicWrite(join(repoPath, 'package.json'), rootPkg);

  // === Client package.json ===
  const clientPkg = {
    name: `${dirName}-ui`,
    version: '0.1.0',
    private: true,
    type: 'module',
    scripts: {
      'dev': `vite --host 0.0.0.0 --port ${uiPort || 3000}`,
      'build': 'vite build',
      'preview': 'vite preview'
    },
    dependencies: {
      'lucide-react': '^0.562.0',
      'portos-ai-toolkit': '^0.1.0',
      'react': '^18.3.1',
      'react-dom': '^18.3.1',
      'react-hot-toast': '^2.6.0',
      'react-router-dom': '^7.1.1',
      'socket.io-client': '^4.8.3'
    },
    devDependencies: {
      '@vitejs/plugin-react': '^4.3.4',
      'autoprefixer': '^10.4.20',
      'postcss': '^8.4.49',
      'tailwindcss': '^3.4.17',
      'vite': '^6.0.6'
    }
  };
  await atomicWrite(join(clientDir, 'package.json'), clientPkg);

  // === Client vite.config.js ===
  await writeFile(join(clientDir, 'vite.config.js'), `import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: ${uiPort || 3000},
    proxy: {
      '/api': {
        target: 'http://localhost:${apiPort || 3001}',
        changeOrigin: true
      },
      '/socket.io': {
        target: 'http://localhost:${apiPort || 3001}',
        changeOrigin: true,
        ws: true
      }
    }
  }
});
`);

  // === Client tailwind.config.js ===
  await writeFile(join(clientDir, 'tailwind.config.js'), `/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        'app-bg': '#0f0f0f',
        'app-card': '#1a1a1a',
        'app-border': '#2a2a2a',
        'app-accent': '#3b82f6',
        'app-success': '#22c55e',
        'app-warning': '#f59e0b',
        'app-error': '#ef4444'
      }
    },
  },
  plugins: [],
}
`);

  // === Client postcss.config.js ===
  await writeFile(join(clientDir, 'postcss.config.js'), `export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
`);

  // === Client index.html ===
  await writeFile(join(clientDir, 'index.html'), `<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>${name}</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>
`);

  // === Client src files ===
  const clientSrcDir = join(clientDir, 'src');
  await ensureDir(clientSrcDir);

  await writeFile(join(clientSrcDir, 'main.jsx'), `import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import { Toaster } from 'react-hot-toast';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
      <Toaster position="bottom-right" />
    </BrowserRouter>
  </React.StrictMode>
);
`);

  await writeFile(join(clientSrcDir, 'App.jsx'), `import { Routes, Route, Link } from 'react-router-dom';
import { Menu, X, Home, Brain, Info } from 'lucide-react';
import { useState } from 'react';
import { useLocation } from 'react-router-dom';
import AIProviders from './pages/AIProviders';

function HomePage() {
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold mb-4">Welcome to ${name}</h1>
      <p className="text-gray-400">Built with PortOS Stack</p>
    </div>
  );
}

function About() {
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold mb-4">About</h1>
      <p className="text-gray-400">Express + React + Vite + Tailwind + AI Provider Integration</p>
    </div>
  );
}

export default function App() {
  const [navOpen, setNavOpen] = useState(true);
  const location = useLocation();

  return (
    <div className="flex min-h-screen bg-app-bg text-white">
      {/* Collapsible sidebar */}
      <nav className={\`\${navOpen ? 'w-48' : 'w-12'} bg-app-card border-r border-app-border transition-all duration-200 flex flex-col\`}>
        <button
          onClick={() => setNavOpen(!navOpen)}
          className="p-3 hover:bg-app-border"
        >
          {navOpen ? <X size={20} /> : <Menu size={20} />}
        </button>
        <div className="flex flex-col gap-1 p-2">
          <Link to="/" className={\`flex items-center gap-2 p-2 rounded hover:bg-app-border \${location.pathname === '/' ? 'bg-app-accent/20 text-app-accent' : ''}\`}>
            <Home size={18} />
            {navOpen && <span>Home</span>}
          </Link>
          <Link to="/providers" className={\`flex items-center gap-2 p-2 rounded hover:bg-app-border \${location.pathname === '/providers' ? 'bg-app-accent/20 text-app-accent' : ''}\`}>
            <Brain size={18} />
            {navOpen && <span>AI Providers</span>}
          </Link>
          <Link to="/about" className={\`flex items-center gap-2 p-2 rounded hover:bg-app-border \${location.pathname === '/about' ? 'bg-app-accent/20 text-app-accent' : ''}\`}>
            <Info size={18} />
            {navOpen && <span>About</span>}
          </Link>
        </div>
      </nav>

      {/* Main content */}
      <main className="flex-1 overflow-auto">
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/providers" element={<AIProviders />} />
          <Route path="/about" element={<About />} />
        </Routes>
      </main>
    </div>
  );
}
`);

  await writeFile(join(clientSrcDir, 'index.css'), `@tailwind base;
@tailwind components;
@tailwind utilities;

body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
`);

  // === Client pages ===
  const pagesDir = join(clientSrcDir, 'pages');
  await ensureDir(pagesDir);

  // AIProviders page - uses shared component from ai-toolkit
  await writeFile(join(pagesDir, 'AIProviders.jsx'), `import { AIProviders } from 'portos-ai-toolkit/client';
import toast from 'react-hot-toast';

export default function AIProvidersPage() {
  return <AIProviders onError={toast.error} colorPrefix="app" />;
}
`);

  addStep('Create client', 'done');

  // === Server package.json ===
  const serverPkg = {
    name: `${dirName}-server`,
    version: '0.1.0',
    private: true,
    type: 'module',
    scripts: {
      'dev': 'node --watch index.js',
      'start': 'node index.js',
      'test': 'vitest run',
      'test:watch': 'vitest'
    },
    dependencies: {
      'express': '^4.21.2',
      'portos-ai-toolkit': '^0.1.0',
      'socket.io': '^4.8.3',
      'zod': '^3.24.1'
    },
    devDependencies: {
      'vitest': '^2.1.8'
    }
  };
  await atomicWrite(join(serverDir, 'package.json'), serverPkg);

  // === Server index.js ===
  await writeFile(join(serverDir, 'index.js'), `import express from 'express';
import { createServer } from 'http';
import { Server } from 'socket.io';
import { createAIToolkit } from 'portos-ai-toolkit/server';

const app = express();
const httpServer = createServer(app);
const io = new Server(httpServer, {
  cors: { origin: '*' }
});

const PORT = process.env.PORT || ${apiPort || 3001};

${CORS_SNIPPET}
app.use(express.json());

// Initialize AI Toolkit with routes for providers, runs, and prompts
const aiToolkit = createAIToolkit({
  dataDir: './data',
  io
});
aiToolkit.mountRoutes(app);

// Health endpoint
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

// Socket.IO connection
io.on('connection', (socket) => {
  console.log(\`🔌 Client connected: \${socket.id}\`);
  socket.on('disconnect', () => {
    console.log(\`🔌 Client disconnected: \${socket.id}\`);
  });
});

httpServer.listen(PORT, '0.0.0.0', () => {
  console.log(\`🚀 Server running on port \${PORT}\`);
});
`);

  // === Server vitest.config.js ===
  await writeFile(join(serverDir, 'vitest.config.js'), `import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node'
  }
});
`);

  addStep('Create server', 'done');

  // === Default Data (providers, etc.) ===
  const dataDir = join(repoPath, 'data');
  await ensureDir(dataDir);

  const defaultProviders = {
    activeProvider: 'claude-code',
    providers: {
      'claude-code': {
        id: 'claude-code',
        name: 'Claude Code CLI',
        type: 'cli',
        command: 'claude',
        args: ['--print'],
        models: ['claude-haiku-4-5', 'claude-sonnet-5', 'claude-opus-5-5', 'claude-opus-5'],
        defaultModel: 'claude-opus-5-5',
        lightModel: 'claude-haiku-4-5',
        mediumModel: 'claude-sonnet-5',
        heavyModel: 'claude-opus-5-5',
        timeout: 300000,
        enabled: true,
        envVars: {}
      },
      'codex': {
        id: 'codex',
        name: 'Codex CLI',
        type: 'cli',
        command: 'codex',
        args: [],
        models: ['codex-configured-default'],
        defaultModel: 'codex-configured-default',
        lightModel: 'codex-configured-default',
        mediumModel: 'codex-configured-default',
        heavyModel: 'codex-configured-default',
        timeout: 300000,
        enabled: true,
        envVars: {}
      },
      'lm-studio': {
        id: 'lm-studio',
        name: 'LM Studio (Local)',
        type: 'api',
        endpoint: 'http://localhost:1234/v1',
        apiKey: 'lm-studio',
        models: [],
        defaultModel: null,
        timeout: 300000,
        enabled: false,
        envVars: {}
      },
      'ollama': {
        id: 'ollama',
        name: 'Ollama (Local)',
        type: 'api',
        endpoint: 'http://localhost:11434/v1',
        apiKey: '',
        models: [],
        defaultModel: null,
        timeout: 300000,
        enabled: false,
        envVars: {}
      }
    }
  };
  await atomicWrite(join(dataDir, 'providers.json'), defaultProviders);
  addStep('Create default data', 'done');

  // === GitHub Actions CI ===
  await writeFile(join(workflowsDir, 'ci.yml'), `name: CI

on:
  pull_request:
    branches: [main, dev]
  push:
    branches: [dev]

permissions:
  contents: write

jobs:
  test:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip ci]')"

    strategy:
      matrix:
        node-version: [20.x]

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js \${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: \${{ matrix.node-version }}
          cache: 'npm'

      - name: Install root dependencies
        run: npm ci

      - name: Install client dependencies
        working-directory: ./client
        run: npm ci

      - name: Install server dependencies
        working-directory: ./server
        run: npm ci

      - name: Run server tests
        working-directory: ./server
        run: npm test

      - name: Build client
        working-directory: ./client
        run: npm run build

  bump-build:
    runs-on: ubuntu-latest
    needs: [test]
    if: github.event_name == 'push' && github.ref == 'refs/heads/dev' && !contains(github.event.head_commit.message, '[skip ci]')

    steps:
      - uses: actions/checkout@v4
        with:
          token: \${{ secrets.GITHUB_TOKEN }}

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Bump patch version
        run: |
          CURRENT_VERSION=\$(node -p "require('./package.json').version")
          MAJOR=\$(echo \$CURRENT_VERSION | cut -d. -f1)
          MINOR=\$(echo \$CURRENT_VERSION | cut -d. -f2)
          PATCH=\$(echo \$CURRENT_VERSION | cut -d. -f3)
          NEW_PATCH=\$((PATCH + 1))
          NEW_VERSION="\$MAJOR.\$MINOR.\$NEW_PATCH"
          npm version \$NEW_VERSION --no-git-tag-version
          cd client && npm version \$NEW_VERSION --no-git-tag-version && cd ..
          cd server && npm version \$NEW_VERSION --no-git-tag-version && cd ..
          git add package.json package-lock.json client/package.json server/package.json
          git commit -m "build: bump version to \$NEW_VERSION [skip ci]"
          git push
`);

  // === GitHub Actions Release ===
  await writeFile(join(workflowsDir, 'release.yml'), `name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip ci]')"

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: \${{ secrets.GITHUB_TOKEN }}

      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: 20.x

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Get version from package.json
        id: package-version
        run: echo "version=\$(node -p \\"require('./package.json').version\\")" >> \$GITHUB_OUTPUT

      - name: Check if tag exists
        id: tag-check
        run: |
          if git rev-parse "v\${{ steps.package-version.outputs.version }}" >/dev/null 2>&1; then
            echo "exists=true" >> \$GITHUB_OUTPUT
          else
            echo "exists=false" >> \$GITHUB_OUTPUT
          fi

      - name: Generate changelog
        id: changelog
        if: steps.tag-check.outputs.exists == 'false'
        run: |
          PREV_TAG=\$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
          CHANGELOG=\$(git log \$PREV_TAG..HEAD --pretty=format:"- %s" --no-merges | grep -v "\\[skip ci\\]" | head -50)
          echo "changelog<<EOF" >> \$GITHUB_OUTPUT
          echo "\$CHANGELOG" >> \$GITHUB_OUTPUT
          echo "EOF" >> \$GITHUB_OUTPUT

      - name: Create Release
        if: steps.tag-check.outputs.exists == 'false'
        uses: softprops/action-gh-release@v2
        with:
          tag_name: v\${{ steps.package-version.outputs.version }}
          name: v\${{ steps.package-version.outputs.version }}
          body: |
            ## Changes

            \${{ steps.changelog.outputs.changelog }}
          draft: false
          prerelease: false
        env:
          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}

      - name: Prep dev branch for next release
        if: steps.tag-check.outputs.exists == 'false'
        run: |
          CURRENT_VERSION=\${{ steps.package-version.outputs.version }}
          MAJOR=\$(echo \$CURRENT_VERSION | cut -d. -f1)
          MINOR=\$(echo \$CURRENT_VERSION | cut -d. -f2)
          NEW_MINOR=\$((MINOR + 1))
          NEW_VERSION="\$MAJOR.\$NEW_MINOR.0"
          git fetch origin dev
          git checkout dev
          npm version \$NEW_VERSION --no-git-tag-version
          cd client && npm version \$NEW_VERSION --no-git-tag-version && cd ..
          cd server && npm version \$NEW_VERSION --no-git-tag-version && cd ..
          git add package.json package-lock.json client/package.json server/package.json
          git commit -m "build: prep v\$NEW_VERSION for next release [skip ci]"
          git push origin dev
`);

  addStep('Create GitHub Actions', 'done');

  // === AGENTS.md (+ the Claude Code bridge) ===
  await writeAgentInstructions(repoPath, `# AGENTS.md

This file provides guidance to AI coding agents working with code in this repository.

## Commands

\`\`\`bash
# Install all dependencies
npm run install:all

# Development (both server and client)
npm run dev

# Run tests
cd server && npm test

# Production
pm2 start ecosystem.config.cjs
\`\`\`

## Architecture

${name} is a monorepo with Express.js server (port ${apiPort || 3001}) and React/Vite client (port ${uiPort || 3000}). PM2 manages app lifecycles.

### Server (\`server/\`)
- **index.js**: Express server with Socket.IO and AI toolkit integration

### Client (\`client/src/\`)
- **App.jsx**: Main component with routing and collapsible nav
- **main.jsx**: React entry point

### AI Provider Integration

This project includes \`portos-ai-toolkit\` for AI provider management. The server exposes:
- \`GET/POST /api/providers\` - Manage AI providers (CLI or API-based)
- \`GET/POST /api/runs\` - Execute and track AI runs
- \`GET/POST /api/prompts\` - Manage prompt templates

Provider data is stored in \`./data/providers.json\`.

## Code Conventions

- **No try/catch** - errors bubble to centralized middleware
- **Functional programming** - no classes, use hooks in React
- **Single-line logging** - use emoji prefixes

## Git Workflow

- **dev**: Active development (auto-bumps patch on CI pass)
- **main**: Production releases only
`);

  // === README.md ===
  await writeFile(join(repoPath, 'README.md'), `# ${name}

Built with PortOS Stack.

## Quick Start

\`\`\`bash
npm run install:all
npm run dev
\`\`\`

## Architecture

- **Client**: React + Vite + Tailwind (port ${uiPort || 3000})
- **Server**: Express + Socket.IO (port ${apiPort || 3001})
- **AI**: portos-ai-toolkit for provider management
- **PM2**: Process management
- **CI/CD**: GitHub Actions

## API Endpoints

- \`GET /api/health\` - Health check
- \`GET/POST /api/providers\` - AI provider management
- \`GET/POST /api/runs\` - AI execution runs
- \`GET/POST /api/prompts\` - Prompt templates

## Scripts

| Command | Description |
|---------|-------------|
| \`npm run dev\` | Start both client and server |
| \`npm run build\` | Build client for production |
| \`npm test\` | Run server tests |
`);

  addStep('Create documentation', 'done');
}