Skip to content

fix(cli): refuse an unknown ingest --step with exit code 2 - #783

Merged
kstonekuan merged 2 commits into
Hebbian-Robotics:mainfrom
vincentvega011:fix/ingest-unknown-step-exit-code
Nov 16, 2026
Merged

kstonekuan merged 2 commits into
Hebbian-Robotics:mainfrom
vincentvega011:fix/ingest-unknown-step-exit-code

Conversation

@vincentvega011

@vincentvega011 vincentvega011 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

hflow ingest --step NAME with no runtime addressed now refuses a step
selection it cannot honour with a one-line ingest: ... message and exit
code 2, before any episode is read. Previously it printed a Python traceback
and exited 1.

Two cases are covered:

  • a name no step is registered under:
    ingest: unknown step names ['nope']; registered steps: [...]
  • a step whose stage the profile disables, e.g. --profile relabel --step <a check>:
    ingest: selected steps belong to stages that are not enabled: [...]; enabled stages: ['labels']

Why

--step is a documented flag and a mistyped name is the most likely mistake
with it. docs/FORMAT.md defines exit code 2 as bad input and 1 as "ran, and
found something to report", so a script could not tell a typo from failed
episodes, and the reason was buried under a traceback.

_ingest_in_process only caught RuntimeError (the mass-failure gates), so
the ValueError from step selection escaped. The fix parses the selection up
front through the existing resolve_step_names_for_stage and guards only that
call. The handler around run_stages_directly is unchanged, so a ValueError
raised while processing still surfaces as a real failure.

Scope is the in-process executor only. The Airflow path is untouched: from
reading AirflowClient.ingest, step names are forwarded in the run conf
without being checked against the registered steps, so an unknown name there
is only refused inside the DAG tasks after the run is triggered. I have not
exercised that against a running runtime, and it seemed better handled
separately.

No transform behaviour or step version changes; no stored data is affected.

Validation

On macOS (Python 3.14, system ffmpeg 9.0.2):

  • uv run pytest -q tests/test_ingest_in_process.py -k step_selection
    • before the fix: 2 failed (raw ValueError from step selection)
    • after the fix: 2 passed
  • uv run ruff check --fix - All checks passed
  • uv run ruff format - 321 files left unchanged
  • uv run ty check - All checks passed
  • uv run pytest -q -n 4 - 2604 passed, 49 skipped
  • Manual, against a workspace with ingested synthetic episodes:
    • hflow ingest landing/ep1.mcap --step nope - one-line message, exit 2
    • hflow ingest landing/ep1.mcap --profile relabel --step timestamps - one-line message, exit 2

Not run: the lychee link check (not installed; the docs edit adds no links)
and the opt-in Docker runtime tests (the runtime path is unchanged).

Checklist

  • I added or updated outcome-focused tests for changed business logic.
  • I updated documentation for changed behavior, flags, formats, or requirements.
  • I ran uv run ruff check --fix, uv run ruff format, and uv run ty check.
  • I ran the relevant pytest suite.
  • I did not add recordings, generated media, credentials, private URLs, or runtime artifacts.
  • I preserved stored-data compatibility or documented an explicit version change.

Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

Running `hflow ingest --step NAME` with no runtime addressed crashed with
a traceback and exit code 1 when NAME was not a registered step, or when
its stage was disabled by the chosen --profile. Both are bad input, which
docs/FORMAT.md assigns exit code 2 and a `command: message` line.

The in-process executor now parses the step selection before it announces
or starts any processing and reports a refusal as `ingest: <reason>`. Only
that parse is guarded: an error raised while episodes are being processed
still surfaces as before.
@github-actions

Copy link
Copy Markdown

👋 Hi @vincentvega011 — thank you so much for your first contribution to HFlow!

A maintainer will review your pull request as soon as possible. In the meantime:

💡 Tip: one open pull request per contributor at a time. Before starting an issue, check its sidebar for an assignee or a linked pull request. Either one means somebody is already on it; everything else is fair game.

We are excited to have you here and appreciate your help making the project better! 🙌

@greptile-apps

greptile-apps Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Low impact] The PR appears safe to merge.

Summary

In-process hflow ingest rejects unknown or disabled-stage --step names with a short message and exit code 2 before reading episodes.

  • In-process ingest rejects invalid --step choices before reading episodes.

Reviews (2) · Last reviewed commit: "fix(cli): validate the ingest step selec..." · Reviewed by Greptile

greptile-apps[bot]
greptile-apps Bot previously approved these changes Nov 14, 2026

@kstonekuan kstonekuan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Behaviour's right, and both new tests fail without the fix.

_ingest_in_process picks enabled_stage_names[0] to call a per-stage resolver and throws the answer away, and it takes five lines of comment to explain why. Can the selection be validated without naming a stage?

Also, how does a TypeError reach that except from the CLI?

Add a public, stage-free resolve_step_selection in stage_execution and route its callers through it. The in-process ingest path now validates the selection with it before the banner instead of borrowing the per-stage resolver, and catches only ValueError: Typer only passes list[str] | None, so the TypeError guards cannot fire from the CLI.
@greptile-apps
greptile-apps Bot dismissed their stale review November 16, 2026 17:45

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

@vincentvega011

Copy link
Copy Markdown
Contributor Author

Thanks! Yes: run_stages_directly already validates the whole selection stage-free, so I added a public resolve_step_selection in stage_execution, and every caller in that module plus the CLI now goes through it. The CLI calls it before the banner and the comment is gone.

It can't: Typer only ever passes list[str] | None, so the type guards never fire from the CLI. I've dropped TypeError from the except.

If you'd rather the selection be parsed once, I can have run_stages_directly take the resolved selection instead of re-parsing step_names.

@kstonekuan kstonekuan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, merging. Both new tests fail without the fix, 2638 passed on a merge with main. Thanks!

@kstonekuan
kstonekuan merged commit e3cd885 into Hebbian-Robotics:main Nov 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants