feat(cli): add deploy --preserve-resources + destructive-delete guard (AI-426) [ship] (#1390)

* feat(cli): add deploy --preserve-resources + destructive-delete guard (AI-426)

`checkly deploy --preserve-resources` detaches resources removed from code
(kept in the account, returned to UI management) instead of deleting them,
forwarding preserveResources to the deploy endpoint and rendering the removed
resources as "Detached" in the preview.

Default deploy now guards against silent data loss: for an interactive,
non-forced run a preflight dry-run surfaces any resources that would be
permanently deleted and requires an explicit confirmation (skipped by --force).
The pre-deploy summary also advertises --preserve-resources.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): read DETACHED deploy action from backend (AI-426)

The deploy preview now reads an explicit DETACHED action from the diff
instead of inferring detachment solely from the client-side
--preserve-resources flag. Detached resources render in their own
"Detached (kept in account, now UI-managed)" section, separate from
"Delete:".

Backwards compatible both ways: older backends that still return DELETE
for preserved resources are folded into the detached bucket when
--preserve-resources is set, and older CLIs simply ignore the unknown
DETACHED action (no crash, since the action field is an unvalidated
string matched by an if/else chain).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(cli): address deploy --preserve-resources review feedback (AI-426)

- Add StatusPage and StatusPageService to PRETTY_RESOURCE_TYPES so they
  render with friendly names in delete/detach previews and guards.
- Reword user-facing "UI" references to "Checkly Webapp".
- Replace the em dash before --preserve-resources with a period for
  readability.
- Remove the transitional DELETE-to-detach display fallback in
  formatPreview (and its now-unused preserveResources param); the backend
  ships before the CLI and always emits DETACHED.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(cli): only send preserveResources deploy param when opted in (AI-426)

The /v1/projects/deploy endpoint rejects unknown query params, and the
deploy-side backend support for preserveResources is not deployed yet, so
sending preserveResources=false on every deploy made all deploys fail with
`"preserveResources" is not allowed` (all e2e deploy tests red).

preserveResources=false is identical to the backend's default (delete
resources removed from code), so omit the param unless the user opted in
with --preserve-resources. Default deploys are now byte-for-byte identical
to before the feature; the param only rides along when explicitly requested
(which requires the deploy-side backend support to ship first).

Also fix the merged projects-deploy unit test to drive the async
event-stream deploy, and update assertions to the conditional param.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: martzoukos

packages/cli/src/commands/deploy.ts

@@ -9,7 +9,7 @@ import {
   Check, AlertChannelSubscription, AlertChannel, CheckGroup, Dashboard,
   MaintenanceWindow, PrivateLocation, PrivateLocationCheckAssignment, PrivateLocationGroupAssignment,
   Project, ProjectData, Diagnostics,
-  Session,
+  Session, StatusPage, StatusPageService,
 } from '../constructs/index.js'
 import chalk from 'chalk'
 import { splitConfigFilePath, getGitInformation } from '../services/util.js'
@@ -27,8 +27,30 @@ enum ResourceDeployStatus {
   UPDATE = 'UPDATE',
   CREATE = 'CREATE',
   DELETE = 'DELETE',
+  // Returned by newer backends for resources removed from code that are kept in
+  // the account (detached, now managed in the Checkly Webapp) instead of deleted.
+  DETACHED = 'DETACHED',
 }
 
+const PRETTY_RESOURCE_TYPES: Record<string, string> = {
+  [Check.__checklyType]: 'Check',
+  [AlertChannel.__checklyType]: 'AlertChannel',
+  [CheckGroup.__checklyType]: 'CheckGroup',
+  [MaintenanceWindow.__checklyType]: 'MaintenanceWindow',
+  [PrivateLocation.__checklyType]: 'PrivateLocation',
+  [Dashboard.__checklyType]: 'Dashboard',
+  [StatusPage.__checklyType]: 'StatusPage',
+  [StatusPageService.__checklyType]: 'StatusPageService',
+}
+
+// Internal resources that users don't create directly. They are reported as
+// part of their owning check, so we exclude them from delete previews/guards.
+const NON_REPORTED_TYPES = [
+  AlertChannelSubscription.__checklyType,
+  PrivateLocationCheckAssignment.__checklyType,
+  PrivateLocationGroupAssignment.__checklyType,
+]
+
 export default class Deploy extends AuthCommand {
   static coreCommand = true
   static hidden = false
@@ -56,6 +78,10 @@ export default class Deploy extends AuthCommand {
       default: true,
       allowNo: true,
     }),
