@meshxdata/fops 0.0.6 → 0.0.8

package/src/plugins/bundled/fops-plugin-1password/index.js

@@ -144,9 +144,7 @@ export function register(api) {
       } else if (whoami.hasAccount) {
         ok(`1Password configured`, `${whoami.email} — session will unlock on next use`);
       } else {
-        warn("1Password not signed in", "enable CLI integration in 1Password app", async () => {
-          await opSignin();
-        });
+        warn("1Password not signed in", "optional — run: op signin");
       }
     },
   });
@@ -163,7 +161,11 @@ export function register(api) {
 
     const whoami = await opWhoami();
     if (!whoami.authenticated) {
-      console.log(chalk.yellow("  ⚠ 1Password: not signed in — skipping secret sync"));
+      if (whoami.hasAccount) {
+        console.log(chalk.dim("  1Password: session locked — unlock the app to auto-sync secrets"));
+      } else {
+        console.log(chalk.yellow("  ⚠ 1Password: not signed in — skipping secret sync"));
+      }
       return;
     }
 

package/src/plugins/bundled/fops-plugin-1password/lib/op.js

@@ -90,7 +90,7 @@ export async function opSignin() {
     if (check.exitCode === 0) return;
   } catch {}
 
-  // Desktop app integration not enabled — open settings and wait
+  // Desktop app integration not enabled — platform-specific fallback
   if (process.platform === "darwin") {
     console.log("  Opening 1Password Developer settings...");
     console.log("  Enable \"Integrate with 1Password CLI\", then come back.\n");
@@ -105,7 +105,15 @@ export async function opSignin() {
         if (exitCode === 0) return;
       } catch {}
     }
+  } else if (process.platform === "linux") {
+    // On Linux/WSL there's no desktop app — use interactive signin
+    console.log("  No 1Password desktop app on Linux. Signing in interactively...\n");
+    try {
+      await execa("op", ["signin"], { stdio: "inherit", timeout: 120_000 });
+      const check = await execa("op", ["whoami"], { reject: false, timeout: 5000 });
+      if (check.exitCode === 0) return;
+    } catch {}
   }
 
-  throw new Error("1Password CLI integration not enabled");
+  throw new Error("1Password CLI integration not enabled — run: op signin");
 }

package/src/plugins/bundled/fops-plugin-1password/lib/setup.js

@@ -2,9 +2,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
-import inquirer from "inquirer";
 import { opVersion, opWhoami, opSignin, opListVaults } from "./op.js";
 import { discoverTemplates } from "./env.js";
