@sylphx/contract 0.2.0

package/dist/endpoints/deployments.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Deployments endpoints — status / trigger / history / rollback. Paths mount
+ * under `/projects` (management-plane) except `GET /deployments/:id` which
+ * lives at the top level. Response shapes mirror production handlers in
+ * `apps/api/src/server/platform/routes/management/projects/deploy.ts` and
+ * `routes/deployments/*` (ADR-084 Wave 2b).
+ *
+ * ADR-084 Wave 3E — env-scoped Console deploy operations added. Those
+ * paths live under `/deployments/*` (mounted separately from the management
+ * `/projects/:id/...` surface) and drive the Console UI per-env-service
+ * rollback / promote flows. Keys are prefixed `envScoped*` to distinguish
+ * them from the project-scoped management operations while preserving the
+ * flat namespace shape that the OpenAPI generator iterates.
+ */
+import { Schema } from 'effect';
+export declare const deploymentsEndpoints: {
+    readonly status: import("../endpoint.js").Endpoint<"GET", "/projects/:id/status", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Struct<{
+        envId: Schema.optional<typeof Schema.String>;
+        envType: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        projectId: Schema.brand<Schema.filter<typeof Schema.String>, "ProjectId">;
+        projectSlug: typeof Schema.String;
+        projectName: typeof Schema.String;
+        isActive: typeof Schema.Boolean;
+        status: typeof Schema.String;
+        environments: Schema.Array$<Schema.Struct<{
+            envId: Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">;
+            envType: Schema.optional<typeof Schema.String>;
+            envName: Schema.optional<typeof Schema.String>;
+            status: typeof Schema.String;
+            url: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            gitBranch: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            lastDeployedAt: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            latestDeployment: Schema.optional<Schema.NullOr<Schema.Struct<{
+                id: Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">;
+                status: typeof Schema.String;
+                deploymentUuid: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+                triggeredBy: Schema.NullOr<typeof Schema.String>;
+                startedAt: Schema.NullOr<typeof Schema.String>;
+                finishedAt: Schema.NullOr<typeof Schema.String>;
+            }>>>;
+            error: Schema.optional<typeof Schema.String>;
+        }>>;
+    }>>;
+    readonly get: import("../endpoint.js").Endpoint<"GET", "/deployments/:id", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        id: Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">;
+        status: typeof Schema.String;
+        projectId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ProjectId">>;
+        projectSlug: Schema.optional<typeof Schema.String>;
+        environment: Schema.optional<typeof Schema.String>;
+        environmentId: Schema.optional<Schema.NullOr<Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">>>;
+        image: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        commitSha: Schema.optional<typeof Schema.String>;
+        commitMessage: Schema.optional<typeof Schema.String>;
+        author: Schema.optional<typeof Schema.String>;
+        gitCommit: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        gitBranch: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        createdAt: Schema.optional<typeof Schema.String>;
+        startedAt: Schema.optional<typeof Schema.String>;
+        completedAt: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        finishedAt: Schema.optional<typeof Schema.String>;
+        failedAt: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        durationMs: Schema.optional<typeof Schema.Number>;
+        errorMessage: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        url: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        buildLogUrl: Schema.optional<typeof Schema.String>;
+        services: Schema.optional<Schema.Array$<Schema.Struct<{
+            id: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ServiceId">>;
+            name: typeof Schema.String;
+            image: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            status: typeof Schema.String;
+        }>>>;
+    }>>;
+    readonly trigger: import("../endpoint.js").Endpoint<"POST", "/projects/:id/deploy", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envType: Schema.optional<Schema.Literal<["production", "staging", "development"]>>;
+        envId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">>;
+        image: Schema.optional<typeof Schema.String>;
+        serviceId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ServiceId">>;
+    }>, Schema.Struct<{
+        deploymentId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">>;
+        deploymentRecordId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">>;
+        buildRecordId: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        projectId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ProjectId">>;
+        envId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">>;
+        envType: Schema.optional<typeof Schema.String>;
+        namespace: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        status: typeof Schema.String;
+        environment: Schema.optional<typeof Schema.String>;
+        message: Schema.optional<typeof Schema.String>;
+        triggeredAt: Schema.optional<typeof Schema.String>;
+    }>>;
+    readonly history: import("../endpoint.js").Endpoint<"GET", "/projects/:id/deployments", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Struct<{
+        envType: Schema.optional<typeof Schema.String>;
+        triggeredBy: Schema.optional<typeof Schema.String>;
+        status: Schema.optional<typeof Schema.String>;
+        serviceId: Schema.optional<typeof Schema.String>;
+        limit: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        object: Schema.Literal<["list"]>;
+        data: Schema.Array$<Schema.Struct<{
+            id: Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">;
+            projectId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ProjectId">>;
+            envId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">>;
+            envType: Schema.NullOr<typeof Schema.String>;
+            envName: Schema.NullOr<typeof Schema.String>;
+            deploymentUuid: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            status: typeof Schema.String;
+            gitCommit: Schema.NullOr<typeof Schema.String>;
+            gitBranch: Schema.NullOr<typeof Schema.String>;
+            commitMessage: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            triggeredBy: Schema.NullOr<typeof Schema.String>;
+            startedAt: Schema.NullOr<typeof Schema.String>;
+            finishedAt: Schema.NullOr<typeof Schema.String>;
+            createdAt: typeof Schema.String;
+        }>>;
+    }>>;
+    readonly rollback: import("../endpoint.js").Endpoint<"POST", "/projects/:id/rollback", Schema.Struct<{
+        id: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">>;
+        deploymentRecordId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">>;
+        buildRecordId: Schema.optional<typeof Schema.String>;
+        serviceId: Schema.optional<Schema.brand<Schema.filter<typeof Schema.String>, "ServiceId">>;
+    }>, Schema.Struct<{
+        rolledBack: typeof Schema.Boolean;
+        imageDigest: Schema.NullOr<typeof Schema.String>;
+        deploymentId: Schema.NullOr<Schema.brand<Schema.filter<typeof Schema.String>, "DeploymentId">>;
+        serviceId: Schema.NullOr<Schema.brand<Schema.filter<typeof Schema.String>, "ServiceId">>;
+    }>>;
+    readonly envScopedServiceStatus: import("../endpoint.js").Endpoint<"GET", "/deployments/status", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        configured: typeof Schema.Boolean;
+    }>>;
+    readonly envScopedListAppDeployments: import("../endpoint.js").Endpoint<"GET", "/deployments/projects", Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        projectId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        projectId: Schema.brand<Schema.filter<typeof Schema.String>, "ProjectId">;
+        buildMachineType: Schema.Literal<["standard", "large", "xlarge"]>;
+        environments: Schema.Array$<Schema.Struct<{
+            envId: Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">;
+            envType: typeof Schema.String;
+            name: typeof Schema.String;
+            status: typeof Schema.String;
+            url: Schema.NullOr<typeof Schema.String>;
+            gitBranch: Schema.NullOr<typeof Schema.String>;
+            lastDeployedAt: Schema.NullOr<typeof Schema.String>;
+            deployConfigured: typeof Schema.Boolean;
+        }>>;
+    }>>;
+    readonly envScopedTrigger: import("../endpoint.js").Endpoint<"POST", "/deployments/projects/:envId/deploy", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        deploymentId: typeof Schema.String;
+        message: typeof Schema.String;
+    }>>;
+    readonly envScopedRollbackByCommit: import("../endpoint.js").Endpoint<"POST", "/deployments/projects/:envId/rollback", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        commitSha: typeof Schema.String;
+    }>, Schema.Struct<{
+        deploymentId: typeof Schema.String;
+        message: typeof Schema.String;
+    }>>;
+    readonly envScopedCancelBuild: import("../endpoint.js").Endpoint<"POST", "/deployments/builds/:buildId/cancel", Schema.Struct<{
+        buildId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        cancelled: typeof Schema.Boolean;
+        buildId: typeof Schema.String;
+    }>>;
+    readonly envScopedListEnvVars: import("../endpoint.js").Endpoint<"GET", "/deployments/projects/:envId/env", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envId: Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">;
+        vars: Schema.Array$<Schema.Struct<{
+            key: typeof Schema.String;
+            value: typeof Schema.String;
+        }>>;
+    }>>;
+    readonly envScopedSetEnvVar: import("../endpoint.js").Endpoint<"POST", "/deployments/projects/:envId/env", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        key: typeof Schema.String;
+        value: typeof Schema.String;
+    }>, Schema.Struct<{
+        success: typeof Schema.Boolean;
+        message: typeof Schema.String;
+    }>>;
+    readonly envScopedDeleteEnvVar: import("../endpoint.js").Endpoint<"DELETE", "/deployments/projects/:envId/env/:key", Schema.Struct<{
+        envId: typeof Schema.String;
+        key: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        success: typeof Schema.Boolean;
+    }>>;
+    readonly envScopedHistory: import("../endpoint.js").Endpoint<"GET", "/deployments/projects/:envId/deployments", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envId: Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">;
+        deployments: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            status: Schema.Literal<["queued", "running", "building", "success", "failed", "cancelled"]>;
+            createdAt: typeof Schema.String;
+            commitMessage: Schema.NullOr<typeof Schema.String>;
+            gitCommit: Schema.NullOr<typeof Schema.String>;
+            gitBranch: Schema.NullOr<typeof Schema.String>;
+            supersededByGitSha: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+            cancellationReason: Schema.optional<Schema.NullOr<typeof Schema.String>>;
+        }>>;
+    }>>;
+    readonly envScopedHealthStatus: import("../endpoint.js").Endpoint<"GET", "/deployments/projects/:envId/status", Schema.Struct<{
+        envId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envId: Schema.brand<Schema.filter<typeof Schema.String>, "EnvironmentId">;
+        status: typeof Schema.String;
+        url: Schema.NullOr<typeof Schema.String>;
+        gitBranch: Schema.NullOr<typeof Schema.String>;
+        lastDeployedAt: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    readonly envServiceRollback: import("../endpoint.js").Endpoint<"POST", "/deployments/projects/:projectId/environments/:envId/services/:envSvcId/rollback", Schema.Struct<{
+        projectId: typeof Schema.String;
+        envId: typeof Schema.String;
+        envSvcId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        to_deployment_id: typeof Schema.String;
+    }>, Schema.Struct<{
+        ok: Schema.Literal<[true]>;
+        alreadyAtTarget: typeof Schema.Boolean;
+        newDeploymentId: Schema.NullOr<typeof Schema.String>;
+        imageDigest: typeof Schema.String;
+        reconcileTriggered: typeof Schema.Boolean;
+    }>>;
+    readonly envServicePromote: import("../endpoint.js").Endpoint<"POST", "/deployments/projects/:projectId/promote", Schema.Struct<{
+        projectId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        from_env_svc_id: typeof Schema.String;
+        to_env_svc_id: typeof Schema.String;
+        artifact_digest: Schema.optional<typeof Schema.String>;
+    }>, Schema.Struct<{
+        ok: Schema.Literal<[true]>;
+        targetEnvSvcId: typeof Schema.String;
+        artifactDigest: typeof Schema.String;
+        newDeploymentId: Schema.NullOr<typeof Schema.String>;
+        reconcileTriggered: typeof Schema.Boolean;
+    }>>;
+    readonly envServiceHistory: import("../endpoint.js").Endpoint<"GET", "/deployments/projects/:projectId/environments/:envId/services/:envSvcId/deployments", Schema.Struct<{
+        projectId: typeof Schema.String;
+        envId: typeof Schema.String;
+        envSvcId: typeof Schema.String;
+    }>, Schema.Struct<{
+        limit: Schema.optional<typeof Schema.String>;
+        status: Schema.optional<Schema.Literal<["queued", "running", "building", "success", "failed", "cancelled"]>>;
+        cursor: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        envSvcId: typeof Schema.String;
+        deployments: Schema.Array$<Schema.Struct<{
+            id: typeof Schema.String;
+            imageDigest: Schema.NullOr<typeof Schema.String>;
+            imageRef: Schema.NullOr<typeof Schema.String>;
+            status: Schema.Literal<["queued", "running", "building", "success", "failed", "cancelled"]>;
+            triggeredBy: Schema.NullOr<typeof Schema.String>;
+            triggerSource: Schema.Literal<["build", "promote", "rollback", "manual", "unknown"]>;
+            createdAt: typeof Schema.String;
+            finishedAt: Schema.NullOr<typeof Schema.String>;
+            gitSha: Schema.NullOr<typeof Schema.String>;
+            gitCommit: Schema.NullOr<typeof Schema.String>;
+            gitBranch: Schema.NullOr<typeof Schema.String>;
+            commitMessage: Schema.NullOr<typeof Schema.String>;
+            isCurrent: typeof Schema.Boolean;
+            isDesired: typeof Schema.Boolean;
+        }>>;
+        nextCursor: Schema.NullOr<typeof Schema.String>;
+    }>>;
+};
+//# sourceMappingURL=deployments.d.ts.map

