Skip to content
Skills Library
Programming · Learning & explanation

koopa-completion

/koopa-completion

koopa shell completion architecture, generator, flag extraction, bash/zsh/PowerShell/elvish emitters, lazy-load mechanism, compdump freshness, and known bug patterns. Use when debugging missing completions, editing generate_completion.py, or adding flags to a CLI handler that need to appear in TAB completion.

Repository
koopa ↗
Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

koopa shell completion architecture, generator, flag extraction, bash/zsh/PowerShell/elvish emitters, lazy-load mechanism, compdump freshness, and known bug patterns. Use when debugging missing completions, editing generate_completion.py, or adding flags to a CLI handler that need to appear in TAB completion.

Original author description

koopa shell completion architecture, generator, flag extraction, bash/zsh/PowerShell/elvish emitters, lazy-load mechanism, compdump freshness, and known bug patterns. Use when debugging missing completions, editing generate_completion.py, or adding flags to a CLI handler that need to appear in TAB completion.

How it works

  1. Source of truth
  2. How flags reach completions
  3. Bash lazy-load mechanism
  4. zsh compdump freshness
  5. Known bug pattern: flag-gate too strict (fixed 2026-06-19)
  6. Known bug pattern: completion offering args the parser rejects (fixed 2026-08-11)
  7. Adding a koopa run command
  8. Diagnosing "completion not working"
  9. Dead symlink cleanup (done 2026-06-19)
Original SKILL.md headings · 188 lines, 1,115 words
SKILL.md preview
---
name: koopa-completion
description: >-
  koopa shell completion architecture, generator, flag extraction, bash/zsh/PowerShell/elvish
  emitters, lazy-load mechanism, compdump freshness, and known bug patterns. Use when
  debugging missing completions, editing generate_completion.py, or adding flags to a
  CLI handler that need to appear in TAB completion.
---

# koopa Completion Architecture

## Source of truth

All completion files are **auto-generated**; never hand-edit them:

| Generated file | Shell |
|---|---|
| `share/bash-completion/completions/koopa` | bash (and zsh via bashcompinit fallback) |
| `share/zsh/site-functions/_koopa` | zsh native `#compdef` |
| `share/fish/vendor_completions.d/koopa.fish` | fish |
| `share/powershell/completions/koopa.ps1` | PowerShell |
| `share/elvish/completions/koopa.elv` | elvish |
| `share/nushell/completions/koopa.nu` | nushell |

Generator: `lang/python/src/koopa/generate_completion.py`  
Invoke via: `koopa develop generate-completion`  
After a successful run it prints `"Reload your shell to apply changes."`.

The CLI handler (`cli_develop.py:543`) already emits both the success and reload
messages: no need to add them.

## How flags reach completions

`_extract_handler_flags()` (generator ~line 224) AST-walks each `_handle_*`
function and collects literal `"--..."` strings from `parser.add_argument(...)` and
`--flag` comparisons. `_build_flag_map()` then assembles a
`"develop/check-app-versions" → ["--help", "--json", ...]` map.

**Adding a new flag to a command:** add `parser.add_argument("--my-flag", ...)` in
the handler, then run `koopa develop generate-completion`. The flag is picked up
automatically: no manual edits to the completion files.

Flags are only picked up if the literal `"--flag-name"` string appears directly in
the handler function body (not constructed dynamically).

## Bash lazy-load mechanism

Activation sets `BASH_COMPLETION_USER_DIR=${KOOPA_PREFIX}/share/bash-completion`
(in `lang/bash/functions/activate/activate-bash-completion.sh`).

The bash-completion v2 framework (`opt/bash-completion/`) lazy-loads the `koopa`
completion file on first TAB. Until that first TAB:
- `complete -p koopa` returns nothing
- `_koopa_complete` is not defined in memory

This is normal: it is **not** a sign that completion is broken. Running
`complete -p koopa` before ever TABbing on `koopa` will always show "NOT
registered".

The framework requires `PS1` to be set (interactive shell check). It is
version-guarded (`BASH_COMPLETION_VERSINFO`); activation unsets this sentinel so
koopa's versioned framework always wins over any system-installed v2.

## zsh compdump freshness

