mcli-framework 8.0.62__tar.gz → 8.0.65__tar.gz

{mcli_framework-8.0.62/src/mcli_framework.egg-info → mcli_framework-8.0.65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcli-framework
-Version: 8.0.62
+Version: 8.0.65
 Summary: Portable workflow framework - transform any script into a versioned, schedulable command. Store in ~/.mcli/workflows/, version with lockfile, run as daemon or cron job.
 Author-email: Luis Fernandez de la Vara <luis@lefv.io>
 Maintainer-email: Luis Fernandez de la Vara <luis@lefv.io>

{mcli_framework-8.0.62 → mcli_framework-8.0.65}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcli-framework"
-version = "8.0.62"
+version = "8.0.65"
 description = "Portable workflow framework - transform any script into a versioned, schedulable command. Store in ~/.mcli/workflows/, version with lockfile, run as daemon or cron job."
 readme = "README.md"
  requires-python = ">=3.10"

mcli_framework-8.0.65/src/mcli/workflow/ci/act_lock.py

@@ -0,0 +1,171 @@
+"""Machine-wide advisory lock that serialises `mcli ci preflight` act runs.
+
+Every repo that ran `mcli ci install-hook` fires `mcli ci preflight` from its
+pre-push hook. With several agents (or several terminals) pushing at once, that
+starts several `act` runs at once, and each one drives the same container
+runtime — one podman/docker VM with a fixed CPU/memory budget shared with
+everything else on the host. Concurrent runs starve it; the observed symptom was
+an Android emulator ANR'ing under test while act runs churned.
+
+This module gives the act path a single machine-wide gate:
+
+* Exclusion is `fcntl.flock(LOCK_EX)` on a lockfile in the mcli home. flock is
+  owned by the open file description, so the kernel drops it when the holder
+  exits — normally, by exception, or by SIGKILL. There is nothing to clean up
+  and nothing to go stale.
+* The PID/repo written into the lockfile is *informational only*: it makes the
+  "waiting for…" message useful. Correctness never reads it.
+* Waiting is bounded. On expiry the caller is told it did not get the lock and
+  decides what to do — a gate that can block a push forever is worse than one
+  that occasionally cannot validate.
+"""
+
+from __future__ import annotations
+
+import errno
+import fcntl
+import os
+import sys
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Callable
+
+from mcli.lib.paths import get_mcli_home
+
+# Ten minutes: long enough for a slow act run ahead of us to finish, short
+# enough that a wedged machine never holds a push hostage for a workday.
+DEFAULT_LOCK_TIMEOUT_SECONDS = 600.0
+
+LOCK_TIMEOUT_ENV = "MCLI_CI_LOCK_TIMEOUT"
+LOCK_PATH_ENV = "MCLI_CI_LOCK_PATH"
+
+_LOCK_DIR_NAME = "locks"
+_LOCK_FILE_NAME = "ci-act.lock"
+
+# Retry cadence while waiting. flock's blocking mode cannot be bounded
+# portably, so poll the non-blocking variant instead.
+_POLL_INTERVAL_SECONDS = 0.5
+
+_UNKNOWN_HOLDER = "holder unknown"
+
+
+def lock_path() -> Path:
+    """The one lockfile every repo on this machine contends for.
+
+    Deliberately NOT per-repo: the resource being protected is the host's
+    container runtime, which every repo shares.
+    """
+    override = os.getenv(LOCK_PATH_ENV)
+    if override:
+        return Path(override)
+    return get_mcli_home() / _LOCK_DIR_NAME / _LOCK_FILE_NAME
+
+
+def resolve_timeout(timeout: float | None = None) -> float:
+    """Explicit argument beats `MCLI_CI_LOCK_TIMEOUT` beats the 600s default.
+
+    An unparsable env value falls back to the default rather than raising: a
+    typo in a shell profile must not break every push on the machine.
+    """
+    if timeout is not None:
+        return float(timeout)
+    raw = os.getenv(LOCK_TIMEOUT_ENV)
+    if raw:
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    return DEFAULT_LOCK_TIMEOUT_SECONDS
+
+
+def _write_holder(handle) -> None:
+    """Record who holds the lock. Informational only — never load-bearing."""
+    try:
+        os.ftruncate(handle.fileno(), 0)
+        handle.seek(0)
+        stamp = datetime.now().isoformat(timespec="seconds")
+        handle.write(f"pid={os.getpid()} repo={os.getcwd()} since={stamp}\n")
+        handle.flush()
+    except OSError:
+        pass  # metadata is a nicety; never fail a run over it
+
+
+def _holder_description(path: Path) -> str:
+    """Best-effort description of the current holder, for the wait message."""
+    try:
+        text = path.read_text().strip()
+    except OSError:
+        return _UNKNOWN_HOLDER
+    return text.splitlines()[0] if text else _UNKNOWN_HOLDER
+
+
+@contextmanager
+def act_lock(
+    timeout: float | None = None,
+    path: Path | None = None,
+    announce: Callable[[str], object] | None = None,
+) -> Iterator[bool]:
+    """Hold the machine-wide act lock for the duration of the block.
+
+    Yields True when the lock was acquired and False when the wait timed out —
+    it never raises on contention, so the caller stays in control of what a
+    missed lock means.
+    """
+    wait_budget = resolve_timeout(timeout)
+    lockfile = path if path is not None else lock_path()
+    emit = announce if announce is not None else sys.stdout.write
+
+    try:
+        lockfile.parent.mkdir(parents=True, exist_ok=True)
+        handle = open(lockfile, "a+")
+    except OSError as exc:
+        # Read-only home, a lockfile owned by another user, no space… none of
+        # that is a reason to fail a push. Degrade to the pre-lock behaviour
+        # (unserialised) and say so, rather than raising into the gate — an
+        # exception here would exit 1 and BLOCK the push in every repo.
+        emit(
+            f"⚠️  Cannot use the machine-wide act lock at {lockfile} ({exc}); "
+            "running act unserialised.\n"
+        )
+        yield True
+        return
+
+    acquired = False
+    try:
+        deadline = time.monotonic() + wait_budget
+        announced = False
+        while True:
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                acquired = True
+                break
+            except OSError as exc:
+                if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK):
+                    raise
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            if not announced:
+                emit(
+                    f"⏳ Another `mcli ci preflight` is already running act "
+                    f"({_holder_description(lockfile)}); waiting up to "
+                    f"{wait_budget:.0f}s for the machine-wide CI lock…\n"
+                )
+                announced = True
+            time.sleep(min(_POLL_INTERVAL_SECONDS, remaining))
+
+        if acquired:
+            _write_holder(handle)
+        yield acquired
+    finally:
+        # Closing the descriptor releases the flock by itself; unlocking first
+        # is belt-and-braces in case the handle ever outlives this frame.
+        if acquired:
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        handle.close()

