@synth-deploy/server 0.1.0

package/src/api/environments.ts

@@ -0,0 +1,97 @@
+import type { FastifyInstance } from "fastify";
+import type { IEnvironmentStore, IArtifactStore, ITelemetryStore } from "@synth-deploy/core";
+import { CreateEnvironmentSchema, UpdateEnvironmentSchema } from "./schemas.js";
+import { requirePermission } from "../middleware/permissions.js";
+import type { DeploymentStore } from "../agent/synth-agent.js";
+
+export function registerEnvironmentRoutes(
+  app: FastifyInstance,
+  environments: IEnvironmentStore,
+  deployments: DeploymentStore,
+  telemetry: ITelemetryStore,
+): void {
+  // List all environments
+  app.get("/api/environments", { preHandler: [requirePermission("environment.view")] }, async () => {
+    return { environments: environments.list() };
+  });
+
+  // Create an environment
+  app.post("/api/environments", { preHandler: [requirePermission("environment.create")] }, async (request, reply) => {
+    const parsed = CreateEnvironmentSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: "Invalid input", details: parsed.error.format() });
+    }
+
+    const environment = environments.create(parsed.data.name.trim(), parsed.data.variables ?? {});
+    telemetry.record({ actor: (request.user?.email) ?? "anonymous", action: "environment.created", target: { type: "environment", id: environment.id }, details: { name: parsed.data.name } });
+    return reply.status(201).send({ environment });
+  });
+
+  // Get environment by ID
+  app.get<{ Params: { id: string } }>(
+    "/api/environments/:id",
+    { preHandler: [requirePermission("environment.view")] },
+    async (request, reply) => {
+      const environment = environments.get(request.params.id);
+      if (!environment) {
+        return reply.status(404).send({ error: "Environment not found" });
+      }
+      return { environment };
+    },
+  );
+
+  // Update environment
+  app.put<{ Params: { id: string } }>(
+    "/api/environments/:id",
+    { preHandler: [requirePermission("environment.update")] },
+    async (request, reply) => {
+      const parsed = UpdateEnvironmentSchema.safeParse(request.body);
+      if (!parsed.success) {
+        return reply.status(400).send({ error: "Invalid input", details: parsed.error.format() });
+      }
+
+      try {
+        const environment = environments.update(request.params.id, {
+          name: parsed.data.name?.trim(),
+          variables: parsed.data.variables,
+        });
+        telemetry.record({ actor: (request.user?.email) ?? "anonymous", action: "environment.updated", target: { type: "environment", id: request.params.id }, details: { name: parsed.data.name } });
+        return { environment };
+      } catch (err) {
+        if (err instanceof Error && err.message.toLowerCase().includes("not found")) {
+          return reply.status(404).send({ error: "Environment not found" });
+        }
+        app.log.error(err, "Failed to update environment");
+        return reply.status(500).send({ error: "Internal server error" });
+      }
+    },
+  );
+
+  // Delete environment (with linked-operations safety check)
+  app.delete<{ Params: { id: string } }>(
+    "/api/environments/:id",
+    { preHandler: [requirePermission("environment.delete")] },
+    async (request, reply) => {
+      const envId = request.params.id;
+      const env = environments.get(envId);
+      if (!env) {
+        return reply.status(404).send({ error: "Environment not found" });
+      }
+
+      // Check if any deployments reference this environment
+      const linkedDeployments = deployments
+        .list()
+        .filter((d) => d.environmentId === envId);
+
+      if (linkedDeployments.length > 0) {
+        return reply.status(409).send({
+          error: `Environment has ${linkedDeployments.length} deployment(s). Cannot delete an environment with deployment history.`,
+          deploymentCount: linkedDeployments.length,
+        });
+      }
+
+      environments.delete(envId);
+      return { deleted: true };
+    },
+  );
+}

package/src/api/envoy-reports.ts

