From 9e75175c793e1b213d11a1fd1739deb106642ade Mon Sep 17 00:00:00 2001
From: Cormac Shannon <>
Date: Wed, 4 Mar 2026 23:28:11 +0000
Subject: [PATCH] =?UTF-8?q?Add=20issues=20#16=E2=80=93#23?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#16 multiline shell commands
#17 _ scope (global vs local)
#18 path expansion (~)
#19 nested commands trigger prompt2
#20 simplify backtick return value
#21 prompt redesign
#22 implicit interactive commands (drop ! prefix)
#23 general cleanup and refactor
---
 issues/16-multiline-shell-commands.md      | 11 ++++++++
 issues/17-underscore-scope.md              | 15 +++++++++++
 issues/18-tilde-expansion.md               | 27 +++++++++++++++++++
 issues/19-nested-commands-prompt2.md       | 12 +++++++++
 issues/20-backtick-return-value.md         | 30 ++++++++++++++++++++++
 issues/21-prompt-redesign.md               | 27 +++++++++++++++++++
 issues/22-implicit-interactive-commands.md | 21 +++++++++++++++
 issues/23-cleanup-refactor.md              | 20 +++++++++++++++
 8 files changed, 163 insertions(+)
 create mode 100644 issues/16-multiline-shell-commands.md
 create mode 100644 issues/17-underscore-scope.md
 create mode 100644 issues/18-tilde-expansion.md
 create mode 100644 issues/19-nested-commands-prompt2.md
 create mode 100644 issues/20-backtick-return-value.md
 create mode 100644 issues/21-prompt-redesign.md
 create mode 100644 issues/22-implicit-interactive-commands.md
 create mode 100644 issues/23-cleanup-refactor.md

