@penvhq/cli 0.10.0 → 0.12.0

package/dist/install.d.cts

@@ -0,0 +1,126 @@
+import { PenvError } from '@penvhq/core';
+
+/**
+ * The runtime dependencies an adopted project takes, and how they get there.
+ *
+ * PRD §3: an adopted project depends on `@penvhq/penv` at the engine's own
+ * version — the typed `@env` surface, not a CLI distribution. It also depends on
+ * zod, because the `penv.schema.ts` init scaffolds imports it: zod is a *peer* of
+ * `@penvhq/penv`, and a peer is a package the project supplies. Under pnpm's
+ * strict layout nothing hoists it to the project root, so an install that named
+ * only `@penvhq/penv` left the very schema init had just written unable to
+ * resolve `zod` — and adoption could never finish.
+ *
+ * Both are installed with the package manager the project already uses, and only
+ * after showing the exact `package.json` and lockfile change: an install is the
+ * one step of adoption that reaches outside the repository, so it is the one step
+ * that is shown before it happens rather than reported after.
+ *
+ * The install itself is a seam. It shells out to a package manager, which the
+ * tests must never do — and a fake here is not a weaker test, because what init
+ * has to get right is the plan, the consent, and the refusal when the install
+ * does not happen.
+ *
+ * A plan is a list of steps, because in a workspace "the project's dependency"
+ * is plural. pnpm refuses a bare `add` at a workspace root (`-w` is how you say
+ * you meant the root), and a workspace package that declares `@penvhq/penv`
+ * itself is a second copy of the very version the manifest pins — one repository
+ * ran the 0.8 bridge under a 0.11 pin for three releases because nothing looked
+ * below the root. So every `package.json` that declares it moves, under one
+ * consent, and the commands shown are the ones that run.
+ *
+ * Two commands write that dependency line: `penv init`, which is the engine's,
+ * and `penv upgrade`, which is the launcher's. This module is published at
+ * `@penvhq/cli/install` so the launcher reaches it without loading the command
+ * surface — one answer to "which package manager, which diff, which spawn",
+ * rather than a second copy on the other side of the launcher/engine split.
+ */
+
+/** The package an adopted project depends on. The CLI engine is not one of its dependencies. */
+declare const RUNTIME_PACKAGE = "@penvhq/penv";
+/** The peer `penv.schema.ts` imports, which the project supplies because a peer is not hoisted. */
+declare const SCHEMA_PACKAGE = "zod";
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+/** One package the adopted project needs, and what its `package.json` says today. */
+interface InstallPackage {
+    readonly name: string;
+    readonly version: string;
+    /** What `package.json` already says about it, when it says anything. */
+    readonly declared?: string;
+    /** True when this project already has it — nothing to install for this one. */
+    readonly satisfied: boolean;
+}
+/** One `package.json` the install rewrites, and the command that rewrites it. */
+interface InstallStep {
+    /** The file the diff names — `package.json`, or a workspace package's path to it. */
+    readonly manifest: string;
+    /** Everything this file needs, in the order the diff shows them. */
+    readonly packages: readonly InstallPackage[];
+    /** The command, argv-shaped — run from the project root, whichever file it writes. */
+    readonly command: readonly string[];
+    /** True when this file already declares every one of them. */
+    readonly satisfied: boolean;
+}
+interface InstallPlan {
+    readonly root: string;
+    readonly manager: PackageManager;
+    /** The root's `package.json` first, then every workspace package that declares the runtime one. */
+    readonly steps: readonly InstallStep[];
+    /** The lockfile the manager will rewrite, when the project has one. */
+    readonly lockfile?: string;
+    /** True when every step is already satisfied — nothing to install. */
+    readonly satisfied: boolean;
+}
+/** Runs an install plan, or throws. Replaced in tests; never spawns there. */
+type InstallRuntime = (plan: InstallPlan) => Promise<void>;
+/**
+ * The engine's own version, read from its manifest rather than restated in the
+ * source: `@penvhq/penv` must match the engine exactly, and a constant beside
+ * the version a release bumps is a second answer waiting to drift.
+ */
+declare function engineVersion(): string;
+/**
+ * The zod an adopted project installs: the floor of the peer range the engine
+ * and `@penvhq/penv` both declare, which is the version penv is built and tested
+ * against.
+ *
+ * The floor rather than the range, because the diff shown before the install has
+ * to be the line that actually lands — `--save-exact` on `^4.4.3` would write
+ * whatever the registry resolved that day, which is not something a reader can
+ * consent to in advance.
+ */
+declare function schemaPackageVersion(): string;
+/** The package manager this project already uses: its lockfile, then what it declares, then npm. */
+declare function detectPackageManager(root: string): PackageManager;
+/** True when `root` is the root of a pnpm workspace, which is what `-w` is for. */
+declare function isPnpmWorkspaceRoot(root: string): boolean;
+declare function planInstall(root: string, version?: string): InstallPlan;
+/** What this plan actually installs, once per package however many files declare it. */
+declare function installedPackages(plan: InstallPlan): readonly InstallPackage[];
+/**
+ * The change, as it will appear in the diff — the whole point of showing it is
+ * that the reader recognises their own file, so these are the `package.json`
+ * lines that land and the lockfile that gets rewritten, not a summary of both.
+ *
+ * In a workspace that is more than one file, and the commands underneath are the
+ * ones that run: a "Run with:" line the reader cannot paste is worse than none.
+ */
+declare function renderInstallPlan(plan: InstallPlan): string[];
+/**
+ * The real install: the project's own package manager, started the way any other
+ * child is (`.cmd` shims on Windows included), with its output the user's to see.
+ *
+ * Every step runs from the project root — `-w` and `--filter` are how a workspace
+ * says which `package.json` it means, so the directory never changes.
+ */
+declare const installWithPackageManager: InstallRuntime;
+/**
+ * What to do about a package manager that refused.
+ *
+ * Never the command that just failed: the one remediation guaranteed not to work
+ * is the one the reader already ran. The manager said why, on their screen, and
+ * nothing was migrated — so the answer is that line and a second `penv init`.
+ */
+declare function installFailed(plan: InstallPlan, step: InstallStep): PenvError;
+
+export { type InstallPackage, type InstallPlan, type InstallRuntime, type InstallStep, type PackageManager, RUNTIME_PACKAGE, SCHEMA_PACKAGE, detectPackageManager, engineVersion, installFailed, installWithPackageManager, installedPackages, isPnpmWorkspaceRoot, planInstall, renderInstallPlan, schemaPackageVersion };

