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)
SECRET_SCAN_IGNORE_KEY = "secretScanIgnore"
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 secret_scan_ignore_paths(root: Path = ROOT) -> set[Path]:
try:
config = json.loads((root / "scripts" / "extensions.json").read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError):
return set()
paths = config.get(SECRET_SCAN_IGNORE_KEY)
if not isinstance(paths, list):
return set()
return {Path(path) for path in paths if isinstance(path, str) and path}
def is_secret_scan_ignored(file: Path, ignores: set[Path], root: Path = ROOT) -> bool:
try:
rel = file.resolve().relative_to(root.resolve())
except ValueError:
return False
return rel in ignores
def static_check(ext: Path) -> list[str]:
secret_scan_ignores = secret_scan_ignore_paths()
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) and not is_secret_scan_ignored(file, secret_scan_ignores):
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())