Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,45 @@ on:
branches: [main, develop]

jobs:
validate-completion:
name: Isolated completion (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Install test dependencies (Linux)
if: runner.os == 'Linux'
run: sudo apt-get update && sudo apt-get install -y zsh shellcheck

- name: Install lint dependency (macOS)
if: runner.os == 'macOS'
run: command -v shellcheck || brew install shellcheck

- name: Verify native shells and PTY test capability
run: |
/bin/bash --version
/bin/zsh --version
python3 -c 'import pty'

- name: Syntax and lint (including system Bash 3.2 on macOS)
run: |
for script in config/dotfiles/*completion.sh tests/test_completion*.sh; do
/bin/bash --noprofile --norc -n "$script"
shellcheck "$script"
done
/bin/zsh -df -n config/dotfiles/completion.sh

- name: Isolated completion install, upgrade, and removal
run: /bin/bash tests/test_completion_install.sh

- name: Native shell state and PTY completion tests (no adapters)
run: /bin/bash tests/test_completion_runtime.sh --bash /bin/bash --zsh /bin/zsh

validate-linux:
name: Validate Linux Setup
runs-on: ubuntu-latest
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Explicit completion-only Bash/Zsh opt-in with native Tab/Shift+Tab cycling,
separate validated rc hooks, backups, mutation-free preview, disable switch,
and feature-only removal. Older Readline (including macOS Bash 3.2) gets
forward Tab only and preserves existing Shift+Tab. Ordinary setup is unchanged.
Includes isolated lifecycle and actual shell/PTY tests on Linux/macOS. (#516)
- Isolated shutdown-helper regression coverage under Bash/Zsh on Linux/macOS,
including macOS system Bash 3.2, with non-forwarding command stubs. (#514)

Expand Down
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,26 @@ Full definitions:
- **Linux/macOS:** `config/dotfiles/.aliases` (bash/zsh only -- see header for the non-POSIX features in use)
- **Windows:** `scripts/windows/setup.ps1` (the `Write-PowerShellProfile` function)

## Opt-in Native Completion Cycling

Bash/Zsh users can opt in without rerunning setup or reinstalling dotfiles:

```bash
bash config/dotfiles/install-completion.sh --dry-run
bash config/dotfiles/install-completion.sh
```

Open a fresh shell: **Tab** selects the next match, **Shift+Tab** the previous
match. **macOS system Bash 3.2 supports forward Tab only; its existing Shift+Tab
binding is left untouched** because that Readline lacks a native backward widget.
Ordinary installation never opts you in. No plugins or system inputrc changes.

Use `DEV_SETUP_COMPLETION=0` before the hook to disable in fresh shells, or
`bash config/dotfiles/install-completion.sh --uninstall` to remove only this
feature. See the [completion guide](config/dotfiles/README.md#opt-in-tab-completion-cycling-bash--zsh)
for backups, `ZDOTDIR`, framework/login-shell ordering, terminal support, and
optional completion providers.

## Shell Functions

The following helper functions are available after setup:
Expand Down
141 changes: 141 additions & 0 deletions config/dotfiles/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ These templates give every Dev Container and Codespace a sensible, consistent en
| `.npmrc.template` | `$HOME/.npmrc` | Copy | Editable per-machine |
| `.vimrc` | `$HOME/.vimrc` | Symlink | Vim configuration |
| `install.sh` | -- | Script | Idempotent installer |
| `install-completion.sh` | -- | Script | Separate, explicit completion-only opt-in |
| `completion.sh` | `$HOME/.dev-setup-completion.sh` | Symlink | Interactive Bash/Zsh native completion bindings |

---

Expand All @@ -28,6 +30,145 @@ bash config/dotfiles/install.sh --dry-run

---

## Opt-in Tab completion cycling (Bash / Zsh)

**This is not enabled by `setup.sh` or `install.sh`.** Both existing and fresh
installations use the same separate command, without reinstalling other dotfiles:

```bash
# From the repository root, after your normal shell/framework setup:
bash config/dotfiles/install-completion.sh --dry-run
bash config/dotfiles/install-completion.sh
# Open a fresh interactive shell afterward.
```

| Shell | Tab | Shift+Tab |
|-------|-----|-----------|
| Bash with native `menu-complete-backward` | Next match | Previous match |
| **macOS system Bash 3.2 / older Readline** | **Next match** | **Existing binding unchanged; no backward cycling added** |
| Zsh | Next match | Previous match |

The helper detects native Readline widget availability, not a Bash version
number. It deliberately does **not** add a macro fallback or reserve extra keys.
Opting in explicitly overrides existing Tab and (where supported) Shift+Tab
bindings in Bash's `emacs-standard` / `vi-insert` and Zsh's `emacs` / `viins`
keymaps. Editing mode, vi command mode, and unrelated bindings are preserved.
Custom keymaps outside these maps remain user-managed. The helper does nothing
in noninteractive shells. It is not a PowerShell feature.

### Ordering, terminals, and providers

- The installer appends a **separate** `dev-setup completion v1` hook at the end
of each rc. Keep the entire hook, including its preceding separator newline,
intact. Existing general DevSetup managed blocks are never edited.
- Put framework initialization, `compinit`, completion providers, and general
key bindings **before** this hook. Later user configuration wins; frameworks
loaded later may override it. If moving the hook, move its separator too.
- Zsh's native completion works without `compinit`. If your framework already
initialized completion, these widget names reuse its providers/styles. This
helper never runs `compinit` (which would also bind unrelated keys), installs
a framework, or bypasses `compinit`'s security audit. Follow your framework's
normal initialization/security instructions for richer completion.
- Commands, files, and directories work natively. Git branches, tool flags,
package names, etc. depend on separately configured completion providers
(such as `bash-completion` or Zsh's completion system). Their filtering and
ordering still apply. This is not fuzzy search or an autosuggestion plugin.
- Shift+Tab must reach the shell as **ESC `[Z`**. Some terminals, IDEs, and
multiplexers intercept it or send another sequence; configure them yourself.
Tab/Ctrl-I are the same terminal key. Existing Readline variables and Zsh
completion styles may affect listing, ordering, or wraparound behavior.
- Bash login shells, especially macOS Terminal, may not read `.bashrc` unless
your existing login profile sources it. This command **never edits
`.bash_profile`**; choose that startup arrangement yourself.

### `ZDOTDIR` and ownership safety

The command targets **both** `$HOME/.bashrc` and `${ZDOTDIR:-$HOME}/.zshrc`;
Zsh need not be installed at opt-in time. If you use `ZDOTDIR`, export its
**effective absolute path** when installing, previewing, or uninstalling:

```bash
ZDOTDIR="$HOME/.config/zsh" bash config/dotfiles/install-completion.sh
```

The directory must already exist. The command never executes `.zshenv` to
infer configuration. If `$HOME/.zshenv` exists, an explicit `ZDOTDIR` is required
(use `ZDOTDIR="$HOME"` if it does not relocate rc files). Ensure it matches the
value used by your shell; changing `ZDOTDIR` later requires removing the old
hook using the old value first. Empty/relative/missing `ZDOTDIR` is rejected.

Trailing/repeated slashes and `.` or `..` components are supported for real
directories. **Every component of the absolute `ZDOTDIR` path is checked for
symlinks**, including ancestors: `link/`, `link/.`, `link/child`, and
`link/../other` are all rejected if `link` is a symlink. The supplied path is
not resolved or rewritten to silently choose a target. Use a symlink-free
absolute path (for example, `/private/tmp/...` rather than `/tmp/...` on macOS
when `/tmp` is a symlink). This is preflight validation, not a filesystem-race
or sandbox guarantee.

Both rc files and the helper destination are validated before any mutation.
Symlinked rc files, symlinks in `ZDOTDIR` paths, conflicting helper links,
user-owned files at the helper destination, and malformed/modified/duplicate
hooks are rejected rather than overwritten. Binary/NUL rc content and paths
containing newlines are unsupported. Spaces and shell metacharacters in paths
are supported. If validation fails, review the indicated configuration manually;
do not delete user configuration just to make the check pass.

Existing rc files are backed up to unique
`<rc>.dev-setup-completion.bak.XXXXXX` files before edits. Backups retain file
permissions and are not automatically pruned or used to overwrite later edits.
Bytes outside the owned hook are retained. When the hook is at EOF, removal
restores the original bytes exactly, including a missing final newline. When
text follows the hook, removal retains one separator newline if otherwise a
nonempty, unterminated preceding line would join that following text. No extra
separator is retained if the preceding text is empty, already ends in a newline,
or the following text starts with a newline. This keeps later assignments
separate without restoring a whole backup or changing any user-added bytes.
Re-running the command does not duplicate hooks or create new backups.
`--dry-run` performs validation but creates no files, directories, links, or backups.

The helper link points into **this checkout**. Keep it in place; updating
`completion.sh` updates already opted-in shells on their next startup, without
rewriting hooks. To move/remove a checkout, uninstall this feature using the
original checkout first. A link into a different checkout is a conflict, not an
implicit migration.

### Disable, remove, or recover

For a temporary disable, export this **before the hook** (or in the parent
process environment), then open a **fresh** shell:

```bash
export DEV_SETUP_COMPLETION=0
```

This leaves that fresh shell's prior bindings intact. Setting it after the
helper already ran does not undo current-shell bindings. Unset it to re-enable
in future shells. Do not place the switch inside the owned hook.

To remove only this feature, without reinstalling or restoring other dotfiles:

```bash
bash config/dotfiles/install-completion.sh --uninstall --dry-run
bash config/dotfiles/install-completion.sh --uninstall
```

Removal validates both targets, backs up changed rc files, removes only the
owned hook (with the separator rule above) and expected helper link, and preserves
later user additions. Newly created rc files are left empty rather than deleted.
Repeated removal is safe.
Open a fresh shell to get normal bindings back. Remove this feature separately
**before** the general DevSetup uninstaller or deleting the checkout; the general
uninstaller does not manage this opt-in hook.

Avoid concurrent edits/installers. Replacements are prepared and backups made
before activating hooks, with a snapshot recheck, but this is **not a multi-file
transaction or a filesystem lock**. On an I/O failure, inspect the diagnostic,
current hooks, helper link, and named backups; fix the underlying problem and
rerun. Never blindly restore a backup over newer user additions.

---

## Customisation

### `.gitconfig`
Expand Down
33 changes: 33 additions & 0 deletions config/dotfiles/completion.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# DevSetup opt-in completion. Sourced by the separate completion rc hook.
# Bash 3.2+ / Zsh. No effect in noninteractive shells or when disabled.
# shellcheck shell=bash
case $- in *i*) ;; *) return 0 ;; esac
[ "${DEV_SETUP_COMPLETION:-1}" != 0 ] || return 0

_dev_setup_completion() {
local map widgets
if [ -n "${BASH_VERSION:-}" ]; then
widgets=$'\n'"$(bind -l)"$'\n'
case "$widgets" in *$'\nmenu-complete\n'*) ;; *) return 1 ;; esac
for map in emacs-standard vi-insert; do
bind -m "$map" '"\C-i": menu-complete'
# Readline 5.2 (macOS Bash 3.2) has no backward widget. Leave the
# existing Shift+Tab binding alone; do not reserve extra keys.
case "$widgets" in
*$'\nmenu-complete-backward\n'*)
bind -m "$map" '"\e[Z": menu-complete-backward' ;;
esac
done
elif [ -n "${ZSH_VERSION:-}" ]; then
# These are native widgets even without compinit. If a framework has
# initialized completion, the same widget names use its providers.
# Do not run compinit here: it also changes unrelated key bindings.
# Users/frameworks retain responsibility for its normal security audit.
for map in emacs viins; do
bindkey -M "$map" '^I' menu-complete
bindkey -M "$map" '^[[Z' reverse-menu-complete
done
fi
}
_dev_setup_completion
unset -f _dev_setup_completion
Loading
Loading