Skip to content

flurdy/agent-skills / skills/next

Rank ready beads across validated workspace stores or one local store. List read-only, or claim one selected bead, show its details, and continue into its work.

scripts/collect.py

View on GitHub
#!/usr/bin/env python3
from __future__ import annotations

import json
import os
import re
import shlex
import subprocess
import sys
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from pathlib import Path
from time import monotonic
from typing import Any

COMMAND_TIMEOUT_SECONDS = 5
BEADS_READ_TIMEOUT_ENV = "NEXT_BEADS_READ_TIMEOUT_SECONDS"
MISSING_STORE_ERROR = "missing .beads store"
DOLT_UNREACHABLE = re.compile(r"Dolt server (?:unreachable|may not be running)", re.IGNORECASE)
REGISTRATION_NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
DEFER_UNTIL = re.compile(
    r"^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$"
)
RELATIONS = ("parent", "blocked by", "unblocks", "child", "sibling", "related",
             "discovered from", "discovered here")
EDGE_RELATIONS = {
    ("down", "blocks"): "blocked by",
    ("up", "blocks"): "unblocks",
    ("up", "parent-child"): "child",
    ("down", "relates-to"): "related",
    ("up", "relates-to"): "related",
    ("down", "related"): "related",
    ("up", "related"): "related",
    ("down", "discovered-from"): "discovered from",
    ("up", "discovered-from"): "discovered here",
}
MANAGED_DIRECTORIES = (
    "docs",
    "docs/prds",
    "docs/adrs",
    "docs/architecture",
    "docs/runbooks",
    "repos",
    "infrastructure",
)


@dataclass(frozen=True)
class Source:
    name: str
    relative_path: str
    directory: Path
    store: str = "local"
    declaration_error: str | None = None
    store_declared: bool = False


def beads_read_timeout() -> int:
    value = os.environ.get(BEADS_READ_TIMEOUT_ENV, "60")
    if not re.fullmatch(r"[0-9]{1,3}", value) or not 1 <= int(value) <= 120:
        raise ValueError(f"{BEADS_READ_TIMEOUT_ENV} must be an integer from 1 to 120 seconds")
    return int(value)


def is_nested(path: Path, parent: Path) -> bool:
    try:
        path.relative_to(parent)
    except ValueError:
        return False
    return True


def is_git_root(directory: Path) -> bool:
    try:
        result = subprocess.run(
            ["git", "-C", str(directory), "rev-parse", "--show-toplevel"],
            capture_output=True,
            check=False,
            text=True,
            timeout=COMMAND_TIMEOUT_SECONDS,
        )
    except (OSError, subprocess.TimeoutExpired):
        return False
    return result.returncode == 0 and Path(result.stdout.strip()).resolve() == directory.resolve()


def text_file(path: Path) -> str | None:
    if path.is_symlink() or not path.is_file():
        return None
    try:
        return path.read_text(encoding="utf-8")
    except (OSError, UnicodeError):
        return None


def entry_summary(entries: list[dict[str, Any]], empty: str) -> str:
    if not entries:
        return empty
    lines = []
    for entry in entries:
        suffix = f" ({entry['role']})" if entry.get("role") else ""
        lines.append(
            f"- `{entry['name']}` — [`{entry['path']}`]({entry['path']}){suffix}"
        )
    return "\n".join(lines)