{mcli_framework-8.0.62 → mcli_framework-8.0.65}/src/mcli/workflow/ci/act_runner.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import platform
 import shutil
 import subprocess
@@ -10,6 +11,8 @@ import time
 from enum import Enum
 from pathlib import Path
 
+from mcli.workflow.ci.act_lock import LOCK_TIMEOUT_ENV, act_lock, resolve_timeout
+
 # Docker Hub returns these when the unauthenticated image-pull rate limit is hit.
 # act surfaces them while pulling the runner image — this is an environment
 # problem, NOT a test failure, so it must not hard-block a push.
@@ -28,16 +31,20 @@ _NO_STAGES_MARKERS = ("could not find any stages to run",)
 _RETRY_BACKOFF = (15, 45)
 _MAX_RETRIES = 2
 
-# Canonical CI entrypoint created by `mcli ci migrate`: ci.yml runs on
-# `workflow_dispatch`. The job id is NOT fixed (`mcli ci migrate` keeps the
-# repo's original job name, e.g. `test`) — so preflight discovers the real job
-# id(s) from `act --list` rather than assuming a hardcoded name.
-_DISPATCH_WORKFLOW = Path(".github/workflows/ci.yml")
+# Dispatch-only workflows that are safe and expected to run as local gates.
+# Deploy, release, and audit workflows are intentionally not selected.
+_WORKFLOW_DIR = Path(".github/workflows")
+_DISPATCH_GATE_NAMES = {"ci", "secret-scan", "security-scan"}
 
 # Header label of the job-id column in `act --list` table output.
 _JOB_ID_HEADER = "Job ID"
 
 
