From ee72ce398f817338914b604acec5fc8bbe95b6d7 Mon Sep 17 00:00:00 2001 From: Forge Date: Sat, 4 Apr 2026 03:25:04 -0700 Subject: [PATCH 1/3] docs: add README/SPEC/PLAN --- PLAN.md | 68 ++++++++++++ SPEC.md | 331 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 399 insertions(+) create mode 100644 PLAN.md create mode 100644 SPEC.md diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 00000000..1511ca46 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,68 @@ +# BytePort — PLAN.md + +## Implementation Roadmap + +### Phase 1: Foundation (Weeks 1-2) + +| Task | Description | Deliverable | +|------|-------------|-------------| +| P1.1 | Go project setup | Module structure, build scripts | +| P1.2 | NVMS parser | Manifest validation, transformation | +| P1.3 | AWS SDK setup | Credentials, base client | +| P1.4 | Frontend shell | UI framework, routing | + +### Phase 2: NanoVMS Core (Weeks 3-4) + +| Task | Description | Deliverable | +|------|-------------|-------------| +| P2.1 | SpinCLI integration | VM creation, management | +| P2.2 | MicroVM images | Build pipeline, base images | +| P2.3 | Networking | VPC, security groups | +| P2.4 | VM lifecycle | Start, stop, health checks | + +### Phase 3: Deploy Engine (Weeks 5-6) + +| Task | Description | Deliverable | +|------|-------------|-------------| +| P3.1 | Git integration | Repo clone, branch checkout | +| P3.2 | Service discovery | Multi-service apps | +| P3.3 | Environment config | Env var injection | +| P3.4 | Deploy pipeline | End-to-end flow | + +### Phase 4: Portfolio Generation (Weeks 7-8) + +| Task | Description | Deliverable | +|------|-------------|-------------| +| P4.1 | LLM integration | OpenAI + LLaMA backends | +| P4.2 | Screenshot capture | Puppeteer/Playwright | +| P4.3 | Template system | Page generation | +| P4.4 | Portfolio hosting | S3 + CloudFront | + +### Phase 5: Polish (Weeks 9-10) + +| Task | Description | Deliverable | +|------|-------------|-------------| +| P5.1 | UI completion | Dashboard, deploy wizard | +| P5.2 | Error handling | Retry, rollback, alerts | +| P5.3 | Testing | Unit, integration tests | +| P5.4 | Documentation | User guide, API docs | + +--- + +## Resources + +| Role | Allocation | +|------|------------| +| Backend Engineer | 2 FTE | +| Frontend Engineer | 1 FTE | +| DevOps Engineer | 0.5 FTE | + +--- + +## Success Criteria + +- [ ] Deploy from GitHub in <5 minutes +- [ ] Multi-service app support +- [ ] Auto-generated portfolio pages +- [ ] 99.9% deployed app uptime +- [ ] Zero-downtime redeploys diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 00000000..a3d33712 --- /dev/null +++ b/SPEC.md @@ -0,0 +1,331 @@ +# BytePort — SPEC.md + +## Overview + +BytePort is an Infrastructure-as-Code (IaC) deployment platform combined with portfolio UX generation. Developers define applications and AWS infrastructure in a single NVMS manifest; BytePort deploys to AWS and automatically generates portfolio site components showcasing deployed projects. + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ BytePort │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Management UI │ │ +│ │ (Frontend - Web Interface for Deployment Management) │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │ │ +│ │ │ Dashboard │ │ Deploy │ │ Portfolio │ │ │ +│ │ │ (Status) │ │ Wizard │ │ Preview │ │ │ +│ │ └─────────────┘ └─────────────┘ └──────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────┴──────────────────────────────┐ │ +│ │ ByteBridge API (Go) │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ Manifest │ │ Deploy │ │ Portfolio │ │ │ +│ │ │ Parser │ │ Engine │ │ Generator │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ • Validate │ │ • AWS SDK │ │ • LLM │ │ │ +│ │ │ • Transform│ │ • NanoVMS │ │ • Templates│ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────┴──────────────────────────────┐ │ +│ │ NanoVMS Layer │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ MicroVM Orchestration │ │ │ +│ │ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ +│ │ │ │ VM 1 │ │ VM 2 │ │ VM 3 │ │ VM N │ │ │ │ +│ │ │ │(App A) │ │(App B) │ │(App C) │ │(App N) │ │ │ │ +│ │ │ └────────┘ └────────┘ └────────┘ └────────┘ │ │ │ +│ │ │ Lightweight, isolated VMs │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌───────────────────────────┴──────────────────────────────┐ │ +│ │ AWS Infrastructure │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ EC2 │ │ ECS │ │ Lambda │ │ │ +│ │ │ (Compute) │ │(Containers)│ │ (Serverless)│ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Components + +### Core Components + +| Component | Responsibility | Interface | +|-----------|----------------|-----------| +| `ManifestParser` | NVMS manifest validation | `Parse(manifest []byte) (*DeploymentConfig, error)` | +| `DeployEngine` | AWS resource provisioning | `Deploy(config *DeploymentConfig) (*Deployment, error)` | +| `NanoVMSManager` | MicroVM lifecycle | `CreateVM(spec VMSpec) (*VM, error)` | +| `PortfolioGenerator` | UX template generation | `Generate(project *Project) (*PortfolioPage, error)` | +| `LLMBackend` | Template text generation | `GenerateDescription(project Project) (string, error)` | + +### NVMS Manifest Format + +```yaml +# odin.nvms - Example manifest +NAME: my-app +DESCRIPTION: A web application for task management + +SERVICES: + - NAME: "main" + PATH: "./frontend" + PORT: 8080 + ENV: + - API_URL=http://localhost:8081 + + - NAME: "backend" + PATH: "./backend" + PORT: 8081 + ENV: + - DATABASE_URL=postgres://localhost/mydb + +INFRASTRUCTURE: + compute: ec2 # or ecs, lambda + region: us-east-1 + instance_type: t3.micro + +PORTFOLIO: + generate_page: true + screenshots: auto # auto-capture on deploy + description_source: llm # or readme, manual +``` + +--- + +## Data Models + +### Deployment Configuration + +```go +type DeploymentConfig struct { + Name string `yaml:"NAME"` + Description string `yaml:"DESCRIPTION"` + Services []Service `yaml:"SERVICES"` + Infra Infrastructure `yaml:"INFRASTRUCTURE"` + Portfolio PortfolioConfig `yaml:"PORTFOLIO"` +} + +type Service struct { + Name string `yaml:"NAME"` + Path string `yaml:"PATH"` + Port int `yaml:"PORT"` + Env map[string]string `yaml:"ENV"` +} + +type Infrastructure struct { + Compute string `yaml:"compute"` + Region string `yaml:"region"` + InstanceType string `yaml:"instance_type"` +} +``` + +### Deployment State + +```go +type Deployment struct { + ID string + Name string + Status DeploymentStatus + Services []ServiceStatus + VM *VMInfo + URL string + PortfolioURL string + CreatedAt time.Time + UpdatedAt time.Time +} + +type DeploymentStatus string +const ( + StatusPending DeploymentStatus = "PENDING" + StatusPreparing DeploymentStatus = "PREPARING" + StatusDeploying DeploymentStatus = "DEPLOYING" + StatusRunning DeploymentStatus = "RUNNING" + StatusFailed DeploymentStatus = "FAILED" + StatusTerminated DeploymentStatus = "TERMINATED" +) +``` + +### Portfolio Page + +```go +type PortfolioPage struct { + ProjectID string + Title string + Description string + ScreenshotURLs []string + DeployURL string + RepoURL string + TechStack []string + GeneratedAt time.Time +} +``` + +--- + +## Stack + +| Layer | Technology | Notes | +|-------|-----------|-------| +| Backend | Go | Deployment engine | +| Frontend | Web (vanilla/Svelte) | Management UI | +| IaC Format | NVMS | Custom YAML-based | +| Cloud | AWS | EC2 primary, ECS/Lambda optional | +| Virtualization | NanoVMS | Custom MicroVM platform | +| LLM | OpenAI / LLaMA | Template generation | +| CLI | SpinCLI | VM management tool | + +--- + +## API Contract + +### Deploy Application + +``` +POST /api/v1/deployments +Content-Type: application/json + +Request: +{ + "repo_url": "https://github.com/user/repo", + "branch": "main", + "manifest_path": "odin.nvms", + "name": "my-app" +} + +Response: 202 Accepted +{ + "deployment_id": "dep_abc123", + "status": "PENDING", + "stream_url": "/api/v1/deployments/dep_abc123/stream" +} +``` + +### Get Deployment Status + +``` +GET /api/v1/deployments/:id + +Response: 200 OK +{ + "id": "dep_abc123", + "name": "my-app", + "status": "RUNNING", + "services": [ + {"name": "main", "status": "healthy", "url": "http://..."}, + {"name": "backend", "status": "healthy", "url": "http://..."} + ], + "vm": { + "id": "vm_xyz789", + "ip": "3.91.42.100", + "status": "running" + }, + "portfolio_url": "https://portfolio.example.com/projects/my-app" +} +``` + +### Generate Portfolio Page + +``` +POST /api/v1/portfolio/generate + +Request: +{ + "deployment_id": "dep_abc123", + "options": { + "include_screenshots": true, + "description_source": "llm", + "template": "modern" + } +} + +Response: 200 OK +{ + "page_url": "https://portfolio.example.com/projects/my-app", + "generated_description": "A task management application built with...", + "screenshots": [ + "https://cdn.example.com/screenshots/my-app-1.png" + ] +} +``` + +--- + +## NanoVMS Integration + +| Feature | Implementation | +|---------|----------------| +| VM Creation | SpinCLI + Firecracker | +| Image Building | Dockerfile → MicroVM image | +| Networking | VPC + Security groups | +| Storage | EBS volumes per VM | +| Scaling | Horizontal VM pools | + +### VM Lifecycle + +``` +Create → Configure → Start → Health Check → Register + ↓ ↓ ↓ ↓ ↓ + └────────┴─────────┴──────────┴──────────────┘ + ↓ + Running + ↓ + ┌──────────────────┼──────────────────┐ + ↓ ↓ ↓ + Update Terminate Snapshot +``` + +--- + +## Performance + +| Metric | Target | Measurement | +|--------|--------|-------------| +| Deploy latency | <5 min | Repo pull to running | +| VM cold start | <2s | NanoVMS boot time | +| Portfolio generation | <30s | LLM + screenshots | +| Concurrent deploys | 10+ | Per BytePort instance | +| Uptime SLA | 99.9% | Deployed applications | + +--- + +## Project Structure + +``` +BytePort/ +├── backend/ +│ ├── byteport/ # Core deployment engine +│ │ ├── cmd/ # CLI commands +│ │ ├── pkg/ +│ │ │ ├── manifest/ # NVMS parser +│ │ │ ├── deploy/ # AWS deployment +│ │ │ ├── nanovms/ # VM management +│ │ │ └── portfolio/ # UX generation +│ │ └── main.go # Entry point +│ └── bytebridge/ # Integration layer +│ ├── api/ # REST handlers +│ ├── middleware/ # Auth, logging +│ └── server.go # HTTP server +├── frontend/ # Management UI +│ ├── src/ +│ └── public/ +├── odin.nvms # Example manifest +└── start # Local dev script +``` + +--- + +## References + +- [AWS SDK for Go](https://aws.github.io/aws-sdk-go-v2/) +- [Firecracker MicroVMs](https://firecracker-microvm.github.io/) +- [SpinCLI Documentation](https://developer.fermyon.com/spin) +- [NVMS Manifest Spec](./docs/NVMS_SPEC.md) From 51cfb285e37ffab80bec2e1b36fad6d0609d1c64 Mon Sep 17 00:00:00 2001 From: Forge Date: Sat, 4 Apr 2026 03:46:45 -0700 Subject: [PATCH 2/3] ci(legacy-enforcement): add legacy tooling anti-pattern gate (WARN mode) Adds legacy-tooling-gate.yml monitoring per CLAUDE.md Technology Adoption Philosophy. Refs: phenotype/repos/tooling/legacy-enforcement/ --- .github/workflows/legacy-tooling-gate.yml | 102 ++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 .github/workflows/legacy-tooling-gate.yml diff --git a/.github/workflows/legacy-tooling-gate.yml b/.github/workflows/legacy-tooling-gate.yml new file mode 100644 index 00000000..d4936626 --- /dev/null +++ b/.github/workflows/legacy-tooling-gate.yml @@ -0,0 +1,102 @@ +name: Legacy Tooling Gate (WARN Mode) + +on: + push: + branches: [main, master, develop] + pull_request: + branches: [main, master] + workflow_dispatch: + +jobs: + legacy-tooling-scan: + name: Legacy Tooling Anti-Pattern Scan + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + pull-requests: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Checkout phenotype/repos for shared tools + uses: actions/checkout@v4 + with: + repository: kooshapari/phenotype + path: phenotype-repos + sparse-checkout: tooling/legacy-enforcement + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: pip install pyyaml + + - name: Run Legacy Tooling Scanner (WARN Mode) + run: | + python3 phenotype-repos/tooling/legacy-enforcement/scanner/legacy_tooling_scanner.py \ + --repo-root . \ + --policy phenotype-repos/tooling/legacy-enforcement/policy/rules.yaml \ + --output-json legacy_tooling_report.json \ + --output-md legacy_tooling_report.md \ + --report-only + continue-on-error: true + + - name: Upload scan report (JSON) + uses: actions/upload-artifact@v4 + with: + name: legacy-tooling-report-json + path: legacy_tooling_report.json + retention-days: 30 + + - name: Upload scan report (Markdown) + uses: actions/upload-artifact@v4 + with: + name: legacy-tooling-report-md + path: legacy_tooling_report.md + retention-days: 30 + + - name: Comment PR with findings + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + let report = '**Legacy Tooling Scan Report**\n\n'; + + try { + const data = JSON.parse(fs.readFileSync('legacy_tooling_report.json', 'utf8')); + const totals = data.totals || {}; + + report += `| Severity | Count |\n|----------|-------|\n`; + report += `| Critical | ${totals.critical || 0} |\n`; + report += `| High | ${totals.high || 0} |\n`; + report += `| Medium | ${totals.medium || 0} |\n`; + report += `| Low | ${totals.low || 0} |\n\n`; + + const findings = data.findings || []; + if (findings.length > 0) { + report += '**Top Violations:**\n'; + findings.slice(0, 5).forEach(f => { + report += `- [${f.severity.toUpperCase()}] ${f.rule_id}: ${f.file}:${f.line}\n`; + }); + if (findings.length > 5) { + report += `- ... and ${findings.length - 5} more\n`; + } + } else { + report += 'No violations detected.\n'; + } + + report += '\n*This is a WARN-mode scan. Fix before strict enforcement begins.*'; + } catch (e) { + report += 'Could not parse scan results.'; + } + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: report + }); From 3500efe4ecfa1e6565ea6d0ab759028e9308be00 Mon Sep 17 00:00:00 2001 From: Forge Date: Sun, 5 Apr 2026 21:09:01 -0700 Subject: [PATCH 3/3] ci: add reusable phenotype workflows --- VERSION | 1 + 1 file changed, 1 insertion(+) create mode 100644 VERSION diff --git a/VERSION b/VERSION new file mode 100644 index 00000000..6e8bf73a --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0