Merge pull request #405 from paritytech/feat/mod-package-manager-autoinstall

feat: auto-install the project's package manager during mod/deploy

Author: UtkarshBhardwaj007

.changeset/mod-package-manager-autoinstall.md

@@ -0,0 +1,10 @@
+---
+"playground-cli": minor
+---
+
+`playground mod` now detects the package manager a project uses (pnpm/yarn/bun/npm)
+and, when it (or Node.js) is missing, offers to install it with one confirmation
+before running the project's setup, instead of failing with a confusing error.
+`playground deploy` and `playground build` install a missing manager automatically
+as part of the build step. macOS and Linux are supported; non-interactive runs
+install without prompting.

src/commands/mod/SetupScreen.tsx

@@ -13,7 +13,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { Box, Text } from "ink";
 import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -31,9 +31,12 @@ import { runCommand } from "../../utils/git.js";
 import { createOptionalGitBaseline } from "../../utils/mod/git-baseline.js";
 import { downloadGitHubTarball, parseGitHubRepoUrl } from "../../utils/mod/source.js";
 import {
-    findUnsatisfiedPackageManagers,
-    missingPackageManagerMessage,
-} from "../../utils/mod/packageManager.js";
+    ensurePackageManager,
+    planPackageManager,
+    type InstallPlan,
+} from "../../utils/packageManagers.js";
+import { decidePmPhase, pmConfirmLabel } from "./setupFlow.js";
+import { Select } from "../../utils/ui/theme/Select.js";
 import { VERSION_LABEL } from "../../utils/version.js";
 import { getNetworkLabel } from "../../config.js";
 import { fetchBulletinJson, getBulletinGateway } from "../../utils/bulletinGateway.js";
