Epic: a pipeline-native relix command #17

Build relix, a command for Unix pipelines, on the Relix engine's published API alone. Design: docs/design.md.

The shape

• stdout is data, stderr is talk. Each command writes one thing to stdout.
• Commands: run (the default), check, explain, optimize, trace, bundle, ir, provenance, fmt, catalog, drivers, connectors, doc, help, version, completion.
• Relix text arrives from -e, files or stdin.
• Data arrives with -i NAME=[FORMAT:]LOCATION (- is stdin).
• Output is table on a terminal and tsv in a pipe; csv, ndjson, json and markdown are on -o. A machine format prints the last query unless --query=NAME names another.
• The catalog comes from the directory tree. .relix/catalog/*.relix files are found walking up to $HOME, with a nearer declaration winning. Project catalogs are trusted per directory, as direnv does.
• Secrets come from the process environment or a user-only profiles.json. -P/--profile selects a profile.
• Exit codes distinguish usage, analysis, execution, environment and internal failures. SIGPIPE and SIGINT end a run cleanly.
• Packaging: jlink with an AppCDS archive, distributed through Homebrew and Scoop.
• One module, no library. The renderers, reports, script loader, profile loading and driver progress are internal packages of the command, and nothing is published to Maven Central. What the command needs goes into the command, or into the engine's published API when another embedder would need it too.

Engine API it needs

Still open: none.

Landed:

• Bind a relation to an input stream (CSV/TSV/JSON/NDJSON) with the connectors' parsers and schema inference relix-core#80: stream-backed inputs with the connectors' parsers and schema inference (S3).
• Resolve a source's relative path against the file that declares it relix-core#81: a relative source path resolves against its declaring file (S4).
• Bound query parameters ($name) supplied outside the script text relix-core#82: bound query parameters (S10).
• Closing a result stream cancels in-flight work (JDBC statement, HTTP fetch) relix-core#83: closing a stream cancels in-flight work (S2).
• Move the reference lookup into relix-docs: functions and front-end pages in one index relix-core#95: the reference lookup in relix-docs (S9, adopted in Adopt the relix-core#102 engine changes and drop their workarounds #37).
• Refuse a blocking operator over an unbounded Relix.input at plan time relix-core#98: a blocking operator over an unbounded Relix.input is refused at plan time (S3, adopted in Adopt the relix-core#102 engine changes and drop their workarounds #37).
• Keep comments, and offer the ASCII spelling, when printing a script relix-core#99: comments kept, and the ASCII spelling, when printing a script (S8, adopted in Adopt the relix-core#102 engine changes and drop their workarounds #37).
• Relation.render() of an optimised CLOSURE writes a seed the parser cannot read relix-core#100: Relation.render() of an optimised CLOSURE parses back (S7, adopted in Adopt the relix-core#102 engine changes and drop their workarounds #37).
• Bind a parameter from text: convert a String to the parameter's analysed type relix-core#101: a parameter's text read as its analysed type (S10).
• Print a comment at the end of a Markdown table row back on that row relix-core#106: a comment at the end of a table row printed back on that row (S8, with Align a table row that ends in a comment, and the rows after it #38).
• ScriptPrinter drops a blank line between a comment and the statement after it relix-core#107: a blank line between a comment and the statement after it kept when printing (S8, with Re-enable fmt's test that a blank line after a comment is kept #40).

Shipped

Merged to develop:

Outstanding

None: every slice has shipped.

Suggested order: S0a → S0b → S1 → S2a → S2 → S4+S5 → S7 → S9 → S6 → S8 → S3 → S10 → S11 → S12 shipped. S11's dry-run release runs once it reaches main.