@camunda8/cli 2.7.0-alpha.9 → 2.8.0-alpha.1

package/dist/commands/deployments.js

@@ -5,12 +5,13 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { TenantId } from "@camunda8/orchestration-cluster-api";
 import { createClient } from "../client.js";
-import { defineCommand } from "../command-framework.js";
-import { resolveClusterConfig, resolveTenantId } from "../config.js";
+import { defineCommand, dryRun } from "../command-framework.js";
+import { resolveTenantId } from "../config.js";
+import { normalizeToError, SilentError } from "../errors.js";
 import { isIgnored, loadIgnoreRules } from "../ignore.js";
 import { getLogger, isRecord } from "../logger.js";
 import { c8ctl } from "../runtime.js";
-const RESOURCE_EXTENSIONS = [".bpmn", ".dmn", ".form"];
+import { DEPLOYABLE_EXTENSIONS } from "./resource-extensions.js";
 const PROCESS_APPLICATION_FILE = ".process-application";
 /**
  * Helper to output messages that respect JSON mode for Unix pipe compatibility
@@ -89,7 +90,7 @@ function findGroupRoot(filePath, basePath) {
 /**
  * Recursively collect resource files from a directory
  */
-function collectResourceFiles(dirPath, collected = [], basePath, ig, ignoreBaseDir) {
+function collectResourceFiles(dirPath, collected = [], basePath, ig, ignoreBaseDir, force) {
     if (!existsSync(dirPath)) {
         return collected;
     }
@@ -102,18 +103,19 @@ function collectResourceFiles(dirPath, collected = [], basePath, ig, ignoreBaseD
         if (ig && ignoreBaseDir && isIgnored(ig, dirPath, ignoreBaseDir)) {
             return collected;
         }
-        const ext = extname(dirPath);
-        if (RESOURCE_EXTENSIONS.includes(ext)) {
-            const groupInfo = findGroupRoot(dirPath, basePath);
-            collected.push({
-                path: dirPath,
-                name: basename(dirPath),
-                content: readFileSync(dirPath),
-                isBuildingBlock: groupInfo.type === "bb",
-                isProcessApplication: groupInfo.type === "pa",
-                groupPath: groupInfo.root || undefined,
-            });
+        // Unless --force, reject files with unsupported extensions
+        if (!force && !DEPLOYABLE_EXTENSIONS.includes(extname(dirPath))) {
+            return collected;
         }
+        const groupInfo = findGroupRoot(dirPath, basePath);
+        collected.push({
+            path: dirPath,
+            name: basename(dirPath),
+            content: readFileSync(dirPath),
+            isBuildingBlock: groupInfo.type === "bb",
+            isProcessApplication: groupInfo.type === "pa",
+            groupPath: groupInfo.root || undefined,
+        });
         return collected;
     }
     if (stat.isDirectory()) {
@@ -144,35 +146,40 @@ function collectResourceFiles(dirPath, collected = [], basePath, ig, ignoreBaseD
                 }
             }
             else if (entryStat.isFile()) {
+                // Skip hidden files (e.g. .c8ignore, .process-application)
+                if (entry.startsWith(".")) {
+                    return;
+                }
                 // Skip ignored files
                 if (ig && ignoreBaseDir && isIgnored(ig, fullPath, ignoreBaseDir)) {
                     return;
                 }
+                // Unless --force, only collect files with known deployable extensions
+                if (!force && !DEPLOYABLE_EXTENSIONS.includes(extname(fullPath))) {
+                    return;
+                }
                 files.push(fullPath);
             }
         });
         // Process files in current directory first
         files.forEach((file) => {
-            const ext = extname(file);
-            if (RESOURCE_EXTENSIONS.includes(ext)) {
-                const groupInfo = findGroupRoot(file, basePath);
-                collected.push({
-                    path: file,
-                    name: basename(file),
-                    content: readFileSync(file),
-                    isBuildingBlock: groupInfo.type === "bb",
-                    isProcessApplication: groupInfo.type === "pa",
-                    groupPath: groupInfo.root || undefined,
-                });
-            }
+            const groupInfo = findGroupRoot(file, basePath);
+            collected.push({
+                path: file,
+                name: basename(file),
+                content: readFileSync(file),
+                isBuildingBlock: groupInfo.type === "bb",
+                isProcessApplication: groupInfo.type === "pa",
+                groupPath: groupInfo.root || undefined,
+            });
         });
         // Process building block folders first (prioritized)
         bbFolders.forEach((bbFolder) => {
-            collectResourceFiles(bbFolder, collected, basePath, ig, ignoreBaseDir);
+            collectResourceFiles(bbFolder, collected, basePath, ig, ignoreBaseDir, force);
         });
         // Then process regular folders
         regularFolders.forEach((regularFolder) => {
-            collectResourceFiles(regularFolder, collected, basePath, ig, ignoreBaseDir);
+            collectResourceFiles(regularFolder, collected, basePath, ig, ignoreBaseDir, force);
         });
     }
     return collected;
