# 30 — User-defined commands should behave like real shell commands

**Status:** open

**Related:** #26 (user builtins), #06 (piping), #15 (builtins)

## Problem

User-defined builtins registered via `lush.builtins.mycmd = function(name, arg, ...) end` are called directly as Lua functions in the parent process. This means:

1. **No stdout/stderr capture** — `print()` inside the function writes directly to the terminal, not into the `{code, stdout, stderr}` result table. Backtick invocation returns `nil` instead of a result table.
2. **No pipe support** — piping to/from a user builtin fails because `exec_pipeline()` forks children that call `execvp()`, which can't find the function as an external command.
3. **No redirection support** — for the same reason, `>`, `>>`, `2>` etc. won't work.

Current behavior:

```
$ pat hello          -- prints "hello", returns nil (no result table)
$ `pat hello`        -- prints "hello", returns nil (no .stdout)
$ !pat hello | nvim  -- "pat: No such file or directory"
```

In bash, user-defined functions work exactly like external commands at the call site — they can be piped, redirected, and captured. Lush should match this.

## Proposal

### Restructure the lush table

Separate built-in commands from user-defined commands:

- **`lush.builtins`** — reserved for C builtins (`cd`, `exec`, `umask`) that must run in-process because they modify parent process state. Read-only / not user-extensible.
- **`lush.commands`** — user-defined commands. These are Lua functions that behave like shell commands: they run in a forked subprocess, their stdout/stderr are captured, and they work with pipes and redirection.

Dispatch order: alias expansion → `lush.commands` → `lush.builtins` → `$PATH` lookup.

### Fork user commands into a subprocess

When dispatching a `lush.commands` entry:

1. Set up stdout/stderr capture pipes (same as external command execution)
2. `fork()`
3. **Child**: wire stdout/stderr to the pipe write ends, call the Lua function, `_exit()` with the return code
4. **Parent**: read captured output, `waitpid()`, build and return the `{code, stdout, stderr}` result table

This makes user commands compatible with `exec_pipeline()` — each pipeline stage already forks a child, so the child just needs to check `lush.commands` before falling through to `execvp()`.

**Important caveat**: because user commands run in a forked child, they **cannot** modify parent Lua state. Setting a global variable inside a `lush.commands` function will not be visible after the command returns. This matches how bash functions behave when used in a pipeline (bash also forks subshells for pipeline stages). This trade-off should be clearly documented.

### Return protocol

User commands should follow the same return convention as C builtins:

- Return a table `{code=int, stdout=string, stderr=string}`, OR
- Return an integer exit code (0 = success), OR
- Return nothing (implies exit code 0)

The forked child captures whatever the function `print()`s as stdout, and uses the return value for the exit code.

## Files

| File | Change |
|------|--------|
| `lcmd.c` | Split `try_builtin()` into `try_builtin()` (in-process, `lush.builtins` only) and `try_user_command()` (fork+capture, `lush.commands`); add `lush.commands` check in pipeline child processes |
| `lbuiltin.c` | Register C builtins under `lush.builtins`; create empty `lush.commands` table for user use |

## Open questions

- Should user commands receive stdin naturally (child inherits the pipe fd, `io.read()` works) or as a string argument? Leaning toward natural stdin inheritance — matches bash and the child's stdin is already wired.
- Naming: `lush.commands` vs `lush.functions` vs `lush.cmds`? `commands` is clearest.