repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

scripts/extensions.py

Raw
#!/usr/bin/env python3
"""Pi extension repo workflow."""

from __future__ import annotations

import argparse
import importlib.util
import json
import re
import shutil
import subprocess
import sys
import tempfile
import textwrap
import time
from pathlib import Path
from types import ModuleType

ROOT = Path(__file__).resolve().parents[1]
EXT_ROOT = ROOT / "extensions"
DRIVER_ROOT = ROOT / "drivers"
PI_PEERS = {
    "@earendil-works/pi-ai",
    "@earendil-works/pi-agent-core",
    "@earendil-works/pi-coding-agent",
    "@earendil-works/pi-tui",
    "typebox",
}
HARNESS = "@marcfargas/pi-test-harness"
ROOT_INSTALL_DONE = False
IMPORT_RE = re.compile(
    r"(?:import|export)\s+(?:[^'\"]+?\s+from\s+)?['\"]([^'\"]+)['\"]|import\(['\"]([^'\"]+)['\"]\)"
)
SECRET_RE = re.compile(r"(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]{12,}", re.I)
OSC_RE = re.compile(r"\x1b\][^\x07]*(?:\x07|\x1b\\)")
ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")

CHANGELOG_STYLE = """Voice:
- terse, technical, human
- brutal minimalism: no marketing, no excitement, no filler
- concrete nouns/verbs; name actual commands, tools, hooks, files, API
- no corporate adjectives: enhanced, improved, streamlined, robust, seamless
- also ban: powerful, comprehensive, leverage
- no vague "various fixes"
- write like a maintainer note, not an ad
- short fragments beat full sentences

Hard format:
## {version}

- bullet
- bullet

Hard limits:
- 3-5 bullets total
- max 100 chars per bullet; rewrite until every bullet fits
- each bullet must start with a verb, command name, or concrete noun
- combine details; do not enumerate implementation internals separately
- omit internal function names unless they are the change users maintain
"""

README_STYLE = """Return the full root README.md content for bugabinga/pi-ext.
Use only the context in this prompt. Do not edit files.
Do not say done. Do not summarize. Output the complete markdown file only.

Task:
- If root README.md exists: update it; preserve useful manual text; refresh stale facts.
- If root README.md is missing: create it.

Voice:
- terse, technical, human
- no marketing slime
- funny is allowed; cute and mean is allowed; bloat is not
- concrete install commands and examples

Required content.
For missing README, use these sections.
For existing README, keep equivalent existing headings/placement when present:
# pi-ext
one-line description

## Install
Use exact Pi CLI syntax. The command is `pi install`, never `pi ext install`.
- all extensions via git: `pi install git:github.com/bugabinga/pi-ext@v{version}`
- default branch install: `pi install git:github.com/bugabinga/pi-ext`
- local checkout via absolute path: `pi install /home/me/Workspace/pi-ext`
- local checkout via ~ path: `pi install ~/Workspace/pi-ext`
- single-extension package filter JSON for `~/.pi/agent/settings.json`
- explain skills/prompts/themes filters briefly

## Extensions
Markdown table: extension slug, short explanation, link to sub README.
One row per extension under extensions/*.

## Resources
Mention skills/, prompts/, themes/ are exported by root Pi package manifest.

## Release model
Single repo version. Tag format vX.Y.Z. Per-extension package versions intentionally absent.

---

A cute, mean, dark haiku about these extensions and Pi philosophy.
"""

EXT_README_STYLE = """Return the full README.md content for one bugabinga/pi-ext extension.
Use only the context in this prompt. Do not edit files.
Do not say done. Do not summarize. Output the complete markdown file only.

Task:
- If README.md exists: update it; preserve useful manual text; refresh stale facts.
- If README.md is missing: create it.
- Preserve existing demo blocks exactly when present:
  <!-- demo:NAME:start --> ... <!-- demo:NAME:end -->.
- Do not invent commands, tools, settings, env vars, or install paths.

Voice:
- terse, technical, human
- no marketing slime
- concrete behavior over adjectives

Required content.
For missing README, use these sections.
For existing README, keep equivalent existing headings/placement when present:
# extension-slug
one-line purpose

## Install / load
Briefly say this extension is loaded through the root pi-ext package.
Link root README relatively as ../../README.md.

## Commands / tools / settings
List actual commands/tools/hooks/settings. Say none where none exist.

## Behavior
Short operational notes from source.

## Demo
Only include when an existing demo block is provided in current README.
"""


def root_pkg() -> dict:
    return json.loads((ROOT / "package.json").read_text())


SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")


def root_version() -> str:
    return root_pkg().get("version", "0.0.0")


