[jrusso1020]

hyperframes cloud render --dry-run --json now lists every outside file the upload would leave out, so a wrapper (HyperFrames Desktop first) can tell the person before anything uploads. A full --json run reports the same list, and publish, cloud render and feedback count what they left out in telemetry.

Builds on #7598 (merged); rebased onto main. Refs #7598

Claude Opus 5.5

Why

When an upload leaves out a file the composition points at (a private location, or an outside file reached from a file that came in with an imported project, #7598), the CLI prints a warning naming it. A wrapper that runs the CLI and shows only progress and failures, such as Desktop's cloud render, never shows that warning to the person: the render arrives without the file and nothing says so. The product rule is that a skipped reference is always named to the person, never dropped silently. The CLI had no way to tell a program which files it will leave out.

What changed

• Preflight: cloud render --dry-run --json. This is the CLI's existing "build and inspect the zip without uploading" pattern, and Desktop already runs it to weigh a project for the cloud. Its archive now carries left_out:

  { "file": "index.html", "reference": "../notes.txt", "path": "../notes.txt", "reason": "received", "levels_up": 1 }

  file is the project file holding the reference (or the link itself, for a symlink), reference is as written, path is from the project folder (absolute only on another drive), reason is blocklisted or received, and levels_up is how many folders above the project it leads (null on another drive).
• During a real run (--json). The final JSON (--no-wait and waited) carries the same left_out list. Each file also prints a {"event":"left_out",…} line on stderr as it is left out, beside the existing human warning. That line uses the same shape as the existing upload_progress lines, so stderr readers that only parse upload_progress are unaffected.
• Plumbing. onLeftOut in publishProject.ts now takes a second, structured argument (LeftOutReference, new utils/leftOutReference.ts). Existing one-argument callers still type-check. The warning text is unchanged.
• Telemetry: cli_upload_left_out, sent once per staging that left something out (new telemetry/uploadLeftOut.ts, through the existing trackEvent). Properties: command (publish / cloud_render / feedback), dry_run, left_out_count, received_count, blocklisted_count, max_levels_up, levels_up_1, levels_up_2, levels_up_3_plus and other_drive. Only counts and depths, never a file name, reference or path; a test checks this.
• docs/packages/cli.mdx documents left_out under cloud render.

Scope notes

• publish and feedback --file-issue have no --json or dry-run mode, so they keep the human warning and gain the telemetry. All three paths stage through the same stagePublishFiles rules, so cloud render <dir> --dry-run --json answers "what would be left out" for publish too. Desktop drives only cloud render: its feedback guard refuses --file-issue, and it never runs publish.
• publishProject.ts (1060 → 1069 lines) and cloud/render.ts (1140 → 1159) were already over 600 lines before this change. The new logic lives in new small files, and those two files only gained the wiring.

Testing

• render.leftOut.test.ts runs the real CLI with cloud render --dry-run --json on an imported project that has one received and one blocklisted outside reference. It checks archive.left_out, one stderr left_out event per entry, and that the human warning is still printed.
• leftOutReference.test.ts covers the structured entry for a ../../ reference into a hidden folder (levels_up: 2), an absolute reference in a received file (path made relative to the project), and a symlink to a private file.
• uploadLeftOut.test.ts covers the event's counts and depth histogram, checks that no name or path appears in the properties, and checks that nothing is sent when nothing was left out.
• Locally: vitest run on src/commands/cloud, src/utils/publishProject*, publishProxyBake, publish, feedback, and the new tests: 222 passed. oxlint, oxfmt, typecheck, fallow audit and comment-ratchet --base origin/main all pass.

🤖 Generated with Claude Code

— Rames Jusso

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 13, 2026, 12:53 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 267 (base branch 267), smooth 121 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

• seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): fail / pass / pass, passes
• seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head c5932b3d

The left_out contract matches what hyperframes-internal#10620 parses: same file/reference on the stderr event and the human warning, so Desktop's dedup key holds, and a null levels_up maps to null. CI is green on this head.

Scope

Read in full: leftOutReference.ts, uploadLeftOut.ts, the publishProject.ts wiring (all three leaveOut sites plus the symlink loop in stagePublishFiles), cloud/render.ts (dry run, --no-wait and waited JSON), and publish.ts/feedback.ts. Checked: no telemetry property carries a name or path; --json keeps stdout clean (warning and event both go to stderr, and NO_COLOR comes from Desktop); levels_up on another drive. cli_upload_left_out also fires for each Desktop weigh dry run, with dry_run: true, so upload counts need dry_run = false.

— Genesis reviewer