def legacy_readme(manifest: dict[str, Any]) -> str | None:
    if manifest["infrastructure"]:
        return None
    name = manifest["name"]
    repositories = entry_summary(
        manifest["repositories"], "_No repositories are registered yet._"
    )
    return f"""# {name} Workspace

This workspace holds cross-project context and tracking for **{name}**.
Implementation remains in the repositories linked below.

## Start here

- [`workspace.json`](workspace.json) is the machine-readable topology index.
- [`AGENTS.md`](AGENTS.md) defines workspace-level agent guidance.
- [`docs/prds/`](docs/prds/) contains cross-project product requirements.
- [`docs/adrs/`](docs/adrs/) contains cross-project architecture decisions.
- [`docs/architecture/`](docs/architecture/) contains architecture context.
- [`docs/runbooks/`](docs/runbooks/) contains cross-project operational guidance.

## Repositories

{repositories}

For a greenfield workspace, link the first repository under `repos/` and add its
relative path to `workspace.json` when it exists. Repository-specific instructions and """ \
        """documentation remain authoritative inside each
repository. Infrastructure repositories or configuration may be linked under
[`infrastructure/`](infrastructure/) and indexed in `workspace.json`.

## Commands

```bash
make help
make status
make doctor
```

Use `bd` from this root for durable cross-project work. Configure multi-repository Git
operations separately with `/setup-multirepo-git` when needed.
"""


def readme_matches_manifest(readme: str, manifest: dict[str, Any]) -> bool:
    sections = {
        "repositories": entry_summary(
            manifest["repositories"], "_No repositories are registered yet._"
        ),
        "infrastructure": entry_summary(
            manifest["infrastructure"],
            "_No infrastructure references are registered yet._",
        ),
    }
    markers = [
        f"<!-- project-workspace:{collection}:{boundary} -->"
        for collection in sections
        for boundary in ("start", "end")
    ]
    if all(readme.count(marker) == 1 for marker in markers):
        return all(
            (
                f"<!-- project-workspace:{collection}:start -->\n"
                f"{content}\n"
                f"<!-- project-workspace:{collection}:end -->"
            )
            in readme
            for collection, content in sections.items()
        )
    if any(marker in readme for marker in markers):
        return False
    return readme == legacy_readme(manifest)


def valid_workspace_root(root: Path) -> bool:
    git_path = root / ".git"
    beads_path = root / ".beads"
    if root.is_symlink() or git_path.is_symlink() or beads_path.is_symlink():
        return False
    if not is_git_root(root) or not beads_path.is_dir():
        return False
    for relative_path in MANAGED_DIRECTORIES:
        directory = root / relative_path
        if not directory.is_dir() or directory.is_symlink():
            return False
    return all(
        text_file(root / filename) is not None
        for filename in ("README.md", "AGENTS.md", "Makefile")
    )


def registered_sources(root: Path, manifest: dict[str, Any]) -> list[Source] | None:
    if manifest.get("version") != 1 or not isinstance(manifest.get("name"), str):
        return None
    if not manifest["name"].strip() or "\n" in manifest["name"] or "\r" in manifest["name"]:
        return None
    if not valid_workspace_root(root):
        return None

    names: set[str] = set()
    targets: set[Path] = set()
    expected_links: set[Path] = set()
    repositories: list[Source] = []
    physical_root = root.resolve()

    for collection, directory_name in (
        ("repositories", "repos"),
        ("infrastructure", "infrastructure"),
    ):
        directory = root / directory_name
        entries = manifest.get(collection)
        if not directory.is_dir() or directory.is_symlink() or not isinstance(entries, list):
            return None
        for entry in entries:
            if not isinstance(entry, dict):
                return None
            name = entry.get("name")
            relative_path = entry.get("path")
            if not isinstance(name, str) or not isinstance(relative_path, str):
                return None
            if not REGISTRATION_NAME.fullmatch(name) or name in names:
                return None
            if relative_path != f"{directory_name}/{name}":
                return None
            if collection == "repositories" and entry.get("role") not in {"primary", "service"}:
                return None

            names.add(name)
            link = root / relative_path
            expected_links.add(link)
            if not link.is_symlink() or os.path.isabs(os.readlink(link)) or not link.is_dir():
                return None
            target = link.resolve()
            if is_nested(target, physical_root) or is_nested(physical_root, target):
                return None
            if target in targets:
                return None
            targets.add(target)
            if collection == "repositories":
                if not is_git_root(target):
                    return None
                store = entry.get("beadsStore", "local")
                error = None
                if store not in ("local", "workspace"):
                    error = "invalid beadsStore declaration: expected local or workspace"
                    store = "local"
                repositories.append(Source(
                    name, relative_path, link, store, error,
                    store_declared="beadsStore" in entry,
                ))

        if any(
            child.name != ".gitkeep" and child not in expected_links
            for child in directory.iterdir()
        ):
            return None

    readme = text_file(root / "README.md")
    if readme is None or not readme_matches_manifest(readme, manifest):
        return None
    return [Source("workspace", ".", root), *repositories]


