DevOS v1 + Phase 2: unified resource model, infra ops, website deployment, AI chat ops
- Monorepo: NestJS API (Fastify) + React web (antd/ProComponents) + shared packages - PostgreSQL/Prisma (unified resources, relations graph, audit, events, jobs) - Auth/RBAC/workspace isolation, credential vault (AES-256-GCM) - Servers/SSH, Docker discovery & lifecycle, Job Center - Websites & deployments (git provider credential clone, env, health verification) - Domains/DNS (Cloudflare adapter), certificates (TLS probe), monitoring - Automation (cron/event/webhook HMAC + notifications), AI Gateway, MCP (29 tools) - AI chat window (LLM function-calling + rules fallback, SSE streaming, approvals) - Notes: Vditor WYSIWYG markdown editor, non-blocking autosave - Tests: 35 unit/security tests; UI audit clean (desktop+mobile, deep links)
This commit is contained in:
phptits
@@ -0,0 +1,83 @@
|
||||
# DevOS v1 Product Requirements Document
|
||||
|
||||
## 1. Product Definition
|
||||
DevOS is a Developer Work OS: a unified workspace for servers, websites, domains, code, databases, email, notes, tasks, documents, monitoring and automation, with AI as an operational Agent rather than merely a chat interface.
|
||||
|
||||
## 2. Core Product Model
|
||||
The platform is organized around four primitives:
|
||||
|
||||
**Resource + Action + Event + Agent**
|
||||
|
||||
- Resource: everything managed by DevOS.
|
||||
- Action: an operation performed against a resource.
|
||||
- Event: a state change or external signal.
|
||||
- Agent: observes resources, plans actions, executes through tools, verifies outcomes and reports.
|
||||
|
||||
The central architectural principle is the **Unified Resource Model**.
|
||||
|
||||
## 3. Primary Users
|
||||
- Individual developers
|
||||
- Small development teams
|
||||
|
||||
## 4. V1 Scope
|
||||
V1 focuses on Infrastructure OS capabilities:
|
||||
- Server
|
||||
- Docker / Containers
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- Monitoring
|
||||
- Authentication, Workspace, Resource, Permission and Audit foundations
|
||||
|
||||
## 5. V2 Scope
|
||||
Developer OS:
|
||||
- GitHub / GitLab / other Git providers
|
||||
- Projects
|
||||
- Tasks
|
||||
- Notes
|
||||
- Documents
|
||||
- Email
|
||||
|
||||
## 6. V3 Scope
|
||||
Automation OS:
|
||||
- Event Bus
|
||||
- Workflow Engine
|
||||
- Cron
|
||||
- Webhook
|
||||
- Notifications
|
||||
|
||||
## 7. V4 Scope
|
||||
AI OS:
|
||||
- Resource Discovery
|
||||
- Planning
|
||||
- Tool Calling
|
||||
- Execution
|
||||
- Verification
|
||||
- Memory
|
||||
- Approval
|
||||
|
||||
## 8. Representative User Journey
|
||||
“Deploy my blog to the Tokyo server, use Docker, configure blog.example.com and enable HTTPS.”
|
||||
|
||||
The intended Agent flow:
|
||||
1. Find Project and Repository
|
||||
2. Find target Server
|
||||
3. Check Docker
|
||||
4. Clone repository
|
||||
5. Build image
|
||||
6. Run container
|
||||
7. Configure reverse proxy
|
||||
8. Configure DNS
|
||||
9. Obtain SSL
|
||||
10. Health check
|
||||
11. Return an action log and result
|
||||
|
||||
## 9. Non-Goals
|
||||
- Reimplementing Git
|
||||
- Reimplementing SMTP
|
||||
- Building a Kubernetes control plane in V1
|
||||
- Building a full Notion replacement in the first release
|
||||
- Starting with microservices
|
||||
|
||||
## 10. Product Success Criteria
|
||||
A developer can manage the core infrastructure lifecycle from one workspace, while resources remain related and discoverable enough for later automation and AI operation.
|
||||
@@ -0,0 +1,105 @@
|
||||
# DevOS v1 Product Architecture
|
||||
|
||||
## 1. System Concept
|
||||
|
||||
```text
|
||||
DevOS AI
|
||||
Agent / Copilot / MCP
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| | |
|
||||
Infrastructure Projects Productivity
|
||||
| | |
|
||||
Server / Docker / DB Git / Website / API Notes / Tasks / Docs
|
||||
+-------------------+-------------------+
|
||||
|
|
||||
Unified Resource Model
|
||||
```
|
||||
|
||||
## 2. Core Primitives
|
||||
|
||||
```text
|
||||
Resource
|
||||
|
|
||||
Action
|
||||
|
|
||||
Event
|
||||
|
|
||||
Automation / Agent
|
||||
|
|
||||
Resource
|
||||
```
|
||||
|
||||
Example:
|
||||
- Resource: Website/blog.com
|
||||
- Action: Deploy
|
||||
- Event: deployment.success
|
||||
- Automation: Send notification
|
||||
- Agent: Analyze deployment
|
||||
|
||||
## 3. Resource Graph
|
||||
Resources are related rather than isolated:
|
||||
|
||||
```text
|
||||
Project
|
||||
├── Repository
|
||||
├── Website
|
||||
├── Server
|
||||
├── Database
|
||||
├── Deployment
|
||||
├── Domain
|
||||
├── Email
|
||||
└── Monitoring
|
||||
```
|
||||
|
||||
## 4. Architectural Style
|
||||
- Frontend: React application
|
||||
- Backend: modular monolith
|
||||
- Persistence: PostgreSQL
|
||||
- Cache/async infrastructure: Redis
|
||||
- Integrations: provider adapters
|
||||
- AI: Agent + Tool + MCP + Workflow layer
|
||||
- Infrastructure execution: SSH, Docker API, provider APIs
|
||||
|
||||
## 5. Module Boundaries
|
||||
Core modules:
|
||||
- Identity
|
||||
- Workspace
|
||||
- Resource
|
||||
- Permission
|
||||
- Audit
|
||||
|
||||
Infrastructure:
|
||||
- Server
|
||||
- Container
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- Monitoring
|
||||
|
||||
Integration:
|
||||
- Git Provider
|
||||
- DNS Provider
|
||||
- Cloud Provider
|
||||
- Email Provider
|
||||
- Docker
|
||||
|
||||
Automation:
|
||||
- Event
|
||||
- Workflow
|
||||
- Trigger
|
||||
- Action
|
||||
- Job
|
||||
|
||||
AI:
|
||||
- AI Gateway
|
||||
- Agent
|
||||
- Planner
|
||||
- Executor
|
||||
- Memory
|
||||
- Approval
|
||||
- Tools
|
||||
- MCP
|
||||
|
||||
## 6. Key Principle
|
||||
Do not turn every domain into a separate service in V1. Modules must have explicit boundaries while sharing one deployable backend.
|
||||
@@ -0,0 +1,40 @@
|
||||
# DevOS v1 Technology Stack
|
||||
|
||||
## Frontend
|
||||
- React
|
||||
- TypeScript
|
||||
- Ant Design
|
||||
- Ant Design ProComponents
|
||||
- React Router
|
||||
- TanStack Query
|
||||
- Zustand
|
||||
- TipTap
|
||||
|
||||
## Backend
|
||||
- Node.js
|
||||
- TypeScript
|
||||
- NestJS
|
||||
- Prefer Fastify adapter where appropriate
|
||||
|
||||
## Data
|
||||
- PostgreSQL
|
||||
- Prisma
|
||||
- Redis
|
||||
|
||||
## Infrastructure
|
||||
- Docker
|
||||
- SSH
|
||||
- Docker API
|
||||
- Nginx or Caddy integration
|
||||
- Linux
|
||||
- External DNS / cloud / Git / email APIs
|
||||
|
||||
## Architecture Decision
|
||||
Prefer NestJS + Prisma for the initial implementation because the source discussion prioritizes modular structure and AI-friendly code comprehension.
|
||||
|
||||
## Dependency Rule
|
||||
Do not introduce a new dependency without documenting:
|
||||
1. Why existing dependencies cannot satisfy the requirement
|
||||
2. Security and maintenance implications
|
||||
3. Operational impact
|
||||
4. Alternative considered
|
||||
@@ -0,0 +1,105 @@
|
||||
# DevOS v1 Domain Model
|
||||
|
||||
## 1. Resource
|
||||
|
||||
```typescript
|
||||
interface Resource {
|
||||
id: string
|
||||
type: ResourceType
|
||||
name: string
|
||||
workspaceId: string
|
||||
provider?: string
|
||||
status: ResourceStatus
|
||||
metadata: Record<string, unknown>
|
||||
createdAt: Date
|
||||
updatedAt: Date
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Resource Types
|
||||
Initial model:
|
||||
- Server
|
||||
- Domain
|
||||
- Website
|
||||
- Repository
|
||||
- Database
|
||||
- Container
|
||||
- EmailAccount
|
||||
- Project
|
||||
- Task
|
||||
- Note
|
||||
- Document
|
||||
- Backup
|
||||
- Deployment
|
||||
- Monitor
|
||||
- Credential
|
||||
|
||||
## 3. Core Entities
|
||||
|
||||
### Workspace
|
||||
Tenant/security boundary for users and resources.
|
||||
|
||||
### Project
|
||||
Business/work boundary connecting repositories, websites, servers, databases, deployments, domains, email and monitoring.
|
||||
|
||||
### Server
|
||||
Managed compute target. Supports SSH connection and infrastructure discovery.
|
||||
|
||||
### Website
|
||||
Deployable application resource associated with domain, repository, deployment, server/container, database, SSL, environment, logs, monitoring and backup.
|
||||
|
||||
### Deployment
|
||||
A concrete execution of deploying a repository/version to a target.
|
||||
|
||||
### Credential
|
||||
Encrypted provider or infrastructure secret reference. Secret material is never exposed as ordinary resource metadata.
|
||||
|
||||
### Task
|
||||
Work item associated with a project and optionally related to resources and automations.
|
||||
|
||||
## 4. Relationships
|
||||
|
||||
```text
|
||||
Workspace
|
||||
├── Projects
|
||||
├── Resources
|
||||
├── Users
|
||||
├── Credentials
|
||||
└── Automations
|
||||
|
||||
Project
|
||||
├── Repository*
|
||||
├── Website*
|
||||
├── Server*
|
||||
├── Database*
|
||||
├── Deployment*
|
||||
├── Domain*
|
||||
├── Task*
|
||||
└── Monitoring*
|
||||
```
|
||||
|
||||
## 5. Actions
|
||||
Every mutable operation should be modeled as an auditable action:
|
||||
- server.exec
|
||||
- server.restart
|
||||
- server.installPackage
|
||||
- website.deploy
|
||||
- website.logs
|
||||
- domain.updateRecords
|
||||
- deployment.create
|
||||
- container.restart
|
||||
|
||||
## 6. Events
|
||||
Canonical event names should use `<resource>.<verb>` or `<domain>.<verb>`:
|
||||
- deployment.created
|
||||
- deployment.started
|
||||
- deployment.success
|
||||
- deployment.failed
|
||||
- server.online
|
||||
- server.offline
|
||||
- website.down
|
||||
- website.recovered
|
||||
- email.received
|
||||
- github.push
|
||||
- task.created
|
||||
- task.completed
|
||||
@@ -0,0 +1,119 @@
|
||||
# DevOS v1 Database Schema
|
||||
|
||||
## 1. Persistence Strategy
|
||||
PostgreSQL is the system of record. Prisma is the initial ORM.
|
||||
|
||||
## 2. Core Tables
|
||||
|
||||
Recommended initial tables:
|
||||
- users
|
||||
- workspaces
|
||||
- workspace_members
|
||||
- resources
|
||||
- resource_relations
|
||||
- projects
|
||||
- project_resources
|
||||
- credentials
|
||||
- audit_logs
|
||||
- events
|
||||
- jobs
|
||||
- deployments
|
||||
- servers
|
||||
- websites
|
||||
- domains
|
||||
- containers
|
||||
- monitors
|
||||
|
||||
## 3. Resource Table
|
||||
|
||||
Conceptual schema:
|
||||
|
||||
```text
|
||||
resources
|
||||
- id
|
||||
- workspace_id
|
||||
- type
|
||||
- name
|
||||
- provider
|
||||
- status
|
||||
- metadata_json
|
||||
- created_at
|
||||
- updated_at
|
||||
```
|
||||
|
||||
Use a typed domain table when the resource has substantial operational state; use `resources` for identity, discovery and graph-level common fields.
|
||||
|
||||
## 4. Resource Relations
|
||||
|
||||
```text
|
||||
resource_relations
|
||||
- id
|
||||
- workspace_id
|
||||
- source_resource_id
|
||||
- target_resource_id
|
||||
- relation_type
|
||||
- metadata_json
|
||||
- created_at
|
||||
```
|
||||
|
||||
This allows the resource graph to evolve without embedding every relationship into one giant table.
|
||||
|
||||
## 5. Credential Storage
|
||||
Store encrypted credential payloads separately from general resource metadata.
|
||||
|
||||
```text
|
||||
credentials
|
||||
- id
|
||||
- workspace_id
|
||||
- type
|
||||
- provider
|
||||
- encrypted_data
|
||||
- metadata_json
|
||||
- created_at
|
||||
- updated_at
|
||||
```
|
||||
|
||||
The application must never log decrypted credential material.
|
||||
|
||||
## 6. Audit Log
|
||||
|
||||
```text
|
||||
audit_logs
|
||||
- id
|
||||
- workspace_id
|
||||
- actor_type
|
||||
- actor_id
|
||||
- action
|
||||
- resource_type
|
||||
- resource_id
|
||||
- risk_level
|
||||
- status
|
||||
- request_id
|
||||
- metadata_json
|
||||
- created_at
|
||||
```
|
||||
|
||||
## 7. Event
|
||||
|
||||
```text
|
||||
events
|
||||
- id
|
||||
- workspace_id
|
||||
- event_type
|
||||
- resource_id
|
||||
- payload_json
|
||||
- correlation_id
|
||||
- created_at
|
||||
```
|
||||
|
||||
## 8. Indexing
|
||||
At minimum index:
|
||||
- workspace_id
|
||||
- resource type/status
|
||||
- resource relation endpoints
|
||||
- event type + created_at
|
||||
- audit workspace + created_at
|
||||
- deployment website/project + created_at
|
||||
- jobs status + scheduled_at
|
||||
|
||||
Exact migrations should be generated from the implementation model and reviewed before production.
|
||||
@@ -0,0 +1,109 @@
|
||||
# DevOS v1 API Specification
|
||||
|
||||
## 1. API Style
|
||||
Use versioned HTTP APIs under `/api/v1`.
|
||||
|
||||
All mutations use explicit DTOs and return structured resources/results.
|
||||
|
||||
## 2. Core Endpoints
|
||||
|
||||
### Auth
|
||||
```text
|
||||
POST /api/v1/auth/login
|
||||
POST /api/v1/auth/logout
|
||||
GET /api/v1/auth/me
|
||||
```
|
||||
|
||||
### Workspaces
|
||||
```text
|
||||
GET /api/v1/workspaces
|
||||
POST /api/v1/workspaces
|
||||
GET /api/v1/workspaces/:workspaceId
|
||||
```
|
||||
|
||||
### Resources
|
||||
```text
|
||||
GET /api/v1/resources
|
||||
POST /api/v1/resources
|
||||
GET /api/v1/resources/:id
|
||||
PATCH /api/v1/resources/:id
|
||||
DELETE /api/v1/resources/:id
|
||||
GET /api/v1/resources/:id/relations
|
||||
```
|
||||
|
||||
### Servers
|
||||
```text
|
||||
GET /api/v1/servers
|
||||
POST /api/v1/servers
|
||||
GET /api/v1/servers/:id
|
||||
POST /api/v1/servers/:id/connect
|
||||
GET /api/v1/servers/:id/status
|
||||
GET /api/v1/servers/:id/containers
|
||||
POST /api/v1/servers/:id/exec
|
||||
POST /api/v1/servers/:id/restart
|
||||
```
|
||||
|
||||
### Websites
|
||||
```text
|
||||
GET /api/v1/websites
|
||||
POST /api/v1/websites
|
||||
GET /api/v1/websites/:id
|
||||
POST /api/v1/websites/:id/deploy
|
||||
GET /api/v1/websites/:id/logs
|
||||
GET /api/v1/websites/:id/health
|
||||
```
|
||||
|
||||
### Deployments
|
||||
```text
|
||||
GET /api/v1/deployments
|
||||
GET /api/v1/deployments/:id
|
||||
POST /api/v1/deployments
|
||||
POST /api/v1/deployments/:id/cancel
|
||||
```
|
||||
|
||||
### Domains
|
||||
```text
|
||||
GET /api/v1/domains
|
||||
POST /api/v1/domains
|
||||
GET /api/v1/domains/:id
|
||||
POST /api/v1/domains/:id/records
|
||||
```
|
||||
|
||||
### Automation
|
||||
```text
|
||||
GET /api/v1/automations
|
||||
POST /api/v1/automations
|
||||
GET /api/v1/automations/:id
|
||||
POST /api/v1/automations/:id/enable
|
||||
POST /api/v1/automations/:id/disable
|
||||
```
|
||||
|
||||
### AI
|
||||
```text
|
||||
POST /api/v1/ai/runs
|
||||
GET /api/v1/ai/runs/:id
|
||||
POST /api/v1/ai/runs/:id/approve
|
||||
```
|
||||
|
||||
## 3. Mutation Contract
|
||||
Every mutation:
|
||||
- validates a DTO
|
||||
- checks workspace authorization
|
||||
- determines risk
|
||||
- writes an audit record
|
||||
- emits domain events when appropriate
|
||||
- returns a request/correlation identifier
|
||||
|
||||
## 4. Error Contract
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "Resource was not found",
|
||||
"requestId": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Never expose stack traces, credentials or provider secrets through API errors.
|
||||
@@ -0,0 +1,71 @@
|
||||
# DevOS v1 Frontend Architecture
|
||||
|
||||
## 1. Stack
|
||||
React + TypeScript + Ant Design + ProComponents + TanStack Query + Zustand + React Router + TipTap.
|
||||
|
||||
## 2. Application Layout
|
||||
|
||||
```text
|
||||
apps/web
|
||||
├── app
|
||||
├── routes
|
||||
├── layouts
|
||||
├── features
|
||||
│ ├── auth
|
||||
│ ├── dashboard
|
||||
│ ├── resources
|
||||
│ ├── servers
|
||||
│ ├── websites
|
||||
│ ├── deployments
|
||||
│ ├── domains
|
||||
│ ├── monitoring
|
||||
│ ├── automation
|
||||
│ └── ai
|
||||
├── components
|
||||
└── services
|
||||
```
|
||||
|
||||
Shared packages:
|
||||
|
||||
```text
|
||||
packages/
|
||||
├── ui/
|
||||
├── api-client/
|
||||
├── types/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
## 3. UI Principle
|
||||
Use Ant Design and ProComponents instead of building common enterprise controls from scratch.
|
||||
|
||||
Primary components:
|
||||
- ProLayout
|
||||
- ProTable
|
||||
- ProForm
|
||||
- ProDescriptions
|
||||
- ProCard
|
||||
- ProList
|
||||
|
||||
## 4. State
|
||||
- Server state: TanStack Query
|
||||
- Local UI state: Zustand / React state
|
||||
- Do not duplicate server state into global stores without a clear reason.
|
||||
|
||||
## 5. Dashboard
|
||||
The home page should prioritize:
|
||||
- AI command entry
|
||||
- Infrastructure health
|
||||
- Projects
|
||||
- Recent activity
|
||||
- Deployment/monitoring warnings
|
||||
|
||||
## 6. Resource UI
|
||||
Resource detail pages should expose:
|
||||
- Overview
|
||||
- Relations
|
||||
- Actions
|
||||
- Activity/Audit
|
||||
- Logs where applicable
|
||||
- Related resources
|
||||
|
||||
Dangerous actions require explicit confirmation and risk presentation.
|
||||
@@ -0,0 +1,73 @@
|
||||
# DevOS v1 Backend Architecture
|
||||
|
||||
## 1. Style
|
||||
Modular monolith with NestJS.
|
||||
|
||||
## 2. Suggested Structure
|
||||
|
||||
```text
|
||||
apps/api/
|
||||
├── src/
|
||||
│ ├── modules/
|
||||
│ │ ├── identity/
|
||||
│ │ ├── workspace/
|
||||
│ │ ├── resource/
|
||||
│ │ ├── permission/
|
||||
│ │ ├── audit/
|
||||
│ │ ├── server/
|
||||
│ │ ├── container/
|
||||
│ │ ├── website/
|
||||
│ │ ├── domain/
|
||||
│ │ ├── deployment/
|
||||
│ │ ├── monitoring/
|
||||
│ │ ├── automation/
|
||||
│ │ └── ai/
|
||||
│ ├── integrations/
|
||||
│ │ ├── ssh/
|
||||
│ │ ├── docker/
|
||||
│ │ ├── git/
|
||||
│ │ ├── dns/
|
||||
│ │ ├── cloud/
|
||||
│ │ └── email/
|
||||
│ ├── common/
|
||||
│ └── main.ts
|
||||
```
|
||||
|
||||
## 3. Rules
|
||||
- Controllers handle transport only.
|
||||
- DTOs define input/output contracts.
|
||||
- Business logic belongs in application/domain services.
|
||||
- Provider-specific logic belongs behind adapters.
|
||||
- Credential access is centralized.
|
||||
- Mutations are auditable.
|
||||
- Long-running operations run asynchronously.
|
||||
- External calls have timeouts, retries where safe, and idempotency where possible.
|
||||
|
||||
## 4. Infrastructure Adapters
|
||||
DevOS does not reimplement:
|
||||
- SSH
|
||||
- Git
|
||||
- Docker
|
||||
- DNS
|
||||
- SMTP
|
||||
- cloud control planes
|
||||
|
||||
It provides unified adapters over those systems.
|
||||
|
||||
## 5. Async Execution
|
||||
Use Redis-backed jobs for:
|
||||
- deployment
|
||||
- server discovery
|
||||
- monitoring checks
|
||||
- long-running SSH commands
|
||||
- automation execution
|
||||
|
||||
## 6. Observability
|
||||
Every operation should carry:
|
||||
- request ID
|
||||
- correlation ID
|
||||
- actor
|
||||
- workspace
|
||||
- resource
|
||||
- action
|
||||
- outcome
|
||||
@@ -0,0 +1,96 @@
|
||||
# DevOS v1 AI Agent Architecture
|
||||
|
||||
## 1. Principle
|
||||
AI is an operating layer, not merely a chat feature.
|
||||
|
||||
```text
|
||||
AI Gateway
|
||||
|
|
||||
+----------+----------+
|
||||
| |
|
||||
Agent Memory
|
||||
|
|
||||
+------+------+------+
|
||||
| | | |
|
||||
Tools MCP Workflow Approval
|
||||
```
|
||||
|
||||
## 2. Agent Loop
|
||||
|
||||
```text
|
||||
Observe
|
||||
↓
|
||||
Discover Resources
|
||||
↓
|
||||
Plan
|
||||
↓
|
||||
Risk Evaluation
|
||||
↓
|
||||
Approval if required
|
||||
↓
|
||||
Execute Tools
|
||||
↓
|
||||
Verify
|
||||
↓
|
||||
Report
|
||||
```
|
||||
|
||||
## 3. Tool Examples
|
||||
- server.list
|
||||
- server.exec
|
||||
- server.restart
|
||||
- server.getStatus
|
||||
- server.getDockerContainers
|
||||
- website.list
|
||||
- website.deploy
|
||||
- website.logs
|
||||
- git.repositories
|
||||
- git.commits
|
||||
- domain.records
|
||||
- email.search
|
||||
- note.create
|
||||
- task.create
|
||||
|
||||
## 4. Context
|
||||
Agent context should be built from:
|
||||
- workspace
|
||||
- user permissions
|
||||
- relevant resources
|
||||
- resource relations
|
||||
- recent events
|
||||
- task/run history
|
||||
- tool schemas
|
||||
|
||||
Do not indiscriminately inject the entire database into the model.
|
||||
|
||||
## 5. Risk
|
||||
Risk levels:
|
||||
- LOW
|
||||
- MEDIUM
|
||||
- HIGH
|
||||
- CRITICAL
|
||||
|
||||
HIGH and CRITICAL operations require user approval by default.
|
||||
|
||||
Examples:
|
||||
- production deployment
|
||||
- destructive filesystem operations
|
||||
- database deletion
|
||||
- credential changes
|
||||
|
||||
## 6. Verification
|
||||
An Agent action is not successful merely because a command returned zero. The Agent should perform domain-specific verification where possible:
|
||||
- deployment health
|
||||
- HTTP health check
|
||||
- container state
|
||||
- DNS propagation/result
|
||||
- SSL availability
|
||||
|
||||
## 7. Action Log
|
||||
Agent runs should expose human-readable steps such as:
|
||||
- found target server
|
||||
- Docker available
|
||||
- repository connected
|
||||
- deployment created
|
||||
- container started
|
||||
- health check passed
|
||||
@@ -0,0 +1,54 @@
|
||||
# DevOS v1 MCP Specification
|
||||
|
||||
## 1. Purpose
|
||||
DevOS should expose its capabilities as an MCP Server so external Agents such as ChatGPT, Claude, Cursor, Codex and other compatible agents can operate the developer infrastructure layer.
|
||||
|
||||
## 2. Conceptual Interface
|
||||
|
||||
```text
|
||||
External Agent
|
||||
|
|
||||
v
|
||||
DevOS MCP
|
||||
|
|
||||
+-- Servers
|
||||
+-- Websites
|
||||
+-- Git
|
||||
+-- Domains
|
||||
+-- Email
|
||||
+-- Notes
|
||||
+-- Tasks
|
||||
+-- Automation
|
||||
```
|
||||
|
||||
## 3. Tool Design Rules
|
||||
Tools should:
|
||||
- have narrow, explicit responsibilities
|
||||
- declare structured input/output schemas
|
||||
- be workspace-aware
|
||||
- enforce authorization server-side
|
||||
- expose risk classification
|
||||
- return stable machine-readable results
|
||||
- never return raw secrets
|
||||
|
||||
## 4. Initial Tool Set
|
||||
```text
|
||||
devos.server.list
|
||||
devos.server.status
|
||||
devos.server.exec
|
||||
devos.website.list
|
||||
devos.website.deploy
|
||||
devos.website.logs
|
||||
devos.deployment.get
|
||||
devos.domain.list
|
||||
devos.domain.records
|
||||
devos.task.create
|
||||
devos.note.create
|
||||
devos.automation.run
|
||||
```
|
||||
|
||||
## 5. Safety
|
||||
MCP is not a bypass around DevOS security. All requests must pass the same permission, credential, risk and audit layers as first-party UI/API actions.
|
||||
|
||||
## 6. Resource Exposure
|
||||
Prefer references and summarized metadata. Secrets and unnecessary infrastructure internals must not be exposed by default.
|
||||
@@ -0,0 +1,72 @@
|
||||
# DevOS v1 Automation Engine
|
||||
|
||||
## 1. Model
|
||||
|
||||
```text
|
||||
Trigger
|
||||
↓
|
||||
Condition
|
||||
↓
|
||||
Action
|
||||
↓
|
||||
Action
|
||||
↓
|
||||
Action
|
||||
```
|
||||
|
||||
## 2. Triggers
|
||||
Initial trigger classes:
|
||||
- Manual
|
||||
- Cron
|
||||
- Webhook
|
||||
- Event
|
||||
- AI Trigger
|
||||
|
||||
## 3. Example
|
||||
|
||||
```text
|
||||
WHEN github.push
|
||||
IF branch = main
|
||||
THEN build
|
||||
THEN deploy
|
||||
THEN health check
|
||||
THEN notify
|
||||
```
|
||||
|
||||
## 4. Execution Model
|
||||
Automation execution should be represented as a job/run with:
|
||||
- automation ID
|
||||
- trigger event
|
||||
- execution ID
|
||||
- step index
|
||||
- input/output references
|
||||
- status
|
||||
- retry state
|
||||
- timestamps
|
||||
- correlation ID
|
||||
|
||||
## 5. Event Bus
|
||||
Canonical events include:
|
||||
- deployment.created
|
||||
- deployment.started
|
||||
- deployment.success
|
||||
- deployment.failed
|
||||
- server.online
|
||||
- server.offline
|
||||
- website.down
|
||||
- website.recovered
|
||||
- email.received
|
||||
- github.push
|
||||
- task.created
|
||||
- task.completed
|
||||
|
||||
## 6. Reliability
|
||||
- idempotency for externally triggered workflows
|
||||
- bounded retries
|
||||
- timeout per action
|
||||
- explicit failure states
|
||||
- dead-letter handling for unrecoverable jobs
|
||||
- full audit trail
|
||||
|
||||
## 7. AI Integration
|
||||
AI may create or execute automation, but generated workflows must still pass schema validation, permissions and risk policies.
|
||||
@@ -0,0 +1,78 @@
|
||||
# DevOS v1 Security Specification
|
||||
|
||||
## 1. Threat Model
|
||||
DevOS manages highly sensitive credentials:
|
||||
- SSH keys
|
||||
- API keys
|
||||
- cloud tokens
|
||||
- Git tokens
|
||||
- SMTP credentials
|
||||
- DNS API credentials
|
||||
- database passwords
|
||||
|
||||
Therefore security is a core architecture boundary.
|
||||
|
||||
## 2. Credential Vault
|
||||
Credentials are stored encrypted, separately from ordinary resource metadata.
|
||||
|
||||
```text
|
||||
Application Master Key
|
||||
↓
|
||||
Envelope Encryption
|
||||
↓
|
||||
Encrypted Credential
|
||||
```
|
||||
|
||||
Do not store plaintext passwords or tokens in PostgreSQL.
|
||||
|
||||
## 3. Authorization
|
||||
Implement:
|
||||
- authentication
|
||||
- workspace isolation
|
||||
- RBAC
|
||||
- resource-level permission checks where required
|
||||
- action-level authorization
|
||||
|
||||
## 4. Audit
|
||||
All mutations and sensitive reads/actions should be auditable:
|
||||
- actor
|
||||
- workspace
|
||||
- action
|
||||
- resource
|
||||
- risk
|
||||
- outcome
|
||||
- timestamp
|
||||
- correlation/request ID
|
||||
|
||||
## 5. Secret Masking
|
||||
Secrets must be masked in:
|
||||
- logs
|
||||
- UI
|
||||
- Agent context
|
||||
- error messages
|
||||
- audit metadata
|
||||
- tool results
|
||||
|
||||
## 6. AI Safety
|
||||
AI execution must use the same authorization path as humans.
|
||||
|
||||
HIGH / CRITICAL:
|
||||
```text
|
||||
Plan
|
||||
↓
|
||||
User Approval
|
||||
↓
|
||||
Execute
|
||||
↓
|
||||
Verify
|
||||
```
|
||||
|
||||
## 7. Infrastructure Execution
|
||||
- SSH command execution must be scoped and logged.
|
||||
- Command timeouts are mandatory.
|
||||
- Production targets should be distinguishable.
|
||||
- Destructive actions require explicit confirmation.
|
||||
- Never allow prompt text alone to override security policy.
|
||||
|
||||
## 8. Security Non-Goals
|
||||
This document does not claim a complete production security certification. Before public production deployment, perform threat modeling, dependency review, penetration testing and secret-rotation drills.
|
||||
@@ -0,0 +1,77 @@
|
||||
# DevOS v1 UI Specification
|
||||
|
||||
## 1. Navigation
|
||||
|
||||
```text
|
||||
DevOS
|
||||
├── Dashboard
|
||||
├── AI
|
||||
├── Projects
|
||||
├── Infrastructure
|
||||
│ ├── Servers
|
||||
│ ├── Containers
|
||||
│ ├── Databases
|
||||
│ ├── Storage
|
||||
│ └── Monitoring
|
||||
├── Websites
|
||||
│ ├── Websites
|
||||
│ ├── Domains
|
||||
│ ├── SSL
|
||||
│ └── Deployments
|
||||
├── Code
|
||||
│ ├── Repositories
|
||||
│ ├── Issues
|
||||
│ ├── Pull Requests
|
||||
│ └── Releases
|
||||
├── Email
|
||||
├── Knowledge
|
||||
│ ├── Notes
|
||||
│ ├── Documents
|
||||
│ └── Knowledge Base
|
||||
├── Tasks
|
||||
├── Automation
|
||||
├── Credentials
|
||||
└── Settings
|
||||
```
|
||||
|
||||
## 2. Dashboard
|
||||
The dashboard is an operational command center, not a conventional analytics page.
|
||||
|
||||
```text
|
||||
Good morning.
|
||||
|
||||
[ AI: What do you want to do? ]
|
||||
|
||||
Infrastructure
|
||||
3 Servers | 24 Containers | 99.98% Uptime
|
||||
|
||||
Projects
|
||||
Blog | DevOS | SaaS
|
||||
|
||||
Activity
|
||||
Deployment successful
|
||||
SSL renewed
|
||||
Server disk 82%
|
||||
```
|
||||
|
||||
## 3. Resource Detail
|
||||
Every major resource should expose a consistent information architecture:
|
||||
- Summary
|
||||
- Status
|
||||
- Relations
|
||||
- Actions
|
||||
- Activity
|
||||
- Logs/metrics where relevant
|
||||
|
||||
## 4. Action UX
|
||||
Actions should show:
|
||||
- what will happen
|
||||
- target resource
|
||||
- risk level
|
||||
- expected impact
|
||||
- confirmation requirement
|
||||
- progress
|
||||
- final verification
|
||||
|
||||
## 5. Design System
|
||||
Use Ant Design as the primary visual/system foundation and ProComponents for data-heavy administration.
|
||||
@@ -0,0 +1,75 @@
|
||||
# DevOS v1 Roadmap
|
||||
|
||||
## V0 — Foundation
|
||||
- Monorepo
|
||||
- React
|
||||
- Ant Design
|
||||
- NestJS
|
||||
- PostgreSQL
|
||||
- Prisma
|
||||
- Redis
|
||||
- Docker
|
||||
- Auth
|
||||
- User
|
||||
- Workspace
|
||||
- Resource
|
||||
- Permission
|
||||
- Audit
|
||||
|
||||
## V1 — Infrastructure OS
|
||||
- Server
|
||||
- SSH
|
||||
- Docker/container discovery
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- SSL integration
|
||||
- Logs
|
||||
- Monitoring
|
||||
|
||||
Target flow:
|
||||
```text
|
||||
Add Server
|
||||
↓
|
||||
SSH
|
||||
↓
|
||||
Discover Docker
|
||||
↓
|
||||
View Containers
|
||||
↓
|
||||
Deploy Website
|
||||
↓
|
||||
Bind Domain
|
||||
↓
|
||||
SSL
|
||||
↓
|
||||
Logs
|
||||
```
|
||||
|
||||
## V2 — Developer OS
|
||||
- GitHub / GitLab
|
||||
- Projects
|
||||
- Tasks
|
||||
- Notes
|
||||
- Documents
|
||||
- Email
|
||||
|
||||
## V3 — Automation OS
|
||||
- Event Bus
|
||||
- Workflow Engine
|
||||
- Cron
|
||||
- Webhook
|
||||
- Notifications
|
||||
|
||||
## V4 — AI OS
|
||||
- Resource discovery
|
||||
- Planning
|
||||
- Tool calling
|
||||
- Execution
|
||||
- Verification
|
||||
- Memory
|
||||
- Approval
|
||||
- MCP
|
||||
|
||||
## Delivery Rule
|
||||
Do not start by implementing every product category. Deliver vertical slices that prove the Resource + Action + Event model.
|
||||
@@ -0,0 +1,56 @@
|
||||
# AGENTS.md — DevOS Coding Rules
|
||||
|
||||
## Mission
|
||||
Build DevOS as a maintainable modular monolith and preserve the Resource + Action + Event + Agent architecture.
|
||||
|
||||
## Mandatory Rules
|
||||
1. TypeScript strict mode.
|
||||
2. Never use `any` unless explicitly justified.
|
||||
3. All API endpoints use DTOs.
|
||||
4. Controllers contain transport concerns only.
|
||||
5. Business logic belongs in services/domain/application layers.
|
||||
6. Every mutation requires an audit record.
|
||||
7. Every credential is encrypted at rest.
|
||||
8. Secrets must never appear in logs or model context unless explicitly required and policy-approved.
|
||||
9. UI uses Ant Design / ProComponents unless there is a documented exception.
|
||||
10. Every feature must have an API contract.
|
||||
11. Every module must have tests appropriate to its risk.
|
||||
12. Do not introduce dependencies without justification.
|
||||
13. Provider-specific behavior belongs behind integration adapters.
|
||||
14. Long-running work must be asynchronous.
|
||||
15. External operations require timeout and explicit failure handling.
|
||||
16. HIGH/CRITICAL AI actions require approval.
|
||||
17. Security controls cannot be bypassed by UI, API, MCP or Agent paths.
|
||||
18. Preserve workspace isolation.
|
||||
19. Prefer idempotent operations.
|
||||
20. Update documentation when changing a domain contract.
|
||||
|
||||
## Development Sequence
|
||||
```text
|
||||
Requirement
|
||||
↓
|
||||
Domain Model
|
||||
↓
|
||||
API Contract
|
||||
↓
|
||||
UI / Interaction
|
||||
↓
|
||||
Tests
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Verification
|
||||
↓
|
||||
Documentation
|
||||
```
|
||||
|
||||
## Definition of Done
|
||||
A feature is not done until:
|
||||
- type checks pass
|
||||
- tests pass
|
||||
- API contract is documented
|
||||
- authorization is enforced
|
||||
- audit behavior is implemented where applicable
|
||||
- error handling exists
|
||||
- UI states cover loading/empty/error/success
|
||||
- documentation is updated
|
||||
@@ -0,0 +1,240 @@
|
||||
# DevOS v1 ZCODE Development Specification
|
||||
|
||||
## 1. Purpose
|
||||
This document converts the architecture into executable work units for an AI coding agent such as ZCODE, Codex, Cursor or Claude Code.
|
||||
|
||||
The agent must work from specifications instead of inventing architecture during implementation.
|
||||
|
||||
## 2. Repository Target
|
||||
|
||||
```text
|
||||
devos/
|
||||
├── apps/
|
||||
│ ├── web/
|
||||
│ └── api/
|
||||
├── packages/
|
||||
│ ├── ui/
|
||||
│ ├── api-client/
|
||||
│ ├── types/
|
||||
│ └── auth/
|
||||
├── packages/integrations/
|
||||
├── prisma/
|
||||
├── docs/
|
||||
├── specs/
|
||||
└── AGENTS.md
|
||||
```
|
||||
|
||||
## 3. Initial Task Queue
|
||||
|
||||
### Task 001 — Monorepo
|
||||
Create the workspace structure for web, API and shared packages.
|
||||
|
||||
Acceptance:
|
||||
- package manager/workspaces configured
|
||||
- TypeScript shared configuration
|
||||
- lint/format/test commands
|
||||
- build pipeline
|
||||
|
||||
### Task 002 — Backend Bootstrap
|
||||
Create NestJS API with versioned `/api/v1` routing.
|
||||
|
||||
Acceptance:
|
||||
- health endpoint
|
||||
- configuration management
|
||||
- structured logging
|
||||
- error handling
|
||||
- request ID
|
||||
|
||||
### Task 003 — Frontend Bootstrap
|
||||
Create React + Ant Design application.
|
||||
|
||||
Acceptance:
|
||||
- ProLayout
|
||||
- routing
|
||||
- authentication shell
|
||||
- dashboard shell
|
||||
- API client
|
||||
- loading/error/empty states
|
||||
|
||||
### Task 004 — Database
|
||||
Create PostgreSQL + Prisma setup.
|
||||
|
||||
Acceptance:
|
||||
- migrations
|
||||
- core identity/workspace/resource schema
|
||||
- seed strategy
|
||||
- database documentation
|
||||
|
||||
### Task 005 — Authentication
|
||||
Implement authentication and current-user endpoint.
|
||||
|
||||
Acceptance:
|
||||
- login/logout
|
||||
- session/token strategy
|
||||
- password/credential handling appropriate to chosen auth design
|
||||
- authorization guards
|
||||
|
||||
### Task 006 — Workspace
|
||||
Implement workspace and membership.
|
||||
|
||||
Acceptance:
|
||||
- create/list/read workspace
|
||||
- membership
|
||||
- workspace isolation in service and query layers
|
||||
|
||||
### Task 007 — Resource System
|
||||
Implement unified Resource abstraction.
|
||||
|
||||
Acceptance:
|
||||
- CRUD
|
||||
- typed resource type
|
||||
- status
|
||||
- metadata
|
||||
- relation graph
|
||||
- workspace scope
|
||||
|
||||
### Task 008 — Audit
|
||||
Implement audit service and mutation hooks.
|
||||
|
||||
Acceptance:
|
||||
- audit record for every mutation
|
||||
- actor/workspace/resource/action
|
||||
- request/correlation ID
|
||||
- sensitive data masking
|
||||
|
||||
### Task 009 — Server Module
|
||||
Implement Server resource and provider adapter.
|
||||
|
||||
Acceptance:
|
||||
- create server
|
||||
- credential reference
|
||||
- connectivity check
|
||||
- status
|
||||
- SSH execution
|
||||
- audit
|
||||
- timeout/error handling
|
||||
|
||||
### Task 010 — Docker
|
||||
Implement Docker discovery through Server integration.
|
||||
|
||||
Acceptance:
|
||||
- list containers
|
||||
- inspect container
|
||||
- restart container
|
||||
- resource relation
|
||||
- audit
|
||||
|
||||
### Task 011 — Website
|
||||
Implement Website domain model and UI.
|
||||
|
||||
Acceptance:
|
||||
- website CRUD
|
||||
- repository/server/domain relations
|
||||
- status
|
||||
- detail page
|
||||
|
||||
### Task 012 — Deployment
|
||||
Implement deployment job model and asynchronous execution.
|
||||
|
||||
Acceptance:
|
||||
- create deployment
|
||||
- run deployment
|
||||
- progress
|
||||
- logs
|
||||
- cancellation where safe
|
||||
- verification
|
||||
- success/failure events
|
||||
|
||||
### Task 013 — Domain
|
||||
Implement domain and DNS provider adapter.
|
||||
|
||||
Acceptance:
|
||||
- domain CRUD
|
||||
- record read/update
|
||||
- authorization
|
||||
- audit
|
||||
|
||||
### Task 014 — Monitoring
|
||||
Implement initial health checks.
|
||||
|
||||
Acceptance:
|
||||
- website health
|
||||
- server status
|
||||
- monitor result history
|
||||
- down/recovered events
|
||||
|
||||
### Task 015 — Event Bus
|
||||
Implement internal domain events and persistence/dispatch model.
|
||||
|
||||
Acceptance:
|
||||
- canonical event names
|
||||
- correlation IDs
|
||||
- durable execution for required events
|
||||
|
||||
### Task 016 — Automation
|
||||
Implement Trigger → Condition → Action workflow model.
|
||||
|
||||
Acceptance:
|
||||
- manual trigger
|
||||
- event trigger
|
||||
- cron design
|
||||
- execution history
|
||||
- retries/timeouts
|
||||
|
||||
### Task 017 — AI Gateway
|
||||
Implement an AI run abstraction without allowing unrestricted execution.
|
||||
|
||||
Acceptance:
|
||||
- create AI run
|
||||
- plan
|
||||
- tool registry
|
||||
- risk evaluation
|
||||
- approval state
|
||||
- execution history
|
||||
- verification result
|
||||
|
||||
### Task 018 — MCP
|
||||
Expose selected DevOS capabilities through MCP.
|
||||
|
||||
Acceptance:
|
||||
- server list/status
|
||||
- website list/deploy
|
||||
- deployment get
|
||||
- domain list/records
|
||||
- task/note tools when corresponding modules exist
|
||||
- all requests pass normal authorization/audit/risk controls
|
||||
|
||||
## 4. Agent Execution Protocol
|
||||
|
||||
For each task:
|
||||
1. Read relevant docs.
|
||||
2. Inspect existing code.
|
||||
3. State implementation plan internally.
|
||||
4. Implement the smallest coherent change.
|
||||
5. Add/update tests.
|
||||
6. Run typecheck/lint/tests.
|
||||
7. Verify API and UI contracts.
|
||||
8. Update documentation.
|
||||
9. Do not refactor unrelated code.
|
||||
|
||||
## 5. Stop Conditions
|
||||
The coding agent must stop and ask for a human decision when:
|
||||
- architecture requires a new major dependency
|
||||
- a security boundary must change
|
||||
- destructive production behavior is requested
|
||||
- domain terminology conflicts with existing specifications
|
||||
- an API breaking change is unavoidable
|
||||
- two specification documents materially conflict
|
||||
|
||||
## 6. Priority
|
||||
When requirements conflict, use this order:
|
||||
1. Security
|
||||
2. Explicit user requirement
|
||||
3. Domain model
|
||||
4. API contract
|
||||
5. Architecture
|
||||
6. UI convenience
|
||||
7. Implementation preference
|
||||
|
||||
## 7. Important Constraint
|
||||
Do not convert DevOS into microservices during V1 unless a concrete operational requirement proves modular monolith insufficient.
|
||||
@@ -0,0 +1,20 @@
|
||||
# DevOS v1 Development Document Package
|
||||
|
||||
This package was generated from the supplied architecture discussion.
|
||||
|
||||
## Source basis
|
||||
The source defines DevOS as a Developer Work OS centered on:
|
||||
- Unified Resource Model
|
||||
- Resource + Action + Event + Agent
|
||||
- Modular Monolith
|
||||
- React + Ant Design + ProComponents
|
||||
- NestJS + TypeScript
|
||||
- PostgreSQL + Prisma + Redis
|
||||
- Infrastructure/provider adapters
|
||||
- Event Bus / Automation
|
||||
- AI Agent + MCP
|
||||
- Credential Vault / RBAC / Audit / Approval
|
||||
- V0 → V1 → V2 → V3 → V4 roadmap
|
||||
|
||||
## Important
|
||||
This package preserves the source decisions and turns them into implementation-oriented specifications. Where the source did not define exact production-level details (for example exact auth protocol, complete SQL constraints, or a full MCP wire contract), this package intentionally leaves them as implementation decisions rather than pretending they were already decided.
|
||||
Reference in New Issue
Block a user