fix: oa validate accepts a bare spec path (#94)

[sgriffiths]

What changed

oa validate <spec.yaml> — the form most people reach for first — now works. Previously it failed with No such command '<path>' because validate is a command group (for oa validate aac) and Click resolves a bare positional as a subcommand name before the callback's --spec option is ever considered.

The fix is a small custom TyperGroup: a leading *.yaml/*.yml token that isn't a known subcommand is rewritten to --spec before parsing. Everything else is preserved:

• oa validate aac (and its flags) route exactly as before — suffix-gating means aac is never touched.
• oa validate --spec path unchanged.
• Passing both a bare path and --spec is an explicit error ("not both"), rather than one silently winning.
• A genuine typo (oa validate acc) or non-YAML argument still errors, and the message now names the valid forms: oa validate <spec.yaml>, oa validate --spec <path>, oa validate aac.

README examples now show the shorter form as primary (with --spec noted as still supported).

One implementation note for review: the issue's sketch (an optional typer.Argument on the group callback) can't work — a group-level positional is consumed before subcommand resolution, so it would swallow aac. Hence the group-level rewrite instead. Also, typer ≥0.26 vendors its own click fork, so the group raises errors via ctx.fail() rather than raising click.UsageError directly — the public click exception classes don't match what typer's error rendering catches (raising the public class produces a raw traceback instead of the error panel).

Why

Closes #94. With an external project about to implement against the spec, the first command a newcomer runs shouldn't dead-end with a misleading error.

How tested

• All existing tests pass (pytest tests/ — 513 passed, 3 skipped)
• New tests added — tests/test_cli_validate.py, 8 cases: bare .yaml path, bare .yml path, --spec unchanged, both-forms error, missing-file bare path is a validation error (not "No such command"), aac still routes, typo and non-YAML arguments name the valid forms

Also: ruff check . clean, ruff format --check clean, mypy oas_cli clean. Manually exercised every form against the venv-installed CLI, including --help and no-args.

Type of change

• Bug fix

Checklist

• Code follows project style (ruff check . && ruff format --check .)
• Self-review completed
• Version bumped if needed — not needed; changelog entry added under Unreleased → Fixed

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
open-agent-spec	Ready	Preview, Comment	Jul 27, 2026 1:45am

[aswhitehouse]

Reviewed at 29bb9fd. The custom group rewrite is narrowly gated to leading YAML/YML paths, preserves aac and explicit --spec routing, rejects ambiguous dual input, and improves genuine typo errors. The focused CLI tests cover the important parsing paths, and CI is green. Approved.

[sgriffiths]

npm parity follow-up filed as #100 (bare spec path in the npm CLI, same guardrails). The no-suffix behaviour is indeed intentional — suffix-gating is what keeps aac routing and typo errors intact.