Merge pull request #1547 from tailor-platform/feat/improve-setup

feat(cli): route deploy --dry-run output to stdout and add --json support

Author: dqn

.changeset/deploy-dry-run-stdout-json.md

@@ -0,0 +1,5 @@
+---
+"@tailor-platform/sdk": minor
+---
+
+Route `deploy --dry-run` plan diff output to stdout so CI pipelines can capture it cleanly without `2>&1`. Add `--json` / `-j` support to `deploy`: dry-run outputs `{ summary, changes, warnings, conflicts }` and apply outputs `{ summary, status: "applied" }` to stdout for machine-readable consumption. The `warnings` array includes unmanaged resources and skipped secrets; the `conflicts` array lists owner conflicts.

packages/sdk/docs/cli/application.md

@@ -110,10 +110,45 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 After the detailed list, a summary line is printed:
 
 ```text
-Plan: 5 to create, 3 to update, 1 to delete, 25 unchanged
+Plan: 5 to create, 3 to update, 1 to delete
 ```
 
-Use `--dry-run` to preview the plan without applying anything.
+Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
+
+```bash
+tailor-sdk deploy --dry-run > plan.txt
+```
+
+In apply mode, the plan is printed to stderr so it does not interfere with piped output.
+
+**JSON Output:**
+
+Pass the global `--json` / `-j` flag to get machine-readable output.
+
+**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:
+
+```json
+{
+  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "changes": [{ "action": "create", "name": "Order", "labels": ["type"], "namespace": "tailordb" }],
+  "warnings": [
+    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
+    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
+  ],
+  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
+}
+```
+
+- `summary` — counts of each change type.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
+- `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
+
+**Apply** (`--json`): writes a JSON object to stdout:
+
+```json
+{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
+```
 
 ## remove
 

packages/sdk/docs/cli/application.template.md

@@ -50,10 +50,45 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 After the detailed list, a summary line is printed:
 
 ```text
-Plan: 5 to create, 3 to update, 1 to delete, 25 unchanged
+Plan: 5 to create, 3 to update, 1 to delete
 ```
 
-Use `--dry-run` to preview the plan without applying anything.
+Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
+
+```bash
+tailor-sdk deploy --dry-run > plan.txt
+```
+
+In apply mode, the plan is printed to stderr so it does not interfere with piped output.
+
+**JSON Output:**
+
+Pass the global `--json` / `-j` flag to get machine-readable output.
+
+**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:
+
+```json
+{
+  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "changes": [{ "action": "create", "name": "Order", "labels": ["type"], "namespace": "tailordb" }],
+  "warnings": [
+    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
+    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
+  ],
+  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
+}
+```
+
+- `summary` — counts of each change type.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
+- `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
+
+**Apply** (`--json`): writes a JSON object to stdout:
+
+```json
+{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
+```
 
 {{politty:command:remove}}
 {{politty:command:show}}

packages/sdk/src/cli/commands/deploy/aigateway.test.ts

@@ -18,19 +18,7 @@ vi.mock("./label", async (importOriginal) => {
   };
 });
 
-vi.mock("./change-set", async (importOriginal) => {
-  const original = (await importOriginal()) as Record<string, unknown>;
-  const createChangeSet = original.createChangeSet as (title: string) => {
-    print: () => void;
-  };
-  return {
-    ...original,
-    createChangeSet: (title: string) => ({
-      ...createChangeSet(title),
-      print: () => {},
-    }),
-  };
-});
+vi.mock("./change-set", async (importOriginal) => importOriginal());
 
 const workspaceId = "test-workspace";
 const appName = "test-app";

packages/sdk/src/cli/commands/deploy/application.test.ts

@@ -26,19 +26,7 @@ vi.mock("./label", async (importOriginal) => {
   };
 });
 
