@penvhq/launcher 0.9.5 → 0.11.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { PenvError, ManifestEngine } from '@penvhq/core';
+import { Environment, PenvError, ManifestEngine, PackageKind, Manifest } from '@penvhq/core';
+import { InstallRuntime } from '@penvhq/cli/install';
 
 /**
  * Every byte penv downloads comes through here.
@@ -156,50 +157,6 @@ interface WriteDeclarationOptions extends DeclarationSubject {
 /** Writes the declaration and answers with the path a message prints. */
 declare function writeDeclaration(options: WriteDeclarationOptions): string;
 
-/**
- * `$PENV_HOME` — the one directory the launcher owns.
- *
- * Engines and extensions are addressed by exact name and exact version, so a
- * machine holds every version any of its projects pins at once and no project's
- * command is ever answered by another project's bytes.
- */
-/** A read-only view of the process environment. */
-type Environment = Readonly<Record<string, string | undefined>>;
-/** The variable that moves the store off `~/.penv`. */
-declare const PENV_HOME_VAR = "PENV_HOME";
-/** The two things the store holds, and the directory each lives under. */
-type PackageKind = "engines" | "extensions";
-/** How the launcher was installed, recorded by the installer that did it. */
-declare const HOME_META_FILE = "meta.json";
-/** Written beside an installed package: the SSRI of the tarball it came from. */
-declare const INTEGRITY_FILE = ".penv-integrity";
-/** The update command for a launcher whose installer recorded nothing. */
-declare const NPM_UPDATE_COMMAND = "npm install -g @penvhq/launcher";
-/** The store, from the environment. `~/.penv` unless `$PENV_HOME` says otherwise. */
-declare function penvHome(env: Environment): string;
-/**
- * Where one exact version lives.
- *
- * The manifest's grammar already refuses a name or a version that could climb
- * out of the store, so the containment check is the second lock rather than the
- * first: this function is also reached from `penv add`, where the name is
- * whatever the user typed.
- *
- * Containment is measured against the bucket, not against `$PENV_HOME`. A name
- * of `../extensions/x` stays inside the store while landing an engine among the
- * extensions, and a store where the two are not separated is a store where the
- * kind a caller asked for is not the kind it gets.
- */
-declare function packageDir(home: string, kind: PackageKind, name: string, version: string): string;
-/**
- * The command that updates this launcher.
- *
- * Advisory, so it never throws: a store with no `meta.json`, or one holding
- * something unreadable, falls back to the npm form rather than turning a
- * manifest-format refusal into a second failure about a metadata file.
- */
-declare function launcherUpdateCommand(home: string): string;
-
 /**
  * Handing the command over.
  *
@@ -269,6 +226,10 @@ declare function bundledEngine(): Engine;
 
 /** The command that materializes everything the manifest pins. */
 declare const INSTALL_COMMAND = "penv install";
+/** The command that moves the engine pin, with no version: whatever `latest` points at. */
+declare const UPGRADE_COMMAND = "penv upgrade";
+/** The flag that answers `upgrade`'s one question ahead of time. */
+declare const YES_FLAG = "--yes";
 /** How long a package outside the official scope must have existed. */
 declare const MIN_PACKAGE_AGE_DAYS = 7;
 /** The flag that overrides {@link MIN_PACKAGE_AGE_DAYS}, and only that. */
@@ -330,6 +291,23 @@ declare class AddLocalFlagError extends PenvError {
     readonly name = "AddLocalFlagError";
     constructor(subject: string);
 }