def discover_sources(root: Path) -> tuple[bool, list[Source]]:
    manifest_path = root / "workspace.json"
    if not manifest_path.is_file() or manifest_path.is_symlink():
        return False, [Source("local", ".", root)]
    try:
        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
    except (OSError, UnicodeError, json.JSONDecodeError):
        return False, [Source("local", ".", root)]
    if not isinstance(manifest, dict):
        return False, [Source("local", ".", root)]
    sources = registered_sources(root, manifest)
    if sources is None:
        return False, [Source("local", ".", root)]
    return True, sources


def concise_text(text: str) -> str:
    return text.strip().replace("\n", " ")[:240]


def diagnostic_text(result: subprocess.CompletedProcess[str]) -> str:
    return concise_text(result.stderr or result.stdout) or f"bd exited {result.returncode}"


def store_error(source: Source) -> str | None:
    if source.declaration_error is not None:
        return source.declaration_error
    beads = source.directory / ".beads"
    if source.store == "workspace":
        if os.path.lexists(beads):
            return "unexpected .beads store for workspace-owned repository"
        return None
    if beads.is_symlink():
        return "unusable .beads store: symlink"
    if not beads.exists():
        return MISSING_STORE_ERROR
    if not beads.is_dir():
        return "unusable .beads store: not a directory"
    return None


def unavailable_store(source: Source, reason: str) -> dict[str, Any]:
    hint = None
    if DOLT_UNREACHABLE.search(reason):
        command = f"bd -C {shlex.quote(str(source.directory))} dolt start"
        hint = (f"Dolt server unreachable. `/next recover {source.name}` checks eligibility "
                f"and asks for confirmation before one local start. "
                f"Manual command (not executed): `{command}`. Listing remains read-only.")
    return {"repository": source.name, "reason": reason, "hint": hint}


def load_issues(source: Source, arguments: list[str]) -> tuple[list[dict[str, Any]], str | None]:
    timeout = beads_read_timeout()
    started = monotonic()
    try:
        result = subprocess.run(
            ["bd", "-C", str(source.directory), *arguments, "--json", "--readonly"],
            cwd=source.directory,
            capture_output=True,
            check=False,
            text=True,
            timeout=timeout,
        )
    except subprocess.TimeoutExpired:
        return [], (f"Beads read timed out (elapsed {monotonic() - started:.2f}s, "
                    f"deadline {timeout}s; {BEADS_READ_TIMEOUT_ENV})")
    except OSError as error:
        return [], concise_text(str(error))
    if result.returncode != 0:
        return [], diagnostic_text(result)
    try:
        issues = json.loads(result.stdout)
    except json.JSONDecodeError as error:
        return [], f"invalid bd JSON: {error}"
    if not isinstance(issues, list) or not all(
        isinstance(issue, dict) and isinstance(issue.get("id"), str) and issue["id"].strip()
        for issue in issues
    ):
        return [], "invalid bd JSON: expected an issue list with non-empty IDs"
    return issues, None


def owned_issues(
    source: Source, issues: list[dict[str, Any]], workspace: bool
) -> list[dict[str, Any]]:
    if not workspace:
        return issues
    return [
        {
            **issue,
            "repository": source.name,
            "repository_path": source.relative_path,
            "selector": f"{source.name}:{issue.get('id', '')}",
        }
        for issue in issues
    ]


