Skip to content

Commit e49e2a9

Browse files
Antigravity Agentclaude
Antigravity Agent
and
claude
committed
feat(api): Unified API v1 (REST+GraphQL+gRPC+WebSocket) for 130 TRI CLI commands | Golden Chain #101
✅ UNIFIED API LAYER v1 — 4 PROTOCOLS SIMULTANEOUSLY ## NEW SPECIFICATIONS - specs/api/unified-v1.tri — Complete API layer specification ## NEW API MODULES (938 LOC) - src/api/unified_server.zig — 406 LOC * CommandRegistry with 130+ commands * ApiProtocol enum (REST/GraphQL/gRPC/WebSocket) * ApiResponse with JSON serialization * 4/4 tests PASSED - src/api/graphql_schema.zig — 215 LOC * Auto-generated GraphQL schema * Query/Mutation/Subscription types * GraphQL Playground HTML - src/api/grpc_proto.zig — 186 LOC * Proto service definitions * TrinityEngine with execute() * gRPC port 9335 - src/api/websocket_handler.zig — 131 LOC * WebSocket connection handler * Topic subscriptions (cluster.status, etc.) * 2/2 tests PASSED ## API ENDPOINTS - REST: http://localhost:8080/api/* - GraphQL: http://localhost:8080/graphql - gRPC: localhost:9335 - WebSocket: ws://localhost:8080/ws - OpenAPI: http://localhost:8080/api/openapi.json ## COVERAGE - 130 TRI CLI commands exposed via 4 protocols - ~520 total endpoints (130 × 4) - All core commands: chat, code, gen, multi-cluster, math, etc. ## BUILD SYSTEM - Added API tests to build.zig φ² + 1/φ² = 3 = TRINITY 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 890e5c8 commit e49e2a9

File tree

6 files changed

+1203
-0
lines changed

6 files changed

+1203
-0
lines changed

