feat(cli): openfilter emit-schema (FILTER-442)

[stwilt]

📦 Pull Request

📋 What does this PR do?

Adds the openfilter emit-schema <module>[:Class] CLI subcommand — the build-time producer half of the FC-3 schema-transport contract. The command imports a filter module, locates its FilterConfigBase subclass, and writes the emitted JSON Schema (draft 2020-12) to stdout (default) or -o <path>. Filter Dockerfiles invoke this at build time; the resulting JSON is pushed as a sibling OCI artifact (application/vnd.openfilter.schema+json) and the image manifest is stamped with a com.plainsight.openfilter.schema label carrying the artifact's sha256 digest.

Specifically:

• New openfilter/cli/cmd_emit_schema.py — argparse-driven subcommand with module / module:Class resolution, automatic candidate detection (errors out cleanly when a module declares 0 or 2+ FilterConfigBase subclasses), --include-managed opt-in to surface platform-managed fields, and -o <path> output redirection.
• Tweak the openfilter CLI dispatcher (openfilter/cli/__main__.py) to translate cmd-with-hyphens to cmd_with_hyphens so subcommands can use their canonical hyphenated spellings without breaking the underscore-named Python handler convention.
• 5 unit tests in tests/test_emit_schema_cli.py covering stdout output, -o <path>, --include-managed, single-class auto-pick, and unknown-class failure.

The wiring of the sibling-artifact upload + label-stamping into cloudbuild-cascade.yaml is tracked as a sub-step of FILTER-442; it depends on PLAT-side FC-5 ingest and lands separately.

---

🔍 Why is this needed?

FILTER-441 landed FilterConfigBase.emit_schema() — the in-process serializer that produces each filter's JSON Schema. This PR is the CLI wrapper Dockerfiles invoke at build time so the artifact can ride alongside the image without a Python-runtime hop in the platform's ingest path.

Once both are in place, the transport contract closes: filter CI emits the schema, pushes it as a sibling OCI artifact, and stamps the image manifest's com.plainsight.openfilter.schema label with the sha256 digest. The platform fetches the artifact by digest from the same registry without pulling the filter image's layers. Integrity is transitively protected by whatever trust we already place in the registry serving the image bytes — no separate key infrastructure needed.

(Cosign-signed attestations were considered for the transport but deferred to a future-driver-only ticket — see
FILTER-448, closed Won't Do — the marginal threat surface didn't justify standing up KMS for the first internal use.)

---

🧪 How was it tested?

5 unit tests in tests/test_emit_schema_cli.py:

• test_emit_schema_cli_stdout — module:Class spec, stdout output, $schema keyword + managed-field stripping
• test_emit_schema_cli_writes_file — -o <path> redirection
• test_emit_schema_cli_include_managed_surfaces_overrides — --include-managed round-trips FC-2 markers
• test_emit_schema_cli_auto_picks_single_class — module-only spec finds the lone FilterConfigBase subclass
• test_emit_schema_cli_fails_on_unknown_class — typo'd class name errors out cleanly

$ uv run --with pytest pytest tests/test_emit_schema_cli.py -q
.....                                                                    [100%]
5 passed in 1.79s

Combined with FILTER-441's config-side suite (already merged in #86, 46 tests), the full FC-1 / FC-1.5 / FC-2 / FC-3-emission contract has 51 tests exercising it end-to-end.

---

🔗 Related Issues

• FILTER-442 — this ticket
• FILTER-441 — FilterConfigBase.emit_schema() (merged in feat(filter_runtime): typed FilterConfigBase + emit_schema (FILTER-441) #86)
• FILTER-440 — Declarative Configuration Contract (parent epic)
• FILTER-448 — cosign / KMS signing (closed Won't Do; revisit on concrete compliance/multi-tenancy driver)

---

🖼️ Screenshots or Logs (if applicable)

$ openfilter emit-schema my_filter.filter --include-managed
{
  "title": "MyFilterConfig",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "sources": {
      "items": {"format": "video-source", "type": "string"},
      "type": "array",
      "x-openfilter-managed": true,
      "x-openfilter-resolve": "orchestrator-generated"
    },
    "confidence_threshold": {
      "type": "number", "minimum": 0, "maximum": 1, "default": 0.5
    },
    ...
  }
}

---

✅ Checklist

• I have read and agreed to the terms of the LICENSE
• I have read the CONTRIBUTING guide
• I have followed the coding style
• I have signed all commits in compliance with the DCO (git commit -s)
• I have added or updated tests as needed
• I have added or updated documentation as needed (docs/declarative-config.md's "Schema emission" section, landed with FILTER-441 in feat(filter_runtime): typed FilterConfigBase + emit_schema (FILTER-441) #86, already describes this CLI's surface)

[lucasmundim]

LGTM. Clean dispatcher tweak, correct use of the FilterConfigBase.emit_schema(include_managed=...) API from #86, and a reasonable test set. A few non-blocking notes for follow-up:

• Non-atomic write to -o <path>: cmd_emit_schema.py writes directly with open(path, "w"). If this ever feeds OCI artifact upload at build time, a tempfile.NamedTemporaryFile on the same filesystem + os.replace() would avoid leaving a partial file on interruption.
• Unwrapped importlib.import_module in _resolve_config_class: every other failure branch raises a clean SystemExit(...), but a bad module path falls through as a raw ModuleNotFoundError traceback. Minor consistency nit.
• Dead setdefault calls for title and $schema in the CLI: both keys are already injected by pydantic and FilterConfigBase.emit_schema() respectively, so the CLI's setdefault calls are no-ops and can be removed.
• Auto-detect edge cases worth keeping in mind: module-level class aliases (Alias = MyConfig) would be yielded twice by inspect.getmembers, and package re-exports (__init__.py re-exporting a class defined in a submodule) would fail the __module__ check. Neither pattern is used in the repo today — flagging in case third-party filters hit them.

[shingonoide]

Echoing Lucas's APPROVE — adding one finding worth picking up alongside his follow-ups, plus a test-coverage note.

LOG_LEVEL typo crashes the entire openfilter CLI at import time (cmd_emit_schema.py:25)

logger.setLevel(int(getattr(logging, (os.getenv("LOG_LEVEL") or "INFO").upper())))

getattr(logging, "VERBOSE") (or any other typo / unsupported level) raises AttributeError at module import. Because openfilter/cli/__main__.py imports cmd_emit_schema unconditionally, a bad LOG_LEVEL in the build environment doesn't just break emit-schema — it breaks openfilter run, openfilter info, and any future subcommand the dispatcher tries to load. Suggested fix:

logger.setLevel(getattr(logging, (os.getenv("LOG_LEVEL") or "INFO").upper(), logging.INFO))

(The int(...) cast is also unneeded — logging.INFO is already an int.)

Test coverage gaps tied to the import paths

The 5 tests cover happy paths well; two negative-path gaps worth filling alongside Lucas's import_module wrap:

• No test for ModuleNotFoundError (e.g. ["emit-schema", "no.such.module"]) — would lock in his suggested wrap.
• test_emit_schema_cli_fails_on_unknown_class exercises getattr(...) is None, but not the inspect.isclass(cls) and not issubclass(cls, FilterConfigBase) branch (cmd_emit_schema.py:48-52). Passing a non-Filter attribute (module:dict) would close that hole.