def parse_version(version: str) -> tuple[int, int, int]:
    match = SEMVER_RE.match(version)
    if not match:
        raise SystemExit(f"root package.json version must be X.Y.Z, got {version!r}")
    return tuple(int(part) for part in match.groups())


def bump_patch(version: str) -> str:
    major, minor, patch = parse_version(version)
    return f"{major}.{minor}.{patch + 1}"


def write_json(path: Path, data: object) -> None:
    path.write_text(json.dumps(data, indent="\t") + "\n", encoding="utf-8", newline="\n")


def set_root_version(version: str) -> None:
    parse_version(version)
    pkg = root_pkg()
    pkg["version"] = version
    write_json(ROOT / "package.json", pkg)

    lock_path = ROOT / "package-lock.json"
    lock = json.loads(lock_path.read_text())
    lock["version"] = version
    root_lock_pkg = lock.get("packages", {}).get("")
    if isinstance(root_lock_pkg, dict):
        root_lock_pkg["version"] = version
    write_json(lock_path, lock)
    print(f"OK version v{version}")


def pkg_name(spec: str) -> str:
    if spec.startswith("@"):
        parts = spec.split("/")
        return "/".join(parts[:2])
    return spec.split("/")[0]


def read_pkg(ext: Path) -> dict:
    return json.loads((ext / "package.json").read_text())


def ext_dirs(selected: list[str]) -> list[Path]:
    dirs = sorted(p.parent for p in EXT_ROOT.glob("*/package.json"))
    if not selected:
        return dirs

    wanted = set(selected)
    result = []
    for ext in dirs:
        pkg = read_pkg(ext)
        if ext.name in wanted or pkg.get("name") in wanted:
            result.append(ext)

    found = {ext.name for ext in result} | {read_pkg(ext).get("name") for ext in result}
    missing = wanted - found
    if missing:
        raise SystemExit(f"unknown extension(s): {', '.join(sorted(missing))}")
    return result


def ts_files(ext: Path) -> list[Path]:
    return sorted(p for p in ext.rglob("*.ts") if "node_modules" not in p.parts)


def import_specs(ext: Path) -> set[str]:
    specs: set[str] = set()
    for file in ts_files(ext):
        for match in IMPORT_RE.finditer(file.read_text(errors="ignore")):
            spec = match.group(1) or match.group(2)
            if spec:
                specs.add(spec)
    return specs


def is_allowed_test_import(file: Path, resolved: Path) -> bool:
    try:
        resolved.relative_to((ROOT / "test").resolve())
    except ValueError:
        return False
    return "__tests__" in file.parts


def err(errors: list[str], ext: Path, msg: str) -> None:
    errors.append(f"{ext.name}: {msg}")


def static_check(ext: Path) -> list[str]:
    errors: list[str] = []
    try:
        pkg = read_pkg(ext)
    except Exception as e:
        return [f"{ext.name}: invalid package.json: {e}"]

    expected = f"@bugabinga/pi-ext-{ext.name}"
    if pkg.get("name") != expected:
        err(errors, ext, f"package name must be {expected!r}")
    if pkg.get("version") is not None:
        err(
            errors, ext, "per-extension version must be absent; root package.json owns repo version"
        )
    if pkg.get("private") is not True:
        err(errors, ext, "package must have private:true")
    if pkg.get("type") != "module":
        err(errors, ext, "package.json type must be 'module'")
    if pkg.get("main") != "index.ts":
        err(errors, ext, "package.json main must be 'index.ts'")
    if not (ext / "index.ts").exists():
        err(errors, ext, "missing index.ts")
    if pkg.get("license") != "MIT":
        err(errors, ext, "package license must be MIT")
    if not (ext / "README.md").exists():
        err(errors, ext, "missing README.md")

    deps = pkg.get("dependencies", {}) or {}
    peers = pkg.get("peerDependencies", {}) or {}
    dev = pkg.get("devDependencies", {}) or {}
    if dev.get(HARNESS) is None:
        err(errors, ext, f"missing devDependency {HARNESS}")
    # test:harness script is optional; vitest discovers tests by convention
    if not (ext / "__tests__" / "harness.test.ts").exists():
        err(errors, ext, "missing __tests__/harness.test.ts")

    for dep in deps:
        if dep in PI_PEERS:
            err(errors, ext, f"Pi package {dep} belongs in peerDependencies, not dependencies")
        if dep.startswith("@bugabinga/pi-ext-"):
            err(errors, ext, f"must not depend on sibling extension {dep}")
    for dep in peers:
        if dep.startswith("@bugabinga/pi-ext-"):
            err(errors, ext, f"must not peer-depend on sibling extension {dep}")

    specs = import_specs(ext)
    packages = {
        pkg_name(s)
        for s in specs
        if not (s.startswith(".") or s.startswith("/") or s.startswith("node:"))
    }

    for spec in specs:
        if spec.startswith("@bugabinga/pi-ext-"):
            err(errors, ext, f"must not import sibling extension {spec}")

    for file in ts_files(ext):
        text = file.read_text(errors="ignore")
        for match in IMPORT_RE.finditer(text):
            spec = match.group(1) or match.group(2)
            if not spec or not spec.startswith("../"):
                continue
            resolved = (file.parent / spec).resolve()
            try:
                resolved.relative_to(ext.resolve())
            except ValueError:
                if not is_allowed_test_import(file, resolved):
                    err(
                        errors,
                        ext,
                        f"cross-extension relative import {spec} in {file.relative_to(ext)}",
                    )
        if SECRET_RE.search(text):
            err(errors, ext, f"possible secret in {file.relative_to(ext)}")

    for dep in sorted(packages & PI_PEERS):
        if dep not in peers:
            err(errors, ext, f"imported {dep} but missing peerDependency")
    for dep in sorted(packages - PI_PEERS):
        if dep not in deps and dep not in peers and dep not in dev:
            err(
                errors, ext, f"imported external package {dep} but package.json does not declare it"
            )

    return errors


