@deeeed/metamask-harness 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.5 - 2026-07-04
+
+### Fixed
+- **IMP-24b: shell leaves run even when packed without the exec bit** — `yarn pack` (used by `yarn npm publish`) strips the executable bit off shipped `*.sh` leaves to `644`, even though git stores `100755` and `npm pack` preserves `755`. The 0.3.4 fix (git `100755` + an `npm pack` tarball test) was therefore insufficient: the published `yarn`-packed tarball still shipped `644` leaves and a fresh `npm i -g` hit `EACCES` on the first leaf. `spawnScript` now invokes shell leaves through `bash <leaf>` instead of exec'ing them directly, so the leaf's file mode is irrelevant (node leaves were already interpreter-invoked via `process.execPath`). Env overlays (`FORCE_COLOR`/`RECIPE_RUNTIME_DIR`), arg passing, cwd, JSON envelope, and exit codes are unchanged. New contract test `tests/contract/leaf-644-runs.test.sh` forces the device leaves to mode `644` and drives them through the real `mm-harness` spawn path, asserting they still run — the regression the `npm pack` tarball test could not catch.
+
+### Changed
+- **Publish with `npm publish`, not `yarn npm publish`** — `npm publish` preserves the git `100755` mode on shipped `*.sh` leaves (defense-in-depth on top of the interpreter invocation above). Documented in `AGENTS.md`; git exec bits remain `100755`.
+
+## 0.3.4 - 2026-07-04
+
+### Fixed
+- **IMP-24: published tarball stripped exec bits from shell leaves** — the harness execs `adapters/**/*.sh` leaves directly, but six shipped leaves (`adapters/mobile/lib/metro-listener.sh`, `adapters/shared/activate-repo-node.sh`, `cli-ux.sh`, `harness-path.sh`, `hash-helpers.sh`, `resolve-farmslot-ports.sh`) were committed without the git exec bit (mode `100644`), so npm packed them `644`. A fresh `npm i -g` then hit `EACCES` on the first leaf. All shipped `*.sh` are now stored `100755` in git, so the published tarball packs them executable. Added contract test `tests/contract/packaging-exec-bits.test.sh` — it runs `npm pack` to produce the actual `.tgz`, then asserts via `tar tzvf` that every shipped `*.sh` entry has owner-execute set; fails with the offending path(s) if any is `644`, so this cannot silently regress.
+- **IMP-24: spawn failures are surfaced, not swallowed** — `spawnScript` returned on `result.error` (a leaf that is missing/`ENOENT` or not executable/`EACCES`) before its human-mode stderr forward, so a leaf that could not start produced a silent exit-1 (surfaced upstream as `MOBILE_PREPARE_FAILED`). The `result.error` branch now always writes a teaching diagnostic (`leaf could not start: <leaf> (<errno>)` + a `Next: reinstall mm-harness` hint) to stderr before returning. Covered by `tests/contract/spawn-error-surfaced.test.sh`.
+
 ## 0.3.3 - 2026-07-04
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -56,4 +56,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}

package/src/commands/shared.ts

@@ -11,6 +11,7 @@ import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 
 import { detectAdapter } from '../harness.ts';
+import { resolveLeafInvoke, shellLeafMissing } from '../leaf-invoke.ts';
 import { runnerDir } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 
