Merge branch 'main' into martzoukos/ai-445-pending-mappings-on-pr

Conflict in the confirmation protocol docs: #1410 landed a paragraph on
defaults being omitted from the confirmCommand, in the same spot as this
branch's pinned-target section. Both are wanted — kept the general note
first, then the pinning section.

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

Author: martzoukos

.github/workflows/test.yml

@@ -18,7 +18,48 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # ---------------------------------------------------------------------------
+  # Detects whether anything outside the ignore list below changed. Meta files
+  # (agent instructions, docs, license, .gitignore) cannot affect lint,
+  # packaging or test outcomes, so a change touching only those skips the whole
+  # matrix.
+  #
+  # The filter runs inside a job rather than as an `on: paths-ignore` trigger:
+  # a workflow skipped by a trigger-level path filter never reports a status, so
+  # required checks stay pending forever and block merge. The CI gates below
+  # depend on this job, so if it fails, the gates fail rather than passing on a
+  # matrix that never ran.
+  # ---------------------------------------------------------------------------
+  changes:
+    name: detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          # 'every' makes a file match `code` only when it matches *all* the
+          # patterns, i.e. when it is none of the ignored paths. `code` is
+          # therefore true when at least one changed file lives outside the
+          # ignore list.
+          predicate-quantifier: 'every'
+          filters: |
+            code:
+              - '!.claude/**'
+              - '!AGENTS.md'
+              - '!CLAUDE.md'
+              - '!CONTRIBUTING.md'
+              - '!LICENSE'
+              - '!README.md'
+              - '!.gitignore'
+
   lint:
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -39,6 +80,8 @@ jobs:
   # ---------------------------------------------------------------------------
   test-ubuntu:
     name: test - ubuntu
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -61,6 +104,8 @@ jobs:
           retention-days: 1
   test-windows:
     name: test - windows
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
     runs-on: blacksmith-4vcpu-windows-2025
     steps:
       - uses: actions/checkout@v3
@@ -88,7 +133,8 @@ jobs:
   # ---------------------------------------------------------------------------
   test-e2e-checkly-ubuntu:
     name: e2e - checkly - ubuntu
-    if: github.event_name == 'pull_request'
+    needs: changes
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -110,7 +156,8 @@ jobs:
           CHECKLY_EMPTY_API_KEY: ${{ secrets.E2E_EMPTY_CHECKLY_API_KEY }}
   test-e2e-checkly-windows:
     name: e2e - checkly - windows (${{ matrix.shard }})
-    if: github.event_name == 'pull_request'
+    needs: changes
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -140,7 +187,8 @@ jobs:
   # ---------------------------------------------------------------------------
   test-e2e-create-checkly-ubuntu:
     name: e2e - create-checkly - ubuntu
-    if: github.event_name == 'pull_request'
+    needs: changes
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -155,7 +203,8 @@ jobs:
       - run: pnpm --filter create-checkly run test:e2e
   test-e2e-create-checkly-windows:
     name: e2e - create-checkly - windows
-    if: github.event_name == 'pull_request'
+    needs: changes
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
     runs-on: blacksmith-4vcpu-windows-2025
     steps:
       - uses: actions/checkout@v3
@@ -179,6 +228,7 @@ jobs:
     name: CI gate - ubuntu
     if: always()
     needs:
+      - changes
       - lint
       - test-ubuntu
       - test-e2e-checkly-ubuntu
@@ -189,8 +239,11 @@ jobs:
         run: |
           results="${{ join(needs.*.result, ', ') }}"
           echo "Ubuntu job results: $results"
-          # 'skipped' is allowed (e2e jobs are skipped on push-to-main); only
-          # 'failure'/'cancelled' should fail the gate.
+          # 'skipped' is allowed (e2e jobs are skipped on push-to-main, and
+          # every job is skipped for meta-file-only changes); only
+          # 'failure'/'cancelled' should fail the gate. `changes` is a
+          # dependency so that a failure to compute the path filter fails the
+          # gate instead of green-lighting a matrix that never ran.
           if [[ "$results" == *failure* || "$results" == *cancelled* ]]; then
             echo "::error::One or more Ubuntu jobs did not succeed"
             exit 1
@@ -199,6 +252,7 @@ jobs:
     name: CI gate - windows
     if: always()
     needs:
+      - changes
       - test-windows
       - test-e2e-checkly-windows
       - test-e2e-create-checkly-windows

eslint.config.mjs