+def _act_command(*args: str) -> list[str]:
+    """Build an act command without implicitly loading the repository .env."""
+    return ["act", *args, "--env-file", os.devnull]
+
+
 class PreflightResult(Enum):
     PASS = "pass"
     FAIL = "fail"
@@ -98,7 +105,7 @@ def probe() -> bool:
     if not act_available() or not docker_running():
         return False
     try:
-        proc = subprocess.run(["act", "-l"], capture_output=True, text=True, timeout=60)
+        proc = subprocess.run(_act_command("-l"), capture_output=True, text=True, timeout=60)
     except (FileNotFoundError, subprocess.TimeoutExpired):
         return False
     return proc.returncode == 0
@@ -107,38 +114,56 @@ def probe() -> bool:
 def default_container_arch() -> str | None:
     """`--container-architecture` value for the host, or None to let act decide.
 
-    act's runner images are amd64. On Apple-silicon (darwin/arm64) act warns and
-    misbehaves unless told to emulate amd64, so force it; native amd64 Linux
-    needs nothing.
+    On Apple Silicon, select native arm64 together with the multi-arch runner
+    mapping added by build_act_command; native Linux needs no override.
     """
     if sys.platform == "darwin" and platform.machine() in ("arm64", "aarch64"):
-        return "linux/amd64"
+        return "linux/arm64"
     return None
 
 
-def dispatch_workflow() -> str | None:
-    """The canonical workflow file to drive via `workflow_dispatch`, or None."""
-    if _DISPATCH_WORKFLOW.exists():
-        return str(_DISPATCH_WORKFLOW)
-    return None
+def dispatch_workflows() -> list[str]:
+    """Return dispatch-only CI and security workflows safe to run locally.
+
+    The act-first migration historically preserved workflow filenames, so a
+    real gate may be ``elixir-ci.yml`` rather than the newer canonical
+    ``ci.yml``. Select those CI names plus explicit security scans, while
+    excluding the dormant self-hosted fallback and every deploy/release job.
+    """
+    if not _WORKFLOW_DIR.is_dir():
+        return []
+
+    workflows: list[str] = []
+    for path in sorted((*_WORKFLOW_DIR.glob("*.yml"), *_WORKFLOW_DIR.glob("*.yaml"))):
+        stem = path.stem.lower()
+        is_ci = stem == "ci" or stem.startswith("ci-") or stem.endswith("-ci")
+        if stem == "self-hosted-ci":
+            continue
+        if is_ci or stem in _DISPATCH_GATE_NAMES:
+            workflows.append(str(path))
+    return workflows
 
 
-def list_jobs(event: str, workflow: str | None = None) -> list[str]:
+def list_jobs(event: str, workflow: str | None = None) -> list[str] | None:
     """Real job ids act would run for `event`, parsed from the `act --list` table.
 
     `act --list` prints a table whose first row is a header containing a `Job ID`
     column; each subsequent row is a runnable job. Returns job ids in table order
     (deduplicated). Returns ``[]`` when act lists no jobs for the event (including
-    the "could not find any stages" no-op) or when act can't be invoked — never
-    raises, so callers can treat an empty result as "nothing to run".
+    the "could not find any stages" no-op). Returns ``None`` when act cannot be
+    invoked or listing fails, so callers cannot mistake an error for a green
+    workflow with no jobs.
     """
