@deeeed/metamask-harness 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.6 - 2026-07-04
+
+### Fixed
+- **Install manifest carries target checkout identity (`targetRevision`)** — `adapters/mobile/inject.sh` stamps the target repo's `HEAD` (resolved once, up front, via `git rev-parse --verify HEAD`) and an explicit `installMode` into the mobile install manifest on both install paths (product-owned/metadata-only and overlay). Consumers (the farm recipe hook) can now gate their fast path on manifest identity matching the current checkout instead of manifest existence, closing the stale-manifest hole where a gitignored manifest survives a branch switch to a bridge-less checkout. Install now fails with teaching guidance when the target `HEAD` cannot be resolved (not-a-repo, unborn branch), instead of stamping an unusable `targetRevision`. Contract tests cover the identity stamp on both paths and the unborn-HEAD refusal.
+
+## 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

package/adapters/mobile/inject.sh

@@ -60,6 +60,19 @@ if ! command -v harness_root >/dev/null 2>&1; then
   exit 1
 fi
 TARGET="$(cd "$TARGET" && pwd)"
+# The install stamps this checkout's HEAD into the manifest as its identity. If we
+# cannot resolve it (not a git repo, unborn HEAD, git unavailable) we must not
+# install with an unidentifiable target: a downstream consumer could not tell a
+# stale manifest (left behind by a previous branch/tag) from a current one. Fail
+# loud with escape guidance rather than stamping an "unknown" revision.
+# --verify fails cleanly (no stdout) on an unborn HEAD, where plain `rev-parse
+# HEAD` would echo the literal "HEAD" and slip past the emptiness check below.
+TARGET_REV="$(git -C "$TARGET" rev-parse --verify HEAD 2>/dev/null || true)"
+if [ -z "$TARGET_REV" ]; then
+  echo "Refusing mobile recipe harness install: cannot resolve the target checkout HEAD in $TARGET." >&2
+  echo "Next: ensure the target is a git checkout with at least one commit (git -C \"$TARGET\" rev-parse HEAD succeeds), then retry the install." >&2
+  exit 1
+fi
 METAMASK_RUNNER_DIR="$RUNNER_DIR"
 METAMASK_RUNNER_SOURCE_KIND="runner-self"
 METAMASK_RUNNER_REVISION="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
@@ -272,10 +285,11 @@ if [ "$FORCE_OVERLAY" = false ] && has_product_owned_mobile_harness; then
   fi
   node -e '
     const fs = require("fs");
-    const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, scriptDir, manifestPath, harnessRoot, harnessRel, cleanupCommand] = process.argv.slice(1);
+    const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, scriptDir, manifestPath, harnessRoot, harnessRel, cleanupCommand, targetRevision] = process.argv.slice(1);
     const m = {
       adapter: "mobile",
       installMode: "product-owned",
+      targetRevision,
       installedAt: new Date().toISOString(),
       source: {
         runnerOwnerDir,
@@ -308,7 +322,7 @@ if [ "$FORCE_OVERLAY" = false ] && has_product_owned_mobile_harness; then
       note: "This checkout already contains the Mobile in-app bridge. Runner install only writes recipe-harness metadata and must not overwrite tracked in-app bridge files."
     };
     fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
-  ' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND"
+  ' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND" "$TARGET_REV"
   echo "Installed mobile recipe harness metadata only (in-app bridge detected): $HARNESS_DIR/manifest.json"
   exit 0
 fi
@@ -637,9 +651,11 @@ SOURCE_REV="$(git -C "$RUNNER_DIR" rev-parse HEAD 2>/dev/null || echo unknown)"
 CLEANUP_COMMAND="RECIPE_HARNESS_ROOT=$HARNESS_ROOT $(printf '%q' "$CLEANUP_SH") --target $(printf '%q' "$TARGET")"
 node -e '
   const fs = require("fs");
-  const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, backupDir, scriptDir, manifestPath, mobileAgenticSource, harnessRoot, harnessRel, cleanupCommand] = process.argv.slice(1);
+  const [runnerOwnerDir, runnerOwnerRevision, runnerDir, runnerRevision, runnerSourceKind, adapterRuntime, target, backupDir, scriptDir, manifestPath, mobileAgenticSource, harnessRoot, harnessRel, cleanupCommand, targetRevision] = process.argv.slice(1);
   const m = {
     adapter: "mobile",
+    installMode: "overlay",
+    targetRevision,
     installedAt: new Date().toISOString(),
     source: {
       runnerOwnerDir,
@@ -669,7 +685,7 @@ node -e '
     ]
   };
   fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
-' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$BACKUP_DIR" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "${MOBILE_AGENTIC_SOURCE:-}" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND"
+' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$BACKUP_DIR" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "${MOBILE_AGENTIC_SOURCE:-}" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND" "$TARGET_REV"
 
 ENSURE_DEPS="$SCRIPT_DIR/../shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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,23 +108,36 @@ 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) {
-    // A spawn failure (EACCES on a non-executable leaf, ENOENT on a missing one)
-    // is otherwise silent because the human-mode stderr forward below is skipped
-    // on early return. Always emit the diagnostic so a leaf that can't start is
-    // never a mystery exit-1. For node invocations the leaf is args[0], not node.
+    // 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 =

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);
+}