@@ -43,6 +43,9 @@ const checklyStyle = {
 
 export default defineConfig([
   globalIgnores([
+    // Holds git worktrees, each a full checkout of the repo with its own
+    // in-progress code that must not be linted as part of this checkout.
+    '**/.claude/',
     '**/dist/',
     `**/gen/`,
     '**/__checks__/**/*.spec.{js,ts,mjs}',

packages/cli/src/ai-context/references/communicate.md

@@ -20,11 +20,13 @@ Write commands (`incidents create`, `incidents update`, `incidents resolve`, `de
 **Rules for agents:**
 
 1. When exit code is 2 and output contains `"status": "confirmation_required"`, **always present the `changes` array to the user** and ask for confirmation.
-2. **Never auto-append `--force`** — only run the `confirmCommand` after the user explicitly approves.
+2. **Run the `confirmCommand` verbatim, and only after the user explicitly approves.** It is normally the command you just ran, plus `--force` to skip the second prompt. Don't append `--force` to anything yourself, and don't edit the `confirmCommand` — changing its flags changes what you were authorized to do.
 3. This applies to **every** write command, not just the first one. Incident updates and resolutions also require confirmation.
 4. Use `--dry-run` to preview what a command will do without executing or prompting.
 5. Read-only commands (`incidents list`, `status-pages list`) execute immediately without confirmation.
 
+The `confirmCommand` omits flags left at their default, so a bare `npx checkly deploy` confirms as `checkly deploy --force` rather than echoing back every boolean the parser filled in. Treat every flag you see there as deliberate.
+
 ### Commands that pin a resolved target
 
 A command that picks its own target before confirming writes that target back into the `confirmCommand`. `import commit` and `import cancel` do this: run without `--plan-id` they select the only candidate plan themselves, and confirm as `checkly import commit --plan-id="<resolved-id>" --force` — carrying a flag you never passed. That is deliberate: the pinned ID guarantees the approved run acts on the plan whose `changes` you showed the user, not on whatever happens to be pending by then. Run the `confirmCommand` exactly as returned; do not strip the flag or fall back to the bare command.

packages/cli/src/ai-context/references/configure-traceroute-monitors.md

@@ -8,6 +8,7 @@
 - Use `request.maxHops` (default: 30) and `request.maxUnknownHops` (default: 15) to control trace depth.
 - Use `degradedResponseTime` and `maxResponseTime` (milliseconds) to configure response time thresholds.
 - Traceroute assertions support `RESPONSE_TIME`, `HOP_COUNT`, and `PACKET_LOSS` sources.
+- `TracerouteAssertionBuilder.responseTime()` takes an optional property — `'avg'` (default), `'min'`, `'max'`, or `'stdDev'`. `hopCount()` and `packetLoss()` take no property.
 - **Plan-gated properties:** `retryStrategy`, `runParallel`, and higher frequencies are not available on all plans. Check entitlements matching `UPTIME_CHECKS_*` before using these. Omit any property whose entitlement is disabled. See `npx checkly skills manage` for details.
 
 <!-- EXAMPLE: TRACEROUTE_MONITOR -->

packages/cli/src/ai-context/references/configure.md

@@ -75,3 +75,26 @@ Run `npx checkly skills manage plan` for the full reference.
 ## Deploying
 
 - Deploy checks using the `npx checkly deploy` command. Use `--output` to see the created, updated, and deleted resources. Use `--verbose` to also include each resource's name and physical ID (UUID), which is useful for programmatically referencing deployed resources (e.g. `npx checkly checks get <id>`).
+- Use `--preview` to see what a deploy would change without applying it.
+
+### Deleted resources
+
+A deploy makes the account match the code. **Any resource that was deployed before and is no longer in the code gets deleted, along with its run history.** Pass `--preserve-resources` to keep those resources and their history in the Checkly account instead, where the user can manage them from the web app.
+
+This matters when the local project isn't the whole picture — a partial checkout, or a project whose checks were also edited elsewhere. If you're not sure the code is the complete source of truth, say so before deploying.
+
+### Confirmation
+
+`deploy` is a write command: without `--force` it returns exit code 2 and a `confirmation_required` envelope. Present its `changes` to the user and run the `confirmCommand` verbatim only after they approve.
+
+That confirmation happens **before the project is parsed**, so it cannot tell you which resources would be deleted — its `changes` only warn that deletion is possible. There is a second, itemised guard that lists each doomed resource by name, but it is skipped by `--force`, and `--force` is exactly what the `confirmCommand` carries. **An agent following the confirmation protocol never sees that list.** It is a prompt for humans deploying by hand.
+
+So when resources may have been removed from the code, don't rely on the confirmation to surface it — preview first:
+
+```bash
+npx checkly deploy --preview
+```
+
+This is a dry run: nothing is applied and nothing is confirmed. It prints the resources that would be created, updated, and deleted (add `--verbose` for names and IDs). Show the user what would be deleted, and only then deploy.
+
+Run `npx checkly skills communicate` for the full protocol.

packages/cli/src/ai-context/skill.md

@@ -34,9 +34,11 @@ Run `npx checkly skills manage` for the full reference.
 
 ## Confirmation Protocol
 
-Write commands (e.g. `incidents create`, `deploy`, `destroy`) return exit code 2 with a `confirmation_required` JSON envelope instead of executing. **Always present the `changes` to the user and wait for approval before running the `confirmCommand`.** Never auto-append `--force`. This applies to every write command individually — updates and resolutions need confirmation too, not just the initial create.
+Write commands (e.g. `incidents create`, `deploy`, `destroy`) return exit code 2 with a `confirmation_required` JSON envelope instead of executing. **Always present the `changes` to the user and wait for approval before running the `confirmCommand`.** This applies to every write command individually — updates and resolutions need confirmation too, not just the initial create.
 
-Run `npx checkly skills communicate` for the full protocol details.
+The `confirmCommand` is the approved command, ready to run verbatim: it repeats the flags you passed and already ends in `--force`. Run it as-is once the user approves — don't add `--force` to a command yourself, and don't add flags the user didn't ask for.
+
+Run `npx checkly skills communicate` for the full protocol details, or `npx checkly skills configure` for what `deploy` confirms.
 
 ## API Pass-Through (fallback for any endpoint)
 

packages/cli/src/commands/__tests__/confirm-flow-deploy.spec.ts

@@ -1,3 +1,4 @@
+import { Parser } from '@oclif/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('../../helpers/cli-mode', () => ({
@@ -39,11 +40,23 @@ vi.mock('prompts', () => ({
 }))
 
 import { detectCliMode } from '../../helpers/cli-mode.js'
+import { buildConfirmCommand } from '../../helpers/command-preview.js'
 import * as api from '../../rest/api.js'
 import { parseProject } from '../../services/project-parser.js'
 import { AuthCommand } from '../authCommand.js'
 import Deploy from '../deploy.js'
 
+/** Turn a generated confirmCommand back into argv, so oclif can re-parse it. */
+function flagArgv (confirmCommand: string): string[] {
+  return [...confirmCommand.matchAll(/--[a-zA-Z0-9-]+(?:="[^"]*")?/g)]
+    .map(([token]) => token.replace(/="(.*)"$/, '=$1'))
+}
+
+async function confirmCommandFor (argv: string[]): Promise<string> {
+  const { flags, metadata } = await Parser.parse(argv, { flags: Deploy.flags, strict: true })
+  return buildConfirmCommand('deploy', flags, undefined, metadata.flags)
+}
+
 function createConfirmContext () {
   const logged: string[] = []
   let exitCodeValue: number | undefined
@@ -156,6 +169,17 @@ describe('deploy confirmation flow', () => {
         'debug-bundle': false,
         'debug-bundle-output-file': './debug-bundle.json',
       },
+      metadata: {
+        flags: {
+          'preview': { setFromDefault: true },
+          'output': { setFromDefault: true },
+          'verbose': { setFromDefault: true },
+          'schedule-on-deploy': { setFromDefault: true },
+          'verify-runtime-dependencies': { setFromDefault: true },
+          'debug-bundle': { setFromDefault: true },
+          'debug-bundle-output-file': { setFromDefault: true },
+        },
+      },
     })
 
     await expect(
@@ -172,5 +196,28 @@ describe('deploy confirmation flow', () => {
     expect(output.command).toBe('deploy')
     expect(output.classification.idempotent).toBe(true)
     expect(output.confirmCommand).toContain('--force')
+    expect(output.confirmCommand).not.toContain('--no-preview')
+  })
+})
+
+describe('deploy confirmCommand', () => {
+  it('echoes only the flags the user typed', async () => {
+    expect(await confirmCommandFor([])).toBe('checkly deploy --force')
+    expect(await confirmCommandFor(['--preserve-resources'])).toBe('checkly deploy --preserve-resources --force')
+  })
+
+  it('keeps an explicit --no-<flag> for flags that allow it', async () => {
+    expect(await confirmCommandFor(['--no-schedule-on-deploy']))
+      .toBe('checkly deploy --no-schedule-on-deploy --force')
+  })
+
+  it('generates a command oclif can parse back', async () => {
+    for (const argv of [[], ['--preserve-resources'], ['--no-schedule-on-deploy'], ['--verbose']]) {
+      const confirmCommand = await confirmCommandFor(argv)
+      await expect(
+        Parser.parse(flagArgv(confirmCommand), { flags: Deploy.flags, strict: true }),
+        `confirmCommand for "checkly deploy ${argv.join(' ')}" must be runnable: ${confirmCommand}`,
+      ).resolves.toBeDefined()
+    }
   })
 })

packages/cli/src/commands/__tests__/confirm-flow-destroy.spec.ts

@@ -1,3 +1,4 @@
+import { Parser } from '@oclif/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('../../helpers/cli-mode', () => ({
@@ -29,14 +30,26 @@ vi.mock('prompts', () => ({
 import { detectCliMode } from '../../helpers/cli-mode.js'
 import prompts from 'prompts'
 import * as api from '../../rest/api.js'
+import { buildConfirmCommand } from '../../helpers/command-preview.js'
 import { AuthCommand } from '../authCommand.js'
 import Destroy from '../destroy.js'
 
-function createCommandContext (parsed: unknown) {
+/** Turn a generated confirmCommand back into argv, so oclif can re-parse it. */
+function flagArgv (confirmCommand: string): string[] {
+  return [...confirmCommand.matchAll(/--[a-zA-Z0-9-]+(?:="[^"]*")?/g)]
+    .map(([token]) => token.replace(/="(.*)"$/, '=$1'))
+}
+
+async function confirmCommandFor (argv: string[]): Promise<string> {
+  const { flags, metadata } = await Parser.parse(argv, { flags: Destroy.flags, strict: true })
+  return buildConfirmCommand('destroy', flags, undefined, metadata.flags)
+}
+
+function createCommandContext (parsed: { flags: Record<string, unknown>, metadata?: unknown }) {
   const logged: string[] = []
   let exitCodeValue: number | undefined
   return {
-    parse: vi.fn().mockResolvedValue(parsed),
+    parse: vi.fn().mockResolvedValue({ metadata: { flags: {} }, ...parsed }),
     log: vi.fn((msg?: string) => {
       if (msg) logged.push(msg)
     }),
@@ -172,3 +185,20 @@ describe('destroy confirmation flow', () => {
     expect(Destroy.idempotent).toBe(false)
   })
 })
+
+describe('destroy confirmCommand', () => {
+  it('echoes only the flags the user typed', async () => {
+    expect(await confirmCommandFor([])).toBe('checkly destroy --force')
+    expect(await confirmCommandFor(['--preserve-resources'])).toBe('checkly destroy --preserve-resources --force')
+  })
+
+  it('generates a command oclif can parse back', async () => {
+    for (const argv of [[], ['--preserve-resources'], ['--cancel-in-progress-deployment']]) {
+      const confirmCommand = await confirmCommandFor(argv)
+      await expect(
+        Parser.parse(flagArgv(confirmCommand), { flags: Destroy.flags, strict: true }),
+        `confirmCommand for "checkly destroy ${argv.join(' ')}" must be runnable: ${confirmCommand}`,
+      ).resolves.toBeDefined()
+    }
+  })
+})

packages/cli/src/commands/deploy.ts

@@ -110,7 +110,7 @@ export default class Deploy extends AuthCommand {
   }
 
   async run (): Promise<void> {
-    const { flags } = await this.parse(Deploy)
+    const { flags, metadata } = await this.parse(Deploy)
     const {
       force,
       preview,
@@ -146,6 +146,7 @@ export default class Deploy extends AuthCommand {
             : 'Delete any resources removed from code, losing their run history. Pass --preserve-resources to keep them in your Checkly account instead',
         ],
         flags,
+        flagMetadata: metadata.flags,
         classification: {
           readOnly: Deploy.readOnly,
           destructive: Deploy.destructive,
@@ -316,6 +317,7 @@ export default class Deploy extends AuthCommand {
               `Delete ${PRETTY_RESOURCE_TYPES[resourceType] ?? resourceType}: ${logicalId}`),
           ],
           flags,
+          flagMetadata: metadata.flags,
           classification: {
             readOnly: Deploy.readOnly,
             destructive: Deploy.destructive,

packages/cli/src/commands/destroy.ts

@@ -31,7 +31,7 @@ export default class Destroy extends AuthCommand {
   }
 
   async run (): Promise<void> {
-    const { flags } = await this.parse(Destroy)
+    const { flags, metadata } = await this.parse(Destroy)
     const {
       config: configFilename,
       'preserve-resources': preserveResources,
@@ -52,6 +52,7 @@ export default class Destroy extends AuthCommand {
           : `PERMANENTLY delete ALL resources associated with the project "${checklyConfig.projectName}" in account "${account.name}"`,
       ],
       flags,
+      flagMetadata: metadata.flags,
       classification: {
         readOnly: Destroy.readOnly,
         destructive: Destroy.destructive,