everyome 0.1.0a1__tar.gz

everyome-0.1.0a1/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use Everyome, adapt its code, or reuse its text or figures, please cite it as below."
+title: "Everyome: every -ome, for everyone"
+type: software
+authors:
+  - family-names: Horkan
+    given-names: Helen R.
+    affiliation: Stowers Institute for Medical Research
+version: 0.1.0a1
+license: MIT
+repository-code: "https://github.com/Everyome/everyome"

everyome-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helen R Horkan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everyome-0.1.0a1/MANIFEST.in

@@ -0,0 +1,3 @@
+# Intent: the source package carries the tests (and their helper), the citation and the licences.
+include LICENSE THIRD_PARTY_NOTICES.md CITATION.cff README.md
+recursive-include tests *.py

everyome-0.1.0a1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: everyome
+Version: 0.1.0a1
+Summary: Every -ome, for everyone: omics analysis with a simple interface and every setting in reach, on your own computer or Slurm cluster.
+Author: Helen R Horkan
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Everyome/everyome
+Project-URL: Source, https://github.com/Everyome/everyome
+Project-URL: Issues, https://github.com/Everyome/everyome/issues
+Project-URL: Citation, https://github.com/Everyome/everyome/blob/main/CITATION.cff
+Keywords: bioinformatics,omics,single-cell,SPLiT-seq,RNA-seq,differential expression,Slurm,Nextflow,GUI
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: python-multipart
+Requires-Dist: pyyaml
+Requires-Dist: setproctitle
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: singlecell
+Requires-Dist: numpy; extra == "singlecell"
+Requires-Dist: pandas; extra == "singlecell"
+Requires-Dist: scipy; extra == "singlecell"
+Requires-Dist: scanpy>=1.9; extra == "singlecell"
+Requires-Dist: anndata>=0.9; extra == "singlecell"
+Requires-Dist: harmonypy; extra == "singlecell"
+Requires-Dist: leidenalg; extra == "singlecell"
+Requires-Dist: igraph; extra == "singlecell"
+Requires-Dist: openpyxl; extra == "singlecell"
+Requires-Dist: seaborn; extra == "singlecell"
+Requires-Dist: matplotlib; extra == "singlecell"
+Provides-Extra: rna
+Requires-Dist: numpy; extra == "rna"
+Requires-Dist: pandas; extra == "rna"
+Requires-Dist: matplotlib; extra == "rna"
+Requires-Dist: pydeseq2; extra == "rna"
+Provides-Extra: all
+Requires-Dist: everyome[rna,singlecell]; extra == "all"
+Dynamic: license-file
+
+# Everyome
+
+*Every -ome, for everyone.*
+
+Created by **Helen R Horkan PhD** (Stowers Institute). If you use Everyome, adapt its
+code, or reuse its text or figures, please cite it (see [`CITATION.cff`](https://github.com/Everyome/everyome/blob/main/CITATION.cff)).
+
+Everyome is a free, open-source platform for omics analysis. It gives biologists a
+simple point-and-click interface while keeping every setting visible and editable.
+It runs on your own computer or on your own Slurm cluster account over SSH, so
+your data stays where it is.
+
+Planned suites: DNA, RNA, single cell, spatial, protein, molecular biology and
+phylogenetics. Every module will come with a manual, a playground, guides to
+reading its output, and a lab-book protocol and methods section for every run.
+
+Everyome grows out of SPLiTscape (SPLiT-seq reads to annotated cell atlases),
+which becomes its first single-cell module and keeps its own citation.
+
+## Status
+
+The core is in place (phase 1 of [`docs/PLAN.md`](https://github.com/Everyome/everyome/blob/main/docs/PLAN.md)): connect to a
+cluster or the built-in demo cluster, create projects, choose an analysis, fill
+in its settings, check the exact job scripts, submit them, follow the jobs, and
+explore the results in a live session. Every run then gets a lab-book
+protocol, a draft methods section to edit, its references, and a bundle that
+repeats it exactly.
+
+Modules so far:
+- **SPLiT-seq (SPLiTscape)**, single cell: SPLiT-seq sublibraries from raw reads
+  to annotated cell types, on their own (for example, to build a first atlas) or
+  merged with an existing atlas or dataset. Includes a playground.
+- **Bulk RNA-seq differential expression**, RNA: nf-core/rnaseq turns reads into
+  gene counts on the cluster, then DESeq2 compares conditions in a live session.
+- **Sequence summary**, getting started: a small worked example of how every
+  module runs.
+
+## Install
+
+```bash
+pip install "everyome==0.1.0a1"          # the app and the tutorial
+pip install "everyome[all]==0.1.0a1"     # plus SPLiT-seq and bulk RNA-seq (Scanpy, PyDESeq2, ...)
+everyome                              # opens http://127.0.0.1:8777
+```
+
+Naming the version installs this early release of Everyome while everything it
+needs comes from normal, stable releases. (Avoid `pip install --pre`: it would
+also pull in unfinished versions of other packages.) Everyome needs Python 3.10
+or newer and runs on macOS and Linux. Choose **Demo
+cluster** to try everything on your own computer, with example data and a
+pretend job scheduler; demo data lives in `~/.everyome/demo_cluster` (delete it
+to start fresh). To use your own cluster, Everyome also needs to be installed in
+a Python environment there (ask IT for a shared one), and the readiness checks
+tell you what is missing.
+
+## Develop
+
+```bash
+git clone https://github.com/Everyome/everyome && cd everyome
+pip install -e ".[test,all]"
+pytest
+```
+
+## Licence
+
+MIT (see `LICENSE`). Fonts, UMAP-JS and the nf-core/rnaseq schemas that ship
+with Everyome keep their own licences; see `THIRD_PARTY_NOTICES.md`.

everyome-0.1.0a1/README.md

@@ -0,0 +1,67 @@
+# Everyome
+
+*Every -ome, for everyone.*
+
+Created by **Helen R Horkan PhD** (Stowers Institute). If you use Everyome, adapt its
+code, or reuse its text or figures, please cite it (see [`CITATION.cff`](https://github.com/Everyome/everyome/blob/main/CITATION.cff)).
+
+Everyome is a free, open-source platform for omics analysis. It gives biologists a
+simple point-and-click interface while keeping every setting visible and editable.
+It runs on your own computer or on your own Slurm cluster account over SSH, so
+your data stays where it is.
+
+Planned suites: DNA, RNA, single cell, spatial, protein, molecular biology and
+phylogenetics. Every module will come with a manual, a playground, guides to
+reading its output, and a lab-book protocol and methods section for every run.
+
+Everyome grows out of SPLiTscape (SPLiT-seq reads to annotated cell atlases),
+which becomes its first single-cell module and keeps its own citation.
+
+## Status
+
+The core is in place (phase 1 of [`docs/PLAN.md`](https://github.com/Everyome/everyome/blob/main/docs/PLAN.md)): connect to a
+cluster or the built-in demo cluster, create projects, choose an analysis, fill
+in its settings, check the exact job scripts, submit them, follow the jobs, and
+explore the results in a live session. Every run then gets a lab-book
+protocol, a draft methods section to edit, its references, and a bundle that
+repeats it exactly.
+
+Modules so far:
+- **SPLiT-seq (SPLiTscape)**, single cell: SPLiT-seq sublibraries from raw reads
+  to annotated cell types, on their own (for example, to build a first atlas) or
+  merged with an existing atlas or dataset. Includes a playground.
+- **Bulk RNA-seq differential expression**, RNA: nf-core/rnaseq turns reads into
+  gene counts on the cluster, then DESeq2 compares conditions in a live session.
+- **Sequence summary**, getting started: a small worked example of how every
+  module runs.
+
+## Install
+
+```bash
+pip install "everyome==0.1.0a1"          # the app and the tutorial
+pip install "everyome[all]==0.1.0a1"     # plus SPLiT-seq and bulk RNA-seq (Scanpy, PyDESeq2, ...)
+everyome                              # opens http://127.0.0.1:8777
+```
+
+Naming the version installs this early release of Everyome while everything it
+needs comes from normal, stable releases. (Avoid `pip install --pre`: it would
+also pull in unfinished versions of other packages.) Everyome needs Python 3.10
+or newer and runs on macOS and Linux. Choose **Demo
+cluster** to try everything on your own computer, with example data and a
+pretend job scheduler; demo data lives in `~/.everyome/demo_cluster` (delete it
+to start fresh). To use your own cluster, Everyome also needs to be installed in
+a Python environment there (ask IT for a shared one), and the readiness checks
+tell you what is missing.
+
+## Develop
+
+```bash
+git clone https://github.com/Everyome/everyome && cd everyome
+pip install -e ".[test,all]"
+pytest
+```
+
+## Licence
+
+MIT (see `LICENSE`). Fonts, UMAP-JS and the nf-core/rnaseq schemas that ship
+with Everyome keep their own licences; see `THIRD_PARTY_NOTICES.md`.

everyome-0.1.0a1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-party material in Everyome
+
+Everyome itself is under the MIT licence (`LICENSE`). It ships the following
+material from others, each under its own licence, with the licence text next to it.
+
+| What | Where | Licence |
+|---|---|---|
+| Fonts (Fontsource builds of open-source typefaces) | `everyome/static/fonts/` | SIL Open Font License 1.1; one `*-LICENSE` file per family |
+| UMAP-JS (used by the SPLiT-seq playground) | `everyome/modules/singlecell/splitseq/docs/playground/umap-js.min.js` | Apache License 2.0; `UMAP-JS-LICENSE` in the same folder |
+| nf-core/rnaseq 3.27.0 parameter and samplesheet schemas | `everyome/modules/rna/bulk_de/pipeline/` | MIT; `LICENSE-nf-core-rnaseq` in the same folder |
+
+Everyome runs, but does not include, other tools (for example nf-core/rnaseq,
+Nextflow, STAR, Salmon, cutadapt, Scanpy, Harmony, PyDESeq2). Each analysis
+lists the tools it uses and how to cite them in its manual and in each run's
+write-up.

everyome-0.1.0a1/everyome/__init__.py

@@ -0,0 +1,2 @@
+"""Everyome: every -ome, for everyone. Created by Helen R Horkan PhD (Stowers Institute); please cite it if you use it."""
+__version__ = "0.1.0a1"

everyome-0.1.0a1/everyome/__main__.py

@@ -0,0 +1,30 @@
+"""Start Everyome: `everyome` (or `python -m everyome`) opens the app in your browser."""
+import argparse
+import os
+import threading
+import webbrowser
+
+import uvicorn
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Everyome: every -ome, for everyone")
+    ap.add_argument("--port", type=int, default=8777)
+    ap.add_argument("--no-browser", action="store_true", help="do not open a browser window")
+    a = ap.parse_args()
+    try:
+        import setproctitle
+        # Intent: Stowers policy names every process Claude_<user>_<tool>_<stage>.
+        setproctitle.setproctitle(f"Claude_{os.environ.get('USER', 'user')}_everyome_app")
+    except ImportError:
+        pass
+    url = f"http://127.0.0.1:{a.port}"
+    if not a.no_browser:
+        threading.Timer(1.2, lambda: webbrowser.open(url)).start()
+    print(f"Everyome is running at {url}  (press Ctrl+C to quit)")
+    # Intent: listen on localhost only; the app is for this computer's user.
+    uvicorn.run("everyome.core.server:app", host="127.0.0.1", port=a.port, log_level="warning")
+
+
+if __name__ == "__main__":
+    main()

everyome-0.1.0a1/everyome/core/__init__.py

@@ -0,0 +1 @@
+"""Core: backends, scheduler, projects, runs and the module loader (see docs/PLAN.md, section 3)."""

everyome-0.1.0a1/everyome/core/backends.py

@@ -0,0 +1,166 @@
+"""How the app talks to the computer that does the work (carried over from SPLiTscape).
+
+Two backends with one interface:
+  * SSHBackend   — a real cluster. Uses the system `ssh` client, so the user's
+                   key, ssh-agent, ~/.ssh/config and jump hosts all apply. The
+                   app never reads the private key. BatchMode means it never
+                   prompts for a password: key-based login only.
+  * LocalBackend — this computer, inside a folder. With fake Slurm on PATH it is
+                   the demo cluster; without it, it runs local modules.
+
+Both expose: run, read_bytes, write_bytes, listdir, exists, tunnel, close.
+"""
+from __future__ import annotations
+
+import os
+import shlex
+import socket
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Entry:
+    name: str
+    is_dir: bool
+    size: int
+
+
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class Backend:
+    label = "cluster"
+    user = "unknown"
+
+    def run(self, cmd: str, timeout: float = 60, stdin: bytes | None = None) -> tuple[int, str, str]:
+        raise NotImplementedError
+
+    def read_bytes(self, path: str) -> bytes:
+        rc, out, err = self.run_bytes(f"cat {shlex.quote(path)}")
+        if rc:
+            raise FileNotFoundError(f"{path}: {err.strip()}")
+        return out
+
+    def read_text(self, path: str) -> str:
+        return self.read_bytes(path).decode()
+
+    def write_bytes(self, path: str, data: bytes) -> None:
+        q = shlex.quote(path)
+        rc, _, err = self.run(f"mkdir -p $(dirname {q}) && cat > {q}", stdin=data)
+        if rc:
+            raise OSError(f"could not write {path}: {err.strip()}")
+
+    def write_text(self, path: str, text: str) -> None:
+        self.write_bytes(path, text.encode())
+
+    def exists(self, path: str) -> bool:
+        return self.run(f"test -e {shlex.quote(path)}")[0] == 0
+
+    def listdir(self, path: str) -> list[Entry]:
+        # Intent: portable listing (type, size, name), one entry per line.
+        cmd = (f"cd {shlex.quote(path)} && for f in * .[!.]*; do [ -e \"$f\" ] || continue; "
+               "if [ -d \"$f\" ]; then t=d; s=0; else t=f; s=$(wc -c < \"$f\" | tr -d ' '); fi; "
+               "printf '%s\\t%s\\t%s\\n' \"$t\" \"$s\" \"$f\"; done")
+        rc, out, err = self.run(cmd)
+        if rc:
+            raise FileNotFoundError(f"{path}: {err.strip() or 'not a folder'}")
+        rows = [line.split("\t", 2) for line in out.splitlines() if line.count("\t") >= 2]
+        return sorted((Entry(n, t == "d", int(s)) for t, s, n in rows), key=lambda e: (not e.is_dir, e.name.lower()))
+
+    def run_bytes(self, cmd: str, timeout: float = 120) -> tuple[int, bytes, str]:
+        raise NotImplementedError
+
+    def tunnel(self, node: str, remote_port: int) -> int:
+        """Forward a local port to node:remote_port; returns the local port."""
+        raise NotImplementedError
+
+    def close(self) -> None:
+        pass
+
+
+class LocalBackend(Backend):
+    """This computer: a working folder, optionally with fake Slurm commands (the demo cluster)."""
+
+    def __init__(self, root: Path, fake_slurm_bin: Path | None = None, label: str = "this computer"):
+        self.root = root
+        self.label = label
+        self.env = dict(os.environ)
+        if fake_slurm_bin:
+            self.env["PATH"] = f"{fake_slurm_bin}{os.pathsep}{self.env.get('PATH', '')}"
+            self.env["FAKE_SLURM_HOME"] = str(root / ".slurm")
+        # Intent: jobs import this same copy of Everyome, as they would from a cluster install.
+        self.env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(Path(__file__).resolve().parents[2]), self.env.get("PYTHONPATH")]))
+        self.user = os.environ.get("USER", "user")
+        self.host = "localhost"
+
+    def run(self, cmd, timeout=60, stdin=None):
+        p = subprocess.run(["bash", "-c", cmd], cwd=self.root, env=self.env, input=stdin,
+                           capture_output=True, timeout=timeout)
+        return p.returncode, p.stdout.decode(errors="replace"), p.stderr.decode(errors="replace")
+
+    def run_bytes(self, cmd, timeout=120):
+        p = subprocess.run(["bash", "-c", cmd], cwd=self.root, env=self.env, capture_output=True, timeout=timeout)
+        return p.returncode, p.stdout, p.stderr.decode(errors="replace")
+
+    def tunnel(self, node, remote_port):
+        return remote_port          # same machine: nothing to forward
+
+
+class SSHBackend(Backend):
+    """Real cluster over OpenSSH with connection sharing (one login, many commands)."""
+
+    def __init__(self, host: str, user: str, port: int = 22, ssh_options: list[str] | None = None):
+        self.host, self.user, self.port = host, user, port
+        self.label = f"{user}@{host}"
+        ctl = Path.home() / ".ssh" / "everyome-%r@%h-%p"
+        (Path.home() / ".ssh").mkdir(mode=0o700, exist_ok=True)
+        # Intent: share one login across commands (not supported by Windows' OpenSSH).
+        share = [] if os.name == "nt" else ["-o", "ControlMaster=auto", "-o", f"ControlPath={ctl}", "-o", "ControlPersist=15m"]
+        self.base = ["ssh", "-p", str(port), "-o", "BatchMode=yes", "-o", "ConnectTimeout=15", *share,
+                     "-o", "ServerAliveInterval=30", *(ssh_options or []), f"{user}@{host}"]
+        self.tunnels: list[subprocess.Popen] = []
+
+    def _ssh(self, cmd, stdin=None, timeout=60):
+        # Intent: run under a login shell so the user's cluster PATH (Slurm, modules) is set.
+        return subprocess.run([*self.base, f"bash -lc {shlex.quote(cmd)}"], input=stdin, capture_output=True, timeout=timeout)
+
+    def run(self, cmd, timeout=60, stdin=None):
+        p = self._ssh(cmd, stdin, timeout)
+        return p.returncode, p.stdout.decode(errors="replace"), p.stderr.decode(errors="replace")
+
+    def run_bytes(self, cmd, timeout=120):
+        p = self._ssh(cmd, None, timeout)
+        return p.returncode, p.stdout, p.stderr.decode(errors="replace")
+
+    def tunnel(self, node, remote_port):
+        lport = free_port()
+        args = [a for a in self.base if a != f"{self.user}@{self.host}"]
+        proc = subprocess.Popen([*args, "-N", "-o", "ExitOnForwardFailure=yes",
+                                 "-L", f"127.0.0.1:{lport}:{node}:{remote_port}", f"{self.user}@{self.host}"],
+                                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+        self.tunnels.append(proc)
+        return lport
+
+    def close(self):
+        for t in self.tunnels:
+            t.terminate()
+        subprocess.run([*self.base[:-1], "-O", "exit", f"{self.user}@{self.host}"], capture_output=True)
+
+
+def describe_ssh_error(err: str) -> str:
+    """Turn common ssh failures into plain-language advice."""
+    e = err.lower()
+    if "permission denied" in e:
+        return "The cluster refused your key. Check that your SSH key is added to the cluster and loaded (ssh-add)."
+    if "could not resolve" in e or "name or service not known" in e:
+        return "That cluster address could not be found. Check the host name, and that you are on the institute network or VPN."
+    if "timed out" in e or "no route" in e:
+        return "The cluster did not answer. Check you are on the institute network or VPN."
+    if "host key verification failed" in e:
+        return "Your computer has not seen this cluster before. Log in once from a terminal to accept its host key, or ask IT."
+    return err.strip() or "Connection failed."

everyome-0.1.0a1/everyome/core/demo/__init__.py

@@ -0,0 +1,38 @@
+"""The demo cluster: a folder on this computer plus a pretend Slurm.
+
+<root>/
+  projects/             where demo projects are saved
+  data/<module id>/     each module's small demo dataset
+  .bin/                 sbatch, squeue, sacct, scancel (fake_slurm.py)
+  .slurm/               the pretend scheduler's job records
+"""
+from __future__ import annotations
+
+import importlib
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+
+def setup(root: Path, modules: dict) -> Path:
+    """Create or refresh the demo cluster; returns the folder holding the fake Slurm commands."""
+    (root / "projects").mkdir(parents=True, exist_ok=True)
+    for m in modules.values():
+        if m.demo.get("data"):
+            # Intent: refresh demo data from the installed modules, never touching users' demo projects.
+            shutil.copytree(m.dir / m.demo["data"], root / "data" / m.id, dirs_exist_ok=True)
+        if m.demo.get("build") and not (root / "data" / m.id / ".demo_ready").exists():
+            # Intent: modules whose demo data is generated (too large to ship) build it once, here.
+            mod, _, fn = m.demo["build"].partition(":")
+            getattr(importlib.import_module(mod), fn)(root / "data" / m.id)
+            (root / "data" / m.id / ".demo_ready").write_text("1")
+    bin_dir = root / ".bin"
+    bin_dir.mkdir(exist_ok=True)
+    for cmd in ("sbatch", "squeue", "sacct", "scancel"):
+        f = bin_dir / cmd
+        f.write_text(f"#!/bin/bash\nexec {shlex.quote(sys.executable)} {shlex.quote(str(HERE / 'fake_slurm.py'))} {cmd} \"$@\"\n")
+        f.chmod(0o755)
+    return bin_dir

everyome-0.1.0a1/everyome/core/demo/fake_slurm.py

@@ -0,0 +1,151 @@
+"""A tiny stand-in for Slurm, used by the demo cluster.
+
+Implements the subset Everyome uses (carried over from SPLiTscape):
+  sbatch [--parsable] [--dependency=afterok:ID[:ID]] [--job-name=..] [--output=..] script
+  squeue -h -j IDS -o "%i %T %N"
+  sacct  -n -P -j IDS -o JobID,State,Elapsed
+  scancel ID [ID ...]
+
+Jobs run as background processes; state lives in $FAKE_SLURM_HOME.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+HOME = Path(os.environ.get("FAKE_SLURM_HOME", Path.home() / ".fake_slurm"))
+JOBS = HOME / "jobs"
+
+
+def _load(jid):
+    return json.loads((JOBS / f"{jid}.json").read_text())
+
+
+def _save(job):
+    tmp = JOBS / f"{job['id']}.json.tmp"
+    tmp.write_text(json.dumps(job))
+    tmp.replace(JOBS / f"{job['id']}.json")
+
+
+def _directives(script: str) -> dict:
+    out = {}
+    for line in Path(script).read_text().splitlines():
+        m = re.match(r"#SBATCH\s+--([\w-]+)(?:[= ](.+))?", line.strip())
+        if m:
+            out[m.group(1)] = (m.group(2) or "").strip()
+    return out
+
+
+def sbatch(args):
+    JOBS.mkdir(parents=True, exist_ok=True)
+    opts, script = {}, None
+    for a in args:
+        if a.startswith("--"):
+            k, _, v = a[2:].partition("=")
+            opts[k] = v
+        else:
+            script = a
+    if not script:
+        sys.exit("sbatch: no script given")
+    opts = {**_directives(script), **opts}
+    counter = HOME / "counter"
+    jid = int(counter.read_text()) + 1 if counter.exists() else 1001
+    counter.write_text(str(jid))
+    deps = []
+    if opts.get("dependency", "").startswith("afterok:"):
+        deps = [int(x) for x in opts["dependency"][8:].split(":") if x]
+    out = opts.get("output", str(Path.cwd() / f"slurm-{jid}.out")).replace("%j", str(jid))
+    job = {"id": jid, "name": opts.get("job-name", Path(script).name), "script": str(Path(script).resolve()),
+           "cwd": str(Path.cwd()), "output": out, "deps": deps, "state": "PENDING", "start": None, "end": None,
+           "node": socket.gethostname(), "pid": None}
+    _save(job)
+    # Intent: detach a runner that waits for dependencies, then executes the script.
+    subprocess.Popen([sys.executable, __file__, "_run", str(jid)], start_new_session=True,
+                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=os.environ.copy())
+    print(jid if "parsable" in opts else f"Submitted batch job {jid}")
+
+
+def _run(jid):
+    job = _load(jid)
+    while True:
+        states = [_load(d)["state"] for d in job["deps"]]
+        if any(s in ("FAILED", "CANCELLED", "TIMEOUT") for s in states):
+            job = _load(jid); job.update(state="CANCELLED", reason="DependencyNeverSatisfied", end=time.time()); _save(job); return
+        if all(s == "COMPLETED" for s in states):
+            break
+        if _load(jid)["state"] == "CANCELLED":
+            return
+        time.sleep(0.5)
+    job = _load(jid)
+    if job["state"] == "CANCELLED":
+        return
+    Path(job["output"]).parent.mkdir(parents=True, exist_ok=True)
+    with open(job["output"], "w") as log:
+        env = dict(os.environ, SLURM_JOB_ID=str(jid), SLURMD_NODENAME=job["node"])
+        p = subprocess.Popen(["bash", job["script"]], cwd=job["cwd"], stdout=log, stderr=subprocess.STDOUT, env=env, start_new_session=True)
+        job.update(state="RUNNING", start=time.time(), pid=p.pid); _save(job)
+        rc = p.wait()
+    job = _load(jid)
+    if job["state"] != "CANCELLED":
+        job.update(state="COMPLETED" if rc == 0 else "FAILED", end=time.time(), exit=rc); _save(job)
+
+
+def _ids(args):
+    for i, a in enumerate(args):
+        if a == "-j" and i + 1 < len(args):
+            return [int(x) for x in args[i + 1].split(",") if x]
+        if a.startswith("--jobs="):
+            return [int(x) for x in a[7:].split(",") if x]
+    return sorted(int(p.stem) for p in JOBS.glob("*.json")) if JOBS.exists() else []
+
+
+def _elapsed(job):
+    if not job["start"]:
+        return "00:00:00"
+    s = int((job["end"] or time.time()) - job["start"])
+    return f"{s // 3600:02d}:{s % 3600 // 60:02d}:{s % 60:02d}"
+
+
+def squeue(args):
+    for jid in _ids(args):
+        try:
+            j = _load(jid)
+        except FileNotFoundError:
+            continue
+        if j["state"] in ("PENDING", "RUNNING"):
+            print(f"{jid} {j['state']} {j['node'] if j['state'] == 'RUNNING' else '(None)'}")
+
+
+def sacct(args):
+    for jid in _ids(args):
+        try:
+            j = _load(jid)
+        except FileNotFoundError:
+            continue
+        print(f"{jid}|{j['state']}|{_elapsed(j)}")
+
+
+def scancel(args):
+    for a in args:
+        if not a.isdigit():
+            continue
+        j = _load(int(a))
+        if j["state"] in ("PENDING", "RUNNING"):
+            if j.get("pid"):
+                try:
+                    os.killpg(j["pid"], 15)
+                except ProcessLookupError:
+                    pass
+            j.update(state="CANCELLED", end=time.time()); _save(j)
+
+
+if __name__ == "__main__":
+    cmd, rest = sys.argv[1], sys.argv[2:]
+    {"sbatch": sbatch, "squeue": squeue, "sacct": sacct, "scancel": scancel,
+     "_run": lambda a: _run(int(a[0]))}[cmd](rest)