package/dist/install.d.ts

@@ -0,0 +1,126 @@
+import { PenvError } from '@penvhq/core';
+
+/**
+ * The runtime dependencies an adopted project takes, and how they get there.
+ *
+ * PRD §3: an adopted project depends on `@penvhq/penv` at the engine's own
+ * version — the typed `@env` surface, not a CLI distribution. It also depends on
+ * zod, because the `penv.schema.ts` init scaffolds imports it: zod is a *peer* of
+ * `@penvhq/penv`, and a peer is a package the project supplies. Under pnpm's
+ * strict layout nothing hoists it to the project root, so an install that named
+ * only `@penvhq/penv` left the very schema init had just written unable to
+ * resolve `zod` — and adoption could never finish.
+ *
+ * Both are installed with the package manager the project already uses, and only
+ * after showing the exact `package.json` and lockfile change: an install is the
+ * one step of adoption that reaches outside the repository, so it is the one step
+ * that is shown before it happens rather than reported after.
+ *
+ * The install itself is a seam. It shells out to a package manager, which the
+ * tests must never do — and a fake here is not a weaker test, because what init
+ * has to get right is the plan, the consent, and the refusal when the install
+ * does not happen.
+ *
+ * A plan is a list of steps, because in a workspace "the project's dependency"
+ * is plural. pnpm refuses a bare `add` at a workspace root (`-w` is how you say
+ * you meant the root), and a workspace package that declares `@penvhq/penv`
+ * itself is a second copy of the very version the manifest pins — one repository
+ * ran the 0.8 bridge under a 0.11 pin for three releases because nothing looked
+ * below the root. So every `package.json` that declares it moves, under one
+ * consent, and the commands shown are the ones that run.
+ *
+ * Two commands write that dependency line: `penv init`, which is the engine's,
+ * and `penv upgrade`, which is the launcher's. This module is published at
+ * `@penvhq/cli/install` so the launcher reaches it without loading the command
+ * surface — one answer to "which package manager, which diff, which spawn",
+ * rather than a second copy on the other side of the launcher/engine split.
+ */
+
+/** The package an adopted project depends on. The CLI engine is not one of its dependencies. */
+declare const RUNTIME_PACKAGE = "@penvhq/penv";
+/** The peer `penv.schema.ts` imports, which the project supplies because a peer is not hoisted. */
+declare const SCHEMA_PACKAGE = "zod";
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+/** One package the adopted project needs, and what its `package.json` says today. */
+interface InstallPackage {
+    readonly name: string;
+    readonly version: string;
+    /** What `package.json` already says about it, when it says anything. */
+    readonly declared?: string;
+    /** True when this project already has it — nothing to install for this one. */
+    readonly satisfied: boolean;
+}
+/** One `package.json` the install rewrites, and the command that rewrites it. */
+interface InstallStep {
+    /** The file the diff names — `package.json`, or a workspace package's path to it. */
+    readonly manifest: string;
+    /** Everything this file needs, in the order the diff shows them. */
+    readonly packages: readonly InstallPackage[];
+    /** The command, argv-shaped — run from the project root, whichever file it writes. */
+    readonly command: readonly string[];
+    /** True when this file already declares every one of them. */
+    readonly satisfied: boolean;
+}
+interface InstallPlan {
+    readonly root: string;
+    readonly manager: PackageManager;
+    /** The root's `package.json` first, then every workspace package that declares the runtime one. */
+    readonly steps: readonly InstallStep[];
+    /** The lockfile the manager will rewrite, when the project has one. */
+    readonly lockfile?: string;
+    /** True when every step is already satisfied — nothing to install. */
+    readonly satisfied: boolean;
+}
+/** Runs an install plan, or throws. Replaced in tests; never spawns there. */
+type InstallRuntime = (plan: InstallPlan) => Promise<void>;
+/**
+ * The engine's own version, read from its manifest rather than restated in the
+ * source: `@penvhq/penv` must match the engine exactly, and a constant beside
+ * the version a release bumps is a second answer waiting to drift.
+ */
+declare function engineVersion(): string;
+/**
+ * The zod an adopted project installs: the floor of the peer range the engine
+ * and `@penvhq/penv` both declare, which is the version penv is built and tested
+ * against.
+ *
+ * The floor rather than the range, because the diff shown before the install has
+ * to be the line that actually lands — `--save-exact` on `^4.4.3` would write
+ * whatever the registry resolved that day, which is not something a reader can
+ * consent to in advance.
+ */
+declare function schemaPackageVersion(): string;
+/** The package manager this project already uses: its lockfile, then what it declares, then npm. */
+declare function detectPackageManager(root: string): PackageManager;
+/** True when `root` is the root of a pnpm workspace, which is what `-w` is for. */
+declare function isPnpmWorkspaceRoot(root: string): boolean;
+declare function planInstall(root: string, version?: string): InstallPlan;
+/** What this plan actually installs, once per package however many files declare it. */
+declare function installedPackages(plan: InstallPlan): readonly InstallPackage[];
+/**
+ * The change, as it will appear in the diff — the whole point of showing it is
+ * that the reader recognises their own file, so these are the `package.json`
+ * lines that land and the lockfile that gets rewritten, not a summary of both.
+ *
+ * In a workspace that is more than one file, and the commands underneath are the
+ * ones that run: a "Run with:" line the reader cannot paste is worse than none.
+ */
+declare function renderInstallPlan(plan: InstallPlan): string[];
+/**
+ * The real install: the project's own package manager, started the way any other
+ * child is (`.cmd` shims on Windows included), with its output the user's to see.
+ *
+ * Every step runs from the project root — `-w` and `--filter` are how a workspace
+ * says which `package.json` it means, so the directory never changes.
+ */
+declare const installWithPackageManager: InstallRuntime;
+/**
+ * What to do about a package manager that refused.
+ *
+ * Never the command that just failed: the one remediation guaranteed not to work
+ * is the one the reader already ran. The manager said why, on their screen, and
+ * nothing was migrated — so the answer is that line and a second `penv init`.
+ */
+declare function installFailed(plan: InstallPlan, step: InstallStep): PenvError;
+
+export { type InstallPackage, type InstallPlan, type InstallRuntime, type InstallStep, type PackageManager, RUNTIME_PACKAGE, SCHEMA_PACKAGE, detectPackageManager, engineVersion, installFailed, installWithPackageManager, installedPackages, isPnpmWorkspaceRoot, planInstall, renderInstallPlan, schemaPackageVersion };