`_koopa_activate_zsh_compinit` (`lang/zsh/functions/activate/activate-zsh-compinit.sh`):
- Dump path: `${ZDOTDIR:-$HOME}/.zcompdump` → typically `~/.config/zsh/.zcompdump`
- Fast path (`compinit -C`) only fires when dump is < 24 h old AND no file in
  `${KOOPA_PREFIX}/share/zsh/site-functions` is newer than the dump.
- After `koopa develop generate-completion`, the `_koopa` mtime changes, so the
  next new shell forces a full `compinit` rebuild automatically.

A live session never picks up completion file changes: `exec zsh` or open a new
terminal.

## Known bug pattern: flag-gate too strict (fixed 2026-06-19)

**Symptom:** `koopa develop check-app-versions `+TAB (bare or single `-`) showed
nothing; had to type `--` first.

**Root cause:** the bash flag-collection block in the generator was gated on
`[[ "${COMP_WORDS[COMP_CWORD]}" == --* ]]`: only fired when the current word
already started with two dashes.

**Fix applied to `generate_completion.py`:**

```python
# Bash emitter (~line 1649): was `--*`, now `-*` || empty args
lines.append(f'{_I}if [[ "${{COMP_WORDS[COMP_CWORD]}}" == -* ]] || [[ -z "${{args[*]}}" ]]')
```

The `|| [[ -z "${args[*]}" ]]` clause fires the flag lookup when no subcommand
candidates were found (leaf command), so bare TAB on a fully-resolved command
offers its flags. Non-leaf commands (`develop`, `configure`, etc.) populate `args`
with subcommand names before this block and are unaffected.

Same single-dash relaxation applied to PowerShell (`-like '-*'`) and elvish
(`str:has-prefix $last '-'`) emitters.

## Known bug pattern: completion offering args the parser rejects (fixed 2026-08-11)

**Symptom:** `koopa update system` TAB-completed `homebrew python r
tex-packages`, but running `koopa update system homebrew` was an argparse
error ("unrecognized arguments"). The `update` subparser's `mode` positional
had no `apps` positional to receive them (see the `koopa-update` skill for
the CLI-side fix).

**Root cause, part 1 (bash only):** the bash emitter's depth-3 block for
`update system` (`generate_completion.py`, `_emit_platform_block(
installer_modes["update-system"], ...)`) was already correctly deriving app
names from the registry; it was the parser that lagged behind. No other
shell emitted this depth-3 block at all, so bash alone offered-then-rejected.

**Root cause, part 2 (bash + PowerShell + elvish): a phantom `user` mode.**
Three emitters offered `koopa`, `system`, **and** `user` after `update` even
though `koopa update user` has never existed:

```python
# bash (was):
update_items = ["koopa", "system", "user"]
# PowerShell (was):
f"{_ps_array(['koopa', 'system', 'user'])}"
# elvish (was):
lines.append("            put koopa system user")
```

fish and zsh were already correct (`koopa`, `system` only) and nushell didn't
enumerate modes at all, so the drift was bash/PowerShell/elvish-only. The `user`
token likely leaked in by analogy with `koopa configure system|user`, which
is a real two-mode command; `update` only ever had `koopa`/`system`.

**Fix:** dropped `'user'` from all three emitters; added the equivalent
depth-3 `update system <app>` completion to fish (the one shell that had the
top-level `koopa`/`system` mode completion but no per-app follow-up), keyed
off the same `installer_modes["update-system"]` list already computed by
`_get_installer_mode_apps()`. Threaded that list into
`_generate_fish_completion()` as a new parameter rather than re-deriving it,
since the caller (`generate_completion()`) already has it in scope.

**Trap when generating a fish app-name list from a multi-platform registry
entry:** `PYTHON_INSTALLER_MODES` lists `r` twice (once per `("r", "macos",
"update-system")` and `("r", "debian", "update-system")` platform variant).
A naive `for app, _plat in entries: lines.append(...)` emits a duplicate
`complete` line for `r`. Dedupe by name first: `sorted({name for name, _plat
in entries})`. zsh/PowerShell/elvish's depth-3 blocks don't have this trap
because they route through `_emit_platform_block()`, which already groups
entries by platform tag before emitting.

