@penvhq/launcher 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { Environment, PenvError, ManifestEngine, PackageKind } 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.
@@ -225,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. */
@@ -323,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 {
@@ -336,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 {
@@ -401,6 +412,48 @@ 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";
@@ -548,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. */
@@ -621,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, 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, VersionUnknownError, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packumentUrl, 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 { Environment, PenvError, ManifestEngine, PackageKind } 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.
@@ -225,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. */
@@ -323,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 {
@@ -336,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 {
@@ -401,6 +412,48 @@ 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";
@@ -548,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. */
@@ -621,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, 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, VersionUnknownError, add, assertReleasePin, bundledEngine, declarationPath, engineAt, fetchRelease, findAdoptedRoot, findProject, httpFetcher, inspectInstall, installPin, integrityOf, launcherUpdateCommand, nodeSpawner, packumentUrl, 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

@@ -42,7 +42,15 @@ import {
   TrustDeclinedError,
   TrustPublisherMissingError,
   TrustReasonMissingError,
+  UPGRADE_COMMAND,
+  UpgradeDeclinedError,
+  UpgradeFlagError,
+  UpgradeInstallFailedError,
+  UpgradeNoDownloadError,
+  UpgradeSubjectError,
+  UpgradeUnattendedError,
   VersionUnknownError,
+  YES_FLAG,
   add,
   assertReleasePin,
   bundledEngine,
@@ -66,8 +74,9 @@ import {
   runLauncher,
   setProviderType,
   tarballUrl,
+  upgrade,
   writeDeclaration
-} from "./chunk-BNUZ52VN.js";
+} from "./chunk-USYQEKPW.js";
 export {
   AddFlagError,
   AddLocalFlagError,
@@ -112,7 +121,15 @@ export {
   TrustDeclinedError,
   TrustPublisherMissingError,
   TrustReasonMissingError,
+  UPGRADE_COMMAND,
+  UpgradeDeclinedError,
+  UpgradeFlagError,
+  UpgradeInstallFailedError,
+  UpgradeNoDownloadError,
+  UpgradeSubjectError,
+  UpgradeUnattendedError,
   VersionUnknownError,
+  YES_FLAG,
   add,
   assertReleasePin,
   bundledEngine,
@@ -136,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.10.0",
+  "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.10.0",
-    "@penvhq/core": "0.10.0"
+    "@penvhq/cli": "0.11.0",
+    "@penvhq/core": "0.11.0"
   },
   "scripts": {
     "build": "tsup"