@@ -193,195 +200,249 @@ function findDuplicateDefinitionIds(resources) {
     return new Map([...idMap].filter(([, paths]) => paths.length > 1));
 }
 /**
- * Deploy resources
+ * Collect deployable resources from the given paths, applying `.c8ignore`
+ * rules. Throws on the two pre-API guard failures so callers (deploy
+ * handler, watch, dry-run preview) all surface the same errors with the
+ * same wording.
+ *
+ * Shared between `deployCommand` (used for both the dry-run preview and
+ * the execute path via `deployResources`) and `deployResources` itself.
  */
-export async function deploy(paths, options) {
+function collectResourcesForPaths(paths, force) {
+    if (paths.length === 0) {
+        throw new Error("No paths provided. Use: c8 deploy <path> or c8 deploy (for current directory)");
+    }
+    // Load .c8ignore rules from the working directory
+    const ignoreBaseDir = resolve(process.cwd());
+    const ig = loadIgnoreRules(ignoreBaseDir);
+    const resources = [];
+    paths.forEach((path) => {
+        collectResourceFiles(path, resources, undefined, ig, ignoreBaseDir, force);
+    });
+    if (resources.length === 0) {
+        throw new Error("No deployable files found in the specified paths");
+    }
+    return resources;
+}
+/**
+ * Internal helper: deploy the given paths to the cluster and render the
+ * result table. Used by `deployCommand` (the standard CLI entry point)
+ * and by `watchCommand` (for change-triggered re-deploys).
+ *
+ * Does NOT consult `c8ctl.dryRun` — dry-run handling lives in the
+ * `deployCommand` handler so the framework's `dryRun()` helper owns
+ * preview emission. Watch never triggers a dry-run, so this split also
+ * removes a footgun where a stale dry-run flag could suppress a watch
+ * deploy.
+ */
+export async function deployResources(paths, options) {
     const logger = getLogger();
     const tenantId = resolveTenantId(options.profile);
-    const resources = [];
-    try {
-        // Store the base paths for relative path calculation
-        const basePaths = paths.length === 0 ? [process.cwd()] : paths;
-        if (paths.length === 0) {
-            logger.error("No paths provided. Use: c8 deploy <path> or c8 deploy (for current directory)");
-            process.exit(1);
-        }
-        // Load .c8ignore rules from the working directory
-        const ignoreBaseDir = resolve(process.cwd());
-        const ig = loadIgnoreRules(ignoreBaseDir);
-        // Collect all resource files (respecting .c8ignore)
-        paths.forEach((path) => {
-            collectResourceFiles(path, resources, undefined, ig, ignoreBaseDir);
-        });
-        if (resources.length === 0) {
-            logger.error("No BPMN/DMN/Form files found in the specified paths");
-            process.exit(1);
-        }
-        // Dry-run: emit the would-be API request without executing
-        if (c8ctl.dryRun) {
-            const config = resolveClusterConfig(options.profile);
-            logger.json({
-                dryRun: true,
-                command: "deploy",
-                method: "POST",
-                url: `${config.baseUrl}/deployments`,
-                body: {
-                    tenantId,
-                    resources: resources.map((r) => ({ name: r.name })),
-                },
-            });
-            return;
-        }
-        const client = createClient(options.profile);
-        // Calculate relative paths for display
-        const basePath = basePaths.length === 1 ? basePaths[0] : process.cwd();
-        resources.forEach((r) => {
-            r.relativePath = relative(basePath, r.path) || r.name;
-        });
-        // Sort: group resources by their group, with building blocks first, then process applications, then standalone
-        resources.sort((a, b) => {
-            // Building blocks have highest priority
-            if (a.isBuildingBlock && !b.isBuildingBlock)
-                return -1;
-            if (!a.isBuildingBlock && b.isBuildingBlock)
-                return 1;
-            // Within building blocks, group by groupPath
-            if (a.isBuildingBlock && b.isBuildingBlock) {
-                if (a.groupPath && b.groupPath) {
-                    const groupCompare = a.groupPath.localeCompare(b.groupPath);
-                    if (groupCompare !== 0)
-                        return groupCompare;
-                }
-                return a.path.localeCompare(b.path);
-            }
-            // Process applications come next
-            if (a.isProcessApplication && !b.isProcessApplication)
-                return -1;
-            if (!a.isProcessApplication && b.isProcessApplication)
-                return 1;
-            // Within process applications, group by groupPath
-            if (a.isProcessApplication && b.isProcessApplication) {
-                if (a.groupPath && b.groupPath) {
-                    const groupCompare = a.groupPath.localeCompare(b.groupPath);
-                    if (groupCompare !== 0)
-                        return groupCompare;
-                }
-                return a.path.localeCompare(b.path);
+    // ─── Pre-API-call validation and preparation ────────────────────────
+    // These steps run OUTSIDE any try/catch so validation errors bubble
+    // straight to the framework's `handleCommandError`. Only the actual
+    // HTTP deploy call (further down) is wrapped in a catch that routes
+    // through `handleDeploymentError` for rich Problem-Detail rendering.
+    const resources = collectResourcesForPaths(paths, options.force);
+    // Store the base paths for relative path calculation. Safe to assign
+    // directly now: the empty-paths guard inside `collectResourcesForPaths`
+    // has already thrown.
+    const basePaths = paths;
+    const client = createClient(options.profile);
+    // Calculate relative paths for display
+    const basePath = basePaths.length === 1 ? basePaths[0] : process.cwd();
+    resources.forEach((r) => {
+        r.relativePath = relative(basePath, r.path) || r.name;
+    });
+    // Sort: group resources by their group, with building blocks first, then process applications, then standalone
+    resources.sort((a, b) => {
+        // Building blocks have highest priority
+        if (a.isBuildingBlock && !b.isBuildingBlock)
+            return -1;
+        if (!a.isBuildingBlock && b.isBuildingBlock)
+            return 1;
+        // Within building blocks, group by groupPath
+        if (a.isBuildingBlock && b.isBuildingBlock) {
+            if (a.groupPath && b.groupPath) {
+                const groupCompare = a.groupPath.localeCompare(b.groupPath);
+                if (groupCompare !== 0)
+                    return groupCompare;
             }
-            // Finally, standalone resources sorted by path
             return a.path.localeCompare(b.path);
-        });
-        // Validate for duplicate process/decision IDs
-        const duplicates = findDuplicateDefinitionIds(resources);
-        if (duplicates.size > 0) {
-            logger.error("Cannot deploy: Multiple files with the same process/decision ID in one deployment");
-            duplicates.forEach((paths, id) => {
-                logMessage(`  Process/Decision ID "${id}" found in: ${paths.join(", ")}`);
-            });
-            logMessage("\nCamunda does not allow deploying multiple resources with the same definition ID in a single deployment.");
-            logMessage("Please deploy these files separately or ensure each process/decision has a unique ID.");
-            process.exit(1);
         }
-        logger.info(`Deploying ${resources.length} resource(s)...`);
-        // Create a mapping from definition ID to resource file for later reference
-        const definitionIdToResource = new Map();
-        const formNameToResource = new Map();
-        resources.forEach((r) => {
-            const ext = extname(r.path);
-            if (ext === ".bpmn" || ext === ".dmn") {
-                const defId = extractDefinitionId(r.content, ext);
-                if (defId) {
-                    definitionIdToResource.set(defId, r);
-                }
+        // Process applications come next
+        if (a.isProcessApplication && !b.isProcessApplication)
+            return -1;
+        if (!a.isProcessApplication && b.isProcessApplication)
+            return 1;
+        // Within process applications, group by groupPath
+        if (a.isProcessApplication && b.isProcessApplication) {
+            if (a.groupPath && b.groupPath) {
+                const groupCompare = a.groupPath.localeCompare(b.groupPath);
+                if (groupCompare !== 0)
+                    return groupCompare;
             }
-            else if (ext === ".form") {
-                // Forms are matched by filename (without extension)
-                const formId = basename(r.name, ".form");
-                formNameToResource.set(formId, r);
-            }
-        });
-        // Create deployment request - convert buffers to File objects with proper MIME types
-        const result = await client.createDeployment({
-            tenantId: TenantId.assumeExists(tenantId),
-            resources: resources.map((r) => {
-                // Determine MIME type based on extension
-                const ext = r.name.split(".").pop()?.toLowerCase();
-                const mimeType = ext === "bpmn"
-                    ? "application/xml"
-                    : ext === "dmn"
-                        ? "application/xml"
-                        : ext === "form"
-                            ? "application/json"
-                            : "application/octet-stream";
-                // Convert Buffer to Uint8Array for File constructor
-                return new File([new Uint8Array(r.content)], r.name, {
-                    type: mimeType,
-                });
-            }),
-        });
-        logger.success("Deployment successful", result.deploymentKey.toString());
-        // Normalize all deployed resources into a common structure
-        const allResources = [
-            ...result.processes.map((proc) => ({
-                type: "Process",
-                id: proc.processDefinitionId,
-                version: proc.processDefinitionVersion,
-                key: proc.processDefinitionKey.toString(),
-                resource: definitionIdToResource.get(proc.processDefinitionId),
-            })),
-            ...result.decisions.map((dec) => ({
-                type: "Decision",
-                id: dec.decisionDefinitionId || "-",
-                version: dec.version ?? "-",
-                key: dec.decisionDefinitionKey?.toString() || "-",
-                resource: definitionIdToResource.get(dec.decisionDefinitionId || ""),
-            })),
-            ...result.forms.map((form) => ({
-                type: "Form",
-                id: form.formId || "-",
-                version: form.version ?? "-",
-                key: form.formKey?.toString() || "-",
-                resource: formNameToResource.get(form.formId || ""),
-            })),
-        ];
-        const tableData = allResources.map(({ type, id, version, key, resource }) => {
-            const fileDisplay = resource
-                ? `${resource.isBuildingBlock ? "🧱 " : ""}${resource.isProcessApplication ? "📦 " : ""}${resource.relativePath || resource.name}`
-                : "-";
-            // Extract directory path for grouping (e.g., "bla/_bb-building-block" or "pa")
-            const sortKey = resource?.relativePath
-                ? resource.relativePath.substring(0, resource.relativePath.lastIndexOf("/") + 1) || resource.relativePath
-                : "zzz"; // Resources without paths go last
-            return {
-                File: fileDisplay,
-                Type: type,
-                ID: id,
-                Version: version,
-                Key: key,
-                sortKey,
-            };
+            return a.path.localeCompare(b.path);
+        }
+        // Finally, standalone resources sorted by path
+        return a.path.localeCompare(b.path);
+    });
+    // Validate for duplicate process/decision IDs
+    const duplicates = findDuplicateDefinitionIds(resources);
+    if (duplicates.size > 0) {
+        // Single source of truth for both the user-visible logger.error and
+        // the SilentError message — keeps stderr and `--verbose` rethrow
+        // stack message aligned even if the wording is later edited.
+        const duplicateIdsMessage = "Cannot deploy: Multiple files with the same process/decision ID in one deployment";
+        // Pre-render the rich detail (per-id file list + guidance) so the
+        // user sees actionable context, then throw a SilentError so the
+        // framework records the failure without re-rendering a duplicate
+        // summary line.
+        logger.error(duplicateIdsMessage);
+        duplicates.forEach((dupPaths, id) => {
+            logMessage(`  Process/Decision ID "${id}" found in: ${dupPaths.join(", ")}`);
         });
-        // Sort by directory path (grouping), then by file name
-        tableData.sort((a, b) => {
-            if (a.sortKey !== b.sortKey) {
-                return a.sortKey.localeCompare(b.sortKey);
+        logMessage("\nCamunda does not allow deploying multiple resources with the same definition ID in a single deployment.");
+        logMessage("Please deploy these files separately or ensure each process/decision has a unique ID.");
+        throw new SilentError(duplicateIdsMessage);
+    }
+    logger.info(`Deploying ${resources.length} resource(s)...`);
+    // Create a mapping from definition ID to resource file for later reference
+    const definitionIdToResource = new Map();
+    const formNameToResource = new Map();
+    resources.forEach((r) => {
+        const ext = extname(r.path);
+        if (ext === ".bpmn" || ext === ".dmn") {
+            const defId = extractDefinitionId(r.content, ext);
+            if (defId) {
+                definitionIdToResource.set(defId, r);
             }
-            return a.File.localeCompare(b.File);
-        });
-        // Remove sortKey before displaying
-        const displayData = tableData.map(({ File, Type, ID, Version, Key }) => ({
-            File,
-            Type,
-            ID,
-            Version,
-            Key,
-        }));
-        if (displayData.length > 0) {
-            logger.table(displayData);
+        }
+        else if (ext === ".form") {
+            // Forms are matched by filename (without extension)
+            const formId = basename(r.name, ".form");
+            formNameToResource.set(formId, r);
+        }
+    });
+    // ─── API call ────────────────────────────────────────────────────────
+    // Only this section is wrapped in a catch that routes through
+    // `handleDeploymentError`. Pre-API errors above bubble to the
+    // framework directly.
+    // Create deployment request - convert buffers to File objects with proper MIME types
+    const pendingDeploy = client.createDeployment({
+        tenantId: TenantId.assumeExists(tenantId),
+        resources: resources.map((r) => {
+            // Determine MIME type based on extension
+            const ext = r.name.split(".").pop()?.toLowerCase();
+            const mimeType = ext === "bpmn"
+                ? "application/xml"
+                : ext === "dmn"
+                    ? "application/xml"
+                    : ext === "form"
+                        ? "application/json"
+                        : "application/octet-stream";
+            // Convert Buffer to Uint8Array for File constructor
+            return new File([new Uint8Array(r.content)], r.name, {
+                type: mimeType,
+            });
+        }),
+    });
+    // Wire optional cancellation: when the caller's AbortSignal fires,
+    // cancel the underlying CancelablePromise so the in-flight HTTP
+    // request is aborted promptly. Used by `watch` so SIGINT mid-deploy
+    // shuts down within ~one event-loop tick rather than blocking on
+    // the network round-trip.
+    const onAbort = () => {
+        pendingDeploy.cancel();
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            onAbort();
+        }
+        else {
+            options.signal.addEventListener("abort", onAbort, { once: true });
         }
     }
+    let result;
+    try {
+        result = await pendingDeploy;
+    }
     catch (error) {
+        options.signal?.removeEventListener("abort", onAbort);
+        // Caller-initiated cancellation (e.g. SIGINT in `watch`): the
+        // CancelablePromise rejects with a "Cancelled" error after we
+        // invoked `pendingDeploy.cancel()` from the abort listener. The
+        // caller already knows the request was aborted — do not surface
+        // it as a user-visible deploy failure or exit non-zero.
+        if (options.signal?.aborted) {
+            return;
+        }
         handleDeploymentError(error, resources, logger, options.continueOnError, options.continueOnUserError);
+        // `handleDeploymentError` either throws (terminal) or returns
+        // (continue-on-error). On the continue path, skip the success
+        // render below — there's no result to render.
+        return;
+    }
+    options.signal?.removeEventListener("abort", onAbort);
+    logger.success("Deployment successful", result.deploymentKey.toString());
+    // Normalize all deployed resources into a common structure
+    const allResources = [
+        ...result.processes.map((proc) => ({
+            type: "Process",
+            id: proc.processDefinitionId,
+            version: proc.processDefinitionVersion,
+            key: proc.processDefinitionKey.toString(),
+            resource: definitionIdToResource.get(proc.processDefinitionId),
+        })),
+        ...result.decisions.map((dec) => ({
+            type: "Decision",
+            id: dec.decisionDefinitionId || "-",
+            version: dec.version ?? "-",
+            key: dec.decisionDefinitionKey?.toString() || "-",
+            resource: definitionIdToResource.get(dec.decisionDefinitionId || ""),
+        })),
+        ...result.forms.map((form) => ({
+            type: "Form",
+            id: form.formId || "-",
+            version: form.version ?? "-",
+            key: form.formKey?.toString() || "-",
+            resource: formNameToResource.get(form.formId || ""),
+        })),
+    ];
+    const tableData = allResources.map(({ type, id, version, key, resource }) => {
+        const fileDisplay = resource
+            ? `${resource.isBuildingBlock ? "🧱 " : ""}${resource.isProcessApplication ? "📦 " : ""}${resource.relativePath || resource.name}`
+            : "-";
+        // Extract directory path for grouping (e.g., "bla/_bb-building-block" or "pa")
+        const sortKey = resource?.relativePath
+            ? resource.relativePath.substring(0, resource.relativePath.lastIndexOf("/") + 1) || resource.relativePath
+            : "zzz"; // Resources without paths go last
+        return {
+            File: fileDisplay,
+            Type: type,
+            ID: id,
+            Version: version,
+            Key: key,
+            sortKey,
+        };
+    });
+    // Sort by directory path (grouping), then by file name
+    tableData.sort((a, b) => {
+        if (a.sortKey !== b.sortKey) {
+            return a.sortKey.localeCompare(b.sortKey);
+        }
+        return a.File.localeCompare(b.File);
+    });
+    // Remove sortKey before displaying
+    const displayData = tableData.map(({ File, Type, ID, Version, Key }) => ({
+        File,
+        Type,
+        ID,
+        Version,
+        Key,
+    }));
+    if (displayData.length > 0) {
+        logger.table(displayData);
     }
 }
 /**
@@ -397,9 +458,14 @@ function handleDeploymentError(error, resources, logger, continueOnError, contin
         if (shouldContinue) {
             throw error;
         }
-        const normalizedError = error instanceof Error ? error : new Error(String(error));
-        console.error(normalizedError);
-        process.exit(1);
+        // Verbose mode: surface the original error to the framework so
+        // `handleCommandError` rethrows it and Node prints the stack trace.
+        // Non-Error throws (e.g. RFC 9457 problem-detail plain objects from
+        // the SDK) are normalized via the centralized helper so the message
+        // is built from `title` / `detail` / `status` instead of collapsing
+        // to `Error: [object Object]`. The original value is preserved as
+        // `cause` so it remains inspectable.
+        throw normalizeToError(error, "Deployment request failed");
     }
     // Try to interpret common transport/network issues first for actionable guidance
     const deriveNetworkErrorTitle = (err) => {
@@ -456,7 +522,10 @@ function handleDeploymentError(error, resources, logger, continueOnError, contin
     if (shouldContinue) {
         return;
     }
-    process.exit(1);
+    // Pre-rendered the rich error context above; throw a SilentError so
+    // `handleCommandError` exits non-zero without re-rendering a
+    // duplicate "Failed to deploy: <message>" summary line.
+    throw new SilentError(title);
 }
 /**
  * Format the error detail for better readability
@@ -471,11 +540,8 @@ function formatDeploymentErrorDetail(detail) {
     const result = [];
     let inFileError = false;
     for (const line of lines) {
-        if (line.startsWith("'") &&
-            (line.includes(".bpmn") ||
-                line.includes(".dmn") ||
-                line.includes(".form"))) {
-            // This is a file-specific error
+        if (line.startsWith("'") && line.includes("':")) {
+            // This is a file-specific error (detected by 'filename': pattern)
             inFileError = true;
             result.push(`  📄 ${line}`);
         }
@@ -548,15 +614,51 @@ function printDeploymentHints(title, detail, status, resources) {
         logMessage(h);
     });
 }
-// ─── defineCommand wrapper ───────────────────────────────────────────────────
-/** Side-effectful: collects files, validates, deploys, and renders its own table output. */
-export const deployCommand = defineCommand("deploy", "", async (ctx) => {
+// ─── defineCommand ───────────────────────────────────────────────────────────
+/**
+ * Side-effectful: collects files, validates, deploys, and renders its own
+ * table output.
+ *
+ * The body lives directly in the handler (per #288): argument-shape
+ * resolution, dry-run preview via the framework's `dryRun()` helper,
+ * and the call into the shared `deployResources` helper that watch also
+ * uses for change-triggered re-deploys.
+ */
+export const deployCommand = defineCommand("deploy", "", async (ctx, flags) => {
+    // Argument shape: `c8 deploy [path...]`. With no positional, default
+    // to cwd. Pinned by tests/unit/deploy-behaviour.test.ts.
     const paths = ctx.resource
         ? [ctx.resource, ...ctx.positionals]
         : ctx.positionals.length > 0
             ? ctx.positionals
             : ["."];
-    await deploy(paths, { profile: ctx.profile });
+    // Dry-run preview. Collect resources first so the preview body
+    // reflects what would actually be sent — and so the empty-paths /
+    // no-files guards still surface as thrown errors before we emit.
+    // Uses `ctx.dryRun` and `ctx.tenantId` from the framework rather
+    // than reaching into the global runtime/config layer.
+    if (ctx.dryRun) {
+        const previewResources = collectResourcesForPaths(paths, flags.force);
+        const dr = dryRun({
+            command: "deploy",
+            method: "POST",
+            endpoint: "/deployments",
+            profile: ctx.profile,
+            body: {
+                tenantId: ctx.tenantId,
+                resources: previewResources.map((r) => ({ name: r.name })),
+            },
+        });
+        if (dr)
+            return dr;
+    }
+    // Execute path: only reached when not in dry-run mode (the branch
+    // above returns early). `deployResources` runs its own
+    // `collectResourcesForPaths` internally and renders the success
+    // table. Keeping the helper self-contained avoids threading
+    // pre-collected state between the handler and the shared helper
+    // used by `watch`.
+    await deployResources(paths, { profile: ctx.profile, force: flags.force });
     return { kind: "none" };
 });
 //# sourceMappingURL=deployments.js.map