mainsequence 2.0.0__py3-none-any.whl

mainsequence/__main__.py

@@ -0,0 +1,9 @@
+# mainsequence/__main__.py
+from .cli import app
+
+def main():
+    # Typer app is callable
+    app(prog_name="mainsequence")
+
+if __name__ == "__main__":
+    main()

mainsequence/cli/__init__.py

@@ -0,0 +1 @@
+from .cli import app

mainsequence/cli/api.py

@@ -0,0 +1,157 @@
+# mainsequence/cli/api.py
+from __future__ import annotations
+import os, re, subprocess, json, platform, pathlib, shlex, sys
+import requests
+from .config import backend_url, get_tokens, save_tokens, set_env_access
+
+AUTH_PATHS = {
+    "obtain": "/auth/jwt-token/token/",
+    "refresh": "/auth/jwt-token/token/refresh/",
+    "ping": "/auth/rest-auth/user/",
+}
+
+S = requests.Session()
+S.headers.update({"Content-Type": "application/json"})
+
+class ApiError(RuntimeError): ...
+class NotLoggedIn(ApiError): ...
+
+def _full(path: str) -> str:
+    p = "/" + path.lstrip("/")
+    return backend_url() + p
+
+def _normalize_api_path(p: str) -> str:
+    p = "/" + (p or "").lstrip("/")
+    if not re.match(r"^/(api|auth|pods|orm|user)(/|$)", p):
+        raise ApiError("Only /api/*, /auth/*, /pods/*, /orm/*, /user/* allowed")
+    return p
+
+def _access_token() -> str | None:
+    t = os.environ.get("MAIN_SEQUENCE_USER_TOKEN")
+    if t:
+        return t
+    tok = get_tokens()
+    return tok.get("access")
+
+def _refresh_token() -> str | None:
+    tok = get_tokens()
+    return tok.get("refresh")
+
+def login(email: str, password: str) -> dict:
+    url = _full(AUTH_PATHS["obtain"])
+    payload = {"email": email, "password": password}  # server expects 'email'
+    r = S.post(url, data=json.dumps(payload))
+    try:
+        data = r.json()
+    except Exception:
+        data = {}
+    if not r.ok:
+        msg = data.get("detail") or data.get("message") or r.text
+        raise ApiError(f"{msg}")
+    access = data.get("access") or data.get("token") or data.get("jwt") or data.get("access_token")
+    refresh = data.get("refresh") or data.get("refresh_token")
+    if not access or not refresh:
+        raise ApiError("Server did not return expected tokens.")
+    save_tokens(email, access, refresh)
+    set_env_access(access)
+    return {"username": email, "backend": backend_url()}
+
+def refresh_access() -> str:
+    refresh = _refresh_token()
+    if not refresh:
+        raise NotLoggedIn("Not logged in. Run `mainsequence login <email>`.")
+    r = S.post(_full(AUTH_PATHS["refresh"]), data=json.dumps({"refresh": refresh}))
+    data = r.json() if r.headers.get("content-type","").startswith("application/json") else {}
+    if not r.ok:
+        raise NotLoggedIn(data.get("detail") or "Token refresh failed.")
+    access = data.get("access")
+    if not access:
+        raise NotLoggedIn("Refresh succeeded but no access token returned.")
+    tokens = get_tokens()
+    save_tokens(tokens.get("username") or "", access, refresh)
+    set_env_access(access)
+    return access
+
+def authed(method: str, api_path: str, body: dict | None = None) -> requests.Response:
+    api_path = _normalize_api_path(api_path)
+    access = _access_token()
+    if not access:
+        # try to refresh once
+        access = refresh_access()
+    headers = {"Authorization": f"Bearer {access}"}
+    r = S.request(method.upper(), _full(api_path), headers=headers,
+                  data=None if method.upper() in {"GET","HEAD"} else json.dumps(body or {}))
+    if r.status_code == 401:
+        # retry after refresh
+        access = refresh_access()
+        headers = {"Authorization": f"Bearer {access}"}
+        r = S.request(method.upper(), _full(api_path), headers=headers,
+                      data=None if method.upper() in {"GET","HEAD"} else json.dumps(body or {}))
+    if r.status_code == 401:
+        raise NotLoggedIn("Not logged in.")
+    return r
+
+# ---------- Helper APIs ----------
+
+def safe_slug(s: str) -> str:
+    x = re.sub(r"[^a-z0-9-_]+", "-", (s or "project").lower()).strip("-")
+    return x[:64] or "project"
+
+def repo_name_from_git_url(url: str | None) -> str | None:
+    if not url: return None
+    s = re.sub(r"[?#].*$", "", url.strip())
+    last = s.split("/")[-1] if "/" in s else s
+    if last.lower().endswith(".git"): last = last[:-4]
+    return re.sub(r"[^A-Za-z0-9._-]+", "-", last)
+
+def deep_find_repo_url(extra) -> str | None:
+    if not isinstance(extra, dict): return None
+    cand = ["ssh_url","git_ssh_url","repo_ssh_url","git_url","repo_url","repository","url"]
+    for k in cand:
+        v = extra.get(k)
+        if isinstance(v, str) and (v.startswith("git@") or re.search(r"\.git($|\?)", v)):
+            return v
+        if isinstance(v, dict):
+            for vv in v.values():
+                if isinstance(vv, str) and (vv.startswith("git@") or re.search(r"\.git($|\?)", vv)):
+                    return vv
+    for v in extra.values():
+        if isinstance(v, dict):
+            found = deep_find_repo_url(v)
+            if found: return found
+    return None
+
+def get_current_user_profile() -> dict:
+    who = authed("GET", AUTH_PATHS["ping"])
+    d = who.json() if who.ok else {}
+    uid = d.get("id") or d.get("pk") or (d.get("user") or {}).get("id") or d.get("user_id")
+    if not uid:
+        return {}
+    full = authed("GET", f"/user/api/user/{uid}/")
+    u = full.json() if full.ok else {}
+    org_name = (u.get("organization") or {}).get("name") or u.get("organization_name") or ""
+    return {"username": u.get("username") or "", "organization": org_name}
+
+def get_projects() -> list[dict]:
+    r = authed("GET", "/orm/api/pods/projects/")
+    # If the API shape ever changes, still try to pull a list.
+    if not r.ok:
+        raise ApiError(f"Projects fetch failed ({r.status_code}).")
+    data = r.json() if r.headers.get("content-type","",).startswith("application/json") else {}
+    if isinstance(data, list):
+        return data
+    return data.get("results") or []
+
+def fetch_project_env_text(project_id: int | str) -> str:
+    r = authed("GET", f"/orm/api/pods/projects/{project_id}/get_environment/")
+    raw = r.json() if r.headers.get("content-type","").startswith("application/json") else r.text
+    if isinstance(raw, dict):
+        raw = raw.get("environment") or raw.get("env") or raw.get("content") or raw.get("text") or ""
+    return (raw or "")
+
+def add_deploy_key(project_id: int | str, key_title: str, public_key: str) -> None:
+    try:
+        authed("POST", f"/orm/api/pods/projects/{project_id}/add_deploy_key/",
+               {"key_title": key_title, "public_key": public_key})
+    except Exception:
+        pass

