Function runCreateFromPlan

src/commands/test.ts:1842–1963

(
  opts: CreateFromPlanOptions,
  deps: TestDeps = {},
)

 * when M3.3 lands.
 */
export async function runCreateFromPlan(
  opts: CreateFromPlanOptions,
  deps: TestDeps = {},
): Promise<CliCreateFromPlanResponse> {
  assertIdempotencyKey(opts.idempotencyKey);
  // codex #128 P2: validate the derived `<key>:run` chain key before the
  // create POST (see runCreate) so a near-limit base key fails fast instead
  // of orphaning a created test with no run.
  assertChainedRunKeyFits(opts.run, opts.idempotencyKey);
  requireNonEmpty('plan-from', opts.planFrom);

  if (opts.targetUrl !== undefined) {
    assertNotLocal(opts.targetUrl);
  }

  const plan = readPlanFromGuarded(opts.planFrom);

  // The plan validated (projectId/type/name/planSteps present). Only NOW
  // warn that overlapping `test create` flags were ignored — emitting this
  // before validation made a missing-projectId failure look like the
  // ignored --project flag was the cause (dogfood L1778).
  if (opts.ignoredFlags && opts.ignoredFlags.length > 0) {
    const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
    stderr(
      `warning: --plan-from supplies the test definition; ignoring ${opts.ignoredFlags.join(', ')}. ` +
        `Edit the plan JSON to change these fields.`,
    );
  }

  // FE-only after the 2026-05-13 scope cut. The server also rejects
  // BE plans, but bailing here saves a round trip and matches piece-2's
  // "fast-fail at the input gate" pattern.
  if (plan.type === 'backend') {
    throw ApiError.fromEnvelope({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Backend tests via the CLI require --code-file.',
        nextAction:
          "Backend tests via the CLI require '--code-file <path>'. Use 'testsprite test create --type backend --code-file foo.py'.",
        requestId: 'local',
        details: { field: 'type', reason: 'backend not supported in --plan-from path' },
      },
    });
  }

  const idempotencyKey = opts.idempotencyKey ?? `cli-create-plan-${randomUUID()}`;
  if (opts.idempotencyKey === undefined && (opts.output === 'json' || opts.verbose || opts.debug)) {
    const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
    stderr(`idempotency-key: ${idempotencyKey}`);
  }

  const body = {
    projectId: plan.projectId,
    type: plan.type,
    name: plan.name,
    description: plan.description,
    priority: plan.priority,
    planSteps: plan.planSteps,