Skip to content

Point users at shell completion setup on first start - #484

Open
joe4dev wants to merge 3 commits into
mainfrom
devx-821-completion-tip
Open

Point users at shell completion setup on first start#484
joe4dev wants to merge 3 commits into
mainfrom
devx-821-completion-tip

Conversation

@joe4dev

@joe4dev joe4dev commented Sep 4, 2026

Copy link
Copy Markdown
Member

Motivation

Only Homebrew installs get shell completion set up automatically (homebrew_casks.completions). npm and GitHub-release users have to find the docs themselves, so a shipped time-saving feature goes mostly unused.

Solution

Emit one line after the first successful interactive start, pointing at lstk completion [bash|zsh|fish|powershell] and the docs section:

> Tip: Enable tab completion for your shell: lstk completion [bash|zsh|fish|powershell] See https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/#shell-completions

Two deliberate deviations from the ticket: the trigger is the first run, not install (no install path offers a usable hook — npm's package.json is generated, a postinstall that edits a shell rc is hostile and is skipped under --ignore-scripts, and binary installs have no hook), and it is a pointer, not a prompt — lstk never writes to the user's shell config. An automated lstk completion --write was designed and dropped in favour of this because the big complexity (cross-platform, cross-shell, cross-install-method) is not worth maintaining for a small gain.

Needs no new persisted state: firstRun means "config.toml was absent", and that same path creates the config, so the tip cannot repeat. Interactive-only, so CI and --json output are unchanged. Prefix and severity match tipsForType, whose tip renders directly above it.

The wording follows the Verb ...: <command> shape the neighbouring tips already use.

The main_test.go/awsconfig_test.go part of the diff is test plumbing: these tests isolate HOME under t.TempDir() and start a real emulator, whose container writes root-owned files into the bind-mounted volume that Go's TempDir cleanup cannot delete on Linux. awsconfig_test.go already solved this; scheduleVolumeCleanup extracts it so there is one copy rather than two.

Manual testing

make build
export LOCALSTACK_AUTH_TOKEN=<token>
H=$(mktemp -d)

HOME=$H bin/lstk start   # accept AWS at the emulator picker
#   -> last line is the "> Tip: Enable tab completion ..." line above

HOME=$H bin/lstk start   # tip must NOT reappear (config now exists)
HOME=$H bin/lstk stop

HOME=$(mktemp -d) bin/lstk start --json   # envelope must contain no tip

Screenshot from manual testing:

  • Tip appears on first launch
  • Tip does not appear on subsequent commands
Screenshot 2026-09-04 at 16 19 37
Docs

No documentation change needed — the tip points at the existing "Shell completions" section and adds no command, flag, or env var. Worth knowing that the CLI now links to that section directly, so the #shell-completions anchor should stay stable.

Review

Human review advised — new user-facing output on the shared start path.

Todo

  • Manual testing (see above)

Closes DEVX-821

@joe4dev joe4dev added semver: patch docs: skip Pull request does not require documentation changes labels Sep 4, 2026
@joe4dev
joe4dev marked this pull request as ready for review September 4, 2026 14:25
@joe4dev
joe4dev requested review from a team and peter-smith-phd as code owners September 4, 2026 14:25
@joe4dev
joe4dev force-pushed the devx-821-completion-tip branch from 3df75be to 6d5ed2a Compare September 7, 2026 09:28
joe4dev and others added 3 commits September 7, 2026 10:07
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@joe4dev
joe4dev force-pushed the devx-821-completion-tip branch from 6d5ed2a to 3039a2b Compare September 7, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs: skip Pull request does not require documentation changes semver: patch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant