S1: command skeleton — script sources, exit codes, diagnostics, profiles, engine options #4

Part of #17. Design: docs/design.md §3, §3.1, §3.4, §3.5, §4, §5.5.

Scope

The relix command's skeleton, which every later slice builds on.

• Command shape. A picocli root with subcommands, and run as the default command. POSIX short options that cluster, GNU --opt=value, -- to end options, - meaning stdin.

• Where the script comes from (§3.1), in this order:

  1. -e/--expr (repeatable). A bare expression is wrapped as a query via Relix.relation(String).
  2. SCRIPT... files.
  3. stdin, when it is not a terminal.
  4. Otherwise print usage and exit 2.

  Each file runs in a session of its own.

• Exit codes (§3.4), in one mapping in Main:

  Code	Meaning
  0	success
  2	usage
  3	parse or analysis
  4	execution
  5	environment
  70	internal
  130	SIGINT
  141	SIGPIPE

  Code 1 (assertions) belongs to S2.

• Diagnostics (§3.5): FILE:LINE:COL: severity: message on stderr. -q silences warnings, -v adds notices (loaded drivers), -vv adds timings. Nothing but the result ever goes to stdout.

• Profiles and placeholders (§5.5):

  • -P/--profile (RELIX_PROFILE) and -D NAME=VALUE.
  • profiles.json, merged across levels, nearest winning.
  • ${VAR} resolves from -D, then the profile, then the process environment, lazily through Builder.placeholders.
  • A profiles.json that group or others can read is refused, naming the chmod that fixes it (skipped on Windows).

• Engine options (§4):

  • --now/RELIX_NOW, --max-fixpoint-rounds, --max-materialized-rows
  • new: --max-processed-rows, --timeout, --sandbox=FILE, --remote, --allow-download

• -C DIR: act as if started in DIR.

• run streams rows through the relix-console renderers. Full output handling is S2.

Dependencies

• S0a (S0a: project build — Gradle, engine pin, boundary test, CI #2), S0b (S0b: console support as internal packages of the command #3).

Seams

• relix-cli: packages command/, io/ (ScriptSource) and config/.
• config/ is written here, not copied: the earlier command's only configuration code was the relix-env.json loader, which the design drops (§8). Its flat JSON parser may be reused if profiles.json keeps the {profile: {NAME: value}} shape.
• Only the engine's embed facade and the types it exports; S0a's boundary test holds that.

Acceptance

• Every input source and the precedence between them are tested end-to-end through Main with captured streams.
• The exit-code table is a parameterised test.
• Placeholder precedence and the profile permission check are tested over @TempDir trees.