#!/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: ... . - 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(("#", "