@music-league-eras/local-runner 0.1.0 → 0.1.1

package/README.md

@@ -6,7 +6,7 @@ extracted `manifest.json` to the Music League Eras API using your short-lived `s
 ## Prerequisites (macOS MVP)
 
 - Node.js `>=18.17`
-- Python `>=3.11` available as `python3`
+- Python `>=3.11` installed (runner will try `python3.12`, `python3.11`, then `python3`)
 
 On first run, Playwright may download Chromium (network required).
 
@@ -67,5 +67,6 @@ By default, the runner stores its Python virtualenv under:
 Override with:
 
 - `ML_ERAS_LOCAL_RUNNER_HOME=/some/dir`
+- `ML_ERAS_PYTHON=python3.11` (or an absolute path to a Python 3.11+ executable)
 
 To reset the runner environment, delete that folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@music-league-eras/local-runner",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Music League Eras local runner (npx wrapper around the Python scraper runner).",
   "type": "module",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
     "node": ">=18.17.0"
   },
   "bin": {
-    "ml-eras-local-runner": "./bin/ml-eras-local-runner.js"
+    "ml-eras-local-runner": "bin/ml-eras-local-runner.js"
   },
   "files": [
     "bin/",
@@ -25,4 +25,3 @@
     "access": "public"
   }
 }
-

package/src/python/bootstrap.js

@@ -23,16 +23,47 @@ function _spawn(spawnSync, file, args, opts) {
   return result;
 }
 
-function _pythonCandidates(platform = process.platform) {
+function _pushCandidate(list, candidate) {
+  if (!candidate?.file) return;
+  const key = `${candidate.file}::${(candidate.prefixArgs || []).join(" ")}`;
+  if (list.some((c) => `${c.file}::${(c.prefixArgs || []).join(" ")}` === key)) return;
+  list.push(candidate);
+}
+
+function _pythonCandidates({ platform = process.platform, env = process.env } = {}) {
+  const candidates = [];
+  const override = env?.ML_ERAS_PYTHON;
+  if (override && override.trim()) {
+    _pushCandidate(candidates, { file: override.trim(), prefixArgs: [] });
+  }
+
   if (platform === "win32") {
     // Prefer the official Python Launcher (`py -3`) if present.
-    return [
-      { file: "py", prefixArgs: ["-3"] },
-      { file: "python", prefixArgs: [] },
-      { file: "python3", prefixArgs: [] }
-    ];
+    _pushCandidate(candidates, { file: "py", prefixArgs: ["-3"] });
+    _pushCandidate(candidates, { file: "python", prefixArgs: [] });
+    _pushCandidate(candidates, { file: "python3", prefixArgs: [] });
+    return candidates;
   }
-  return [{ file: "python3", prefixArgs: [] }, { file: "python", prefixArgs: [] }];
+
+  // Prefer explicitly versioned executables first, since macOS may have an older system `python3`.
+  _pushCandidate(candidates, { file: "python3.12", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "python3.11", prefixArgs: [] });
+
+  // Common Homebrew locations (arm64 + intel).
+  _pushCandidate(candidates, { file: "/opt/homebrew/bin/python3.12", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/opt/homebrew/bin/python3.11", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/usr/local/bin/python3.12", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/usr/local/bin/python3.11", prefixArgs: [] });
+
+  // Keg-only Homebrew formula locations (no PATH changes needed).
+  _pushCandidate(candidates, { file: "/opt/homebrew/opt/python@3.12/bin/python3.12", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/opt/homebrew/opt/python@3.11/bin/python3.11", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/usr/local/opt/python@3.12/bin/python3.12", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "/usr/local/opt/python@3.11/bin/python3.11", prefixArgs: [] });
+
+  _pushCandidate(candidates, { file: "python3", prefixArgs: [] });
+  _pushCandidate(candidates, { file: "python", prefixArgs: [] });
+  return candidates;
 }
 
 function _pythonNotFoundMessage(platform = process.platform) {
@@ -43,37 +74,71 @@ function _pythonNotFoundMessage(platform = process.platform) {
       "then re-run: `npx @music-league-eras/local-runner@latest bootstrap`."
     ].join(" ");
   }
-  return "python3 not found. Install Python 3.11+ (e.g. `brew install python@3.11`).";
+  return [
+    "python not found.",
+    "Install Python 3.11+ (e.g. `brew install python@3.11`),",
+    "or set ML_ERAS_PYTHON=/path/to/python3.11."
+  ].join(" ");
 }
 
-export function ensurePythonAvailable({ spawnSync = nodeSpawnSync, platform = process.platform } = {}) {
+function _parsePythonVersion(text) {
+  const trimmed = String(text || "").trim();
+  const parts = trimmed.split(".").map((p) => Number(p));
+  if (parts.length < 2 || !Number.isFinite(parts[0]) || !Number.isFinite(parts[1])) return null;
+  return { major: parts[0], minor: parts[1], patch: Number.isFinite(parts[2]) ? parts[2] : null, raw: trimmed };
+}
+
+function _isAtLeast({ major, minor }, requiredMajor, requiredMinor) {
+  if (major > requiredMajor) return true;
+  if (major < requiredMajor) return false;
+  return minor >= requiredMinor;
+}
+
+export function ensurePythonAvailable({
+  spawnSync = nodeSpawnSync,
+  platform = process.platform,
+  env = process.env
+} = {}) {
   const versionSnippet = "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}')";
-  const candidates = _pythonCandidates(platform);
-  let chosen = null;
-  let versionText = null;
+  const candidates = _pythonCandidates({ platform, env });
+  let bestFound = null;
+  let bestVersion = null;
 
   for (const c of candidates) {
-    const result = _spawn(spawnSync, c.file, [...c.prefixArgs, "-c", versionSnippet], { encoding: "utf-8" });
-    if (result.status === 0) {
-      chosen = c;
-      versionText = String(result.stdout || "").trim();
-      break;
+    let result;
+    try {
+      result = _spawn(spawnSync, c.file, [...c.prefixArgs, "-c", versionSnippet], { encoding: "utf-8" });
+    } catch {
+      continue;
+    }
+    if (result.status !== 0) continue;
+
+    const parsed = _parsePythonVersion(result.stdout);
+    if (!parsed) continue;
+
+    // Track the best version found for a more helpful error message.
+    if (!bestVersion || _isAtLeast(parsed, bestVersion.major, bestVersion.minor)) {
+      bestFound = c;
+      bestVersion = parsed;
+    }
+
+    if (_isAtLeast(parsed, 3, 11)) {
+      return { ok: true, version: parsed.raw, python: c };
     }
   }
 
-  if (!chosen) {
+  if (!bestFound) {
     return { ok: false, error: _pythonNotFoundMessage(platform) };
   }
-  const text = String(versionText || "").trim();
-  const parts = text.split(".").map((p) => Number(p));
-  if (parts.length < 2 || !Number.isFinite(parts[0]) || !Number.isFinite(parts[1])) {
-    return { ok: false, error: `Unable to parse python3 version: ${text}` };
-  }
-  const [major, minor] = parts;
-  if (major < 3 || (major === 3 && minor < 11)) {
-    return { ok: false, error: `python3 >= 3.11 required (found ${text}).` };
-  }
-  return { ok: true, version: text, python: chosen };
+
+  return {
+    ok: false,
+    error: [
+      `python >= 3.11 required (found ${bestVersion.raw} via ${bestFound.file}).`,
+      "If you installed Python 3.11+ already, try running `python3.11 --version` and re-running the bootstrap,",
+      "or set ML_ERAS_PYTHON=python3.11."
+    ].join(" ")
+  };
 }
 
 export function bootstrapPythonRunner({
@@ -90,7 +155,7 @@ export function bootstrapPythonRunner({
     log.error(pythonCheck.error);
     return { ok: false, exitCode: 2 };
   }
-  log.info(`Using python3 ${pythonCheck.version}`);
+  log.info(`Using python ${pythonCheck.version} (${pythonCheck.python.file})`);
 
   const venvDir = platform === "win32" ? path.win32.join(runnerHome, "venv") : path.join(runnerHome, "venv");
   const venvPython = resolveVenvPython(runnerHome, platform);

package/vendor/python/app/local_runner_cli.py

@@ -7,6 +7,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from .local_sync_runner import run_local_sync
+from .sync_token import resolve_sync_token
 
 
 def _env_bool(key: str, default: bool) -> bool:
@@ -49,7 +50,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     local_sync_parser.add_argument("--api-base-url", required=True, help="API base URL (e.g. http://localhost:8000)")
     local_sync_parser.add_argument("--sync-session-id", required=True, help="Local sync session id")
-    local_sync_parser.add_argument("--sync-token", required=True, help="Local sync token (secret)")
+    local_sync_parser.add_argument(
+        "--sync-token",
+        required=False,
+        help="Local sync token (secret). If omitted, reads ML_ERAS_SYNC_TOKEN or prompts.",
+    )
     local_sync_parser.add_argument(
         "--music-league-base-url",
         default=_default_music_league_base_url(),
@@ -91,11 +96,12 @@ def main(argv: list[str] | None = None) -> None:
         raise SystemExit(f"Unknown command: {args.command}")
 
     out_dir = args.out_dir or _default_runner_out_dir(args.sync_session_id)
+    sync_token = resolve_sync_token(flag_token=args.sync_token)
     result = asyncio.run(
         run_local_sync(
             api_base_url=args.api_base_url,
             sync_session_id=args.sync_session_id,
-            sync_token=args.sync_token,
+            sync_token=sync_token,
             music_league_base_url=args.music_league_base_url,
             capture_headless=args.capture_headless,
             scrape_headless=args.scrape_headless,
@@ -109,4 +115,3 @@ def main(argv: list[str] | None = None) -> None:
 
 if __name__ == "__main__":
     main()
-