@nidvue/teamwork 0.0.0-stage → 1.1.0

package/skills/teamwork/src/teamwork/gitutil.py

@@ -0,0 +1,172 @@
+"""Git plumbing used by the branch/PR/merge flow."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from .io import write_lf
+from .names import slugify
+
+DEFAULT_BASE = "main"
+
+LFS_PATTERNS = (
+    "*.png",
+    "*.jpg",
+    "*.jpeg",
+    "*.gif",
+    "*.webp",
+    "*.ico",
+    "*.bmp",
+    "*.tif",
+    "*.tiff",
+    "*.psd",
+    "*.ai",
+    "*.sketch",
+    "*.fig",
+    "*.mp4",
+    "*.mov",
+    "*.webm",
+    "*.mkv",
+    "*.avi",
+    "*.mp3",
+    "*.wav",
+    "*.flac",
+    "*.ogg",
+    "*.pdf",
+    "*.zip",
+    "*.tar",
+    "*.tar.gz",
+    "*.tgz",
+    "*.gz",
+    "*.bz2",
+    "*.7z",
+    "*.rar",
+    "*.whl",
+    "*.so",
+    "*.dylib",
+    "*.dll",
+    "*.a",
+    "*.o",
+    "*.jar",
+    "*.wasm",
+    "*.onnx",
+    "*.pt",
+    "*.pth",
+    "*.safetensors",
+    "*.ckpt",
+    "*.bin",
+    "*.gguf",
+    "*.parquet",
+    "*.arrow",
+    "*.feather",
+    "*.sqlite",
+    "*.db",
+    "*.ttf",
+    "*.otf",
+    "*.woff",
+    "*.woff2",
+    "*.glb",
+    "*.gltf",
+    "*.obj",
+    "*.fbx",
+    "*.blend",
+    "*.exr",
+    "*.hdr",
+    "*.unitypackage",
+)
+
+
+def run_git(project: Path, *argv: str):
+    return subprocess.run(["git", "-C", str(project), *argv], capture_output=True, text=True)
+
+
+def is_git_repo(project: Path) -> bool:
+    r = run_git(project, "rev-parse", "--is-inside-work-tree")
+    return r.returncode == 0 and r.stdout.strip() == "true"
+
+
+def current_branch(project: Path) -> str:
+    return run_git(project, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+
+
+def branch_exists(project: Path, branch: str) -> bool:
+    r = run_git(project, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
+    return r.returncode == 0
+
+
+def branch_merged(project: Path, branch: str, base: str = DEFAULT_BASE) -> bool:
+    if not branch or not branch_exists(project, branch):
+        return False
+    r = run_git(project, "branch", "--merged", base)
+    return any(line.strip().lstrip("* ").strip() == branch for line in r.stdout.splitlines())
+
+
+def branch_worktree(project: Path, branch: str):
+    """The worktree that has ``branch`` checked out, or ``None``."""
+    current = ""
+    for line in run_git(project, "worktree", "list", "--porcelain").stdout.splitlines():
+        if line.startswith("worktree "):
+            current = line.split(" ", 1)[1].strip()
+        elif line.strip() == f"branch refs/heads/{branch}" and current:
+            return Path(current)
+    return None
+
+
+def ensure_lfs(project: Path, quiet: bool = False) -> dict:
+    """Enable Git LFS locally and keep .gitattributes in sync."""
+    result = {"available": False, "installed": False, "patterns_added": 0}
+    probe = subprocess.run(["git", "lfs", "version"], capture_output=True, text=True)
+    if probe.returncode != 0:
+        if not quiet:
+            print(
+                "teamwork: WARNING git-lfs is not installed; large binaries will be"
+                " committed as plain blobs. Install git-lfs for archival."
+            )
+        return result
+    result["available"] = True
+    inst = subprocess.run(
+        ["git", "-C", str(project), "lfs", "install", "--local"], capture_output=True, text=True
+    )
+    result["installed"] = inst.returncode == 0
+
+    path = project / ".gitattributes"
+    existing = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    have = {line.split()[0] for line in existing if line.strip() and not line.startswith("#")}
+    missing = [pat for pat in LFS_PATTERNS if pat not in have]
+    if missing:
+        lines = list(existing)
+        if not any("teamwork: LFS" in line for line in lines):
+            lines += ["", "# --- teamwork: Git LFS tracked content ---"]
+        lines += [f"{pat} filter=lfs diff=lfs merge=lfs -text" for pat in missing]
+        write_lf(path, "\n".join(lines).rstrip() + "\n")
+        result["patterns_added"] = len(missing)
+    if not quiet:
+        print(
+            f"teamwork: git-lfs ready (local install={result['installed']}, "
+            f"{result['patterns_added']} pattern(s) added to .gitattributes)"
+        )
+    return result
+
+
+def lfs_tracked(project: Path, rel: str) -> bool:
+    path = project / ".gitattributes"
+    if not path.exists():
+        return False
+    name = Path(rel).name
+    for line in path.read_text(encoding="utf-8").splitlines():
+        parts = line.split()
+        if len(parts) >= 2 and "filter=lfs" in line:
+            pattern = parts[0]
+            if pattern.startswith("*."):
+                if name.endswith(pattern[1:]):
+                    return True
+            elif Path(rel).match(pattern):
+                return True
+    return False
+
+
+def branch_name(instance: str, task_id: str, title: str) -> str:
+    who = re.sub(r"[^a-z0-9]+", "-", (instance or "agent").lower()).strip("-")
+    return f"{who}/{task_id.lower()}-{slugify(title)}"

package/skills/teamwork/src/teamwork/imaging.py

@@ -0,0 +1,124 @@
+"""Offline image-model capability probe (no network, no prompt leak)."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+
+IMAGE_MODEL_RANKING = {
+    "openai": ("gpt-image-1", "dall-e-3"),
+    "google": (
+        "imagen-4.0-ultra-generate-001",
+        "imagen-4.0-generate-001",
+        "gemini-2.5-flash-image",
+    ),
+    "black-forest-labs": ("flux-1.1-pro", "flux-1-dev", "flux-1-schnell"),
+    "stability": ("stable-image-ultra", "sd3.5-large", "sd3.5-medium"),
+    "replicate": (
+        "black-forest-labs/flux-1.1-pro",
+        "stability-ai/stable-diffusion-3.5-large",
+    ),
+    "local": ("qwen-image-2.1", "sdxl", "sd3.5-large"),
+    "ollama-cloud": (),  # text/vision INPUT only as of 2026-10-17
+}
+
+IMAGE_PROVIDER_PRIORITY = (
+    "openai",
+    "google",
+    "black-forest-labs",
+    "stability",
+    "replicate",
+    "local",
+    "ollama-cloud",
+)
+
+IMAGE_PROVIDER_CREDENTIALS = {
+    "openai": ("OPENAI_API_KEY",),
+    "google": ("GEMINI_API_KEY", "GOOGLE_API_KEY"),
+    "black-forest-labs": ("BFL_API_KEY", "BLACK_FOREST_LABS_API_KEY"),
+    "stability": ("STABILITY_API_KEY",),
+    "replicate": ("REPLICATE_API_TOKEN",),
+    "ollama-cloud": ("OLLAMA_API_KEY",),
+}
+
+IMAGE_FALLBACK_HINT = (
+    "no cloud image model detected: fall back to a local model, then to a "
+    "hand-authored SVG (roles/designer.md, fallback ladder). Do not stall, and "
+    "do not report an image that was never generated."
+)
+
+
+def detect_image_provider(env=None) -> str:
+    """First provider in priority order that is configured and has a model."""
+    env = os.environ if env is None else env
+    for provider in IMAGE_PROVIDER_PRIORITY:
+        if provider == "local":
+            if shutil.which("qimg") or any(key.startswith("QIMG_") for key in env):
+                return provider
+            continue
+        if not IMAGE_MODEL_RANKING.get(provider):
+            continue
+        if any(env.get(name) for name in IMAGE_PROVIDER_CREDENTIALS.get(provider, ())):
+            return provider
+    return ""
+
+
+def resolve_image_model(env=None) -> dict:
+    """Decide which image generator to use, without touching the network."""
+    env = os.environ if env is None else env
+    override = (env.get("TEAMWORK_IMAGE_MODEL") or "").strip()
+    if override:
+        provider = (env.get("TEAMWORK_IMAGE_PROVIDER") or "custom").strip() or "custom"
+        return {
+            "provider": provider,
+            "model": override,
+            "ranked": [],
+            "source": "TEAMWORK_IMAGE_MODEL override",
+            "fallback": "",
+        }
+    explicit = (env.get("TEAMWORK_IMAGE_PROVIDER") or "").strip()
+    if explicit:
+        ranked = list(IMAGE_MODEL_RANKING.get(explicit, ()))
+        return {
+            "provider": explicit,
+            "model": ranked[0] if ranked else "",
+            "ranked": ranked,
+            "source": "TEAMWORK_IMAGE_PROVIDER",
+            "fallback": "" if ranked else IMAGE_FALLBACK_HINT,
+        }
+    provider = detect_image_provider(env)
+    ranked = list(IMAGE_MODEL_RANKING.get(provider, ()))
+    return {
+        "provider": provider,
+        "model": ranked[0] if ranked else "",
+        "ranked": ranked,
+        "source": "ambient environment" if provider else "none detected",
+        "fallback": "" if provider else IMAGE_FALLBACK_HINT,
+    }
+
+
+def cmd_imaging(args) -> int:
+    """`teamwork imaging probe` - which image model, if any, is available."""
+
+    decision = resolve_image_model()
+    if getattr(args, "json", False):
+        print(json.dumps({"command": "imaging.probe", **decision}, indent=2))
+        return 0
+    print("# imaging probe (offline: environment + PATH only)")
+    print(f"  provider:  {decision['provider'] or '-'}")
+    print(f"  model:     {decision['model'] or '-'}")
+    print(f"  source:    {decision['source']}")
+    if decision["ranked"]:
+        print("  ranked:    " + " > ".join(decision["ranked"]))
+    if decision["model"]:
+        print("  supports:  text-to-image, image-to-image")
+    else:
+        print("  supports:  none")
+    if decision["fallback"]:
+        print(f"  fallback:  {decision['fallback']}")
+    print(
+        "  policy:    roles/designer.md (plan, 4+ candidates, visual review,"
+        " improvement, privacy and licence red lines)"
+    )
+    return 0