-vi.mock("./change-set", async (importOriginal) => {
-  const original = (await importOriginal()) as Record<string, unknown>;
-  const createChangeSet = original.createChangeSet as (title: string) => {
-    print: () => void;
-  };
-  return {
-    ...original,
-    createChangeSet: (title: string) => ({
-      ...createChangeSet(title),
-      print: () => {},
-    }),
-  };
-});
+vi.mock("./change-set", async (importOriginal) => importOriginal());
 
 const workspaceId = "test-workspace";
 const appName = "test-app";

packages/sdk/src/cli/commands/deploy/auth.plan.test.ts

@@ -30,19 +30,7 @@ vi.mock("./label", async (importOriginal) => {
   };
 });
 
-vi.mock("./change-set", async (importOriginal) => {
-  const original = (await importOriginal()) as Record<string, unknown>;
-  const createChangeSet = original.createChangeSet as (title: string) => {
-    print: () => void;
-  };
-  return {
-    ...original,
-    createChangeSet: (title: string) => ({
-      ...createChangeSet(title),
-      print: () => {},
-    }),
-  };
-});
+vi.mock("./change-set", async (importOriginal) => importOriginal());
 
 const workspaceId = "test-workspace";
 const appName = "test-app";

packages/sdk/src/cli/commands/deploy/auth.test.ts