def declared_source_scope(issue: dict[str, Any], source: Source) -> dict[str, Any]:
    def result(state: str, reason: str, roots: list[str] | None = None) -> dict[str, Any]:
        return {"state": state, "reason": reason, "roots": roots or []}

    metadata = issue.get("metadata")
    if metadata is None or isinstance(metadata, dict) and "source_scope" not in metadata:
        return result("unknown", "source scope is undeclared")
    scope = metadata.get("source_scope") if isinstance(metadata, dict) else None
    if not isinstance(scope, dict) or set(scope) != {"version", "complete", "roots"}:
        return result("invalid", "expected source_scope version, complete and roots")
    roots = scope["roots"]
    if (
        type(scope["version"]) is not int or scope["version"] != 1
        or type(scope["complete"]) is not bool
        or not isinstance(roots, list) or not 1 <= len(roots) <= 32
        or any(not isinstance(root, str) or not root or len(root) > 4096
               or Path(root).is_absolute() or root.startswith("~")
               or any(ord(char) < 32 or 127 <= ord(char) <= 159 for char in root)
               for root in roots)
    ):
        return result("invalid", "invalid or oversized source_scope v1 declaration")
    if store_error(source) is not None or os.path.lexists(source.directory / ".beads" / "redirect"):
        return result("unavailable", "source-scope base is not a usable non-redirected store root")
    canonical = []
    try:
        for root in roots:
            path = (source.directory.resolve() / root).resolve(strict=True)
            if not path.is_dir():
                return result("invalid", "source roots must be directories")
            if str(path) not in canonical:
                canonical.append(str(path))
    except (OSError, RuntimeError):
        return result("unavailable", "a declared source path cannot be resolved")
    return result(
        "declared" if scope["complete"] else "partial",
        "explicit complete declaration; Git roots not yet observed" if scope["complete"]
        else "source scope is explicitly incomplete",
        canonical,
    )


def service_names(source: Source, workspace: bool) -> dict[str, str]:
    directories = [source.directory]
    if workspace and source.relative_path == ".":
        directories += [source.directory / "repos", source.directory / "infrastructure"]
    names: dict[str, str] = {}
    for directory in directories:
        try:
            for child in directory.iterdir():
                if child.is_dir() and not child.name.startswith("."):
                    names.setdefault(child.name, str(child.resolve()))
        except OSError:
            continue
    return names


def service_labels(issue: dict[str, Any], services: dict[str, str]) -> list[str]:
    labels = issue.get("labels")
    if not isinstance(labels, list):
        return []
    return [label for label in labels if isinstance(label, str) and label in services]


def defer_elapsed(value: Any, now: datetime) -> bool | None:
    """True when a timezone-aware defer_until instant is at or before now; None when absent or unparseable."""
    match = DEFER_UNTIL.fullmatch(value) if isinstance(value, str) else None
    if match is None:
        return None
    *fields, fraction, offset = match.groups()
    try:
        if offset == "Z":
            zone = timezone.utc
        else:
            sign = 1 if offset[0] == "+" else -1
            zone = timezone(sign * timedelta(hours=int(offset[1:3]), minutes=int(offset[4:6])))
        instant = datetime(*map(int, fields), int((fraction or "0")[:6].ljust(6, "0")), tzinfo=zone)
    except ValueError:
        return None
    return instant <= now


def machine_identity() -> dict[str, Any]:
    path = Path.home() / ".agents" / "AGENTS.local.md"
    result: dict[str, Any] = {"id": None, "source": str(path), "state": "missing",
                              "reason": "machine declaration is missing"}
    try:
        lines = path.read_text(encoding="utf-8").splitlines()
    except FileNotFoundError:
        return result
    except (OSError, UnicodeError):
        return {**result, "state": "invalid", "reason": "machine context is unreadable"}
    identities = set()
    fence = ""
    for line in lines:
        marker = re.match(r"^\s*(`{3,}|~{3,})", line)
        if marker:
            if not fence:
                fence = marker[1]
            elif marker[1][0] == fence[0] and len(marker[1]) >= len(fence):
                fence = ""
            continue
        if fence or not re.match(r"^\s*(?:[-*]\s*)?Machine\b", line, re.IGNORECASE):
            continue
        match = re.fullmatch(r"\s*-\s+Machine:\s*([A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\.?\s*", line, re.IGNORECASE)
        if not match:
            return {**result, "state": "invalid", "reason": "expected - Machine: stable-id"}
        identities.add(match[1].lower())
    if len(identities) > 1:
        return {**result, "state": "conflict", "reason": "conflicting machine declarations"}
    if identities:
        return {**result, "id": identities.pop(), "state": "ok", "reason": "user local context"}
    return result