package/skills/teamwork/src/teamwork/io.py

@@ -0,0 +1,144 @@
+"""Atomic file IO, the exclusive lock and the one error exit."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .portable import newline_for, pid_alive
+
+if TYPE_CHECKING:  # pragma: no cover
+    from typing import NoReturn
+
+
+LOCK_TIMEOUT = float(os.environ.get("TEAMWORK_LOCK_TIMEOUT", "60"))
+
+LOCK_STALE_SECONDS = float(os.environ.get("TEAMWORK_LOCK_STALE_SECONDS", "300"))
+
+
+def _lock_owner_stale(path: Path) -> bool:
+    """True only when the lock is clearly abandoned: old AND its owner is gone."""
+    try:
+        age = time.time() - path.stat().st_mtime
+        body = path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return False
+    if age < LOCK_STALE_SECONDS:
+        return False
+    pid = int(body.split(".", 1)[0]) if body.split(".", 1)[0].isdigit() else 0
+    if pid <= 0:
+        return True
+    # Portable liveness probe: on Windows os.kill(pid, 0) is not a probe, so
+    # this goes through the audited helper in teamwork.portable.
+    return not pid_alive(pid)
+
+
+@contextlib.contextmanager
+def lock(path: Path, timeout: float | None = None):
+    """Exclusive lock via O_CREAT|O_EXCL. Never steals a live lock, and only
+    removes the lock file if this process owns it."""
+    if timeout is None:
+        timeout = LOCK_TIMEOUT
+    path.parent.mkdir(parents=True, exist_ok=True)
+    token = f"{os.getpid()}.{time.time():.6f}"
+    deadline = time.monotonic() + max(timeout, 0.0)
+    while True:
+        try:
+            fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.write(fd, token.encode())
+            os.close(fd)
+            break
+        except FileExistsError:
+            if _lock_owner_stale(path):
+                try:
+                    os.unlink(str(path))
+                    continue
+                except OSError:
+                    pass
+            if time.monotonic() > deadline:
+                die(
+                    f"timed out after {int(timeout)}s waiting for {path.name}. "
+                    "Another agent holds it. Wait, or clear it only if the owner "
+                    "is gone. Never delete a lock that is still in use.",
+                    4,
+                )
+            time.sleep(0.05)
+    try:
+        yield
+    finally:
+        try:
+            if path.read_text(encoding="utf-8").strip() == token:
+                path.unlink()
+        except OSError:
+            pass
+
+
+def atomic_write(path: Path, text: str) -> None:
+    """Write via a unique temp file in the same directory, then rename.
+
+    Windows rejects ``os.replace`` while another process has the target open, so
+    the rename is retried briefly. The original mode is preserved because
+    ``mkstemp`` creates a 0600 file, which would otherwise make a previously
+    group-readable workspace file private after the first rewrite.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        try:
+            mode = path.stat().st_mode & 0o777
+        except OSError:
+            mode = 0o644
+    else:
+        # Respect the caller's umask instead of forcing a world-readable file.
+        current_umask = os.umask(0)
+        os.umask(current_umask)
+        mode = 0o666 & ~current_umask
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=path.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline=newline_for()) as fh:
+            fh.write(text)
+        try:
+            os.chmod(tmp, mode)
+        except OSError:
+            pass
+        for attempt in range(5):
+            try:
+                os.replace(tmp, str(path))
+                break
+            except PermissionError:
+                if attempt == 4:
+                    raise
+                time.sleep(0.05 * (attempt + 1))
+            except OSError:
+                # Windows file-sharing violations are not always PermissionError.
+                if os.name != "nt" or attempt == 4:
+                    raise
+                time.sleep(0.05 * (attempt + 1))
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def write_lf(path: Path, text: str, encoding: str = "utf-8") -> None:
+    """Write ``text`` with LF newlines on every platform and every Python >= 3.9.
+
+    ``Path.write_text(..., newline=...)`` only exists from Python 3.10, and this
+    package supports 3.9 (CI runs the matrix on 3.9), so the file is opened here
+    directly. On Windows the default text mode would translate ``\n`` to CRLF and
+    a clone would no longer be byte-identical across platforms.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding=encoding, newline="\n") as handle:
+        handle.write(text)
+
+
+def die(msg: str, code: int = 1) -> NoReturn:
+    print(f"teamwork: {msg}", file=sys.stderr)
+    raise SystemExit(code)

package/skills/teamwork/src/teamwork/layout.py

@@ -0,0 +1,253 @@
+"""Workspace layout: the team tree, committed docs and their links."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .config import (
+    DIR_AGENTS,
+    DIR_DOCS,
+    DIR_GLOBAL,
+    DIR_ROLES,
+    DIR_RUNTIME,
+    DIR_WORKTREES,
+    F_CRITERIA,
+    F_DISPUTES,
+    F_GLOBAL,
+    F_GLOBAL_ARCHIVE,
+    F_INBOX,
+    F_LONG,
+    F_MAP,
+    F_MEM_ARCHIVE,
+    F_REVIEWS,
+    F_ROLE,
+    F_SHORT,
+    F_SKILLS,
+    F_TASKS,
+    F_TESTPLAN,
+    F_TESTS,
+    F_WORKLOG,
+    SKILLS_DIR,
+    TEAM_ROOT_DIR,
+    TEAMS_SUBDIR,
+)
+from .io import die
+from .names import pascal, resolve_role, safe_component, team_slug
+
+
+def project_path(args) -> Path:
+    if getattr(args, "project", None):
+        return Path(args.project).expanduser().resolve()
+    return Path.cwd()
+
+
+def project_of(root: Path) -> Path:
+    """<project>/.pi/Teamwork/Teams/<Team> -> <project>."""
+    return root.parents[3]
+
+
+def docs_dir(root: Path) -> Path:
+    """Committed project output. The team's own tree stays in .pi/Teamwork."""
+    return project_of(root).joinpath(*DIR_DOCS)
+
+
+def work_repo(root: Path, cwd: Path | None = None) -> Path:
+    """The git work tree this command should act on.
+
+    Inside one of our per-instance worktrees that worktree is the answer;
+    otherwise it is the project that owns the team tree.
+    """
+    cwd = (cwd or Path.cwd()).resolve()
+    wt_root = root / DIR_RUNTIME / DIR_WORKTREES
+    if wt_root.is_dir():
+        for parent in [cwd, *cwd.parents]:
+            try:
+                rel = parent.relative_to(wt_root)
+            except ValueError:
+                continue
+            if rel.parts:
+                cand = wt_root / rel.parts[0]
+                if (cand / ".git").exists():
+                    return cand
+    return project_of(root)
+
+
+def team_root_from_cwd(cwd: Path) -> Path | None:
+    """If we are inside one of our own worktrees, use the team that owns it.
+
+    `<team>/Runtime/Worktrees/<Instance>/...` -> `<team>`; anything else -> None.
+    Without this, running a command from a worktree would look for (and create)
+    a second, unrelated team tree.
+    """
+    for parent in [cwd, *cwd.parents]:
+        if parent.name == DIR_WORKTREES and parent.parent.name == DIR_RUNTIME:
+            candidate = parent.parent.parent
+            if (candidate / DIR_ROLES).is_dir() or (candidate / F_MAP).exists():
+                return candidate
+    return None
+
+
+def project_root(args) -> Path:
+    """The current team's hidden tree:
+    <project>/.pi/Teamwork/Teams/<Team>/"""
+    if os.environ.get("TEAMWORK_ROOT"):
+        return Path(os.environ["TEAMWORK_ROOT"]).expanduser().resolve()
+    if not getattr(args, "project", None):
+        found = team_root_from_cwd(Path.cwd().resolve())
+        if found is not None:
+            return found
+    project = project_path(args)
+    slug = team_slug(project, getattr(args, "team", "") or "")
+    return (project / TEAM_ROOT_DIR / TEAMS_SUBDIR / slug).resolve()
+
+
+def teams_root_unused(project: Path) -> Path:
+    return project / TEAM_ROOT_DIR / TEAMS_SUBDIR
+
+
+def agents_dir(root: Path) -> Path:
+    return root / DIR_AGENTS
+
+
+def agent_dir(root: Path, agent: str) -> Path:
+    """An instance directory: private scratch, artifacts, reports, worklog."""
+    return agents_dir(root) / safe_component(pascal(agent))
+
+
+def roles_dir(root: Path) -> Path:
+    return root / DIR_ROLES
+
+
+def role_dir(root: Path, role: str) -> Path:
+    """A role directory: memory and the task list, SHARED by every instance of
+    that role. developer-1 and developer-2 share one memory and one queue."""
+    return roles_dir(root) / safe_component(pascal(resolve_role(role)))
+
+
+def global_dir(root: Path) -> Path:
+    return root / DIR_GLOBAL
+
+
+def list_agents(root: Path) -> list:
+    """Instance names (developer-1, developer-2, ...)."""
+    d = agents_dir(root)
+    if not d.is_dir():
+        return []
+    return sorted(p.name for p in d.iterdir() if p.is_dir())
+
+
+def list_roles(root: Path) -> list:
+    """Canonical role slugs that own a shared memory + task queue."""
+    d = roles_dir(root)
+    if not d.is_dir():
+        return []
+    return sorted({resolve_role(p.name) for p in d.iterdir() if p.is_dir()})
+
+
+def instances_of(root: Path, role: str) -> list:
+    role = resolve_role(role)
+    return [n for n in list_agents(root) if resolve_role(n) == role]
+
+
+def known_instances(root: Path) -> list:
+    return sorted(i for r in list_roles(root) for i in instances_of(root, r))
+
+
+def team_root_from(path: Path) -> Path:
+    """Recover the team root from any generated file inside the team tree.
+
+    Roles/<Role>/X -> root ; Agents/<I>/X -> root ; Global/X -> root ; root/X -> root
+    """
+    parent = path.parent
+    if parent.parent.name in (DIR_ROLES, DIR_AGENTS):
+        return parent.parent.parent
+    if parent.name == DIR_GLOBAL:
+        return parent.parent
+    return parent
+
+
+def _rel(path: Path, target: Path) -> str:
+    return os.path.relpath(target, start=path.parent).replace(os.sep, "/")
+
+
+def link_fields(path: Path, owner: str) -> dict:
+    """Relative links that stay correct at any depth in the team tree."""
+    root = team_root_from(path)
+    role = resolve_role(owner)
+    docs = docs_dir(root) if root.parent.name == TEAMS_SUBDIR else root
+    return {
+        "tasks": _rel(path, role_dir(root, role) / F_TASKS),
+        "short": _rel(path, role_dir(root, role) / F_SHORT),
+        "long": _rel(path, role_dir(root, role) / F_LONG),
+        "mem_archive": _rel(path, role_dir(root, role) / F_MEM_ARCHIVE),
+        "role": _rel(path, role_dir(root, role) / F_ROLE),
+        "global_mem": _rel(path, global_dir(root) / F_GLOBAL),
+        "global_archive": _rel(path, global_dir(root) / F_GLOBAL_ARCHIVE),
+        "disputes": _rel(path, root / F_DISPUTES),
+        "map": _rel(path, root / F_MAP),
+        "project": _rel(path, docs / "Project.md"),
+        "plan": _rel(path, docs / "Plan.md"),
+        "architecture": _rel(path, docs / "Architecture.md"),
+        "decisions": _rel(path, docs / "Decisions.md"),
+        "archive": _rel(path, docs / "Archive.md"),
+        "board": _rel(path, docs / "Board.md"),
+        "worklog": _rel(path, path.parent / F_WORKLOG),
+        "inbox": _rel(path, path.parent / F_INBOX),
+        "Role": pascal(role),
+    }
+
+
+def criteria_path(root: Path) -> Path:
+    return root / F_CRITERIA
+
+
+def tests_path(root: Path) -> Path:
+    return root / F_TESTS
+
+
+def testplan_path(root: Path) -> Path:
+    return root / F_TESTPLAN
+
+
+def reviews_path(root: Path) -> Path:
+    return root / F_REVIEWS
+
+
+def disputes_path(root: Path) -> Path:
+    return root / F_DISPUTES
+
+
+def skills_path(root: Path) -> Path:
+    return root / F_SKILLS
+
+
+def task_file(root: Path, agent: str) -> Path:
+    """The role's shared queue. Any instance of the role may claim from it."""
+    role = resolve_role(agent)
+    d = role_dir(root, role)
+    if not d.is_dir() and not agents_dir(root).is_dir():
+        die("no workspace here: run `teamwork.py init` first")
+    if agents_dir(root).is_dir() and not d.is_dir():
+        known = list_roles(root)
+        if role not in known:
+            die(
+                f"no '{role}' role in this team. Known roles: "
+                + (", ".join(known) if known else "(none)")
+            )
+    d.mkdir(parents=True, exist_ok=True)
+    return d / F_TASKS
+
+
+def skills_dir(root: Path) -> Path:
+    """Where team skills are written: the work tree this agent is actually in."""
+    return work_repo(root).joinpath(*SKILLS_DIR)
+
+
+def skill_file(root: Path, rel: str) -> Path:
+    """Locate a registered skill file from either the work tree or the project."""
+    for base in (work_repo(root), project_of(root)):
+        p = base / rel
+        if p.exists():
+            return p
+    return work_repo(root) / rel