@@ -71,10 +74,18 @@ export function SetupScreen({ domain, metadata: initial, registry, targetDir, on
     // sourceUnavailable.ts) — the publisher made the repo private/deleted it
     // after publishing, which we can't undo and the user can't fix.
     const [unavailable, setUnavailable] = useState(false);
+    // Package-manager-aware phase machine. After the source is downloaded we
+    // detect the project's PM and, when it (or Node) is missing, ask once to
+    // install it before running setup.sh. See setupFlow.ts for the decision.
+    const [phase, setPhase] = useState<"pre" | "confirm" | "install" | "post" | "halt">("pre");
+    const [pmPlan, setPmPlan] = useState<InstallPlan | null>(null);
     const setupLogFile = resolve(targetDir, ".dot-mod-setup.log");
     const sourceLogFile = resolve(targetDir, ".dot-mod-source.log");
 
-    const steps: Step[] = [
+    // Steps that always run first: fetch metadata + download source. `meta` is
+    // populated by the first step and read by the second, so they must stay
+    // together in this array (StepRunner runs them sequentially).
+    const preSteps: Step[] = [
         {
             name: "fetch app metadata",
             run: async (log) => {
@@ -148,33 +159,44 @@ export function SetupScreen({ domain, metadata: initial, registry, targetDir, on
                 ignoreModLogs(targetDir);
             },
         },
-        {
-            name: "run setup.sh",
-            keepLogOnSuccess: true,
-            run: async (log) => {
-                const setupPath = resolve(targetDir, "setup.sh");
-                if (!existsSync(setupPath)) {
-                    // Most moddable apps have no setup.sh, and that's normal —
-                    // surfacing it as a warning row alarmed users. Skip the step
-                    // silently so nothing is shown; the parent still prints the
-                    // generic "Next steps" footer because `setupRan` stays false.
-                    throw new SilentSkip("no setup.sh found");
-                }
-                const missing = await findUnsatisfiedPackageManagers(
-                    readFileSync(setupPath, "utf8"),
-                );
-                if (missing.length > 0) {
-                    throw new Error(missingPackageManagerMessage(missing));
-                }
-                await runCommand("bash setup.sh", { cwd: targetDir, log, logFile: setupLogFile });
-                setupRanRef.current = true;
-                setSetupRanVisible(true);
-            },
-        },
     ];
 
+    // Final on-disk work: run the app's setup.sh. The package manager is
+    // guaranteed present by the install phase that runs before this, so the
+    // old "missing package manager" gate is gone.
+    const runSetupSh: Step = {
+        name: "run setup.sh",
+        keepLogOnSuccess: true,
+        run: async (log) => {
+            const setupPath = resolve(targetDir, "setup.sh");
+            if (!existsSync(setupPath)) {
+                // Most moddable apps have no setup.sh, and that's normal —
+                // surfacing it as a warning row alarmed users. Skip the step
+                // silently so nothing is shown; the parent still prints the
+                // generic "Next steps" footer because `setupRan` stays false.
+                throw new SilentSkip("no setup.sh found");
+            }
+            await runCommand("bash setup.sh", { cwd: targetDir, log, logFile: setupLogFile });
+            setupRanRef.current = true;
+            setSetupRanVisible(true);
+        },
+    };
+
     const [error, setError] = useState<string | null>(null);
 
+    // Declining the install (or having no installable PM path) is a SOFT
+    // outcome: exit cleanly with `setupRan: false` and let the halt Callout
+    // explain the manual remedy. Fire `onDone` exactly once on entering halt.
+    const haltReportedRef = useRef(false);
+    useEffect(() => {
+        if (phase === "halt" && !haltReportedRef.current) {
+            haltReportedRef.current = true;
+            onDone({ ok: true, setupRan: false });
+        }
+        // onDone is captured once on mount by the parent; gate purely on phase.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [phase]);
+
     return (
         <Box flexDirection="column">
             <Header
@@ -193,14 +215,93 @@ export function SetupScreen({ domain, metadata: initial, registry, targetDir, on
                 </Callout>
             )}
 
-            <StepRunner
-                title={`modding ${domain}`}
-                steps={steps}
-                onDone={(result) => {
-                    if (result.error) setError(result.error);
-                    onDone({ ok: result.ok, setupRan: setupRanRef.current });
-                }}
-            />
+            {phase === "pre" && (
+                <StepRunner
+                    title={`modding ${domain}`}
+                    steps={preSteps}
+                    onDone={async (result) => {
+                        if (!result.ok) {
+                            if (result.error) setError(result.error);
+                            onDone({ ok: false, setupRan: false });
+                            return;
+                        }
+                        // Planning is best-effort: if PM detection throws, fall
+                        // through to setup.sh and let any real failure surface
+                        // there rather than blocking the mod on a probe error.
+                        // This callback is fire-and-forget (StepRunner doesn't
+                        // await it), but the success path only ever advances the
+                        // phase — it never calls the terminal onDone — so the
+                        // component stays mounted and the post-await setState
+                        // lands on a live component.
+                        try {
+                            const plan = await planPackageManager(targetDir);
+                            setPmPlan(plan);
+                            const next = decidePmPhase({
+                                missing: plan.toolsToInstall,
+                                isTTY: Boolean(process.stdin.isTTY),
+                            });
+                            setPhase(next === "setup" ? "post" : next);
+                        } catch {
+                            setPhase("post");
+                        }
+                    }}
+                />
+            )}
+
+            {phase === "confirm" && pmPlan && (
+                <Select
+                    label={pmConfirmLabel(pmPlan.pm, pmPlan.toolsToInstall)}
+                    options={[
+                        { value: "yes", label: "Install now" },
+                        { value: "no", label: "Cancel — I'll install it myself" },
+                    ]}
+                    onSelect={(v) => setPhase(v === "yes" ? "install" : "halt")}
+                />
+            )}
+
+            {phase === "install" && (
+                <StepRunner
+                    title="installing package manager"
+                    steps={[
+                        {
+                            name: `install ${pmPlan?.pm ?? "package manager"}`,
+                            run: async (log) => {
+                                // `confirm` omitted on purpose — the user already
+                                // confirmed (TTY) or we auto-proceed (non-TTY).
+                                await ensurePackageManager(targetDir, { onData: log });
+                            },
+                        },
+                    ]}
+                    onDone={(result) => {
+                        if (!result.ok) {
+                            setError(result.error ?? "package manager install failed");
+                            onDone({ ok: false, setupRan: false });
+                            return;
+                        }
+                        setPhase("post");
+                    }}
+                />
+            )}
+
+            {phase === "post" && (
+                <StepRunner
+                    title={`finishing ${domain}`}
+                    steps={[runSetupSh]}
+                    onDone={(result) => {
+                        if (result.error) setError(result.error);
+                        onDone({ ok: result.ok, setupRan: setupRanRef.current });
+                    }}
+                />
+            )}
+
+            {phase === "halt" && pmPlan && (
+                <Callout tone="warning" title="package manager not installed">
+                    <Text>
+                        This project uses {pmPlan.pm}. Install it, then re-run playground mod (or
+                        the build).
+                    </Text>
+                </Callout>
+            )}
 
             {!unavailable && <Hint>→ {targetDir}</Hint>}
             {setupRanVisible && <Hint>full setup log: {setupLogFile}</Hint>}

src/commands/mod/setupFlow.test.ts

@@ -0,0 +1,39 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, it, expect } from "vitest";
+import { decidePmPhase, pmConfirmLabel } from "./setupFlow.js";
+
+describe("decidePmPhase", () => {
+    it("goes straight to setup when nothing is missing", () => {
+        expect(decidePmPhase({ missing: [], isTTY: true })).toBe("setup");
+    });
+
+    it("prompts for confirmation in a TTY when tools are missing", () => {
+        expect(decidePmPhase({ missing: ["Node.js", "pnpm"], isTTY: true })).toBe("confirm");
+    });
+
+    it("auto-installs without a prompt when there is no TTY", () => {
+        expect(decidePmPhase({ missing: ["bun"], isTTY: false })).toBe("install");
+    });
+});
+
+describe("pmConfirmLabel", () => {
+    it("names the PM and exactly what will be installed", () => {
+        expect(pmConfirmLabel("pnpm", ["Node.js", "pnpm"])).toBe(
+            "This project uses pnpm, which isn't installed. Install it now? (Node.js + pnpm)",
+        );
+    });
+});

src/commands/mod/setupFlow.ts

@@ -0,0 +1,31 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/** Pure decision + text helpers for SetupScreen's package-manager phase. */
+
+import type { PackageManager } from "../../utils/packageManagers.js";
+
+/** Phase to enter after the source has been downloaded and the PM planned. */
+export type PmPhase = "setup" | "confirm" | "install";
+
+export function decidePmPhase(opts: { missing: string[]; isTTY: boolean }): PmPhase {
+    if (opts.missing.length === 0) return "setup";
+    return opts.isTTY ? "confirm" : "install";
+}
+
+/** Confirmation prompt label, naming the PM and the exact tools to install. */
+export function pmConfirmLabel(pm: PackageManager, toolsToInstall: string[]): string {
+    return `This project uses ${pm}, which isn't installed. Install it now? (${toolsToInstall.join(" + ")})`;
+}

src/utils/build/detect.test.ts

@@ -49,6 +49,10 @@ describe("detectPackageManager", () => {
     it("picks bun when only bun.lockb is present", () => {
         expect(detectPackageManager(new Set(["bun.lockb"]))).toBe("bun");
     });
+
+    it("picks bun when only bun.lock (bun 1.2+ text lockfile) is present", () => {
+        expect(detectPackageManager(new Set(["bun.lock"]))).toBe("bun");
+    });
 });
 
 describe("detectBuildConfig", () => {

src/utils/build/detect.ts

@@ -24,14 +24,21 @@ import { DEFAULT_BUILD_DIR } from "../../config.js";
 
 export type PackageManager = "pnpm" | "yarn" | "bun" | "npm";
 
-/** Files we inspect on disk to infer the package manager. */
+/** Canonical lockfile basename per package manager. */
 export const PM_LOCKFILES: Record<PackageManager, string> = {
     pnpm: "pnpm-lock.yaml",
     yarn: "yarn.lock",
     bun: "bun.lockb",
     npm: "package-lock.json",
 };
 
+// Bun 1.2+ defaults to a TEXT lockfile (`bun.lock`); older bun wrote the binary
+// `bun.lockb`. Detect either so modern bun projects aren't mis-detected as npm.
+const BUN_TEXT_LOCKFILE = "bun.lock";
+
+/** Every lockfile basename to probe on disk (some PMs have more than one). */
+export const PM_LOCKFILES_ALL: string[] = [...Object.values(PM_LOCKFILES), BUN_TEXT_LOCKFILE];
+
 export interface BuildConfig {
     /** Binary + args to spawn. */
     cmd: string;
@@ -80,7 +87,7 @@ export class BuildDetectError extends Error {
 export function detectPackageManager(lockfiles: Set<string>): PackageManager {
     if (lockfiles.has(PM_LOCKFILES.pnpm)) return "pnpm";
     if (lockfiles.has(PM_LOCKFILES.yarn)) return "yarn";
-    if (lockfiles.has(PM_LOCKFILES.bun)) return "bun";
+    if (lockfiles.has(PM_LOCKFILES.bun) || lockfiles.has(BUN_TEXT_LOCKFILE)) return "bun";
     return "npm";
 }