What Changes on an Upgrade
A kit version is a bundle: upgrading it changes more than one prompt. This page lists what moves together, and how kit versions relate to an IST release (snapshot).
Upgrading one kit
skit install @ist/tda-kit # latest
skit install @ist/tda-kit@<version> # a specific version
skit install replaces the kit as a unit. Compared with the previous version:
| Part | What happens |
|---|---|
| Profiles | Replaced by the new version's files. Next session start uses them (see When Sessions Load Prompts) |
| Prompts | Replaced. Prompts the new version no longer ships are removed. Prompts it adds appear |
| Prompt scope | Follows the new manifest. A prompt can move between global and profile scope (e.g. from ~/.ist/prompts/global/ to ~/.ist/prompts/profiles/tda-manager/) |
CLI dependencies (dependencies.npm) | Installed globally at the versions the new kit pins |
Kit dependencies (dependencies.skit) | Installed first, at the versions the new kit asks for |
Permission overlays (profilePermissions) | Applied for the new version |
| Hooks | Copied into place. Hook directories are not tracked, so a hook the new version drops is not removed |
Your own files (e.g. a conventions slot) | Untouched. skit only removes files it recorded for the kit |
The old version's files are removed just before the new ones are copied, so there is no state where both versions' prompts are mixed. skit list shows the installed version afterwards.
CLIs come along
Because a kit pins the CLIs its prompts use, upgrading a kit can also change the version of commands such as itda or isesh on your machine. The kit's pinned version is installed even if a different version is already present. Check with the CLI's own --version after an upgrade if a command behaves differently.
Upgrading an IST release
An IST release is a snapshot: one manifest that pins a tested combination of CLIs and kits. The banner at the top of these docs names the release they describe.
snapshot install @ist/beta # latest release
snapshot install @ist/beta@<version> # a specific release
snapshot current # what you have
snapshot install installs, in the order the manifest lists them:
- CLI packages (e.g.
@ist/sesh,@ist/tda,@microwiseai/skit) at the pinned versions - Kits (e.g.
@ist/tda-kit), each through skit, which in turn installs the kit's owndependencies.npm
npm packages and kits that are already installed at the pinned version are skipped.
So, relative to a single skit install, a release upgrade can also change skit itself and the session tools (isesh, itda, …) that read profiles and prompts. When the release changes the skit version, the skit command's options can change too. The skit reference describes the version pinned by the release in the banner.
By default, packages from the previous release that the new one no longer lists stay installed. snapshot install @ist/beta --replace removes them (--dry-run shows what would be removed first).
Kit version vs. release version
| You run | What is pinned | Use it when |
|---|---|---|
snapshot install @ist/beta | Every CLI and kit, as one tested combination | Normal setup and upgrades |
skit install <kit>@<version> | That kit and the CLIs it declares | Trying a newer kit, or rolling one kit back |
Installing a kit outside the release (newer or older than the release pins) is allowed, but that combination has not been tested together. snapshot install brings you back to the release's combination.
Next
- When Sessions Load Prompts: which running sessions see the upgrade, and when
- Versioned Prompts: why kits are versioned at all