@planningcenter/tapestry-migration-cli 3.4.1 → 3.6.0

package/src/index.test.ts

@@ -0,0 +1,79 @@
+/**
+ * E2E regression test for `list --json`.
+ *
+ * Spawns the CLI exactly as consumers do — `npx tsx src/index.ts list --json` —
+ * and asserts the full stdout/stderr/exit-code contract.
+ */
+
+import { spawnSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
+
+import { describe, expect, it } from "vitest"
+
+import { buildMigrationList } from "./migrationList"
+
+const CLI_PATH = fileURLToPath(new URL("./index.ts", import.meta.url))
+
+function runCli(args: string[]) {
+  return spawnSync("npx", ["tsx", CLI_PATH, ...args], {
+    encoding: "utf8",
+    // tsx cold-start can take a few seconds; allow up to 30 s.
+    timeout: 30_000,
+  })
+}
+
+describe("list --json (stdout/exit-code contract)", () => {
+  it("exits with code 0", () => {
+    const result = runCli(["list", "--json"])
+    expect(result.status).toBe(0)
+  })
+
+  it("emits valid JSON as the entire stdout (no stray lines)", () => {
+    const result = runCli(["list", "--json"])
+    // JSON.parse throws if there is ANY non-JSON content on stdout.
+    expect(() => JSON.parse(result.stdout)).not.toThrow()
+  })
+
+  it("payload matches buildMigrationList() (schemaVersion + migrations)", () => {
+    const result = runCli(["list", "--json"])
+    const payload = JSON.parse(result.stdout)
+    expect(payload).toEqual(buildMigrationList())
+  })
+
+  it("schemaVersion is exactly the integer 1", () => {
+    const result = runCli(["list", "--json"])
+    const { schemaVersion } = JSON.parse(result.stdout)
+    expect(schemaVersion).toBe(1)
+    expect(Number.isInteger(schemaVersion)).toBe(true)
+  })
+
+  it("stderr is empty on success", () => {
+    const result = runCli(["list", "--json"])
+    expect(result.stderr).toBe("")
+  })
+
+  it("does not require --path and makes no filesystem writes", () => {
+    // If --path were required, commander would write an error to stderr and exit 1.
+    // We assert the happy path — exit 0 with no --path — proving the flag is absent.
+    const result = runCli(["list", "--json"])
+    expect(result.status).toBe(0)
+  })
+})
+
+describe("list (human-readable, non-contractual)", () => {
+  it("exits with code 0 and writes component ids to stdout", () => {
+    const result = runCli(["list"])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain("button")
+    expect(result.stdout).toContain("toggle-switch")
+  })
+})
+
+describe("diagnostics contract (nonzero exit → stderr)", () => {
+  it("exits nonzero and writes to stderr for an unknown subcommand", () => {
+    const result = runCli(["unknown-subcommand"])
+    // Commander writes "error: unknown command 'unknown-subcommand'" to stderr.
+    expect(result.status).not.toBe(0)
+    expect(result.stderr.length).toBeGreaterThan(0)
+  })
+})

package/src/index.ts

@@ -2,7 +2,10 @@
 
 import { Command } from "commander"
 
+import { AVAILABLE_CLI_COMPONENTS } from "./availableComponents"
 import { runTransforms } from "./jscodeshiftRunner"
+import { buildMigrationList } from "./migrationList"
+import { formatComponentLabel } from "./utils/componentLabel"
 import { normalizeComponentName } from "./utils/componentNameNormalizer"
 
 const program = new Command()
@@ -11,24 +14,10 @@ program
   .name("tapestry-migration-cli")
   .description("CLI tool for Tapestry migrations")
 
-const COMPONENTS_SET = new Set([
-  "button",
-  "checkbox",
-  "date-picker",
-  "dropdown",
-  "input",
-  "link",
-  "radio",
-  "select",
-  "text-area",
-  "time-field",
-  "toggle-switch",
-])
-
 const COMPONENTS_SENTENCE = new Intl.ListFormat("en", {
   style: "long",
   type: "conjunction",
-}).format([...COMPONENTS_SET])
+}).format([...AVAILABLE_CLI_COMPONENTS])
 
 program
   .command("run")