-    cmd = ["act", event, "--list"]
+    cmd = _act_command(event, "--list")
     if workflow is not None:
         cmd += ["-W", workflow]
     try:
         proc = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
     except (FileNotFoundError, subprocess.TimeoutExpired):
-        return []
+        return None
+    output = (proc.stdout or "") + (proc.stderr or "")
+    if proc.returncode != 0:
+        return [] if _has_no_stages(output) else None
     return _parse_job_ids(proc.stdout or "")
 
 
@@ -169,13 +194,19 @@ def build_act_command(
     job: str | None = None,
     arch: str | None = None,
 ) -> list[str]:
-    cmd = ["act", event]
+    cmd = _act_command(event)
     if workflow is not None:
         cmd += ["-W", workflow]
     if job is not None:
         cmd += ["-j", job]
     if arch is not None:
         cmd += ["--container-architecture", arch]
+        if arch == "linux/arm64":
+            # Use act's full multi-arch runner on Apple Silicon. Emulating BEAM
+            # and Dialyzer under QEMU is resource-heavy and prone to
+            # compiler/PLT segfaults.
+            cmd += ["--env", "RUNNER_ARCH=ARM64"]
+            cmd += ["-P", "ubuntu-latest=catthehacker/ubuntu:act-20.04"]
     if Path(".secrets").exists():
         cmd += ["--secret-file", ".secrets"]
     return cmd
