bundle

Overview ¶

Package bundle implements the canonical nSelf paid plugin bundle catalog plus install/remove orchestration with license validation, version pinning, and atomic rollback on failure (S2.T03/T04/T22).

Bundle membership is resolved from bundles.json (ADR-P6-03), the single source of truth for bundle -> plugin membership, served at plugins.nself.org/bundles.json. See registry.go for the fetch+cache loader. The cmd layer must consume this package via Get/Names/All — do NOT hand-maintain a second bundle map anywhere else in the CLI.

installer.go — S2.T03: `nself bundle install <bundle>` orchestrator.

Atomicity: pre-flight ALL licenses, then install each constituent plugin sequentially via plugin.Install. On any per-plugin failure we roll back by removing every plugin we successfully installed in THIS invocation. Plugins that were already on disk before the call are left untouched.

--dry-run prints the planned actions and exits without filesystem changes. --force re-installs even if the same version is already installed

(repair/upgrade path). License is ALWAYS validated regardless of
--force; --force NEVER bypasses the license check.

--strict fails if any plugin in the bundle is missing from the registry

(default: skip missing with a warning).

--channel selects stable/beta/canary for version resolution (T22).

App-ready (P7-PLUG-19): after the members are installed the installer records the ledger and, when InstallOpts.Hooks is set, runs reconcile, start, readiness, tracking and health (package appready; installer_appready.go). The member loop is in installer_members.go and the licence pre-flight in installer_licence.go. A free bundle (Bundle.IsFree) skips the ping_api bundle entitlement call.

registry.go — fetch+cache loader for bundles.json (ADR-P6-03).

Load is called once, eagerly, at command start (bundleCmd's PersistentPreRunE) — never lazily on first Get/All access. It fetches the live document from plugins.nself.org/bundles.json, validates it, and populates the in-memory bundle map every invocation. On fetch failure it falls back to the last-known-good local cache (mirrors internal/license/validate.go's RefreshCache/ExportCache/ImportCache cache-then-fall-back convention); if no cache exists either, Load returns a clear network error rather than silently serving an empty bundle set.

There is no go:embed fallback — the loader always fetches live, cache fallback only on fetch failure (per ticket P6-E4-W3-S3-T10).

registry_cache.go — local on-disk cache for the last-known-good bundles.json (P6-E4-W3-S3-T10). Split out of registry.go to stay under the 300-line/file cap (internal/repoqa).

remove_guard.go — `remove <plugin>` and the bundle ledger (P7-PLUG-20).