def external_deps(pkg: dict) -> list[str]:
    deps = set()
    for key in ("dependencies", "peerDependencies", "devDependencies"):
        deps.update((pkg.get(key) or {}).keys())
    return sorted(deps)


def install(_ext: Path) -> None:
    global ROOT_INSTALL_DONE
    if ROOT_INSTALL_DONE:
        return
    subprocess.run(["npm", "ci", "--silent"], cwd=ROOT, check=True)
    ROOT_INSTALL_DONE = True


def git(*args: str, check: bool = True, capture: bool = False) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        ["git", *args],
        cwd=ROOT,
        check=check,
        text=True,
        stdout=subprocess.PIPE if capture else None,
        stderr=subprocess.PIPE if capture else None,
    )


def git_changes(path: Path, since: str | None) -> list[str]:
    cmd = ["log", "--format=%h %s"]
    if since:
        cmd.append(f"{since}..HEAD")
    cmd.extend(["--", str(path.relative_to(ROOT))])
    proc = git(*cmd, check=False, capture=True)
    if proc.returncode != 0:
        return []
    return [line.strip() for line in proc.stdout.splitlines() if line.strip()]


def latest_release_tag() -> str | None:
    proc = git("tag", "--list", "v*", "--sort=-creatordate", capture=True)
    tags = [line.strip() for line in proc.stdout.splitlines() if line.strip()]
    return tags[0] if tags else None


def changed_since_release(path: Path) -> bool:
    rel = str(path.relative_to(ROOT))
    if git("status", "--porcelain", "--", rel, capture=True).stdout.strip():
        return True
    tag = latest_release_tag()
    if not tag:
        return True
    return git("diff", "--quiet", tag, "--", rel, check=False).returncode != 0


def any_changed_since_release(paths: list[Path]) -> bool:
    tag = latest_release_tag()
    if not tag:
        return True
    return any(changed_since_release(path) for path in paths)


def strip_terminal_noise(text: str) -> str:
    return ANSI_RE.sub("", OSC_RE.sub("", text)).strip()


def pi_generate(prompt: str, model: str | None = None, label: str = "agent") -> str:
    pi_bin = shutil.which("pi") or shutil.which("pi.cmd")
    if not pi_bin:
        raise RuntimeError("pi executable not found on PATH")

    cmd = [
        pi_bin,
        "--no-session",
        "--no-tools",
        "--no-extensions",
        "--no-skills",
        "--no-prompt-templates",
        "--no-context-files",
        "-p",
    ]
    if model:
        cmd.extend(["--model", model])

    with (
        tempfile.TemporaryDirectory(prefix="pi-ext-prompt-") as prompt_dir,
        tempfile.TemporaryFile("w+", encoding="utf-8") as out,
        tempfile.TemporaryFile("w+", encoding="utf-8") as err_out,
    ):
        prompt_path = Path(prompt_dir) / "prompt.md"
        prompt_path.write_text(prompt, encoding="utf-8")
        proc = subprocess.Popen(
            [*cmd, f"@{prompt_path}"],
            cwd=ROOT,
            text=True,
            stdout=out,
            stderr=err_out,
        )
        frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
        start = time.monotonic()
        i = 0
        tty = sys.stderr.isatty()
        if not tty:
            print(f"RUN {label}", file=sys.stderr)
        while proc.poll() is None:
            elapsed = int(time.monotonic() - start)
            if tty:
                print(
                    f"\r{frames[i % len(frames)]} {label} {elapsed}s",
                    end="",
                    file=sys.stderr,
                    flush=True,
                )
                i += 1
            time.sleep(0.12)

        elapsed = int(time.monotonic() - start)
        out.seek(0)
        err_out.seek(0)
        stdout = out.read()
        stderr = err_out.read()

    if tty:
        icon = "✓" if proc.returncode == 0 else "✗"
        print(f"\r{icon} {label} {elapsed}s\033[K", file=sys.stderr, flush=True)
    else:
        print(("OK" if proc.returncode == 0 else "ERROR") + f" {label} {elapsed}s", file=sys.stderr)

    if proc.returncode != 0:
        if stderr:
            print(stderr, file=sys.stderr)
        raise subprocess.CalledProcessError(proc.returncode, proc.args, stdout, stderr)
    return strip_terminal_noise(stdout)