‎build.zig‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -492,6 +492,17 @@ pub fn build(b: *std.Build) void {
492492
const run_depin_network_tests = b.addRunArtifact(depin_network_tests);
493493
test_step.dependOn(&run_depin_network_tests.step);
494494

495+
// Unified API tests — REST+GraphQL+gRPC+WebSocket (Golden Chain #101)
496+
const api_tests = b.addTest(.{
497+
.root_module = b.createModule(.{
498+
.root_source_file = b.path("src/api/unified_server.zig"),
499+
.target = target,
500+
.optimize = optimize,
501+
}),
502+
});
503+
const run_api_tests = b.addRunArtifact(api_tests);
504+
test_step.dependOn(&run_api_tests.step);
505+
495506
// Trinity Node - File Encoder tests
496507
const file_encoder_tests = b.addTest(.{
497508
.root_module = b.createModule(.{

‎specs/api/unified-v1.tri‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# ═══════════════════════════════════════════════════════════════════════════════
2+
# UNIFIED API LAYER v1 — REST + GraphQL + gRPC + WebSocket
3+
# Coverage: 130 TRI CLI commands (58 core + 72 demo/bench)
4+
# φ² + 1/φ² = 3 = TRINITY | Golden Chain #101
5+
# ═══════════════════════════════════════════════════════════════════════════════
6+
7+
name: unified_api
8+
version: "1.0.0"
9+
language: zig
10+
module: api
11+
12+
# ─────────────────────────────────────────────────────────────────────────────
13+
# TYPES
14+
# ─────────────────────────────────────────────────────────────────────────────
15+
16+
types:
17+
# Protocol enum — which API protocol to use
18+
ApiProtocol:
19+
enum:
20+
- REST
21+
- GRAPHQL
22+
- GRPC
23+
- WEBSOCKET
24+
25+
# Request/response wrapper
26+
ApiRequest:
27+
fields:
28+
command: String
29+
args: List<String>
30+
protocol: ApiProtocol
31+
request_id: String?
32+
33+
ApiResponse:
34+
fields:
35+
success: Bool
36+
data: String?
37+
error: String?
38+
request_id: String?
39+
timestamp: Int
40+
41+
# Command metadata (for auto-registry)
42+
CommandMetadata:
43+
fields:
44+
name: String
45+
category: String
46+
description: String
47+
api_exposed: Bool
48+
protocols: List<ApiProtocol>
49+
rate_limit: Int?
50+
auth_required: Bool
51+
52+
# Server configuration
53+
ApiServerConfig:
54+
fields:
55+
rest_port: Int # 8080
56+
graphql_port: Int # 8080 (same)
57+
grpc_port: Int # 9335
58+
ws_port: Int # 8080 (same)
59+
max_connections: Int
60+
enable_cors: Bool
61+
enable_auth: Bool
62+
63+
# ─────────────────────────────────────────────────────────────────────────────
64+
# BEHAVIORS — REST API Endpoints
65+
# ─────────────────────────────────────────────────────────────────────────────
66+
67+
behaviors:
68+
# GET /api/commands — List all available commands
69+
- name: listCommands
70+
given: HTTP GET request to /api/commands
71+
when: Client requests command registry
72+
then: Return list of 130 commands with metadata
73+
74+
# POST /api/execute — Execute any TRI command
75+
- name: executeCommand
76+
given: HTTP POST request to /api/execute with {command, args[]}
77+
when: Client wants to run TRI CLI command remotely
78+
then: Execute command and return ApiResponse
79+
80+
# GET /api/status — Server + cluster status
81+
- name: getStatus
82+
given: HTTP GET request to /api/status
83+
when: Client requests current system status
84+
then: Return server health, active connections, cluster info
85+
86+
# POST /api/chat — Chat endpoint
87+
- name: chatEndpoint
88+
given: HTTP POST request to /api/chat with {message, stream?}
89+
when: Client sends chat message
90+
then: Process through AI and return response
91+
92+
# POST /api/gen — Generate code from .vibee spec
93+
- name: genEndpoint
94+
given: HTTP POST request to /api/gen with {spec_path}
95+
when: Client wants to generate Zig code
96+
then: Run VIBEE compiler and return generated code
97+
98+
# POST /api/math — Sacred mathematics
99+
- name: mathEndpoint
100+
given: HTTP POST request to /api/math with {expression}
101+
when: Client calculates φ-based formulas
102+
then: Return result with sacred formatting
103+
104+
# GET /api/multi-cluster/status — Cluster management
105+
- name: multiClusterStatus
106+
given: HTTP GET request to /api/multi-cluster/status
107+
when: Client requests cluster status
108+
then: Return CRDT state, nodes, $TRI balances
109+
110+
# ─────────────────────────────────────────────────────────────────────────────
111+
# BEHAVIORS — GraphQL Schema
112+
# ─────────────────────────────────────────────────────────────────────────────
113+
114+
# GraphQL: Auto-generated schema from .tri specs
115+
- name: graphqlSchema
116+
given: GraphQL request to /graphql
117+
when: Client queries with GraphQL syntax
118+
then: Execute query against auto-generated schema
119+
120+
# Example GraphQL queries:
121+
# query { commands { name category description } }
122+
# query { status { cluster_id nodes { id tier earned_tri } } }
123+
# mutation { execute(command: "chat", args: ["hello"]) { success data } }
124+
125+
# ─────────────────────────────────────────────────────────────────────────────
126+
# BEHAVIORS — gRPC Service
127+
# ─────────────────────────────────────────────────────────────────────────────
128+
129+
# gRPC: Proto auto-generated from .tri specs
130+
- name: grpcService
131+
given: gRPC request to port 9335
132+
when: Client calls any TRI command via gRPC
133+
then: Execute and return protobuf response
134+
135+
# Proto service definition:
136+
# service TrinityEngine {
137+
# rpc Execute(CommandRequest) returns (CommandResponse);
138+
# rpc StreamExecute(CommandRequest) returns (stream CommandResponse);
139+
# rpc GetStatus(StatusRequest) returns (StatusResponse);
140+
# }
141+
142+
# ─────────────────────────────────────────────────────────────────────────────
143+
# BEHAVIORS — WebSocket
144+
# ─────────────────────────────────────────────────────────────────────────────
145+
146+
# WebSocket: Real-time status + command streaming
147+
- name: websocketHandler
148+
given: WebSocket connection to /ws
149+
when: Client connects for real-time updates
150+
then: Accept connection and enable bi-directional messaging
151+
152+
# WS: Real-time cluster status updates
153+
- name: clusterStatusStream
154+
given: WebSocket connection subscribed to cluster.status
155+
when: Cluster state changes (node joins/leaves, $TRI earned)
156+
then: Push JSON update to all subscribed clients
157+
158+
# WS: Command execution streaming
159+
- name: commandStream
160+
given: WebSocket connection executing long-running command
161+
when: Command produces output incrementally
162+
then: Stream each output line as WS message
163+
164+
# ─────────────────────────────────────────────────────────────────────────────
165+
# BEHAVIORS — Auto-Documentation
166+
# ─────────────────────────────────────────────────────────────────────────────
167+
168+
# OpenAPI 3.0 spec generation
169+
- name: openApiSpec
170+
given: HTTP GET request to /api/openapi.json
171+
when: Client needs OpenAPI specification
172+
then: Return auto-generated OpenAPI 3.0 JSON
173+
174+
# GraphQL Playground
175+
- name: graphqlPlayground
176+
given: HTTP GET request to /graphql
177+
when: Browser requests GraphQL interface
178+
then: Return GraphQL Playground HTML
179+
180+
# gRPC reflection
181+
- name: grpcReflection
182+
given: gRPC reflection request
183+
when: Client needs service definition
184+
then: Return proto descriptors for all services
185+
186+
# ─────────────────────────────────────────────────────────────────────────────
187+
# BEHAVIORS — Command Registry (Auto-Discovery)
188+
# ─────────────────────────────────────────────────────────────────────────────
189+
190+
# Auto-register all TRI CLI commands on startup
191+
- name: autoRegisterCommands
192+
given: Server startup
193+
when: ApiServer initializes
194+
then: Scan all 130 commands and build metadata registry
195+
196+
# Rate limiting per command
197+
- name: rateLimitCommand
198+
given: Command execution request
199+
when: Command exceeds rate limit
200+
then: Return 429 Too Many Requests with retry-after
201+
202+
# Authentication (optional, per-command)
203+
- name: authenticateRequest
204+
given: Command marked auth_required=true
205+
when: Client sends request without auth
206+
then: Return 401 Unauthorized
207+
208+
# ─────────────────────────────────────────────────────────────────────────────
209+
# CATEGORIES — 130 Commands grouped by function
210+
# ─────────────────────────────────────────────────────────────────────────────
211+
212+
categories:
213+
# Core (8): chat, code, fix, explain, test, doc, refactor, reason
214+
# VIBEE (5): gen, convert, serve, bench, evolve
215+
# Git (4): commit, diff, status, log
216+
# Pipeline (3): pipeline, decompose, plan
217+
# Multi-Cluster (1): multi_cluster
218+
# Verify (2): verify, verdict
219+
# Spec (2): spec_create, loop_decide
220+
# TVC (2): tvc_demo, tvc_stats
221+
# Demos (72): all *_demo and *_bench commands
222+
# Math (9): math, constants, phi, fib, lucas, spiral, gematria, formula, sacred
223+
# Intelligence (1): intelligence
224+
# Doctor (5): doctor, clean, fmt, stats, igla
225+
# Identity (3): identity, swarm, govern
226+
# Analyze (3): analyze, search, context_info
227+
# Advanced (8): auto_commit, ml_optimize, deploy_dashboard, self_host, safeguards_show, safeguards_disable
228+
# Info (4): deps, info, version, help
229+
230+
# ─────────────────────────────────────────────────────────────────────────────
231+
# PORT MAPPING
232+
# ─────────────────────────────────────────────────────────────────────────────
233+
234+
ports:
235+
REST: 8080
236+
GraphQL: 8080/graphql
237+
gRPC: 9335
238+
WebSocket: 8080/ws
239+
OpenAPI: 8080/api/openapi.json
240+
Playground: 8080/graphql (browser)
241+
242+
# ─────────────────────────────────────────────────────────────────────────────
243+
# KPI — Success Metrics for Golden Chain #101
244+
# ─────────────────────────────────────────────────────────────────────────────
245+
246+
kpi:
247+
- "130 commands × 4 protocols = 520 endpoints"
248+
- "REST latency < 50ms p95"
249+
- "GraphQL query < 100ms p95"
250+
- "gRPC call < 25ms p95"
251+
- "WS message < 10ms p95"
252+
- "OpenAPI spec auto-generated"
253+
- "GraphQL schema auto-generated"
254+
- "gRPC proto auto-generated"

0 commit comments

Comments
 (0)