def machine_eligibility(issue: dict[str, Any], machine: dict[str, Any]) -> dict[str, Any]:
    labels = issue.get("labels") or []
    required = []
    invalid = not isinstance(labels, list)
    for label in labels if isinstance(labels, list) else []:
        if not isinstance(label, str):
            invalid = True
            continue
        if not label.strip().lower().startswith("run-on"):
            continue
        match = re.fullmatch(r"run-on:([a-z0-9]+(?:-[a-z0-9]+)*)", label, re.IGNORECASE)
        if not match:
            invalid = True
        elif match[1].lower() not in required:
            required.append(match[1].lower())
    if invalid:
        state, reason = "invalid", "malformed run-on label"
    elif not required:
        state, reason = "unrestricted", "no declared machine restriction"
    elif machine["id"] is None:
        state, reason = "unknown", "machine identity unknown; requires " + ", ".join(required)
    elif machine["id"] in required:
        state, reason = "match", "matches " + machine["id"]
    else:
        state, reason = "mismatch", "requires " + ", ".join(required)
    return {"eligible": state in {"unrestricted", "match"}, "state": state,
            "required": required, "reason": reason}


def related_view(
    source: Source, issue_ids: list[str], workspace: bool
) -> tuple[list[dict[str, Any]], str | None]:
    """One-hop graph context for focus issues in one store; closed rows omitted except parents."""
    now = datetime.now(timezone.utc)
    ready, error = load_issues(source, ["list", "--ready", "--flat", "--limit=0"])
    blocked, blocked_error = load_issues(source, ["blocked"])
    if error or blocked_error:
        return [], f"ready: {error}" if error else f"blocked: {blocked_error}"
    ready_ids = {row["id"] for row in ready}
    blocked_by = {row["id"]: row.get("blocked_by") or [] for row in blocked}

    def described(row: dict[str, Any]) -> dict[str, Any]:
        status = row.get("status")
        state = (status if status in {"closed", "in_progress", "deferred"}
                 else "blocked" if row["id"] in blocked_by
                 else "ready" if row["id"] in ready_ids else status or "open")
        extra: dict[str, Any] = {"state": state}
        if state == "blocked":
            extra["blocked_by"] = blocked_by[row["id"]]
        if state == "deferred":
            extra["defer_elapsed"] = defer_elapsed(row.get("defer_until"), now)
        return {**row, **extra}

    views = []
    for issue_id in issue_ids:
        error = None
        edges: dict[str, list[dict[str, Any]]] = {}
        for direction in ("down", "up"):
            if error is None:
                edges[direction], error = load_issues(
                    source, ["dep", "list", issue_id, f"--direction={direction}"])
        parent = next((row for row in edges.get("down", [])
                       if row.get("dependency_type") == "parent-child"), None)
        children: list[dict[str, Any]] = []
        if error is None and parent is not None:
            children, error = load_issues(source, [
                "dep", "list", parent["id"], "--direction=up", "--type=parent-child"])
        if error is not None:
            return [], f"{issue_id}: {error}"

        links = [(row, EDGE_RELATIONS.get((direction, row.get("dependency_type"))))
                 for direction, rows in edges.items() for row in rows]
        links += [(parent, "parent")] if parent is not None else []
        links += [(child, "sibling") for child in children]
        relations: dict[str, tuple[set[str], dict[str, Any]]] = {}
        for row, relation in links:
            if relation is not None and row["id"] != issue_id:
                relations.setdefault(row["id"], (set(), row))[0].add(relation)

        wanted = [issue_id, *(row_id for row_id, (names, row) in relations.items()
                              if row.get("status") != "closed" or "parent" in names)]
        # Dependency rows omit parent and may omit defer dates; show records are authoritative.
        shown, error = load_issues(source, ["show", *(f"--id={row_id}" for row_id in wanted)])
        records = {row["id"]: row for row in shown}
        if error is None and set(records) != set(wanted):
            error = "bd show did not return every related issue"
        if error is not None:
            return [], f"{issue_id}: {error}"
        related = []
        for row_id in wanted[1:]:
            names = relations[row_id][0]
            related.append({**described(records[row_id]),
                            "relations": sorted(names, key=RELATIONS.index)})
        related.sort(key=lambda row: (RELATIONS.index(row["relations"][0]),
                                      99 if row.get("priority") is None else row["priority"],
                                      row.get("created_at") or "",
                                      row["id"]))
        progress = None
        if parent is not None:
            progress = {"closed": sum(child.get("status") == "closed" for child in children),
                        "total": len(children)}
        views.append({
            **owned_issues(source, [described(records[issue_id])], workspace)[0],
            "parent_progress": progress,
            "related": owned_issues(source, related, workspace),
        })
    return views, None