+/**
+ * The extension resolved and is not something penv can import.
+ *
+ * `add` used to certify resolution and stop there, so a package whose `exports`
+ * pointed at TypeScript source got three green checks and failed much later,
+ * from an unrelated command. The load check runs here, at the one moment the
+ * operator is looking at the provider.
+ */
+declare class ExtensionNotImportableError extends PenvError {
+    readonly name = "ExtensionNotImportableError";
+    constructor(name: string, entry: string | undefined, local: boolean);
+}
+/** The extension imported and threw. Its own failure is the diagnosis. */
+declare class ExtensionUnloadableError extends PenvError {
+    readonly name = "ExtensionUnloadableError";
+    constructor(name: string, entry: string, detail: string, local: boolean);
+}
 /** `--local` on a package the project does not have. */
 declare class LocalExtensionUnresolvedError extends PenvError {
     readonly name = "LocalExtensionUnresolvedError";
@@ -350,10 +328,16 @@ declare class OfficialRegistryError extends PenvError {
     readonly name = "OfficialRegistryError";
     constructor(name: string, registry: string);
 }
-/** The registry could not be read at all. */
+/**
+ * The registry could not be read at all.
+ *
+ * `retry` is the command that would repeat this resolution. Two commands read a
+ * release — `add` and `upgrade` — and a refusal that named the wrong one would
+ * send the reader to a command that answers a different question.
+ */
 declare class RegistryUnreadableError extends PenvError {
     readonly name = "RegistryUnreadableError";
-    constructor(name: string, url: string, detail: string);
+    constructor(name: string, url: string, detail: string, retry?: string);
 }
 /** The registry has no such package. */
 declare class PackageUnknownError extends PenvError {
@@ -363,7 +347,7 @@ declare class PackageUnknownError extends PenvError {
 /** The package exists; the version asked for does not. */
 declare class VersionUnknownError extends PenvError {
     readonly name = "VersionUnknownError";
-    constructor(name: string, version: string, url: string);
+    constructor(name: string, version: string, url: string, retry?: string);
 }
 /** The registry answered, but without a fact the manifest has to record. */
 declare class ReleaseIncompleteError extends PenvError {
@@ -428,12 +412,77 @@ declare class EnginePinMismatchError extends PenvError {
     readonly name = "EnginePinMismatchError";
     constructor(pinned: string, ran: string);
 }
+/** `penv upgrade` with something other than one optional version. */
+declare class UpgradeSubjectError extends PenvError {
+    readonly name = "UpgradeSubjectError";
+    constructor();
+}
+/** A flag `penv upgrade` does not have. */
+declare class UpgradeFlagError extends PenvError {
+    readonly name = "UpgradeFlagError";
+    constructor(flag: string);
+}
+/** `penv upgrade` needs the registry, and `--no-download` says this run has no network. */
+declare class UpgradeNoDownloadError extends PenvError {
+    readonly name = "UpgradeNoDownloadError";
+    constructor();
+}
+/**
+ * `penv upgrade` on a machine with nobody at it.
+ *
+ * Unattended, penv will move the pin only to a version somebody named and only
+ * with the flag that says they meant it: what upgrade rewrites is two committed
+ * files, and a pipeline that picks the engine is a pipeline choosing which bytes
+ * the project runs.
+ */
+declare class UpgradeUnattendedError extends PenvError {
+    readonly name = "UpgradeUnattendedError";
+    constructor();
+}
+/** The upgrade was shown and declined. Neither committed file was touched. */
+declare class UpgradeDeclinedError extends PenvError {
+    readonly name = "UpgradeDeclinedError";
+    constructor(version: string);
+}
+/**
+ * The package manager refused, so the pin stayed where it was.
+ *
+ * The dependency moves before the manifest for exactly this reason: an upgrade
+ * that cannot finish leaves a project pinning the engine it was already running.
+ */
+declare class UpgradeInstallFailedError extends PenvError {
+    readonly name = "UpgradeInstallFailedError";
+    constructor(command: string);
+}
 /** An installed directory with nothing runnable in it. */
 declare class EngineEntryError extends PenvError {
     readonly name = "EngineEntryError";
     constructor(name: string, version: string, dir: string);
 }
 
+/**
+ * What the launcher alone knows about `$PENV_HOME`: how the installation that
+ * created it updates itself, and what it writes beside an installed package.
+ *
+ * The store's layout — where `$PENV_HOME` is and where one exact version lives —
+ * is `@penvhq/core`'s, because the engine reads the same directories the
+ * launcher fills.
+ */
+/** How the launcher was installed, recorded by the installer that did it. */
+declare const HOME_META_FILE = "meta.json";
+/** Written beside an installed package: the SSRI of the tarball it came from. */
+declare const INTEGRITY_FILE = ".penv-integrity";
+/** The update command for a launcher whose installer recorded nothing. */
+declare const NPM_UPDATE_COMMAND = "npm install -g @penvhq/launcher";
+/**
+ * The command that updates this launcher.
+ *
+ * Advisory, so it never throws: a store with no `meta.json`, or one holding
+ * something unreadable, falls back to the npm form rather than turning a
+ * manifest-format refusal into a second failure about a metadata file.
+ */
+declare function launcherUpdateCommand(home: string): string;
+
 /**
  * The one hash penv checks: npm's SSRI, over the tarball bytes.
  *
@@ -552,6 +601,8 @@ interface ReleaseQuery {
     readonly version?: string;
     /** Only when the package comes from somewhere other than npmjs. */
     readonly registry?: string;
+    /** The command that would repeat this resolution. Absent means `penv add <name>`. */
+    readonly retry?: string;
     readonly fetcher: Fetcher;
 }
 /** The packument's address, which an exact name can be built rather than searched. */
@@ -625,4 +676,51 @@ interface ArchiveSubject {
 /** Every regular file in an npm tarball, `package/` stripped. */
 declare function readTarball(gzipped: Uint8Array, subject: ArchiveSubject): TarEntry[];
 
-export { AddFlagError, AddLocalFlagError, AddLocalInCiError, AddNoDownloadError, AddNotInteractiveError, type AddOptions, AddPackageNameError, AddRegistryError, type AddResult, AddSubjectError, ArchiveError, type ArchiveSubject, BUNDLED_ENGINE_PIN, DEFAULT_REGISTRY, DEV_PIN_INTEGRITY, DEV_PIN_VERSION, DeclarationMissingError, DeclarationNotSelfContainedError, type DeclarationSubject, type Delegation, DownloadFailedError, DownloadIntegrityError, ENGINE_BIN, type Engine, EngineEntryError, EnginePinMismatchError, EnginePinUnreleasedError, type Environment, type ExtensionPackage, type Fetcher, HOME_META_FILE, INSTALL_COMMAND, INTEGRITY_FILE, InstallDeclinedError, type InstallOptions, type InstallState, type Installation, LOCAL_FLAG, type LauncherIo, type LauncherOptions, LocalExtensionUnresolvedError, MIN_PACKAGE_AGE_DAYS, NPM_UPDATE_COMMAND, NoProjectError, OfficialRegistryError, PENV_HOME_VAR, PackageCorruptError, type PackageKind, PackageMissingError, PackageTooYoungError, PackageUnknownError, type Pin, type Project, type ProviderEntry, RegistryUnreadableError, type Release, ReleaseIncompleteError, type ReleaseQuery, type Spawner, TRUST_YOUNG_FLAG, type TarEntry, TrustDeclinedError, TrustPublisherMissingError, TrustReasonMissingError, VersionUnknownError, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packageDir, packumentUrl, penvHome, readExtensionPackage, readProviderEntries, readTarball, releaseEnginePin, renderDeclaration, runLauncher, setProviderType, tarballUrl, writeDeclaration };
+/**
+ * `penv upgrade [version]` — the one command that moves the engine pin.
+ *
+ * It belongs to the launcher for the same reason `add` does: everything it
+ * writes is the launcher's. An engine cannot compute the npm integrity of its
+ * own tarball, and the pin is a promise about bytes, so the integrity comes from
+ * the registry's `dist.integrity` and from nowhere else — never hashed here, and
+ * never typed by a person. Before this command existed, moving the pin meant
+ * hand-editing a version *and* an 88-character hash into the one file whose
+ * whole purpose is that its bytes are verified, and a mistyped character came
+ * back as a supply-chain check failing closed.
+ *
+ * Two committed files move: the manifest's engine pin and the project's
+ * `@penvhq/penv` dependency, at the same exact version. They move together or
+ * not at all — one consent covers both, and the dependency lands first, so a
+ * package manager that refuses leaves a project still pinning the engine it was
+ * already running.
+ *
+ * Extensions are not touched. Each carries its own pin and its own trust
+ * decision, and re-pinning them because the engine moved would be penv choosing
+ * bytes nobody reviewed; `penv add <package>@<version>` moves one.
+ *
+ * A downgrade is an upgrade backwards and takes the same path — a pin is a pin,
+ * and a project that needs the engine it ran last week is not asking for
+ * something penv should argue with.
+ */
+
+interface UpgradeOptions {
+    /** The tokens after `upgrade`. */
+    readonly argv: readonly string[];
+    /** The project root — the directory holding `.penv/`. */
+    readonly root: string;
+    readonly manifestFile: string;
+    /** The manifest as the launcher already parsed it. */
+    readonly manifest: Manifest;
+    readonly home: string;
+    readonly io: LauncherIo;
+    readonly fetcher: Fetcher;
+    /** The launcher's `--no-download`: this run reaches no registry at all. */
+    readonly noDownload?: boolean;
+    /** True on a CI runner, which may have a terminal and still have nobody at it. */
+    readonly ci?: boolean;
+    /** Injected in tests: how the project's dependency is installed. Never spawns there. */
+    readonly install?: InstallRuntime;
+}
+declare function upgrade(options: UpgradeOptions): Promise<void>;
+
+export { AddFlagError, AddLocalFlagError, AddLocalInCiError, AddNoDownloadError, AddNotInteractiveError, type AddOptions, AddPackageNameError, AddRegistryError, type AddResult, AddSubjectError, ArchiveError, type ArchiveSubject, BUNDLED_ENGINE_PIN, DEFAULT_REGISTRY, DEV_PIN_INTEGRITY, DEV_PIN_VERSION, DeclarationMissingError, DeclarationNotSelfContainedError, type DeclarationSubject, type Delegation, DownloadFailedError, DownloadIntegrityError, ENGINE_BIN, type Engine, EngineEntryError, EnginePinMismatchError, EnginePinUnreleasedError, ExtensionNotImportableError, type ExtensionPackage, ExtensionUnloadableError, type Fetcher, HOME_META_FILE, INSTALL_COMMAND, INTEGRITY_FILE, InstallDeclinedError, type InstallOptions, type InstallState, type Installation, LOCAL_FLAG, type LauncherIo, type LauncherOptions, LocalExtensionUnresolvedError, MIN_PACKAGE_AGE_DAYS, NPM_UPDATE_COMMAND, NoProjectError, OfficialRegistryError, PackageCorruptError, PackageMissingError, PackageTooYoungError, PackageUnknownError, type Pin, type Project, type ProviderEntry, RegistryUnreadableError, type Release, ReleaseIncompleteError, type ReleaseQuery, type Spawner, TRUST_YOUNG_FLAG, type TarEntry, TrustDeclinedError, TrustPublisherMissingError, TrustReasonMissingError, UPGRADE_COMMAND, UpgradeDeclinedError, UpgradeFlagError, UpgradeInstallFailedError, UpgradeNoDownloadError, type UpgradeOptions, UpgradeSubjectError, UpgradeUnattendedError, VersionUnknownError, YES_FLAG, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packumentUrl, readExtensionPackage, readProviderEntries, readTarball, releaseEnginePin, renderDeclaration, runLauncher, setProviderType, tarballUrl, upgrade, writeDeclaration };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { PenvError, ManifestEngine } from '@penvhq/core';
+import { Environment, PenvError, ManifestEngine, PackageKind, Manifest } from '@penvhq/core';
+import { InstallRuntime } from '@penvhq/cli/install';
 
 /**
  * Every byte penv downloads comes through here.
@@ -156,50 +157,6 @@ interface WriteDeclarationOptions extends DeclarationSubject {
 /** Writes the declaration and answers with the path a message prints. */
 declare function writeDeclaration(options: WriteDeclarationOptions): string;
 
-/**
- * `$PENV_HOME` — the one directory the launcher owns.
- *
- * Engines and extensions are addressed by exact name and exact version, so a
- * machine holds every version any of its projects pins at once and no project's
- * command is ever answered by another project's bytes.
- */
-/** A read-only view of the process environment. */
-type Environment = Readonly<Record<string, string | undefined>>;
-/** The variable that moves the store off `~/.penv`. */
-declare const PENV_HOME_VAR = "PENV_HOME";
-/** The two things the store holds, and the directory each lives under. */
-type PackageKind = "engines" | "extensions";
-/** How the launcher was installed, recorded by the installer that did it. */
-declare const HOME_META_FILE = "meta.json";
-/** Written beside an installed package: the SSRI of the tarball it came from. */
-declare const INTEGRITY_FILE = ".penv-integrity";
-/** The update command for a launcher whose installer recorded nothing. */
-declare const NPM_UPDATE_COMMAND = "npm install -g @penvhq/launcher";
-/** The store, from the environment. `~/.penv` unless `$PENV_HOME` says otherwise. */
-declare function penvHome(env: Environment): string;
-/**
- * Where one exact version lives.
- *
- * The manifest's grammar already refuses a name or a version that could climb
- * out of the store, so the containment check is the second lock rather than the
- * first: this function is also reached from `penv add`, where the name is
- * whatever the user typed.
- *
- * Containment is measured against the bucket, not against `$PENV_HOME`. A name
- * of `../extensions/x` stays inside the store while landing an engine among the
- * extensions, and a store where the two are not separated is a store where the
- * kind a caller asked for is not the kind it gets.
- */
-declare function packageDir(home: string, kind: PackageKind, name: string, version: string): string;
-/**
- * The command that updates this launcher.
- *
- * Advisory, so it never throws: a store with no `meta.json`, or one holding
- * something unreadable, falls back to the npm form rather than turning a
- * manifest-format refusal into a second failure about a metadata file.
- */
-declare function launcherUpdateCommand(home: string): string;
-
 /**
  * Handing the command over.
  *
@@ -269,6 +226,10 @@ declare function bundledEngine(): Engine;
 
 /** The command that materializes everything the manifest pins. */
 declare const INSTALL_COMMAND = "penv install";
+/** The command that moves the engine pin, with no version: whatever `latest` points at. */
+declare const UPGRADE_COMMAND = "penv upgrade";
+/** The flag that answers `upgrade`'s one question ahead of time. */
+declare const YES_FLAG = "--yes";
 /** How long a package outside the official scope must have existed. */
 declare const MIN_PACKAGE_AGE_DAYS = 7;
 /** The flag that overrides {@link MIN_PACKAGE_AGE_DAYS}, and only that. */
@@ -330,6 +291,23 @@ declare class AddLocalFlagError extends PenvError {
     readonly name = "AddLocalFlagError";
     constructor(subject: string);
 }
+/**
+ * The extension resolved and is not something penv can import.
+ *
+ * `add` used to certify resolution and stop there, so a package whose `exports`
+ * pointed at TypeScript source got three green checks and failed much later,
+ * from an unrelated command. The load check runs here, at the one moment the
+ * operator is looking at the provider.
+ */
+declare class ExtensionNotImportableError extends PenvError {
+    readonly name = "ExtensionNotImportableError";
+    constructor(name: string, entry: string | undefined, local: boolean);
+}
+/** The extension imported and threw. Its own failure is the diagnosis. */
+declare class ExtensionUnloadableError extends PenvError {
+    readonly name = "ExtensionUnloadableError";
+    constructor(name: string, entry: string, detail: string, local: boolean);
+}
 /** `--local` on a package the project does not have. */
 declare class LocalExtensionUnresolvedError extends PenvError {
     readonly name = "LocalExtensionUnresolvedError";
@@ -350,10 +328,16 @@ declare class OfficialRegistryError extends PenvError {
     readonly name = "OfficialRegistryError";
     constructor(name: string, registry: string);
 }
-/** The registry could not be read at all. */
+/**
+ * The registry could not be read at all.
+ *
+ * `retry` is the command that would repeat this resolution. Two commands read a
+ * release — `add` and `upgrade` — and a refusal that named the wrong one would
+ * send the reader to a command that answers a different question.
+ */
 declare class RegistryUnreadableError extends PenvError {
     readonly name = "RegistryUnreadableError";
-    constructor(name: string, url: string, detail: string);
+    constructor(name: string, url: string, detail: string, retry?: string);
 }
 /** The registry has no such package. */
 declare class PackageUnknownError extends PenvError {
@@ -363,7 +347,7 @@ declare class PackageUnknownError extends PenvError {
 /** The package exists; the version asked for does not. */
 declare class VersionUnknownError extends PenvError {
     readonly name = "VersionUnknownError";
-    constructor(name: string, version: string, url: string);
+    constructor(name: string, version: string, url: string, retry?: string);
 }
 /** The registry answered, but without a fact the manifest has to record. */
 declare class ReleaseIncompleteError extends PenvError {
@@ -428,12 +412,77 @@ declare class EnginePinMismatchError extends PenvError {
     readonly name = "EnginePinMismatchError";
     constructor(pinned: string, ran: string);
 }
+/** `penv upgrade` with something other than one optional version. */
+declare class UpgradeSubjectError extends PenvError {
+    readonly name = "UpgradeSubjectError";
+    constructor();
+}
+/** A flag `penv upgrade` does not have. */
+declare class UpgradeFlagError extends PenvError {
+    readonly name = "UpgradeFlagError";
+    constructor(flag: string);
+}
+/** `penv upgrade` needs the registry, and `--no-download` says this run has no network. */
+declare class UpgradeNoDownloadError extends PenvError {
+    readonly name = "UpgradeNoDownloadError";
+    constructor();
+}
+/**
+ * `penv upgrade` on a machine with nobody at it.
+ *
+ * Unattended, penv will move the pin only to a version somebody named and only
+ * with the flag that says they meant it: what upgrade rewrites is two committed
+ * files, and a pipeline that picks the engine is a pipeline choosing which bytes
+ * the project runs.
+ */
+declare class UpgradeUnattendedError extends PenvError {
+    readonly name = "UpgradeUnattendedError";
+    constructor();
+}
+/** The upgrade was shown and declined. Neither committed file was touched. */
+declare class UpgradeDeclinedError extends PenvError {
+    readonly name = "UpgradeDeclinedError";
+    constructor(version: string);
+}
+/**
+ * The package manager refused, so the pin stayed where it was.
+ *
+ * The dependency moves before the manifest for exactly this reason: an upgrade
+ * that cannot finish leaves a project pinning the engine it was already running.
+ */
+declare class UpgradeInstallFailedError extends PenvError {
+    readonly name = "UpgradeInstallFailedError";
+    constructor(command: string);
+}
 /** An installed directory with nothing runnable in it. */
 declare class EngineEntryError extends PenvError {
     readonly name = "EngineEntryError";
     constructor(name: string, version: string, dir: string);
 }
 
+/**
+ * What the launcher alone knows about `$PENV_HOME`: how the installation that
+ * created it updates itself, and what it writes beside an installed package.
+ *
+ * The store's layout — where `$PENV_HOME` is and where one exact version lives —
+ * is `@penvhq/core`'s, because the engine reads the same directories the
+ * launcher fills.
+ */
+/** How the launcher was installed, recorded by the installer that did it. */
+declare const HOME_META_FILE = "meta.json";
+/** Written beside an installed package: the SSRI of the tarball it came from. */
+declare const INTEGRITY_FILE = ".penv-integrity";
+/** The update command for a launcher whose installer recorded nothing. */
+declare const NPM_UPDATE_COMMAND = "npm install -g @penvhq/launcher";
+/**
+ * The command that updates this launcher.
+ *
+ * Advisory, so it never throws: a store with no `meta.json`, or one holding
+ * something unreadable, falls back to the npm form rather than turning a
+ * manifest-format refusal into a second failure about a metadata file.
+ */
+declare function launcherUpdateCommand(home: string): string;
+
 /**
  * The one hash penv checks: npm's SSRI, over the tarball bytes.
  *
@@ -552,6 +601,8 @@ interface ReleaseQuery {
     readonly version?: string;
     /** Only when the package comes from somewhere other than npmjs. */
     readonly registry?: string;
+    /** The command that would repeat this resolution. Absent means `penv add <name>`. */
+    readonly retry?: string;
     readonly fetcher: Fetcher;
 }
 /** The packument's address, which an exact name can be built rather than searched. */
@@ -625,4 +676,51 @@ interface ArchiveSubject {
 /** Every regular file in an npm tarball, `package/` stripped. */
 declare function readTarball(gzipped: Uint8Array, subject: ArchiveSubject): TarEntry[];
 
-export { AddFlagError, AddLocalFlagError, AddLocalInCiError, AddNoDownloadError, AddNotInteractiveError, type AddOptions, AddPackageNameError, AddRegistryError, type AddResult, AddSubjectError, ArchiveError, type ArchiveSubject, BUNDLED_ENGINE_PIN, DEFAULT_REGISTRY, DEV_PIN_INTEGRITY, DEV_PIN_VERSION, DeclarationMissingError, DeclarationNotSelfContainedError, type DeclarationSubject, type Delegation, DownloadFailedError, DownloadIntegrityError, ENGINE_BIN, type Engine, EngineEntryError, EnginePinMismatchError, EnginePinUnreleasedError, type Environment, type ExtensionPackage, type Fetcher, HOME_META_FILE, INSTALL_COMMAND, INTEGRITY_FILE, InstallDeclinedError, type InstallOptions, type InstallState, type Installation, LOCAL_FLAG, type LauncherIo, type LauncherOptions, LocalExtensionUnresolvedError, MIN_PACKAGE_AGE_DAYS, NPM_UPDATE_COMMAND, NoProjectError, OfficialRegistryError, PENV_HOME_VAR, PackageCorruptError, type PackageKind, PackageMissingError, PackageTooYoungError, PackageUnknownError, type Pin, type Project, type ProviderEntry, RegistryUnreadableError, type Release, ReleaseIncompleteError, type ReleaseQuery, type Spawner, TRUST_YOUNG_FLAG, type TarEntry, TrustDeclinedError, TrustPublisherMissingError, TrustReasonMissingError, VersionUnknownError, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packageDir, packumentUrl, penvHome, readExtensionPackage, readProviderEntries, readTarball, releaseEnginePin, renderDeclaration, runLauncher, setProviderType, tarballUrl, writeDeclaration };
+/**
+ * `penv upgrade [version]` — the one command that moves the engine pin.
+ *
+ * It belongs to the launcher for the same reason `add` does: everything it
+ * writes is the launcher's. An engine cannot compute the npm integrity of its
+ * own tarball, and the pin is a promise about bytes, so the integrity comes from
+ * the registry's `dist.integrity` and from nowhere else — never hashed here, and
+ * never typed by a person. Before this command existed, moving the pin meant
+ * hand-editing a version *and* an 88-character hash into the one file whose
+ * whole purpose is that its bytes are verified, and a mistyped character came
+ * back as a supply-chain check failing closed.
+ *
+ * Two committed files move: the manifest's engine pin and the project's
+ * `@penvhq/penv` dependency, at the same exact version. They move together or
+ * not at all — one consent covers both, and the dependency lands first, so a
+ * package manager that refuses leaves a project still pinning the engine it was
+ * already running.
+ *
+ * Extensions are not touched. Each carries its own pin and its own trust
+ * decision, and re-pinning them because the engine moved would be penv choosing
+ * bytes nobody reviewed; `penv add <package>@<version>` moves one.
+ *
+ * A downgrade is an upgrade backwards and takes the same path — a pin is a pin,
+ * and a project that needs the engine it ran last week is not asking for
+ * something penv should argue with.
+ */
+
+interface UpgradeOptions {
+    /** The tokens after `upgrade`. */
+    readonly argv: readonly string[];
+    /** The project root — the directory holding `.penv/`. */
+    readonly root: string;
+    readonly manifestFile: string;
+    /** The manifest as the launcher already parsed it. */
+    readonly manifest: Manifest;
+    readonly home: string;
+    readonly io: LauncherIo;
+    readonly fetcher: Fetcher;
+    /** The launcher's `--no-download`: this run reaches no registry at all. */
+    readonly noDownload?: boolean;
+    /** True on a CI runner, which may have a terminal and still have nobody at it. */
+    readonly ci?: boolean;
+    /** Injected in tests: how the project's dependency is installed. Never spawns there. */
+    readonly install?: InstallRuntime;
+}
+declare function upgrade(options: UpgradeOptions): Promise<void>;
+
+export { AddFlagError, AddLocalFlagError, AddLocalInCiError, AddNoDownloadError, AddNotInteractiveError, type AddOptions, AddPackageNameError, AddRegistryError, type AddResult, AddSubjectError, ArchiveError, type ArchiveSubject, BUNDLED_ENGINE_PIN, DEFAULT_REGISTRY, DEV_PIN_INTEGRITY, DEV_PIN_VERSION, DeclarationMissingError, DeclarationNotSelfContainedError, type DeclarationSubject, type Delegation, DownloadFailedError, DownloadIntegrityError, ENGINE_BIN, type Engine, EngineEntryError, EnginePinMismatchError, EnginePinUnreleasedError, ExtensionNotImportableError, type ExtensionPackage, ExtensionUnloadableError, type Fetcher, HOME_META_FILE, INSTALL_COMMAND, INTEGRITY_FILE, InstallDeclinedError, type InstallOptions, type InstallState, type Installation, LOCAL_FLAG, type LauncherIo, type LauncherOptions, LocalExtensionUnresolvedError, MIN_PACKAGE_AGE_DAYS, NPM_UPDATE_COMMAND, NoProjectError, OfficialRegistryError, PackageCorruptError, PackageMissingError, PackageTooYoungError, PackageUnknownError, type Pin, type Project, type ProviderEntry, RegistryUnreadableError, type Release, ReleaseIncompleteError, type ReleaseQuery, type Spawner, TRUST_YOUNG_FLAG, type TarEntry, TrustDeclinedError, TrustPublisherMissingError, TrustReasonMissingError, UPGRADE_COMMAND, UpgradeDeclinedError, UpgradeFlagError, UpgradeInstallFailedError, UpgradeNoDownloadError, type UpgradeOptions, UpgradeSubjectError, UpgradeUnattendedError, VersionUnknownError, YES_FLAG, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packumentUrl, readExtensionPackage, readProviderEntries, readTarball, releaseEnginePin, renderDeclaration, runLauncher, setProviderType, tarballUrl, upgrade, writeDeclaration };

package/dist/index.js

@@ -20,6 +20,8 @@ import {
   EngineEntryError,
   EnginePinMismatchError,
   EnginePinUnreleasedError,
+  ExtensionNotImportableError,
+  ExtensionUnloadableError,
   HOME_META_FILE,
   INSTALL_COMMAND,
   INTEGRITY_FILE,
@@ -30,7 +32,6 @@ import {
   NPM_UPDATE_COMMAND,
   NoProjectError,
   OfficialRegistryError,
-  PENV_HOME_VAR,
   PackageCorruptError,
   PackageMissingError,
   PackageTooYoungError,
@@ -41,7 +42,15 @@ import {
   TrustDeclinedError,
   TrustPublisherMissingError,
   TrustReasonMissingError,
+  UPGRADE_COMMAND,
+  UpgradeDeclinedError,
+  UpgradeFlagError,
+  UpgradeInstallFailedError,
+  UpgradeNoDownloadError,
+  UpgradeSubjectError,
+  UpgradeUnattendedError,
   VersionUnknownError,
+  YES_FLAG,
   add,
   assertReleasePin,
   bundledEngine,
@@ -56,9 +65,7 @@ import {
   integrityOf,
   launcherUpdateCommand,
   nodeSpawner,
-  packageDir,
   packumentUrl,
-  penvHome,
   readExtensionPackage,
   readProviderEntries,
   readTarball,
@@ -67,8 +74,9 @@ import {
   runLauncher,
   setProviderType,
   tarballUrl,
+  upgrade,
   writeDeclaration
-} from "./chunk-4YZYBC5T.js";
+} from "./chunk-USYQEKPW.js";
 export {
   AddFlagError,
   AddLocalFlagError,
@@ -91,6 +99,8 @@ export {
   EngineEntryError,
   EnginePinMismatchError,
   EnginePinUnreleasedError,
+  ExtensionNotImportableError,
+  ExtensionUnloadableError,
   HOME_META_FILE,
   INSTALL_COMMAND,
   INTEGRITY_FILE,
@@ -101,7 +111,6 @@ export {
   NPM_UPDATE_COMMAND,
   NoProjectError,
   OfficialRegistryError,
-  PENV_HOME_VAR,
   PackageCorruptError,
   PackageMissingError,
   PackageTooYoungError,
@@ -112,7 +121,15 @@ export {
   TrustDeclinedError,
   TrustPublisherMissingError,
   TrustReasonMissingError,
+  UPGRADE_COMMAND,
+  UpgradeDeclinedError,
+  UpgradeFlagError,
+  UpgradeInstallFailedError,
+  UpgradeNoDownloadError,
+  UpgradeSubjectError,
+  UpgradeUnattendedError,
   VersionUnknownError,
+  YES_FLAG,
   add,
   assertReleasePin,
   bundledEngine,
@@ -127,9 +144,7 @@ export {
   integrityOf,
   launcherUpdateCommand,
   nodeSpawner,
-  packageDir,
   packumentUrl,
-  penvHome,
   readExtensionPackage,
   readProviderEntries,
   readTarball,
@@ -138,6 +153,7 @@ export {
   runLauncher,
   setProviderType,
   tarballUrl,
+  upgrade,
   writeDeclaration
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penvhq/launcher",
-  "version": "0.9.5",
+  "version": "0.11.0",
   "description": "The stable penv launcher: it verifies the engine your project pins and hands over the command.",
   "license": "MIT",
   "type": "module",
@@ -22,8 +22,8 @@
   ],
   "dependencies": {
     "zod": "4.4.3",
-    "@penvhq/cli": "0.9.5",
-    "@penvhq/core": "0.9.5"
+    "@penvhq/cli": "0.11.0",
+    "@penvhq/core": "0.11.0"
   },
   "scripts": {
     "build": "tsup"