Add lstk extension mechanism

[peter-smith-phd]

What this is

lstk gains Git-style extensions: when you run lstk <name> and <name> isn't a built-in command, lstk finds and runs an executable called lstk-<name>, forwarding your arguments and the child's stdin/stdout/stderr and exit code. Same model as git-<name>. Extensions can be written in any language, open or closed source, with no manifest and no registration step.

This PR contains the implementation plus the proposal/specs (the openspec/ change artifacts) and the author-facing guide. Read docs/extensions-authoring.md for user-facing details on how extensions work.

How dispatch works

• Built-ins always win. Dispatch happens only on Cobra's unknown-command path, so an extension can never shadow start, snapshot, etc.
• Resolution order: built-ins → a bundled directory next to the lstk binary → PATH. A bundled extension wins over a same-named one on PATH.
• Global flags are consumed before the name. lstk --non-interactive deploy --foo runs the extension with just --foo; everything after <name> is the extension's and is forwarded verbatim.

What lstk passes to an extension

So extensions don't re-implement endpoint discovery or read lstk's config, lstk hands them context through two environment variables:

• LSTK_EXT_API_VERSION — an integer contract version.
• LSTK_EXT_CONTEXT — a JSON object: the config dir, the auth token (when logged in), whether the session is non-interactive, and an array of every running emulator (type, endpoint, port).

Emulators is an array because lstk can run AWS, Snowflake, and Azure emulators at once. New fields may be added without bumping the version — an extension confirms a field by its presence in the JSON; the version bumps only on a breaking change.

Authorization

lstk passes the user's auth token and makes no entitlement decision. An extension that needs to gate access (e.g. a paid feature) authorizes the user itself, server-side, with that token. This is deliberate: lstk is open source and rebuildable, so any client-side check is a speed bump, not a control.

Telemetry

When telemetry is enabled (LSTK_OTEL), lstk records each extension invocation (name, duration, exit code) as an OpenTelemetry span. Nothing is emitted when telemetry is off.

Scope of the first release

The first release runs extensions and passes context to them — including a bundled extension placed manually next to lstk (that is, in the same directory), so LocalStack's own bundled extensions can be validated by hand.

This code does not download or auto-update bundled extensions. Automated packaging into the install artifacts (binary archive / Homebrew / npm) and atomic version-matched updates are deferred to a follow-up change, add-bundled-extension-distribution (its artifacts are also in this PR's openspec/ tree).

What's in the PR

• internal/extension/ — domain logic: resolution (bundled dir + PATH), the JSON runtime context, exec/telemetry.
• cmd/extension.go (hooked from cmd/root.go) — unknown-command dispatch, help listing, and context wiring; cmd/help.go aligns the Extensions help section with the built-in command columns.
• test/integration/ — integration tests driving a real lstk binary against an in-tree reference extension (test-samples/extensions/lstk-ref).
• openspec/changes/add-extension-mechanism/ — proposal, design, specs (framework, runtime-context, entitlement, bundling), and tasks.
• openspec/changes/add-bundled-extension-distribution/ — the deferred distribution + auto-update change.
• docs/extensions-authoring.md — the author-facing guide to the contract.

Review feedback incorporated

• Multi-emulator support → the context carries a JSON array of emulators from day one.
• Telemetry of extension invocations.
• TUI: no shared library — extensions couple to lstk only through the env contract and bring their own libraries.
• Malicious extensions: no allow-list — lstk runs any resolvable lstk-<name> like Git; trust is the local machine's, and bundled extensions ship inside the lstk artifact rather than as separate downloads.

[carole-lavillonniere]

This overall looks good to me! Here are a few things that are not addressed as far as I could see, which I think deserve decisions before starting with implementation:

• Telemetry and tracing of extensions
• TUI: the proposal does not say if we share any components with main binary or re-implement?
• Possibility of malicious extensions: do we want to implement something such as a whitelist of extensions to prevent that?
• Multi-emulator support: passing the endpoint as a simple env var is conflicting with that. Can we go with the json format from day 1?

[mmaureenliu]

This overall looks good to me! Here are a few things that are not addressed as far as I could see, which I think deserve decisions before starting with implementation:

• Telemetry and tracing of extensions
• TUI: the proposal does not say if we share any components with main binary or re-implement?
• Possibility of malicious extensions: do we want to implement something such as a whitelist of extensions to prevent that?
• Multi-emulator support: passing the endpoint as a simple env var is conflicting with that. Can we go with the json format from day 1?

I'd also like to see answers to questions 3 and 4

[peter-smith-phd]

Thanks for the discussion :-)

• Telemetry and tracing of extensions

Great idea, I'll add that.

• TUI: the proposal does not say if we share any components with main binary or re-implement?

I've gone with the no-sharing approach. I did think about creating a shared library, but that makes building an extension more complicated and more dependent on Golang APIs (which can change without much control). Instead, I went with a simple environment variable-based contract that's less likely to change (and we have a version number if we need to change it). If a third-party wants to build an extension, they'll need to incorporate their own libraries for doing whatever they want their extension to do (including TUI).

• Possibility of malicious extensions: do we want to implement something such as a whitelist of extensions to prevent that?

I haven't worried about this, because the only way to inject a malicious extension is to install it onto your local machine, which should be secured in other ways. If I was a hacker, I'd target commands like ls or cat, rather than lstk-xxx. I know that some extension mechanisms can download arbitrary extensions directly from the internet, but that seems overkill for us. Note that we will have "bundle extensions" (e.g. lstk-deploy and lstk-doctor), but those will be bundled with the main lstk binary, rather than separate downloads.

I did notice that some tools have an extension add command, but that seems overkill.

• Multi-emulator support: passing the endpoint as a simple env var is conflicting with that. Can we go with the json format from day 1?

Good idea... changing to a JSON format and using arrays/objects will solve that. We'd definitely want extensions to be aware that multiple emulators might be running, and to not require modification in future.

[anisaoshafi]

LGTM 👍🏼
Could you add a small section in the README explaining how to use extension feature?