Purpose: stop a single-plugin remove from leaving an installed bundle half installed, and keep the ledger in step after a plugin is removed. Inputs: the plugin directory and a plugin name. Outputs: ReferencingBundles (who needs the plugin), GuardPluginRemove (the E133 refusal or a warning), ForgetPlugin (drop the removed plugin's record). Constraints: reads go through Store.Load (a missing ledger is bootstrapped in memory and never written); ForgetPlugin writes only when the ledger file already exists and never creates it.

remove_guard_testhook.go — a test hook for the bundle catalog (P7-PLUG-20).

Purpose: tests of callers that run before any command has loaded the bundle catalog (remove <plugin>, remove <bundle>) need the "not loaded yet" state. Inputs: none. Outputs: the catalog is unloaded; the returned func restores it. Constraints: tests only; production code never calls it.

remover.go — `nself bundle remove <bundle>` orchestrator (P7-PLUG-20).

Purpose: remove a bundle without deleting what something else still needs. A plugin goes only when the bundle install ledger says no other installed bundle references it AND the owner did not install it on its own (PLUG D6); a plugin another bundle or the owner needs stays, with the reason printed. Inputs: a bundle slug and RemoveOpts (dry-run, delete-data, confirmation). Outputs: a RemoveResult; the plugins removed from the plugin directory and the ledger at <pluginDir>/.nself-state/bundles.json updated to match. Constraints: the plan, the removals and the ledger writes all happen inside one ledger lock (Store.Locked), so a concurrent install cannot add a reference between the plan and the delete. Before the first removal the ledger is written (a bootstrap ledger included) and a remove intent is recorded in .nself-state/remove-intent.json (remover_intent.go); the intent shrinks after each member and is cleared on full success, so a kill or a failed final write is resumed by running the same command again. Removal stops at the first failure and the ledger then reflects exactly what was removed. A member that an installed plugin outside the plan depends on is kept and recorded explicit (remover_deps.go). Plugin data is kept unless --delete-data (see remover_plan.go for the v1.4/v1.5 rules and the confirmation gate). Members are removed in reverse bundle order (a dependency before its dependents is removed last).

remover_deps.go — keep bundle members that a kept plugin depends on (D-0325).

Purpose: `bundle remove` releases a member when no bundle and no explicit install needs it, but a plugin outside the plan can still list that member in its plugin.json dependencies. Removing it would break that plugin. Inputs: a removePlan, the original ledger, the plugin directory and a reverse-dependency scan (plugin.ReverseDependencies unless a test swaps it). Outputs: the plan with such members moved from Planned to Kept (reason "needed by <plugins>; recorded explicit") and their records in plan.work restored as explicit, so a later bundle remove keeps them too. Constraints: iterates to a fixpoint (a kept plugin is itself an outside dependent of what it needs). A scan error refuses the plan: nothing is removed. No I/O beyond the scan.

remover_intent.go — the durable steps of a real `nself bundle remove` (D-0368).

Purpose: before this, the plan, every plugin removal and the ledger write ran inside one ledger Update that wrote the file only at the end. With no ledger file yet, a kill between members (or a failed final write) left nothing on disk, so the next run re-bootstrapped and, because bootstrap records a bundle only when every member is installed, lost the half-removed bundle (E134). Inputs: the held ledger Tx and ledger, the bundle, the plugin directory and the Remove options. Outputs: members removed; the ledger and the remove intent kept in step. Constraints: all of it runs inside ONE Store.Locked. Order: read the intent, plan, checkpoint the ledger, record the intent, remove members (intent shrinks after each), on full success clear the intent, then write the final ledger (a kill between the last two is harmless: see locked). If either checkpoint write fails nothing is removed. A failed intent shrink is only a warning: the intent then over-approximates and a gone member plans as not installed. RemoveOpts.noIntent (tests only) skips the intent and the checkpoint to reproduce the old behaviour.

remover_plan.go — the plan, the data policy and the ledger settlement of `nself bundle remove` (P7-PLUG-20).

Purpose: keep Remove short. Holds the pure planning step (what the ledger lets this bundle remove), the data-handling rules, the --delete-data confirmation gate and the ledger bookkeeping after removals. Inputs: a Bundle, a ledger.Ledger and the plugin directory. Outputs: a removePlan, the data decision, and the ledger to write. Constraints: computePlan and settleLedger do no I/O beyond stat calls on the plugin directory; the caller holds the ledger lock for real runs.

remover_recover.go — read the remove intent of an interrupted `bundle remove` (D-0368).

Purpose: tell the user a remove is being resumed, and drop an intent whose bundle the ledger no longer records. Inputs: the held ledger Tx, the loaded ledger and the bundle. Outputs: whether the intent belongs to a recorded bundle; a stale intent is cleared. Constraints: runs inside the Locked callback of Remove. The checkpoint write makes the ledger durable before any delete, so a recorded bundle needs no repair. If the ledger does not record the bundle (the file was deleted and re-bootstrapped, which marks leftovers explicit), the intent is only cleared and the normal path follows (E134 on v1.5, a no-op warning on v1.4): nothing is rebuilt from the intent, because a plugin that came back unrecorded after a stale intent must not be deleted on its say-so.

resolver.go — S2.T22: cross-bundle plugin version MAX resolution.

When multiple bundles are installed simultaneously (e.g. `nself bundle install nself+` which installs all 6 paid bundles), the same plugin P may be required at different versions by different bundles. This file resolves those conflicts: MAX version wins across all bundles. Conflicts are informational — they are logged but never block the install.

Exit code 3 (downgrade): if an already-installed plugin version is HIGHER than all requested bundle versions, the caller skips that plugin to avoid a downgrade. This is surfaced as a Conflict with Resolved = "" to signal skip.

version_resolver.go — S2.T22: resolve bundle slugs + release channels into concrete plugin version pins. Reads plugins-pro/registry.json via the existing internal/plugin registry fetcher so the same fallback + cache chain (primary URL → GitHub raw → stale cache) applies.

Also provides cross-bundle MAX-resolution: when multiple bundles are installed and share plugins, the installed version is always the MAX (newest) of what each bundle requires — never a silent downgrade.