mainsequence/cli/cli.py

@@ -0,0 +1,442 @@
+# mainsequence/cli/cli.py
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+import typer
+
+from . import config as cfg
+from .api import (
+    ApiError,
+    NotLoggedIn,
+    add_deploy_key,
+    deep_find_repo_url,
+    fetch_project_env_text,
+    get_current_user_profile,
+    get_projects,
+    login as api_login,
+    repo_name_from_git_url,
+    safe_slug,
+)
+from .ssh_utils import (
+    ensure_key_for_repo,
+    open_folder,
+    open_signed_terminal,
+    start_agent_and_add_key,
+)
+import time
+
+app = typer.Typer(help="MainSequence CLI (login + project operations)")
+
+project = typer.Typer(help="Project commands")
+settings = typer.Typer(help="Settings (base folder, backend, etc.)")
+
+app.add_typer(project, name="project")
+app.add_typer(settings, name="settings")
+
+# ---------- helpers ----------
+
+def _projects_root(base_dir: str, org_slug: str) -> pathlib.Path:
+    p = pathlib.Path(base_dir).expanduser()
+    return p / org_slug / "projects"
+
+def _org_slug_from_profile() -> str:
+    prof = get_current_user_profile()
+    name = prof.get("organization") or "default"
+    return re.sub(r"[^a-z0-9-_]+", "-", name.lower()).strip("-") or "default"
+
+def _determine_repo_url(p: dict) -> str:
+    repo = (p.get("git_ssh_url") or "").strip()
+    if repo.lower() == "none":
+        repo = ""
+    if not repo:
+        extra = (p.get("data_source") or {}).get("related_resource", {}) or {}
+        extra = extra.get("extra_arguments") or (p.get("data_source") or {}).get("extra_arguments") or {}
+        repo = deep_find_repo_url(extra) or ""
+    return repo
+
+def _copy_clipboard(txt: str) -> bool:
+    try:
+        if sys.platform == "darwin":
+            p = subprocess.run(["pbcopy"], input=txt, text=True)
+            return p.returncode == 0
+        elif shutil.which("wl-copy"):
+            p = subprocess.run(["wl-copy"], input=txt, text=True)
+            return p.returncode == 0
+        elif shutil.which("xclip"):
+            p = subprocess.run(["xclip", "-selection", "clipboard"], input=txt, text=True)
+            return p.returncode == 0
+    except Exception:
+        pass
+    return False
+
+def _render_projects_table(items: list[dict], links: dict, base_dir: str, org_slug: str) -> str:
+    """Return an aligned table with Local status + path (map or default folder guess)."""
+    def ds(obj, path, default=""):
+        try:
+            for k in path.split("."):
+                obj = obj.get(k, {})
+            return obj or default
+        except Exception:
+            return default
+
+    rows = []
+    for p in items:
+        pid   = str(p.get("id", ""))
+        name  = p.get("project_name") or "(unnamed)"
+        dname = ds(p, "data_source.related_resource.display_name", "")
+        klass = ds(p, "data_source.related_resource.class_type",
+                   ds(p, "data_source.related_resource_class_type", ""))
+        status = ds(p, "data_source.related_resource.status", "")
+
+        # 1) mapping file
+        mapped = links.get(pid)
+        local_path = mapped if mapped and pathlib.Path(mapped).exists() else None
+        # 2) guess default location if mapping is absent
+        if not local_path:
+            guess = _projects_root(base_dir, org_slug) / safe_slug(name)
+            if guess.exists():
+                local_path = str(guess)
+
+        local = "Local" if local_path else "—"
+        path_col = local_path or "—"
+        rows.append((pid, name, dname, klass, status, local, path_col))
+
+    header = ["ID","Project","Data Source","Class","Status","Local","Path"]
+    if not rows:
+        return "No projects."
+
+    colw = [max(len(r[i]) for r in rows + [tuple(header)]) for i in range(len(header))]
+    fmt = "  ".join("{:<" + str(colw[i]) + "}" for i in range(len(header)))
+    out = [fmt.format(*header), fmt.format(*["-"*len(h) for h in header])]
+    for r in rows:
+        out.append(fmt.format(*r))
+    return "\n".join(out)
+
+# ---------- top-level commands ----------
+
+@app.command()
+def login(
+    email: str = typer.Argument(..., help="Email/username (server expects 'email' field)"),
+    password: Optional[str] = typer.Option(None, prompt=True, hide_input=True, help="Password"),
+    export: bool = typer.Option(False, "--export", help='Print `export MAIN_SEQUENCE_USER_TOKEN=...` so you can eval it'),
+    no_status: bool = typer.Option(False, "--no-status", help="Do not print projects table after login")
+):
+    """
+    Obtain tokens, store them locally, and set MAIN_SEQUENCE_USER_TOKEN for this process.
+    On success, print the base folder and the project table (like the Electron app).
+    """
+    try:
+        res = api_login(email, password)
+    except ApiError as e:
+        typer.secho(f"Login failed: {e}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    cfg_obj = cfg.get_config()
+    base = cfg_obj["mainsequence_path"]
+    typer.secho(f"Signed in as {res['username']} (Backend: {res['backend']})", fg=typer.colors.GREEN)
+    typer.echo(f"Projects base folder: {base}")
+
+    tok = cfg.get_tokens().get("access", os.environ.get("MAIN_SEQUENCE_USER_TOKEN", ""))
+    if export and tok:
+        print(f'export MAIN_SEQUENCE_USER_TOKEN="{tok}"')
+
+    if not no_status:
+        try:
+            items = get_projects()
+            links = cfg.get_links()
+            org_slug = _org_slug_from_profile()
+            typer.echo("\nProjects:")
+            typer.echo(_render_projects_table(items, links, base, org_slug))
+        except NotLoggedIn:
+            typer.secho("Not logged in.", fg=typer.colors.RED)
+
+# ---------- settings group ----------
+
+@settings.callback(invoke_without_command=True)
+def settings_cb(ctx: typer.Context):
+    """`mainsequence settings` defaults to `show`."""
+    if ctx.invoked_subcommand is None:
+        settings_show()
+        raise typer.Exit()
+
+@settings.command("show")
+def settings_show():
+    c = cfg.get_config()
+    typer.echo(json.dumps({
+        "backend_url": c.get("backend_url"),
+        "mainsequence_path": c.get("mainsequence_path")
+    }, indent=2))
+
+@settings.command("set-base")
+def settings_set_base(path: str = typer.Argument(..., help="New projects base folder")):
+    out = cfg.set_config({"mainsequence_path": path})
+    typer.secho(f"Projects base folder set to: {out['mainsequence_path']}", fg=typer.colors.GREEN)
+
+# ---------- project group (require login) ----------
+
+@project.callback()
+def project_guard():
+    try:
+        prof = get_current_user_profile()
+        if not prof or not prof.get("username"):
+            raise NotLoggedIn("Not logged in.")
+    except NotLoggedIn:
+        typer.secho("Not logged in. Run: mainsequence login <email>", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    except ApiError:
+        typer.secho("Not logged in. Run: mainsequence login <email>", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+@project.command("list")
+def project_list():
+    """List projects with Local status and path."""
+    cfg_obj = cfg.get_config()
+    base = cfg_obj["mainsequence_path"]
+    org_slug = _org_slug_from_profile()
+
+    items = get_projects()
+    links = cfg.get_links()
+    typer.echo(_render_projects_table(items, links, base, org_slug))
+
+@project.command("open")
+def project_open(project_id: int):
+    """Open the local folder in the OS file manager."""
+    links = cfg.get_links()
+    path = links.get(str(project_id))
+    if not path or not pathlib.Path(path).exists():
+        # also try default guess
+        cfg_obj = cfg.get_config()
+        base = cfg_obj["mainsequence_path"]
+        org_slug = _org_slug_from_profile()
+        items = get_projects()
+        p = next((x for x in items if str(x.get("id")) == str(project_id)), None)
+        if p:
+            guess = _projects_root(base, org_slug) / safe_slug(p.get("project_name") or "")
+            if guess.exists():
+                path = str(guess)
+    if not path or not pathlib.Path(path).exists():
+        typer.secho("No local folder mapped for this project. Run `set-up-locally` first.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    open_folder(path)
+    typer.echo(f"Opened: {path}")
+
+@project.command("delete-local")
+def project_delete_local(
+    project_id: int,
+    permanent: bool = typer.Option(False, "--permanent", help="Also remove the folder (dangerous)")
+):
+    """Unlink the mapped folder, optionally delete it."""
+    mapped = cfg.remove_link(project_id)
+    if not mapped:
+        typer.echo("No mapping found.")
+        return
+    p = pathlib.Path(mapped)
+    if p.exists():
+        if permanent:
+            import shutil
+            shutil.rmtree(mapped, ignore_errors=True)
+            typer.secho(f"Deleted: {mapped}", fg=typer.colors.YELLOW)
+        else:
+            typer.secho(f"Unlinked mapping (kept folder): {mapped}", fg=typer.colors.GREEN)
+    else:
+        typer.echo("Mapping removed; folder already absent.")
+
+@project.command("open-signed-terminal")
+def project_open_signed_terminal(project_id: int):
+    """Open a terminal window in the project directory with ssh-agent started and the repo's key added."""
+    links = cfg.get_links()
+    dir_ = links.get(str(project_id))
+
+    if not dir_ or not pathlib.Path(dir_).exists():
+        # also try default guess
+        cfg_obj = cfg.get_config()
+        base = cfg_obj["mainsequence_path"]
+        org_slug = _org_slug_from_profile()
+        items = get_projects()
+        p = next((x for x in items if str(x.get("id")) == str(project_id)), None)
+        if p:
+            guess = _projects_root(base, org_slug) / safe_slug(p.get("project_name") or "")
+            if guess.exists():
+                dir_ = str(guess)
+
+    if not dir_ or not pathlib.Path(dir_).exists():
+        typer.secho("No local folder mapped for this project. Run `set-up-locally` first.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    proc = subprocess.run(["git", "-C", dir_, "remote", "get-url", "origin"], text=True, capture_output=True)
+    origin = (proc.stdout or "").strip().splitlines()[-1] if proc.returncode == 0 else ""
+    name = repo_name_from_git_url(origin) or pathlib.Path(dir_).name
+    key_path = pathlib.Path.home() / ".ssh" / name
+    open_signed_terminal(dir_, key_path, name)
+
+@project.command("set-up-locally")
+def project_set_up_locally(
+    project_id: int,
+    base_dir: Optional[str] = typer.Option(None, "--base-dir", help="Override base dir (default from settings)")
+):
+    cfg_obj = cfg.get_config()
+    base = base_dir or cfg_obj["mainsequence_path"]
+
+    org_slug = _org_slug_from_profile()
+
+    items = get_projects()
+    p = next((x for x in items if int(x.get("id", -1)) == project_id), None)
+    if not p:
+        typer.secho("Project not found/visible.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    repo = _determine_repo_url(p)
+    if not repo:
+        typer.secho("No repository URL found for this project.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    name = safe_slug(p.get("project_name") or f"project-{project_id}")
+    projects_root = _projects_root(base, org_slug)
+    target_dir = projects_root / name
+    projects_root.mkdir(parents=True, exist_ok=True)
+
+    key_path, pub_path, pub = ensure_key_for_repo(repo)
+    copied = _copy_clipboard(pub)
+
+    try:
+        host = platform.node()
+        add_deploy_key(project_id, host, pub)
+    except Exception:
+        pass
+
+    agent_env = start_agent_and_add_key(key_path)
+
+    if target_dir.exists():
+        typer.secho(f"Target already exists: {target_dir}", fg=typer.colors.RED)
+        raise typer.Exit(2)
+
+    env = os.environ.copy() | agent_env
+    env["GIT_SSH_COMMAND"] = f'ssh -i "{str(key_path)}" -o IdentitiesOnly=yes'
+    rc = subprocess.call(["git", "clone", repo, str(target_dir)], env=env, cwd=str(projects_root))
+    if rc != 0:
+        try:
+            if target_dir.exists():
+                import shutil
+                shutil.rmtree(target_dir, ignore_errors=True)
+        except Exception:
+            pass
+        typer.secho("git clone failed", fg=typer.colors.RED)
+        raise typer.Exit(3)
+
+    env_text = ""
+    try:
+        env_text = fetch_project_env_text(project_id)
+    except Exception:
+        env_text = ""
+    env_text = (env_text or "").replace("\r", "")
+    if any(line.startswith("VFB_PROJECT_PATH=") for line in env_text.splitlines()):
+        lines = [f"VFB_PROJECT_PATH={str(target_dir)}" if line.startswith("VFB_PROJECT_PATH=") else line
+                 for line in env_text.splitlines()]
+        env_text = "\n".join(lines)
+    else:
+        if env_text and not env_text.endswith("\n"): env_text += "\n"
+        env_text += f"VFB_PROJECT_PATH={str(target_dir)}\n"
+    (target_dir / ".env").write_text(env_text, encoding="utf-8")
+
+    cfg.set_link(project_id, str(target_dir))
+
+    typer.secho(f"Local folder: {target_dir}", fg=typer.colors.GREEN)
+    typer.echo(f"Repo URL: {repo}")
+    if copied:
+        typer.echo("Public key copied to clipboard.")
+
+@app.command("build_and_run")
+def build_and_run(dockerfile: Optional[str] = typer.Argument(
+    None,
+    help="Path to Dockerfile to build & run. If omitted, only lock & export requirements."
+)):
+    """
+    - uv lock
+    - uv export --format requirements --no-dev --hashes > requirements.txt
+    - If DOCKERFILE argument is given: docker build -f DOCKERFILE . && docker run IMAGE
+    """
+
+    # ----- sanity checks for uv + project files -----
+    if shutil.which("uv") is None:
+        typer.secho("uv is not installed. Install it with: pip install uv", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    if not pathlib.Path("pyproject.toml").exists():
+        typer.secho(f"pyproject.toml not found in {pathlib.Path.cwd()}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    # ----- 1) solve and lock -----
+    typer.secho("Running: uv lock", fg=typer.colors.BLUE)
+    p = subprocess.run(["uv", "lock"])
+    if p.returncode != 0:
+        typer.secho("uv lock failed.", fg=typer.colors.RED)
+        raise typer.Exit(p.returncode)
+
+    # ----- 2) export pinned, hashed requirements -----
+    typer.secho("Exporting hashed requirements to requirements.txt", fg=typer.colors.BLUE)
+    p = subprocess.run(
+        ["uv", "export", "--format", "requirements", "--no-dev", "--hashes"],
+        capture_output=True, text=True
+    )
+    if p.returncode != 0:
+        typer.secho("uv export failed:", fg=typer.colors.RED)
+        if p.stderr:
+            typer.echo(p.stderr.strip())
+        raise typer.Exit(p.returncode)
+
+    pathlib.Path("requirements.txt").write_text(p.stdout, encoding="utf-8")
+    typer.secho("requirements.txt written.", fg=typer.colors.GREEN)
+
+    # ----- 3) optional Docker build + run -----
+    if dockerfile is None:
+        typer.secho("No Dockerfile provided; skipping Docker build/run.", fg=typer.colors.BLUE)
+        return
+
+    df_path = pathlib.Path(dockerfile)
+    if not df_path.exists():
+        typer.secho(f"Dockerfile not found: {dockerfile}", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    if shutil.which("docker") is None:
+        typer.secho("Docker CLI is not installed or not on PATH.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    # Image name: directory-name + '-img' (overridable via env IMAGE_NAME)
+    cwd_name = pathlib.Path.cwd().name
+    safe_name = re.sub(r"[^a-z0-9_.-]+", "-", cwd_name.lower())
+    image_name = os.environ.get("IMAGE_NAME", f"{safe_name}-img")
+
+    # Tag: short git sha if available, else timestamp (overridable via env TAG)
+    tag = os.environ.get("TAG")
+    if not tag:
+        try:
+            tag = subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], text=True).strip()
+        except Exception:
+            tag = time.strftime("%Y%m%d%H%M%S")
+
+    image_ref = f"{image_name}:{tag}"
+
+    typer.secho(f"Building Docker image: {image_ref}", fg=typer.colors.BLUE)
+    build = subprocess.run(["docker", "build", "-f", str(df_path), "-t", image_ref, "."])
+    if build.returncode != 0:
+        typer.secho("docker build failed.", fg=typer.colors.RED)
+        raise typer.Exit(build.returncode)
+
+    typer.secho(f"Running container: {image_ref}", fg=typer.colors.BLUE)
+    try:
+        # interactive by default; relies on your ENTRYPOINT
+        subprocess.check_call(["docker", "run", "--rm", "-it", image_ref])
+    except subprocess.CalledProcessError as e:
+        typer.secho(f"docker run failed (exit {e.returncode}).", fg=typer.colors.RED)
+        raise typer.Exit(e.returncode)
+

mainsequence/cli/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import json, os, sys, pathlib, platform, time
+
+APP_NAME = "MainSequenceCLI"
+
+def _config_dir() -> pathlib.Path:
+    home = pathlib.Path.home()
+    if sys.platform == "win32":
+        base = pathlib.Path(os.environ.get("APPDATA", home))
+        return base / APP_NAME
+    elif sys.platform == "darwin":
+        return home / "Library" / "Application Support" / APP_NAME
+    else:
+        return home / ".config" / "mainsequence"
+
+CFG_DIR = _config_dir()
+CFG_DIR.mkdir(parents=True, exist_ok=True)
+
+CONFIG_JSON = CFG_DIR / "config.json"
+TOKENS_JSON = CFG_DIR / "token.json"        # {username, access, refresh, ts}
+LINKS_JSON  = CFG_DIR / "project-links.json" # {"<id>": "/abs/path"}
+
+DEFAULTS = {
+    "backend_url": os.environ.get("MAIN_SEQUENCE_BACKEND_URL", "https://main-sequence.app/"),
+    "mainsequence_path": str(pathlib.Path.home() / "mainsequence"),
+    "version": 1,
+}
+
+def read_json(path: pathlib.Path, default):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return default
+
+def write_json(path: pathlib.Path, obj) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(obj, indent=2), encoding="utf-8")
+
+def get_config() -> dict:
+    cfg = DEFAULTS | read_json(CONFIG_JSON, {})
+    # ensure base exists
+    pathlib.Path(cfg["mainsequence_path"]).mkdir(parents=True, exist_ok=True)
+    return cfg
+
+def set_config(updates: dict) -> dict:
+    cfg = get_config() | (updates or {})
+    cfg["updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    write_json(CONFIG_JSON, cfg)
+    return cfg
+
+def get_links() -> dict:
+    return read_json(LINKS_JSON, {})
+
+def set_link(project_id: int | str, path: str) -> None:
+    links = get_links()
+    links[str(project_id)] = path
+    write_json(LINKS_JSON, links)
+
+def remove_link(project_id: int | str) -> str | None:
+    links = get_links()
+    prev = links.pop(str(project_id), None)
+    write_json(LINKS_JSON, links)
+    return prev
+
+def get_tokens() -> dict:
+    return read_json(TOKENS_JSON, {})
+
+def save_tokens(username: str, access: str, refresh: str) -> None:
+    write_json(TOKENS_JSON, {"username": username, "access": access, "refresh": refresh, "ts": int(time.time())})
+
+def set_env_access(access: str) -> None:
+    # For the current process (and children). Parent shell can't be set from here.
+    os.environ["MAIN_SEQUENCE_USER_TOKEN"] = access
+
+def backend_url() -> str:
+    cfg = get_config()
+    url = (cfg.get("backend_url") or DEFAULTS["backend_url"]).rstrip("/")
+    return url