def changelog_prompt(ext: Path) -> str:
    pkg = read_pkg(ext)
    version = root_version()
    tag = latest_release_tag()
    commits = git_changes(ext, tag)
    commit_text = "\n".join(f"- {line}" for line in commits) or "- no commits since previous tag"
    rel = ext.relative_to(ROOT)
    return f"""You are writing one changelog section for one Pi extension.

Output markdown only. No preamble. No code fence.

{CHANGELOG_STYLE.format(version=version)}

Task:
Extension: {ext.name}
Package: {pkg["name"]}
Path: {rel}
Repo version: {version}
Previous repo tag: {tag or "none"}

Use only the context in this prompt. Do not edit files.

Git commits touching this extension:
{commit_text}
"""


def generate_changelog_entry(ext: Path, model: str | None = None) -> str:
    out = pi_generate(changelog_prompt(ext), model, f"changelog {ext.name}")
    if not out.startswith("## "):
        raise RuntimeError(f"bad changelog output for {ext.name}: {out[:200]!r}")
    return out.rstrip() + "\n"


def wrap_generated_markdown(text: str, width: int = 80) -> str:
    lines: list[str] = []
    in_fence = False
    for raw_line in text.replace("\r\n", "\n").replace("\r", "\n").split("\n"):
        line = raw_line.rstrip()
        stripped = line.lstrip()
        if stripped.startswith("```") or stripped.startswith("~~~"):
            in_fence = not in_fence
            lines.append(line)
            continue
        if in_fence or not line or stripped.startswith(("#", "<!--", "![")) or "|" in line:
            lines.append(line)
            continue

        bullet = re.match(r"^(\s*[-*]\s+)(.+)$", line)
        if bullet:
            prefix, body = bullet.groups()
            lines.extend(
                textwrap.wrap(
                    body,
                    width=width,
                    initial_indent=prefix,
                    subsequent_indent=" " * len(prefix),
                    break_long_words=False,
                    break_on_hyphens=False,
                )
            )
            continue

        numbered = re.match(r"^(\s*\d+[.)]\s+)(.+)$", line)
        if numbered:
            prefix, body = numbered.groups()
            lines.extend(
                textwrap.wrap(
                    body,
                    width=width,
                    initial_indent=prefix,
                    subsequent_indent=" " * len(prefix),
                    break_long_words=False,
                    break_on_hyphens=False,
                )
            )
            continue

        if line.startswith(" "):
            lines.append(line)
            continue

        lines.extend(
            textwrap.wrap(
                line,
                width=width,
                break_long_words=False,
                break_on_hyphens=False,
            )
        )
    return "\n".join(lines).rstrip() + "\n"


def write_repo_text(path: Path, text: str) -> None:
    path.write_text(wrap_generated_markdown(text), encoding="utf-8", newline="\n")


def update_changelog(ext: Path, model: str | None = None) -> str:
    path = ext / "CHANGELOG.md"
    entry = generate_changelog_entry(ext, model)
    heading = f"## {root_version()}"
    if not path.exists():
        write_repo_text(path, f"# Changelog\n\n{entry}")
        print(f"OK changelog {ext.name}")
        return entry

    text = path.read_text()
    if heading in text:
        lines = text.splitlines(keepends=True)
        start = next(i for i, line in enumerate(lines) if line.startswith(heading))
        end = next(
            (i for i in range(start + 1, len(lines)) if lines[i].startswith("## ")), len(lines)
        )
        write_repo_text(
            path,
            "".join(lines[:start]) + entry + "\n" + "".join(lines[end:]).lstrip("\n"),
        )
    elif text.startswith("# Changelog"):
        _, rest = text.split("\n", 1)
        write_repo_text(path, "# Changelog\n\n" + entry + "\n" + rest.lstrip("\n"))
    else:
        write_repo_text(path, f"# Changelog\n\n{entry}\n{text}")
    print(f"OK changelog {ext.name}")
    return entry