@@ -107,20 +108,43 @@ export function spawnScript(
   // For node invocations (script === process.execPath) the seam stem is derived
   // from args[0] so each spawned script has its own override key.
   const isNodeScript = script === process.execPath && args.length > 0;
+  // Seam stem: for node invocations derive from args[0] so each script has its
+  // own override key; for shell and other leaves derive from the script basename.
   const stem = isNodeScript
     ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
     : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
   const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
   const bin = override ?? script;
-  const spawnArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
-  const result = spawnSync(bin, spawnArgs, {
+  const directArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
+
+  // Shell leaves (.sh) run through bash so file mode need not be executable.
+  // Bash exits 127 (not a Node spawn error) for a missing file, so pre-check.
+  if (shellLeafMissing(bin)) {
+    const message =
+      `leaf could not start: ${path.basename(bin)} (ENOENT)\n` +
+      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}\n`);
+    return { status: 1, output: message };
+  }
+
+  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
+  const result = spawnSync(invokeBin, spawnArgs, {
     cwd,
     encoding: 'utf8',
     env: env ? { ...process.env, ...env } : process.env,
     maxBuffer: 64 * 1024 * 1024,
   });
   if (result.error) {
-    return { status: 1, output: `script could not start (${path.basename(script)}): ${result.error.message}` };
+    // Spawn failure for non-shell leaves (ENOENT/EACCES) or when bash itself
+    // cannot start. Always emit so a leaf that cannot start is never silent.
+    // For node invocations the leaf name comes from args[0], not process.execPath.
+    const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
+    const code = (result.error as NodeJS.ErrnoException).code ?? 'ESPAWN';
+    const message =
+      `leaf could not start: ${leaf} (${code})\n` +
+      `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}\n`);
+    return { status: 1, output: message };
   }
   const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
   if (!json && output) process.stderr.write(output);

package/src/harness.ts

@@ -2,6 +2,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from './leaf-invoke.ts';
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from './paths.ts';
 import type { MetaMaskRecipeAdapter } from './types.ts';
 import { prepareMobile } from './adapters/mobile/prepare.ts';
@@ -334,7 +335,8 @@ function resolveHarnessDispatch(
     if (adapter === 'extension') {
       return { command: process.execPath, prefixArgs: [resolveEntry(runnerDir, [entry, fallback], 'file')] };
     }
-    return { command: resolveEntry(runnerDir, [entry, fallback], 'exec'), prefixArgs: [] };
+    // Shell leaves are invoked through bash; file existence is the only requirement.
+    return { command: resolveEntry(runnerDir, [entry, fallback], 'file'), prefixArgs: [] };
   }
 
   if (action === 'cleanup') {
@@ -343,7 +345,7 @@ function resolveHarnessDispatch(
     if (adapter === 'extension') {
       return { command: process.execPath, prefixArgs: [resolveEntry(base, [entry, fallback], 'file')] };
     }
-    return { command: resolveEntry(base, [entry, fallback], 'exec'), prefixArgs: [] };
+    return { command: resolveEntry(base, [entry, fallback], 'file'), prefixArgs: [] };
   }
 
   if (adapter === 'core' && action === 'verify') {
@@ -360,16 +362,16 @@ function resolveHarnessDispatch(
     return { command: delegate, prefixArgs: ['doctor', '--adapter', 'core'] };
   }
 
-  // mobile/extension live|verify: prefer the installed helper, else the runner's
-  // own adapters/scripts helper (first executable candidate wins).
+  // mobile/extension live|verify: prefer the installed helper (any mode), else
+  // the runner's own adapters/scripts candidate. Bash invocation makes +x irrelevant.
   const installedScript = path.join(recipeHarnessPath(target, adapter), 'scripts', `${action}.sh`);
-  if (isExecutable(installedScript)) {
+  if (fs.existsSync(installedScript)) {
     return { command: installedScript, prefixArgs: [] };
   }
   const command = resolveEntry(
     runnerDir,
     [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
-    'exec',
+    'file',
   );
   return { command, prefixArgs: [] };
 }
@@ -414,15 +416,32 @@ async function handleMobileLive(
 
   // Verify leaf: --no-auto-start because launch already started the app.
   const installedVerify = path.join(recipeHarnessPath(target, 'mobile'), 'scripts', 'verify.sh');
-  const verifySh = isExecutable(installedVerify)
+  const verifySh = fs.existsSync(installedVerify)
     ? installedVerify
-    : resolveEntry(runnerDir, ['adapters/mobile/verify.sh', 'scripts/mobile/verify.sh'], 'exec');
+    : resolveEntry(runnerDir, ['adapters/mobile/verify.sh', 'scripts/mobile/verify.sh'], 'file');
 
   const verifyArgs = hasArg(forwardArgs, '--no-auto-start')
     ? [...forwardArgs]
     : ['--no-auto-start', ...forwardArgs];
 
-  const result = spawnSync(verifySh, verifyArgs, {
+  if (shellLeafMissing(verifySh)) {
+    const message = missingShellLeafMessage(verifySh);
+    if (json) {
+      console.log(
+        harnessSummary('live', 'mobile', target, 'fail', 1, autoDetected, {
+          code: 'HARNESS_SPAWN_FAILED',
+          message,
+          userAction: failureHint('mobile', 'live'),
+        }),
+      );
+    } else {
+      console.error(`✗ ${message}`);
+    }
+    return 1;
+  }
+
+  const { bin: verifyBin, args: verifySpawnArgs } = resolveLeafInvoke(verifySh, verifyArgs);
+  const result = spawnSync(verifyBin, verifySpawnArgs, {
     stdio: json ? ['inherit', 2, 'inherit'] : 'inherit',
     env: process.env,
   });
@@ -544,7 +563,29 @@ export async function handleHarness(argv: string[]): Promise<number> {
   }
 
   const start = Date.now();
-  const result = spawnSync(dispatch.command, [...dispatch.prefixArgs, ...forwardArgs], {
+
+  // Shell leaves need bash invocation; bash exits 127 (not ENOENT) for missing files.
+  if (shellLeafMissing(dispatch.command)) {
+    const message = missingShellLeafMessage(dispatch.command);
+    if (json) {
+      console.log(
+        harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
+          code: 'HARNESS_SPAWN_FAILED',
+          message,
+          userAction: failureHint(adapter, harnessAction),
+        }),
+      );
+    } else {
+      console.error(`✗ ${message}`);
+    }
+    return 1;
+  }
+
+  const { bin: dispatchBin, args: dispatchArgs } = resolveLeafInvoke(dispatch.command, [
+    ...dispatch.prefixArgs,
+    ...forwardArgs,
+  ]);
+  const result = spawnSync(dispatchBin, dispatchArgs, {
     // Default: stream child output verbatim (byte-identical to the skill path).
     // --json: route child output to our stderr so stdout carries only the summary.
     stdio: json ? ['inherit', 2, 'inherit'] : 'inherit',

package/src/leaf-invoke.ts

@@ -0,0 +1,28 @@
+// Interpreter routing for adapter shell and node leaves.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Returns the interpreter and args for invoking a leaf. Shell leaves (.sh) run
+// through bash so the file mode does not need to be executable. Node leaves
+// are already invoked through process.execPath by their callers and are
+// returned unchanged.
+export function resolveLeafInvoke(command: string, args: string[]): { bin: string; args: string[] } {
+  if (command.endsWith('.sh')) return { bin: 'bash', args: [command, ...args] };
+  return { bin: command, args };
+}
+
+// Teaching diagnostic for a shell leaf that is absent from disk. Bash exits
+// 127 (not a Node spawn error) for a missing file, so callers pre-check and
+// emit this rather than relying on result.error.
+export function missingShellLeafMessage(leafPath: string): string {
+  const leaf = path.basename(leafPath);
+  return (
+    `leaf could not start: ${leaf} (ENOENT)\n` +
+    `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`
+  );
+}
+
+// Returns true when a .sh leaf path does not exist on disk.
+export function shellLeafMissing(leafPath: string): boolean {
+  return leafPath.endsWith('.sh') && !fs.existsSync(leafPath);
+}