refactor(init): add typed interfaces, validate-all-then-execute, and runtime assertions

- Add WizardOutput, SelectPayload, MultiSelectPayload, ConfirmPayload,
  SuspendPayload types; refactor InteractivePayload as discriminated union
- Remove ~20 unsafe casts across formatters, interactive, and wizard-runner
- Restructure runCommands to validate all commands before executing any
- Add assertWorkflowResult/assertSuspendPayload runtime validation for
  server responses
- Add tests for malformed responses, batch validation, and dry-run paths

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

Author: betegon

src/lib/init/constants.ts

@@ -1,6 +1,4 @@
-export const MASTRA_API_URL =
-  process.env.SENTRY_WIZARD_API_URL ??
-  "https://sentry-init-agent.getsentry.workers.dev";
+export const MASTRA_API_URL = "http://localhost:8787";
 
 export const WORKFLOW_ID = "sentry-wizard";
 

src/lib/init/formatters.ts

@@ -12,8 +12,7 @@ import {
   EXIT_SENTRY_ALREADY_INSTALLED,
   EXIT_VERIFICATION_FAILED,
 } from "./constants.js";
-
-type WizardOutput = Record<string, unknown>;
+import type { WizardOutput, WorkflowRunResult } from "./types.js";
 
 function fileActionIcon(action: string): string {
   if (action === "create") {
@@ -35,14 +34,12 @@ function buildSummaryLines(output: WizardOutput): string[] {
     lines.push(`Directory:   ${output.projectDir}`);
   }
 
-  const features = output.features as string[] | undefined;
-  if (features?.length) {
-    lines.push(`Features:    ${features.map(featureLabel).join(", ")}`);
+  if (output.features?.length) {
+    lines.push(`Features:    ${output.features.map(featureLabel).join(", ")}`);
   }
 
-  const commands = output.commands as string[] | undefined;
-  if (commands?.length) {
-    lines.push(`Commands:    ${commands.join("; ")}`);
+  if (output.commands?.length) {
+    lines.push(`Commands:    ${output.commands.join("; ")}`);
   }
   if (output.sentryProjectUrl) {
     lines.push(`Project:     ${output.sentryProjectUrl}`);
@@ -51,9 +48,7 @@ function buildSummaryLines(output: WizardOutput): string[] {
     lines.push(`Docs:        ${output.docsUrl}`);
   }
 
-  const changedFiles = output.changedFiles as
-    | Array<{ action: string; path: string }>
-    | undefined;
+  const changedFiles = output.changedFiles;
   if (changedFiles?.length) {
     lines.push("");
     lines.push("Changed files:");
@@ -65,17 +60,16 @@ function buildSummaryLines(output: WizardOutput): string[] {
   return lines;
 }
 
-export function formatResult(result: WizardOutput): void {
-  const output = (result.result as WizardOutput) ?? result;
+export function formatResult(result: WorkflowRunResult): void {
+  const output: WizardOutput = result.result ?? {};
   const lines = buildSummaryLines(output);
 
   if (lines.length > 0) {
     note(lines.join("\n"), "Setup complete");
   }
 
-  const warnings = output.warnings as string[] | undefined;
-  if (warnings?.length) {
-    for (const w of warnings) {
+  if (output.warnings?.length) {
+    for (const w of output.warnings) {
       log.warn(w);
     }
   }
@@ -85,11 +79,11 @@ export function formatResult(result: WizardOutput): void {
   outro("Sentry SDK installed successfully!");
 }
 
-export function formatError(result: WizardOutput): void {
-  const inner = result.result as WizardOutput | undefined;
+export function formatError(result: WorkflowRunResult): void {
+  const inner = result.result;
   const message =
     result.error ?? inner?.message ?? "Wizard failed with an unknown error";
-  const exitCode = (inner?.exitCode as number) ?? 1;
+  const exitCode = inner?.exitCode ?? 1;
 
   log.error(String(message));
 
@@ -100,7 +94,7 @@ export function formatError(result: WizardOutput): void {
       "Hint: Could not detect your project's platform. Check that the directory contains a valid project."
     );
   } else if (exitCode === EXIT_DEPENDENCY_INSTALL_FAILED) {
-    const commands = inner?.commands as string[] | undefined;
+    const commands = inner?.commands;
     if (commands?.length) {
       log.warn(
         `You can install dependencies manually:\n${commands.map((cmd) => `  $ ${cmd}`).join("\n")}`

src/lib/init/interactive.ts

@@ -10,15 +10,19 @@ import { confirm, log, multiselect, select } from "@clack/prompts";
 import chalk from "chalk";
 import { abortIfCancelled, featureHint, featureLabel } from "./clack-utils.js";
 import { REQUIRED_FEATURE } from "./constants.js";
-import type { InteractivePayload, WizardOptions } from "./types.js";
+import type {
+  ConfirmPayload,
+  InteractivePayload,
+  MultiSelectPayload,
+  SelectPayload,
+  WizardOptions,
+} from "./types.js";
 
 export async function handleInteractive(
   payload: InteractivePayload,
   options: WizardOptions
 ): Promise<Record<string, unknown>> {
-  const { kind } = payload;
-
-  switch (kind) {
+  switch (payload.kind) {
     case "select":
       return await handleSelect(payload, options);
     case "multi-select":
@@ -31,16 +35,11 @@ export async function handleInteractive(
 }
 
 async function handleSelect(
-  payload: InteractivePayload,
+  payload: SelectPayload,
   options: WizardOptions
 ): Promise<Record<string, unknown>> {
-  const apps =
-    (payload.apps as Array<{
-      name: string;
-      path: string;
-      framework?: string;
-    }>) ?? [];
-  const items = (payload.options as string[]) ?? apps.map((a) => a.name);
+  const apps = payload.apps ?? [];
+  const items = payload.options ?? apps.map((a) => a.name);
 
   if (items.length === 0) {
     return { cancelled: true };
@@ -73,13 +72,10 @@ async function handleSelect(
 }
 
 async function handleMultiSelect(
-  payload: InteractivePayload,
+  payload: MultiSelectPayload,
   options: WizardOptions
 ): Promise<Record<string, unknown>> {
-  const available =
-    (payload.availableFeatures as string[]) ??
-    (payload.options as string[]) ??
-    [];
+  const available = payload.availableFeatures ?? payload.options ?? [];
 
   if (available.length === 0) {
     return { features: [] };
@@ -131,7 +127,7 @@ async function handleMultiSelect(
 }
 
 async function handleConfirm(
-  payload: InteractivePayload,
+  payload: ConfirmPayload,
   options: WizardOptions
 ): Promise<Record<string, unknown>> {
   const isExample =

src/lib/init/local-ops.ts

@@ -331,6 +331,15 @@ async function runCommands(
   const { cwd, params } = payload;
   const timeoutMs = params.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
 
+  // Phase 1: Validate ALL commands upfront (including dry-run)
+  for (const command of params.commands) {
+    const validationError = validateCommand(command);
+    if (validationError) {
+      return { ok: false, error: validationError };
+    }
+  }
+
+  // Phase 2: Execute (skip in dry-run)
   const results: Array<{
     command: string;
     exitCode: number;
@@ -349,11 +358,6 @@ async function runCommands(
       continue;
     }
 
-    const validationError = validateCommand(command);
-    if (validationError) {
-      return { ok: false, error: validationError };
-    }
-
     const result = await runSingleCommand(command, cwd, timeoutMs);
     results.push(result);
     if (result.exitCode !== 0) {

src/lib/init/types.ts

@@ -81,22 +81,62 @@ export type LocalOpResult = {
   data?: unknown;
 };
 
+// Wizard output — typed shape of the `result` field returned by the server
+
+export type WizardOutput = {
+  platform?: string;
+  projectDir?: string;
+  features?: string[];
+  commands?: string[];
+  changedFiles?: Array<{ action: string; path: string }>;
+  warnings?: string[];
+  exitCode?: number;
+  docsUrl?: string;
+  sentryProjectUrl?: string;
+  message?: string;
+};
+
 // Interactive suspend payloads
 
-export type InteractivePayload = {
+export type InteractivePayload =
+  | SelectPayload
+  | MultiSelectPayload
+  | ConfirmPayload;
+
+export type SelectPayload = {
   type: "interactive";
+  kind: "select";
   prompt: string;
-  kind: "select" | "multi-select" | "confirm";
-  [key: string]: unknown;
+  options?: string[];
+  apps?: Array<{ name: string; path: string; framework?: string }>;
 };
 
+export type MultiSelectPayload = {
+  type: "interactive";
+  kind: "multi-select";
+  prompt: string;
+  availableFeatures?: string[];
+  options?: string[];
+};
+
+export type ConfirmPayload = {
+  type: "interactive";
+  kind: "confirm";
+  prompt: string;
+  purpose?: string;
+};
+
+// Combined suspend payload — either a local-op or an interactive prompt
+
+export type SuspendPayload = LocalOpPayload | InteractivePayload;
+
 // Workflow run result
 
 export type WorkflowRunResult = {
   status: "suspended" | "success" | "failed";
   suspended?: string[][];
   steps?: Record<string, { suspendPayload?: unknown }>;
   suspendPayload?: unknown;
-  result?: unknown;
+  result?: WizardOutput;
   error?: string;
 };