def repo_changelog_prompt(exts: list[Path]) -> str:
    version = root_version()
    tag = latest_release_tag()
    commit_text = (
        "\n".join(f"- {line}" for line in git_changes(ROOT, tag))
        or "- no commits since previous tag"
    )
    names = ", ".join(ext.name for ext in exts)
    return f"""Write one repo-level CHANGELOG.md section for bugabinga/pi-ext.

Output markdown only. No preamble. No code fence.

{CHANGELOG_STYLE.format(version=version)}

Scope: {names}
Repo version: {version}
Previous repo tag: {tag or "none"}

Use only the context in this prompt. Do not edit files.
Summarize cross-extension release value, not every tiny file.

Git commits:
{commit_text}
"""


def generate_repo_changelog_entry(exts: list[Path], model: str | None = None) -> str:
    entry = pi_generate(repo_changelog_prompt(exts), model, "changelog root").rstrip() + "\n"
    if not entry.startswith("## "):
        raise RuntimeError(f"bad repo changelog output: {entry[:200]!r}")
    return entry


def update_repo_changelog(exts: list[Path], model: str | None = None) -> str:
    entry = generate_repo_changelog_entry(exts, model)
    path = ROOT / "CHANGELOG.md"
    heading = f"## {root_version()}"
    if not path.exists():
        write_repo_text(path, f"# Changelog\n\n{entry}")
        print("OK changelog root")
        return entry
    text = path.read_text()
    if heading in text:
        lines = text.splitlines(keepends=True)
        start = next(i for i, line in enumerate(lines) if line.startswith(heading))
        end = next(
            (i for i in range(start + 1, len(lines)) if lines[i].startswith("## ")), len(lines)
        )
        write_repo_text(
            path,
            "".join(lines[:start]) + entry + "\n" + "".join(lines[end:]).lstrip("\n"),
        )
    elif text.startswith("# Changelog"):
        _, rest = text.split("\n", 1)
        write_repo_text(path, "# Changelog\n\n" + entry + "\n" + rest.lstrip("\n"))
    else:
        write_repo_text(path, f"# Changelog\n\n{entry}\n{text}")
    print("OK changelog root")
    return entry


def readme_prompt() -> str:
    version = root_version()
    current = (
        (ROOT / "README.md").read_text(errors="ignore") if (ROOT / "README.md").exists() else ""
    )
    exts = []
    for ext in ext_dirs([]):
        pkg = read_pkg(ext)
        readme = (ext / "README.md").read_text(errors="ignore")[:1200]
        exts.append(f"- {ext.name}: package={pkg['name']}\nREADME excerpt:\n{readme}")
    return f"""{README_STYLE.format(version=version)}

Existing root README.md:
{current or "<missing>"}

Root package.json:
{json.dumps(root_pkg(), indent=2)}

Extensions:
{chr(10).join(exts)}
"""


def first_heading_markdown(text: str) -> str:
    lines = text.splitlines()
    start = next((i for i, line in enumerate(lines) if line.startswith("# ")), -1)
    if start > 0:
        return "\n".join(lines[start:]).rstrip() + "\n"
    return text.rstrip() + "\n"


def generate_readme(model: str | None = None) -> str:
    out = first_heading_markdown(pi_generate(readme_prompt(), model, "README root"))
    if not out.startswith("# pi-ext"):
        raise RuntimeError(f"bad README output: {out[:200]!r}")
    return out.rstrip() + "\n"


def update_readme(model: str | None = None) -> str:
    text = generate_readme(model)
    write_repo_text(ROOT / "README.md", text)
    print("OK README.md")
    return text


def ext_readme_prompt(ext: Path) -> str:
    pkg = read_pkg(ext)
    current = (ext / "README.md").read_text(errors="ignore") if (ext / "README.md").exists() else ""
    sources = []
    for file in ts_files(ext)[:8]:
        rel = file.relative_to(ext)
        sources.append(f"--- {rel} ---\n{file.read_text(errors='ignore')[:5000]}")
    return f"""{EXT_README_STYLE}

Extension: {ext.name}
Package.json:
{json.dumps(pkg, indent=2)}

Existing README.md:
{current or "<missing>"}

Source excerpts:
{chr(10).join(sources)}
"""