@@ -53,9 +42,9 @@ program
     "MIGRATION_REPORT.md"
   )
   .action((componentName, options) => {
-    const key = normalizeComponentName(componentName, COMPONENTS_SET)
+    const key = normalizeComponentName(componentName, AVAILABLE_CLI_COMPONENTS)
 
-    if (key && COMPONENTS_SET.has(key)) {
+    if (key && AVAILABLE_CLI_COMPONENTS.has(key)) {
       console.log(`🎨 Migrating ${componentName} components...`)
       console.log(`📁 Target: ${options.path}`)
       console.log(
@@ -65,7 +54,7 @@ program
     } else {
       console.error(`❌ Invalid component: "${componentName}"`)
       console.error(
-        `✅ Available components: ${[...COMPONENTS_SET].join(", ")}`
+        `✅ Available components: ${[...AVAILABLE_CLI_COMPONENTS].join(", ")}`
       )
       process.exit(1)
     }
@@ -105,6 +94,33 @@ program
     runTransforms("preflight", options)
   })
 
+program
+  .command("list")
+  .description(
+    "List available migrations. Pass --json for a stable, versioned machine-readable contract."
+  )
+  .option(
+    "--json",
+    "Output migrations as JSON to stdout (diagnostics go to stderr; exits nonzero on failure)"
+  )
+  .action((options) => {
+    try {
+      if (options.json) {
+        // JSON ONLY on stdout — no emoji, no progress lines, no trailing text.
+        process.stdout.write(
+          JSON.stringify(buildMigrationList(), null, 2) + "\n"
+        )
+      } else {
+        for (const id of AVAILABLE_CLI_COMPONENTS) {
+          console.log(`${id} — ${formatComponentLabel(id)}`)
+        }
+      }
+    } catch (error) {
+      console.error(`❌ Failed to list migrations: ${(error as Error).message}`)
+      process.exit(1)
+    }
+  })
+
 program
   .command("help")
   .description("Show help information")

package/src/migrationList.ts

@@ -0,0 +1,22 @@
+import { AVAILABLE_CLI_COMPONENTS } from "./availableComponents"
+import { formatComponentLabel } from "./utils/componentLabel"
+
+export const LIST_SCHEMA_VERSION = 1
+
+/**
+ * Builds the versioned migration list payload used by `list --json`.
+ * Pure — no I/O, no side effects.
+ *
+ * @example
+ * buildMigrationList()
+ * // { schemaVersion: 1, migrations: [{ id: "button", label: "Button" }, ...] }
+ */
+export function buildMigrationList() {
+  return {
+    migrations: [...AVAILABLE_CLI_COMPONENTS].map((id) => ({
+      id,
+      label: formatComponentLabel(id),
+    })),
+    schemaVersion: LIST_SCHEMA_VERSION,
+  }
+}

package/src/utils/componentLabel.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest"
+
+import { AVAILABLE_CLI_COMPONENTS } from "../availableComponents"
+import { buildMigrationList } from "../migrationList"
+import { formatComponentLabel } from "./componentLabel"
+import { normalizeComponentName } from "./componentNameNormalizer"
+
+describe("formatComponentLabel", () => {
+  it("should title-case a single-word id", () => {
+    expect(formatComponentLabel("button")).toBe("Button")
+    expect(formatComponentLabel("input")).toBe("Input")
+    expect(formatComponentLabel("radio")).toBe("Radio")
+  })
+
+  it("should produce Spaced Title Case for multi-word ids", () => {
+    expect(formatComponentLabel("date-picker")).toBe("Date Picker")
+    expect(formatComponentLabel("text-area")).toBe("Text Area")
+    expect(formatComponentLabel("time-field")).toBe("Time Field")
+    expect(formatComponentLabel("toggle-switch")).toBe("Toggle Switch")
+  })
+})
+
+describe("buildMigrationList", () => {
+  it("should return schemaVersion 1 as an integer", () => {
+    const result = buildMigrationList()
+    expect(result.schemaVersion).toBe(1)
+    expect(Number.isInteger(result.schemaVersion)).toBe(true)
+  })
+
+  it("should return a nonempty migrations array", () => {
+    const { migrations } = buildMigrationList()
+    expect(migrations.length).toBeGreaterThan(0)
+  })
+
+  it("should give every migration a nonempty string id and label", () => {
+    for (const { id, label } of buildMigrationList().migrations) {
+      expect(typeof id).toBe("string")
+      expect(id.length).toBeGreaterThan(0)
+      expect(typeof label).toBe("string")
+      expect(label.length).toBeGreaterThan(0)
+    }
+  })
+
+  it("should have unique ids", () => {
+    const ids = buildMigrationList().migrations.map((m) => m.id)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it("should emit ids that are exactly accepted by `run` (present in AVAILABLE_CLI_COMPONENTS)", () => {
+    for (const { id } of buildMigrationList().migrations) {
+      expect(AVAILABLE_CLI_COMPONENTS.has(id)).toBe(true)
+      // Also verify the normalizer round-trips it — proving run would accept it
+      expect(normalizeComponentName(id, AVAILABLE_CLI_COMPONENTS)).toBe(id)
+    }
+  })
+
+  it("should include every id in AVAILABLE_CLI_COMPONENTS with no extras", () => {
+    const emittedIds = buildMigrationList().migrations.map((m) => m.id)
+    expect(emittedIds).toEqual([...AVAILABLE_CLI_COMPONENTS])
+  })
+})

package/src/utils/componentLabel.ts

@@ -0,0 +1,15 @@
+/**
+ * Derives a human-readable display label from a kebab-case component id.
+ * Splits on hyphens and title-cases each word.
+ *
+ * @example
+ * formatComponentLabel("button")        // "Button"
+ * formatComponentLabel("date-picker")   // "Date Picker"
+ * formatComponentLabel("toggle-switch") // "Toggle Switch"
+ */
+export function formatComponentLabel(id: string): string {
+  return id
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ")
+}