Function readPlanStepsFileGuarded

src/commands/test.ts:1077–1127

* Read + validate the `--steps` file. Returns the parsed `planSteps` * array on success; throws a typed `VALIDATION_ERROR` envelope on any * schema problem with a `details.field` pointer the caller can act on. * * Stat-first guard mirrors piece-2's `readCodeFileGuarded`: oversize * payloads fai

(path: string)

 * 256 KB (vs. 350 KB for code) per the piece-6 spec.
 */
function readPlanStepsFileGuarded(path: string): CliPlanStep[] {
  const absolute = resolveAbsolute(path);

  let stat;
  try {
    stat = statSync(absolute);
  } catch (err) {
    const code = (err as NodeJS.ErrnoException).code;
    if (code === 'ENOENT') {
      throw localValidationError('steps', `file does not exist: ${path}`);
    }
    if (code === 'EACCES') {
      throw localValidationError('steps', `permission denied reading ${path}`);
    }
    const reason = err instanceof Error ? err.message : 'unknown error';
    throw localValidationError('steps', `cannot stat ${path}: ${reason}`);
  }
  if (stat.size > MAX_PLAN_STEPS_BODY_BYTES) {
    throw ApiError.fromEnvelope({
      error: {
        code: 'PAYLOAD_TOO_LARGE',
        message: `Plan-steps body exceeds the 256 KB CLI cap (${stat.size} bytes).`,
        nextAction: 'Split into multiple smaller tests or trim step descriptions.',
        requestId: 'local',
        details: {
          field: 'steps',
          sizeBytes: stat.size,
          maxBytes: MAX_PLAN_STEPS_BODY_BYTES,
        },
      },
    });
  }

  let raw;
  try {
    raw = stripBom(readFileSync(absolute, 'utf8'));
  } catch (err) {
    const reason = err instanceof Error ? err.message : 'unknown error';
    throw localValidationError('steps', `cannot read ${path}: ${reason}`);
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch (err) {
    const reason = err instanceof Error ? err.message : 'unknown error';
    throw localValidationError('steps', `not valid JSON: ${reason}`);
  }

  return assertPlanStepsShape(parsed);
}

/**
 * Type-narrow + validate a parsed `{ planSteps: [...] }` envelope.