@penvhq/cli 0.9.3 → 0.9.4

package/dist/index.d.cts

@@ -414,13 +414,19 @@ interface DraftField extends SchemaField {
 }
 
 /**
- * The one runtime dependency an adopted project takes, and how it gets there.
+ * The runtime dependencies an adopted project takes, and how they get there.
  *
- * PRD §3: an adopted project depends on exactly `@penvhq/penv` at the engine's
- * own version — the typed `@env` surface, not a CLI distribution. `penv init`
- * installs it 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
+ * 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
@@ -430,18 +436,25 @@ interface DraftField extends SchemaField {
  */
 
 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;
+}
 interface InstallPlan {
     readonly root: string;
     readonly manager: PackageManager;
-    readonly package: string;
-    readonly version: string;
+    /** Everything an adopted project needs, in the order the diff shows them. */
+    readonly packages: readonly InstallPackage[];
     /** The command, argv-shaped — what runs, and what a refusal tells the user to run. */
     readonly command: readonly string[];
     /** The lockfile the manager will rewrite, when the project has one. */
     readonly lockfile?: string;
-    /** What `package.json` already says about the package, when it says anything. */
-    readonly declared?: string;
-    /** True when `package.json` already pins this exact version — nothing to install. */
+    /** True when every package is already there — nothing to install. */
     readonly satisfied: boolean;
 }
 /** Runs an install plan, or throws. Replaced in tests; never spawns there. */
@@ -628,6 +641,13 @@ interface CutoverOptions {
  * files aside. The order is the guarantee: every step before the move leaves a
  * project whose `.env` files are exactly where they were, so a refusal at any
  * of them costs a re-run and nothing else.
+ *
+ * The scaffold is snapshotted first, and rolled back when anything after it
+ * refuses. Without that, "a refusal costs a re-run" was only true of the dotenv
+ * files: a failed run still left a config, a draft schema, an edited tsconfig
+ * and an imported records tree behind, and the next run kept every one of them
+ * rather than starting clean. The install is not rolled back — it is the one
+ * step the developer consented to by itself, and a re-run finds it satisfied.
  */
 declare function applyCutover(plan: CutoverPlan, options?: CutoverOptions): Promise<CutoverResult>;
 declare function runInit(options: InitOptions): InitResult;
@@ -1112,6 +1132,13 @@ interface ChildInvocation {
     readonly command: readonly string[];
     readonly env: Record<string, string>;
     readonly cwd: string;
+    /**
+     * What penv is starting this on its own behalf to do — `init`'s dependency
+     * install. Absent means the command is the user's, from after `--`, and the
+     * two failures have opposite remedies: one is about what they typed, the other
+     * about a program penv chose to run.
+     */
+    readonly purpose?: string;
 }
 /** A started child: how it ends, and the one thing a wrapper may do to it. */
 interface ChildHandle {

package/dist/index.d.ts

@@ -414,13 +414,19 @@ interface DraftField extends SchemaField {
 }
 
 /**
- * The one runtime dependency an adopted project takes, and how it gets there.
+ * The runtime dependencies an adopted project takes, and how they get there.
  *
- * PRD §3: an adopted project depends on exactly `@penvhq/penv` at the engine's
- * own version — the typed `@env` surface, not a CLI distribution. `penv init`
- * installs it 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
+ * 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
@@ -430,18 +436,25 @@ interface DraftField extends SchemaField {
  */
 
 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;
+}
 interface InstallPlan {
     readonly root: string;
     readonly manager: PackageManager;
-    readonly package: string;
-    readonly version: string;
+    /** Everything an adopted project needs, in the order the diff shows them. */
+    readonly packages: readonly InstallPackage[];
     /** The command, argv-shaped — what runs, and what a refusal tells the user to run. */
     readonly command: readonly string[];
     /** The lockfile the manager will rewrite, when the project has one. */
     readonly lockfile?: string;
-    /** What `package.json` already says about the package, when it says anything. */
-    readonly declared?: string;
-    /** True when `package.json` already pins this exact version — nothing to install. */
+    /** True when every package is already there — nothing to install. */
     readonly satisfied: boolean;
 }
 /** Runs an install plan, or throws. Replaced in tests; never spawns there. */
@@ -628,6 +641,13 @@ interface CutoverOptions {
  * files aside. The order is the guarantee: every step before the move leaves a
  * project whose `.env` files are exactly where they were, so a refusal at any
  * of them costs a re-run and nothing else.
+ *
+ * The scaffold is snapshotted first, and rolled back when anything after it
+ * refuses. Without that, "a refusal costs a re-run" was only true of the dotenv
+ * files: a failed run still left a config, a draft schema, an edited tsconfig
+ * and an imported records tree behind, and the next run kept every one of them
+ * rather than starting clean. The install is not rolled back — it is the one
+ * step the developer consented to by itself, and a re-run finds it satisfied.
  */
 declare function applyCutover(plan: CutoverPlan, options?: CutoverOptions): Promise<CutoverResult>;
 declare function runInit(options: InitOptions): InitResult;
@@ -1112,6 +1132,13 @@ interface ChildInvocation {
     readonly command: readonly string[];
     readonly env: Record<string, string>;
     readonly cwd: string;
+    /**
+     * What penv is starting this on its own behalf to do — `init`'s dependency
+     * install. Absent means the command is the user's, from after `--`, and the
+     * two failures have opposite remedies: one is about what they typed, the other
+     * about a program penv chose to run.
+     */
+    readonly purpose?: string;
 }
 /** A started child: how it ends, and the one thing a wrapper may do to it. */
 interface ChildHandle {