@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/command-contract.js

@@ -0,0 +1,462 @@
+const bool = () => ({ kind: "boolean" });
+const value = (choices) => ({ kind: "value", ...choices ? { choices } : {} });
+const optionalValue = (choices) => ({ kind: "optional-value", ...choices ? { choices } : {} });
+const options = (...groups) => Object.assign({}, ...groups);
+const HELP = { "--help": bool(), "-h": bool() };
+const JSON = { "--json": bool() };
+const JSON_STREAM = { "--json-stream": bool() };
+const TARGET = { "--target": value() };
+const ADAPTER = { "--adapter": value(["mobile", "extension", "core"]) };
+const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
+const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "ios", "android"]) };
+const DEVICE = { "--device": value() };
+const RUNTIME_PORTS = {
+  "--cdp-port": value(),
+  "--watcher-port": value(),
+  "--metro-port": value(),
+  "--runtime-dir": value()
+};
+const RECIPE_RUNTIME = {
+  "--artifacts-dir": value(),
+  "--action-manifest": value(),
+  "--library": value(),
+  "--heal": value(["off", "infra-only", "auto"]),
+  "--slot": value(),
+  "--validation-runtime-dir": value(),
+  "--launch-existing-dist": bool(),
+  "--record-video": optionalValue(["full-run", "off"]),
+  "--source-trust": value(["trusted", "untrusted", "unknown"]),
+  "--source-kind": value(["bundled", "operator", "task", "recipe-file", "library", "custom-adapter"]),
+  "--source-name": value(),
+  "--source-digest": value(),
+  "--approve-plan": value()
+};
+const RUNWAY = {
+  "--branch": value(),
+  "--default-branch": value(),
+  "--run": value(),
+  "--cache-root": value(),
+  "--simulator": value(),
+  "--runtime": value(),
+  "--device-type": value(),
+  "--slot": value(),
+  "--watcher-port": value(),
+  "--runtime-dir": value(),
+  "--force": bool(),
+  "--resolve-only": bool()
+};
+const REMOVED_OPTION_REPLACEMENTS = {
+  "--project-root": "--target",
+  "--record": "--record-video"
+};
+const PUBLIC_COMMAND_CONTRACTS = {
+  status: {
+    aliases: ["health", "home"],
+    options: options(HELP, JSON, TARGET, DEVICE, {
+      "--fast": bool(),
+      "--all-devices": bool()
+    })
+  },
+  checklist: {
+    usage: "mm-harness checklist mark <task-dir> <step> [options]",
+    options: options(HELP, {
+      "--mark-last": bool(),
+      "--already-fixed": bool(),
+      "--no-self-review": bool(),
+      "--skip-learnings": bool(),
+      "--skip-checklist": bool(),
+      "--reason": value(),
+      "--checklist": value(),
+      "--signal": value()
+    }),
+    positionals: [
+      { label: "action", choices: ["mark"] },
+      { label: "task-dir" },
+      {
+        label: "step",
+        validate: (step) => {
+          if (["start", "complete", "no-change", "blocked"].includes(step)) return true;
+          const numeric = Number(step);
+          return Number.isInteger(numeric) && numeric >= 1;
+        },
+        validDescription: "start|complete|no-change|blocked|a positive numeric step"
+      }
+    ],
+    minimumPositionals: 3
+  },
+  actions: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--action": value(),
+      "--categories": bool(),
+      "--category": value(),
+      "--action-manifest": value(),
+      "--library": value(),
+      "--raw": bool()
+    }),
+    positionals: [{ label: "query" }],
+    noPositionalsWith: ["--action", "--categories", "--raw"]
+  },
+  stop: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--port": value(),
+      "--watcher-port": value()
+    })
+  },
+  call: {
+    options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+      "--list": bool(),
+      "--arg": value()
+    }),
+    positionals: [{ label: "action" }],
+    minimumPositionals: 0,
+    requiredUnless: ["--list"],
+    noPositionalsWith: ["--list"],
+    leadingPositionals: 1,
+    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
+  },
+  run: {
+    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+      "--list": bool(),
+      "--plan": bool(),
+      "--describe": bool()
+    }),
+    positionals: [{ label: "recipe" }],
+    minimumPositionals: 1,
+    requiredUnless: ["--list"],
+    noPositionalsWith: ["--list"],
+    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
+  },
+  last: {
+    options: options(HELP, JSON, TARGET, {
+      "--runtime-dir": value()
+    })
+  },
+  doctor: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+      "--fix": bool(),
+      "--expect-live": bool(),
+      "--print-ready": bool(),
+      "--all-devices": bool(),
+      "--action-manifest": value(),
+      "--port": value()
+    })
+  },
+  check: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--base": value(),
+      "--profile": value(["fast", "full"]),
+      "--fix": bool(),
+      "--artifacts-dir": value()
+    }),
+    positionals: [{ label: "action", choices: ["diff"] }],
+    minimumPositionals: 1
+  },
+  "recipe-quality": {
+    options: options(HELP, JSON, {
+      "--input": value(),
+      "--output": value()
+    }),
+    positionals: [{ label: "action", choices: ["build"] }]
+  },
+  provision: {
+    options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, RUNWAY, {
+      "--platform": value(["ios"]),
+      "--device-platform": value(["ios"])
+    }),
+    positionals: [
+      { label: "source", choices: ["runway", "ios"] },
+      { label: "platform", choices: ["ios"] }
+    ]
+  },
+  install: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNWAY, {
+      "--runway": bool()
+    }),
+    allowPassthrough: true
+  },
+  verify: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, RUNTIME_PORTS),
+    allowPassthrough: true
+  },
+  cleanup: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM),
+    allowPassthrough: true
+  },
+  launch: {
+    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+      "--build": bool(),
+      "--verify": bool(),
+      "--runway": bool(),
+      "--watch": bool(),
+      "--sidepanel": bool(),
+      "--fullscreen": bool(),
+      "--url": value(),
+      "--heal": value(["off", "infra-only", "auto"])
+    }),
+    positionals: [{ label: "platform", choices: ["ios", "android"] }]
+  },
+  logs: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--full": bool(),
+      "--window": bool(),
+      "--events": value(),
+      "--source": value()
+    })
+  },
+  debug: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--worker": bool(),
+      "--dev-menu": bool(),
+      "--no-open": bool()
+    })
+  },
+  update: {
+    options: options(HELP, JSON, { "--check": bool() })
+  },
+  fixtures: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
+      "--from": value(),
+      "--dev": bool(),
+      "--force": bool(),
+      "--fixture": value(),
+      "--out": value(),
+      "--state": value(),
+      "--cdp-port": value(),
+      "--extension-dir": value(),
+      "--extension-id-file": value(),
+      "--action-manifest": value()
+    }),
+    positionals: [{ label: "action", choices: ["init", "sync", "set", "generate", "finalize"] }],
+    minimumPositionals: 0
+  }
+};
+function validatePublicInvocation(argv, examples = {}) {
+  const token = argv[0];
+  if (!token || token === "--help" || token === "-h" || token === "--version" || token === "-v") return null;
+  const resolved = resolveCommand(token);
+  if (!resolved) {
+    const names = publicCommandTokens();
+    const suggestion = closest(token, names);
+    if (token.startsWith("-")) {
+      return {
+        code: "CLI_UNKNOWN_OPTION",
+        command: "mm-harness",
+        message: `unknown top-level option '${token}'. Valid top-level options: --help, --version.`,
+        userAction: actionFor(token, closest(token, ["--help", "--version"]), "mm-harness --help")
+      };
+    }
+    return {
+      code: "CLI_UNKNOWN_COMMAND",
+      command: token,
+      message: `unknown command '${token}'. Valid commands: ${Object.keys(PUBLIC_COMMAND_CONTRACTS).join(", ")}.`,
+      userAction: actionFor(token, suggestion, suggestion ? exampleFor(resolveCommand(suggestion)?.name, examples) : "mm-harness --help")
+    };
+  }
+  const { name, contract } = resolved;
+  const tokens = argv.slice(1);
+  const positionals = [];
+  const seenOptions = /* @__PURE__ */ new Set();
+  const validOptions = Object.keys(contract.options);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const argument = tokens[index] ?? "";
+    if (argument === "--") {
+      if (!contract.allowPassthrough) {
+        return usageFailure("CLI_UNEXPECTED_PASSTHROUGH", name, "this command does not accept `--` passthrough.", contract, examples);
+      }
+      break;
+    }
+    if (!argument.startsWith("-") || argument === "-") {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf("=");
+    const optionName = equals === -1 ? argument : argument.slice(0, equals);
+    const inlineValue = equals === -1 ? void 0 : argument.slice(equals + 1);
+    const spec = contract.options[optionName];
+    if (!spec) {
+      const suggestion = REMOVED_OPTION_REPLACEMENTS[optionName] ?? closest(optionName, validOptions);
+      return {
+        code: "CLI_UNKNOWN_OPTION",
+        command: name,
+        message: `unknown option '${optionName}'.`,
+        userAction: actionFor(optionName, suggestion, exampleFor(name, examples))
+      };
+    }
+    seenOptions.add(optionName);
+    if (spec.kind === "boolean") {
+      if (inlineValue !== void 0) {
+        return usageFailure("CLI_INVALID_OPTION_VALUE", name, `${optionName} is a flag and does not take a value.`, contract, examples);
+      }
+      continue;
+    }
+    if (spec.kind === "optional-value" && inlineValue === void 0) continue;
+    const optionValue = inlineValue ?? tokens[index + 1];
+    const nextTokenIsOption = inlineValue === void 0 && (optionValue === "-h" || optionValue === "--" || optionValue?.startsWith("--"));
+    if (optionValue === void 0 || spec.kind === "value" && optionValue === "" || nextTokenIsOption) {
+      return usageFailure("CLI_MISSING_OPTION_VALUE", name, `${optionName} requires a value.`, contract, examples);
+    }
+    if (inlineValue === void 0) index += 1;
+    if (spec.choices && !spec.choices.includes(optionValue)) {
+      const suggestion = closest(optionValue, spec.choices);
+      return {
+        code: "CLI_INVALID_OPTION_VALUE",
+        command: name,
+        message: `${optionName} must be ${formatChoiceList(spec.choices)}; received '${optionValue}'.`,
+        userAction: actionFor(optionValue, suggestion, exampleFor(name, examples))
+      };
+    }
+  }
+  if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
+  if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
+    const missing = contract.positionals?.[0]?.label ?? "argument";
+    return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);
+  }
+  const forbiddingOption = contract.noPositionalsWith?.find((option) => seenOptions.has(option));
+  if (forbiddingOption && positionals.length > 0) {
+    return usageFailure(
+      "CLI_EXCESS_POSITIONAL",
+      name,
+      `${forbiddingOption} does not accept positional '${positionals[0]}'.`,
+      contract,
+      examples
+    );
+  }
+  const minimum = contract.requiredUnless?.some((option) => seenOptions.has(option)) ? 0 : contract.minimumPositionals ?? 0;
+  if (positionals.length < minimum) {
+    const missingSpec = contract.positionals?.[positionals.length];
+    const missing = missingSpec?.label ?? "argument";
+    const valid = missingSpec?.choices?.length ? ` Choose one: ${missingSpec.choices.join("|")}.` : "";
+    const usage = contract.usage ? ` Usage: ${contract.usage}.` : "";
+    return missingPositionalFailure(name, `missing required <${missing}>.${valid}${usage}`, contract, examples);
+  }
+  const fixed = contract.positionals ?? [];
+  for (let index = 0; index < Math.min(positionals.length, fixed.length); index += 1) {
+    const invalid = invalidPositional(positionals[index] ?? "", fixed[index]);
+    if (invalid) return positionalFailure(name, positionals[index] ?? "", fixed[index], contract, examples);
+  }
+  if (positionals.length > fixed.length && !contract.variadic) {
+    const unexpected = positionals[fixed.length] ?? "";
+    return usageFailure("CLI_EXCESS_POSITIONAL", name, `unexpected positional '${unexpected}'; this command accepts ${formatPositionals(contract)}.`, contract, examples);
+  }
+  if (contract.variadic) {
+    for (const positional of positionals.slice(fixed.length)) {
+      if (invalidPositional(positional, contract.variadic)) {
+        return positionalFailure(name, positional, contract.variadic, contract, examples);
+      }
+    }
+  }
+  return null;
+}
+function publicCommandTokens() {
+  const tokens = [];
+  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
+    tokens.push(name, ...contract.aliases ?? []);
+  }
+  return tokens;
+}
+function publicCommandNames() {
+  return Object.keys(PUBLIC_COMMAND_CONTRACTS);
+}
+function resolveCommand(token) {
+  const direct = PUBLIC_COMMAND_CONTRACTS[token];
+  if (direct) return { name: token, contract: direct };
+  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
+    if (contract.aliases?.includes(token)) return { name, contract };
+  }
+  return null;
+}
+function usageFailure(code, command, message, _contract, examples) {
+  return {
+    code,
+    command,
+    message,
+    userAction: `Try: ${exampleFor(command, examples)}. Inspect options: mm-harness ${command} --help`
+  };
+}
+function missingPositionalFailure(command, message, contract, examples) {
+  if (command === "run") {
+    return {
+      code: "CLI_MISSING_POSITIONAL",
+      command,
+      message,
+      userAction: `List recipes: mm-harness run --list
+  Example: ${exampleFor(command, examples)}
+  More: mm-harness run --help`
+    };
+  }
+  if (command === "call") {
+    return {
+      code: "CLI_MISSING_POSITIONAL",
+      command,
+      message,
+      userAction: `List actions: mm-harness call --list
+  Example: ${exampleFor(command, examples)}
+  More: mm-harness call --help`
+    };
+  }
+  return usageFailure("CLI_MISSING_POSITIONAL", command, message, contract, examples);
+}
+function positionalFailure(command, received, spec, _contract, examples) {
+  const valid = spec.validDescription ?? (spec.choices ? spec.choices.join(", ") : spec.pattern || spec.validate ? `a valid <${spec.label}>` : `<${spec.label}>`);
+  const suggestion = spec.choices ? closest(received, spec.choices) : void 0;
+  return {
+    code: "CLI_INVALID_POSITIONAL",
+    command,
+    message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}.`,
+    userAction: actionFor(received, suggestion, exampleFor(command, examples))
+  };
+}
+function invalidPositional(value2, spec) {
+  if (!spec) return true;
+  if (spec.choices && !spec.choices.includes(value2)) return true;
+  if (spec.validate && !spec.validate(value2)) return true;
+  return Boolean(spec.pattern && !spec.pattern.test(value2));
+}
+function formatChoiceList(choices) {
+  if (choices.length === 1) return choices[0] ?? "";
+  if (choices.length === 2) return `${choices[0]} or ${choices[1]}`;
+  return `${choices.slice(0, -1).join(", ")}, or ${choices[choices.length - 1]}`;
+}
+function formatPositionals(contract) {
+  const fixed = (contract.positionals ?? []).map((spec) => `<${spec.label}>`);
+  if (contract.variadic) fixed.push(`[<${contract.variadic.label}> ...]`);
+  return fixed.length > 0 ? fixed.join(" ") : "no positionals";
+}
+function actionFor(received, suggestion, example) {
+  return `${suggestion ? `Did you mean '${suggestion}' instead of '${received}'? ` : ""}Try: ${example}`;
+}
+function exampleFor(command, examples) {
+  return command ? examples[command] ?? `mm-harness ${command} --help` : "mm-harness --help";
+}
+function closest(input, candidates) {
+  if (candidates.length === 0) return void 0;
+  const ranked = candidates.map((candidate) => ({ candidate, distance: levenshtein(input, candidate) })).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate));
+  const best = ranked[0];
+  if (!best) return void 0;
+  const threshold = Math.max(2, Math.floor(Math.max(input.length, best.candidate.length) / 3));
+  return best.distance <= threshold ? best.candidate : void 0;
+}
+function levenshtein(left, right) {
+  let twoBack;
+  let prior = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const substitution = prior[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
+      current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (prior[rightIndex] ?? 0) + 1, substitution);
+      if (twoBack && leftIndex > 1 && rightIndex > 1 && left[leftIndex - 1] === right[rightIndex - 2] && left[leftIndex - 2] === right[rightIndex - 1]) {
+        current[rightIndex] = Math.min(current[rightIndex] ?? 0, (twoBack[rightIndex - 2] ?? 0) + 1);
+      }
+    }
+    twoBack = prior;
+    prior = current;
+  }
+  return prior[right.length] ?? right.length;
+}
+export {
+  PUBLIC_COMMAND_CONTRACTS,
+  closest,
+  publicCommandNames,
+  publicCommandTokens,
+  validatePublicInvocation
+};