@@ -53,7 +53,7 @@ describe("applyAuth phase separation", () => {
       replaces: [] as OAuth2ClientReplace[],
       title: "",
       isEmpty: () => false,
-      print: () => {},
+      lines: () => [],
     };
 
     return {

packages/sdk/src/cli/commands/deploy/change-set.test.ts

@@ -1,37 +1,32 @@
-import { describe, expect, test, vi } from "vitest";
-import { logger } from "#/cli/shared/logger";
+import { describe, expect, test } from "vitest";
 import { createChangeSet, formatPlanSummary, summarizeChangeSets } from "./change-set";
 import type { HasName } from "./change-set";
 
 function createNamedChangeSet(title: string) {
   return createChangeSet<HasName, HasName, HasName, HasName>(title);
 }
 
-describe("ChangeSet.print", () => {
+describe("ChangeSet.lines", () => {
   test("renders an item's optional details indented beneath it", () => {
     const changeSet = createNamedChangeSet("Applications");
     changeSet.updates.push({
       name: "my-app",
       details: ["~ get-user (httpAdapter)", "+ echo (httpAdapter)"],
     });
 
-    using logSpy = vi.spyOn(logger, "log").mockImplementation(() => {});
-    changeSet.print();
-
-    const lines = logSpy.mock.calls.map((call) => String(call[0]));
-    // The application line is present (symbol is color-wrapped, so match loosely),
-    // followed by its detail lines indented by four spaces.
+    const lines = changeSet.lines();
     expect(lines.some((line) => line.includes("my-app"))).toBe(true);
     expect(lines).toContain("    ~ get-user (httpAdapter)");
     expect(lines).toContain("    + echo (httpAdapter)");
   });
+
+  test("returns empty array when change set is empty", () => {
+    expect(createNamedChangeSet("Applications").lines()).toEqual([]);
+  });
 });
 
 describe("summarizeChangeSets", () => {
   test("summarizes resource counts for plan output", () => {
-    const unchanged = createNamedChangeSet("Applications");
-    unchanged.unchanged.push({ name: "app-a" }, { name: "app-b" });
-
     const create = createNamedChangeSet("Executors");
     create.creates.push({ name: "executor-a" }, { name: "executor-b" });
 
@@ -44,12 +39,11 @@ describe("summarizeChangeSets", () => {
     const replace = createNamedChangeSet("OAuth2 clients");
     replace.replaces.push({ name: "client-a" }, { name: "client-b" });
 
-    expect(summarizeChangeSets([unchanged, create, update, deleteSet, replace])).toEqual({
+    expect(summarizeChangeSets([create, update, deleteSet, replace])).toEqual({
       create: 2,
       update: 3,
       delete: 1,
       replace: 2,
-      unchanged: 2,
     });
   });
 });
@@ -62,7 +56,6 @@ describe("formatPlanSummary", () => {
         update: 2,
         delete: 0,
         replace: 0,
-        unchanged: 15,
       }),
     ).toBe("Plan: 1 to create, 2 to update, 0 to delete");
   });
@@ -74,7 +67,6 @@ describe("formatPlanSummary", () => {
         update: 2,
         delete: 0,
         replace: 3,
-        unchanged: 15,
       }),
     ).toBe("Plan: 1 to create, 2 to update, 0 to delete, 3 to replace");
   });

packages/sdk/src/cli/commands/deploy/change-set.ts

@@ -1,10 +1,10 @@
-import { logger, styles, symbols } from "#/cli/shared/logger";
+import { styles, symbols } from "#/cli/shared/logger";
 
 export interface HasName {
   name: string;
   /**
    * Optional pre-formatted lines rendered indented beneath the item by
-   * `ChangeSet.print()` (e.g. per-sub-resource diffs embedded in a single
+   * `ChangeSet.lines()` (e.g. per-sub-resource diffs embedded in a single
    * resource).
    */
   details?: readonly string[];
@@ -24,21 +24,20 @@ export type ChangeSet<
   readonly replaces: R[];
   readonly unchanged: Un[];
   isEmpty: () => boolean;
-  print: () => void;
+  lines: () => string[];
 };
 
 export interface PlanSummary {
   create: number;
   update: number;
   delete: number;
   replace: number;
-  unchanged: number;
 }
 
 /**
  * Create a new ChangeSet for tracking resource changes.
  * @param title - Title for the change set
- * @returns Empty ChangeSet instance with isEmpty() and print() methods
+ * @returns Empty ChangeSet instance with isEmpty() and lines() methods
  */
 export function createChangeSet<
   C extends HasName,
@@ -64,21 +63,19 @@ export function createChangeSet<
     replaces,
     unchanged,
     isEmpty,
-    print: () => {
-      if (isEmpty()) {
-        return;
-      }
-      logger.log(styles.bold(`${title}:`));
-      const printItem = (symbol: string, item: HasName) => {
-        logger.log(`  ${symbol} ${item.name}`);
-        for (const detail of item.details ?? []) {
-          logger.log(`    ${detail}`);
-        }
-      };
-      creates.forEach((item) => printItem(symbols.create, item));
-      deletes.forEach((item) => printItem(symbols.delete, item));
-      updates.forEach((item) => printItem(symbols.update, item));
-      replaces.forEach((item) => printItem(symbols.replace, item));
+    lines: () => {
+      if (isEmpty()) return [];
+      const itemLines = (symbol: string) => (item: HasName) => [
+        `  ${symbol} ${item.name}`,
+        ...(item.details ?? []).map((d) => `    ${d}`),
+      ];
+      return [
+        styles.bold(`${title}:`),
+        ...creates.flatMap(itemLines(symbols.create)),
+        ...deletes.flatMap(itemLines(symbols.delete)),
+        ...updates.flatMap(itemLines(symbols.update)),
+        ...replaces.flatMap(itemLines(symbols.replace)),
+      ];
     },
   };
 }
@@ -92,24 +89,17 @@ export function summarizeChangeSets(
   changeSets: Array<
     Pick<
       ChangeSet<HasName, HasName, HasName, HasName>,
-      "creates" | "updates" | "deletes" | "replaces" | "unchanged"
+      "creates" | "updates" | "deletes" | "replaces"
     >
   >,
 ): PlanSummary {
-  const summary: PlanSummary = {
-    create: 0,
-    update: 0,
-    delete: 0,
-    replace: 0,
-    unchanged: 0,
-  };
+  const summary: PlanSummary = { create: 0, update: 0, delete: 0, replace: 0 };
 
   for (const changeSet of changeSets) {
     summary.create += changeSet.creates.length;
     summary.update += changeSet.updates.length;
     summary.delete += changeSet.deletes.length;
     summary.replace += changeSet.replaces.length;
-    summary.unchanged += changeSet.unchanged.length;
   }
 
   return summary;