def generate_ext_readme(ext: Path, model: str | None = None) -> str:
    prompt = ext_readme_prompt(ext)
    label = f"README {ext.name}"
    last = ""
    for attempt in range(2):
        out = first_heading_markdown(
            pi_generate(prompt, model, label if attempt == 0 else f"{label} retry")
        )
        last = out
        if out.startswith("# "):
            return out.rstrip() + "\n"
        prompt += f"""

Previous output was invalid because it did not start with a markdown H1 heading (`# ...`).
Retry. Output the complete README.md only. First bytes must be `# {ext.name}` or another H1.
Invalid output prefix:
{out[:500]}
"""
    raise RuntimeError(f"bad README output for {ext.name}: {last[:200]!r}")


def update_ext_readme(ext: Path, model: str | None = None) -> str:
    text = generate_ext_readme(ext, model)
    write_repo_text(ext / "README.md", text)
    print(f"OK README {ext.name}")
    return text


def update_all_readmes(exts: list[Path], model: str | None = None) -> None:
    tag = latest_release_tag()
    errors: list[str] = []
    if any_changed_since_release([ROOT / "README.md", ROOT / "package.json", EXT_ROOT]):
        try:
            update_readme(model)
        except Exception as e:
            errors.append(f"root: {e}")
            print(f"ERROR README root: {e}", file=sys.stderr)
    else:
        print(f"OK README root skipped (unchanged since {tag})")

    for ext in exts:
        if not changed_since_release(ext):
            print(f"OK README {ext.name} skipped (unchanged since {tag})")
            continue
        try:
            update_ext_readme(ext, model)
        except Exception as e:
            errors.append(f"{ext.name}: {e}")
            print(f"ERROR README {ext.name}: {e}", file=sys.stderr)
    if errors:
        raise SystemExit("README generation failed: " + "; ".join(errors))


def load_driver(path: Path) -> ModuleType:
    spec = importlib.util.spec_from_file_location(f"driver_{path.stem}", path)
    if spec is None or spec.loader is None:
        raise SystemExit(f"cannot load driver: {path}")
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def drivers_for(exts: list[Path]) -> list[tuple[str, list[str]]]:
    selected = {ext.name for ext in exts}
    drivers: list[tuple[str, list[str]]] = []
    for path in sorted(DRIVER_ROOT.glob("*.py")):
        if path.name.startswith("__"):
            continue
        module = load_driver(path)
        targets = getattr(module, "targets", [])
        if isinstance(targets, list) and selected.intersection(targets):
            drivers.append((path.stem, [t for t in targets if isinstance(t, str)]))
    return drivers


def demo_installed(driver: str, targets: list[str]) -> bool:
    for target in targets:
        ext = EXT_ROOT / target
        if not (ext / "README.md").exists() or not (ext / "assets" / f"{driver}.gif").exists():
            return False
    return True


def installed_drivers_for(exts: list[Path]) -> list[tuple[str, list[str]]]:
    return [
        (driver, targets)
        for driver, targets in drivers_for(exts)
        if demo_installed(driver, targets)
    ]


def demo_changed_since_release(driver: str, targets: list[str]) -> bool:
    module = load_driver(DRIVER_ROOT / f"{driver}.py")
    extensions = [name for name in getattr(module, "extensions", []) if isinstance(name, str)]
    paths = [DRIVER_ROOT / f"{driver}.py"]
    paths.extend(EXT_ROOT / name for name in sorted(set(targets + extensions)))
    return any_changed_since_release(paths)


def demos_to_update(drivers: list[tuple[str, list[str]]]) -> list[tuple[str, list[str]]]:
    return [
        (driver, targets)
        for driver, targets in drivers
        if demo_changed_since_release(driver, targets)
    ]


def update_demo_drivers(drivers: list[tuple[str, list[str]]]) -> list[Path]:
    tag = latest_release_tag()
    selected = demos_to_update(drivers)
    skipped = sorted(
        set(driver for driver, _targets in drivers) - set(driver for driver, _targets in selected)
    )
    for driver in skipped:
        print(f"OK demo {driver} skipped (unchanged since {tag})")
    if not selected:
        print("OK demo none")
        return []
    touched: set[Path] = set()
    for driver, targets in selected:
        subprocess.run(["python3", "scripts/demo.py", driver], cwd=ROOT, check=True)
        touched.update(EXT_ROOT / target for target in targets)
        print(f"OK demo {driver}")
    return sorted(path for path in touched if path.exists())


def update_demos(exts: list[Path]) -> list[Path]:
    return update_demo_drivers(installed_drivers_for(exts))


def changed_paths() -> list[Path]:
    out = (
        git("diff", "--name-only", capture=True).stdout
        + "\n"
        + git("diff", "--cached", "--name-only", capture=True).stdout
    )
    return sorted({Path(line) for line in out.splitlines() if line.strip()})