package/dist/endpoints/deployments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployments.d.ts","sourceRoot":"","sources":["../../src/endpoints/deployments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAkE/B,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiKvB,CAAA"}

package/dist/endpoints/deployments.js

@@ -0,0 +1,205 @@
+/**
+ * Deployments endpoints — status / trigger / history / rollback. Paths mount
+ * under `/projects` (management-plane) except `GET /deployments/:id` which
+ * lives at the top level. Response shapes mirror production handlers in
+ * `apps/api/src/server/platform/routes/management/projects/deploy.ts` and
+ * `routes/deployments/*` (ADR-084 Wave 2b).
+ *
+ * ADR-084 Wave 3E — env-scoped Console deploy operations added. Those
+ * paths live under `/deployments/*` (mounted separately from the management
+ * `/projects/:id/...` surface) and drive the Console UI per-env-service
+ * rollback / promote flows. Keys are prefixed `envScoped*` to distinguish
+ * them from the project-scoped management operations while preserving the
+ * flat namespace shape that the OpenAPI generator iterates.
+ */
+import { Schema } from 'effect';
+import { defineEndpoint } from '../endpoint.js';
+import { CancelBuildResult, DeploymentDetail, DeploymentHistoryResult, DeployResult, DeployServiceStatus, EnvScopedAppDeployments, EnvScopedAppHealthStatus, EnvScopedDeleteEnvVarResult, EnvScopedDeploymentHistory, EnvScopedListEnvVarsResult, EnvScopedRollbackByCommitInput, EnvScopedRollbackByCommitResult, EnvScopedSetEnvVarInput, EnvScopedSetEnvVarResult, EnvScopedTriggerDeployResult, EnvServiceHistoryResult, EnvServiceRollbackInput, EnvServiceRollbackResult, ProjectStatus, PromoteArtifactInput, PromoteArtifactResult, RollbackDeploymentInput, RollbackResult, TriggerDeploymentInput, } from '../schemas/deployment.js';
+const ProjectIdPath = Schema.Struct({ id: Schema.String });
+const DeploymentIdPath = Schema.Struct({ id: Schema.String });
+const EnvIdPath = Schema.Struct({ envId: Schema.String });
+const EnvKeyPath = Schema.Struct({ envId: Schema.String, key: Schema.String });
+const BuildIdPath = Schema.Struct({ buildId: Schema.String });
+const ProjectEnvSvcPath = Schema.Struct({
+    projectId: Schema.String,
+    envId: Schema.String,
+    envSvcId: Schema.String,
+});
+const ProjectOnlyPath = Schema.Struct({ projectId: Schema.String });
+const HistoryQuery = Schema.Struct({
+    envType: Schema.optional(Schema.String),
+    triggeredBy: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.String),
+    serviceId: Schema.optional(Schema.String),
+    limit: Schema.optional(Schema.String),
+});
+const StatusQuery = Schema.Struct({
+    envId: Schema.optional(Schema.String),
+    envType: Schema.optional(Schema.String),
+});
+const ListAppDeploymentsQuery = Schema.Struct({
+    projectId: Schema.String,
+});
+const EnvServiceHistoryQuery = Schema.Struct({
+    limit: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.Literal('queued', 'running', 'building', 'success', 'failed', 'cancelled')),
+    cursor: Schema.optional(Schema.String),
+});
+export const deploymentsEndpoints = {
+    status: defineEndpoint({
+        method: 'GET',
+        path: '/projects/:id/status',
+        params: ProjectIdPath,
+        query: StatusQuery,
+        response: ProjectStatus,
+        summary: 'Aggregate status + per-env health snapshot for a project',
+        tags: ['deployments'],
+    }),
+    get: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/:id',
+        params: DeploymentIdPath,
+        response: DeploymentDetail,
+        summary: 'Detail for a single deployment',
+        tags: ['deployments'],
+    }),
+    trigger: defineEndpoint({
+        method: 'POST',
+        path: '/projects/:id/deploy',
+        params: ProjectIdPath,
+        body: TriggerDeploymentInput,
+        response: DeployResult,
+        summary: 'Trigger a new deployment (GitHub build, image promote, or rebuild)',
+        tags: ['deployments'],
+    }),
+    history: defineEndpoint({
+        method: 'GET',
+        path: '/projects/:id/deployments',
+        params: ProjectIdPath,
+        query: HistoryQuery,
+        response: DeploymentHistoryResult,
+        summary: 'Deployment history for a project/environment',
+        tags: ['deployments'],
+    }),
+    rollback: defineEndpoint({
+        method: 'POST',
+        path: '/projects/:id/rollback',
+        params: ProjectIdPath,
+        body: RollbackDeploymentInput,
+        response: RollbackResult,
+        summary: 'Roll a project/service back to a previous deployment',
+        tags: ['deployments'],
+    }),
+    // ── Env-scoped Console deploy paths (`/deployments/*`) ────────────────────
+    // Added in ADR-084 Wave 3E. These are the env-id-first operations that
+    // the Console uses — the project-id-first shapes above stay the
+    // SDK-facing management surface.
+    envScopedServiceStatus: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/status',
+        response: DeployServiceStatus,
+        summary: 'Deploy service readiness (is the K8s deploy integration configured?)',
+        tags: ['deployments'],
+    }),
+    envScopedListAppDeployments: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/projects',
+        query: ListAppDeploymentsQuery,
+        response: EnvScopedAppDeployments,
+        summary: 'List environments for an app with their current deploy status',
+        tags: ['deployments'],
+    }),
+    envScopedTrigger: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/projects/:envId/deploy',
+        params: EnvIdPath,
+        response: EnvScopedTriggerDeployResult,
+        summary: 'Trigger a new deployment for an app environment (env-id addressed)',
+        tags: ['deployments'],
+    }),
+    envScopedRollbackByCommit: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/projects/:envId/rollback',
+        params: EnvIdPath,
+        body: EnvScopedRollbackByCommitInput,
+        response: EnvScopedRollbackByCommitResult,
+        summary: 'Rollback an env-scoped deployment to a specific commit (legacy commit-based)',
+        tags: ['deployments'],
+    }),
+    envScopedCancelBuild: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/builds/:buildId/cancel',
+        params: BuildIdPath,
+        response: CancelBuildResult,
+        summary: 'Cancel an in-flight build job (idempotent)',
+        tags: ['deployments'],
+    }),
+    envScopedListEnvVars: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/projects/:envId/env',
+        params: EnvIdPath,
+        response: EnvScopedListEnvVarsResult,
+        summary: 'List env vars for an environment (values masked)',
+        tags: ['deployments'],
+    }),
+    envScopedSetEnvVar: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/projects/:envId/env',
+        params: EnvIdPath,
+        body: EnvScopedSetEnvVarInput,
+        response: EnvScopedSetEnvVarResult,
+        summary: 'Set an env var on an environment (encrypted, reconciler-synced)',
+        tags: ['deployments'],
+    }),
+    envScopedDeleteEnvVar: defineEndpoint({
+        method: 'DELETE',
+        path: '/deployments/projects/:envId/env/:key',
+        params: EnvKeyPath,
+        response: EnvScopedDeleteEnvVarResult,
+        summary: 'Delete an env var from an environment',
+        tags: ['deployments'],
+    }),
+    envScopedHistory: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/projects/:envId/deployments',
+        params: EnvIdPath,
+        response: EnvScopedDeploymentHistory,
+        summary: 'Deployment history for an env (all services mixed, env-id addressed)',
+        tags: ['deployments'],
+    }),
+    envScopedHealthStatus: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/projects/:envId/status',
+        params: EnvIdPath,
+        response: EnvScopedAppHealthStatus,
+        summary: 'Health snapshot for a deployed app environment (env-id addressed)',
+        tags: ['deployments'],
+    }),
+    envServiceRollback: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/projects/:projectId/environments/:envId/services/:envSvcId/rollback',
+        params: ProjectEnvSvcPath,
+        body: EnvServiceRollbackInput,
+        response: EnvServiceRollbackResult,
+        summary: 'Roll an env-service back to a previous successful deployment (explicit, digest-targeted)',
+        tags: ['deployments'],
+    }),
+    envServicePromote: defineEndpoint({
+        method: 'POST',
+        path: '/deployments/projects/:projectId/promote',
+        params: ProjectOnlyPath,
+        body: PromoteArtifactInput,
+        response: PromoteArtifactResult,
+        summary: 'Promote an artifact from one env-service to another within the same project (same service)',
+        tags: ['deployments'],
+    }),
+    envServiceHistory: defineEndpoint({
+        method: 'GET',
+        path: '/deployments/projects/:projectId/environments/:envId/services/:envSvcId/deployments',
+        params: ProjectEnvSvcPath,
+        query: EnvServiceHistoryQuery,
+        response: EnvServiceHistoryResult,
+        summary: 'Deployment history scoped to a single env-service with cursor pagination',
+        tags: ['deployments'],
+    }),
+};