package/dist/install.js

@@ -0,0 +1,27 @@
+import {
+  RUNTIME_PACKAGE,
+  SCHEMA_PACKAGE,
+  detectPackageManager,
+  engineVersion,
+  installFailed,
+  installWithPackageManager,
+  installedPackages,
+  isPnpmWorkspaceRoot,
+  planInstall,
+  renderInstallPlan,
+  schemaPackageVersion
+} from "./chunk-NHTDIZZ2.js";
+export {
+  RUNTIME_PACKAGE,
+  SCHEMA_PACKAGE,
+  detectPackageManager,
+  engineVersion,
+  installFailed,
+  installWithPackageManager,
+  installedPackages,
+  isPnpmWorkspaceRoot,
+  planInstall,
+  renderInstallPlan,
+  schemaPackageVersion
+};
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@penvhq/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "penv's command line. Dependency budget is deliberately looser than the runtime's.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Itzfeminisce/penvhq.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Itzfeminisce/penvhq#readme",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -16,6 +22,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "import": "./dist/install.js",
+      "require": "./dist/install.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -25,10 +36,10 @@
     "@napi-rs/keyring": "1.3.0",
     "citty": "0.2.2",
     "jiti": "2.7.0",
-    "@penvhq/core": "0.10.0",
-    "@penvhq/provider-filesystem": "0.10.0",
-    "@penvhq/provider-mock": "0.10.0",
-    "@penvhq/runtime": "0.10.0"
+    "@penvhq/core": "0.12.0",
+    "@penvhq/provider-filesystem": "0.12.0",
+    "@penvhq/provider-mock": "0.12.0",
+    "@penvhq/runtime": "0.12.0"
   },
   "peerDependencies": {
     "zod": "^4.4.3"
@@ -36,8 +47,8 @@
   "devDependencies": {
     "server-only": "0.0.1",
     "zod": "4.4.3",
-    "@penvhq/provider-github": "0.10.0",
-    "@penvhq/provider-vault": "0.10.0"
+    "@penvhq/provider-github": "0.12.0",
+    "@penvhq/provider-vault": "0.12.0"
   },
   "scripts": {
     "build": "tsup"