def allowed_change(path: Path, roots: list[Path]) -> bool:
    for root in roots:
        rel = root.relative_to(ROOT)
        if path == rel or rel in path.parents:
            return True
    return False


def assert_only_release_changes(paths_to_add: list[Path]) -> None:
    roots = [path for path in paths_to_add if path.exists()]
    extra = [path for path in changed_paths() if not allowed_change(path, roots)]
    if extra:
        raise SystemExit(
            "refusing to publish unrelated change(s): " + ", ".join(str(path) for path in extra)
        )


def release_tag_for(version: str) -> str:
    parse_version(version)
    return f"v{version}"


def release_tag() -> str:
    return release_tag_for(root_version())


def tag_exists(tag: str) -> bool:
    return git("rev-parse", "--verify", "--quiet", f"refs/tags/{tag}", check=False).returncode == 0


def remote_tag_exists(tag: str) -> bool:
    return (
        git(
            "ls-remote",
            "--exit-code",
            "--tags",
            "origin",
            f"refs/tags/{tag}",
            check=False,
            capture=True,
        ).returncode
        == 0
    )


def ensure_unreleased_version() -> str:
    git("fetch", "--prune", "--tags", "origin")
    version = root_version()
    bumped = False
    while tag_exists(release_tag_for(version)) or remote_tag_exists(release_tag_for(version)):
        version = bump_patch(version)
        bumped = True
    if bumped:
        set_root_version(version)
    return version


def create_tag() -> str:
    tag = release_tag()
    exists = tag_exists(tag)
    if exists:
        print(f"OK tag {tag} exists")
    else:
        git("tag", tag, "HEAD")
        print(f"OK tag {tag}")
    return tag


def commit_release(paths_to_add: list[Path]) -> bool:
    assert_only_release_changes(paths_to_add)
    paths = sorted({str(path.relative_to(ROOT)) for path in paths_to_add if path.exists()})
    git("add", *paths)
    if git("diff", "--cached", "--quiet", "--", *paths, check=False).returncode == 0:
        print("OK commit none")
        return False
    git("commit", "-m", f"release: v{root_version()}", "--", *paths)
    print(f"OK commit v{root_version()}")
    return True


def push_release(tag: str) -> None:
    git("push")
    git("push", "origin", tag)
    print("OK push")


def cmd_list(selected: list[str]) -> int:
    for ext in ext_dirs(selected):
        print(f"{ext.name}\t{read_pkg(ext).get('name')}")
    return 0


def check_static(dirs: list[Path]) -> int:
    errors: list[str] = []
    for ext in dirs:
        errors.extend(static_check(ext))
    pkg = root_pkg()
    if pkg.get("private") is not True:
        errors.append("root: package must have private:true")
    if pkg.get("workspaces") != ["extensions/*"]:
        errors.append("root: workspaces must be ['extensions/*']")
    if pkg.get("pi", {}).get("extensions") != ["extensions/*/index.ts"]:
        errors.append("root: pi.extensions must be ['extensions/*/index.ts']")
    for key in ["skills", "prompts", "themes"]:
        if pkg.get("pi", {}).get(key) != [key]:
            errors.append(f"root: pi.{key} must be ['{key}']")
    if errors:
        for e in errors:
            print(f"ERROR {e}", file=sys.stderr)
        return 1
    print(f"OK static {len(dirs)} extension package(s)")
    return 0


def cmd_test(selected: list[str]) -> int:
    dirs = ext_dirs(selected)
    args = [str(d.relative_to(ROOT)) for d in dirs] if dirs else []
    subprocess.run(["npm", "run", "test", "--", *args], cwd=ROOT, check=True)
    return 0


def cmd_check(selected: list[str]) -> int:
    return check_static(ext_dirs(selected))


def cmd_changelog(selected: list[str], model: str | None, write: bool) -> int:
    dirs = ext_dirs(selected)
    for ext in dirs:
        entry = update_changelog(ext, model) if write else generate_changelog_entry(ext, model)
        print(entry.rstrip())
    return 0


def cmd_readme(selected: list[str], model: str | None, write: bool) -> int:
    dirs = ext_dirs(selected)
    if write:
        update_all_readmes(dirs, model)
        return 0
    print(generate_readme(model).rstrip())
    for ext in dirs:
        print()
        print(generate_ext_readme(ext, model).rstrip())
    return 0


def cmd_demo(names: list[str]) -> int:
    if names:
        known = {driver: targets for driver, targets in drivers_for(ext_dirs([]))}
        missing = sorted(set(names) - set(known))
        if missing:
            raise SystemExit(f"unknown demo driver(s): {', '.join(missing)}")
        update_demo_drivers([(name, known[name]) for name in names])
    else:
        update_demos(ext_dirs([]))
    return 0