def collect(root: Path, source_scope: bool = False) -> dict[str, Any]:
    beads_read_timeout()
    now = datetime.now(timezone.utc)
    workspace, sources = discover_sources(root)
    payload: dict[str, Any] = {
        "workspace": workspace,
        "machine": machine_identity(),
        "ready": [],
        "blocked": [],
        "in_progress": [],
        "deferred": [],
        "diagnostics": [],
        "unavailable_stores": [],
    }
    commands = {
        "ready": ["list", "--ready", "--flat", "--limit=0"],
        "blocked": ["blocked"],
        "in_progress": ["list", "--status=in_progress", "--flat", "--limit=0"],
        "deferred": ["list", "--status=deferred", "--flat", "--limit=0"],
    }
    for source in sources:
        error = store_error(source)
        if workspace and error is not None:
            payload["diagnostics"].append(f"{source.name}: {error}")
            payload["unavailable_stores"].append(unavailable_store(source, error))
            continue
        if source.store == "workspace":
            continue
        collected: dict[str, list[dict[str, Any]]] = {}
        services = service_names(source, workspace) if source_scope else {}
        for key, arguments in commands.items():
            issues, error = load_issues(source, arguments)
            if error is not None:
                payload["diagnostics"].append(f"{source.name}: {key}: {error}")
                payload["unavailable_stores"].append(unavailable_store(source, f"{key}: {error}"))
                break
            collected[key] = owned_issues(source, issues, workspace)
            if source_scope:
                collected[key] = [
                    {**issue, "repository": source.name, "selector": f"{source.name}:{issue['id']}",
                     "source_scope": declared_source_scope(issue, source),
                     "services": service_labels(issue, services),
                     "service_roots": [services[label] for label in service_labels(issue, services)]}
                    for issue in collected[key]
                ]
        else:
            for key, issues in collected.items():
                payload[key].extend(issues)
    payload["ready"] = [
        {**issue, "machine_eligibility": machine_eligibility(issue, payload["machine"])}
        for issue in payload["ready"]
    ]
    payload["deferred"] = [
        {**issue, "defer_elapsed": defer_elapsed(issue.get("defer_until"), now)}
        for issue in payload["deferred"]
    ]
    return payload


def main() -> int:
    try:
        payload = collect(Path.cwd(), source_scope="--source-scope" in sys.argv[1:])
    except ValueError as error:
        print(f"next-bd: {error}", file=sys.stderr)
        return 2
    json.dump(payload, sys.stdout, separators=(",", ":"))
    sys.stdout.write("\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall