feat(cloud): POST /api/v1/apps/[id]/deploy + GET …/deploy/status (#7804)

* chore(cloud-api): fix codegen path separators on Windows

`_generate-router.mjs` was leaving Windows-style backslash separators in
the result of `path.relative()`, which made `split("/")` collapse every
route path to just "/api" when run from a Windows host. Normalize the
relative path to forward slashes in `fileToHttpPaths`, `importIdent`,
and `importPath` so the generator produces the same output regardless of
host OS. No-op on POSIX.

* feat(cloud-shared): app-deployments service

Backs the new `POST /api/v1/apps/:id/deploy` and
`GET /api/v1/apps/:id/deploy/status` routes. The persisted source of
truth is the `apps` table itself — `deployment_status`,
`production_url`, and `last_deployed_at` columns added in migration
0007. A deployment is identified by `<appId>:<last_deployed_at_iso>`
so the CLI can correlate POST → GET polls without a separate
`deployments` table.

Pure helpers (status enum mapping, deployment-id composition) live in
`app-deployments-helpers.ts` so unit tests can import them without
pulling in the Drizzle-backed `appsService` and the rest of the
runtime.

When a real build/upload service (Vercel or otherwise) lands, this
service becomes the integration boundary — callers will not need to
change.

* feat(cloud): POST /api/v1/apps/[id]/deploy + GET …/deploy/status

Completes the cloud half of `elizaos deploy` (PR #7786). The CLI keel
from that PR drives this endpoint pair: build → upload → POST
/deploy → attach domain → poll GET /deploy/status every 5s until
READY or ERROR (10-minute cap on the CLI side).

Both routes follow the existing `apps/[id]/domains/route.ts` pattern
exactly:
- Hono handler with `requireUserOrApiKeyWithOrg(c)` for auth
- 404 when the app does not exist, 403 when the caller is authed but
  not the owning org
- thin wrapper over `appDeploymentsService`; ownership invariant is
  enforced at the route layer (mirrors the domains/managed-domains
  split)

Request schema lives in a sibling `schema.ts` so unit tests can
import it without pulling in the route's `@/lib/*` aliased imports.

Pure-helper tests under `packages/cloud-api/__tests__/` cover:
- empty body acceptance
- full body shape acceptance
- repoUrl / ref / env value validation
- every enum value of the persisted → public status map
- deployment-id composition (with and without `last_deployed_at`)

Route-level happy-path / auth / not-found scenarios are exercised by
the existing e2e suite once `TEST_API_BASE_URL` is set.

* fix(cloud-shared): import AppDeploymentStatus from schema + drop dead QUEUED variant

Greptile P2 cleanup on PR #7804.

`AppDeploymentStatus` was redefined locally in app-deployments-helpers
despite being exported from `db/schemas/apps`, creating silent drift
risk if the persisted enum gained a new value (e.g. "cancelling"). Now
re-exported via a type-only import so Drizzle runtime is not pulled in.

`QUEUED` was in the public `DeploymentStatus` union but no code path
can ever emit it — PERSISTED_TO_PUBLIC only produces BUILDING / READY /
ERROR / DRAFT. Removed from the public contract.

The 3 remaining P2s (double getById, concurrent build race, surfacing
error field) are design-sized and deferred to the follow-up
build-pipeline wiring PR.

* fix(cloud): include startedAt: null in deploy status no-record branch

The non-null record branch always returns `startedAt`, but the
no-record branch omitted it entirely. A typed CLI client that reads
`response.startedAt` unconditionally would receive `undefined` in
the no-prior-deployment case with no TypeScript error at the call
site (plain JSON). Keep the response shape uniform.

Addresses Greptile round-2 P1 on PR #7804.

* fix(cloud): reject POST /deploy with 409 when a build is already in flight

Two concurrent CLI invocations of `elizaos deploy` both went through
unguarded: createDeployment stamped `last_deployed_at` twice, the
loser's `deploymentId` was immediately stale, and its subsequent GET
/status polls would return the winner's record without any signal
that the original POST got co-opted.

Adds `assertDeployable` helper that throws ApiError(409) when the
app's persisted `deployment_status` is already "building".
`createDeployment` calls it after a (cache-hot) `getById`, so the
race surfaces to the caller as a 409 instead of silently overwriting.

This is a check-then-act guard, not a DB-level lock — a fully race-
free path would do a conditional UPDATE in the apps repo. For the
realistic CLI cadence (invocations seconds apart) this is sufficient.

Addresses Greptile round-1 P2 on PR #7804.

8/8 helper unit tests green.

Author: 2-A-M

packages/cloud-api/__tests__/app-deployments-helpers.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure-helper tests for the app-deployments service + deploy route schema.
+ *
+ * Mirrors the contract these two routes wire together:
+ *   POST /api/v1/apps/:id/deploy
+ *   GET  /api/v1/apps/:id/deploy/status
+ *
+ * Route-level happy-path / auth / not-found scenarios are exercised by the
+ * existing e2e suite under packages/cloud-api/test/e2e (which has live
+ * Postgres + Redis). The helpers below are pure and run without any I/O.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  deploymentIdFor,
+  publicStatusFor,
+} from "@elizaos/cloud-shared/lib/services/app-deployments-helpers.ts";
+import { DeployBodySchema } from "../v1/apps/[id]/deploy/schema";
+
+describe("DeployBodySchema", () => {
+  test("accepts an empty body — all fields are optional", () => {
+    const parsed = DeployBodySchema.safeParse({});
+    expect(parsed.success).toBe(true);
+  });
+
+  test("accepts the full body shape", () => {
+    const parsed = DeployBodySchema.safeParse({
+      repoUrl: "https://github.com/2-A-M/example",
+      ref: "main",
+      dockerfile: "./Dockerfile",
+      env: { FOO: "bar", BAZ: "qux" },
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data.repoUrl).toBe("https://github.com/2-A-M/example");
+      expect(parsed.data.ref).toBe("main");
+      expect(parsed.data.dockerfile).toBe("./Dockerfile");
+      expect(parsed.data.env).toEqual({ FOO: "bar", BAZ: "qux" });
+    }
+  });
+
+  test("rejects a non-URL repoUrl", () => {
+    const parsed = DeployBodySchema.safeParse({ repoUrl: "not-a-url" });
+    expect(parsed.success).toBe(false);
+  });
+
+  test("rejects an empty ref string", () => {
+    const parsed = DeployBodySchema.safeParse({ ref: "" });
+    expect(parsed.success).toBe(false);
+  });
+
+  test("rejects an env entry with a non-string value", () => {
+    const parsed = DeployBodySchema.safeParse({
+      env: { FOO: 42 as unknown as string },
+    });
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe("publicStatusFor", () => {
+  test("maps every persisted enum value to a public status", () => {
+    expect(publicStatusFor("draft")).toBe("DRAFT");
+    expect(publicStatusFor("building")).toBe("BUILDING");
+    expect(publicStatusFor("deploying")).toBe("BUILDING");
+    expect(publicStatusFor("deployed")).toBe("READY");
+    expect(publicStatusFor("failed")).toBe("ERROR");
+  });
+});
+
+describe("deploymentIdFor", () => {
+  test("composes `${appId}:${lastDeployedAt.toISOString()}`", () => {
+    const id = deploymentIdFor({
+      id: "abc-123",
+      last_deployed_at: new Date("2026-05-19T12:00:00.000Z"),
+    });
+    expect(id).toBe("abc-123:2026-05-19T12:00:00.000Z");
+  });
+
+  test("uses the literal '0' when last_deployed_at is null", () => {
+    const id = deploymentIdFor({
+      id: "abc-123",
+      last_deployed_at: null,
+    });
+    expect(id).toBe("abc-123:0");
+  });
+});

packages/cloud-api/src/_generate-router.mjs

@@ -55,7 +55,7 @@ function joinHttpPath(segments) {
 }
 
 export function fileToHttpPaths(filePath, apiRoot = API_ROOT) {
-  const rel = relative(apiRoot, filePath);
+  const rel = relative(apiRoot, filePath).replace(/\\/g, "/");
   const segments = rel.split("/").slice(0, -1);
   const out = ["/api"];
   for (const seg of segments) {
@@ -77,7 +77,9 @@ export function fileToHttpPaths(filePath, apiRoot = API_ROOT) {
 }
 
 export function importIdent(filePath, apiRoot = API_ROOT) {
-  const rel = relative(apiRoot, filePath).replace(/\.tsx?$/, "");
+  const rel = relative(apiRoot, filePath)
+    .replace(/\\/g, "/")
+    .replace(/\.tsx?$/, "");
   return (
     "_route_" +
     rel
@@ -91,7 +93,9 @@ export function importIdent(filePath, apiRoot = API_ROOT) {
 }
 
 export function importPath(filePath) {
-  const rel = relative(__dirname, filePath).replace(/\.tsx?$/, "");
+  const rel = relative(__dirname, filePath)
+    .replace(/\\/g, "/")
+    .replace(/\.tsx?$/, "");
   return rel.startsWith(".") ? rel : `./${rel}`;
 }
 

packages/cloud-api/src/_router.generated.ts

@@ -2,7 +2,7 @@
  * AUTO-GENERATED by src/_generate-router.mjs - do not edit by hand.
  * Re-run `bun run codegen` after adding or removing a route.ts file.
  *
- * 556 routes mounted, 0 skipped (still Next-shaped).
+ * 558 routes mounted, 0 skipped (still Next-shaped).
  */
 
 /* eslint-disable */
@@ -274,6 +274,8 @@ import _route_v1_apps_p_id_charges_p_chargeId_checkout_route from "../v1/apps/[i
 import _route_v1_apps_p_id_charges_p_chargeId_route from "../v1/apps/[id]/charges/[chargeId]/route";
 import _route_v1_apps_p_id_charges_route from "../v1/apps/[id]/charges/route";
 import _route_v1_apps_p_id_chat_route from "../v1/apps/[id]/chat/route";
+import _route_v1_apps_p_id_deploy_status_route from "../v1/apps/[id]/deploy/status/route";
+import _route_v1_apps_p_id_deploy_route from "../v1/apps/[id]/deploy/route";
 import _route_v1_apps_p_id_discord_automation_post_route from "../v1/apps/[id]/discord-automation/post/route";
 import _route_v1_apps_p_id_discord_automation_route from "../v1/apps/[id]/discord-automation/route";
 import _route_v1_apps_p_id_domains_buy_route from "../v1/apps/[id]/domains/buy/route";
@@ -1258,6 +1260,11 @@ export function mountRoutes(app: Hono<AppEnv>): void {
   );
   app.route("/api/v1/apps/:id/charges", _route_v1_apps_p_id_charges_route);
   app.route("/api/v1/apps/:id/chat", _route_v1_apps_p_id_chat_route);
+  app.route(
+    "/api/v1/apps/:id/deploy/status",
+    _route_v1_apps_p_id_deploy_status_route,
+  );
+  app.route("/api/v1/apps/:id/deploy", _route_v1_apps_p_id_deploy_route);
   app.route(
     "/api/v1/apps/:id/discord-automation/post",
     _route_v1_apps_p_id_discord_automation_post_route,

packages/cloud-api/v1/apps/[id]/deploy/route.ts

@@ -0,0 +1,84 @@
+/**
+ * POST /api/v1/apps/:id/deploy
+ *
+ * Kicks off a deploy for the app. Body is fully optional — defaults pull
+ * from the app's linked GitHub repo and stored env config:
+ *
+ *   { repoUrl?: string; ref?: string; dockerfile?: string;
+ *     env?: Record<string, string> }
+ *
+ * Completes the cloud half of `elizaos deploy` (PR #7786). The CLI keel
+ * from that PR drives this endpoint: build → upload → POST here →
+ * attach domain → poll GET /deploy/status until READY or ERROR.
+ */
+
+import { Hono } from "hono";
+import { failureResponse } from "@/lib/api/cloud-worker-errors";
+import { requireUserOrApiKeyWithOrg } from "@/lib/auth/workers-hono-auth";
+import { appDeploymentsService } from "@/lib/services/app-deployments";
+import { appsService } from "@/lib/services/apps";
+import { logger } from "@/lib/utils/logger";
+import type { AppEnv } from "@/types/cloud-worker-env";
+import { DeployBodySchema } from "./schema";
+
+const app = new Hono<AppEnv>();
+
+app.post("/", async (c) => {
+  try {
+    const user = await requireUserOrApiKeyWithOrg(c);
+    const appId = c.req.param("id");
+    if (!appId) {
+      return c.json({ success: false, error: "Missing app id" }, 400);
+    }
+
+    const appRow = await appsService.getById(appId);
+    if (!appRow) {
+      return c.json({ success: false, error: "App not found" }, 404);
+    }
+    if (appRow.organization_id !== user.organization_id) {
+      // 403 — the caller is authed but not the owning org.
+      return c.json({ success: false, error: "Access denied" }, 403);
+    }
+
+    // Body is fully optional — accept an empty/absent body as `{}`.
+    const rawBody: unknown = await c.req.json().catch(() => ({}));
+    const parsed = DeployBodySchema.safeParse(rawBody);
+    if (!parsed.success) {
+      return c.json(
+        {
+          success: false,
+          error: parsed.error.issues[0]?.message ?? "Invalid request body",
+        },
+        400,
+      );
+    }
+
+    const record = await appDeploymentsService.createDeployment({
+      appId,
+      organizationId: user.organization_id,
+      userId: user.id,
+      ...parsed.data,
+    });
+
+    logger.info("[Deploy POST] deployment queued", {
+      appId,
+      deploymentId: record.deploymentId,
+      userId: user.id,
+      organizationId: user.organization_id,
+    });
+
+    return c.json(
+      {
+        success: true,
+        deploymentId: record.deploymentId,
+        status: record.status,
+        startedAt: record.startedAt,
+      },
+      202,
+    );
+  } catch (error) {
+    return failureResponse(c, error);
+  }
+});
+
+export default app;

packages/cloud-api/v1/apps/[id]/deploy/schema.ts

@@ -0,0 +1,17 @@
+/**
+ * Request schema for `POST /api/v1/apps/:id/deploy`.
+ *
+ * Lives in a sibling module so unit tests can import the schema without
+ * pulling in the route's `@/lib/*` aliased imports (Bun's test runner does
+ * not resolve TypeScript path aliases).
+ */
+import { z } from "zod";
+
+export const DeployBodySchema = z.object({
+  repoUrl: z.string().url().optional(),
+  ref: z.string().min(1).max(255).optional(),
+  dockerfile: z.string().min(1).max(255).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+export type DeployBody = z.infer<typeof DeployBodySchema>;

packages/cloud-api/v1/apps/[id]/deploy/status/route.ts

@@ -0,0 +1,59 @@
+/**
+ * GET /api/v1/apps/:id/deploy/status
+ *
+ * Returns the latest deployment record for the app. Polled by the
+ * `elizaos deploy` CLI (PR #7786) every ~5s until status is READY or
+ * ERROR (10-minute cap on the CLI side).
+ */
+
+import { Hono } from "hono";
+import { failureResponse } from "@/lib/api/cloud-worker-errors";
+import { requireUserOrApiKeyWithOrg } from "@/lib/auth/workers-hono-auth";
+import { appDeploymentsService } from "@/lib/services/app-deployments";
+import { appsService } from "@/lib/services/apps";
+import type { AppEnv } from "@/types/cloud-worker-env";
+
+const app = new Hono<AppEnv>();
+
+app.get("/", async (c) => {
+  try {
+    const user = await requireUserOrApiKeyWithOrg(c);
+    const appId = c.req.param("id");
+    if (!appId) {
+      return c.json({ success: false, error: "Missing app id" }, 400);
+    }
+
+    const appRow = await appsService.getById(appId);
+    if (!appRow) {
+      return c.json({ success: false, error: "App not found" }, 404);
+    }
+    if (appRow.organization_id !== user.organization_id) {
+      return c.json({ success: false, error: "Access denied" }, 403);
+    }
+
+    const record = await appDeploymentsService.getLatestDeployment(appId);
+    if (!record) {
+      return c.json({
+        success: true,
+        deploymentId: null,
+        status: "DRAFT" as const,
+        vercelUrl: null,
+        error: null,
+        startedAt: null,
+      });
+    }
+
+    return c.json({
+      success: true,
+      deploymentId: record.deploymentId,
+      status: record.status,
+      vercelUrl: record.vercelUrl,
+      error: record.error,
+      startedAt: record.startedAt,
+    });
+  } catch (error) {
+    return failureResponse(c, error);
+  }
+});
+
+export default app;

packages/cloud-shared/src/lib/services/__tests__/app-deployments-helpers.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Covers the pure helpers backing the app-deployments service:
+ *
+ *   - `publicStatusFor` — db enum → CLI-facing status
+ *   - `deploymentIdFor` — `<appId>:<iso-timestamp>` formatter
+ *   - `assertDeployable` — 409 guard against concurrent deploys
+ */
+import { describe, expect, test } from "bun:test";
+import { ApiError } from "../../api/cloud-worker-errors";
+import {
+  assertDeployable,
+  deploymentIdFor,
+  publicStatusFor,
+} from "../app-deployments-helpers";
+
+describe("publicStatusFor", () => {
+  test("maps draft to DRAFT", () => {
+    expect(publicStatusFor("draft")).toBe("DRAFT");
+  });
+  test("collapses building and deploying to BUILDING", () => {
+    expect(publicStatusFor("building")).toBe("BUILDING");
+    expect(publicStatusFor("deploying")).toBe("BUILDING");
+  });
+  test("maps deployed to READY", () => {
+    expect(publicStatusFor("deployed")).toBe("READY");
+  });
+  test("maps failed to ERROR", () => {
+    expect(publicStatusFor("failed")).toBe("ERROR");
+  });
+});
+
+describe("deploymentIdFor", () => {
+  test("uses ISO timestamp when last_deployed_at is set", () => {
+    const ts = new Date("2026-05-19T15:00:00.000Z");
+    expect(deploymentIdFor({ id: "app_1", last_deployed_at: ts })).toBe(
+      "app_1:2026-05-19T15:00:00.000Z",
+    );
+  });
+  test("uses 0 sentinel when last_deployed_at is null", () => {
+    expect(deploymentIdFor({ id: "app_2", last_deployed_at: null })).toBe("app_2:0");
+  });
+});
+
+describe("assertDeployable", () => {
+  test("throws ApiError(409) when status is building", () => {
+    expect(() => assertDeployable({ deployment_status: "building" })).toThrow(ApiError);
+    try {
+      assertDeployable({ deployment_status: "building" });
+    } catch (err) {
+      expect(err).toBeInstanceOf(ApiError);
+      expect((err as ApiError).status).toBe(409);
+      expect((err as ApiError).code).toBe("session_not_ready");
+    }
+  });
+
+  test("does not throw for draft / deployed / failed / deploying", () => {
+    expect(() => assertDeployable({ deployment_status: "draft" })).not.toThrow();
+    expect(() => assertDeployable({ deployment_status: "deployed" })).not.toThrow();
+    expect(() => assertDeployable({ deployment_status: "failed" })).not.toThrow();
+    // `deploying` is the immediate-after-build state — callers may want to
+    // retry from a fresh deploy after a deploy-side failure during upload,
+    // so we don't reject it here.
+    expect(() => assertDeployable({ deployment_status: "deploying" })).not.toThrow();
+  });
+});