def release_paths(dirs: list[Path]) -> list[Path]:
    paths = {
        ROOT / "README.md",
        ROOT / "CHANGELOG.md",
        ROOT / "package.json",
        ROOT / "package-lock.json",
    }
    for ext in dirs:
        paths.add(ext / "README.md")
        paths.add(ext / "CHANGELOG.md")
    return sorted(paths)


def release_markdown_paths(dirs: list[Path]) -> list[Path]:
    paths = [ROOT / "README.md", ROOT / "CHANGELOG.md"]
    for ext in dirs:
        paths.extend([ext / "README.md", ext / "CHANGELOG.md"])
    return [path for path in paths if path.exists()]


def format_release_artifacts(dirs: list[Path]) -> None:
    dprint = shutil.which("dprint") or shutil.which("dprint.cmd")
    if not dprint:
        raise SystemExit("dprint not found; cannot format release artifacts")
    paths = [str(path.relative_to(ROOT)) for path in release_markdown_paths(dirs)]
    if paths:
        subprocess.run([dprint, "fmt", *paths], cwd=ROOT, check=True)


def cmd_release_plan(selected: list[str], model: str | None) -> int:
    dirs = ext_dirs(selected)
    demos = demos_to_update(installed_drivers_for(dirs))
    print("RELEASE PLAN")
    print(f"version: v{root_version()}")
    print("demos: " + (", ".join(name for name, _targets in demos) if demos else "none"))
    print("README:")
    print(generate_readme(model).rstrip())
    print("repo changelog:")
    print(generate_repo_changelog_entry(dirs, model).rstrip())
    for ext in dirs:
        print(generate_changelog_entry(ext, model).rstrip())
    print("skip write/commit/tag/push")
    return 0


def cmd_release_prepare(selected: list[str], model: str | None) -> int:
    dirs = ext_dirs(selected)
    update_all_readmes(dirs, model)
    update_repo_changelog(dirs, model)
    for ext in dirs:
        update_changelog(ext, model)
    format_release_artifacts(dirs)
    print(f"OK release prepared v{root_version()}")
    return 0


def cmd_publish(selected: list[str]) -> int:
    dirs = ext_dirs(selected)
    paths = release_paths(dirs)
    assert_only_release_changes(paths)
    ensure_unreleased_version()
    cmd_release_prepare(selected, model=None)
    commit_release(paths)
    tag = create_tag()
    push_release(tag)
    return 0


def main() -> int:
    parser = argparse.ArgumentParser()
    sub = parser.add_subparsers(dest="command", required=True)
    list_p = sub.add_parser("list")
    list_p.add_argument("extensions", nargs="*")
    check_p = sub.add_parser("check")
    check_p.add_argument("extensions", nargs="*")
    test_p = sub.add_parser("test")
    test_p.add_argument("extensions", nargs="*")
    changelog_p = sub.add_parser("changelog")
    changelog_p.add_argument("extensions", nargs="+")
    changelog_p.add_argument("--model")
    changelog_p.add_argument("--write", action="store_true")
    readme_p = sub.add_parser("readme")
    readme_p.add_argument("extensions", nargs="*")
    readme_p.add_argument("--model")
    readme_p.add_argument("--write", action="store_true")
    demo_p = sub.add_parser("demo")
    demo_p.add_argument("drivers", nargs="*")
    release_plan_p = sub.add_parser("release-plan")
    release_plan_p.add_argument("extensions", nargs="*")
    release_plan_p.add_argument("--model")
    release_prepare_p = sub.add_parser("release-prepare")
    release_prepare_p.add_argument("extensions", nargs="*")
    release_prepare_p.add_argument("--model")
    publish_p = sub.add_parser("publish")
    publish_p.add_argument("extensions", nargs="*")
    args = parser.parse_args()

    if args.command == "list":
        return cmd_list(args.extensions)
    if args.command == "check":
        return cmd_check(args.extensions)
    if args.command == "test":
        return cmd_test(args.extensions)
    if args.command == "changelog":
        return cmd_changelog(args.extensions, args.model, args.write)
    if args.command == "readme":
        return cmd_readme(args.extensions, args.model, args.write)
    if args.command == "demo":
        return cmd_demo(args.drivers)
    if args.command == "release-plan":
        return cmd_release_plan(args.extensions, args.model)
    if args.command == "release-prepare":
        return cmd_release_prepare(args.extensions, args.model)
    if args.command == "publish":
        return cmd_publish(args.extensions)
    raise AssertionError(args.command)


if __name__ == "__main__":
    raise SystemExit(main())