Module scaffold 

tarn scaffold — bootstrap a minimal .tarn.yaml skeleton from one of four inputs (OpenAPI operation id, raw curl command, explicit method+URL, or a previously-recorded fixture).

The scaffold is intentionally scaffold-quality: the generated YAML parses and validates, the request block is correct enough to execute, and placeholder assertions + captures hint at what the user should tighten — every inferred-but-unverified fragment is marked with a machine-greppable # TODO: comment so agents can drive the next iteration without rereading the whole file.

Determinism is load-bearing: running scaffold twice with identical inputs must produce byte-identical output, including TODO ordering. Every map the emitter walks uses BTreeMap / pre-sorted Vec for that reason, and no clock / RNG state is read at scaffold time. Random placeholders emit Tarn built-in names ($uuid_v4, $random_hex(8)) instead — those resolve deterministically under the faker seed when the test runs, not when the YAML is written.

Modules

curl

tarn scaffold --from-curl <file> — parse a single curl invocation out of a text file and rebuild the Tarn skeleton.

emit

Hand-rolled YAML emitter for scaffold output.

explicit

tarn scaffold --method <M> --url <U> — the minimal-input mode.

openapi

tarn scaffold --from-openapi <spec> --op-id <id> — walk a minimal OpenAPI 3.x document and produce a Tarn skeleton.

recorded

tarn scaffold --from-recorded <path> — rebuild a Tarn skeleton from a previously-recorded fixture (NAZ-252 store under .tarn/fixtures/.../<N>/*.json).

Structs

ScaffoldOptions

Override struct carrying shared options — filled by the CLI once before dispatching into a mode. Keeping this separate from ScaffoldInput means mode unit tests don’t have to fabricate unrelated CLI state.

ScaffoldRequest

Internal, mode-agnostic scaffold IR. Each of the four input modes produces one of these; emit::render is the single consumer. BTreeMap for headers is not accidental — YAML rendering order determines TODO line numbers and the determinism acceptance criterion requires stable iteration even when the same header set comes from two different modes.

ScaffoldResult

Output of generate: the rendered YAML, the TODO list (with final line numbers), a copy of the inferred request, and the round-trip validation report.

Todo

A single TODO marker the emitter will interleave as # TODO: comment above the anchor line in the rendered YAML. line is back-filled by emit::render after layout so callers consuming --format json see the line number they would grep -n in the file.

Enums

BodyShape

Body payload carried through the pipeline. We keep the structural form (Json) when we can synthesise a mapping and fall back to a raw string for non-JSON content-types; the emitter renders each branch differently.

ScaffoldInput

Inputs for generate. The four fields are mutually exclusive; the CLI dispatcher validates that exactly one is populated and surfaces a structured error otherwise.

SourceMode

Which input mode produced a ScaffoldResult. The string form is a public contract for the --format json surface; renaming a variant is a breaking change.

TodoCategory

Categorises a TODO so agents can filter the list without text-matching on the human message. Kept deliberately small — each category maps to a concrete review action (“check auth headers”, “fill required body fields”) rather than a free-form tag cloud.

Functions

generate

Top-level dispatcher. Runs the mode-specific scaffolder, renders YAML with interleaved TODO comments, and round-trips the result through crate::parser::parse_str so a shape-mistake in the scaffold itself surfaces as an error instead of a silently broken file.