Add RunProcess, a safer alternative to Exec

[fingolfin]

Grew out of #5103, and hence closes #5103.

Exec hands its concatenated arguments to a shell. That makes it hard to pass arguments containing spaces or quotes, ties the behaviour to whichever shell happens to be installed, discards the exit code, and wires the child process to the user's terminal.

RunProcess takes the program and its arguments as separate strings and runs it directly:

RunProcess( cmd[, arg1, ..., argN][, options] )  ->  rec( status[, output] )

For example:

gap> RunProcess("echo", "GAP is great!");
rec( output := "GAP is great!\n", status := 0 )
gap> RunProcess("false").status;
1

• Nothing needs quoting or escaping, and no shell is involved.
• The exit code is returned rather than thrown away; a nonzero code is not an error, it is up to the caller to check.
• Output is captured by default instead of being printed.
• Input defaults to nothing at all, rather than to whatever the user types.

The price is that shell features such as redirections and wildcard expansion are gone, so Exec stays; its documentation now points here for new code.

What changed since #5103

The draft let the working directory and the streams appear as positional arguments in any order. Following the discussion there (@ChrisJefferson, @wilfwilson), everything beyond the command line now goes into an optional trailing options record with the keys directory, input and output:

RunProcess("sort", rec(input := someStream, output := OutputTextUser()));

Unknown keys are rejected rather than ignored. That is the point of the record: GAP currently cannot capture a child process's standard error at all (#4657), and this leaves room to add an error key later without breaking any caller — and without older GAP versions silently dropping it.

The name is the other thing #5103 stalled on. RunProcess sits next to the existing Process operation, reads as a verb, and matches Mathematica's RunProcess and Python's subprocess.run.

Arguments must be strings or integers; anything else is an error. Deliberately not String-ing arbitrary objects, as that would close off future extensions.

Co-authored-by: Claude Opus 5 noreply@anthropic.com

[codecov]

Codecov Report

❌ Patch coverage is 73.40426% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.01%. Comparing base (ccd2458) to head (e4d4b60).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
lib/helpview.gi	0.00%	18 Missing ⚠️
lib/streams.gi	0.00%	5 Missing ⚠️
lib/process.gi	97.14%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6536      +/-   ##
==========================================
+ Coverage   78.97%   79.01%   +0.04%     
==========================================
  Files         683      683              
  Lines      294944   295015      +71     
  Branches     8638     8638              
==========================================
+ Hits       232919   233098     +179     
+ Misses      60214    60098     -116     
- Partials     1811     1819       +8     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[lgoettgens]

Looks good overall. Some maybe stupid questions

[lgoettgens]

The docstring states that DirectoriesSystemPrograms is used for lookup. Is this implementation here semantically equivalent?

[fingolfin]

Not quite equivalent, and the docstring was the inaccurate part. PathSystemProgram walks the same DirectoriesSystemPrograms() directories but additionally requires IsExecutableFile, whereas plain Filename would also accept a non-executable file of that name. The stricter behaviour is what we want, so Claude reworded the documentation to name PathSystemProgram directly.

Following this up turned out to be worthwhile, as it exposed two further problems, now fixed:

• RunProcess("") silently returned status := fail. PathSystemProgram("") returns a directory, and directories pass IsExecutableFile, so the lookup "succeeded" and the exec failed in the kernel. Empty command names are now rejected, with a test.
• status is not always an exit code. FuncExecuteProcess maps 255 to fail, and a failed execve in the forked child exits with 255 — so fail means "could not execute", and a program genuinely exiting with 255 is indistinguishable from it. Both facts are now documented. (I'll ponder whether perhaps we should/could change this in ExecuteProcess).

Claude also documented that a cmd containing a path separator is resolved relative to GAP's current directory, not the directory option. This is inherited Process behaviour, but surprising enough to state.

[fingolfin]

The exit code 255 vs. fail issue is being tackled in PR #6565 but that's work in progress.