[kvz]

Why

CLI downloads flatten HLS directories that playlists reference and save converted or bundled results under upload filenames. Public HTTP(S) inputs also fail before upload. Fixing those bugs must preserve the directory layout and freshness checks that existing scripts use.

Closes #593.
Closes #587.

Changes

• Use Assembly result names and extensions for directory downloads, including bundled files and video-to-JPEG/JSON conversions. Preserve ordinary input-relative parent directories and the existing <input>/<step>/… layout for multiple results.
• Retain time-based skipping for directory reruns: inputs with newer mapped outputs do not start another Assembly. --reprocess-stale still forces processing. Explicit file-output freshness behavior remains intact.
• Keep HLS paths from meta.relative_path, separate independent source bundles, reserve linked paths together, and stage linked watch downloads before publishing them. Preserve source ownership across result reordering using the original path and filename. Reject unsafe paths and descendant symlinks.
• Download public HTTP(S) inputs into isolated temporary uploads and clean them afterward. URL download deadlines default to five minutes and can be configured with --url-download-timeout; watch mode requires local inputs.
• Reserve result paths with case and Unicode normalization rules detected independently at the destination root; normalize collision keys after case folding.
• Ship minor changesets for @transloadit/node and transloadit, describing the layout repairs as bug fixes, per Kevin’s 2026-10-23 decision. Synchronize the generated legacy README.

Removing input parent folders only relocates working files, so that change has been dropped from this PR. #621 tracks an opt-in layout instead. HLS directories and incorrect result filenames remain repaired.

#595 already fixed inputless directory downloads and non-TTY stdin. Both checkboxes are ticked on #593; live imports on main succeeded with /dev/null and socket-backed fd 0.

Validation

• The restored directory freshness test first failed because the CLI started an extra Assembly. It now passes for standalone and directory inputs, verifies that existing bytes stay intact, and checks the explicit reprocessing override.
• Red-first CLI behavior tests cover video-to-JPEG/JSON filenames and the input/Step layout. Reinstating the old single-result download behavior reproduces both Save CLI results with their own file extension, not the input's #587 extension failures. A live /video/thumbs CLI run saved testsrc_0.jpg with verified JPEG bytes and no .mp4 output.
• Existing HLS, URL, collision, watch-ordering, and Unicode behavior regressions pass. The ordering test uses explicit concurrency 1 and associates results with their actual uploads.
• corepack yarn check passes, including all 1,119 Node tests (one test skipped), including 60 download-layout cases. Two live freshness E2E tests pass. Generated legacy-package sync and type checks pass.
• Earlier live reproductions demonstrated the original failures; all 13 HLS result checksums matched, independent and combined playlists decoded with ffmpeg, and repeated URL inputs retained both uploads/results.

Final CI passes on 1d5bb2aa: all 14 checks, including Node 20/22/24/26, E2E, full verification, and fixtures. The single blocking gh-run-watch completed with exit 0.

Review and follow-ups

Completed the two authorized review rounds on the rework diff only (DSP-473, option B, 2026-10-23), then stopped. All four retained findings are fixed:

• Round 1: preserve per-input folders for directory-output intents, propagate URL/base64 staging metadata, and retain watch changes when an older download finishes during their freshness check. Four behavior cases failed before the fixes and now pass.
• Round 2: refresh an input’s mapped single-file output in place after changes, so the next unchanged rerun skips processing again. Two behavior cases failed before the fix and now pass for standalone and directory inputs, including the explicit reprocessing override. Unrelated result paths keep collision protection.

No retained review finding remains unaddressed. The final freshness fix was tested after round 2; no third round was run.

• Honor nested filesystem naming rules for CLI downloads #615: nested destination filesystems with case or Unicode naming rules different from the output root.
• Separate HLS bundles sharing an upload in merged result Steps #619: independent HLS bundles sharing one upload in a merged result Step. Ambiguous duplicate linked paths remain rejected.
• Offer an opt-in CLI layout without input parent folders #621: an opt-in layout without input parent folders, preserving the default layout for existing scripts.

Reviewer tim-kos remains requested. The PR is assigned to kvz on project 12.

Overlap

Rebased onto current main after #610 and #612 merged. #610’s CLI reporting and error formatting are preserved; shared assemblies.ts and intentRuntime.ts hunks cover download/path logic, transient-input metadata, and the URL download option. #612’s upload stream cleanup is preserved; this PR does not change Transloadit.ts or tus.ts.

_{🤖 Claimed by kvz on studio1/node-sdk since 2026-10-23 · resume: codex resume 01a16a73-d73f-7e11-83fe-db48d62fa526}