commit ef0d223896bb3f1661875b94a95f27bcbd6c5f00 equwal <13551856+equwal@users.noreply.github.com> 2026-10-04 19:37:44 -0700 patches rule: one runnable block for everything; Terminal may be PowerShell 5.1
rules/patches.md | 9 ++++++++- rules/windows-powershell.md | 2 +- 2 files changed, 9 insertions(+), 2 deletions(-)
diff --git a/rules/patches.md b/rules/patches.md index 54017d8..15e519e 100644 --- a/rules/patches.md +++ b/rules/patches.md @@ -4,9 +4,16 @@ Two cases. Never give loose code lines or whole files. **Change you already made (applied).** Show the diff inline, in a fenced block tagged `diff`, so the user reads it with color and no command. Do not make him run a command (`git show`, `diff -u`, `cat`) just to see a change. -**Change the user must apply** (you could not apply it: denied, blocked, needs his hands or another host). Give one fenced block tagged `bash` (the desktop app adds a Run button only to `bash` blocks) that applies it: `cd DIR && patch -p1 <<'EOF'` ... `EOF`, or `ssh HOST 'cd DIR && patch -p1' <<'EOF'` ... `EOF` for another host. Use an absolute `DIR` and the correct `-p` level. The patch text inside is the diff, so he can read it before he runs it. +**Change the user must apply** (you could not apply it: denied, blocked, needs his hands or another host). Give one fenced block tagged `bash` (the desktop app adds a Run button only to `bash` blocks) that applies it. The Run button types into his Terminal panel, which runs PowerShell, so a bash heredoc fails there. For another host, pipe a here-string script to ssh (see "One message, one click"); inside it, `cd DIR && patch -p1 <<'PATCH'` ... `PATCH`. Use an absolute `DIR` and the correct `-p` level. The patch text inside is the diff, so he can read it before he runs it. - Make diffs with `diff -u` or `git diff`, with context lines and `@@` headers with line numbers. Check an unapplied patch with `patch --dry-run` before you show it. - Long diffs: show the relevant hunks inline and say how many lines/files you left out. - Give a whole file only when the file is new or the user asks for the whole file. - When you edit files yourself, use your edit tools as usual; this rule is about what you show the user. + +**One message, one click.** The user prefers one large runnable block over several small commands. Put every step he must run (all patches, installs, checks, the commit) in a single `bash`-tagged block, so the desktop app's Run button does it all in one click. Never split it into blocks he has to copy or run one by one. + +- His Terminal panel can be Windows PowerShell 5.1. It strips `"` inside native-program arguments, prefixes piped text with a BOM, and ends lines with CRLF. A copied block can also lose its tabs. +- For a remote host, send the script on stdin: a `@'` ... `'@` here-string piped to `ssh HOST 'awk ''{gsub(/[^ -~\t]/,x)}1'' | sh'`. Keep `"` out of the ssh argument. Start the script with `set -e`. +- Never rely on a literal tab in the block. Make one with `t=$(printf '\t')`, or append Makefile recipes with `printf '\t...'`. Prefer `sed` line edits guarded by a `sha256sum -c` of the file over patches whose context holds tabs or trailing spaces. +- Before you give the block, run it with a dry-run switch in both `powershell.exe -File` and `pwsh -File`. diff --git a/rules/windows-powershell.md b/rules/windows-powershell.md index 8e39bc4..54a30e1 100644 --- a/rules/windows-powershell.md +++ b/rules/windows-powershell.md @@ -2,7 +2,7 @@ This section applies on the Windows PC only, not on the Linux desktop `g`. -The PC has PowerShell 7.6 (`pwsh.exe`). The Claude Code agent shell and the desktop Terminal panel both run it. Checked 2026-10-03. `powershell.exe` is the old Windows PowerShell 5.1. Most broken commands on this PC came from mixing the two. +The PC has PowerShell 7.6 (`pwsh.exe`). The Claude Code agent shell runs it. Checked 2026-10-03. The desktop Terminal panel can run Windows PowerShell 5.1 (seen 2026-10-04), so a command for the user must work in both. `powershell.exe` is the old Windows PowerShell 5.1. Most broken commands on this PC came from mixing the two. - Check your own shell once per session: `$PSVersionTable.PSVersion`. On 7.x, `&&`, `||`, `?:`, `??` and `?.` work. On 5.x they fail with "The token '&&' is not a valid statement separator". Then use `A; if ($?) { B }`. - Never wrap a command in `powershell -Command "..."`. That starts 5.1, and your shell expands each `$` inside the double quotes first. For a child shell, write a `.ps1` file and run `pwsh -NoProfile -File <file>.ps1`.