diff --git a/issues/16-multiline-shell-commands.md b/issues/16-multiline-shell-commands.md
new file mode 100644
index 00000000..2a621406
--- /dev/null
+++ b/issues/16-multiline-shell-commands.md
@@ -0,0 +1,11 @@
+# 16 — Multiline shell commands
+
+**Status:** open
+
+Can we handle multiline shell commands? For example, commands that span multiple lines with continuations or heredocs. Currently unclear if backtick syntax or `!` prefix handles this at all.
+
+## Questions
+
+- What should the syntax look like for multiline commands?
+- Should `\` at end-of-line continue a command?
+- How does this interact with prompt2?
diff --git a/issues/17-underscore-scope.md b/issues/17-underscore-scope.md
new file mode 100644
index 00000000..90291e69
--- /dev/null
+++ b/issues/17-underscore-scope.md
@@ -0,0 +1,15 @@
+# 17 — `_` is global rather than local
+
+**Status:** open
+
+The `_` result variable from interactive commands (`!cmd`) is set as a global via `lua_setglobal(L, "_")`. This has several implications:
+
+- It can escape its scope and pollute other scopes
+- A function may silently overwrite `_` if it uses shell commands internally, surprising the caller
+- Lua convention uses `_` as a throwaway variable in `for` loops (`for _, v in pairs(t)`)
+
+## Investigation needed
+
+- What are the concrete consequences of `_` being global vs local?
+- Can we make it local to the REPL line instead?
+- Should we use a different name entirely?
diff --git a/issues/18-tilde-expansion.md b/issues/18-tilde-expansion.md
new file mode 100644
index 00000000..4286a8c1
--- /dev/null
+++ b/issues/18-tilde-expansion.md
@@ -0,0 +1,27 @@
+# 18 — Path expansion (`~`, `*`, `**`)
+
+**Status:** open
+**Related:** #13 shell globbing
+
+Path expansion for `~` is not available. Commands like:
+
+```
+!cat ~/Notes/jobs_board.md
+```
+
+fail with:
+
+```
+cat: ~/Notes/jobs_board.md: No such file or directory
+```
+
+The `~` and other expansions are passed literally to the command rather than being expanded to `$HOME`.
+
+## Requirements
+
+- `~` at the start of a word should expand to `$HOME`
+- Should work in both backtick and `!` prefix contexts
+
+### To invesitigate/decide
+
+- How should it interact with quoting (quoted `~` should not expand), should single/double quotes be used? both? or something else?
diff --git a/issues/19-nested-commands-prompt2.md b/issues/19-nested-commands-prompt2.md
new file mode 100644
index 00000000..056f9061
--- /dev/null
+++ b/issues/19-nested-commands-prompt2.md
@@ -0,0 +1,12 @@
+# 19 — Nested commands in interactive mode trigger prompt2
+
+**Status:** open
+
+Running nested commands in an interactive command drops into prompt2 when it shouldn't:
+
+```
+~/Code/20251000_lush> !echo ${`ls`.stdout}
+>>
+```
+
+The parser sees the opening `{` and thinks the expression is incomplete, waiting for more input. The nested backtick command should be parsed and evaluated inline.
diff --git a/issues/20-backtick-return-value.md b/issues/20-backtick-return-value.md
new file mode 100644
index 00000000..d1e0434f
--- /dev/null
+++ b/issues/20-backtick-return-value.md
@@ -0,0 +1,30 @@
+# 20 — Simplify backtick return value
+
+**Status:** open
+
+Currently backtick expressions return a table `{code, stdout, stderr}`, requiring verbose access:
+
+```lua
+!echo ${`ls`.stdout}
+```
+
+This is explicit but noisy for the common case. Consider making backticks return stdout directly, with the full result table still available via `_`:
+
+```lua
+-- backtick returns stdout string directly
+local files = `ls`
+
+-- full result still available in _
+print(_.code)
+print(_.stderr)
+```
+
+## Considerations
+
+- This would be a breaking change to current backtick semantics
+- The table is still useful when you need exit code or stderr
+- Could we return multiple values? `stdout, result_table = \`cmd\``
+- How does this interact with pipelines where you chain results?
+
+- This would unify the interface/behaviour of backticks and ! commands, both set the majority of their data to `_`
+- Main difference is where do they output their stdout & stderr
\ No newline at end of file
diff --git a/issues/21-prompt-redesign.md b/issues/21-prompt-redesign.md
new file mode 100644
index 00000000..c58314a1
--- /dev/null
+++ b/issues/21-prompt-redesign.md
@@ -0,0 +1,27 @@
+# 21 — Prompt redesign
+
+**Status:** open
+
+Reconsider the prompt system. Some observations:
+
+## Functional prompts via metatables
+
+Functional prompts can be achieved in pure Lua without special support:
+
+```lua
+_PROMPT = setmetatable({}, { __tostring = function(self)
+    local user = os.getenv("USER") or os.getenv("USERNAME") or "user"
+    local cwd  = os.getenv("PWD") or io.popen("pwd"):read("*l") or "?"
+    return string.format("%s:%s$ ", user, cwd)
+end })
+```
+
+This suggests our bespoke prompt implementation (issue #09) may be overengineered. A template-based approach or just documenting the metatable trick might suffice.
+
+## Prompt2 depth
+
+Prompt2 is rigid — opening deeper and deeper blocks results in a prompt at the same level. Bash doesn't do depth indication either, so maybe this is fine. Options:
+
+- Pass depth into `_PROMPT2` somehow
+- Add indentation (spaces/tabs) after prompt2 on the C side
+- Accept it as-is (bash doesn't do this either)
diff --git a/issues/22-implicit-interactive-commands.md b/issues/22-implicit-interactive-commands.md
new file mode 100644
index 00000000..8db216fe
--- /dev/null
+++ b/issues/22-implicit-interactive-commands.md
@@ -0,0 +1,21 @@
+# 22 — Implicit interactive commands (drop `!` prefix)
+
+**Status:** open
+
+In the REPL, maybe we can get away with not needing the `!` prefix.
+
+Lua already attempts to run input as a statement. If that fails, it assumes it might be an expression (e.g. `1 + 2`) and wraps it in `return(...)`. If *that* also fails, we could try wrapping it with `!` prefix semantics as a third fallback.
+
+## Execution order
+
+1. Try as Lua statement
+2. Try as Lua expression (`return ...`)
+3. Try as shell command (interactive execution)
+
+## Considerations
+
+- Ambiguity: `ls` is not valid Lua, so it would fall through to shell — this is the desired behaviour
+- But `print` is valid Lua (it's a value) — so `print` alone wouldn't trigger shell
+- What about `git status`? Not valid Lua, would correctly fall through to shell
+- Error messages: if all three fail, which error do we show?
+- Performance: three parse attempts per input line
diff --git a/issues/23-cleanup-refactor.md b/issues/23-cleanup-refactor.md
new file mode 100644
index 00000000..7199cb0a
--- /dev/null
+++ b/issues/23-cleanup-refactor.md
@@ -0,0 +1,20 @@
+# 23 — General cleanup and refactor
+
+**Status:** open
+
+Housekeeping pass over the codebase.
+
+## Function names
+
+Function names should be reviewed and improved for consistency and clarity.
+
+## Global namespace (`_G`)
+
+Review what's exposed in `_G`. Do we need to expose everything? Candidates for cleanup:
+
+- `__command` — internal, could be hidden
+- `__interactive` — internal, could be hidden
+- `__getenv` / `__setenv` — internal, could be hidden
+- `__builtins` — should this be user-facing or internal?
+
+Consider whether internal functions should live in a single `__lush` table or use the registry instead of polluting globals.