**Still not covered:** depth-3 `update system <app>` completion for zsh,
PowerShell, elvish, and nushell. Those emitters would need structural changes
(zsh's `_koopa_update` is a flat `_arguments` spec; PowerShell/elvish hardcode
their depth-2/3 blocks to `$tokens[0] -eq 'app'`) to add it without
over-offering app names after `koopa update koopa`. They currently offer
nothing after `system`, which is wrong-but-harmless rather than
offer-then-reject.

## Adding a `koopa run` command

`koopa run` completions are auto-discovered from `cli_bin.py:_HANDLERS` via
`_load_run_commands()` in `generate_completion.py`. No manual completion edits
are needed, just:

1. Add `_handle_my_cmd(args: list[str]) -> None` in `cli_bin.py`.
2. Register `"my-cmd": _handle_my_cmd,` in `_HANDLERS` (keep alphabetical).
3. Run `koopa develop generate-completion`.

`koopa system` subcommands are similarly auto-discovered from the `handle_system`
string-comparison chain, but require explicitly adding a `if subcmd == "my-cmd":` branch.
`koopa admin` subcommands are discovered from `_ADMIN_HANDLERS`.

Top-level commands (`koopa install`, `koopa configure`, …) require manual edits to
`_build_parser` and to `_TOP_CMDS` in 8 places in `generate_completion.py`; avoid
adding top-level commands unless truly necessary.

## Diagnosing "completion not working"

```bash
# In the live interactive shell:
complete -p koopa 2>/dev/null || echo "NOT registered (normal before first TAB)"
declare -F _koopa_complete >/dev/null && echo "DEFINED" || echo "NOT defined (normal before first TAB)"
echo "framework: ${BASH_COMPLETION_VERSINFO[*]:-UNSET, framework not loaded}"
echo "user dir:  ${BASH_COMPLETION_USER_DIR:-UNSET, wrong activation}"
```

If `BASH_COMPLETION_VERSINFO` is unset after opening a new shell, the framework
didn't load: check that activation ran (`echo $KOOPA_PREFIX`) and that the shell
is interactive (`PS1` set).

## Dead symlink cleanup (done 2026-06-19)

`~/.local/share/bash-completion/completions/koopa` was a dangling symlink to
the deleted file `etc/completion/koopa.sh`. It was harmless (bash-completion's
`_comp_load` uses `[[ -e ]]` which is false for dangling links, so it silently
skips it), but it was removed as cruft. If it reappears, just `rm` it: it is
not managed by chezmoi or koopa.

Versions

The database has no other skills named koopa-completion.

Database snapshot: 13.11.2026 · package version ccf13277c825 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95koopa-elvish
    Elvish shell programming pitfalls, namespace semantics, and koopa activation architecture. Use when writing or debugging .elv files, editing lang/elvish/include/header.elv or any activate-*.elv, or porting shell logic from bash/zsh to elvish.
  • 98koopa-powershell
    PowerShell (pwsh 7+) activation architecture, starship integration, and color-mode sync in koopa. Use when writing or debugging lang/powershell/ files, editing activate-*.ps1 functions, adding prompt-tool support (starship, zoxide), integrating OS appearance detection, or…
  • 95glab-completion
    Generate shell completion scripts for bash, zsh, fish, or PowerShell. Use when setting up glab autocompletion for your shell. Triggers on completion, autocomplete, shell completion, tab completion.
  • 90shell-completions-and-config
    Generate shell completions (bash/zsh/fish/PowerShell) from the parser and design config-file discovery + env-var conventions (XDG, TOOL_* prefixes). Use when adding tab completion or a config/env layer to a CLI.
  • 95glab-completion
    Generate shell completion scripts for bash, zsh, fish, or PowerShell. Use when setting up glab autocompletion for your shell. Triggers on completion, autocomplete, shell completion, tab completion.
  • 100cli-developer
    Use when building CLI tools, implementing argument parsing, or adding interactive prompts. Invoke for parsing flags and subcommands, displaying progress bars and spinners, generating bash/zsh/fish completion scripts, CLI design, shell completions, and cross-platform terminal…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.