Function assertPlanStepsShape

src/commands/test.ts:1136–1159

* Type-narrow + validate a parsed `{ planSteps: [...] }` envelope. * The file is expected to be a single JSON object with a `planSteps` * array property; we tolerate the bare array form too (some agents * may emit `[...]` directly) so the surface forgives a common * mistake without surprising ca

(parsed: unknown)

 * mistake without surprising callers.
 */
function assertPlanStepsShape(parsed: unknown): CliPlanStep[] {
  let stepsRaw: unknown;
  if (Array.isArray(parsed)) {
    stepsRaw = parsed;
  } else if (typeof parsed === 'object' && parsed !== null) {
    stepsRaw = (parsed as Record<string, unknown>).planSteps;
  } else {
    throw localValidationError('steps', 'must be a JSON object with a `planSteps` array');
  }

  requireArrayLength('planSteps', stepsRaw, { min: 1, max: MAX_PLAN_STEPS, itemNoun: 'step' });

  for (let i = 0; i < stepsRaw.length; i += 1) {
    const step = stepsRaw[i];
    if (typeof step !== 'object' || step === null || Array.isArray(step)) {
      throw localValidationError(`planSteps[${i}]`, 'must be an object', undefined, 'field');
    }
    const s = step as Record<string, unknown>;
    requireEnum(`planSteps[${i}].type`, s.type, PLAN_STEP_TYPES);
    requireString(`planSteps[${i}].description`, s.description);
  }

  return stepsRaw as CliPlanStep[];
}

/**
 * §6.X / M3.2 piece-3 `UpdateTestResponse` shape. `updatedFields` is