@@ -0,0 +1,159 @@
+import type { FastifyInstance } from "fastify";
+import { z } from "zod";
+import { DecisionTypeEnum } from "@synth-deploy/core";
+import type { DebriefWriter, DecisionType } from "@synth-deploy/core";
+import type { DeploymentStore } from "../agent/synth-agent.js";
+import type { EnvoyRegistry } from "../agent/envoy-registry.js";
+
+// ---------------------------------------------------------------------------
+// Schema — validates incoming Envoy reports
+// ---------------------------------------------------------------------------
+
+const DebriefEntrySchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  partitionId: z.string().nullable(),
+  deploymentId: z.string().nullable(),
+  agent: z.enum(["server", "envoy"]),
+  decisionType: DecisionTypeEnum,
+  decision: z.string(),
+  reasoning: z.string(),
+  context: z.record(z.unknown()),
+});
+
+const EnvoyReportSchema = z.object({
+  type: z.literal("deployment-result"),
+  envoyId: z.string(),
+  deploymentId: z.string(),
+  success: z.boolean(),
+  failureReason: z.string().nullable(),
+  debriefEntries: z.array(DebriefEntrySchema),
+  summary: z.object({
+    artifacts: z.array(z.string()),
+    workspacePath: z.string(),
+    executionDurationMs: z.number(),
+    totalDurationMs: z.number(),
+    verificationPassed: z.boolean(),
+    verificationChecks: z.array(
+      z.object({
+        name: z.string(),
+        passed: z.boolean(),
+        detail: z.string(),
+      }),
+    ),
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Endpoint for Envoys to push reports back to Command.
+ *
+ * When a Envoy completes a deployment (success or failure), it pushes
+ * a report containing its full debrief entries. Command ingests these
+ * into its own debrief so there is one unified Debrief that contains
+ * both Command's orchestration decisions and the Envoy's execution
+ * decisions.
+ *
+ * This is the Envoy->Command direction of bidirectional communication.
+ */
+export function registerEnvoyReportRoutes(
+  app: FastifyInstance,
+  debrief: DebriefWriter,
+  deployments: DeploymentStore,
+  registry: EnvoyRegistry,
+): void {
+  app.post("/api/envoy/report", async (request, reply) => {
+    const authHeader = (request.headers.authorization ?? "") as string;
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    if (!token || !registry.validateToken(token)) {
+      return reply.status(401).send({ error: "Invalid or missing envoy token" });
+    }
+
+    const parsed = EnvoyReportSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({
+        error: "Invalid Envoy report",
+        details: parsed.error.format(),
+      });
+    }
+
+    const report = parsed.data;
+
+    // Validate partition boundary: each debrief entry's deploymentId must
+    // belong to the claimed partitionId. Reject cross-partition reports.
+    for (const entry of report.debriefEntries) {
+      if (entry.deploymentId && entry.partitionId) {
+        const deployment = deployments.get(entry.deploymentId);
+        if (!deployment || deployment.partitionId !== entry.partitionId) {
+          debrief.record({
+            partitionId: entry.partitionId,
+            deploymentId: entry.deploymentId,
+            agent: "server",
+            decisionType: "system",
+            decision: "Rejected Envoy report: partition boundary violation",
+            reasoning: `Deployment ${entry.deploymentId} does not belong to partition ${entry.partitionId}. Report from envoy ${report.envoyId} rejected.`,
+            context: { envoyId: report.envoyId, reportedPartitionId: entry.partitionId },
+          });
+          return reply.status(403).send({
+            error: "Partition boundary violation",
+            detail: `Deployment ${entry.deploymentId} does not belong to partition ${entry.partitionId}`,
+          });
+        }
+      }
+    }
+
+    let ingested = 0;
+
+    // Ingest each Envoy debrief entry into Command's debrief.
+    // We re-record them (rather than inserting raw) so Command's debrief
+    // assigns its own IDs and timestamps. The original Envoy entry data
+    // is preserved in the context field for traceability.
+    for (const entry of report.debriefEntries) {
+      debrief.record({
+        partitionId: entry.partitionId,
+        deploymentId: entry.deploymentId,
+        agent: entry.agent as "server" | "envoy",
+        decisionType: entry.decisionType as DecisionType,
+        decision: entry.decision,
+        reasoning: entry.reasoning,
+        context: {
+          ...entry.context,
+          _envoyReport: {
+            envoyId: report.envoyId,
+            originalEntryId: entry.id,
+            originalTimestamp: entry.timestamp,
+          },
+        },
+      });
+      ingested++;
+    }
+
+    // Update deployment status based on the result
+    const deployment = deployments.get(report.deploymentId);
+    if (deployment && deployment.status === "running") {
+      let finalStatus: typeof deployment.status;
+      if (report.success) {
+        finalStatus = "succeeded" as typeof deployment.status;
+      } else {
+        const hadRollback = report.debriefEntries.some((e) => e.decisionType === "rollback-execution");
+        finalStatus = (hadRollback ? "rolled_back" : "failed") as typeof deployment.status;
+      }
+      deployment.status = finalStatus;
+      if (!report.success && report.failureReason) {
+        deployment.failureReason = report.failureReason;
+      }
+      deployment.completedAt = new Date();
+      deployments.save(deployment);
+    }
+
+    return reply.status(200).send({
+      accepted: true,
+      deploymentId: report.deploymentId,
+      envoyId: report.envoyId,
+      entriesIngested: ingested,
+    });
+  });
+}

package/src/api/envoys.ts

@@ -0,0 +1,237 @@
+import type { FastifyInstance } from "fastify";
+import type { ISettingsStore, ITelemetryStore, IDeploymentStore, DebriefReader } from "@synth-deploy/core";
+import type { EnvoyRegistry } from "../agent/envoy-registry.js";
+import { requirePermission } from "../middleware/permissions.js";
+import { getMaxEnvoys, EditionError } from "@synth-deploy/core";
+
+export function registerEnvoyRoutes(
+  app: FastifyInstance,
+  settings: ISettingsStore,
+  registry: EnvoyRegistry,
+  telemetry: ITelemetryStore,
+  deployments: IDeploymentStore,
+  debrief: DebriefReader,
+): void {
+  // List all registered Envoys (cached data — no live probe)
+  app.get("/api/envoys", { preHandler: [requirePermission("envoy.view")] }, async () => {
+    let entries = registry.listEntries();
+
+    // Also include the legacy settings-based default envoy if no registry entries
+    if (entries.length === 0) {
+      const envoyConfig = settings.get().envoy;
+      if (envoyConfig?.url) {
+        const legacy = registry.register({
+          name: "default",
+          url: envoyConfig.url,
+        });
+        const entry = registry.get(legacy.id);
+        if (entry) entries = [entry];
+      }
+    }
+
+    return {
+      envoys: entries.map((e) => ({
+        id: e.id,
+        name: e.name,
+        url: e.url,
+        health: e.health,
+        hostname: e.hostname,
+        os: e.os,
+        lastSeen: e.lastSeen,
+        summary: e.summary,
+        readiness: e.readiness,
+        assignedEnvironments: e.assignedEnvironments,
+        assignedPartitions: e.assignedPartitions,
+      })),
+    };
+  });
+
+  // Register a new Envoy
+  app.post("/api/envoys", { preHandler: [requirePermission("envoy.register")] }, async (request, reply) => {
+    const body = request.body as {
+      name: string;
+      url: string;
+      assignedEnvironments?: string[];
+      assignedPartitions?: string[];
+    };
+
+    if (!body.name || !body.url) {
+      return reply.status(400).send({ error: "name and url are required" });
+    }
+
+    // Enforce envoy count limit (Community: 10, Enterprise: license value)
+    const maxEnvoys = getMaxEnvoys();
+    if (maxEnvoys > 0 && registry.listEntries().length >= maxEnvoys) {
+      throw new EditionError("unlimited-envoys");
+    }
+
+    const registration = registry.register({
+      name: body.name,
+      url: body.url,
+      assignedEnvironments: body.assignedEnvironments,
+      assignedPartitions: body.assignedPartitions,
+    });
+
+    // Probe health immediately after registration
+    const entry = await registry.probe(registration.id);
+
+    telemetry.record({ actor: (request.user?.email) ?? "anonymous", action: "envoy.registered", target: { type: "envoy", id: registration.id }, details: { name: body.name, url: body.url } });
+
+    return reply.status(201).send({
+      envoy: {
+        id: registration.id,
+        name: registration.name,
+        url: registration.url,
+        token: registration.token,
+        assignedEnvironments: registration.assignedEnvironments,
+        assignedPartitions: registration.assignedPartitions,
+        registeredAt: registration.registeredAt,
+        health: entry?.health ?? "Unreachable",
+      },
+    });
+  });
+
+  // Get a specific Envoy's cached status (instant, no live probe)
+  app.get("/api/envoys/:id/health", { preHandler: [requirePermission("envoy.view")] }, async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const entry = registry.get(id);
+
+    if (!entry) {
+      return reply.status(404).send({ error: "Envoy not found" });
+    }
+
+    return {
+      envoy: {
+        id: entry.id,
+        name: entry.name,
+        url: entry.url,
+        health: entry.health,
+        hostname: entry.hostname,
+        os: entry.os,
+        lastSeen: entry.lastSeen,
+        summary: entry.summary,
+        readiness: entry.readiness,
+        assignedEnvironments: entry.assignedEnvironments,
+        assignedPartitions: entry.assignedPartitions,
+      },
+    };
+  });
+
+  // Update an Envoy's configuration
+  app.put("/api/envoys/:id", { preHandler: [requirePermission("envoy.configure")] }, async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const body = request.body as {
+      name?: string;
+      url?: string;
+      assignedEnvironments?: string[];
+      assignedPartitions?: string[];
+    };
+
+    const existing = registry.get(id);
+    const updated = registry.update(id, body);
+    if (!updated) {
+      return reply.status(404).send({ error: "Envoy not found" });
+    }
+
+    const actor = (request.user?.email) ?? "anonymous";
+    if (body.assignedEnvironments !== undefined && existing) {
+      const prev = new Set(existing.assignedEnvironments);
+      const next = new Set(body.assignedEnvironments);
+      for (const envId of next) {
+        if (!prev.has(envId)) telemetry.record({ actor, action: "envoy.connection.added", target: { type: "envoy", id }, details: { connectionType: "environment", targetId: envId } });
+      }
+      for (const envId of prev) {
+        if (!next.has(envId)) telemetry.record({ actor, action: "envoy.connection.removed", target: { type: "envoy", id }, details: { connectionType: "environment", targetId: envId } });
+      }
+    }
+    if (body.assignedPartitions !== undefined && existing) {
+      const prev = new Set(existing.assignedPartitions);
+      const next = new Set(body.assignedPartitions);
+      for (const partId of next) {
+        if (!prev.has(partId)) telemetry.record({ actor, action: "envoy.connection.added", target: { type: "envoy", id }, details: { connectionType: "partition", targetId: partId } });
+      }
+      for (const partId of prev) {
+        if (!next.has(partId)) telemetry.record({ actor, action: "envoy.connection.removed", target: { type: "envoy", id }, details: { connectionType: "partition", targetId: partId } });
+      }
+    }
+
+    return {
+      envoy: {
+        id: updated.id,
+        name: updated.name,
+        url: updated.url,
+        assignedEnvironments: updated.assignedEnvironments,
+        assignedPartitions: updated.assignedPartitions,
+      },
+    };
+  });
+
+  // Deregister an Envoy
+  app.delete("/api/envoys/:id", { preHandler: [requirePermission("envoy.configure")] }, async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const removed = registry.deregister(id);
+
+    if (!removed) {
+      return reply.status(404).send({ error: "Envoy not found" });
+    }
+
+    return reply.status(204).send();
+  });
+
+  // Rotate an Envoy's token
+  app.post("/api/envoys/:id/rotate-token", { preHandler: [requirePermission("envoy.configure")] }, async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const newToken = registry.rotateToken(id);
+
+    if (!newToken) {
+      return reply.status(404).send({ error: "Envoy not found" });
+    }
+
+    return { token: newToken };
+  });
+
+  // Get accumulated knowledge for an Envoy — system observations from environment scans
+  app.get("/api/envoys/:id/knowledge", { preHandler: [requirePermission("envoy.view")] }, async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const entry = registry.get(id);
+    if (!entry) {
+      return reply.status(404).send({ error: "Envoy not found" });
+    }
+
+    const envoyDeployments = deployments.list().filter((d) => d.envoyId === id);
+    const observations: { id: string; timestamp: string; text: string }[] = [];
+
+    for (const d of envoyDeployments) {
+      const entries = debrief.getByDeployment(d.id);
+      for (const e of entries) {
+        if (e.decisionType === "environment-scan") {
+          observations.push({ id: e.id, timestamp: e.timestamp.toISOString(), text: e.reasoning || e.decision });
+        }
+      }
+    }
+
+    // Sort newest first, cap at 20
+    observations.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+    return { knowledge: observations.slice(0, 20) };
+  });
+
+  // Validate an Envoy token (used by Envoy report endpoint)
+  app.post("/api/envoys/validate-token", async (request, reply) => {
+    const body = request.body as { token: string };
+    if (!body.token) {
+      return reply.status(400).send({ error: "token is required" });
+    }
+
+    const envoy = registry.validateToken(body.token);
+    if (!envoy) {
+      return reply.status(401).send({ error: "Invalid token" });
+    }
+
+    return {
+      valid: true,
+      envoyId: envoy.id,
+      envoyName: envoy.name,
+    };
+  });
+}