expand openspec for extension delivery architecture - #452
Conversation
carillan81
added
semver: minor
docs: skip
peter-smith-phd
left a comment
peter-smith-phd
left a comment
There was a problem hiding this comment.
Thanks for doing this! As I've mentioned several times, the update process is quite sensitive and we need to test it very carefully. I'd suggest your next step is to generate a detailed test plan for the DevX team to review.
|
I documented a pending decision about symlink distribution and how to fix it with some proposals |
gtsiolis
left a comment
gtsiolis
left a comment
There was a problem hiding this comment.
Solid expansion of the bundled-extension distribution spec — per-channel packaging (archive root / Homebrew cask staging / npm platform packages), pinned-and-checksum-verified provenance, and cross-transition update continuity are all now spelled out. This is spec/design only, no code.
- thought(non-blocking): on
specs/extension-bundling-distribution/spec.md— the "incomplete bundled set is repaired when lstk is already current" scenario requiresinternal/updateto detect an incomplete set with no version change, i.e. to know the expected set and re-fetch the archive even when versions match. That's a real departure from today's version-only gating; worth making explicit in the test plan @peter-smith-phd asked for, since it's the subtlest part of the update path. - praise: the provenance requirement (a committed pin file plus hard-fail checksum verification before staging) mirrors the existing self-update SHA-256 archive verification, and the public-visibility note — bundled binaries are downloadable, so any gating must be runtime via
LSTK_EXT_CONTEXT, not distribution — is exactly the right thing to pin down now.
Automated review on behalf of @gtsiolis.
Generated by Claude Code
There was a problem hiding this comment.
Thanks for taking care of the extensions architecture and focusing on the update mechanism, Carlos 🙏🏼
I like the stage-than-commit approach, to not break the update.
I tried to understand the delivery mechanism, though I have a bit of a hard time reading tech specs in text only. I might miss many details, and you have better context than me already.
Things will become clearer once doctor implementation starts and when we actually that extension. We can still tweak parts of the design later if needed.
I think the extension you made to the design makes sense. Added some comments for your consideration.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
A thorough rework of the bundled-extension-distribution spec — the channel-placement correction (Homebrew cask, not formula; npm platform package, not the wrapper), the pinned-and-checksummed private-release pull, and a set-wise updater whose guarantee is honestly scoped to "no partially-written file is ever visible under a final name" rather than claiming cross-file atomicity POSIX can't deliver. Docs-only, no code touched.
- thought(non-blocking):
proposal.mdstates "The runtime half already exists and is not touched by this change", but Decision 7's recommended option (b) explicitly changes the runtime resolution contract —Resolver.Resolve/Listgrow a bundled-set branch andLoadDescriptions' "degrade to an empty map on any failure" becomes a hard error for the bundled set. The "not touched" framing holds only under option (a); worth caveating so the proposal summary doesn't undersell (b)'s scope, since (b) is the recommendation. - praise: the "repair an incomplete set even when the binary is already current" case (Decision 5 / task 1.7) is a genuinely subtle catch — the in-the-field pre-bundling updater strands the extensions, and
Check's "already up to date" short-circuit would otherwise hide that for up to a release cycle; keying repair off set completeness rather than the version comparison alone is the right call.
Automated review on behalf of @gtsiolis.
Generated by Claude Code
pending: decide what to do with symlinks pending: remove pinned version
The bundle version now defaults to latest with an explicit tag as an override, instead of a pin file someone has to bump by hand. The release job resolves latest once per build and records the resolved tag in the release notes, so a version still maps to exactly one bundle and a re-run of an already published tag cannot quietly ship different extensions. Bundled extensions are no longer optional payload. An archive that carries none is still valid, but when one does carry them the update installs the whole set or fails, and an install left incomplete by the older updater is repaired on the next run instead of waiting for a newer release. An extension that installs correctly but misbehaves only breaks its own subcommand. The bundled binary layout question is written up as an open decision that blocks packaging only, so the updater and script work can start without it. Adds a task for a CI check that keeps the packaging config and the download step in sync, and notes in the test plan that repairing an incomplete set is a departure from gating on version alone. Co-Authored-By: Claude <noreply@anthropic.com>
3401891 to
51a25de
Compare
5 participants
This PR includes only openspec docs for the extension bundling mechanism. It expands previous work (Thanks Peter!) and defines how the bunlding would work and the tasks to make it real.
This is intended to be the first draft to move forward the project. Any feedback, change, correction, pun or non pejorative expression will be very welcome!