@@ -234,10 +265,9 @@ def run_act(
     - any other non-zero exit -> FAIL.
 
     Migrated repos are ``workflow_dispatch``-only, so the default
-    ``pull_request`` event matches no jobs. Rather than hollow-pass, fall back
-    to the canonical ``ci.yml`` on ``workflow_dispatch``: discover its real job
-    id(s) via ``act --list`` (the job name is NOT fixed — ``mcli ci migrate``
-    keeps the repo's original name) and run each so the gate validates for real.
+    ``pull_request`` event matches no jobs. Rather than hollow-pass, discover
+    CI and security gate workflows and run their real job ids via
+    ``workflow_dispatch``. Deploy and release workflows are never selected.
 
     A green result means act actually executed ≥1 job and every job passed. If
     ``act --list`` shows jobs but a run reports "could not find any stages"
@@ -249,46 +279,58 @@ def run_act(
     if not (result == PreflightResult.PASS and _has_no_stages(output)):
         return result
 
-    # No stages for the requested event — try the workflow_dispatch entrypoint.
-    workflow = dispatch_workflow()
-    if workflow is None:
+    # No stages for the requested event — try safe workflow_dispatch gates.
+    workflows = dispatch_workflows()
+    if not workflows:
         sys.stdout.write(
-            "ℹ️  No act stages for this event and no ci.yml dispatch "
+            "ℹ️  No act stages for this event and no CI/security dispatch "
             "entrypoint — nothing to validate; treating as pass.\n"
         )
         return PreflightResult.PASS
 
-    jobs = list_jobs("workflow_dispatch", workflow)
-    if not jobs:
-        # The dispatch entrypoint genuinely has no jobs — a real no-op.
+    ran_job = False
+    for workflow in workflows:
+        jobs = list_jobs("workflow_dispatch", workflow)
+        if jobs is None:
+            sys.stdout.write(
+                f"❌ Failed to discover workflow_dispatch jobs for {workflow}; "
+                "the gate was not executed.\n"
+            )
+            return PreflightResult.FAIL
+        if not jobs:
+            sys.stdout.write(f"ℹ️  {workflow} has no workflow_dispatch jobs — skipping.\n")
+            continue
+
         sys.stdout.write(
-            f"ℹ️  {workflow} has no workflow_dispatch jobs — nothing to "
-            "validate; treating as pass.\n"
+            f"ℹ️  No '{event}' stages (workflow_dispatch-only); running "
+            f"{workflow} {jobs} via workflow_dispatch…\n"
         )
-        return PreflightResult.PASS
-
-    targets = f"{workflow} {jobs}"
-    sys.stdout.write(
-        f"ℹ️  No '{event}' stages (workflow_dispatch-only); running "
-        f"{targets} via workflow_dispatch…\n"
-    )
-    for job in jobs:
-        result, output = _run_with_retries(
-            build_act_command("workflow_dispatch", workflow=workflow, job=job, arch=arch),
-            retries,
-            backoff,
+        for job in jobs:
+            ran_job = True
+            result, output = _run_with_retries(
+                build_act_command("workflow_dispatch", workflow=workflow, job=job, arch=arch),
+                retries,
+                backoff,
+            )
+            if result == PreflightResult.UNREACHABLE:
+                return PreflightResult.UNREACHABLE
+            # We KNOW this job exists (it came from `act --list`), so "no stages"
+            # here means act ran nothing — a failure, not a no-op. Do not pass.
+            if result != PreflightResult.PASS or _has_no_stages(output):
+                return PreflightResult.FAIL
+
+    if not ran_job:
+        sys.stdout.write(
+            "ℹ️  CI/security dispatch workflows contain no runnable jobs — "
+            "nothing to validate; treating as pass.\n"
         )
-        if result == PreflightResult.UNREACHABLE:
-            return PreflightResult.UNREACHABLE
-        # We KNOW this job exists (it came from `act --list`), so "no stages"
-        # here means act ran nothing — a failure, not a no-op. Do not pass.
-        if result != PreflightResult.PASS or _has_no_stages(output):
-            return PreflightResult.FAIL
 
     return PreflightResult.PASS
 
 
-def preflight(repo_slug: str, event: str = "pull_request") -> PreflightResult:
+def preflight(
+    repo_slug: str, event: str = "pull_request", lock_timeout: float | None = None
+) -> PreflightResult:
     """Primary gate. PASS/FAIL if act can run; UNREACHABLE if act can't start here.
 
     `repo_slug` is accepted for symmetry and future use; the runner fallback is
@@ -296,10 +338,28 @@ def preflight(repo_slug: str, event: str = "pull_request") -> PreflightResult:
 
     Prefers a repo-defined native gate (`make ci-native`) over act: it runs the
     same checks on the host toolchain, avoiding act's flaky container emulation.
+
+    The act run — and only the act run — is serialised machine-wide by
+    `act_lock`, because every repo's act run drives the same container runtime.
+    The native gate is host-local and stays unlocked, and `probe()` runs before
+    the wait so a dead docker is UNREACHABLE immediately instead of after
+    `lock_timeout` seconds. On lock timeout the gate reports UNREACHABLE (the
+    established "cannot validate" state) rather than starting the second
+    concurrent container run this lock exists to prevent.
     """
     if native_gate_available():
         sys.stdout.write("▶ Native CI gate found — running `make ci-native` (no act)…\n")
         return run_native()
     if not probe():
         return PreflightResult.UNREACHABLE
-    return run_act(event)
+    with act_lock(timeout=lock_timeout) as acquired:
+        if not acquired:
+            sys.stdout.write(
+                f"⚠️  Timed out after {resolve_timeout(lock_timeout):.0f}s waiting for the "
+                "machine-wide act lock — another `mcli ci preflight` is still running act. "
+                "Refusing to start a second concurrent container run; this push was NOT "
+                "validated locally (re-run `mcli ci preflight` when the machine is idle, "
+                f"or raise the wait with --lock-timeout / {LOCK_TIMEOUT_ENV}).\n"
+            )
+            return PreflightResult.UNREACHABLE
+        return run_act(event)

{mcli_framework-8.0.62 → mcli_framework-8.0.65}/src/mcli/workflow/ci/ci.py

@@ -9,6 +9,7 @@ from pathlib import Path
 
 import click
 
+from mcli.workflow.ci.act_lock import DEFAULT_LOCK_TIMEOUT_SECONDS, LOCK_TIMEOUT_ENV
 from mcli.workflow.ci.act_runner import PreflightResult, act_available, docker_running
 from mcli.workflow.ci.act_runner import preflight as preflight_fn
 from mcli.workflow.ci.runner_status import has_online_runner
@@ -98,10 +99,21 @@ def migrate(dry_run):
 
 @ci.command()
 @click.option("--event", default="pull_request", show_default=True, help="act event to simulate.")
-def preflight(event):
+@click.option(
+    "--lock-timeout",
+    type=float,
+    default=None,
+    help=(
+        "Seconds to wait for the machine-wide act lock before giving up "
+        f"(default {DEFAULT_LOCK_TIMEOUT_SECONDS:.0f}s, or ${LOCK_TIMEOUT_ENV}). "
+        "act runs are serialised across repos so concurrent pushes cannot "
+        "starve the shared container runtime."
+    ),
+)
+def preflight(event, lock_timeout):
     """Run act as the PR gate. Exit 0=pass, 1=fail, 2=cannot validate, 3=use runner."""
     slug = current_repo_slug()
-    result = preflight_fn(slug, event)
+    result = preflight_fn(slug, event, lock_timeout=lock_timeout)
     if result == PreflightResult.PASS:
         click.echo("✅ act passed — OK to open PR.")
         raise SystemExit(0)
@@ -146,8 +158,25 @@ PRE_PUSH_HOOK = """#!/usr/bin/env bash
 # Blocks ONLY on a real act failure (exit 1). When act cannot validate locally
 # — e.g. Docker Hub rate-limit (toomanyrequests, retried first), no docker, or
 # an online runner will validate instead (exit 2/3) — the push is allowed so an
-# environment hiccup never wedges your workflow. Override a real failure with:
+# environment hiccup never wedges your workflow.
+# act runs are serialised machine-wide, so this may wait for another repo's
+# preflight to finish (bounded; see --lock-timeout / MCLI_CI_LOCK_TIMEOUT).
+# Override a real failure with:
 #   git push --no-verify
+#
+# A gate that cannot run must not pass. Git hooks inherit the environment of
+# whatever invoked `git`, which is not necessarily a login shell — an IDE, a
+# GUI client or a cron job can push with a PATH that never sourced your
+# profile. Without the check below, `mcli` would simply be "command not found"
+# (exit 127), the `-eq 1` test would not match, and the push would sail through
+# with nothing validated — indistinguishable from having no hook at all.
+if ! command -v mcli >/dev/null 2>&1; then
+  echo "mcli-ci: mcli is not on PATH, so nothing was validated — push blocked." >&2
+  echo "  This shell's PATH: $PATH" >&2
+  echo "  Fix the PATH (hooks do not source your shell profile), or override:" >&2
+  echo "    git push --no-verify" >&2
+  exit 1
+fi
 mcli ci preflight
 code=$?
 if [ "$code" -eq 1 ]; then

{mcli_framework-8.0.62 → mcli_framework-8.0.65/src/mcli_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcli-framework
-Version: 8.0.62
+Version: 8.0.65
 Summary: Portable workflow framework - transform any script into a versioned, schedulable command. Store in ~/.mcli/workflows/, version with lockfile, run as daemon or cron job.
 Author-email: Luis Fernandez de la Vara <luis@lefv.io>
 Maintainer-email: Luis Fernandez de la Vara <luis@lefv.io>

{mcli_framework-8.0.62 → mcli_framework-8.0.65}/src/mcli_framework.egg-info/SOURCES.txt

@@ -163,6 +163,7 @@ src/mcli/workflow/doc_convert.py
 src/mcli/workflow/lsh_integration.py
 src/mcli/workflow/workflow.py
 src/mcli/workflow/ci/__init__.py
+src/mcli/workflow/ci/act_lock.py
 src/mcli/workflow/ci/act_runner.py
 src/mcli/workflow/ci/ci.py
 src/mcli/workflow/ci/runner_status.py