Function runCodePut

src/commands/test.ts:3329–3459

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

 * sense (v3 → v4 bump). Matches piece-2's pattern.
 */
export async function runCodePut(
  opts: CodePutOptions,
  deps: TestDeps = {},
): Promise<CliPutTestCodeResponse> {
  assertIdempotencyKey(opts.idempotencyKey);
  requireNonEmpty('test-id', opts.testId);
  requireNonEmpty('code-file', opts.codeFile);

  if (opts.expectedVersion !== undefined && opts.force === true) {
    throw localValidationError(
      'expected-version',
      'is mutually exclusive with --force; pass one or the other (or neither for auto-fetch)',
    );
  }
  if (opts.language !== undefined && !CODE_PUT_LANGUAGES.includes(opts.language)) {
    throw localValidationError('language', `must be one of: ${CODE_PUT_LANGUAGES.join(', ')}`, [
      ...CODE_PUT_LANGUAGES,
    ]);
  }

  const code = opts.dryRun ? DRY_RUN_PLACEHOLDER_CODE : readCodeFileGuarded(opts.codeFile);

  const idempotencyKey = opts.idempotencyKey ?? `cli-code-put-${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}`);
  }

  // Resolve the If-Match header. Three cases:
  //   1. --force         → '*' (skip etag check; audit-logged)
  //   2. --expected-version <v> → that string verbatim
  //   3. neither         → auto-fetch via GET /tests/{id}/code, use
  //                        returned codeVersion. Tell the user (stderr)
  //                        so an operator watching can see the race
  //                        window we just opened.
  const client = makeClient(opts, deps);
  let ifMatch: string;
  if (opts.force === true) {
    ifMatch = '*';
  } else if (opts.expectedVersion !== undefined) {
    requireNonEmpty('expected-version', opts.expectedVersion);
    ifMatch = opts.expectedVersion;
  } else {
    const fetched = await client.get<CliTestCode>(`/tests/${encodeURIComponent(opts.testId)}/code`);
    const cv = fetched.codeVersion;
    if (cv === null || cv === undefined) {
      // Server hasn't stamped a codeVersion yet (legacy row). Send `*`
      // so the backend's force path applies the bump. Audit will mark
      // force: true — visible signal that our auto-fetch hit a
      // legacy row, not a concurrent-write race.
      ifMatch = '*';
      const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
      stderr(
        `auto-fetched codeVersion=null on legacy row; using If-Match: * for this put. Pass --expected-version explicitly to avoid this fallback.`,
      );
    } else {
      ifMatch = cv;
      const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));