Dpx 693 pr 2 teach lstk update to handle the bundled extensions

[carillan81]

Motivation

Once releases ship the bundled extensions (bundled-extensions and lstk-extensions.toml next to lstk), lstk update on the binary channel has to replace all three files together, not just the binary. Today it replaces one file, lstk, and ignores everything else in the archive.

That has a second-order problem. The first bundling release is installed by the updater users already have, which only replaces lstk. They land on a current binary with no extensions, and because they are already on the newest version, lstk update says "already up to date" until the next release ships. Nobody can fix that retroactively, so the new updater has to detect and repair it.

Solution

Set-wise replacement (stage-then-commit). Every member of the archive is copied into the install directory under a .lstk-new name; only when all copies succeed is each renamed over its final name, lstk last. A file visible under its real name is never half-written, a failure before the last rename leaves a working lstk to re-run with, and the updater never deletes an lstk-* file it cannot prove it owns (additive-only). An archive containing only lstk behaves exactly as before, so pre-bundling releases and rollbacks are unaffected.

Repair when current but incomplete. The release stamps the expected set into the binary (version.bundledSet, via ldflags). When versions match but a stamped member is missing or unusable, lstk update reinstalls the same release, then re-checks; if the archive still did not deliver the members it fails loudly ("did not restore the bundled extensions") instead of looping. Empty stamp keeps today's pure version comparison. Homebrew and npm never repair; the package manager owns the whole set there. The passive update notice also nudges an incomplete install toward lstk update.

The same-version repair from the first revision was dropped in review. The transition release (old updater, new archive) leaves the bundle uninstalled until the next lstk update. Instead of repairing, lstk tells the user: a release build that finds no bundle beside itself adds a reinstall hint to the unknown-command error and warns on an up-to-date lstk update (also in the --json warnings array). One goreleaser ldflag, one detector, two call sites.

Hardening. Windows moves every existing member aside before renaming (a running extension no longer breaks the commit); a squatting symlink or directory at a staging path is refused rather than written through; the install directory is listed literally instead of globbed (a [ in the path used to fail every update); setuid/setgid bits survive the update; a concurrent update cannot truncate another's staging file.

Structured output. UpdateCheckedEvent gains RepairBundled; the --json check shape gains "repairBundled": true for a same-version repair (absent otherwise, and scrubbed from the applied shape).

Dependencies and follow-ups

• dpx-692 (PR 1) must merge first or together: it carries the resolver that dispatches bundled commands from the toml. Without it a repaired install has the files but nothing resolves them.
• The bundledSet ldflags stamp (tasks.md 5.2) is not yet in .goreleaser.yaml; until it lands on the packaging side the repair path stays dormant and this PR changes nothing user-visible.
• Once both branches are in, alias bundledBinaryBaseName from extension.BundledBinaryName (TODO left on the constant).

Testing

• Unit: internal/update covers every behaviour above, including the Windows path from any host via a goos parameter. All new behaviour was written test-first.
• Integration: transition repair, complete-set no-op, pre-bundling release unaffected, broken-archive fail-loud, leftover cleanup, plus the existing mock-GitHub happy/failure paths.
• Manual testbed against packages built by the dpx-692 pipeline (goreleaser, npm publisher): the full transition (published 0.23.0 to bundling release, repair, no-op, bundled-to-bundled upgrade, rollback, forward) passes on the binary channel and npm. Caveat: the currently published bundle predates the bundled-extensions list contract, so the release gate was run as a warning for that exercise; Homebrew was not executed.

Docs

No documentation work needed outside this PR. docs/structured-output.md is updated for the new repairBundled key, and the update guarantees are documented in the internal/update package comment. User-facing bundling docs (docs/extensions-bundling.md) live on dpx-692.

The reinstall hint is new user-facing output; the spec has a scenario for it. Release notes for the first bundling release should carry one line: if a bundled command reports "unknown command" after updating, reinstall lstk once.

Review

Human review advisable. This is the update path, the one thing a broken release cannot ship a fix for, and it adds new user-visible behaviour (the repair). Not a self-merge candidate.

Closes DPX-693

[peter-smith-phd]

Thanks for implementing this, but I'm not sure we need a 2000-line solution to handle the "binary" case where we're moving from just lstk to lstk/bundled-extensions/lstk-extensions.toml. I appreciate the need to carefully replace the three files, rather than just one, but this solution feels over complicated. I was expecting closer to 100 lines of code.

In particular, do we really need the "repair" functionality? If it breaks for some reason, we already have error messages that inform the user of the problem. They should instead just uninstall/reinstall lstk and the problem will go away. My concern is that the code has become so complicated that we'll have trouble maintaining it in future.

What can we do to make this significantly less complicated, and focus on just replacing three files instead of one?

[carillan81]

Thanks for implementing this, but I'm not sure we need a 2000-line solution to handle the "binary" case where we're moving from just lstk to lstk/bundled-extensions/lstk-extensions.toml. I appreciate the need to carefully replace the three files, rather than just one, but this solution feels over complicated. I was expecting closer to 100 lines of code.

In particular, do we really need the "repair" functionality? If it breaks for some reason, we already have error messages that inform the user of the problem. They should instead just uninstall/reinstall lstk and the problem will go away. My concern is that the code has become so complicated that we'll have trouble maintaining it in future.

What can we do to make this significantly less complicated, and focus on just replacing three files instead of one?

After some discussion with humans and AI I agree that the repair functionality is an overkill. We are facing a temporal issue while the users update and the repair adds some code that will be stale in a month.

I think we must address user UX so I just implemented a better error message that gives a hint for reinstall (and command) in case the command is not found. It adds some code but barely adds a few tenths of lines.

Bucket	Code	Comments	Blank	Docs / config	Added	Removed
Go production	247	82	24		353	29
Go tests	679	46	62		787	51
Docs (openspec spec + tasks, CLAUDE.md)				16	16	16
Build config (.goreleaser.yaml)				1	1	1
Total	926	128	86	17	1157	97

This looks a much better solution to me.

$ lstk deploy
Error: unknown command "deploy" for lstk
  This lstk release ships bundled extensions, but none are installed in <install dir>.
  ==> See help: lstk -h
  ==> Reinstall lstk: download the latest release from https://github.com/localstack/lstk/releases/latest
(exit 1)

$ lstk update
Checking for updates...
> Note: Already up to date (9.9.9-SNAPSHOT-dfd62a7)
> Warning: This lstk release ships bundled extensions, but none are installed in <install dir>. Reinstall lstk: download ...

Does this works for you?