feat(opal): port opal validation from Go CLI

[beengud]

Closes #4

Summary

Ports the opal validation/inspection commands from the deprecated Go Observe CLI into the TypeScript CLI, preserving the original output contracts and exit codes.

New command surface (observe opal …):

• check <pipeline> / check --file <path> (-f) — validate an OPAL pipeline via the checkQueries API. Prints each error as ERROR row:col: message and exits 1; prints warnings-only as WARN kind row:col and exits 0; on success prints OK followed by the indented result-schema field names. Errors with empty text (which the API returns when compilation requires an input dataset) are suppressed, matching the Go behavior.
• verbs — list all OPAL verbs (name, comma-joined categories, description), sorted by name, tab-separated. Adds --format json|csv.
• functions — list all OPAL functions (name, categories, return type, description), sorted by name, tab-separated. Adds --format json|csv.
• validate-ingest --dataset <id> <pipeline> — validate an ingest filter expression via validateIngestFilterExpression. Null/empty result → OK; diagnostics → ERROR: message per entry and exit 1.

GraphQL operations reproduced from the Go source (cmd_opal.go, cmd_opal_validate.go, ot_opal.go) under src/gql/opal/:

• CheckQueries($queries: MultiStageQueryInput!)
• VerbsAndFunctions
• ValidateIngestFilter($pipeline: String!, $sourceDatasetID: ObjectId!)

Registered the opal route in src/app.ts (before cli), and updated the README Commands table and the AGENTS.md Project Structure.

Verification status

• Codegen / typecheck could not run locally: GraphQL introspection is disabled on the available tenant, so bun run codegen cannot generate src/gql/generated/graphql.ts. As a result tsc / bun run typecheck / bun build / the full bun run test pipeline are expected to fail on the missing generated types. Nothing under src/gql/generated/ was hand-written or committed.
• Unit tests run and passing (the gql wrapper modules are mocked via mock.module before import, so the generated-types import is never executed at runtime):
  • src/commands/opal/check.test.ts
  • src/commands/opal/verbs.test.ts
  • src/commands/opal/functions.test.ts
  • src/commands/opal/validate-ingest.test.ts
  • Result: 19 pass / 0 fail (48 assertions).

Assumptions / risks (could not verify against a live schema)

• GraphQL field/type names were reproduced from the Go source, not validated against introspection. In particular: MultiStageQueryInput with outputStage + stages[{stageID, pipeline, input}]; checkQueries returning a list with parsedPipeline.errors{col,row,text} and parsedPipeline.warnings{kind, symbol{col,row}} and resultSchema.fieldList{name}; verbsAndFunctions using categories (array) and returnType; and validateIngestFilterExpression returning a list of { message }. The generated TS type names (CheckQueriesDocument, etc.) follow the codegen convention and will resolve once codegen is run.

🤖 Generated with Claude Code