+import { getInquirer } from "../../../../lazy.js";
 
 // Patterns that indicate a key is likely a secret
 const SECRET_PATTERNS = [
@@ -50,14 +50,14 @@ function saveFopsConfig(updates) {
 }
 
 async function ask(message, defaultValue = true) {
-  const { answer } = await inquirer.prompt([{
+  const { answer } = await (await getInquirer()).prompt([{
     type: "confirm", name: "answer", message, default: defaultValue,
   }]);
   return answer;
 }
 
 async function choose(message, choices) {
-  const { answer } = await inquirer.prompt([{
+  const { answer } = await (await getInquirer()).prompt([{
     type: "list", name: "answer", message, choices,
   }]);
   return answer;

package/src/plugins/bundled/fops-plugin-1password/lib/sync.js

@@ -51,9 +51,14 @@ export async function syncSecrets(root) {
       console.log(chalk.green(`  ✓ ${relDir}/.env — ${secrets.size} secret(s) synced`));
       synced++;
     } catch (err) {
-      const msg = `${relDir}: ${err.message}`;
+      // Extract clean error: prefer op's stderr over the generic execa message
+      const stderr = err.stderr?.trim();
+      const clean = stderr
+        ? stderr.replace(/^\[ERROR\]\s*\S+\s*/gm, "").trim()
+        : err.message.split("\n")[0];
+      const msg = `${relDir}: ${clean}`;
       errors.push(msg);
-      console.log(chalk.red(`  ✗ ${relDir}/.env.1password — ${err.message}`));
+      console.log(chalk.red(`  ✗ ${relDir}/.env.1password — ${clean}`));
     }
   }
 

package/src/plugins/bundled/fops-plugin-ecr/lib/aws.js

@@ -44,12 +44,11 @@ export async function ssoLogin(profile) {
   const args = ["sso", "login"];
   if (profile) args.push("--profile", profile);
 
-  // Open /dev/tty so SSO login gets a real terminal even under piped stdio
-  let ttyFd;
-  try {
-    ttyFd = fs.openSync("/dev/tty", "r");
-  } catch {
-    ttyFd = null;
+  // Open /dev/tty so SSO login gets a real terminal even under piped stdio.
+  // On Windows /dev/tty doesn't exist — fall back to inherited stdio.
+  let ttyFd = null;
+  if (process.platform !== "win32") {
+    try { ttyFd = fs.openSync("/dev/tty", "r"); } catch { ttyFd = null; }
   }
 
   await execa("aws", args, {

package/src/plugins/bundled/fops-plugin-ecr/lib/setup.js

@@ -2,7 +2,6 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
-import inquirer from "inquirer";
 import {
   awsVersion,
   detectEcrRegistry,
@@ -11,6 +10,7 @@ import {
   ssoLogin,
   ecrLogin,
 } from "./aws.js";
+import { getInquirer } from "../../../../lazy.js";
 
 /**
  * Read ~/.fops.json config (full file).
@@ -53,7 +53,7 @@ export async function runSetupWizard(root) {
   let version = await awsVersion();
   if (!version) {
     console.log(chalk.red("  ✗ AWS CLI not found."));
-    const { install } = await inquirer.prompt([{
+    const { install } = await (await getInquirer()).prompt([{
       type: "confirm", name: "install", message: "Install via Homebrew?", default: true,
     }]);
     if (install) {
@@ -85,7 +85,7 @@ export async function runSetupWizard(root) {
       console.log(chalk.dim(`    Using profile: ${selectedProfile}`));
     } else {
       const choices = profiles.map((p) => ({ name: p.name, value: p.name }));
-      const { profile } = await inquirer.prompt([{
+      const { profile } = await (await getInquirer()).prompt([{
         type: "list", name: "profile", message: "Select AWS profile:", choices,
       }]);
       selectedProfile = profile;
@@ -94,7 +94,7 @@ export async function runSetupWizard(root) {
     // No profiles — prompt for SSO config
     console.log(chalk.yellow("  No SSO profiles found. Let's configure one."));
 
-    const answers = await inquirer.prompt([
+    const answers = await (await getInquirer()).prompt([
       { type: "input", name: "sessionName", message: "SSO session name:", default: "me-central-1" },
       { type: "input", name: "ssoStartUrl", message: "SSO start URL:", validate: (v) => v?.trim() ? true : "Required." },
       { type: "input", name: "ssoRegion", message: "SSO region:", default: "us-east-1" },
@@ -154,7 +154,7 @@ output = json
   }
 
   // Step 5: Auto-login preference
-  const { autoLogin } = await inquirer.prompt([{
+  const { autoLogin } = await (await getInquirer()).prompt([{
     type: "confirm", name: "autoLogin", message: "Auto-login to ECR before `fops up`?", default: true,
   }]);
 

package/src/plugins/loader.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRegistry } from "./registry.js";
 import { validateManifest } from "./manifest.js";
 import { discoverPlugins } from "./discovery.js";
@@ -127,7 +127,7 @@ async function loadBuiltinPlugins(registry) {
   const entries = fs.readdirSync(builtinsDir).filter((f) => f.endsWith(".js"));
   for (const file of entries) {
     try {
-      const mod = await import(path.join(builtinsDir, file));
+      const mod = await import(pathToFileURL(path.join(builtinsDir, file)).href);
       const plugin = mod.default || mod;
       if (typeof plugin.register === "function") {
         const pluginId = `builtin:${path.basename(file, ".js")}`;
@@ -192,7 +192,7 @@ export async function loadPlugins() {
     }
 
     try {
-      const mod = await import(entryPoint);
+      const mod = await import(pathToFileURL(entryPoint).href);
       const plugin = mod.default || mod;
 
       if (typeof plugin.register === "function") {

package/src/plugins/skills.js

@@ -2,7 +2,6 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { execa } from "execa";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -27,6 +26,7 @@ function parseFrontmatter(content) {
  */
 async function hasBin(name) {
   try {
+    const { execa } = await import("execa");
     await execa("which", [name], { reject: false, timeout: 2000 });
     return true;
   } catch {

package/src/setup/aws.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
 import { execa } from "execa";
-import inquirer from "inquirer";
+import { getInquirer } from "../lazy.js";
 
 /**
  * Read saved FOPS config (~/.fops.json) for AWS SSO settings etc.
@@ -34,7 +34,7 @@ export async function promptAwsSsoConfig() {
   console.log(chalk.dim("  We'll set up an AWS CLI profile for ECR image pulls."));
   console.log(chalk.dim("  You can find these values in your AWS SSO portal.\n"));
 
-  const answers = await inquirer.prompt([
+  const answers = await (await getInquirer()).prompt([
     {
       type: "input",
       name: "profileName",
@@ -100,10 +100,13 @@ export function detectEcrRegistry(dir) {
 /**
  * Parse ~/.aws/config and find SSO profiles with their sso_session names.
  */
-export function detectAwsSsoProfiles() {
-  const configPath = path.join(os.homedir(), ".aws", "config");
-  if (!fs.existsSync(configPath)) return [];
-  const content = fs.readFileSync(configPath, "utf8");
+export function detectAwsSsoProfiles(configContent = null) {
+  if (configContent === null) {
+    const configPath = path.join(os.homedir(), ".aws", "config");
+    if (!fs.existsSync(configPath)) return [];
+    configContent = fs.readFileSync(configPath, "utf8");
+  }
+  const content = configContent;
   const profiles = [];
   let currentProfile = null;
   let currentAttrs = {};
@@ -151,7 +154,7 @@ export async function ensureSsoConfig() {
   console.log(chalk.cyan("\n  AWS SSO is not configured. Let's set it up.\n"));
   console.log(chalk.dim("  You can find these values in your AWS SSO portal.\n"));
 
-  const answers = await inquirer.prompt([
+  const answers = await (await getInquirer()).prompt([
     { type: "input", name: "sessionName", message: "SSO session name:", default: "me-central-1" },
     { type: "input", name: "startUrl", message: "SSO start URL:", validate: (v) => v?.trim() ? true : "Required." },
     { type: "input", name: "ssoRegion", message: "SSO region:", default: "us-east-1" },
@@ -183,86 +186,111 @@ output = json
 }
 
 /**
- * Fix AWS SSO: ensure config exists, detect profile, then login.
+ * Run `aws sso login` for a profile, handling TTY on all platforms.
+ * Returns the execa result ({ exitCode, timedOut }).
  */
-export async function fixAwsSso() {
-  await ensureSsoConfig();
-
-  const profiles = detectAwsSsoProfiles();
-  if (profiles.length === 0) {
-    throw new Error("No SSO profiles found after config — check ~/.aws/config");
+async function runSsoLogin(profileName) {
+  let ttyFd = null;
+  if (process.platform !== "win32") {
+    try { ttyFd = fs.openSync("/dev/tty", "r"); } catch { ttyFd = null; }
   }
 
-  const profile = profiles[0];
-  console.log(chalk.dim(`  Using AWS profile: ${profile.name}`));
-  console.log(chalk.cyan(`  ▶ aws sso login --profile ${profile.name}`));
-
-  // Open /dev/tty directly so SSO login gets a real terminal even when
-  // the parent process has piped stdio (e.g. agent → runShellCommand → fops doctor)
-  let ttyFd;
-  try { ttyFd = fs.openSync("/dev/tty", "r"); } catch { ttyFd = null; }
-
-  const { exitCode } = await execa("aws", ["sso", "login", "--profile", profile.name], {
+  const result = await execa("aws", ["sso", "login", "--profile", profileName], {
     stdio: [ttyFd ?? "inherit", "inherit", "inherit"],
     reject: false,
     timeout: 120_000,
   });
 
   if (ttyFd !== null) fs.closeSync(ttyFd);
+  return result;
+}
 
-  if (exitCode !== 0) {
-    // SSO login failed — likely bad config. Remove it and re-run setup.
-    console.log(chalk.yellow("  SSO login failed — re-running setup with new values...\n"));
-    const configPath = path.join(os.homedir(), ".aws", "config");
-    if (fs.existsSync(configPath)) fs.unlinkSync(configPath);
-    await ensureSsoConfig();
+/**
+ * Fix AWS SSO: ensure config exists, detect profile, then login.
+ * Distinguishes timeout/incomplete browser auth from bad config so
+ * the user isn't forced to re-enter values when they just ran out of time.
+ */
+export async function fixAwsSso(ctx = {}) {
+  const exec = ctx.exec || execa;
+  const home = ctx.home || os.homedir();
+
+  await ensureSsoConfig();
 
-    const retryProfiles = detectAwsSsoProfiles();
-    if (retryProfiles.length === 0) {
+  const MAX_ATTEMPTS = 3;
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const profiles = detectAwsSsoProfiles();
+    if (profiles.length === 0) {
       throw new Error("No SSO profiles found after config — check ~/.aws/config");
     }
 
-    const retryProfile = retryProfiles[0];
-    console.log(chalk.cyan(`  ▶ aws sso login --profile ${retryProfile.name}`));
-
-    let retryTtyFd;
-    try { retryTtyFd = fs.openSync("/dev/tty", "r"); } catch { retryTtyFd = null; }
+    const profile = profiles[0];
+    console.log(chalk.dim(`  Using AWS profile: ${profile.name}`));
+    console.log(chalk.cyan(`  ▶ aws sso login --profile ${profile.name}`));
 
-    const { exitCode: retryCode } = await execa("aws", ["sso", "login", "--profile", retryProfile.name], {
-      stdio: [retryTtyFd ?? "inherit", "inherit", "inherit"],
+    const result = await exec("aws", ["sso", "login", "--profile", profile.name], {
+      stdio: "inherit",
       reject: false,
       timeout: 120_000,
     });
 
-    if (retryTtyFd !== null) fs.closeSync(retryTtyFd);
+    if (result.exitCode === 0) return;
+
+    if (result.timedOut) {
+      console.log(chalk.yellow("\n  SSO login timed out — browser auth was not completed in time."));
+    } else {
+      console.log(chalk.yellow("\n  SSO login did not complete."));
+    }
+
+    const { action } = await (await getInquirer()).prompt([{
+      type: "list",
+      name: "action",
+      message: "What would you like to do?",
+      choices: [
+        { name: "Retry login (same settings)", value: "retry" },
+        { name: "Reconfigure SSO (re-enter values)", value: "reconfig" },
+        { name: "Abort", value: "abort" },
+      ],
+    }]);
+
+    if (action === "abort") {
+      throw new Error("SSO login aborted by user");
+    }
 
-    if (retryCode !== 0) {
-      throw new Error("SSO login failed. Check your SSO start URL and region in ~/.aws/config");
+    if (action === "reconfig") {
+      const configPath = path.join(home, ".aws", "config");
+      if (fs.existsSync(configPath)) fs.unlinkSync(configPath);
+      await ensureSsoConfig();
     }
+    // "retry" loops again with the same config
   }
+
+  throw new Error("SSO login failed after multiple attempts. Check your SSO start URL and region in ~/.aws/config");
 }
 
 /**
  * Fix ECR: ensure SSO session is valid, then docker login to ECR.
  */
-export async function fixEcr(ecrInfo) {
+export async function fixEcr(ecrInfo, ctx = {}) {
+  const exec = ctx.exec || execa;
+
   const profiles = detectAwsSsoProfiles();
   // Pick the profile whose region matches ECR, or fall back to first
   const profile = profiles.find((p) => p.region === ecrInfo.region) || profiles[0];
   const profileArgs = profile ? ["--profile", profile.name] : [];
 
   // First make sure SSO works
-  const { stdout } = await execa("aws", ["sts", "get-caller-identity", "--output", "json", ...profileArgs], {
+  const { stdout } = await exec("aws", ["sts", "get-caller-identity", "--output", "json", ...profileArgs], {
     reject: false, timeout: 10000,
   });
   if (!stdout || !stdout.includes("Account")) {
-    await fixAwsSso();
+    await fixAwsSso(ctx);
   }
 
   // Now do ECR docker login
   const ecrUrl = `${ecrInfo.accountId}.dkr.ecr.${ecrInfo.region}.amazonaws.com`;
   console.log(chalk.cyan(`  ▶ ECR docker login → ${ecrUrl}`));
-  const { stdout: password } = await execa("aws", [
+  const { stdout: password } = await exec("aws", [
     "ecr", "get-login-password", "--region", ecrInfo.region, ...profileArgs,
   ], { reject: false, timeout: 15000 });
 

package/src/setup/setup.js

@@ -3,9 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
 import { execa } from "execa";
-import inquirer from "inquirer";
 import { make } from "../shell.js";
 import { readFopsConfig, saveFopsConfig, promptAwsSsoConfig, detectEcrRegistry, checkEcrRepos } from "./aws.js";
+import { getInquirer } from "../lazy.js";
 
 // TODO: change back to "main" once stack/api is merged
 export const CLONE_BRANCH = "stack/api";
@@ -70,7 +70,7 @@ export function runSetup(dir, opts = {}) {
         // Check if docker-compose references ECR to auto-detect some values
         const ecrInfo = detectEcrRegistry(dir);
 
-        const { setupAws } = await inquirer.prompt([{
+        const { setupAws } = await (await getInquirer()).prompt([{
           type: "confirm",
           name: "setupAws",
           message: ecrInfo

package/src/setup/wizard.js

@@ -3,12 +3,12 @@ import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
 import { execa } from "execa";
-import inquirer from "inquirer";
 import { isFoundationRoot, findComposeRootUp } from "../project.js";
 import { discoverPlugins } from "../plugins/discovery.js";
 import { validateManifest } from "../plugins/manifest.js";
 import { runSetup, CLONE_BRANCH } from "./setup.js";
-import { confirm } from "../ui/index.js";
+import { confirm, selectOption } from "../ui/index.js";
+import { getInquirer } from "../lazy.js";
 
 /**
  * Ensure Homebrew is available (macOS). Installs if missing.
@@ -76,7 +76,7 @@ export async function runInitWizard() {
   } else {
     const foundUp = findComposeRootUp(cwd);
     if (foundUp && foundUp !== cwd) {
-      const { useFound } = await inquirer.prompt([
+      const { useFound } = await (await getInquirer()).prompt([
         { type: "confirm", name: "useFound", message: `Found Foundation project at:\n  ${foundUp}\n  Use it instead of the current directory?`, default: false },
       ]);
       if (useFound) projectRoot = foundUp;
@@ -130,24 +130,9 @@ export async function runInitWizard() {
         hasAws = await installTool("AWS CLI", { brew: "awscli", winget: "Amazon.AWSCLI" });
       }
 
-      // 1Password desktop app (optional — needed for CLI integration)
-      const has1PwdApp = process.platform === "darwin"
-        ? fs.existsSync("/Applications/1Password.app")
-        : process.platform === "win32"
-          ? fs.existsSync(path.join(process.env.LOCALAPPDATA || "", "1Password", "app", "8", "1Password.exe"))
-          : false;
-      if (has1PwdApp) console.log(chalk.green("  ✓ 1Password"));
-      else {
-        console.log(chalk.yellow("  ⚠ 1Password") + chalk.dim(" — desktop app needed for CLI integration"));
-        await installTool("1Password", { brewCask: "1password", winget: "AgileBits.1Password" });
-      }
-
-      // 1Password CLI (optional)
+      // 1Password (optional — status only, no install prompt)
       if (hasOp) console.log(chalk.green("  ✓ 1Password CLI"));
-      else {
-        console.log(chalk.yellow("  ⚠ 1Password CLI") + chalk.dim(" — needed for secret sync"));
-        hasOp = await installTool("1Password CLI", { brewCask: "1password-cli", winget: "AgileBits.1Password.CLI" });
-      }
+      else console.log(chalk.yellow("  ⚠ 1Password CLI") + chalk.dim(" — optional, run: op signin"));
 
       // GitHub credentials
       const netrcPath = path.join(os.homedir(), ".netrc");
@@ -185,19 +170,18 @@ export async function runInitWizard() {
         console.log(chalk.red("  Required tools are still missing. Install them and run fops init again.\n"));
         process.exit(1);
       }
-      const choices = [
-        { name: "Clone foundation-compose into this directory", value: "clone" },
-        { name: "Enter path to an existing foundation-compose directory", value: "path" },
-        { name: "Cancel", value: "cancel" },
-      ];
-      const { action } = await inquirer.prompt([{ type: "list", name: "action", message: "No Foundation project found. What do you want to do?", choices }]);
-      if (action === "cancel") process.exit(0);
+      const action = await selectOption("No Foundation project found. What do you want to do?", [
+        { label: "Clone foundation-compose into this directory", value: "clone" },
+        { label: "Enter path to an existing foundation-compose directory", value: "path" },
+        { label: "Cancel", value: "cancel" },
+      ]);
+      if (!action || action === "cancel") process.exit(0);
       if (action === "clone") {
-        const { repoUrl } = await inquirer.prompt([
+        const { repoUrl } = await (await getInquirer()).prompt([
           { type: "input", name: "repoUrl", message: "Repository URL:", default: "https://github.com/meshxdata/foundation-compose.git", validate: (v) => (v?.trim() ? true : "Repository URL is required.") },
         ]);
         const repoName = repoUrl.trim().replace(/\.git$/, "").split("/").pop() || "foundation-compose";
-        const { targetDir } = await inquirer.prompt([
+        const { targetDir } = await (await getInquirer()).prompt([
           { type: "input", name: "targetDir", message: "Clone into:", default: path.join(cwd, repoName) },
         ]);
         const resolved = path.resolve(targetDir.trim());
@@ -238,7 +222,7 @@ export async function runInitWizard() {
         }
       }
       if (action === "path") {
-        const { dir } = await inquirer.prompt([
+        const { dir } = await (await getInquirer()).prompt([
           {
             type: "input", name: "dir", message: "Path to foundation-compose directory:",
             validate: (value) => {
@@ -253,7 +237,7 @@ export async function runInitWizard() {
       }
     }
   }
-  const { submodules, env, download } = await inquirer.prompt([
+  const { submodules, env, download } = await (await getInquirer()).prompt([
     { type: "confirm", name: "submodules", message: "Initialize and update git submodules?", default: true },
     { type: "confirm", name: "env", message: "Create .env from .env.example (if missing)?", default: true },
     { type: "confirm", name: "download", message: "Download container images now (make download)?", default: false },
@@ -292,7 +276,7 @@ export async function runInitWizard() {
       };
     });
 
-    const { enabledPlugins } = await inquirer.prompt([{
+    const { enabledPlugins } = await (await getInquirer()).prompt([{
       type: "checkbox",
       name: "enabledPlugins",
       message: "Plugins:",

package/src/shell.js

@@ -1,9 +1,15 @@
-import { execa } from "execa";
+let _execa;
+async function lazyExeca() {
+  if (!_execa) _execa = (await import("execa")).execa;
+  return _execa;
+}
 
 export async function make(root, target, args = []) {
+  const execa = await lazyExeca();
   return execa("make", [target, ...args], { cwd: root, stdio: "inherit", reject: false });
 }
 
 export async function dockerCompose(root, args) {
+  const execa = await lazyExeca();
   return execa("docker", ["compose", ...args], { cwd: root, stdio: "inherit", reject: false });
 }

package/src/ui/confirm.js

@@ -76,7 +76,16 @@ export async function selectOption(message, options) {
       resolved = true;
       clear();
       unmount();
-      setTimeout(() => resolve(selected ? selected.value : null), 50);
+      // Fix for Node 24+: restore stdin state after ink unmounts
+      // ink leaves stdin paused/in raw mode which breaks inquirer
+      setTimeout(() => {
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+          process.stdin.resume();
+          process.stdin.ref();
+        }
+        resolve(selected ? selected.value : null);
+      }, 100);
     };
     const { unmount, clear } = render(
       h(SelectPrompt, { message, options: normalized, onResult })

package/src/wsl.js

@@ -0,0 +1,82 @@
+import { execa } from "execa";
+
+/**
+ * Run a command inside the default WSL distro.
+ */
+export async function wslExec(cmd, args = [], opts = {}) {
+  const { input, timeout, reject, stdio } = opts;
+  return execa("wsl", ["-e", cmd, ...args], { input, timeout, reject, stdio });
+}
+
+let _cachedHome = null;
+
+/**
+ * Get the WSL user's home directory (cached after first call).
+ */
+export async function wslHomedir() {
+  if (_cachedHome) return _cachedHome;
+  const { stdout } = await execa("wsl", ["-e", "sh", "-c", "echo $HOME"], {
+    timeout: 10000,
+  });
+  _cachedHome = stdout.trim();
+  return _cachedHome;
+}
+
+/**
+ * Reset the cached WSL home directory (for testing).
+ */
+export function _resetHomedirCache() {
+  _cachedHome = null;
+}
+
+/**
+ * Check whether a file exists inside WSL.
+ */
+export async function wslFileExists(filepath) {
+  try {
+    const { exitCode } = await execa("wsl", ["-e", "test", "-f", filepath], {
+      reject: false,
+      timeout: 5000,
+    });
+    return exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read file content from inside WSL.
+ */
+export async function wslReadFile(filepath) {
+  const { stdout } = await execa("wsl", ["-e", "cat", filepath], {
+    timeout: 5000,
+  });
+  return stdout;
+}
+
+/**
+ * Write content to a file inside WSL.
+ */
+export async function wslWriteFile(filepath, content) {
+  await execa("wsl", ["-e", "tee", filepath], {
+    input: content,
+    timeout: 5000,
+    stdout: "ignore",
+  });
+}
+
+/**
+ * Get the version string for a command inside WSL.
+ * Returns the first line of output, or null if the command fails.
+ */
+export async function wslCmdVersion(cmd, args = ["--version"]) {
+  try {
+    const { stdout } = await execa("wsl", ["-e", cmd, ...args], {
+      reject: false,
+      timeout: 10000,
+    });
+    return stdout?.split("\n")[0]?.trim() || null;
+  } catch {
+    return null;
+  }
+}