+    'preserve-resources': Flags.boolean({
+      description: 'Detach resources removed from code (keep them and their run history) instead of deleting them.',
+      default: false,
+    }),
     'force': forceFlag(),
     'cancel-in-progress-deployment': Flags.boolean({
       description: 'If a deployment for this project is already in progress, cancel it instead of waiting for it to finish.',
@@ -90,6 +116,7 @@ export default class Deploy extends AuthCommand {
       preview,
       'cancel-in-progress-deployment': cancelInProgress,
       'schedule-on-deploy': scheduleOnDeploy,
+      'preserve-resources': preserveResources,
       output: outputFlag,
       verbose,
       config: configFilename,
@@ -114,6 +141,9 @@ export default class Deploy extends AuthCommand {
           scheduleOnDeploy
             ? 'Schedule checks after deploy'
             : 'Checks will NOT be scheduled after deploy',
+          preserveResources
+            ? 'Detach any resources removed from code, keeping them and their run history for management in the Checkly Webapp'
+            : 'Delete any resources removed from code, losing their run history. Pass --preserve-resources to detach and keep them instead',
         ],
         flags,
         classification: {
@@ -244,6 +274,48 @@ export default class Deploy extends AuthCommand {
       return
     }
 
+    // Preflight destructive-delete guard. Deletions are only known from the diff,
+    // which we don't have until after a deploy call. For a non-preview, non-preserve
+    // run that isn't already forced, do a dry-run first to surface resources that
+    // would be permanently deleted and require an explicit confirmation.
+    if (!preview && !preserveResources && !force) {
+      let deletions: Array<{ resourceType: string, logicalId: string }> = []
+      try {
+        const { data: dryRunData } = await api.projects.deploy(
+          { ...projectPayload, repoInfo },
+          { dryRun: true, scheduleOnDeploy, preserveResources },
+        )
+        deletions = this.collectDeletions(dryRunData)
+      } catch (err: any) {
+        this.style.longError(`Your project could not be deployed.`, err)
+        this.exit(1)
+      }
+
+      if (deletions.length) {
+        this.log(chalk.bold.red('\nThe following resources were removed from code and will be DELETED, losing their run history:'))
+        for (const { resourceType, logicalId } of deletions) {
+          this.log(chalk.red(`    ${PRETTY_RESOURCE_TYPES[resourceType] ?? resourceType}: ${logicalId}`))
+        }
+        this.log(chalk.yellow('\nPass --preserve-resources to detach and keep them (and their run history) instead.\n'))
+
+        await this.confirmOrAbort({
+          command: 'deploy',
+          description: 'Delete resources removed from code',
+          changes: [
+            `Permanently delete ${deletions.length} resource(s) removed from code, losing their run history`,
+            ...deletions.map(({ resourceType, logicalId }) =>
+              `Delete ${PRETTY_RESOURCE_TYPES[resourceType] ?? resourceType}: ${logicalId}`),
+          ],
+          flags,
+          classification: {
+            readOnly: Deploy.readOnly,
+            destructive: Deploy.destructive,
+            idempotent: Deploy.idempotent,
+          },
+        }, { force })
+      }
+    }
+
     try {
       if (!preview) {
         this.style.actionStart('Deploying project')
@@ -253,6 +325,7 @@ export default class Deploy extends AuthCommand {
         {
           dryRun: preview,
           scheduleOnDeploy,
+          preserveResources,
           cancelInProgress,
           onProgress: preview ? undefined : progress => this.style.actionStatus(`${progress}% complete`),
           onStatus: preview ? undefined : message => this.style.actionStatus(message),
@@ -299,13 +372,30 @@ export default class Deploy extends AuthCommand {
     }
   }
 
-  private formatPreview (previewData: ProjectDeployResponse, project: Project, verbose = false): string {
+  private collectDeletions (previewData: ProjectDeployResponse): Array<{ resourceType: string, logicalId: string }> {
+    return (previewData?.diff ?? [])
+      .filter(change =>
+        change.action === ResourceDeployStatus.DELETE
+        && !NON_REPORTED_TYPES.some(t => t === change.type),
+      )
+      .map(({ type, logicalId }) => ({ resourceType: type, logicalId }))
+      .sort((a, b) =>
+        a.resourceType.localeCompare(b.resourceType) || a.logicalId.localeCompare(b.logicalId),
+      )
+  }
+
+  private formatPreview (
+    previewData: ProjectDeployResponse,
+    project: Project,
+    verbose = false,
+  ): string {
     // Current format of the data is: { checks: { logical-id-1: 'UPDATE' }, groups: { another-logical-id: 'CREATE' } }
     // We convert it into update: [{ logicalId, resourceType, construct }, ...], create: [], delete: []
     // This makes it easier to display.
     const updating = []
     const creating = []
     const deleting: Array<{ resourceType: string, logicalId: string }> = []
+    const detaching: Array<{ resourceType: string, logicalId: string }> = []
     for (const change of previewData?.diff ?? []) {
       const { type, logicalId, physicalId, action } = change
       if ([
@@ -325,6 +415,10 @@ export default class Deploy extends AuthCommand {
       } else if (action === ResourceDeployStatus.DELETE) {
         // Since the resource is being deleted, the construct isn't in the project.
         deleting.push({ resourceType: type, logicalId })
+      } else if (action === ResourceDeployStatus.DETACHED) {
+        // Newer backends report detached resources explicitly. The construct
+        // isn't in the project since it was removed from code.
+        detaching.push({ resourceType: type, logicalId })
       }
     }
 
@@ -366,7 +460,11 @@ export default class Deploy extends AuthCommand {
     const sortedDeleting = deleting
       .sort(compareEntries)
 
-    if (!sortedCreating.length && !sortedDeleting.length && !sortedUpdating.length && !skipping.length) {
+    const sortedDetaching = detaching
+      .sort(compareEntries)
+
+    if (!sortedCreating.length && !sortedDeleting.length && !sortedDetaching.length
+      && !sortedUpdating.length && !skipping.length) {
       return '\nNo checks were detected. More information on how to set up a Checkly CLI project is available at https://checklyhq.com/docs/cli/.\n'
     }
 
@@ -387,16 +485,15 @@ export default class Deploy extends AuthCommand {
     }
     if (sortedDeleting.length) {
       output.push(chalk.bold.red('Delete:'))
-      const prettyResourceTypes: Record<string, string> = {
-        [Check.__checklyType]: 'Check',
-        [AlertChannel.__checklyType]: 'AlertChannel',
-        [CheckGroup.__checklyType]: 'CheckGroup',
-        [MaintenanceWindow.__checklyType]: 'MaintenanceWindow',
-        [PrivateLocation.__checklyType]: 'PrivateLocation',
-        [Dashboard.__checklyType]: 'Dashboard',
-      }
       for (const { resourceType, logicalId } of sortedDeleting) {
-        output.push(`    ${prettyResourceTypes[resourceType] ?? resourceType}: ${logicalId}`)
+        output.push(`    ${PRETTY_RESOURCE_TYPES[resourceType] ?? resourceType}: ${logicalId}`)
+      }
+      output.push('')
+    }
+    if (sortedDetaching.length) {
+      output.push(chalk.bold.yellow('Detached (kept in account, now managed in the Checkly Webapp):'))
+      for (const { resourceType, logicalId } of sortedDetaching) {
+        output.push(`    ${PRETTY_RESOURCE_TYPES[resourceType] ?? resourceType}: ${logicalId}`)
       }
       output.push('')
     }

packages/cli/src/rest/__tests__/projects-deploy.spec.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi } from 'vitest'
+import { Readable } from 'node:stream'
+import type { AxiosInstance } from 'axios'
+import Projects, { type ProjectSync } from '../projects.js'
+
+// Build an SSE frame and a readable stream that emits the given frames then ends.
+const sse = (event: string, data: unknown) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+const sseStream = (...frames: string[]) => ({ data: Readable.from(frames) })
+
+const applied = { project: { name: 'p', logicalId: 'p' }, diff: [] }
+
+function createProjects () {
+  // A real (non-dry-run) deploy submits, then follows the SSE stream to completion,
+  // so post returns a deployment id and get yields a terminal 'complete' frame.
+  const post = vi.fn().mockResolvedValue({ data: { id: 'dep-1', status: 'PENDING' } })
+  const get = vi.fn().mockResolvedValue(
+    sseStream(sse('complete', { id: 'dep-1', status: 'SUCCEEDED', progress: 100, result: applied, error: null })),
+  )
+  const api = { post, get } as unknown as AxiosInstance
+  return { projects: new Projects(api), post }
+}
+
+const resources: ProjectSync = {
+  project: { name: 'p', logicalId: 'p' },
+  resources: [],
+  repoInfo: null,
+}
+
+describe('Projects.deploy query params', () => {
+  it('omits preserveResources by default', async () => {
+    const { projects, post } = createProjects()
+    await projects.deploy(resources)
+    const url = post.mock.calls[0][0] as string
+    expect(url).toContain('dryRun=false')
+    expect(url).toContain('scheduleOnDeploy=true')
+    expect(url).not.toContain('preserveResources')
+  })
+
+  it('forwards preserveResources=true', async () => {
+    const { projects, post } = createProjects()
+    await projects.deploy(resources, { dryRun: true, scheduleOnDeploy: false, preserveResources: true })
+    const url = post.mock.calls[0][0] as string
+    expect(url).toContain('dryRun=true')
+    expect(url).toContain('scheduleOnDeploy=false')
+    expect(url).toContain('preserveResources=true')
+  })
+})

packages/cli/src/rest/__tests__/projects.spec.ts

@@ -54,6 +54,19 @@ describe('Projects.deploy', () => {
     expect(data).toEqual(preview)
   })
 
+  it('omits preserveResources by default and only sends it when opted in', async () => {
+    const preview = { project: sync.project, diff: [] }
+    vi.mocked(api.post).mockResolvedValue({ data: preview })
+
+    await projects.deploy(sync, { dryRun: true })
+    expect(vi.mocked(api.post).mock.calls[0][0]).toBe('/v1/projects/deploy?dryRun=true&scheduleOnDeploy=true')
+
+    await projects.deploy(sync, { dryRun: true, preserveResources: true })
+    expect(vi.mocked(api.post).mock.calls[1][0]).toBe(
+      '/v1/projects/deploy?dryRun=true&scheduleOnDeploy=true&preserveResources=true',
+    )
+  })
+
   it('submits async, follows the SSE stream, reports progress, and returns the applied diff', async () => {
     vi.mocked(api.post).mockResolvedValue({ data: { id: 'dep-1', status: 'PENDING' } })
     vi.mocked(api.get).mockResolvedValue(

packages/cli/src/rest/projects.ts

@@ -378,9 +378,21 @@ class Projects {
    */
   async deploy (
     resources: ProjectSync,
-    { dryRun = false, scheduleOnDeploy = true, cancelInProgress = false, onProgress, onStatus }: {
+    {
+      dryRun = false,
+      scheduleOnDeploy = true,
+      preserveResources = false,
+      cancelInProgress = false,
+      onProgress,
+      onStatus,
+    }: {
       dryRun?: boolean
       scheduleOnDeploy?: boolean
+      /**
+       * Detach resources removed from code (keep them and their run history)
+       * instead of deleting them.
+       */
+      preserveResources?: boolean
       /**
        * On a 409 (another deployment is already in progress), cancel that
        * deployment instead of waiting for it to finish, then retry.
@@ -402,7 +414,7 @@ class Projects {
     const deadlineAt = Date.now() + DEPLOY_CONFLICT_WAIT_DEADLINE_MS
     for (;;) {
       try {
-        return await this.submitDeployment(resources, { dryRun, scheduleOnDeploy, onProgress })
+        return await this.submitDeployment(resources, { dryRun, scheduleOnDeploy, preserveResources, onProgress })
       } catch (err) {
         if (
           dryRun
@@ -424,14 +436,19 @@ class Projects {
 
   private async submitDeployment (
     resources: ProjectSync,
-    { dryRun, scheduleOnDeploy, onProgress }: {
+    { dryRun, scheduleOnDeploy, preserveResources, onProgress }: {
       dryRun: boolean
       scheduleOnDeploy: boolean
+      preserveResources: boolean
       onProgress?: (progress: number) => void
     },
   ): Promise<{ data: ProjectDeployResponse }> {
+    // Only send preserveResources when the user opted in. The endpoint rejects
+    // unknown query params, and preserveResources=false is the default (delete)
+    // behavior, so omitting it keeps default deploys backwards compatible.
+    const preserveParam = preserveResources ? '&preserveResources=true' : ''
     const { data } = await this.api.post<ProjectDeployResponse | ProjectDeployment>(
-      `/v1/projects/deploy?dryRun=${dryRun}&scheduleOnDeploy=${scheduleOnDeploy}`,
+      `/v1/projects/deploy?dryRun=${dryRun}&scheduleOnDeploy=${scheduleOnDeploy}${preserveParam}`,
       resources,
       { transformRequest: compressJSONPayload },
     )