Initial public release

Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

278
scripts/cast-edit.py Executable file
View File

@@ -0,0 +1,278 @@
#!/usr/bin/env python3
"""Cut a raw screen recording down to a demo.
A real session is recorded at the speed a real session runs: a provider thinks for eleven seconds,
a build takes forty, and the interesting part is the two seconds either side. Played back untouched
that is a video of a progress bar. This trims the dead air without touching a single frame's
content — every byte the terminal emitted is still there, in order, and only the *gaps between*
them move.
Three edits, in this order:
window keep what lies between two marks the recording script dropped, so the take can start
before the app is up and end after it has been told to quit — opening with a rebuilt
picture of the screen as it stood at the mark, because a terminal recording is *state*
and a prefix cannot simply be dropped
clamp cap any gap longer than `--max-idle`, which is the whole trick: waiting is compressed,
reading time is not, because a hold the script asked for is shorter than the cap
pad hold the last frame, so a demo that ends on its own final state does not blink away
Before them all, `squeeze`: the stretch between a `squeeze` mark and a `resume` mark (or any
`squeeze-NAME` and `resume-NAME` pair) plays in `--squeeze-to` seconds. It is for a wait that is not dead air, a spinner turning while a model
writes, which clamping cannot touch because the screen never stops changing. Every frame is kept,
in order, and a clock on screen still says how long the wait really was.
`--speed` scales what is left. Clamping only reaches the *gaps*, and a model that streams for
ninety seconds without pausing has no gaps to give — so a long take needs the stream itself played
faster. Applied last, and sparingly: text arriving quickly is still readable, because what a reader
actually reads is the frame it settles on.
Input is asciicast v2 — a JSON header line, then one `[time, "o", data]` array per line. Output is
the same, which is what `asciinema-player` reads.
scripts/cast-edit.py raw.cast --out demo.cast --marks raw.marks --max-idle 1.2
"""
from __future__ import annotations
import argparse
import json
import pathlib
import sys
import pyte
# A gap shorter than this is somebody typing, not somebody waiting. Left alone entirely, so the
# cadence of a typed prompt survives the edit.
KEYSTROKE = 0.25
def load(path: pathlib.Path) -> tuple[dict, list[list]]:
"""Reads an asciicast v2 file into its header and its events."""
header: dict | None = None
events: list[list] = []
for line in path.read_text(encoding="utf8").splitlines():
if not line.strip():
continue
parsed = json.loads(line)
if header is None:
if not isinstance(parsed, dict):
sys.exit(f"{path}: first line is not an asciicast header")
header = parsed
continue
events.append(parsed)
if header is None:
sys.exit(f"{path}: empty recording")
return header, events
def window(
events: list[list],
start: float | None,
end: float | None,
size: tuple[int, int],
) -> list[list]:
"""Keeps the events between two marks, opening on the screen as it stood at the first.
A recording is not a film strip, it is a stream of *edits* to a screen. Ratatui writes only the
cells that changed, so the frame that drew the sidebar, the borders and the composer may be
thousands of events before the moment a demo wants to begin. Slicing the prefix away therefore
does not trim a run-up — it deletes the picture, and the take opens on a blank terminal with a
half-typed line floating in it, which is exactly how the commit demo shipped.
So the prefix is *replayed* rather than dropped, and the take opens with one synthetic event
that paints the resulting screen in full. Everything after the mark is a genuine recording.
"""
before = [e for e in events if start is None or e[0] < start]
kept = [e for e in events if (start is None or e[0] >= start) and (end is None or e[0] <= end)]
if not kept:
return []
offset = kept[0][0]
rebased = [[round(e[0] - offset, 6), *e[1:]] for e in kept]
if not before:
return rebased
return [[0.0, "o", repaint(before, size)], *rebased]
def repaint(events: list[list], size: tuple[int, int]) -> str:
"""Replays events into a screen and returns the escape sequence that redraws it."""
columns, rows = size
screen = pyte.Screen(columns, rows)
stream = pyte.Stream(screen)
for event in events:
stream.feed(event[2])
# Alternate screen, hidden cursor, cleared — the same state the app put the terminal in, so the
# player starts from what it would have had rather than from a fresh terminal's defaults.
out = ["\x1b[?1049h", "\x1b[?25l", "\x1b[H", "\x1b[2J"]
for row in range(rows):
line = screen.buffer[row]
out.append(f"\x1b[{row + 1};1H")
run, style = "", None
for column in range(columns + 1):
cell = line[column] if column < columns else None
here = (cell.fg, cell.bg, cell.bold, cell.reverse) if cell else None
if here != style:
if run:
out.append(run)
out.append(sgr(here) if here else "\x1b[0m")
run, style = "", here
if cell:
run += cell.data or " "
if run:
out.append(run)
out.append("\x1b[0m")
return "".join(out)
def sgr(style: tuple[str, str, bool, bool]) -> str:
"""One cell style as an SGR sequence."""
foreground, background, bold, reverse = style
parts = ["0"]
if bold:
parts.append("1")
if reverse:
parts.append("7")
for value, prefix in ((foreground, "38"), (background, "48")):
if value == "default" or not value:
continue
if len(value) == 6 and all(c in "0123456789abcdefABCDEF" for c in value):
parts += [prefix, "2", str(int(value[0:2], 16)), str(int(value[2:4], 16)), str(int(value[4:6], 16))]
return f"\x1b[{';'.join(parts)}m"
def clamp(events: list[list], max_idle: float) -> list[list]:
"""Caps every gap at `max_idle`, leaving the events themselves untouched.
Deliberately not a uniform speed-up. Scaling the whole timeline would squeeze the pauses the
script asked for — the beat after a prompt lands, the seconds a review screen needs to be read
— by exactly as much as it squeezes the provider's thinking time, and those are opposite
problems. So only the long gaps give.
"""
out: list[list] = []
previous = 0.0
shift = 0.0
for event in events:
gap = event[0] - previous
if gap > max_idle:
shift += gap - max_idle
previous = event[0]
out.append([round(event[0] - shift, 6), *event[1:]])
return out
def accelerate(events: list[list], factor: float) -> list[list]:
"""Plays the whole timeline `factor` times faster."""
if factor == 1.0:
return events
return [[round(e[0] / factor, 6), *e[1:]] for e in events]
def pad(events: list[list], seconds: float) -> list[list]:
"""Holds the last frame by emitting a no-op after it.
The player stops on its final frame, but "stops" is measured from the last event — so a demo
whose last event is the keystroke that produced the payoff cuts the instant the payoff appears.
A zero-width sequence costs nothing and buys the beat.
"""
if not events or seconds <= 0:
return events
return [*events, [round(events[-1][0] + seconds, 6), "o", ""]]
def squeeze(events: list[list], found: dict[str, float], seconds: float) -> list[list]:
"""Plays each `squeeze`…`resume` stretch in `seconds`, moving every later event and mark up by
the time saved. Taken latest first, so an earlier pair's marks are not yet moved when it is."""
pairs = sorted(
(name for name in found if name == "squeeze" or name.startswith("squeeze-")),
key=lambda name: found[name],
reverse=True,
)
for name in pairs:
events = squeeze_one(events, found, name, "resume" + name[len("squeeze"):], seconds)
return events
def squeeze_one(
events: list[list], found: dict[str, float], open_mark: str, close_mark: str, seconds: float
) -> list[list]:
start, end = found.get(open_mark), found.get(close_mark)
if start is None or end is None or end - start <= seconds:
return events
span = end - start
saved = span - seconds
def moved(at: float) -> float:
if at < start:
return at
if at <= end:
return start + (at - start) * seconds / span
return at - saved
for name, at in list(found.items()):
found[name] = moved(at)
return [[round(moved(e[0]), 6), *e[1:]] for e in events]
def marks(path: pathlib.Path | None) -> dict[str, float]:
"""Reads the `name<TAB>seconds` sidecar the recording script writes."""
if path is None or not path.exists():
return {}
found: dict[str, float] = {}
for line in path.read_text(encoding="utf8").splitlines():
name, _, seconds = line.partition("\t")
if seconds:
found[name.strip()] = float(seconds)
return found
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("source", type=pathlib.Path)
parser.add_argument("--out", type=pathlib.Path, required=True)
parser.add_argument("--marks", type=pathlib.Path)
parser.add_argument("--max-idle", type=float, default=1.2, help="cap on a gap, in seconds")
parser.add_argument("--tail", type=float, default=2.5, help="hold on the last frame")
parser.add_argument("--speed", type=float, default=1.0, help="playback multiplier")
parser.add_argument(
"--squeeze-to", type=float, default=2.0, help="seconds the squeeze/resume stretch plays in"
)
parser.add_argument("--from-mark", default="start")
parser.add_argument("--to-mark", default="end")
parser.add_argument("--title")
args = parser.parse_args()
if args.max_idle <= KEYSTROKE:
sys.exit(f"--max-idle must exceed {KEYSTROKE}s, or typing is compressed with the waiting")
header, events = load(args.source)
found = marks(args.marks)
events = squeeze(events, found, args.squeeze_to)
size = (int(header.get("width", 80)), int(header.get("height", 24)))
events = window(events, found.get(args.from_mark), found.get(args.to_mark), size)
if not events:
sys.exit(f"{args.source}: nothing between the {args.from_mark} and {args.to_mark} marks")
raw_duration = events[-1][0]
events = pad(accelerate(clamp(events, args.max_idle), args.speed), args.tail)
if args.title:
header["title"] = args.title
# Regenerated on every edit rather than trusted from the recorder: the player reserves its box
# from this number, and a stale one is a page that jumps when the demo loads.
header["duration"] = events[-1][0]
with args.out.open("w", encoding="utf8") as handle:
handle.write(json.dumps(header) + "\n")
for event in events:
handle.write(json.dumps(event) + "\n")
print(
f"{args.out.name}: {raw_duration:.1f}s recorded → {events[-1][0]:.1f}s played"
f" ({len(events)} frames)"
)
if __name__ == "__main__":
main()

143
scripts/cast-still.py Executable file
View File

@@ -0,0 +1,143 @@
#!/usr/bin/env python3
"""Render one frame of a recording as an SVG screenshot.
Some surfaces do not survive being watched. Guided Review puts a chapter's argument beside the code
it argues about, and a reader meeting it for the first time needs to *stop* on it — played at demo
speed it registers as motion rather than as information. So the same capture that makes a demo also
makes the stills, and there is still exactly one source of truth for what Luxe looks like.
**The drawing is not done here.** This replays the recording with `pyte` to work out what is on the
screen, then hands that grid to `fixture_svg --grid`, which is the exporter the generated
screenshots already come out of. That matters because box-drawing and block characters have to be
drawn as *geometry* rather than typeset: a `│` glyph is shorter than the row pitch, so a column of
them typeset as text breaks into dashes, and a slab's triangle cap detaches from the rect behind it.
That logic is a hundred-odd lines of careful Rust, and a second copy of it in Python would drift
from the first within a release.
scripts/cast-still.py review.cast --at 12.5 --out review.svg
scripts/cast-still.py review.cast --at end --crop 0,0,60,20 --out detail.svg
`--crop` takes `col,row,cols,rows` and is how a surface earns a place on a phone: a cropped detail
of the statusline reads at 390px, and the whole 150-column workspace never will.
"""
from __future__ import annotations
import argparse
import json
import pathlib
import subprocess
import sys
import pyte
# The default colors a recording's cells fall back to. `pyte` reports them by name; the exporter
# wants either a real color or nothing, so "default" becomes absent and the SVG's own canvas shows
# through.
ANSI = {
"black": "#12100e",
"red": "#e68485",
"green": "#81caa0",
"brown": "#faaa51",
"yellow": "#faaa51",
"blue": "#85c7d7",
"magenta": "#d2a5cd",
"cyan": "#85c7d7",
"white": "#e4dfd6",
}
def color(value: str) -> str | None:
"""Turns a pyte color into `#rrggbb`, or `None` for the terminal's default."""
if value == "default":
return None
if value in ANSI:
return ANSI[value]
if len(value) == 6 and all(c in "0123456789abcdefABCDEF" for c in value):
return f"#{value}"
return None
def replay(path: pathlib.Path, until: float, cols: int, rows: int) -> pyte.Screen:
"""Feeds the recording into a screen up to `until` seconds."""
screen = pyte.Screen(cols, rows)
stream = pyte.Stream(screen)
for line in path.read_text(encoding="utf8").splitlines():
if not line.strip():
continue
event = json.loads(line)
if isinstance(event, dict):
continue
if event[0] > until:
break
stream.feed(event[2])
return screen
def grid(screen: pyte.Screen, crop: tuple[int, int, int, int]) -> dict:
"""The visible cells, cropped, in the shape `fixture_svg --grid` reads."""
left, top, width, height = crop
cells = []
for row in range(top, top + height):
line = screen.buffer[row]
for column in range(left, left + width):
cell = line[column]
entry: dict[str, object] = {"c": cell.data}
foreground, background = color(cell.fg), color(cell.bg)
# Reverse video is a real thing on this screen — a selected row, a slab — and swapping
# here means the exporter never has to know about it.
if cell.reverse:
foreground, background = background or "#12100e", foreground or "#e4dfd6"
if foreground:
entry["fg"] = foreground
if background:
entry["bg"] = background
if cell.bold:
entry["bold"] = True
cells.append(entry)
return {"width": width, "height": height, "cells": cells}
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("source", type=pathlib.Path)
parser.add_argument("--out", type=pathlib.Path, required=True)
parser.add_argument("--at", default="end", help="seconds, or `end` for the last frame")
parser.add_argument("--crop", help="col,row,cols,rows")
args = parser.parse_args()
header = json.loads(args.source.read_text(encoding="utf8").splitlines()[0])
cols, rows = header["width"], header["height"]
until = float("inf") if args.at == "end" else float(args.at)
screen = replay(args.source, until, cols, rows)
window = (0, 0, cols, rows)
if args.crop:
left, top, width, height = (int(n) for n in args.crop.split(","))
if left + width > cols or top + height > rows:
sys.exit(f"crop {args.crop} does not fit a {cols}x{rows} screen")
window = (left, top, width, height)
exporter = pathlib.Path(__file__).resolve().parent.parent / "target/release/examples/fixture_svg"
if not exporter.exists():
sys.exit(
f"no exporter at {exporter} — "
"cargo build --release -p luxe-tui --features fixture --example fixture_svg"
)
done = subprocess.run(
[str(exporter), "--grid"],
input=json.dumps(grid(screen, window)),
capture_output=True,
text=True,
check=False,
)
if done.returncode != 0:
sys.exit(f"the exporter refused the grid: {done.stderr.strip()}")
args.out.write_text(done.stdout, encoding="utf8")
print(f"{args.out.name}: {window[2]}x{window[3]} cells, {args.out.stat().st_size // 1024}KB")
if __name__ == "__main__":
main()

88
scripts/comment-report.py Executable file
View File

@@ -0,0 +1,88 @@
#!/usr/bin/env python3
"""Comment report: where shipped Rust source spends its comment lines, and which blocks to read.
Not a gate. The ratio of comment to code says little on its own (well-documented libraries run from
25% to over 100%); what matters is whether a block earns its length. So this lists the blocks most
likely not to: long ones, and lines that narrate history ("used to", "measured on a live run")
rather than state why the code is as it is.
scripts/comment-report.py totals, then the long blocks and the narration, worst first
scripts/comment-report.py --totals totals only
"""
import re
import sys
import rust_source
HISTORY = re.compile(
r"\b(used to|no longer|which is how|this used|once (?:shipped|was|did)|measured on|it shipped|"
r"was the bug|before this|until (?:this|now)|on a live|a real (?:session|run|loop))\b",
re.I,
)
LONG = 15
def blocks(path: str):
"""`(first_line, lines, text)` for each run of comment lines outside test modules."""
source = (rust_source.ROOT / path).read_text(encoding="utf-8").split("\n")
masked = rust_source.masked_source(path)
tests = {line for first, last in rust_source.test_modules(masked) for line in range(first, last + 1)}
at = 0
while at < len(source):
if at not in tests and source[at].strip().startswith("//"):
end = at
while end < len(source) and end not in tests and source[end].strip().startswith("//"):
end += 1
yield at + 1, end - at, [line.strip() for line in source[at:end]]
at = end
else:
at += 1
def main() -> int:
shipped = [
path for path in rust_source.rust_files()
if path not in rust_source.test_files() and "/examples/" not in path
]
doc = inline = code = 0
long_blocks, narration = [], []
for path in shipped:
masked = rust_source.masked_source(path).split("\n")
source = (rust_source.ROOT / path).read_text(encoding="utf-8").split("\n")
tests = {
line
for first, last in rust_source.test_modules(rust_source.masked_source(path))
for line in range(first, last + 1)
}
for index, (line, mask) in enumerate(zip(source, masked)):
stripped = line.strip()
if index in tests or not stripped:
continue
if stripped.startswith(("///", "//!")):
doc += 1
elif stripped.startswith("//"):
inline += 1
elif mask.strip():
code += 1
for first, length, text in blocks(path):
if length >= LONG:
long_blocks.append((length, f"{path}:{first}"))
narration += [(f"{path}:{first + n}", t) for n, t in enumerate(text) if HISTORY.search(t)]
print(f"code {code}, doc {doc} ({100 * doc / code:.1f}%), inline {inline} "
f"({100 * inline / code:.1f}%), together {100 * (doc + inline) / code:.1f}%")
print(f"blocks of {LONG}+ lines: {len(long_blocks)} holding {sum(n for n, _ in long_blocks)} "
f"lines; history narration: {len(narration)} lines")
if "--totals" in sys.argv:
return 0
print(f"\n# blocks of {LONG}+ lines, longest first")
for length, where in sorted(long_blocks, reverse=True):
print(f"{length:4} {where}")
print("\n# lines narrating history")
for where, text in narration:
print(f"{where} {text[:110]}")
return 0
if __name__ == "__main__":
sys.exit(main())

161
scripts/docs-check.py Executable file
View File

@@ -0,0 +1,161 @@
#!/usr/bin/env python3
"""Check the user guide (`docs/guide/`) for what a machine can judge.
The guide is read in three places: on GitHub, on luxe.dev, and by an agent. So its links are written
the way a repository writes them, `configuration.md#github`, and the site rewrites them. This checks:
frontmatter every page has a title, a summary, an order and a known group
links every link to another page names a page that exists, and every anchor a heading on
it; a site-style `/docs/...` link is refused, since it is dead on GitHub
voice on a rewritten page: no lands/arrives/invariant, and an em-dash budget
The config examples, flags and slash commands are checked against the code by the Rust test
`guide_check` in `luxe-cli`, which knows the real types.
python3 scripts/docs-check.py
"""
from __future__ import annotations
import pathlib
import re
import sys
ROOT = pathlib.Path(__file__).resolve().parent.parent
GUIDE = ROOT / "docs" / "guide"
# Sidebar groups, in order. `web/src/content.config.ts` holds the same list.
GROUPS = ["Get started", "Using Luxe", "Customize", "Extend", "Reference"]
# Pages exempt from the voice rules while a rewrite is in progress. Empty: every page follows them.
# Links and frontmatter apply to every page regardless.
PENDING: set[str] = set()
# Words that read as generated, in the guide's prose. Matched as whole words, case-insensitively.
BANNED = ["land", "lands", "landed", "arrive", "arrives", "arrived", "invariant", "invariants"]
# At most one em dash per this many words of prose, and never fewer than this many allowed.
DASH_WORDS = 250
DASH_FLOOR = 2
def split_frontmatter(text: str) -> tuple[dict[str, str], str]:
if not text.startswith("---\n"):
return {}, text
end = text.index("\n---\n", 4)
fields = {}
for line in text[4:end].splitlines():
key, _, value = line.partition(":")
fields[key.strip()] = value.strip().strip('"')
return fields, text[end + 5 :]
def without_code(text: str) -> str:
"""The page with fenced and inline code blanked, line count preserved."""
text = re.sub(r"```.*?```", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.S)
return re.sub(r"`[^`\n]*`", "", text)
def slug(heading: str, seen: dict[str, int]) -> str:
"""The anchor github-slugger, which Astro uses, gives a heading."""
text = re.sub(r"`([^`]*)`", r"\1", heading)
text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)
text = re.sub(r"[*_]", "", text).strip().lower()
text = re.sub(r"[^\w\- ]", "", text)
base = text.replace(" ", "-")
count = seen.get(base, 0)
seen[base] = count + 1
return base if count == 0 else f"{base}-{count}"
def anchors(body: str) -> set[str]:
seen: dict[str, int] = {}
found = set()
in_code = False
for line in body.splitlines():
if line.startswith("```"):
in_code = not in_code
continue
heading = re.match(r"#{1,6} (.+)", line)
if heading and not in_code:
found.add(slug(heading.group(1), seen))
return found
def main() -> int:
pages = {path.stem: path for path in sorted(GUIDE.glob("*.md"))}
parsed = {name: split_frontmatter(path.read_text(encoding="utf-8")) for name, path in pages.items()}
page_anchors = {name: anchors(body) for name, (_, body) in parsed.items()}
problems: list[str] = []
for name in sorted(PENDING - pages.keys()):
problems.append(f"scripts/docs-check.py: PENDING names {name}, which is not a page")
for name, (fields, body) in parsed.items():
where = f"docs/guide/{name}.md"
for key in ("title", "summary", "order", "group"):
if not fields.get(key):
problems.append(f"{where}: frontmatter has no {key}")
if fields.get("group") and fields["group"] not in GROUPS:
problems.append(f"{where}: group {fields['group']!r} is not one of {GROUPS}")
prose = without_code(body)
for number, line in enumerate(prose.splitlines(), start=1):
for target in re.findall(r"\]\(([^)\s]+)\)", line):
problem = check_link(target, name, pages, page_anchors)
if problem:
problems.append(f"{where}:{number + offset(fields)} {problem}: {target}")
if name in PENDING:
continue
for number, line in enumerate(prose.splitlines(), start=1):
for word in BANNED:
if re.search(rf"\b{word}\b", line, re.IGNORECASE):
problems.append(f"{where}:{number + offset(fields)} {word!r}: {line.strip()[:80]}")
words = len(prose.split())
dashes = prose.count("\u2014")
budget = max(DASH_FLOOR, words // DASH_WORDS)
if dashes > budget:
problems.append(f"{where}: {dashes} em dashes in {words} words; the budget is {budget}")
if problems:
print(f"docs check: {len(problems)} problem(s)")
for problem in problems:
print(f" {problem}")
return 1
rewritten = len(pages) - len(PENDING & pages.keys())
print(f"docs check: {len(pages)} pages, {rewritten} rewritten, links and frontmatter clean")
return 0
def offset(fields: dict[str, str]) -> int:
"""Lines the frontmatter takes, so a line number points into the file."""
return len(fields) + 2 if fields else 0
def check_link(
target: str, page: str, pages: dict[str, pathlib.Path], page_anchors: dict[str, set[str]]
) -> str | None:
if re.match(r"[a-z]+:", target):
return None
if target.startswith("/docs"):
return "a site route, which is dead on GitHub; link the file, like `install.md`"
if target.startswith("/"):
return None
file, _, anchor = target.partition("#")
if file.removeprefix("./") in pages:
return "a page without its file name; link the file, like `install.md`"
if file.startswith("./"):
return "a `./` prefix, which the site does not rewrite; link the file, like `install.md`"
if file and not file.endswith(".md"):
return None
name = file.removesuffix(".md") if file else page
if name not in pages:
return "no such page"
if anchor and anchor not in page_anchors[name]:
return "no such heading"
return None
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,17 @@
# Functions allowed over clippy's too_many_lines threshold. See scripts/fn-length-check.py.
# <lines[,lines…]> <path> <fn> # reason
399 crates/luxe-tui/src/commands/built_in.rs built_in # the command catalog: one `Command` literal per entry, no logic to pull out, so a new command raises this by its own entry
369 crates/luxe-tui/src/app/messages.rs reduce_inner # the `Msg` reducer, one arm per message and nearly all of them one call; the fat arms already live in `app::messages::*`
353 crates/luxe-tui/src/app/commands.rs dispatch_action # maps each `UiAction` to the one call that handles it; arms are a line or two and a handler that grows moves out
257 crates/luxe-tui/src/app/events.rs reduce # the `Event` reducer, one arm per engine event; the long arms delegate to `app::events::*`
223 crates/luxe-core/src/engine/run.rs run # the engine action loop, a dispatch over `Action` where each arm is one handler call; the arms that did real work are methods
203 crates/luxe-tui/src/app/commands/slash.rs run_slash # maps each slash command to the handler that runs it; the arms that grew are in `commands::*`
128 crates/luxe-core/src/engine/turn.rs run_turn # the turn state machine: its `break`s and early returns share the loop state, and every step that could stand alone (compact, stream, commit, tools, wrap-up) already does
127 crates/luxe-tui/src/main_loop/click.rs clicked_target # one arm per mouse target, each a view guard and one message or a call into a named handler
125 crates/luxe-cli/src/cli/rpc/translate.rs to_engine_action # the RPC vocabulary mapped onto `Action`, one thin arm per variant
109 crates/luxe-tui/src/app/construct.rs with_file_provider # the `App` literal, one field per line; nothing in it is logic to extract
97 crates/luxe-cli/src/cli/headless.rs headless_json_event # one arm per `Event` the JSON stream reports, each building its small object
93 crates/luxe-core/src/engine/turn/stream.rs read_stream # one match over provider events whose arms share the accumulating reply and `break` the loop; the arms that did more are helpers
90 crates/luxe-tui/src/view/guided_review/overlays/help.rs help_groups # the review keys card as a table of rows, one per line
85 crates/luxe-lsp/src/tools/navigation.rs dispatch # one arm per navigation action over the same arguments, each a call into its handler
84 crates/luxe-providers/src/anthropic/sse.rs map_anthropic_event # one arm per wire event type, each mapping fields onto a `ProviderEvent`

152
scripts/fn-length-check.py Executable file
View File

@@ -0,0 +1,152 @@
#!/usr/bin/env python3
"""Function-length ratchet: clippy's `too_many_lines` at the threshold in `clippy.toml` (80).
Runs clippy over the shipped code (`--lib --bins`, so tests and examples are out) with only that
lint on, in its own target directory so it never invalidates the gate's clippy cache. A function
over the threshold fails unless `scripts/fn-length-allowlist.txt` lists it, and then it may not grow
past the number recorded there. The list only shrinks: an entry whose function is back under the
threshold, or shorter than recorded, fails as stale until `--tighten` rewrites it.
`#[async_trait]` rewrites a method's body inside a macro expansion, and clippy does not lint what a
macro produced, so those methods (every `Tool::run`, among others) are measured here instead by
`rust_source`, with the same rule: non-blank, non-comment lines of the body.
Functions are keyed by file and name, since line numbers move. Same-named functions in one file
(two `deserialize` impls, say) share a key and are compared largest to largest.
scripts/fn-length-check.py check
scripts/fn-length-check.py --tighten lower recorded lengths to current, drop what is now short
scripts/fn-length-check.py --report every function over the threshold, longest first
"""
import json
import re
import subprocess
import sys
from collections import defaultdict
from pathlib import Path
import rust_source
ROOT = Path(__file__).resolve().parent.parent
ALLOWLIST = ROOT / "scripts" / "fn-length-allowlist.txt"
LENGTH = re.compile(r"too many lines \((\d+)/(\d+)\)")
NAME = re.compile(r"\bfn\s+(\w+)")
def measure() -> dict[tuple[str, str], list[int]]:
command = [
"cargo", "clippy", "--workspace", "--lib", "--bins", "--quiet",
"--message-format=json", "--target-dir", str(ROOT / "target" / "fn-length"),
"--", "-A", "clippy::all", "-W", "clippy::too_many_lines",
]
run = subprocess.run(command, cwd=ROOT, capture_output=True, text=True)
if run.returncode != 0:
sys.stderr.write(run.stderr)
sys.exit(f"clippy failed ({run.returncode})")
lengths = defaultdict(list)
seen = set()
for line in run.stdout.splitlines():
message = json.loads(line).get("message") if line.startswith("{") else None
if not message or (message.get("code") or {}).get("code") != "clippy::too_many_lines":
continue
span = message["spans"][0]
name = NAME.search(" ".join(text["text"] for text in span["text"]))
length = LENGTH.search(message["message"])
site = (span["file_name"], span["line_start"])
if not (name and length) or site in seen:
continue # a bin and a lib can both report the same function
seen.add(site)
lengths[(span["file_name"], name.group(1))].append(int(length.group(1)))
threshold = int(re.search(r"too-many-lines-threshold\s*=\s*(\d+)", (ROOT / "clippy.toml").read_text()).group(1))
for path in rust_source.rust_files():
if path in rust_source.test_files() or "/examples/" in path:
continue
for name, line, length in rust_source.async_trait_methods(path):
if length > threshold and (path, line) not in seen:
lengths[(path, name)].append(length)
return {key: sorted(values, reverse=True) for key, values in lengths.items()}
def load_allowlist() -> dict[tuple[str, str], tuple[list[int], str]]:
entries = {}
if not ALLOWLIST.exists():
return entries
for raw in ALLOWLIST.read_text().splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
body, _, reason = line.partition("#")
sizes, path, name = body.split()
entries[(path, name)] = ([int(size) for size in sizes.split(",")], reason.strip())
return entries
def write_allowlist(entries: dict[tuple[str, str], tuple[list[int], str]]) -> None:
header = [
"# Functions allowed over clippy's too_many_lines threshold. See scripts/fn-length-check.py.",
"# <lines[,lines…]> <path> <fn> # reason",
]
rows = sorted(entries.items(), key=lambda item: (-item[1][0][0], item[0]))
body = [
f"{','.join(map(str, sizes)):>7} {path} {name} # {reason}"
for (path, name), (sizes, reason) in rows
]
ALLOWLIST.write_text("\n".join(header + body) + "\n")
def check() -> int:
measured, allowed = measure(), load_allowlist()
problems = []
for key, sizes in sorted(measured.items()):
where = f"{key[0]}: fn {key[1]}"
if key not in allowed:
problems.append(f"{where} is {sizes[0]} lines, over the threshold: split it")
continue
limit = allowed[key][0]
if len(sizes) > len(limit) or any(now > cap for now, cap in zip(sizes, limit)):
problems.append(f"{where} is {sizes} lines, grew past its allowance of {limit}")
for key, (sizes, _) in sorted(allowed.items()):
now = measured.get(key, [])
if len(now) < len(sizes) or any(n < s for n, s in zip(now, sizes)):
problems.append(f"{key[0]}: fn {key[1]} allowlisted at {sizes}, now {now}: run --tighten")
if problems:
print("function-length check failed:")
print("\n".join(f" {problem}" for problem in problems))
return 1
print(f"function-length check: {sum(map(len, measured.values()))} over the threshold, all allowlisted")
return 0
def tighten() -> int:
measured, allowed = measure(), load_allowlist()
kept = {}
for key, (sizes, reason) in allowed.items():
now = measured.get(key, [])
if now:
kept[key] = ([min(n, s) for n, s in zip(now, sizes)] + now[len(sizes):], reason)
write_allowlist(kept)
print(f"allowlist: {len(allowed)} -> {len(kept)} entries")
return 0
def report() -> int:
flat = [(size, path, name) for (path, name), sizes in measure().items() for size in sizes]
for size, path, name in sorted(flat, reverse=True):
print(f"{size:>5} {path} {name}")
return 0
def freeze() -> int:
"""Seed the allowlist with everything over the threshold today. Used once."""
write_allowlist({key: (sizes, "baseline") for key, sizes in measure().items()})
return 0
if __name__ == "__main__":
command = sys.argv[1] if len(sys.argv) > 1 else "--check"
actions = {"--check": check, "--tighten": tighten, "--report": report, "--freeze": freeze}
if command not in actions:
print(__doc__)
sys.exit(2)
sys.exit(actions[command]())

447
scripts/glyph-survey.py Executable file
View File

@@ -0,0 +1,447 @@
#!/usr/bin/env python3
"""glyph-survey — ask real font files which characters the fallback tiers may use.
`glyphs.rs` has two tiers that promise portability, and for a long time nothing checked the promise
against a font. The tests asserted no private-use codepoints and one cell wide by the Unicode width
property; neither is a question about what the reader's font contains. Measured, Liberation Mono was
missing twenty of the thirty-one marks the TUI draws at every tier — including the geometric shapes
chosen *because* they were supposed to be safe.
This is the measurement behind `crates/luxe-tui/src/glyphs/portable.txt`. It reads the installed
files with fontTools rather than trusting a vendor's claim, and it refuses to run rather than
quietly survey eight faces when it was asked for nine — a panel with a hole in it produces a list
that is wrong in the one direction that matters.
scripts/glyph-survey.py # report coverage for the current vocabulary
scripts/glyph-survey.py --candidates # which of a wider palette every face has
scripts/glyph-survey.py --check # portable.txt still holds (CI)
scripts/glyph-survey.py --face FILE... # does a face draw everything Luxe does, cleanly
U+2500-U+259F is not surveyed: terminals synthesize that range against the cell box, so the font is
not in the path. Everything else has to be in every face on the panel.
`--face` asks the opposite question, of a font you might *recommend* rather than one a reader
already has: does it carry every character Luxe can put on screen at the nerd tier, and does each
one stay inside its cell? The second half is the one a coverage count misses. The non-`Mono` cut of
any Nerd Font has every icon and draws most of them twice the cell wide, and plain Iosevka has every
character while `→ … —` print over their neighbor. The character set is read out of the TUI's
string literals (test code stripped) and out of what the site's assets and captures draw, so it
follows the code instead of a list somebody has to remember to update. It takes font *files*, not
family names, for the same reason the panel does.
Requires fontTools (`pip install fonttools`). Point PANEL entries at real files with FONT_DIRS or
the `LUXE_FONT_DIRS` environment variable (colon-separated).
"""
from __future__ import annotations
import argparse
import os
import pathlib
import re
import sys
import unicodedata
ROOT = pathlib.Path(__file__).resolve().parent.parent
PORTABLE = ROOT / "crates" / "luxe-tui" / "src" / "glyphs" / "portable.txt"
# Where `--face` reads what Luxe draws from.
DRAWING_SOURCES = (ROOT / "crates" / "luxe-tui" / "src", ROOT / "crates" / "luxe-cli" / "src")
DRAWING_ASSETS = (
ROOT / "web" / "src" / "assets" / "generated",
ROOT / "web" / "src" / "assets" / "captures",
)
# Sources whose literals reach the terminal without ever reaching a font.
NOT_GLYPHS = {
# kitty's Unicode placeholder and its row/column diacritics address an image; the terminal
# replaces them with pixels
ROOT / "crates" / "luxe-tui" / "src" / "graphics" / "kitty.rs",
}
# How far ink may pass the advance before it lands on the next cell. Outlines routinely overshoot
# by a few units for optical balance; the failures this exists for overshoot by 50 to 100%.
INK_TOLERANCE = 0.15
# The faces a reader plausibly already has. Filenames rather than family names: fontconfig
# substitutes silently, and a control run that quietly became the experimental run is exactly how
# the wordmark probe produced confident wrong answers the first time.
PANEL: dict[str, tuple[str, ...]] = {
"Liberation Mono": ("LiberationMono-Regular.ttf",),
"DejaVu Sans Mono": ("DejaVuSansMono.ttf",),
"Noto Sans Mono": ("NotoSansMono-Regular.ttf", "NotoSansMono[wdth,wght].ttf"),
"Cascadia Mono": ("CascadiaMono.ttf", "CascadiaMono-Regular.otf"),
"Adwaita Mono": ("AdwaitaMono-Regular.ttf",),
"Hack": ("Hack-Regular.ttf",),
"Fira Code": ("FiraCode-Regular.ttf", "FiraCode[wght].ttf"),
"JetBrains Mono": ("JetBrainsMono-Regular.ttf", "JetBrainsMono[wght].ttf"),
"Source Code Pro": ("SourceCodePro-Regular.ttf", "SourceCodePro-Regular.otf"),
}
FONT_DIRS = [
"/usr/share/fonts",
"/usr/local/share/fonts",
os.path.expanduser("~/.local/share/fonts"),
os.path.expanduser("~/Library/Fonts"),
"/Library/Fonts",
"/System/Library/Fonts",
"C:/Windows/Fonts",
]
# A wider palette to measure when looking for a substitute, so the choice is made from numbers.
CANDIDATES = (
"·•…‹›«»†‡¶§¤¬°±×÷√∞≈≡≤≥∙–—←↑→↓"
"□■▪▫▲▼◄►○●◆◇◉◌◦△▽"
"✓✔✗✖★☆↳↺⊘⋯ℹ⦸❯❮▸▾‣⁃∴∵⌐‾"
)
def synthesized(cp: int) -> bool:
"""Whether the terminal draws this itself, which takes the font out of the path."""
return 0x2500 <= cp <= 0x259F
def find_font(names: tuple[str, ...]) -> pathlib.Path | None:
roots = [pathlib.Path(d) for d in os.environ.get("LUXE_FONT_DIRS", "").split(":") if d]
roots += [pathlib.Path(d) for d in FONT_DIRS]
for root in roots:
if not root.is_dir():
continue
for name in names:
hit = next(root.rglob(name), None)
if hit:
return hit
return None
def coverage() -> dict[str, set[int]]:
try:
from fontTools.ttLib import TTFont
except ImportError:
sys.exit("glyph-survey needs fontTools: pip install fonttools")
found: dict[str, set[int]] = {}
missing: list[str] = []
for face, names in PANEL.items():
path = find_font(names)
if path is None:
missing.append(f"{face} ({' or '.join(names)})")
continue
font = TTFont(path, fontNumber=0, lazy=True)
chars: set[int] = set()
for table in font["cmap"].tables:
chars |= set(table.cmap.keys())
font.close()
found[face] = chars
if missing:
sys.exit(
"the panel is incomplete, so the survey would understate what is missing.\n"
" absent: " + "\n ".join(missing) + "\n"
" install them, or point LUXE_FONT_DIRS at a directory that has them."
)
return found
def parse_portable() -> list[int]:
listed = []
for line in PORTABLE.read_text(encoding="utf-8").splitlines():
match = re.match(r"^U\+([0-9A-F]{4,6})\t", line)
if match:
listed.append(int(match.group(1), 16))
return listed
# === What Luxe draws, for --face ===
def rust_literals(src: str) -> tuple[list[tuple[int, int]], str]:
"""Every string and char literal's span, and the source with literals and comments blanked.
The blanked copy is what braces are matched in, so a `{` inside a format string or a comment
cannot unbalance the item it sits in. A lexer and not a regex because Rust's lifetimes look
like the start of a char literal and raw strings nest their own quotes.
"""
spans: list[tuple[int, int]] = []
masked = list(src)
i, n = 0, len(src)
def blank(start: int, end: int) -> None:
for k in range(start, end):
if masked[k] != "\n":
masked[k] = " "
while i < n:
c = src[i]
if src.startswith("//", i):
end = src.find("\n", i)
end = n if end < 0 else end
blank(i, end)
i = end
elif src.startswith("/*", i):
depth, j = 1, i + 2
while j < n and depth:
if src.startswith("/*", j):
depth, j = depth + 1, j + 2
elif src.startswith("*/", j):
depth, j = depth - 1, j + 2
else:
j += 1
blank(i, j)
i = j
elif c == "r" and re.match(r'r#*"', src[i : i + 260]) and not identifier_tail(src, i):
hashes = re.match(r"r(#*)", src[i:]).group(1)
start = i + 2 + len(hashes)
end = src.find('"' + hashes, start)
end = n if end < 0 else end
spans.append((start, end))
blank(start, end)
i = end + 1 + len(hashes)
elif c == '"':
j = i + 1
while j < n and src[j] != '"':
j += 2 if src[j] == "\\" else 1
spans.append((i + 1, j))
blank(i + 1, j)
i = j + 1
elif c == "'" and i + 2 < n and (src[i + 1] == "\\" or src[i + 2] == "'"):
# an escape is two characters or more, so `'\''` cannot close on itself
end = src.find("'", i + 3 if src[i + 1] == "\\" else i + 2)
end = n if end < 0 else end
spans.append((i + 1, end))
blank(i + 1, end)
i = end + 1
else:
i += 1
return spans, "".join(masked)
def test_ranges(masked: str) -> tuple[list[tuple[int, int]], list[str]]:
"""The spans of `#[cfg(test)]` items, and the names of test modules kept in their own file."""
ranges: list[tuple[int, int]] = []
outlined: list[str] = []
for match in re.finditer(r"#\[cfg\(test\)\]", masked):
body = re.compile(r"[{;]").search(masked, match.end())
if body is None:
continue
if body.group() == ";":
declared = re.search(r"\bmod\s+(\w+)\s*$", masked[match.end() : body.start()])
if declared:
outlined.append(declared.group(1))
continue
depth, j = 0, body.start()
while j < len(masked):
if masked[j] == "{":
depth += 1
elif masked[j] == "}":
depth -= 1
if depth == 0:
break
j += 1
ranges.append((match.start(), j))
return ranges, outlined
def source_codepoints() -> set[int]:
"""Non-ASCII characters in the TUI's string literals, outside test code.
Errs toward including: a literal that never reaches the screen costs one extra row in the
report, while a missed one is a character the recommended face was never asked about.
"""
parsed = {}
skipped: set[pathlib.Path] = set(NOT_GLYPHS)
for path in (p for root in DRAWING_SOURCES for p in root.rglob("*.rs")):
src = path.read_text(encoding="utf-8")
spans, masked = rust_literals(src)
ranges, outlined = test_ranges(masked)
parsed[path] = (src, spans, ranges)
# `foo.rs` keeps its children in `foo/`; `lib.rs`, `main.rs` and `mod.rs` beside themselves
home = path.parent if path.stem in ("lib", "main", "mod") else path.parent / path.stem
for name in outlined:
skipped.update({home / f"{name}.rs", home / name})
# a second pass, because a directory's files can be walked before the file declaring them tests
used: set[int] = set()
for path, (src, spans, ranges) in parsed.items():
if any(path == s or s in path.parents for s in skipped):
continue
for start, end in spans:
if any(lo <= start <= hi for lo, hi in ranges):
continue
literal = src[start:end]
used.update(ord(c) for c in literal if ord(c) > 0x7F)
used.update(int(h, 16) for h in re.findall(r"\\u\{([0-9A-Fa-f]{1,6})\}", literal))
return {cp for cp in used if cp > 0x7F}
def asset_codepoints() -> set[int]:
"""Non-ASCII characters the site's assets and captures draw, as site-fonts.sh reads them."""
import json
used: set[str] = set()
for directory in DRAWING_ASSETS:
for path in directory.glob("*.svg"):
body = re.sub(r"<[^>]+>", "", path.read_text(encoding="utf-8"))
used.update(body.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&"))
for path in directory.glob("*.cast"):
for line in path.read_text(encoding="utf-8").splitlines():
try:
event = json.loads(line)
except ValueError:
continue
if isinstance(event, list) and len(event) == 3 and isinstance(event[2], str):
used.update(event[2])
return {ord(c) for c in used if ord(c) > 0x7F}
def identifier_tail(src: str, i: int) -> bool:
"""Whether position `i` continues an identifier, which makes an `r` there not a raw string."""
return i > 0 and (src[i - 1].isalnum() or src[i - 1] == "_")
def private_use(cp: int) -> bool:
return 0xE000 <= cp <= 0xF8FF or 0xF0000 <= cp <= 0xFFFFD
def braille(cp: int) -> bool:
return 0x2800 <= cp <= 0x28FF
def survey_faces(paths: list[str]) -> int:
"""Report each face against everything Luxe draws. Non-zero if any misses or spills anything."""
try:
from fontTools.pens.boundsPen import BoundsPen
from fontTools.ttLib import TTFont
except ImportError:
sys.exit("glyph-survey needs fontTools: pip install fonttools")
drawn = source_codepoints() | asset_codepoints()
classes = {
"icons": [cp for cp in drawn if private_use(cp)],
"box and block": [cp for cp in drawn if synthesized(cp)],
"braille": [cp for cp in drawn if braille(cp)],
}
classes["marks"] = [cp for cp in drawn if not any(cp in group for group in classes.values())]
print(
f"Luxe draws {len(drawn)} non-ASCII characters: "
+ ", ".join(f"{len(group)} {name}" for name, group in classes.items())
+ "\n",
file=sys.stderr,
)
failed = False
for raw in paths:
path = pathlib.Path(raw)
if not path.is_file():
print(f"{raw}: no such file")
failed = True
continue
font = TTFont(path, fontNumber=0)
cmap = font.getBestCmap()
glyphs = font.getGlyphSet()
# a symbols-only face has no letters to take the cell from; its space is the next best thing
cell_glyph = cmap.get(ord("M")) or cmap.get(ord(" "))
if cell_glyph is None:
print(f"{path.name}: no letter or space to measure a cell from")
failed = True
continue
advance = font["hmtx"][cell_glyph][0]
em = font["head"].unitsPerEm
def spills(cp: int) -> bool:
pen = BoundsPen(glyphs)
glyphs[cmap[cp]].draw(pen)
if pen.bounds is None:
return False
left, _, right, _ = pen.bounds
return right > advance * (1 + INK_TOLERANCE) or left < -advance * INK_TOLERANCE
missing = {name: [cp for cp in group if cp not in cmap] for name, group in classes.items()}
spilled = sorted(cp for cp in drawn if cp in cmap and not synthesized(cp) and spills(cp))
absent = sum(len(group) for group in missing.values())
print(f"{path.name}")
print(f" has {len(drawn) - absent}/{len(drawn)}, cell {advance / em:.2f} em")
for name, group in missing.items():
if group:
shown = "" if name == "icons" else " " + " ".join(chr(cp) for cp in sorted(group))
print(f" missing {name}: {len(group)}{shown}")
if spilled:
icons = [cp for cp in spilled if private_use(cp)]
text = [cp for cp in spilled if not private_use(cp)]
if icons:
print(f" {len(icons)} icons spill into the next cell (the non-Mono cut?)")
if text:
print(f" spills into the next cell: {' '.join(chr(cp) for cp in text)}")
# braille is the one class allowed to come from another font, so it cannot fail a face
if absent - len(missing["braille"]) or spilled:
failed = True
else:
print(" draws everything Luxe does, each inside its cell")
font.close()
return 1 if failed else 0
def emit(cps: list[int]) -> None:
for cp in cps:
try:
name = unicodedata.name(chr(cp))
except ValueError:
name = "?"
print(f"U+{cp:04X}\t{chr(cp)}\t{name}")
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--check", action="store_true", help="verify portable.txt against the panel")
parser.add_argument("--candidates", action="store_true", help="survey the wider palette")
parser.add_argument(
"--face", nargs="+", metavar="FILE", help="measure font files against everything Luxe draws"
)
args = parser.parse_args()
if args.face:
return survey_faces(args.face)
cov = coverage()
panel = list(cov)
print(f"panel: {len(panel)} faces — {', '.join(panel)}\n", file=sys.stderr)
if args.candidates:
rows = []
for ch in dict.fromkeys(CANDIDATES):
if synthesized(ord(ch)):
continue
absent = [f for f in panel if ord(ch) not in cov[f]]
rows.append((len(absent), ch, absent))
for count, ch, absent in sorted(rows):
verdict = "PORTABLE" if not count else f"missing {count}/{len(panel)}: {', '.join(absent)}"
print(f" {ch} U+{ord(ch):04X} {verdict}")
return 0
listed = parse_portable()
broken = {}
for cp in listed:
absent = [f for f in panel if cp not in cov[f]]
if absent:
broken[cp] = absent
if args.check:
if broken:
print(f"{PORTABLE.relative_to(ROOT)} claims coverage the panel does not have:\n")
for cp, absent in broken.items():
print(f" U+{cp:04X} {chr(cp)} — absent from {', '.join(absent)}")
return 1
print(f"portable.txt — {len(listed)} characters, present in all {len(panel)} faces")
return 0
print(f"# {len(listed)} surveyed characters, present in all {len(panel)} faces")
emit(listed)
if broken:
print("\n# NOT portable, listed anyway:", file=sys.stderr)
for cp, absent in broken.items():
print(f"# U+{cp:04X} {chr(cp)} — {', '.join(absent)}", file=sys.stderr)
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())

25
scripts/guide-bundle.sh Executable file
View File

@@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Bundle the user guide into the binary's source tree, for `luxe docs`.
#
# `docs/guide/` is the one source of the guide. A published crate carries only its own directory, so
# `cargo install luxe-cli` would have no guide to show; this writes every page into one file inside
# `luxe-cli`, which `luxe docs` embeds. The `guide_check` test fails when the bundle and the guide
# disagree, so run this after editing a page.
#
# scripts/guide-bundle.sh # write crates/luxe-cli/src/guide.md
set -euo pipefail
# byte order, so the bundle does not depend on the locale it was written in
export LC_ALL=C
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
out="${repo_root}/crates/luxe-cli/src/guide.md"
{
printf '%s\n' '<!-- Generated by scripts/guide-bundle.sh from docs/guide/. Edit the guide, not this file. -->'
for page in "${repo_root}"/docs/guide/*.md; do
printf '@@@ page: %s\n' "$(basename "${page}" .md)"
cat "${page}"
done
} >"${out}"
echo "bundled $(ls "${repo_root}"/docs/guide/*.md | wc -l) pages into ${out#"${repo_root}/"}"

86
scripts/install-dev.sh Executable file
View File

@@ -0,0 +1,86 @@
#!/usr/bin/env bash
# Refresh the `luxe` you dogfood with.
#
# Development and the test gate run the *debug* profile, but the `luxe` on PATH is a symlink to
# `target/release/luxe` — so a fix can be green in the workspace and still absent from the binary
# you actually launch. That gap is silent and costs a debugging session every time. This builds
# release and points the symlink at it.
#
# Usage:
# scripts/install-dev.sh [--gate] [bin-dir]
#
# --gate Run fmt/clippy/tests first and refuse to install if any fail.
# [bin-dir] Where to put the symlink (default: ~/.local/bin).
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
run_gate=false
bin_dir="${HOME}/.local/bin"
for arg in "$@"; do
case "$arg" in
--gate) run_gate=true ;;
-h | --help)
sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
exit 0
;;
-*)
echo "unknown flag: $arg" >&2
exit 2
;;
*) bin_dir="$arg" ;;
esac
done
cd "$repo_root"
if [[ "$run_gate" == true ]]; then
echo "==> gate"
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
# Ask cargo, not PATH: the nextest binary lives in ~/.cargo/bin, which a shell that reaches
# cargo through a rustup shim in /usr/bin doesn't necessarily have.
if cargo nextest --version >/dev/null 2>&1; then
cargo nextest run --workspace
else
# `cargo test` runs the suite as threads in ONE process, and a handful of tests set `HOME`
# to a temp dir to isolate global config. Those mutations are process-wide, so they can
# break whichever test happens to run beside them (the git-commit tests lose the global
# identity and fail). Install nextest for a trustworthy gate: cargo install cargo-nextest.
echo "warning: cargo-nextest not found; falling back to cargo test (shared process," >&2
echo " env-mutating tests can cross-talk — install cargo-nextest for a clean run)" >&2
cargo test --workspace
fi
fi
echo "==> building release"
cargo build --release -p luxe-cli
binary="${repo_root}/target/release/luxe"
[[ -x "$binary" ]] || {
echo "expected a binary at ${binary}" >&2
exit 1
}
mkdir -p "$bin_dir"
link="${bin_dir}/luxe"
# Replace whatever is there (stale symlink, or a copy from an older install) rather than failing.
ln -sfn "$binary" "$link"
echo "==> installed"
printf ' %s -> %s\n' "$link" "$(readlink -f "$link")"
printf ' built %s\n' "$(date -r "$binary" '+%Y-%m-%d %H:%M:%S')"
printf ' commit %s\n' "$(git -C "$repo_root" log -1 --format='%h %s' 2>/dev/null || echo 'unknown')"
# "Dirty" means the binary contains something no commit does. Tracked edits always qualify;
# untracked files only when they are source, so stray screenshots and scratch notes stay quiet.
tracked_changes="$(git -C "$repo_root" status --porcelain --untracked-files=no 2>/dev/null)"
untracked_source="$(git -C "$repo_root" ls-files --others --exclude-standard -- 'crates/*' 2>/dev/null)"
if [[ -n "$tracked_changes" || -n "$untracked_source" ]]; then
echo ' note: built from a dirty tree (uncommitted changes are included)'
fi
case ":${PATH}:" in
*":${bin_dir}:"*) ;;
*) echo " warning: ${bin_dir} is not on your PATH" >&2 ;;
esac

50
scripts/make-big-session.py Executable file
View File

@@ -0,0 +1,50 @@
#!/usr/bin/env python3
"""Build a long session out of a real one, so frame cost can be measured against length.
A perf claim about the TUI is only worth what it was measured on, and the interesting sizes are the
ones nobody has a handy session for. This repeats a real transcript end to end with fresh entry ids
and a correct parent chain, which `luxe --resume` then loads like any other.
scripts/make-big-session.py .luxe/sessions/<project>/<id>.jsonl 40 <new-id>
scripts/tui-latency.py --resume <new-id>
"""
from __future__ import annotations
import json
import pathlib
import sys
import uuid
def main() -> int:
if len(sys.argv) != 4:
print(__doc__, file=sys.stderr)
return 2
source = pathlib.Path(sys.argv[1])
repeats = int(sys.argv[2])
destination = source.parent / f"{sys.argv[3]}.jsonl"
entries = [json.loads(line) for line in source.read_text().splitlines() if line.strip()]
if not entries:
print(f"{source} holds no entries", file=sys.stderr)
return 1
header = dict(entries[0], id=str(uuid.uuid4()), parent_id=None)
out = [header]
parent = header["id"]
for _ in range(repeats):
for entry in entries[1:]:
copy = json.loads(json.dumps(entry))
copy["id"] = str(uuid.uuid4())
copy["parent_id"] = parent
parent = copy["id"]
out.append(copy)
destination.write_text("".join(json.dumps(entry) + "\n" for entry in out))
print(f"{destination} — {len(out)} entries, {destination.stat().st_size / 1024:.0f} KiB")
return 0
if __name__ == "__main__":
sys.exit(main())

28
scripts/mutants.sh Executable file
View File

@@ -0,0 +1,28 @@
#!/usr/bin/env bash
# cargo-mutants, in a memory-capped scope of its own.
#
# A mutant can turn a loop that pushes into one that never ends, and every test that reaches it
# then allocates until something stops it. With nextest running a thread per core that is several
# at once, and on a desktop the thing that stops it is systemd-oomd — which kills the whole unit the
# run lives in, the terminal it was started from included. It did, once, taking an agent's session
# with it.
#
# So the run gets a unit of its own with a ceiling. Hit it and the kernel ends that scope, the test
# in question fails, and the terminal stays up. Where there is no systemd user session (macOS, a
# container, CI) it runs uncapped and says so; the test-thread cap in `.cargo/mutants.toml` still
# applies.
#
# LUXE_MUTANTS_MEMORY the ceiling, as systemd reads it (default 24G)
#
# Usage: scripts/mutants.sh [cargo mutants arguments…]
# scripts/mutants.sh -p luxe-tui -f crates/luxe-tui/src/mentions.rs
set -euo pipefail
cap="${LUXE_MUTANTS_MEMORY:-24G}"
if command -v systemd-run >/dev/null 2>&1 && systemctl --user show-environment >/dev/null 2>&1; then
exec systemd-run --user --scope --quiet --collect \
-p MemoryMax="$cap" -p MemorySwapMax=0 \
-- cargo mutants "$@"
fi
echo "mutants.sh: no systemd user session here, so the run has no memory ceiling" >&2
exec cargo mutants "$@"

101
scripts/publish-clean.sh Executable file
View File

@@ -0,0 +1,101 @@
#!/usr/bin/env bash
# Materialize a clean, publishable copy of Luxe — without this repo's development
# artifacts (PROJECT.md, PROGRESS.md, docs/plan/, .pi/, …) or its git history.
#
# The exclusions are declared as `export-ignore` in .gitattributes, so `git archive`
# does the filtering for us. The result is a fresh tree suitable for `git init` in a
# new public repository. Luxe never requires the excluded files at runtime.
#
# Usage:
# scripts/publish-clean.sh <target-dir> [ref]
#
# <target-dir> Empty/nonexistent directory to populate (required).
# [ref] Git ref to export (default: HEAD).
#
# Example:
# scripts/publish-clean.sh /tmp/luxe-public
# cd /tmp/luxe-public && git init && git add -A && git commit -m "Initial public release"
set -euo pipefail
target="${1:-}"
ref="${2:-HEAD}"
if [[ -z "$target" ]]; then
echo "usage: $0 <target-dir> [ref]" >&2
exit 2
fi
if [[ -e "$target" && -n "$(ls -A "$target" 2>/dev/null)" ]]; then
echo "error: target '$target' exists and is not empty" >&2
exit 1
fi
repo_root="$(git rev-parse --show-toplevel)"
cd "$repo_root"
mkdir -p "$target"
# --worktree-attributes honors the working-tree .gitattributes export-ignore rules,
# so the exclusions apply whether or not .gitattributes has been committed yet.
git archive --worktree-attributes "$ref" | tar -x -C "$target"
# `git archive` still emits directory entries for fully-excluded trees; drop them so the
# published tree has no empty `docs/plan/` stub (git couldn't track it anyway).
find "$target" -mindepth 1 -type d -empty -delete
# Verify rather than trust: gitattributes patterns are easy to get subtly wrong (a trailing
# slash matches nothing, so `docs/plan/` silently exports the whole directory). Publishing the
# planning spine or `.pi/memory/` to a public repo is not a recoverable mistake.
leaked=()
for path in PROJECT.md PROGRESS.md PLAN.md ROADMAP.md docs/plan docs/eval .pi \
luxe-review-findings.md shine-text.md scripts/tool-ergonomics.sh; do
if [[ -f "$target/$path" ]] ||
[[ -d "$target/$path" && -n "$(find "$target/$path" -type f -print -quit)" ]]; then
leaked+=("$path")
fi
done
leaked+=($(cd "$target" && find . -path './docs/HANDOFF-*' -print))
if ((${#leaked[@]})); then
echo "error: development artifacts leaked into '$target': ${leaked[*]}" >&2
echo " check the export-ignore patterns in .gitattributes (use 'dir/**', not 'dir/')" >&2
exit 1
fi
# Then read what did ship. Pointers into the excluded tree dangle in public, a home path or a
# private key says something about this machine, and the denylist holds the names that must never
# leave it. The denylist lives in .git/info, outside the tree, because a file listing private names
# would publish them; one PCRE per line, `#` for comments.
denylist="${PUBLISH_DENYLIST:-$repo_root/.git/info/publish-denylist}"
# A citation names a file that did not ship; a bare `docs/plan/` in backticks points at the
# directory. Either dangles. A generic path in an example (`docs/plan/*.md`) is fine.
cited=$(git ls-files -z docs/plan docs/eval | xargs -0 -n1 | sed 's/[.]/\\./g' | paste -sd'|')
patterns=(
"(${cited})"
'`docs/(plan|eval)/`'
"$(printf '%s' "$HOME" | sed 's/[][\\.*^$+?(){}|/]/\\&/g')(/|\b)"
'^-----BEGIN [A-Z ]*PRIVATE KEY-----$'
'sk-ant-api\d\d-[A-Za-z0-9_-]{80,}'
'sk-(proj|svcacct)-[A-Za-z0-9_-]{80,}'
'\bghp_[A-Za-z0-9]{36}\b'
'github_pat_[A-Za-z0-9_]{80,}'
)
if [[ -f "$denylist" ]]; then
while IFS= read -r line; do
[[ -z "$line" || "$line" == \#* ]] || patterns+=("$line")
done <"$denylist"
else
echo "warning: no denylist at $denylist; scanning for the built-in patterns only" >&2
fi
hits=$(cd "$target" && for pattern in "${patterns[@]}"; do
grep -rIPn --exclude-dir=node_modules --exclude=publish-clean.sh --exclude=.gitattributes --exclude=.gitignore -e "$pattern" . || true
done | sort -u)
if [[ -n "$hits" ]]; then
echo "error: the exported tree mentions something it must not ($(wc -l <<<"$hits") lines):" >&2
echo "$hits" | cut -c1-200 >&2
exit 1
fi
echo "Clean tree written to: $target"
echo "Excluded: PROJECT.md PROGRESS.md PLAN.md ROADMAP.md docs/plan/ docs/eval/ docs/HANDOFF-*.md .pi/"
echo
echo "Next: cd $target && git init && git add -A && git commit -m 'Initial public release'"

266
scripts/remediation-eval.py Executable file
View File

@@ -0,0 +1,266 @@
#!/usr/bin/env python3
"""Ask real models to fix review comments and see whether Luxe can read what they report.
A fix request ends with a remediation report, and the review learns what the agent did only from
it. Whether a model writes one Luxe can read is a property of the model and of the prompt, so it is
measured against live models rather than asserted in a unit test. Each run is a scratch repository
with two bugs, a working-tree review, a comment on each, and a fix request over `luxe --rpc`; the
turn's assistant text is then read back from the session log and sorted by how it wrapped its
report.
scripts/remediation-eval.py --runs 3 --out /tmp/remediation github-copilot/gpt-4o github-copilot/gpt-5-mini
It costs real calls and its numbers move with the models, so it is a check to run after changing
the prompt or the reader, not a gate.
"""
import argparse
import concurrent.futures
import json
import os
import queue
import re
import shutil
import subprocess
import tempfile
import threading
import time
SOURCE_BEFORE = '''def total(numbers):
result = 0
for index in range(len(numbers)):
result += numbers[index]
return result
def average(numbers):
return total(numbers) / len(numbers)
'''
SOURCE_AFTER = '''def total(numbers):
result = 0
for index in range(1, len(numbers)):
result += numbers[index]
return result
def average(numbers):
return total(numbers) / len(numbers)
'''
class Luxe:
def __init__(self, luxe, model, cwd):
self.proc = subprocess.Popen(
[luxe, "--rpc", "--model", model], cwd=cwd, stdin=subprocess.PIPE,
stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, bufsize=1)
self.frames = queue.Queue()
self.kinds = []
threading.Thread(target=self._read, daemon=True).start()
def _read(self):
for line in self.proc.stdout:
self.frames.put(json.loads(line))
self.frames.put(None)
def send(self, kind, content=None):
frame = {"kind": kind} | ({"content": content} if content is not None else {})
self.proc.stdin.write(json.dumps(frame) + "\n")
self.proc.stdin.flush()
def wait(self, kind, match=lambda c: True, timeout=400):
deadline = time.time() + timeout
while time.time() < deadline:
try:
frame = self.frames.get(timeout=max(0.1, deadline - time.time()))
except queue.Empty:
break
if frame is None:
raise RuntimeError(f"stream ended waiting for {kind}")
k, c = frame["kind"], frame.get("content")
self.kinds.append(k)
if k == "permission_requested":
self.send("respond_permission", {"id": c["id"], "reply": "once"})
continue
if k == "question_asked":
self.send("answer_question", {"id": c["id"], "reply": "cancelled"})
continue
if k == "action_rejected":
raise RuntimeError(f"rejected: {c}")
if k == kind and match(c):
return c
raise RuntimeError(f"timed out waiting for {kind}")
def close(self):
try:
self.send("close")
self.proc.wait(timeout=60)
except Exception:
self.proc.kill()
def git(cwd, *args):
subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
def scratch():
root = tempfile.mkdtemp(prefix="remed-eval-")
git(root, "init", "-q")
git(root, "config", "user.email", "eval@example.invalid")
git(root, "config", "user.name", "Eval")
open(os.path.join(root, "stats.py"), "w").write(SOURCE_BEFORE)
git(root, "add", ".")
git(root, "commit", "-qm", "initial")
open(os.path.join(root, "stats.py"), "w").write(SOURCE_AFTER)
return root
def anchor(review, line_text):
for file in review["files"]:
for hunk in file["hunks"]:
for line in hunk["lines"]:
if line_text in line.get("text", line.get("content", "")) and line["kind"] == "addition":
return {"kind": "line", "file_id": file["id"], "hunk_id": hunk["id"],
"side": "new", "line": line["new_line"]}
for file in review["files"]:
return {"kind": "file", "file_id": file["id"]}
def assistant_texts(root):
"""Assistant text per message after the last fix request, in order."""
sessions = os.path.join(root, ".luxe", "sessions")
path = max((os.path.join(d, f) for d, _, fs in os.walk(sessions) for f in fs if f.endswith(".jsonl")),
key=os.path.getmtime)
texts, started = [], False
for line in open(path):
kind = json.loads(line)["kind"]
if kind["kind"] != "message":
continue
message = kind["data"]
text = "".join(b.get("content", "") for b in message["content"] if b.get("type") == "text")
if message["role"] == "user" and "Mode: RequestFixes" in text:
texts, started = [], True
continue
if started and message["role"] == "assistant":
calls = sum(1 for b in message["content"] if b.get("type") == "tool_call")
texts.append({"text": text, "tool_calls": calls})
return texts
def user_texts(root):
"""Every user message in the newest session, as text."""
sessions = os.path.join(root, ".luxe", "sessions")
path = max((os.path.join(d, f) for d, _, fs in os.walk(sessions) for f in fs if f.endswith(".jsonl")),
key=os.path.getmtime)
texts = []
for line in open(path):
kind = json.loads(line)["kind"]
if kind["kind"] == "message" and kind["data"]["role"] == "user":
texts.append("".join(b.get("content", "") for b in kind["data"]["content"] if b.get("type") == "text"))
return texts
def classify(texts):
final = texts[-1]["text"] if texts else ""
every = "\n".join(t["text"] for t in texts)
fences = re.findall(r"^[ \t]*(?:```|~~~)([^\n`]*)$", final, re.M)
has_json = '"findings"' in final
earlier = any('"findings"' in t["text"] for t in texts[:-1])
if "```luxe-remediation" in final:
shape = "named fence"
elif has_json and fences:
shape = f"other fence ({','.join(sorted(set(f.strip() or 'bare' for f in fences)))})"
elif has_json:
shape = "unfenced json"
elif earlier:
shape = "report in an earlier message"
else:
shape = "no report"
return shape, final, every
def run_one(luxe_bin, model, out, index):
root = scratch()
luxe = Luxe(luxe_bin, model, root)
record = {"model": model, "run": index, "root": root}
try:
luxe.wait("ready")
luxe.send("load_guided_review", {"request_id": "load", "target": {"kind": "working_tree"}})
review = luxe.wait("guided_review_loaded", lambda c: c["request_id"] == "load")["review"]
rid = review["id"]
luxe.send("edit_review", {"request_id": "c1", "review_id": rid, "edit": "comment",
"anchor": anchor(review, "range(1"), "severity": "blocking",
"body": "This skips the first number, so every total is wrong."})
luxe.wait("review_session_saved", lambda c: c["request_id"] == "c1")
luxe.send("edit_review", {"request_id": "c2", "review_id": rid, "edit": "comment",
"anchor": anchor(review, "range(1"), "severity": "suggestion",
"body": "average() divides by zero on an empty list; return 0.0 there."})
saved = luxe.wait("review_session_saved", lambda c: c["request_id"] == "c2")["session"]
ids = [f["id"] for f in saved["findings"]]
luxe.send("edit_review", {"request_id": "send", "review_id": rid, "edit": "send",
"finding_ids": ids, "mode": "request_fixes"})
reported = {"report": None}
def done(c):
return any(s["dispatch"] in ("completed", "failed", "failed_retryable") and s["mode"] == "request_fixes"
for s in c["session"]["submissions"])
started = time.time()
while True:
frame = luxe.wait("review_session_saved", timeout=600)
if done(frame):
break
# the report event precedes completion, so it is in the kinds seen
record["reported"] = "remediation_reported" in luxe.kinds
record["asked"] = any(t.startswith("Guided review report") for t in user_texts(root))
record["seconds"] = round(time.time() - started)
threads = {f["label"]: [m["body"] for m in f["thread"] if m["author"] == "agent"]
for f in frame["session"]["findings"]}
record["agent_notes"] = threads
record["states"] = {f["label"]: f["state"] for f in frame["session"]["findings"]}
except Exception as error:
record["error"] = str(error)
finally:
luxe.close()
try:
texts = assistant_texts(root)
record["shape"], final, every = classify(texts)
record["messages"] = len(texts)
name = f"{model.replace('/', '_')}-{index}"
open(os.path.join(out, name + ".final.txt"), "w").write(final)
open(os.path.join(out, name + ".all.json"), "w").write(json.dumps(texts, indent=1))
except Exception as error:
record.setdefault("error", f"reading transcript: {error}")
open(os.path.join(out, "results.jsonl"), "a").write(json.dumps(record) + "\n")
print(f"{model:40} run {index}: reported={record.get('reported')} asked={record.get('asked')} "
f"shape={record.get('shape')} {record.get('error', '')}", flush=True)
return record
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--luxe", default="luxe", help="the binary to drive; target/debug/luxe for a branch")
parser.add_argument("--runs", type=int, default=2)
parser.add_argument("--out", required=True)
parser.add_argument("--parallel", type=int, default=4)
parser.add_argument("models", nargs="+")
args = parser.parse_args()
# luxe runs inside each scratch repository, so a relative path has to be made absolute first
found = shutil.which(args.luxe) if os.sep not in args.luxe else os.path.abspath(args.luxe)
if not found or not os.access(found, os.X_OK):
parser.error(f"no luxe at {args.luxe}")
args.luxe = found
os.makedirs(args.out, exist_ok=True)
jobs = [(m, i) for i in range(args.runs) for m in args.models]
with concurrent.futures.ThreadPoolExecutor(args.parallel) as pool:
records = list(pool.map(lambda job: run_one(args.luxe, job[0], args.out, job[1]), jobs))
print(f"\n{'model':40} {'read':>6} {'asked':>6} {'runs':>6}")
for model in args.models:
mine = [r for r in records if r["model"] == model]
read = sum(1 for r in mine if r.get("reported"))
asked = sum(1 for r in mine if r.get("asked"))
print(f"{model:40} {read:>6} {asked:>6} {len(mine):>6}")
print(f"\ntranscripts and results.jsonl in {args.out}")
if __name__ == "__main__":
main()

241
scripts/rust_source.py Normal file
View File

@@ -0,0 +1,241 @@
"""Just enough Rust lexing for the size ratchets: what is code, what is test, where a block ends.
Not a parser. It masks comments and literals so braces and attributes can be found reliably, finds
inline `#[cfg(test)] mod … { … }` blocks by matching braces (production code after a test module
still counts), classifies files that only exist under a test module, and measures the bodies of
`#[async_trait]` methods, which clippy cannot see because the macro rewrites them.
"""
import re
import subprocess
from functools import lru_cache
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
TEST_ATTR = re.compile(r"#\[cfg\(test\)\]")
ASYNC_TRAIT = re.compile(r"#\[(?:async_trait::)?async_trait(?:\([^)]*\))?\]")
MOD_DECL = re.compile(r"\bmod\s+(\w+)\s*([;{])")
FN_NAME = re.compile(r"\bfn\s+(\w+)")
def mask(source: str) -> str:
"""The source with comments blanked and literal contents replaced by `S`, newlines kept.
Lines keep their length, so a line is code exactly when its masked form has a non-space
character, and every brace left in the mask is a real one.
"""
out, i, n = [], 0, len(source)
while i < n:
c = source[i]
if source.startswith("//", i):
end = source.find("\n", i)
end = n if end < 0 else end
out.append(" " * (end - i))
i = end
elif source.startswith("/*", i):
depth, j = 1, i + 2
while j < n and depth:
if source.startswith("/*", j):
depth, j = depth + 1, j + 2
elif source.startswith("*/", j):
depth, j = depth - 1, j + 2
else:
j += 1
out.append(_blank(source[i:j]))
i = j
elif (raw := re.match(r'b?r(#*)"', source[i : i + 260])) and not _ident_before(source, i):
close = '"' + raw.group(1)
j = source.find(close, i + raw.end())
j = n if j < 0 else j + len(close)
out.append(_literal(source[i:j]))
i = j
elif c == '"' or (c == "b" and source.startswith('b"', i) and not _ident_before(source, i)):
j = i + (2 if c == "b" else 1)
while j < n and source[j] != '"':
j += 2 if source[j] == "\\" else 1
out.append(_literal(source[i : j + 1]))
i = j + 1
elif c == "'" and (char := re.match(r"'(\\(x[0-9a-fA-F]{2}|u\{[0-9a-fA-F]+\}|.)|[^\\'\n])'", source[i : i + 14])):
out.append(_literal(char.group(0)))
i += char.end()
else:
out.append(c)
i += 1
return "".join(out)
def _ident_before(source: str, i: int) -> bool:
return i > 0 and (source[i - 1].isalnum() or source[i - 1] == "_")
def _blank(text: str) -> str:
return "".join("\n" if ch == "\n" else " " for ch in text)
def _literal(text: str) -> str:
return "".join("\n" if ch == "\n" else "S" for ch in text)
def matching_brace(masked: str, open_at: int) -> int:
"""Index of the `}` closing the `{` at `open_at`, or the end of the text when it never closes."""
depth = 0
for k in range(open_at, len(masked)):
if masked[k] == "{":
depth += 1
elif masked[k] == "}":
depth -= 1
if depth == 0:
return k
return len(masked) - 1
def line_of(masked: str, index: int) -> int:
return masked.count("\n", 0, index)
def _after_attributes(masked: str, index: int) -> int:
"""Skip whitespace and further `#[…]` attributes after `index`."""
while True:
while index < len(masked) and masked[index].isspace():
index += 1
if not masked.startswith("#[", index):
return index
depth = 0
for k in range(index, len(masked)):
if masked[k] == "[":
depth += 1
elif masked[k] == "]":
depth -= 1
if depth == 0:
index = k + 1
break
else:
return len(masked)
def test_modules(masked: str) -> list[tuple[int, int]]:
"""Line spans `(first, last)` of inline `#[cfg(test)] mod name { … }` blocks."""
spans = []
for attr in TEST_ATTR.finditer(masked):
start = _after_attributes(masked, attr.end())
decl = re.match(r"(pub(\([^)]*\))?\s+)?mod\s+\w+\s*\{", masked[start:])
if decl:
open_at = start + decl.end() - 1
spans.append((line_of(masked, attr.start()), line_of(masked, matching_brace(masked, open_at))))
return spans
def out_of_line_test_modules(masked: str) -> list[str]:
"""Names of `#[cfg(test)] mod name;` declarations: files that only compile under test."""
names = []
for attr in TEST_ATTR.finditer(masked):
start = _after_attributes(masked, attr.end())
decl = re.match(r"(pub(\([^)]*\))?\s+)?mod\s+(\w+)\s*;", masked[start:])
if decl:
names.append(decl.group(3))
return names
def child_paths(path: str, name: str) -> list[str]:
"""Where `mod name;` in `path` can live."""
file = Path(path)
roots = file.name in ("lib.rs", "main.rs", "mod.rs") or file.parent.name in ("tests", "examples", "benches")
base = file.parent if roots else file.parent / file.stem
return [str(base / f"{name}.rs"), str(base / name / "mod.rs")]
@lru_cache(maxsize=None)
def rust_files() -> tuple[str, ...]:
listed = subprocess.run(
["git", "ls-files", "--cached", "--others", "--exclude-standard", "crates/*.rs"],
cwd=ROOT, check=True, capture_output=True, text=True,
).stdout.split()
return tuple(path for path in listed if (ROOT / path).exists())
@lru_cache(maxsize=None)
def masked_source(path: str) -> str:
return mask((ROOT / path).read_text(encoding="utf-8"))
def named_as_test(path: str) -> bool:
name = path.rsplit("/", 1)[-1]
return "/tests/" in path or name in ("tests.rs", "test_support.rs") or name.endswith("_tests.rs")
@lru_cache(maxsize=None)
def test_files() -> frozenset[str]:
"""Every file that only compiles under test: named so, declared under `#[cfg(test)]`, or a
module declared from inside one of those."""
known = set(rust_files())
tests = {path for path in known if named_as_test(path)}
for path in known:
for name in out_of_line_test_modules(masked_source(path)):
tests.update(candidate for candidate in child_paths(path, name) if candidate in known)
frontier = list(tests)
while frontier:
path = frontier.pop()
for decl in MOD_DECL.finditer(masked_source(path)):
if decl.group(2) != ";":
continue
for candidate in child_paths(path, decl.group(1)):
if candidate in known and candidate not in tests:
tests.add(candidate)
frontier.append(candidate)
return frozenset(tests)
def code_lines(masked: str, first: int, last: int) -> int:
"""Non-blank, non-comment lines in `first..=last`, which is how clippy counts a function."""
lines = masked.split("\n")[first : last + 1]
return sum(1 for line in lines if line.strip())
def async_trait_methods(path: str) -> list[tuple[str, int, int]]:
"""`(name, first_line, length)` for each method in an `#[async_trait]` impl outside tests."""
masked = masked_source(path)
in_tests = test_modules(masked)
methods = []
for attr in ASYNC_TRAIT.finditer(masked):
start = _after_attributes(masked, attr.end())
if not re.match(r"(unsafe\s+)?impl\b", masked[start:]):
continue
open_at = masked.find("{", start)
close_at = matching_brace(masked, open_at)
if any(first <= line_of(masked, open_at) <= last for first, last in in_tests):
continue
depth, k = 0, open_at
while k < close_at:
ch = masked[k]
if ch == "{":
depth += 1
elif ch == "}":
depth -= 1
elif depth == 1 and (fn := FN_NAME.match(masked, k)) and (k == 0 or not masked[k - 1].isalnum()):
body = _body_open(masked, fn.end(), close_at)
if body is None:
k = fn.end()
continue
body_end = matching_brace(masked, body)
first, last = line_of(masked, body), line_of(masked, body_end)
methods.append((fn.group(1), line_of(masked, k) + 1, code_lines(masked, first, last)))
k = body_end + 1
continue
k += 1
return methods
def _body_open(masked: str, after: int, limit: int) -> int | None:
"""The `{` opening a function body after its signature, or `None` for a declaration."""
depth = 0
for k in range(after, limit):
ch = masked[k]
if ch in "(<[":
depth += 1
elif ch in ")>]":
depth -= 1
elif ch == ";" and depth <= 0:
return None
elif ch == "{" and depth <= 0:
return k
return None

210
scripts/site-assets.sh Executable file
View File

@@ -0,0 +1,210 @@
#!/usr/bin/env bash
# Regenerate every asset the website derives from this repo.
#
# Nothing under the output directory is authored by hand: the logotype comes from the art constants,
# the color tokens from the theme JSON, and the screenshots from the production view path via the
# fixture runner. That is the point — a screenshot taken by hand is a claim about a build nobody can
# reproduce, and it starts lying the first time a border changes.
#
# Run it after anything that changes how Luxe looks, and commit the result. CI runs it with
# `--check`, which regenerates into a scratch directory and fails if the committed assets differ.
#
# The *demos* are not here and cannot be. They are recordings of real sessions against a real
# provider (`scripts/site-record.sh`), so no two runs produce the same bytes and nothing CI does
# can verify one. They live beside these, under `web/src/assets/captures/`, with a manifest saying
# what each was shot against. Everything in this directory is derived and checked; everything in
# that one is a take.
#
# Usage:
# scripts/site-assets.sh [--out DIR] [--check]
#
# --out DIR where to write (default: web/src/assets/generated)
# --check regenerate to a temp dir and diff against --out; write nothing
#
# The guide's screenshots are generated the same way, into docs/guide/images/, and checked with the
# rest.
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
out_dir="${repo_root}/web/src/assets/generated"
check=false
while [[ $# -gt 0 ]]; do
case "$1" in
--out)
out_dir="$2"
shift 2
;;
--check)
check=true
shift
;;
-h | --help)
sed -n '2,17p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
exit 0
;;
*)
echo "unknown argument: $1" >&2
exit 2
;;
esac
done
# The scenarios the site shows, and the terminal each is drawn at. Guided Review earns a wider box
# because it is a three-pane surface and a narrow capture sells it as a diff viewer. The dashboard
# is first because it is the first thing anyone sees, and it went uncaptured for far too long.
#
# The GitHub review surfaces are the landing page's, each twice: at the width a laptop shows and at
# the width a phone can read, which lays the same review out as one pane. So is peek, once wide
# enough to sit beside the conversation and once narrow enough to take its place, at the same
# aspect (172x50 against 110x32) so switching between the two does not jolt the page. The optional
# fourth field names the file when one scenario is drawn at two sizes, and the fifth opens a state
# over it, by the names `fixture_svg --overlay` takes (`/github` and `/pr` live there).
#
# <fixture scenario>:<cols>:<rows>[:<name>[:<overlay>]]
SHOTS=(
"dashboard:150:36"
"chat-tools:150:40"
"chat-streaming:150:36"
"chat-thinking:150:34"
"chat-question:150:34"
"guided-review-demo:180:44"
"changes-wide:240:40"
"dock-wide:170:42"
"session-picker:150:36"
"guided-review-pull-request:150:42"
"guided-review-pull-request:72:30:guided-review-pull-request.narrow"
"guided-review-pull-request-post:150:42"
"guided-review-pull-request-post:72:30:guided-review-pull-request-post.narrow"
"changes-wide:172:50:peek-beside"
"changes-narrow:110:32:peek-over"
"chat-idle:140:34:github-overview:github"
"chat-idle:72:30:github-overview.narrow:github-detail"
"chat-idle:140:34:github-conversation:github-conversation"
"chat-idle:72:30:github-conversation.narrow:github-conversation"
)
# The guide's screenshots, drawn narrower than the site's: the docs column is about 830px, and a
# 100-column capture keeps the type readable in it. Same fields; the name is required.
GUIDE_SHOTS=(
"dashboard:100:26:quickstart-dashboard"
"setup:110:34:quickstart-setup"
"dashboard-typing:100:28:interface-launcher-typing"
"dashboard-minimal:100:20:interface-launcher-minimal"
"settings-tools:120:36:configuration-settings"
"configuration:100:26:quickstart-configuration"
"chat-tool-run:100:22:quickstart-turn"
"guided-review-demo:110:34:quickstart-review"
"guided-review-open-pull-request:100:30:quickstart-pull-request"
"changes-wide:140:36:interface-peek"
"guided-review-demo:140:40:review-guide"
"guided-review-finish:110:26:review-finish"
"guided-review-pull-request:140:40:review-pull-request"
"chat-idle:140:34:github-overview:github"
"chat-idle:140:34:github-search:github-search"
"chat-idle:140:34:github-conversation:github-conversation"
"chat-question:100:22:agent-question"
"chat-turn:100:36:interface-turn"
"chat-permission:100:24:security-permission-prompt"
"chat-palette:100:30:commands-palette"
"chat-idle:100:22:mentions-picker:mention-files-status"
"session-picker:100:28:sessions-picker"
"chat-plan-ready:100:26:loop-plan-ready"
)
guide_dir="${repo_root}/docs/guide/images"
# Luxe's own theme, the one the site is set in. The colors are baked into each file rather than left
# as custom properties, so a capture stays correct wherever it is embedded — a README, someone's
# blog. The theme preview is the one picture drawn in every theme, below.
THEMES=("luxe")
# The figures the landing page quotes, derived rather than typed.
#
# Only the ones that change with the thing they describe: the theme count moves when a theme ships,
# and the catalog moves when the models.dev snapshot is refreshed, which regenerates this in the
# same pull request. A test total used to live here too, and it made every pull request that added a
# test fail this check until someone regenerated a number the page barely needed.
facts() {
python3 -c "import gzip,json,sys
catalog = json.load(gzip.open('${repo_root}/crates/luxe-providers/data/models-dev-snapshot.json.gz'))
print(json.dumps({
'themes': len(json.load(open('${1}/themes.json'))),
'providers': len(catalog),
'models': sum(len(p.get('models', {})) for p in catalog.values()),
}, indent=2))"
}
fixture() { cargo run --quiet --release -p luxe-tui --features fixture --example fixture_svg -- "$@"; }
wordmark() { cargo run --quiet --release -p luxe-tui --example wordmark_svg -- "$@"; }
tokens() { cargo run --quiet --release -p luxe-tui --example theme_css; }
catalog() { cargo run --quiet --release -p luxe-tui --example theme_css -- --json; }
shiki() { cargo run --quiet --release -p luxe-tui --example shiki_theme -- "$@"; }
generate() {
local target="$1" guide_target="$2"
mkdir -p "${target}" "${guide_target}"
wordmark wordmark >"${target}/wordmark.svg"
wordmark mark >"${target}/mark.svg"
wordmark tile >"${target}/tile.svg"
tokens >"${target}/tokens.css"
catalog >"${target}/themes.json"
facts "${target}" >"${target}/facts.json"
shiki luxe >"${target}/shiki-luxe.json"
local shot theme scenario cols rows name
for shot in "${SHOTS[@]}"; do
IFS=: read -r scenario cols rows name overlay <<<"${shot}"
for theme in "${THEMES[@]}"; do
fixture --theme "${theme}" --scenario "${scenario}" \
--cols "${cols}" --rows "${rows}" ${overlay:+--overlay "${overlay}"} \
>"${target}/${name:-${scenario}}.${theme}.svg"
done
done
# The theme preview: the dashboard, once, in every built-in theme. Each color in it is a CSS
# variable and `theme-preview.json` says what each one is per theme, so the page can repaint the
# real UI as a reader points at a theme instead of shipping twelve copies of one picture. The
# shipped theme leads, so its colors are the fallbacks when no palette has been applied.
local palette
palette="$(python3 -c "
import json, sys
names = sorted(json.load(open(sys.argv[1])))
names.remove('luxe')
print(','.join(['luxe'] + names))
" "${target}/themes.json")"
fixture --scenario dashboard --cols 150 --rows 36 --palette "${palette}" \
--palette-json "${target}/theme-preview.json" >"${target}/theme-preview.svg"
for shot in "${GUIDE_SHOTS[@]}"; do
IFS=: read -r scenario cols rows name overlay <<<"${shot}"
fixture --theme luxe --scenario "${scenario}" --cols "${cols}" --rows "${rows}" \
${overlay:+--overlay "${overlay}"} >"${guide_target}/${name}.svg"
done
}
# One release build up front. Every generator is a separate `cargo run`, and letting each discover
# that for itself turns a five-second job into a minute of cargo deciding it has nothing to do.
cargo build --quiet --release -p luxe-tui --features fixture \
--example fixture_svg --example wordmark_svg --example theme_css --example shiki_theme
if [[ "${check}" == true ]]; then
scratch="$(mktemp -d)"
trap 'rm -rf "${scratch}"' EXIT
generate "${scratch}/site" "${scratch}/guide"
if diff -ru "${out_dir}" "${scratch}/site" && diff -ru "${guide_dir}" "${scratch}/guide"; then
echo "site assets are up to date"
else
echo >&2
echo "site assets are stale — run scripts/site-assets.sh and commit the result" >&2
exit 1
fi
exit 0
fi
generate "${out_dir}" "${guide_dir}"
printf '%s\n' "wrote $(find "${out_dir}" -type f | wc -l) files to ${out_dir}"
du -sh "${out_dir}" | cut -f1 | xargs -I{} echo "total {} on disk, and they gzip to about a tenth of that"

97
scripts/site-check.sh Executable file
View File

@@ -0,0 +1,97 @@
#!/usr/bin/env bash
# site-check — build the site, serve it the way Cloudflare does, and assert it renders.
#
# `astro build` proves the files exist; it never opens one. The demos shipped as empty boxes because
# the CSP blocked the player's WebAssembly, and no step in the pipeline was looking at a rendered
# page. This closes that gap.
#
# It serves through `wrangler pages dev` rather than `astro preview` on purpose: `_headers` — which
# is where the CSP lives — is applied by Pages and by nothing else, so a preview server would test
# a configuration that never reaches production.
set -euo pipefail
cd "$(dirname "$0")/.."
port="${PORT:-8788}"
serve_log="${TMPDIR:-/tmp}/site-check-serve.log"
skip_build=0
[[ "${1:-}" == "--no-build" ]] && skip_build=1
command -v "${CHROME:-google-chrome-stable}" >/dev/null 2>&1 || {
echo "site-check: no headless Chrome (set CHROME=...), skipping" >&2
exit 0
}
# Is anything listening there? Bash's own TCP redirection, because `ss` is Linux-only and `lsof` is
# not guaranteed anywhere.
port_is_open() {
(exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null
}
# Stop the server and everything it spawned.
#
# Signals the process *group*: wrangler spawns workerd and esbuild, and killing only the parent
# leaves the port held. Idempotent, because the interrupt traps below run it and then exit, which
# runs it again.
stop_server() {
[[ -n "${serve_pgid:-}" ]] || return 0
kill -TERM -- -"${serve_pgid}" 2>/dev/null || true
for _ in $(seq 1 30); do
kill -0 -- -"${serve_pgid}" 2>/dev/null || return 0
sleep 0.1
done
# workerd holds the port until it is gone, and the next run cannot tell a stale server from a
# fresh one — so a group that ignored the polite signal does not get to stay.
kill -KILL -- -"${serve_pgid}" 2>/dev/null || true
}
# The readiness probe only asks for `/`, and a stale workerd answers that with a 200 from whatever
# `dist` it was started on. A run that found the port held would therefore validate a build nobody
# made — quietly, and with a green check. Refusing here is also what lets the probe below trust the
# answer it gets: the port was free when this run started, and this run is what bound it.
if port_is_open "${port}"; then
echo "site-check: 127.0.0.1:${port} is already in use — stop that server, or set PORT=…" >&2
exit 1
fi
if ((skip_build == 0)); then
(cd web && npm run build)
fi
# `set -m` gives the background job a process group of its own, with the pgid `$!` reports. Without
# it a script's background job shares the shell's group, so `kill -- -$!` names a group that does
# not exist, the fallback kills the one process not holding anything, and workerd survives on the
# port. That is not only an interrupt path: it leaked on every clean run too.
set -m
(cd web && exec npx wrangler pages dev dist --port "${port}" --ip 127.0.0.1) >"${serve_log}" 2>&1 &
serve_pgid=$!
set +m
# EXIT alone is not enough: bash runs no EXIT trap when an *untrapped* signal kills it, so
# `timeout -s TERM` — which is how this runs unattended — skipped the cleanup entirely. Each of
# these exits with the shell's usual 128 + signal.
trap stop_server EXIT
trap 'stop_server; exit 130' INT
trap 'stop_server; exit 143' TERM
trap 'stop_server; exit 129' HUP
# A server that died is an answer, and without asking we spend the whole window discovering it.
gave_up=1
for _ in $(seq 1 60); do
if ! kill -0 -- -"${serve_pgid}" 2>/dev/null; then
echo "site-check: the dev server exited before it was ready" >&2
tail -20 "${serve_log}" >&2
exit 1
fi
if curl -fsS -o /dev/null "http://127.0.0.1:${port}/" 2>/dev/null; then
gave_up=0
break
fi
sleep 0.5
done
if ((gave_up == 1)); then
echo "site-check: the dev server never answered on 127.0.0.1:${port}" >&2
tail -20 "${serve_log}" >&2
exit 1
fi
node scripts/site-smoke.mjs "http://127.0.0.1:${port}"

404
scripts/site-cross.mjs Normal file
View File

@@ -0,0 +1,404 @@
#!/usr/bin/env node
/**
* Opens the site in every browser engine the machine can run, and asserts the demos actually start.
*
* `site-check.sh` already drives the *built* site in headless Chrome, which is the right check for
* the thing it guards — a real CSP, real headers, no uncaught exceptions. This one exists because
* two separate bugs slipped past it, and both were invisible for the same two reasons.
*
* **One engine is not coverage.** The demo player is behind a dynamic `import()`, and Vite's dev
* server optimizes it mid-session and invalidates the graph it had already served. Chrome quietly
* re-requests. Firefox calls the interrupted response corrupted, refuses it for a disallowed MIME
* type, and every demo on the page stays blank for the rest of the session.
*
* **The built site is not the dev site.** That failure never touched a production bundle, so no
* amount of checking `dist/` would have found it — and `npm run dev` is what anyone actually looks
* at while working.
*
* So this drives `astro dev` by default, in Chromium, Firefox and WebKit, and asserts the islands
* boot rather than that the markup exists. An engine the host cannot launch is reported and
* skipped: Playwright's WebKit build wants Ubuntu's ICU and libxml2 sonames, which a rolling distro
* does not have, and refusing to run anywhere it is missing would just mean nobody runs it.
*
* node scripts/site-cross.mjs # astro dev, every engine available
* node scripts/site-cross.mjs --built # the built site, served statically
* node scripts/site-cross.mjs --require webkit # fail if that engine cannot launch
*/
import { spawn } from "node:child_process";
import { createServer } from "node:http";
import { readFile, rm } from "node:fs/promises";
import { createRequire } from "node:module";
import { extname, join, normalize } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
const web = fileURLToPath(new URL("../web/", import.meta.url));
/** Pages worth opening, and what has to be alive on each once it has settled. */
const PAGES = [
{ path: "/", demos: true, stills: true },
{ path: "/themes/", demos: false, stills: false },
{ path: "/docs/", demos: false, stills: false },
];
/**
* Console noise that is the browser talking about itself rather than about us.
*
* Firefox warns about scroll-linked effects on any page with a scroll-driven reveal, which is a
* performance note about async panning and not a defect. Everything else is reported.
*/
const IGNORABLE = [
/scroll-linked positioning effect/i,
/\[vite\]/i,
/Download the .* DevTools/i,
// A *cancelled* request, not a failed one. The dev server's HMR client and the island scripts
// are routinely abandoned when a page settles, and Firefox reports that as a binding abort where
// Chrome says nothing at all. Three engines, three spellings for one condition — WebKit's was
// missing, so the optimizer reload that Chrome swallows and Firefox names failed the run outright
// on the engine nobody can reproduce locally.
/NS_BINDING_ABORTED/i,
/net::ERR_ABORTED/i,
/Load request cancelled/i,
];
/**
* Dev-server churn, which is Vite talking about itself.
*
* When the optimizer discovers a dependency it re-bundles and answers in-flight module requests
* with a 504, and its client recovers by reloading the page. Chrome swallows that silently; Firefox
* surfaces the rejected import first. Treating it as a defect makes this check fail on a page whose
* demos all started, which is a check nobody will keep.
*
* So dev is judged on its *end state* — did every island boot — and only the built site is held to
* zero errors. That still catches the failure this file was written for, because that one left the
* demos blank for the rest of the session rather than recovering.
*
* WebKit's spelling carries no URL, so unlike Firefox's it cannot be scoped to `.vite/deps`. It is
* forgiven anyway, and only here: a dev-only reload that recovers is not a defect, and holding one
* engine to a stricter rule than the other two only means its check gets switched off.
*/
const DEV_CHURN = [
/error loading dynamically imported module.*\.vite\/deps/i,
/Outdated Optimize Dep/i,
/Importing a module script failed/i,
];
const args = process.argv.slice(2);
const built = args.includes("--built");
const required = args.flatMap((arg, index) => (arg === "--require" ? [args[index + 1]] : []));
// === Serving ===
const MIME = {
".html": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".css": "text/css; charset=utf-8",
".svg": "image/svg+xml",
".json": "application/json",
".cast": "application/json",
".woff2": "font/woff2",
".png": "image/png",
".wasm": "application/wasm",
};
/** Serves `web/dist` the way a static host would, including the `.wasm` type the player needs. */
function serveBuilt(root) {
return new Promise((resolve) => {
const server = createServer(async (request, response) => {
const url = new URL(request.url ?? "/", "http://localhost");
const asked = normalize(join(root, decodeURIComponent(url.pathname)));
if (!asked.startsWith(root)) return response.writeHead(403).end();
// The type comes from the file that is actually sent, not from the path that was asked
// for. A directory has no extension, so deriving it from the URL served `index.html` as
// `application/octet-stream` — and a browser handed that downloads the page instead of
// rendering it, which surfaces as every engine failing to navigate.
for (const file of [asked, join(asked, "index.html")]) {
try {
const body = await readFile(file);
const type = MIME[extname(file)] ?? "application/octet-stream";
response.writeHead(200, { "content-type": type });
return response.end(body);
} catch {
/* try the next candidate */
}
}
response.writeHead(404).end("not found");
});
server.listen(0, () => resolve({ server, port: server.address().port }));
});
}
/**
* Starts `astro dev` on a cold dependency cache and waits for it to answer.
*
* The cache is cleared on purpose, and this is the whole reason the dev mode restarts the server
* per engine rather than sharing one. The failure being guarded against is a *race*: Vite optimizes
* the player the first time something asks for it, mid-session, and only the browser that arrives
* before that has happened is exposed to it. Run Chromium first against a shared server and it
* warms the cache for everyone — Firefox then sails through, the check goes green, and it has
* proved nothing. Verified by deleting the fix and watching this catch it.
*/
async function serveDev(port) {
await rm(join(web, "node_modules/.vite"), { recursive: true, force: true });
// Astro's own entry, not `npx`. A wrapper means the server is a *grandchild*, so stopping it
// needs a signal to the whole process group — and a group kill with the wrong pid takes the
// shell that launched this with it. Spawned directly, `child.kill()` is the server.
const child = spawn(
process.execPath,
[join(web, "node_modules/astro/bin/astro.mjs"), "dev", "--port", String(port)],
{ cwd: web, stdio: "ignore" },
);
return { child, port };
}
function shutdown(target) {
if (target?.server) target.server.close();
if (target?.child && !target.child.killed) {
target.child.kill("SIGTERM");
}
}
async function waitForServer(port, seconds = 90) {
for (let attempt = 0; attempt < seconds * 2; attempt += 1) {
try {
const response = await fetch(`http://localhost:${port}/`);
if (response.ok) return true;
} catch {
/* not up yet */
}
await new Promise((done) => setTimeout(done, 500));
}
return false;
}
// === Checking ===
/**
* Brings the hero to rest before anything is scrolled to.
*
* The hero's demo waits a screen below its place until the opening has played. Centring it from
* there scrolls the page to where it is *waiting*, the scroll assembles the hero, and the demo rises
* into its real place above the viewport — so whether it was ever seen depends on which frame each
* engine paints, and WebKit missed it. A reader never jumps to an element mid-assembly, so the check
* does what a reader's first scroll does and lets it settle.
*/
async function settleHero(tab) {
const assembling = await tab.evaluate(() => {
const hero = document.querySelector("[data-hero]");
if (!hero || getComputedStyle(hero).getPropertyValue("--p").trim() === "1") return false;
dispatchEvent(new Event("scroll"));
return true;
});
if (assembling) await tab.waitForTimeout(1400);
}
/**
* Whether each demo's terminal fills the frame the player sized it for, no wider and no narrower.
*
* The player sets its type from a measured `ch`, and Chromium then rounded each glyph's advance to a
* whole pixel, so a 120-cell line came out 120 roundings off: at this window the hero ran 7% off the
* right of its frame and cut the statusline mid-word, and at others it stopped short and left a
* margin of dead canvas. Nothing threw. Measured at 1600px and twice the density, because that is a
* size where the rounding goes the harmful way, and the system Chrome the smoke run drives already
* uses fractional advances and never showed it.
*/
async function demosFit(browser, port, path) {
const context = await browser.newContext({
viewport: { width: 1600, height: 1000 },
deviceScaleFactor: 2,
colorScheme: "dark",
});
const tab = await context.newPage();
const problems = [];
try {
await tab.goto(`http://localhost:${port}${path}`, { waitUntil: "networkidle" });
await settleHero(tab);
const demos = tab.locator(".demo");
const count = await demos.count();
for (let index = 0; index < count; index += 1) {
const demo = demos.nth(index);
await demo.evaluate((node) => node.scrollIntoView({ block: "center", behavior: "instant" }));
const started = await demo
.locator(".ap-line")
.first()
.waitFor({ timeout: 60_000 })
.then(() => true)
.catch(() => false);
if (!started) continue; // the boot check reports a demo that never starts
// The terminal against the frame the player sized it for. Its own width grows with its
// lines, so comparing those two with each other sees nothing
// Watched for a few seconds rather than read once: the terminal is as wide as its longest
// line so far, and a take whose first frame is short lines is narrow for that instant at
// the right scale. A rounding fault never comes right, so it still fails.
const measure = () =>
demo.evaluate((node) => ({
frame: node.querySelector(".ap-wrapper").getBoundingClientRect().width,
term: node.querySelector(".ap-term").getBoundingClientRect().width,
}));
const fits = (fit) => Math.abs(fit.term - fit.frame) <= Math.max(2, fit.frame * 0.01);
let fit = await measure();
for (let tries = 0; tries < 24 && !fits(fit); tries += 1) {
await tab.waitForTimeout(250);
fit = await measure();
}
if (!fits(fit)) {
problems.push(
`${path}: demo ${index + 1} is ${fit.term.toFixed(0)}px in a ` +
`${fit.frame.toFixed(0)}px frame — glyph advances are being rounded`,
);
}
}
} finally {
await context.close();
}
return problems;
}
/**
* Opens every page in one engine and reports what went wrong.
*
* The assertion that matters is `players === mounts`: markup being present proves the component
* rendered, and every failure this file exists for left the markup perfectly intact and the island
* dead inside it.
*/
async function checkEngine(engine, name, port) {
const browser = await engine.launch();
const problems = [];
try {
for (const page of PAGES) {
const context = await browser.newContext({
viewport: { width: 1440, height: 900 },
colorScheme: "dark",
});
const tab = await context.newPage();
const noise = [];
tab.on("pageerror", (error) => noise.push(`uncaught: ${error}`));
tab.on("console", (message) => {
if (message.type() === "error") noise.push(`console: ${message.text()}`);
});
tab.on("requestfailed", (request) => {
noise.push(`request failed: ${request.url()} (${request.failure()?.errorText})`);
});
await tab.goto(`http://localhost:${port}${page.path}`, { waitUntil: "networkidle" });
await settleHero(tab);
if (page.demos) {
// A demo waits until most of it is on screen before it starts, so bringing its top edge
// into view is not enough to ask whether it works — `scrollIntoViewIfNeeded` scrolls the
// minimum distance, which for a demo taller than half the viewport leaves it below the
// threshold and looking broken. Centring it is what a reader does.
const demos = tab.locator(".demo");
const count = await demos.count();
for (let index = 0; index < count; index += 1) {
const demo = demos.nth(index);
await demo.evaluate((node) =>
node.scrollIntoView({ block: "center", behavior: "instant" }),
);
// Scoped to *this* demo rather than to the page's nth player: they start lazily now,
// so a global index counts whichever happened to boot first.
//
// Generous, because a demo plays once and never pauses: by the time this asks
// about the fifth, four players are still rendering frames behind it. That is
// what a reader scrolling the page has too, but on a shared CI runner it starved
// the later ones past a 20s budget — which failed a different demo each run, in
// one engine, on a page nothing had changed. The claim being made is that a demo
// *starts*, not that it starts inside some particular second.
await demo
.locator(".ap-player")
.waitFor({ timeout: 60_000 })
.catch(() => problems.push(`${page.path}: demo ${index + 1} never started`));
}
if (count === 0) problems.push(`${page.path}: no demos on the page at all`);
}
if (page.stills && (await tab.locator(".still__img").count()) === 0) {
problems.push(`${page.path}: no stills on the page at all`);
}
if (page.demos) problems.push(...(await demosFit(browser, port, page.path)));
const forgiven = built ? IGNORABLE : [...IGNORABLE, ...DEV_CHURN];
for (const line of noise) {
if (!forgiven.some((pattern) => pattern.test(line))) problems.push(`${page.path}: ${line}`);
}
await context.close();
}
} finally {
await browser.close();
}
return problems;
}
// === Run ===
// Resolved against `web/`, not against this file. The script lives in `scripts/`, which has no
// `node_modules` of its own, so a bare specifier here looks in the wrong tree and fails with a
// message about Playwright being missing while it sits installed one directory over.
const { chromium, firefox, webkit } = await (async () => {
try {
const require = createRequire(new URL("../web/package.json", import.meta.url));
const loaded = await import(pathToFileURL(require.resolve("playwright")).href);
// Playwright's entry is CommonJS, and importing one by path puts its exports on `default`
// rather than lifting them — so the named bindings come back undefined and every engine fails
// to launch for a reason that reads like a browser problem.
return loaded.chromium ? loaded : loaded.default;
} catch (error) {
console.error(`playwright is not available: ${error}`);
console.error("run `npm install` in web/, then `npx playwright install`");
process.exit(2);
}
})();
let shared = built ? await serveBuilt(join(web, "dist")) : null;
let current = shared;
process.on("exit", () => shutdown(current));
console.log(`checking the ${built ? "built site" : "dev server"}\n`);
let failed = false;
let port = 4399;
for (const [name, engine] of [
["chromium", chromium],
["firefox", firefox],
["webkit", webkit],
]) {
// A fresh server per engine in dev mode, each on its own port so a lingering listener from the
// previous one cannot be mistaken for this one.
if (!built) {
shutdown(current);
current = await serveDev((port += 1));
if (!(await waitForServer(current.port))) {
console.log(`✗ ${name.padEnd(9)} the dev server never answered`);
failed = true;
continue;
}
}
let problems;
try {
problems = await checkEngine(engine, name, current.port);
} catch (error) {
const missing = /missing dependencies|Executable doesn't exist/i.test(String(error));
if (missing && !required.includes(name)) {
console.log(` ${name.padEnd(9)} skipped — not installed on this host`);
continue;
}
console.log(`✗ ${name.padEnd(9)} could not launch: ${String(error).split("\n")[0]}`);
failed = true;
continue;
}
if (problems.length === 0) {
console.log(`✓ ${name.padEnd(9)} every demo started, no errors`);
} else {
failed = true;
console.log(`✗ ${name}`);
for (const problem of problems.slice(0, 8)) console.log(` ${problem}`);
}
}
shutdown(current);
if (failed) {
console.error("\na browser disagreed with the others — see above.");
process.exit(1);
}
console.log("\nevery engine agrees.");

638
scripts/site-drive.py Executable file
View File

@@ -0,0 +1,638 @@
#!/usr/bin/env python3
"""Drive a real Luxe session from a script, and record what the terminal saw.
Run *inside* a terminal, with the app under a pseudo-terminal this process owns:
ghostty -e scripts/site-drive.py --script demo.rec --out raw.cast -- luxe
Two rules shaped it.
**Keystrokes go into the pty, never to the compositor.** The obvious way to drive a TUI on a
desktop is to synthesize key events with `wtype`, and it works until focus moves — after which
every remaining keystroke, `Ctrl+C` included, is typed into whatever window took it. Writing to the
pty cannot reach another window at all, and it does not need the recording to hold focus.
**The relay is transparent both ways.** Luxe asks the terminal what it can do — cursor position,
device attributes, the glyph probe — and a driver that answers none of those hangs on the first
question. So the app's output goes to our stdout (the real terminal, which answers) and the real
terminal's replies go back into the pty. Only the outbound half is recorded; the terminal's answers
are not something a viewer ever saw.
The output is asciicast v2, which `scripts/cast-edit.py` then cuts down to a demo.
Steps, one per line, `#` comments allowed:
sleep <seconds> wait
type <text> type literal text at a readable cadence
enter [text] type text (optionally none) then Return
key <name>[ xN] press a named key N times (Return, Escape, Down, PageUp, F5, …)
mod <mods> <name> a chord: mods among ctrl/alt/shift joined by `+`
send <escaped> raw bytes, Python escapes (`\\x1b[27;5u`) — the escape hatch
settle <secs> [max N] wait until the app has drawn nothing for <secs>
expect <text> [max N] wait until <text> appears in what the app has drawn
answer <key> [hold N] when <text>
from now on, press <key> (or chord, `ctrl+g`) whenever <text> appears
mark <name> record a timestamp; `start` and `end` bound the finished cast
log <text> a note in the driver log
`expect` and `answer` match against the *screen*, reconstructed with `pyte`, not against the byte
stream. Ratatui writes only the cells that changed and moves the cursor between them, so a phrase
that is plainly on screen — `review ready · Ctrl+G opens it` — is essentially never contiguous in
what the terminal received. Whitespace is collapsed before matching, so a needle does not have to
know how a surface pads its columns.
Prefer `settle` over `sleep` for anything that waits on a model. A turn is finished when the
screen stops changing, and a fixed sleep cannot tell that apart from a session that is never going
to answer — which is how a take ends up as a recording of a hung terminal nobody was watching.
Two things `settle` cannot see, both worth knowing before writing a script:
- **An animation is not stillness.** The startup wordmark and the working indicator redraw
continuously, so a `settle` across either spends its whole budget. Use `sleep` on the dashboard
and `expect` for anything with a spinner in front of it.
- **A modal is stillness.** A permission prompt waiting for a person looks exactly like a finished
turn, except that the turn behind it never ends. `answer` exists for that: it presses the key
every time the prompt appears, so a take cannot stall on a dialog nobody is there to dismiss.
"""
from __future__ import annotations
import argparse
import codecs
import errno
import fcntl
import json
import os
import pathlib
import pty
import random
import re
import select
import pyte
import signal
import struct
import sys
import termios
import threading
import time
import tty
# Typing, at reading speed rather than at typing speed. A prompt entered at 40ms a character
# replays faster than anyone can read a sentence they are meeting for the first time, which is the
# commonest reason a terminal recording is unwatchable. With the jitter and pauses below this
# averages about 60ms a character; it was 80, which read as someone typing carefully rather than
# as someone who knows what they want.
CADENCE = 0.046
PUNCTUATION_BEAT = 0.15
PUNCTUATION = ",.;:?!"
# Nobody types on a metronome, and a perfectly even cadence is the tell that gives a scripted demo
# away — it reads as output being printed rather than as somebody at a keyboard. So each keystroke
# is scaled by a factor in this range, and now and then the typist stops to think.
JITTER = (0.6, 1.6)
HESITATION_ODDS = 0.025
HESITATION = (0.2, 0.55)
# Fingers are faster inside a word than across one.
SPACE_DRAG = 1.45
# === Keys ===
# Named keys the legacy encoding can express on their own.
LEGACY = {
"return": "\r",
"enter": "\r",
"escape": "\x1b",
"esc": "\x1b",
"tab": "\t",
"backspace": "\x7f",
"space": " ",
"up": "\x1b[A",
"down": "\x1b[B",
"right": "\x1b[C",
"left": "\x1b[D",
"home": "\x1b[H",
"end": "\x1b[F",
"pageup": "\x1b[5~",
"pagedown": "\x1b[6~",
"delete": "\x1b[3~",
"insert": "\x1b[2~",
**{f"f{n}": f"\x1b[{10 + n}~" for n in range(5, 13)},
**dict(zip(("f1", "f2", "f3", "f4"), ("\x1bOP", "\x1bOQ", "\x1bOR", "\x1bOS"))),
}
# The same keys as Unicode codepoints, for the CSI-u form. Luxe negotiates the Kitty keyboard
# protocol, so a chord the legacy encoding cannot spell — `Ctrl+Esc`, which is how a turn is
# interrupted — has a representation here rather than being unreachable.
CSI_U_CODE = {
"return": 13,
"enter": 13,
"escape": 27,
"esc": 27,
"tab": 9,
"backspace": 127,
"space": 32,
}
CSI_U_TILDE = {"up": "A", "down": "B", "right": "C", "left": "D", "home": "H", "end": "F"}
MODIFIER_BIT = {"shift": 1, "alt": 2, "ctrl": 4}
def chord(mods: list[str], name: str) -> str:
"""Encodes a modified key press.
Prefers the legacy encoding, because every terminal and every parser understands it, and falls
back to CSI-u only where legacy has no spelling for the combination.
"""
name = name.lower()
bits = 0
for mod in mods:
if mod not in MODIFIER_BIT:
sys.exit(f"unknown modifier {mod!r}")
bits |= MODIFIER_BIT[mod]
# Ctrl with a plain letter is a control character, which is what a terminal has always sent.
if bits == MODIFIER_BIT["ctrl"] and len(name) == 1 and name.isalpha():
return chr(ord(name.upper()) & 0x1F)
if bits == MODIFIER_BIT["alt"] and len(name) == 1:
return "\x1b" + name
if bits == (MODIFIER_BIT["alt"] | MODIFIER_BIT["ctrl"]) and len(name) == 1 and name.isalpha():
return "\x1b" + chr(ord(name.upper()) & 0x1F)
parameter = bits + 1
if name in CSI_U_TILDE:
return f"\x1b[1;{parameter}{CSI_U_TILDE[name]}"
code = CSI_U_CODE.get(name) or (ord(name) if len(name) == 1 else None)
if code is None:
sys.exit(f"no encoding for {'+'.join(mods)}+{name}")
return f"\x1b[{code};{parameter}u"
def named(name: str) -> str:
"""Encodes an unmodified key press."""
key = LEGACY.get(name.lower())
if key is None:
sys.exit(f"unknown key {name!r}")
return key
def press(token: str) -> str:
"""Encodes one key from a script token: `Down`, `ctrl+g`, or a bare character."""
if "+" in token:
*mods, name = token.split("+")
return chord(mods, name)
return named(token) if len(token) > 1 else token
# === What may come back in ===
# CSI sequences that are answers to a question the app asked. Everything else arriving from the
# outer terminal is a person, and a person is not part of the take.
REPLY_FINALS = frozenset("Rcnut")
# Everything that is not a printable cell, for `expect`.
ESCAPES = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b[P\]_^].*?(?:\x1b\\|\x07)|\x1b[=>()][A-Za-z0-9]?", re.S)
def device_replies(buffer: str) -> tuple[str, str]:
"""Splits inbound bytes into the device reports worth forwarding and an unparsed remainder.
The app's own escape sequences reach the real terminal through our stdout, so the terminal
duly turns on mouse tracking and focus reporting and starts reporting *the operator* back at
us. Relayed, that lands a stray pointer move in the middle of a take — which is how two
recordings came out as a corrupted screen when a mouse crossed the window.
So the inbound half carries exactly what it exists for: cursor position reports, device
attributes, the keyboard-protocol flags, and the string replies (DCS/OSC/APC). Keystrokes,
mouse events and focus changes are dropped.
"""
out: list[str] = []
i = 0
while i < len(buffer):
if buffer[i] != "\x1b":
i += 1 # a bare keystroke
continue
rest = buffer[i:]
if len(rest) < 2:
return "".join(out), rest # an ESC that may yet become a sequence
kind = rest[1]
if kind == "[":
match = re.match(r"\x1b\[[\x30-\x3f]*[\x20-\x2f]*([\x40-\x7e])", rest)
if not match:
return "".join(out), rest
if match.group(1) in REPLY_FINALS and not rest.startswith("\x1b[<"):
out.append(match.group(0))
i += match.end()
continue
if kind in "P]_^":
match = re.match(r"\x1b[P\]_^].*?(?:\x1b\\|\x07)", rest, re.S)
if not match:
return "".join(out), rest
out.append(match.group(0))
i += match.end()
continue
i += 2 # ESC-something we did not ask for
return "".join(out), ""
# === The session ===
class Session:
"""A pty running the app, a recording of what it drew, and a way to type at it."""
def __init__(
self,
command: list[str],
cols: int,
rows: int,
cwd: str,
env: dict[str, str],
seed: int = 0,
):
# Seeded, so the unevenness is a property of the take rather than of the run. Re-recording
# a demo after a visual change should differ in what the model said, not in how the prompt
# was typed.
self.random = random.Random(seed)
self.events: list[tuple[float, str]] = []
self.marks: dict[str, float] = {}
self.cols, self.rows = cols, rows
self.started = time.time()
self.alive = True
self.last_output = time.time()
self._lock = threading.Lock()
# A model of what is actually on screen. Cheap enough to keep current — 200k characters of
# redraw costs about a tenth of a second — and the only thing a script can reliably wait
# on, because the byte stream carries cell updates rather than sentences.
self._screen = pyte.Screen(cols, rows)
self._stream = pyte.Stream(self._screen)
# Incremental, and that matters. A read returns whatever bytes happened to be available, so
# a multi-byte character — every box-drawing rule and every Nerd Font glyph Luxe draws — can
# be split across two of them. Decoding each read on its own turns both halves into U+FFFD,
# which is how stray `<60>` diamonds ended up scattered through otherwise good takes. This
# holds the incomplete tail until the rest of it arrives.
self._decoder = codecs.getincrementaldecoder("utf8")("replace")
self.pid, self.fd = pty.fork()
if self.pid == 0:
os.chdir(cwd)
os.execvpe(command[0], command, env)
# The app is told the size we want the recording to be, not the size of the window this is
# running in. That is the whole reason the driver owns the pty: a demo's column count is
# its type size on the page, and it cannot be left to whatever the compositor handed the
# terminal.
fcntl.ioctl(self.fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
def relay(self) -> None:
"""Pumps both directions until the app exits. Runs on the main thread.
Our own stdin has to be raw for the duration. The app's questions to the terminal come back
as ordinary input, and a cooked line discipline holds them until a newline that a cursor
position report never contains — so the app asks, the answer sits in a buffer, and the
launch dies on `the cursor position could not be read`.
"""
stdin = sys.stdin.fileno()
try:
saved = termios.tcgetattr(stdin)
tty.setraw(stdin)
except termios.error: # not a terminal — nothing to answer with, and nothing to restore
saved = None
pending = ""
while self.alive:
try:
readable, _, _ = select.select([self.fd, stdin], [], [], 0.05)
except (OSError, select.error):
break
if self.fd in readable:
try:
data = os.read(self.fd, 65536)
except OSError as error:
if error.errno == errno.EIO: # the app closed its end
break
raise
if not data:
break
text = self._decoder.decode(data)
if not text:
continue
with self._lock:
self.events.append((time.time() - self.started, text))
self.last_output = time.time()
self._stream.feed(text)
sys.stdout.write(text)
sys.stdout.flush()
# The terminal's answers to the app's questions. Relayed, never recorded: nobody
# watching the demo ever saw them.
if stdin in readable:
try:
inbound = os.read(stdin, 4096)
except OSError:
inbound = b""
if inbound:
pending += inbound.decode("utf8", "replace")
replies, pending = device_replies(pending)
if replies:
os.write(self.fd, replies.encode("utf8"))
self.alive = False
if saved is not None:
termios.tcsetattr(stdin, termios.TCSADRAIN, saved)
def send(self, text: str) -> None:
if self.alive:
try:
os.write(self.fd, text.encode("utf8"))
except OSError:
self.alive = False
def type_text(self, text: str) -> None:
for char in text:
self.send(char)
delay = CADENCE * self.random.uniform(*JITTER)
if char == " ":
delay *= SPACE_DRAG
time.sleep(delay)
if char in PUNCTUATION:
time.sleep(PUNCTUATION_BEAT * self.random.uniform(*JITTER))
elif self.random.random() < HESITATION_ODDS:
time.sleep(self.random.uniform(*HESITATION))
def mark(self, name: str) -> None:
self.marks[name] = time.time() - self.started
def screen_text(self) -> str:
"""What is on screen now, with runs of whitespace collapsed."""
with self._lock:
lines = self._screen.display
return re.sub(r"\s+", " ", " ".join(lines))
def on_screen(self, needle: str) -> bool:
return re.sub(r"\s+", " ", needle.strip()) in self.screen_text()
def settle(self, quiet: float, limit: float) -> bool:
"""Waits until the app has drawn nothing for `quiet` seconds. False if `limit` ran out."""
deadline = time.time() + limit
while time.time() < deadline:
if not self.alive:
return True
if time.time() - self.last_output >= quiet:
return True
time.sleep(0.1)
return False
def expect(self, needle: str, limit: float) -> bool:
"""Waits until `needle` is drawn. False if `limit` ran out.
Matched against the text with the escape sequences taken out, because on screen a phrase is
rarely one run: `review ready · Ctrl+G opens it` reaches the terminal as several styled
pieces with SGR codes between them, so a raw search for it never matches.
"""
deadline = time.time() + limit
while time.time() < deadline:
if not self.alive:
return False
if self.on_screen(needle):
return True
time.sleep(0.1)
return False
def autoanswer(self, needle: str, key: str, hold: float) -> None:
"""Presses `key` whenever `needle` appears, for the rest of the take.
The hold is so a viewer reads the prompt before it is answered — a dialog that vanishes the
instant it appears reads as a glitch rather than as a decision.
"""
def watch() -> None:
armed = not self.on_screen(needle)
while self.alive:
showing = self.on_screen(needle)
if showing and armed:
armed = False
time.sleep(hold)
self.send(press(key))
note(f" answered {needle!r} with {key!r}")
elif not showing:
# Re-arm only once it has gone, or a prompt still on screen while the app
# processes the keystroke gets answered a second time.
armed = True
time.sleep(0.2)
threading.Thread(target=watch, daemon=True).start()
def stop(self, grace: float) -> None:
"""Ends the app, politely and then not."""
deadline = time.time() + grace
while time.time() < deadline:
if os.waitpid(self.pid, os.WNOHANG) != (0, 0):
self.alive = False
return
time.sleep(0.1)
for sig in (signal.SIGTERM, signal.SIGKILL):
try:
os.kill(self.pid, sig)
except ProcessLookupError:
break
time.sleep(0.5)
self.alive = False
def write(self, cast: pathlib.Path, marks: pathlib.Path, title: str) -> None:
with self._lock, cast.open("w", encoding="utf8") as handle:
handle.write(
json.dumps(
{
"version": 2,
"width": self.cols,
"height": self.rows,
"title": title,
"env": {"TERM": "xterm-256color"},
}
)
+ "\n"
)
for at, text in self.events:
handle.write(json.dumps([round(at, 6), "o", text]) + "\n")
marks.write_text("".join(f"{n}\t{t:.3f}\n" for n, t in self.marks.items()), encoding="utf8")
# === The script ===
STEP = re.compile(r"^(\w+)(?:\s+(.*))?$")
# Where progress goes. Not stderr: stderr is the recording terminal, so a note written there lands
# in the middle of the shot — and when a take goes wrong the window is usually already gone, which
# is the exact moment the notes are worth having.
LOG: object | None = None
def note(message: str) -> None:
if LOG is not None:
print(message, file=LOG, flush=True)
def run_script(session: Session, steps: list[str]) -> None:
"""Plays the step list against the session. Runs on its own thread.
Anything raised here would otherwise vanish: this is not the main thread, so an exception ends
the script and leaves the relay recording a screen nobody is driving any more. The take still
gets written, which is worse than failing — it looks like a demo that stopped early rather than
a script with a bad step in it.
"""
try:
play(session, steps)
except BaseException as error: # noqa: BLE001 - the alternative is losing it entirely
note(f"!! step failed: {error!r}")
def play(session: Session, steps: list[str]) -> None:
for raw in steps:
line = raw.rstrip("\r\n")
if not line.strip() or line.lstrip().startswith("#"):
continue
match = STEP.match(line.strip())
if not match:
sys.exit(f"cannot parse step: {line!r}")
verb, rest = match.group(1), (match.group(2) or "")
if not session.alive:
note(f"!! app exited before step: {line!r}")
return
note(f"[{time.time() - session.started:7.1f}s] {line.strip()}")
if verb == "sleep":
time.sleep(float(rest))
elif verb == "log":
note(f"-- {rest}")
elif verb == "settle":
words = rest.split()
quiet = float(words[0]) if words else 3.0
limit = float(words[2]) if len(words) > 2 and words[1] == "max" else 300.0
if not session.settle(quiet, limit):
note(f"!! never settled within {limit}s — carrying on")
elif verb == "expect":
words = rest.rsplit(" max ", 1)
limit = float(words[1]) if len(words) > 1 else 300.0
if not session.expect(words[0], limit):
note(f"!! never saw {words[0]!r} within {limit}s — carrying on")
elif verb == "answer":
# Key first and the text last, after a `when`. The text is the part with spaces in it,
# so any other order needs the parser to guess where it ends — and a guess that came
# out wrong watched for "Allow" and tried to press a key named "once", which failed
# silently on a background thread and let a take stall on the very prompt it was
# supposed to dismiss.
match = re.match(r"^(\S+)(?:\s+hold\s+([\d.]+))?\s+when\s+(.+)$", rest)
if not match:
sys.exit(f"answer wants `<key> [hold N] when <text>`, got: {rest!r}")
key, hold, needle = match.group(1), match.group(2), match.group(3)
session.autoanswer(needle.strip(), key, float(hold) if hold else 2.5)
elif verb == "mark":
session.mark(rest.strip())
elif verb == "type":
session.type_text(rest)
elif verb == "enter":
if rest:
session.type_text(rest)
time.sleep(0.2)
session.send("\r")
elif verb == "send":
session.send(rest.encode("utf8").decode("unicode_escape"))
elif verb == "key":
parts = rest.split()
count = int(parts[1][1:]) if len(parts) > 1 and parts[1].startswith("x") else 1
for _ in range(count):
# `press`, not `named`: a step is as likely to want a letter the surface binds
# (`c` to comment, `a` to ask) as a named key, and `named` has no entry for one —
# it exited the script thread mid-take, silently, because that thread is where the
# exit was raised.
session.send(press(parts[0]))
time.sleep(0.12)
elif verb == "mod":
parts = rest.split()
session.send(chord(parts[0].split("+"), parts[1]))
time.sleep(0.12)
else:
sys.exit(f"unknown step {verb!r}")
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--script", type=pathlib.Path, required=True)
parser.add_argument("--out", type=pathlib.Path, required=True)
parser.add_argument("--marks", type=pathlib.Path, required=True)
parser.add_argument("--log", type=pathlib.Path)
parser.add_argument("--seed", type=int, default=0)
parser.add_argument("--cols", type=int, default=92)
parser.add_argument("--rows", type=int, default=28)
parser.add_argument("--cwd", default=os.getcwd())
parser.add_argument("--title", default="luxe")
parser.add_argument(
"--quit",
default="",
help="keys sent to end the take, `|`-separated (default: none — the app is signalled)",
)
parser.add_argument("command", nargs=argparse.REMAINDER)
args = parser.parse_args()
command = [c for c in args.command if c != "--"]
if not command:
sys.exit("nothing to run: pass the command after --")
global LOG
if args.log:
LOG = args.log.open("w", encoding="utf8")
steps = args.script.read_text(encoding="utf8").splitlines()
session = Session(command, args.cols, args.rows, args.cwd, dict(os.environ), args.seed)
# A take is usually abandoned by closing the window, which is a signal rather than a return —
# and a recording that is only written on the happy path is one that never survives the run you
# most wanted to look at.
def rescue(*_: object) -> None:
session.alive = False
note("!! interrupted — saving what was captured")
session.write(args.out, args.marks, args.title)
os._exit(1)
for sig in (signal.SIGTERM, signal.SIGHUP, signal.SIGINT):
signal.signal(sig, rescue)
driver = threading.Thread(target=run_script, args=(session, steps), daemon=True)
driver.start()
# The relay owns the main thread; the script thread only writes. When the script finishes, the
# app is asked to leave and then made to.
def finish() -> None:
driver.join()
time.sleep(0.4)
if "end" not in session.marks:
session.mark("end")
# Nothing is typed to leave. A quit key is a key like any other, so it lands in whatever
# has focus — `q` in the composer, on screen, in the last seconds of the take. The cast is
# already cut at the `end` mark, so the tidy exit buys nothing and costs a visible
# keystroke.
for key in filter(None, args.quit.split("|")):
session.send(key.encode("utf8").decode("unicode_escape"))
time.sleep(0.6)
# Then made to. Everything worth keeping is already recorded and the cast is cut at the
# `end` mark, so a take that will not leave politely costs nothing by being ended.
session.stop(grace=4.0)
threading.Thread(target=finish, daemon=True).start()
try:
session.relay()
except KeyboardInterrupt:
pass
finally:
session.alive = False
try:
os.kill(session.pid, signal.SIGTERM)
except ProcessLookupError:
pass
session.write(args.out, args.marks, args.title)
note(f"recorded {len(session.events)} frames to {args.out}")
if __name__ == "__main__":
main()

270
scripts/site-fonts.sh Executable file
View File

@@ -0,0 +1,270 @@
#!/usr/bin/env bash
# Build the website's webfonts, subset to what the site actually draws.
#
# Three families: Instrument Serif for display, JetBrains Mono for everything a terminal would set,
# and a sliver of Adwaita Mono for the handful of marks JetBrains Mono does not draw. All three are
# SIL Open Font License 1.1, and none declares a Reserved Font Name — checked, because a
# subset is a "Modified Version" under the OFL and an RFN would forbid keeping the name. The license
# requires the copyright notice and license text to travel with the files, which `web/public/fonts/
# LICENSES.md` does.
#
# Why subset at all: the terminal face is a Nerd Font, and the unsubset file is several MB. The site
# draws a couple of hundred distinct characters, a dozen of them private-use icons. Shipping the
# other several thousand would be most of the page weight, for glyphs no visitor will ever see.
#
# The codepoint list is derived from the generated assets rather than guessed — run
# `scripts/site-assets.sh` first, since this reads its output.
#
# That derivation is also the failure mode: the assets are regenerated far more often than the
# fonts, and a character that appears in a new capture without a rebuild here renders as tofu with
# its own codepoint printed inside it. It happened — thirty-one glyphs, every Nerd Font icon and
# both Powerline caps among them, for nine days. So the build records what it covered in
# `coverage.txt` and `--check` holds the assets to it, which is a diff rather than a font parse and
# therefore cheap enough for CI to run on every push.
#
# `coverage.txt` is read back out of the *built* files, not from the list that was requested.
# `pyftsubset` silently drops a codepoint the source font does not have, so a manifest of the
# request would assert coverage the font does not deliver — which is the bug, restated. Anything
# neither face has is listed with its reason in `fallback-ok.txt` and left to the reader's own font,
# on the web through the CSS stack and in a terminal through fontconfig.
#
# **Why two mono faces.** JetBrains Mono is the one people already run, so it is what the site and
# every capture are set in. It lacks six marks Luxe draws (`ℹ ↳ ↺ ⏸ ✔ ✖`), and a missing glyph on
# the web is whatever the reader's system substitutes, at whatever width. Adwaita Mono has all six
# on the same 0.6em cell, so those codepoints, and only those, come from it; the CSS stack names it
# second and the browser falls through per glyph.
#
# Requires: fonttools + brotli (`pip install fonttools brotli`), plus JetBrains Mono and Adwaita
# Mono Nerd Font Mono installed (or `JETBRAINS_DIR` / `ADWAITA_DIR`). `--check` needs none of it —
# bash and python3 only.
#
# Usage: scripts/site-fonts.sh [--check]
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
out_dir="${repo_root}/web/public/fonts"
assets_dir="${repo_root}/web/src/assets/generated"
# Recordings draw glyphs too, and they are not derived from the Rust source — so a capture that
# catches an icon no fixture ever drew would ship it as tofu, silently, to every reader without the
# face installed. Both directories feed the subset.
captures_dir="${repo_root}/web/src/assets/captures"
# The guide's screenshots are drawn on the site too, and so is the guide's own text, which names
# the symbols Luxe draws: set in a face that lacks them, a browser reaches for color emoji.
guide_images_dir="${repo_root}/docs/guide/images"
guide_dir="${repo_root}/docs/guide"
coverage_file="${out_dir}/coverage.txt"
fallback_file="${out_dir}/fallback-ok.txt"
work_dir="$(mktemp -d)"
trap 'rm -rf "${work_dir}"' EXIT
check=false
case "${1:-}" in
--check) check=true ;;
-h | --help)
sed -n '2,39p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
exit 0
;;
'') ;;
*)
echo "unknown argument: $1" >&2
exit 2
;;
esac
# What the generated assets actually draw, read out of them. One definition, used by the build and
# by the check, or the two can disagree about what coverage means.
asset_codepoints() {
python3 - "${assets_dir}" "${captures_dir}" "${guide_images_dir}" "${guide_dir}" <<'PY'
import glob, json, re, sys
used = set()
for directory in sys.argv[1:]:
for path in glob.glob(f"{directory}/*.svg"):
body = re.sub(r"<[^>]+>", "", open(path, encoding="utf-8").read())
used.update(body.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&"))
for path in glob.glob(f"{directory}/*.md"):
used.update(open(path, encoding="utf-8").read())
for path in glob.glob(f"{directory}/*.cast"):
for line in open(path, encoding="utf-8"):
try:
event = json.loads(line)
except ValueError:
continue
if isinstance(event, list) and len(event) == 3:
used.update(event[2])
# Control bytes are escape sequences, and variation selectors pick a presentation; neither is drawn.
glyphs = sorted(
c for c in used if ord(c) >= 0x20 and ord(c) != 0x7F and not 0xFE00 <= ord(c) <= 0xFE0F
)
print(",".join(f"U+{ord(c):04X}" for c in glyphs))
PY
}
if [[ "${check}" == true ]]; then
[[ -f "${coverage_file}" ]] || {
echo "no ${coverage_file} — run scripts/site-fonts.sh" >&2
exit 1
}
missing="$(
comm -23 \
<(asset_codepoints | tr ',' '\n' | sort -u) \
<(cat "${coverage_file}" "${fallback_file}" |
sed 's/#.*//' | tr -d '[:blank:]' | grep . | sort -u)
)"
if [[ -n "${missing}" ]]; then
echo "the webfonts do not cover what the assets draw:" >&2
echo "${missing}" | tr '\n' ' ' >&2
echo >&2
echo "each of these renders as tofu — run scripts/site-fonts.sh and commit the result" >&2
exit 1
fi
echo "webfonts cover every character the assets draw"
exit 0
fi
command -v pyftsubset >/dev/null || {
echo "pyftsubset not found — pip install fonttools brotli" >&2
exit 1
}
# Every style has to come from one directory, and the file names are the upstream ones, so a release
# unpacked anywhere works with the directory variable pointed at it.
find_face() {
local override="$1" file="$2" candidate
shift 2
if [[ -n "${override}" ]]; then
[[ -f "${override}/${file}" ]] && echo "${override}"
return 0
fi
for candidate in "$@"; do
[[ -f "${candidate}/${file}" ]] && echo "${candidate}" && return 0
done
return 0
}
font_dirs=("${HOME}/.local/share/fonts" /usr/share/fonts/TTF /usr/share/fonts/truetype "${HOME}/Library/Fonts")
jetbrains_dir="$(find_face "${JETBRAINS_DIR:-}" JetBrainsMonoNerdFontMono-Regular.ttf \
"${HOME}/.local/share/fonts/JetBrainsMonoNFM" "${font_dirs[@]}")"
[[ -n "${jetbrains_dir}" ]] || {
echo "JetBrains Mono Nerd Font Mono not found (set JETBRAINS_DIR to the directory holding" >&2
echo "JetBrainsMonoNerdFontMono-*.ttf — https://github.com/ryanoasis/nerd-fonts/releases)" >&2
exit 1
}
adwaita_dir="$(find_face "${ADWAITA_DIR:-}" AdwaitaMonoNerdFontMono-Regular.ttf "${font_dirs[@]}")"
[[ -n "${adwaita_dir}" ]] || {
echo "Adwaita Mono Nerd Font Mono not found (set ADWAITA_DIR to the directory holding" >&2
echo "AdwaitaMonoNerdFontMono-*.ttf — https://github.com/ryanoasis/nerd-fonts/releases)" >&2
exit 1
}
# The woff2 encoder needs brotli, so ask the encoder — not the ambient `python3`. `pyftsubset` is
# commonly installed into its own virtualenv (pipx, `uv tool`), where importing brotli here proves
# nothing and refuses a setup that works.
pyftsubset "${jetbrains_dir}/JetBrainsMonoNerdFontMono-Regular.ttf" \
--output-file="${work_dir}/probe.woff2" \
--flavor=woff2 --unicodes='U+0041' 2>/dev/null
[[ -s "${work_dir}/probe.woff2" ]] || {
echo "pyftsubset cannot write woff2 — its interpreter needs brotli (pip install brotli)" >&2
exit 1
}
mkdir -p "${out_dir}"
codepoints="$(asset_codepoints)"
[[ -n "${codepoints}" ]] || {
echo "no codepoints found — run scripts/site-assets.sh first" >&2
exit 1
}
subset() {
local src="$1" dst="$2" unicodes="$3"
pyftsubset "${src}" \
--output-file="${dst}" \
--flavor=woff2 \
--unicodes="${unicodes}" \
--layout-features= \
--no-hinting \
--desubroutinize \
--name-IDs='0,1,2,3,4,5,6,13,14' \
--notdef-outline 2>/dev/null
printf ' %-34s %6s\n' "$(basename "${dst}")" "$(stat -c%s "${dst}")"
}
# The terminal face. Regular and Bold are what Luxe's cells ask for; Italic is there because reasoning
# and a few labels are set in it, and a synthesized slant of an upright mono reads as a rendering bug.
pyftsubset_python="$(head -1 "$(command -v pyftsubset)" | sed 's/^#!//')"
cmap() {
${pyftsubset_python} - "$1" <<'PY'
import sys
from fontTools.ttLib import TTFont
for codepoint in sorted(TTFont(sys.argv[1]).getBestCmap()):
print(f"U+{codepoint:04X}")
PY
}
echo "terminal face — JetBrains Mono Nerd Font Mono, the assets' own characters plus printable ASCII:"
for style in Regular Bold Italic; do
subset "${jetbrains_dir}/JetBrainsMonoNerdFontMono-${style}.ttf" \
"${out_dir}/jetbrains-mono-nfm-${style,,}.woff2" \
"${codepoints},U+0020-007E"
done
# What JetBrains Mono could not carry, and nothing else, from Adwaita Mono. Computed from the built
# file rather than listed, so a glyph a future JetBrains release adds drops out of the fallback on
# its own.
requested="$(printf '%s' "${codepoints}" | tr ',' '\n' | sort -u)"
primary="$(cmap "${out_dir}/jetbrains-mono-nfm-regular.woff2" | sort -u)"
gaps="$(comm -23 <(printf '%s\n' "${requested}") <(printf '%s\n' "${primary}") | paste -sd, -)"
rm -f "${out_dir}"/adwaita-mono-nfm-*.woff2
if [[ -n "${gaps}" ]]; then
echo "fallback face — Adwaita Mono Nerd Font Mono, what JetBrains Mono lacks (${gaps}):"
for style in Regular Bold; do
subset "${adwaita_dir}/AdwaitaMonoNerdFontMono-${style}.ttf" \
"${out_dir}/adwaita-mono-nfm-${style,,}.woff2" \
"${gaps}"
done
fi
# Display face: latin plus the punctuation editorial copy actually uses.
latin='U+0020-007E,U+00A0-00FF,U+2010-2015,U+2018-201F,U+2022,U+2026,U+2032-2033,U+20AC,U+2122'
echo "display face — Instrument Serif, latin:"
for style in Regular Italic; do
url="https://github.com/google/fonts/raw/main/ofl/instrumentserif/InstrumentSerif-${style}.ttf"
curl -sSL -o "${work_dir}/${style}.ttf" "${url}"
subset "${work_dir}/${style}.ttf" "${out_dir}/instrument-serif-${style,,}.woff2" "${latin}"
done
curl -sSL -o "${work_dir}/instrument-ofl.txt" \
"https://github.com/google/fonts/raw/main/ofl/instrumentserif/OFL.txt"
cp "${work_dir}/instrument-ofl.txt" "${out_dir}/OFL-InstrumentSerif.txt"
curl -sSL -o "${out_dir}/OFL-JetBrainsMono.txt" \
"https://raw.githubusercontent.com/JetBrains/JetBrainsMono/master/OFL.txt"
curl -sSL -o "${out_dir}/OFL-AdwaitaMono.txt" \
"https://gitlab.gnome.org/GNOME/adwaita-fonts/-/raw/main/LICENSE"
rm -f "${out_dir}/OFL-Lilex.txt" "${out_dir}"/lilex-nf-mono-*.woff2 \
"${out_dir}/OFL-Iosevka.txt" "${out_dir}"/iosevka-term-nfm-*.woff2
# What the built files actually carry, read back out of them — see the header. One codepoint per
# line, so the check is a `comm` between two sorted lists rather than a font parse. Both mono faces
# count: the fallback exists to cover exactly what the first one drops.
{
printf '%s\n' "${primary}"
if [[ -f "${out_dir}/adwaita-mono-nfm-regular.woff2" ]]; then
cmap "${out_dir}/adwaita-mono-nfm-regular.woff2"
fi
} | sort -u >"${coverage_file}"
dropped="$(comm -23 <(printf '%s\n' "${requested}") <(sort -u "${coverage_file}"))"
if [[ -n "${dropped}" ]]; then
echo
echo "in neither mono face, so the reader's own font draws them:"
echo "${dropped}" | tr '\n' ' '
echo
echo "list them in $(basename "${fallback_file}") with a reason, or stop drawing them"
fi
echo
echo "wrote $(find "${out_dir}" -name '*.woff2' | wc -l) fonts, $(du -sh "${out_dir}" | cut -f1) total"

505
scripts/site-record.sh Executable file
View File

@@ -0,0 +1,505 @@
#!/usr/bin/env bash
# Record a demo for the website by driving the real Luxe in a real terminal.
#
# These used to be scripted through the reducer with no terminal involved, which made them exactly
# reproducible and exactly as much work as writing the app twice. This runs the shipped binary
# against a real provider in Ghostty and records what a person would have seen — so a demo is a
# take, and re-shooting it after a visual change is re-running one command rather than editing a
# thousand lines of Rust.
#
# What that costs, stated plainly: a recording is no longer verifiable by CI, so nothing checks
# that it still matches the build. `web/src/assets/captures/manifest.json` records what each take
# was shot against, and re-recording is the only way to refresh one.
#
# Usage:
# scripts/site-record.sh [options] <script-file>
#
# Options:
# --name NAME output basename (default: the script's own)
# --cols N terminal columns (default 92 — see below)
# --rows N terminal rows (default 28)
# --font-size N Ghostty font size (default 13)
# --theme NAME Luxe theme (default luxe)
# --project DIR where to run Luxe (default: a scratch copy of web/demo)
# --project-src DIR the project template to copy
# --project-name N what the scratch copy is called, which is the name every surface shows
# --max-idle SECS cap on a gap between frames after editing (default 1.2)
# --speed N play the finished take N times faster (default 1.0)
# --timeout SECS abandon a take that has not finished (default 900)
# --out DIR where the finished cast lands (default web/src/assets/captures)
# --raw keep the unedited recording beside the finished one
# --keep-project leave the scratch project behind for inspection
# --monitor NAME which output the recording window opens on, when --watch is set
# --watch put the recording window on screen instead of hiding it
# --seed 'CMD' shell run before the first commit, so its result is the project's history
# --setup 'CMD' shell run after it, so its result is an uncommitted change
# --model P/ID which model answers (default: LUXE_RECORD_MODEL, else whatever is remembered)
# --thinking LEVEL reasoning level for the take
# --glyphs STYLE glyph fidelity: auto, nerd, nerd_wide, unicode, ascii
# --bin DIR put DIR first on Luxe's PATH (relative to web/demo-scripts), for stand-ins
#
# Both are how a demo gets a starting state without spending a turn on it: a changes-and-commit
# demo needs a dirty tree, and paying a provider to manufacture one so the demo can then talk about
# it is a minute of recording nobody watches.
#
# Which side of the commit matters. A defect introduced *after* it is a defect `git checkout` can
# undo, and a model asked to fix one will notice — one take ended with "restoring working tree to
# HEAD", which is a correct answer to a question the demo did not mean to ask. `--seed` puts it in
# history instead, where fixing it means editing the code.
#
# 92 columns is the whole mobile strategy. A demo is drawn at a fixed size per character, so the
# column count *is* the type size — and the review surface at 180 columns is three pixels a
# character on a phone, which is the same as not being there. 92 carries a two-pane review and
# still reads at 390px wide.
#
# The keystrokes go into Luxe's pty, never to the compositor. `wtype` was the obvious way to drive
# a TUI and it works right up until focus moves, after which every remaining key — `Ctrl+C`
# included — is typed into whatever window took it. `scripts/site-drive.py` writes to the pty
# instead, which cannot reach another window and does not need the recording to hold focus.
#
# The step language is documented in that script.
#
# A demo declares its own options in `#:` directives at the top of its script, so re-shooting the
# set is one command and the size a demo needs lives with the demo rather than in somebody's shell
# history. A flag on the command line overrides its directive.
#
# #: cols 150
# #: speed 1.6
# #: setup sed -i 's/x/y/' src/filter.js
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
name=""
cols=92
rows=28
font_size=13
theme="luxe"
project=""
project_src="${repo_root}/web/demo"
# The directory name is the project name in the statusline, the dock and the dashboard, so it is
# part of the shot rather than an implementation detail of the scratch copy.
project_name="todo"
max_idle=1.2
speed=1.0
take_timeout=900
out_dir="${repo_root}/web/src/assets/captures"
keep_raw=false
keep_project=false
script_file=""
monitor="${LUXE_RECORD_MONITOR:-}"
watch=false
setup_cmd=""
seed_cmd=""
model="${LUXE_RECORD_MODEL:-}"
thinking="${LUXE_RECORD_THINKING:-}"
glyphs=""
bin_dir=""
usage() { sed -n '2,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
while [[ $# -gt 0 ]]; do
case "$1" in
--name) name="$2" && shift 2 ;;
--cols) cols="$2" && shift 2 ;;
--rows) rows="$2" && shift 2 ;;
--font-size) font_size="$2" && shift 2 ;;
--theme) theme="$2" && shift 2 ;;
--project) project="$2" && shift 2 ;;
--project-src) project_src="$2" && shift 2 ;;
--project-name) project_name="$2" && shift 2 ;;
--max-idle) max_idle="$2" && shift 2 ;;
--speed) speed="$2" && shift 2 ;;
--timeout) take_timeout="$2" && shift 2 ;;
--out) out_dir="$2" && shift 2 ;;
--raw) keep_raw=true && shift ;;
--keep-project) keep_project=true && shift ;;
--monitor) monitor="$2" && shift 2 ;;
--watch) watch=true && shift ;;
--setup) setup_cmd="$2" && shift 2 ;;
--seed) seed_cmd="$2" && shift 2 ;;
--model) model="$2" && shift 2 ;;
--thinking) thinking="$2" && shift 2 ;;
--glyphs) glyphs="$2" && shift 2 ;;
--bin) bin_dir="$2" && shift 2 ;;
-h | --help)
usage
exit 0
;;
-*)
echo "unknown flag: $1" >&2
exit 2
;;
*) script_file="$1" && shift ;;
esac
done
[[ -n "$script_file" ]] || {
usage
exit 2
}
[[ -f "$script_file" ]] || {
echo "no such script: $script_file" >&2
exit 2
}
[[ -n "$name" ]] || name="$(basename "${script_file%.*}")"
# Directives first, so an explicit flag still wins: everything above has already been parsed, so
# only a setting still at its default is taken from the file.
while IFS= read -r directive; do
key="${directive%% *}"
value="${directive#"$key"}"
value="${value# }"
case "$key" in
cols) [[ "$cols" == 92 ]] && cols="$value" ;;
rows) [[ "$rows" == 28 ]] && rows="$value" ;;
speed) [[ "$speed" == 1.0 ]] && speed="$value" ;;
max-idle) [[ "$max_idle" == 1.2 ]] && max_idle="$value" ;;
setup) [[ -z "$setup_cmd" ]] && setup_cmd="$value" ;;
seed) [[ -z "$seed_cmd" ]] && seed_cmd="$value" ;;
model) [[ -z "$model" ]] && model="$value" ;;
thinking) [[ -z "$thinking" ]] && thinking="$value" ;;
glyphs) [[ -z "$glyphs" ]] && glyphs="$value" ;;
bin) [[ -z "$bin_dir" ]] && bin_dir="$value" ;;
project-name) [[ "$project_name" == todo ]] && project_name="$value" ;;
*)
echo "unknown directive in ${script_file}: ${key}" >&2
exit 2
;;
esac
done < <(sed -n 's/^#: *//p' "$script_file")
for tool in ghostty python3 git; do
command -v "$tool" >/dev/null || {
echo "missing required tool: $tool" >&2
exit 2
}
done
luxe_bin="${repo_root}/target/release/luxe"
[[ -x "$luxe_bin" ]] || {
echo "no release binary at ${luxe_bin} — run scripts/install-dev.sh first" >&2
exit 2
}
mkdir -p "$out_dir"
work="$(mktemp -d /tmp/luxe-record-XXXXXX)"
raw_cast="${work}/raw.cast"
marks_file="${work}/marks"
drive_log="${work}/drive.log"
# === The terminal ===
# Ghostty wears the Luxe palette. The app paints nearly every cell itself, but not the ones it has
# not reached yet — and a demo whose first frame is somebody else's background color announces that
# it was staged.
theme_json="${repo_root}/crates/luxe-core/src/themes/${theme}.json"
[[ -f "$theme_json" ]] || {
echo "no such theme: ${theme_json}" >&2
exit 2
}
read -r term_bg term_fg < <(python3 -c "
import json, sys
palette = json.load(open(sys.argv[1]))['vars']
print(palette['bg'], palette['fg'])
" "$theme_json")
ghostty_config="${work}/ghostty.conf"
cat >"$ghostty_config" <<CONF
font-family = JetBrainsMono Nerd Font Mono
font-size = ${font_size}
window-width = ${cols}
window-height = ${rows}
window-padding-x = 0
window-padding-y = 0
window-decoration = none
window-inherit-font-size = false
background = ${term_bg}
foreground = ${term_fg}
confirm-close-surface = false
resize-overlay = never
mouse-hide-while-typing = true
cursor-style-blink = false
shell-integration = none
CONF
# === The project under the demo ===
# A scratch copy, every time. A demo that edits a file has to start from the same file next time,
# and a template that accumulates the last five takes is a template that eventually shows them.
if [[ -z "$project" ]]; then
[[ -d "$project_src" ]] || {
echo "no demo project at ${project_src} — pass --project" >&2
exit 2
}
project="${work}/${project_name}"
cp -r "$project_src" "$project"
if [[ -n "$seed_cmd" ]]; then
(cd "$project" && DEMO_SCRIPTS="${repo_root}/web/demo-scripts" eval "$seed_cmd")
fi
git -C "$project" init --quiet --initial-branch=main
# Configured on the repository, not passed per command. A `git commit` with no identity anywhere
# cannot proceed, so an agent asked to commit correctly stops and asks who it is — which is good
# behavior and a poor demo, and it is the recorder's doing rather than something to talk the
# model out of in the prompt.
git -C "$project" config user.name "Luxe"
git -C "$project" config user.email "demo@luxe.dev"
git -C "$project" add -A
git -C "$project" commit --quiet -m "Initial commit"
fi
# After the commit, so whatever it does shows up as a change rather than as the baseline.
#
# `DEMO_SCRIPTS` because the command runs in the scratch project, which is somewhere under /tmp —
# so a change big enough to live in its own file has no relative path to reach itself by.
if [[ -n "$setup_cmd" ]]; then
(cd "$project" && DEMO_SCRIPTS="${repo_root}/web/demo-scripts" eval "$setup_cmd")
fi
# === Luxe's own config ===
# Copied from the real one so the credentials and the model are the ones being demonstrated, then
# overridden where a demo needs a fixed answer. Never the real directory: a take must not be able
# to write to it, and a theme set for a recording must not outlive it.
config_home="${work}/config"
mkdir -p "${config_home}/luxe"
real_config="${XDG_CONFIG_HOME:-$HOME/.config}/luxe"
if [[ -d "$real_config" ]]; then
# Not `mcp.json`: the operator's servers would sit in the picker's MCP tab of every take, and
# connect to real services on the way.
find "$real_config" -maxdepth 1 -name '*.json' ! -name 'auth.json' ! -name 'mcp.json' \
-exec cp {} "${config_home}/luxe/" \;
# Linked, not copied. An OAuth credential rotates: the provider hands back a new refresh token
# and invalidates the one just used, and Luxe writes it to whichever auth file it was given. A
# copy in a scratch directory therefore takes the rotation with it when the directory is
# deleted, and every later take authenticates with a token the provider has already retired —
# which is a signed-out account after one recording, not a recording problem you notice at the
# time. The real file is the credential store; a take uses it exactly as a normal run would.
[[ -e "${real_config}/auth.json" ]] &&
ln -s "${real_config}/auth.json" "${config_home}/luxe/auth.json"
fi
python3 - "$config_home" "$theme" "$glyphs" <<'PY'
import json, pathlib, sys
home, theme, glyphs = sys.argv[1], sys.argv[2], sys.argv[3]
path = pathlib.Path(home) / "luxe" / "config.json"
config = json.loads(path.read_text()) if path.exists() else {}
config["theme"] = theme
if glyphs:
config["glyphs"] = glyphs
# Straight into a session. The dashboard is a real surface and it has its own demo if it ever wants
# one, but as a preamble it costs every take three seconds of a screen the demo is not about.
config["dashboard"] = False
# A desktop notification landing mid-take is somebody else's window in the shot.
config["notifications"] = False
# The update check is one request that can only make a recording slower or wrong.
config.setdefault("update", {})["check"] = False
path.write_text(json.dumps(config, indent=2))
PY
# A scratch state directory, always. The remembered model outranks `default_model`, and it lives
# outside the config directory — so without this a take silently inherits whichever model the
# operator last picked, which is how a demo meant for a local model got recorded against a frontier
# one. Isolating it also stops a recording from writing back to real state.
state_home="${work}/state"
mkdir -p "${state_home}/luxe"
python3 - "$state_home" "$model" <<'PY'
import json, pathlib, sys
home, model = sys.argv[1], sys.argv[2]
state = {"schema_version": 1}
if model:
provider, _, identifier = model.partition("/")
if not identifier:
sys.exit(f"--model wants provider/id, got {model!r}")
state["model"] = {"provider": provider, "id": identifier}
path = pathlib.Path(home) / "luxe" / "state.json"
path.write_text(json.dumps(state, indent=2))
path.chmod(0o600)
PY
# `--thinking` on the command line, not in the state file. A model's own configured level in
# `models.json` outranks the remembered one, so a level written to state is silently ignored for
# exactly the models that declare a default — which is the set worth overriding.
luxe_args=()
[[ -n "$thinking" ]] && luxe_args+=(--thinking "$thinking")
# A stand-in for a program the demo project has no real counterpart for, like `gh` for a repository
# that doesn't exist. First on PATH, so Luxe and every command the model runs find it.
record_path="$PATH"
if [[ -n "$bin_dir" ]]; then
[[ "$bin_dir" == /* ]] || bin_dir="${repo_root}/web/demo-scripts/${bin_dir}"
[[ -d "$bin_dir" ]] || {
echo "no such bin directory: ${bin_dir}" >&2
exit 2
}
record_path="${bin_dir}:${PATH}"
fi
# === Launch ===
cleanup() {
# `|| true`: by the time this runs the terminal has usually already gone, and under `set -e` a
# failed kill in the exit trap turns a finished recording into a non-zero exit.
if [[ -n "${term_pid:-}" ]]; then
kill "$term_pid" 2>/dev/null || true
fi
if [[ "$keep_project" == true ]]; then
echo "project left at ${project}"
else
rm -rf "$work"
fi
return 0
}
trap cleanup EXIT
# By default the window is hidden on a silent special workspace, and that is the important setting
# rather than a convenience.
#
# A take does not need to be seen: the recording comes from the pty the driver owns, and a hidden
# GTK window still answers the device queries Luxe asks. What an on-screen window *does* do is sit
# in the way — it takes focus, it lands on whichever monitor the pointer last touched, and the
# operator cannot use their machine without wondering whether they just spoiled a minute of
# recording. `silent` keeps the workspace from being switched to.
#
# `--watch` puts it back on screen for the times you need to see what a script is actually doing.
# A class of its own, per run.
#
# `hyprctl keyword windowrulev2` *adds* a rule for the rest of the compositor's session; there is no
# unset. So a run that once asked for `float, size, center, monitor DP-2` leaves those rules behind,
# and every later run of the hidden variant matches them too — the window floats onto whichever
# monitor last had the pointer instead of going quietly to its workspace. A unique class means only
# this run's rules can ever match this run's window.
#
# The segment cannot start with a digit: Ghostty validates the class as a GTK application id and
# silently ignores an invalid one, which puts the window back under the desktop's own class where
# no rule reaches it.
window_class="dev.luxe.record.r$$"
rule() { hyprctl keyword windowrulev2 "$1, class:^(${window_class})\$" >/dev/null 2>&1 || true; }
if [[ "$watch" == true ]]; then
# Ghostty's own `window-width`/`window-height` are in cells and Hyprland overrides them for a
# new float, so the size is asked for again in pixels. The cell is JetBrains Mono's own box, a
# 0.6em advance by a 1.32em line, at the 20px a 13pt face measures on this display.
read -r window_px_w window_px_h < <(python3 -c "
import sys
cols, rows, size = (int(a) for a in sys.argv[1:4])
print(round(cols * 12.02 * size / 13), round(rows * 26.45 * size / 13))
" "$cols" "$rows" "$font_size")
rule "float"
rule "size ${window_px_w} ${window_px_h}"
rule "center"
[[ -n "$monitor" ]] && rule "monitor ${monitor}"
else
rule "workspace special:luxe-record silent"
rule "noanim"
fi
echo "==> recording ${name} (${cols}x${rows}, ${theme})"
XDG_CONFIG_HOME="$config_home" \
XDG_STATE_HOME="$state_home" \
TERM=xterm-256color \
LUXE_UPDATE_CHECK=0 \
LUXE_WIRE_LOG="${work}/wire.jsonl" \
PATH="$record_path" \
ghostty \
--config-default-files=false \
--config-file="$ghostty_config" \
--gtk-single-instance=false \
--class="${window_class}" \
--title="luxe-record-$$" \
-e python3 "${repo_root}/scripts/site-drive.py" \
--script "$script_file" \
--out "$raw_cast" \
--marks "$marks_file" \
--log "$drive_log" \
--cols "$cols" --rows "$rows" \
--cwd "$project" \
--title "luxe — ${name}" \
-- "$luxe_bin" "${luxe_args[@]}" &
term_pid=$!
# A take that never finishes is a script with a step that never lands. Bounded, so a bad script
# costs a wait rather than a window nobody notices is still open.
waited=0
while kill -0 "$term_pid" 2>/dev/null; do
sleep 1
waited=$((waited + 1))
if ((waited > take_timeout)); then
echo "take exceeded ${take_timeout}s — abandoning" >&2
kill "$term_pid" 2>/dev/null || true
break
fi
done
wait "$term_pid" 2>/dev/null || true
# The driver's notes, always — a take that went wrong is exactly the one whose window is gone.
if [[ -f "$drive_log" ]]; then
cp "$drive_log" "${out_dir}/${name}.log"
fi
# And what the take actually said and sent: the session it wrote and every request and reply on
# the wire. A card that went red for no reason the cast can show is answered by these, and the
# scratch project they lived in is about to be deleted. Kept beside the driver's notes, and like
# them never committed (`luxe wire` reads the second).
if [[ -f "${work}/wire.jsonl" ]]; then
cp "${work}/wire.jsonl" "${out_dir}/${name}.wire.jsonl"
fi
session_file="$(ls -t "${project}"/.luxe/sessions/*/*.jsonl 2>/dev/null | head -1 || true)"
if [[ -n "$session_file" ]]; then
cp "$session_file" "${out_dir}/${name}.session.jsonl"
fi
[[ -s "$raw_cast" ]] || {
echo "nothing was recorded — see ${out_dir}/${name}.log" >&2
exit 1
}
# === Cut ===
python3 "${repo_root}/scripts/cast-edit.py" "$raw_cast" \
--out "${out_dir}/${name}.cast" \
--marks "$marks_file" \
--max-idle "$max_idle" \
--speed "$speed" \
--title "luxe — ${name}"
[[ "$keep_raw" == true ]] && cp "$raw_cast" "${out_dir}/${name}.raw.cast"
python3 - "$out_dir" "$name" "$cols" "$rows" "$theme" "$script_file" "$repo_root" <<'PY'
import datetime, json, pathlib, subprocess, sys
out_dir, name, cols, rows, theme, script, root = sys.argv[1:8]
path = pathlib.Path(out_dir) / "manifest.json"
manifest = json.loads(path.read_text()) if path.exists() else {}
def relative(target: str) -> str:
"""Names the script inside the repository, or absolutely for a one-off from elsewhere."""
try:
return str(pathlib.Path(target).resolve().relative_to(pathlib.Path(root).resolve()))
except ValueError:
return str(pathlib.Path(target).resolve())
def git(*args: str) -> str:
try:
done = subprocess.run(["git", "-C", root, *args], capture_output=True, text=True, check=True)
return done.stdout.strip()
except (subprocess.CalledProcessError, OSError):
return "unknown"
manifest[name] = {
"recorded": datetime.datetime.now().astimezone().strftime("%Y-%m-%d"),
"commit": git("rev-parse", "--short", "HEAD"),
"dirty": bool(git("status", "--porcelain")),
"cols": int(cols),
"rows": int(rows),
"theme": theme,
"script": relative(script),
}
path.write_text(json.dumps(dict(sorted(manifest.items())), indent=2) + "\n")
PY
echo "==> ${out_dir}/${name}.cast"

606
scripts/site-smoke.mjs Normal file
View File

@@ -0,0 +1,606 @@
#!/usr/bin/env node
/**
* site-smoke — load the built site in a real browser and fail on anything broken.
*
* `astro check` type-checks and `astro build` emits files; neither one ever *renders* a page, so a
* component that throws at runtime builds clean and ships blank. That is exactly how the demo
* players went out as empty boxes: the CSP blocked the player's WebAssembly, every `create()` threw
* into a floating promise, and nothing in the pipeline was looking.
*
* So this drives headless Chrome over CDP and asserts three things per page: no uncaught
* exceptions, no CSP violations, and the elements that are supposed to exist actually do. It runs
* against `wrangler pages dev`, not `astro preview`, because `_headers` — where the CSP lives — is
* only applied by Pages.
*
* One thing about the site decides how the checking works: the demos are `client:visible` islands,
* and such an island mounts where the viewport comes to *rest*, not where it passes. A single jump
* to the bottom therefore hydrates whatever happens to be in view when it lands — which depends on
* how tall the page is at that instant, which depends on how fast the images arrived. That is
* measured rather than assumed: with the network throttled to a cold runner's speed, this script
* failed six runs out of six on the jump and none out of six once it walked the page a screen at a
* time instead. So it walks, and it waits for the load event rather than guessing at one.
*
* Usage: node scripts/site-smoke.mjs [base-url]
*/
import { spawn } from "node:child_process";
import { setTimeout as sleep } from "node:timers/promises";
const BASE = process.argv[2] ?? "http://127.0.0.1:8788";
const PORT = 9333;
/** What each page must contain to count as rendered, keyed by path. */
const PAGES = [
{
path: "/",
expect: [".ap-player", ".still__img", ".masthead__mark"],
shine: ".hero__mark .wordmark",
captures: true,
},
{ path: "/themes/", expect: [".theme__name", ".masthead__mark"] },
// The measured bars come from a JSON a script writes, the part that could go missing
{ path: "/tools/", expect: [".bench__bar", ".contrast", ".masthead__mark"] },
{ path: "/docs/", expect: [".docs__body", ".docs__nav"] },
// Highlighted code and an inlined screenshot, the part a broken plugin would drop silently
{ path: "/docs/quickstart/", expect: [".docs__body", ".astro-code", ".guide-shot svg"] },
{ path: "/brand/", expect: [".masthead__mark"] },
{ path: "/404", expect: [] },
];
/**
* The guide as text, for agents: each must be served as the type it claims, with UTF-8, since
* Pages only applies `_headers` and a wrong charset turns every em dash into mojibake for a model.
*/
const TEXTS = [
{ path: "/llms.txt", type: "text/plain", expect: ["# Luxe", "/docs/install.md"] },
{ path: "/llms-full.txt", type: "text/plain", expect: ["# Install"] },
{ path: "/docs/install.md", type: "text/markdown", expect: ["# Install"] },
];
/** What is wrong with a text endpoint, if anything. */
async function checkText({ path, type, expect }) {
const response = await fetch(BASE + path);
if (!response.ok) return [`HTTP ${response.status}`];
const contentType = response.headers.get("content-type") ?? "";
const bad = [];
if (!contentType.startsWith(type) || !/charset=utf-8/i.test(contentType)) {
bad.push(`content-type is ${contentType || "missing"}, wanted ${type}; charset=utf-8`);
}
const body = await response.text();
for (const text of expect) if (!body.includes(text)) bad.push(`missing ${JSON.stringify(text)}`);
return bad;
}
/** CSP reports and network failures arrive as Log entries, not exceptions. */
const IGNORABLE = [/favicon/i, /Failed to load resource.*404/i];
async function cdp(url) {
const problems = [];
const ws = new WebSocket(url);
let seq = 0;
const pending = new Map();
const send = (method, params = {}) =>
new Promise((resolve) => {
const id = ++seq;
pending.set(id, resolve);
ws.send(JSON.stringify({ id, method, params }));
});
await new Promise((resolve, reject) => {
ws.addEventListener("open", resolve, { once: true });
ws.addEventListener("error", reject, { once: true });
});
ws.addEventListener("message", (event) => {
let msg;
try {
msg = JSON.parse(event.data);
} catch {
return; // a frame we can't read tells us nothing; the assertions still hold
}
if (msg.id && pending.has(msg.id)) {
pending.get(msg.id)(msg.result);
pending.delete(msg.id);
return;
}
if (msg.method === "Runtime.exceptionThrown") {
const d = msg.params.exceptionDetails;
problems.push(`uncaught: ${d.exception?.description ?? d.text}`);
}
if (msg.method === "Log.entryAdded") {
const { level, text, source } = msg.params.entry;
if (level === "error" && !IGNORABLE.some((re) => re.test(text))) {
problems.push(`${source}: ${text}`);
}
}
});
return { send, problems, close: () => ws.close() };
}
/**
* Evaluate `expression` until it returns something truthy, or the attempts run out.
*
* `scroll` walks the page down one screen per attempt while it waits, which is what gives a
* `client:visible` island its chance to mount: the page rests at each stop long enough for a frame,
* and never returns to the top, so nothing is skipped however tall the page turns out to be.
*/
async function poll(send, expression, { attempts = 60, waitMs = 250, scroll = false } = {}) {
for (let attempt = 0; attempt < attempts; attempt++) {
const { result } = await send("Runtime.evaluate", {
expression,
returnByValue: true,
});
if (result?.value) return result.value;
if (scroll) {
await send("Runtime.evaluate", {
expression: `scrollTo(0, Math.min(${attempt} * innerHeight * 0.8, document.body.scrollHeight))`,
});
}
await sleep(waitMs);
}
return 0;
}
/**
* Milliseconds from load: mid-pass across the letters, and parked after it.
*
* Offset by the front page's `--shine-delay`, which holds the first sweep until the opening has
* finished typing the logotype in. Sampled at 800ms the band had not started, and this probe
* correctly reported that it could not see the shine move — which is the failure it exists to
* catch, so the window moves rather than the assertion loosening.
*/
const SHINE_DELAY = 7800;
const MID_PASS = SHINE_DELAY + 800;
const AT_REST = SHINE_DELAY + 3000;
/**
* How far right of the bottom the top of the band has to sit, as a fraction of the mark's width.
*
* The terminal's lean is one column per row over seven rows of a forty-four column mark, and the
* slices measured are a third of the height apart — so the true figure is near a tenth. A third of
* that is enough to tell a `/` from a `\` or from no lean at all, without pinning the exact angle.
*/
const LEAN_FLOOR = 0.035;
/**
* Hold everything in the mark's corner of the page at an exact frame, and report where that leaves
* the band.
*
* The Web Animations API, not a negative `animation-delay`: changing the delay on an animation that
* is already running *shifts* its timeline rather than setting it, so the frame you get back
* depends on how long the page happens to have been open. Two arbitrary frames differ on a broken
* build as readily as on a good one, which is a probe that passes whatever it is shown.
* `currentTime` is the frame you asked for.
*
* **Every** animation over the captured region, not only the sweep. Two captures are subtracted to
* isolate the band, so anything else still moving between them lands in the difference and is
* measured as if it were shine. The front page has two such things: the opening `print` reveal,
* which is a `clip-path` on the `<svg>` itself, and `.hero__caret` — an opaque bar in the accent
* color that runs the width of the mark while it types. Pinning the band alone left both of them
* advancing in real time, so the probe's answer depended on how long the page had been open when
* it ran: green on a slow runner where the opening had finished, and a wrong lean on a fast one
* where it had not. A caret caught mid-sweep is a bright stripe in the diff, which is exactly the
* shape this is trying to measure.
*
* Scoped to the mark's own container rather than the document, so a check that runs after this one
* still finds the rest of the page animating.
*
* `null` means there was no sweep to sample at all, which is a broken probe rather than a pass.
*/
const holdAt = (selector, ms) => `(() => {
const svg = document.querySelector(${JSON.stringify(selector)});
const band = svg?.querySelector(".wordmark__band");
if (!band?.getAnimations().length) return null;
// The opening reveal and the caret are siblings of the mark, not children of it.
const region = svg.closest(".hero__mark") ?? svg;
for (const animation of document.getAnimations()) {
const target = animation.effect?.target;
if (!target || !(region === target || region.contains(target))) continue;
animation.pause();
// Settle the one-shots on their last frame — the reveal fully open, the caret gone — so the
// two captures differ by the band and nothing else. An infinite animation has no last
// frame; the drift parks at zero, where it is identical in both.
const end = animation.effect?.getComputedTiming?.().endTime;
animation.currentTime = Number.isFinite(end) ? end : 0;
}
for (const animation of band.getAnimations()) animation.currentTime = ${ms};
return getComputedStyle(band).transform;
})()`;
/**
* The mark's box in page coordinates, plus a patch inside it that no letter covers.
*
* As near the middle as the letters allow, because that is where the band is at `MID_PASS`. Simply
* taking the first bare point puts the patch in the top-left corner, which the band has not reached
* at either sampled frame — and a patch the shine could never touch cannot report a mask that has
* stopped containing it.
*/
const probeGeometry = (selector) => `(() => {
const svg = document.querySelector(${JSON.stringify(selector)});
if (!svg) return null;
// The band sits over the letters, and this finds them by hit testing.
const band = svg.querySelector(".wordmark__band");
if (band) band.style.pointerEvents = "none";
const box = svg.getBoundingClientRect();
const ink = [...svg.querySelectorAll(".wordmark__ink path")];
const middle = box.left + box.width / 2;
let bare = null;
for (let row = 1; row < 16; row++) {
for (let col = 1; col < 32; col++) {
const x = box.left + (box.width * col) / 32;
const y = box.top + (box.height * row) / 16;
if (ink.includes(document.elementFromPoint(x, y))) continue;
if (!bare || Math.abs(x - middle) < Math.abs(bare.x - middle)) bare = { x, y };
}
}
return {
mark: { x: box.left + scrollX, y: box.top + scrollY, width: box.width, height: box.height },
bare: bare && { x: bare.x + scrollX - 4, y: bare.y + scrollY - 4, width: 8, height: 8 },
};
})()`;
/**
* Where the shine sits, per horizontal slice of the mark.
*
* The lit capture minus the resting one is the band on its own, with the letters and the drift
* subtracted out. Its weighted mean column, taken across the top slice and the bottom slice, is the
* lean: the terminal's band gains a column of lead per row upward, so the top slice has to sit to
* the right of the bottom one.
*/
const measureLean = (litPng, restPng) => `(async () => {
const load = (data) =>
new Promise((resolve, reject) => {
const image = new Image();
image.onload = () => resolve(image);
image.onerror = () => reject(new Error("the capture would not decode"));
image.src = "data:image/png;base64," + data;
});
const pixels = (image) => {
const canvas = document.createElement("canvas");
[canvas.width, canvas.height] = [image.width, image.height];
const context = canvas.getContext("2d", { willReadFrequently: true });
context.drawImage(image, 0, 0);
return context.getImageData(0, 0, image.width, image.height).data;
};
const [litImage, restImage] = await Promise.all([
load(${JSON.stringify(litPng)}),
load(${JSON.stringify(restPng)}),
]);
const { width, height } = litImage;
const [lit, rest] = [pixels(litImage), pixels(restImage)];
const meanColumn = (from, to) => {
let weight = 0;
let moment = 0;
for (let y = from; y < to; y++) {
for (let x = 0; x < width; x++) {
const at = (y * width + x) * 4;
let added = 0;
for (const channel of [0, 1, 2]) {
added += Math.max(0, lit[at + channel] - rest[at + channel]);
}
weight += added;
moment += added * x;
}
}
return weight > 0 ? moment / weight : null;
};
const slice = Math.max(1, Math.floor(height / 3));
return { top: meanColumn(0, slice), bottom: meanColumn(height - slice, height), width };
})()`;
/**
* Assert the shine actually paints, paints only on the letters, and leans the way the terminal's does.
*
* The band is a `<rect>` that is always in the DOM, so every selector check above passes whether or
* not one pixel of it ever lands on the mark — and for the whole life of the site, none did. The
* mask sat on the element the sweep transforms, and an element's own transform redefines the user
* space a `userSpaceOnUse` mask resolves in, so the letters traveled with the band and the two
* never met. Nothing threw, nothing was missing, and the site shipped with no shine at all.
*
* Pixels are the only honest witness, so this compares the mark mid-pass against the mark at rest.
* They must differ — that is the shine arriving — while a patch of background inside the same box
* must not, which is the mask still doing its job rather than the band washing over everything.
*
* The lean gets the same treatment, and for the same reason: an SVG gradient's vector runs across
* the stripe it draws, not along it, so `/` and `\` are one sign apart and look like the same
* arithmetic on the page. Only the paint says which one shipped.
*/
async function shinePaints(send, selector) {
// `instant`, because the site sets `scroll-behavior: smooth` and a clip captured mid-scroll comes
// back blank — two blank captures compare equal, which is this check's own failure signal.
await send("Runtime.evaluate", {
expression: `scrollTo({ top: 0, left: 0, behavior: "instant" })`,
});
const { result } = await send("Runtime.evaluate", {
expression: probeGeometry(selector),
returnByValue: true,
});
const geometry = result?.value;
if (!geometry) return [`no shine to check: ${selector} is not on the page`];
if (!geometry.bare) return [`no background inside ${selector} to check the mask against`];
const capture = async (ms, clip) => {
const { result: held } = await send("Runtime.evaluate", {
expression: holdAt(selector, ms),
returnByValue: true,
});
// Two frames: one for the hold to land, one for the compositor to draw it.
await send("Runtime.evaluate", {
awaitPromise: true,
expression: `new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)))`,
});
const shot = await send("Page.captureScreenshot", {
format: "png",
clip: { ...clip, scale: 1 },
captureBeyondViewport: true,
});
return { at: held?.value ?? null, png: shot?.data ?? "" };
};
const lit = await capture(MID_PASS, geometry.mark);
const rest = await capture(AT_REST, geometry.mark);
if (!lit.at || !rest.at) return [`no sweep animation on the band inside ${selector}`];
if (lit.at === rest.at) {
return [`the probe is blind: the band does not move between ${MID_PASS}ms and ${AT_REST}ms`];
}
const problems = [];
if (!lit.png || lit.png === rest.png) {
problems.push(`the shine paints nothing: ${selector} is identical mid-pass and at rest`);
}
// The same frame twice. Two captures are subtracted to isolate the band, so the whole method
// rests on nothing *else* over the mark moving between them — and when something did, the
// difference carried it and the lean below measured it as shine. This is that assumption
// asserted rather than assumed: the opening reveal and the caret used to fail it.
const again = await capture(MID_PASS, geometry.mark);
if (again.png !== lit.png) {
problems.push(
`the mark is not still at one frame: two captures of ${MID_PASS}ms inside ${selector} ` +
`differ, so something over it is animating unpinned and lands in the difference`,
);
}
const litBare = await capture(MID_PASS, geometry.bare);
const restBare = await capture(AT_REST, geometry.bare);
if (litBare.png !== restBare.png) {
problems.push(`the shine escapes the letters: background inside ${selector} lit up too`);
}
const { result: lean } = await send("Runtime.evaluate", {
expression: measureLean(lit.png, rest.png),
awaitPromise: true,
returnByValue: true,
});
const { top, bottom, width } = lean?.value ?? {};
if (typeof top !== "number" || typeof bottom !== "number") {
problems.push(`could not read where the shine fell inside ${selector}`);
} else if (top - bottom < width * LEAN_FLOOR) {
problems.push(
`the shine leans the wrong way inside ${selector}: the top of the band sits ` +
`${(top - bottom).toFixed(1)}px right of the bottom, wanted at least ` +
`${(width * LEAN_FLOOR).toFixed(1)}px`,
);
}
return problems;
}
/**
* The advance width the captures are drawn against, as a fraction of the type size.
*
* `fixture_svg.rs`'s `ADVANCE`. Every row of a capture is stretched to `cols × CELL_W` by
* `textLength`, so a face that advances anything else has its glyphs squeezed or pulled apart —
* across every picture on the page at once, and silently.
*/
const CAPTURE_ADVANCE = 0.6;
/**
* Whether the captures are set in the face this site ships, measured rather than assumed.
*
* An SVG loaded through `<img src>` is a document of its own in secure static mode: it cannot see
* this page's `@font-face`, so the subset webfont never reached a single screenshot and every Nerd
* Font icon in them drew as tofu. None of that is visible to anyone with the face installed
* locally, which is anyone who works on Luxe — so the check has to be a measurement taken in the
* page.
*
* `foreign` is the structural half: a capture that is not an `<svg>` holding real `<text>` in *this*
* document cannot be reached by a face declared in it, whatever the pixels say. `advance` is the
* numeric half, and it is the figure the export's geometry is pinned to.
*/
const captureTypeface = `(async () => {
// Both kinds of capture. A .shot__img is generated from the Rust source; a .still__img is a
// frame cut out of a recording. Same page font, same failure, so the probe has to see both or
// it silently stops covering whichever a page happens to use. (No backticks in here: this
// whole function is a template literal, and one would end it.)
const shots = [...document.querySelectorAll(".shot__img, .still__img")];
if (!shots.length) return { none: true };
// The structural half first, and the measurement only from a capture that passed it: an <img>
// carries no font-family to read, so asking it what face it uses would report a broken probe
// where the answer is the defect itself.
const inline = shots.filter((shot) => shot.localName === "svg" && shot.querySelector("text"));
const report = { total: shots.length, foreign: shots.length - inline.length };
const stack = inline[0]?.getAttribute("font-family");
if (!stack) return report;
report.stack = stack;
const font = \`400 100px \${stack}\`;
try {
await document.fonts.load(font);
} catch (error) {
return { ...report, error: String(error) };
}
await document.fonts.ready;
const canvas = document.createElement("canvas").getContext("2d");
canvas.font = font;
report.loaded = [...document.fonts].filter(
(face) => stack.includes(face.family) && face.status === "loaded",
).length;
report.advance = canvas.measureText("M").width / 100;
return report;
})()`;
async function capturesAreTypeset(send) {
const { result } = await send("Runtime.evaluate", {
expression: captureTypeface,
awaitPromise: true,
returnByValue: true,
});
const report = result?.value;
if (!report) return ["could not read how the captures are typeset"];
if (report.none) return ["no captures on the page to check"];
const problems = [];
if (report.foreign) {
problems.push(
`${report.foreign} of ${report.total} captures are not inline <svg> with <text> — an ` +
"SVG in an <img> is its own document and cannot use this page's @font-face",
);
}
if (report.error) {
problems.push(`the face the captures ask for would not load: ${report.error}`);
return problems;
}
if (!report.stack) {
// Only reachable when every capture is foreign, which the line above has already said.
if (!problems.length) problems.push("the captures name no font-family to measure");
return problems;
}
if (!report.loaded) {
problems.push("the site declares no loaded webfont for the face the captures ask for");
}
if (Math.abs(report.advance - CAPTURE_ADVANCE) > 0.005) {
problems.push(
`the captures' face advances ${report.advance.toFixed(3)}em where the export is pinned ` +
`to ${CAPTURE_ADVANCE}em — every row is squeezed or pulled apart by that ratio`,
);
}
return problems;
}
async function main() {
const chrome = spawn(
process.env.CHROME ?? "google-chrome-stable",
[
"--headless",
"--disable-gpu",
"--no-sandbox",
"--hide-scrollbars",
`--remote-debugging-port=${PORT}`,
"about:blank",
],
// Kept rather than discarded: when the port never opens, Chrome's own complaint is the only
// thing that says why, and throwing it away left a failure reading "never came up" with
// nothing to act on.
{ stdio: ["ignore", "ignore", "pipe"] },
);
let stderr = "";
chrome.stderr?.on("data", (chunk) => {
stderr += chunk;
});
let exit = null;
chrome.on("exit", (code, signal) => {
exit = signal ?? code;
});
// A cold runner starts Chrome a lot slower than a warm laptop, and this budget is waiting on a
// process launch rather than on anything the site does — so it is generous. A wrong answer here
// fails the build for a reason unrelated to the thing being checked.
let target;
for (let attempt = 0; attempt < 240 && !target; attempt++) {
await sleep(250);
try {
const list = await fetch(`http://127.0.0.1:${PORT}/json/list`).then((r) =>
r.json(),
);
target = list.find((t) => t.type === "page");
} catch {
/* not up yet */
}
}
if (!target) {
chrome.kill();
const why = [
exit === null ? "still running" : `exited with ${exit}`,
stderr.trim() || "no output on stderr",
].join("; ");
throw new Error(`headless Chrome never opened port ${PORT} (${why})`);
}
const { send, problems, close } = await cdp(target.webSocketDebuggerUrl);
await send("Runtime.enable");
await send("Log.enable");
await send("Page.enable");
// Pinned rather than inherited: a runner that reports `reduce` hides the shine by design, and the
// pixel probe below would read that as the defect it exists to catch.
await send("Emulation.setEmulatedMedia", {
features: [{ name: "prefers-reduced-motion", value: "no-preference" }],
});
let failed = 0;
for (const page of PAGES) {
problems.length = 0;
const url = `${BASE}${page.path}`;
await send("Page.navigate", { url });
// The real signal rather than a guess at it: a fixed sleep is either wasted on a warm run or
// too short on a cold one, and what follows wants a page that has finished laying out.
await poll(send, "document.readyState === 'complete'");
const missing = [];
for (const selector of page.expect) {
const expression = `document.querySelectorAll(${JSON.stringify(selector)}).length`;
if (!(await poll(send, expression, { scroll: true }))) missing.push(selector);
}
// A page with nothing to wait for still gets a beat to surface a late error.
await sleep(750);
const bad = [...problems];
if (page.captures) bad.push(...(await capturesAreTypeset(send)));
if (page.shine) bad.push(...(await shinePaints(send, page.shine)));
if (missing.length) {
bad.push(`missing from the DOM: ${missing.join(", ")}`);
// What the page looked like when we gave up. A missing element with no error beside it is
// otherwise indistinguishable from a page that never got the chance to render one, which is
// how the last failure here cost a re-run to diagnose.
const { result } = await send("Runtime.evaluate", {
expression: `JSON.stringify({ readyState: document.readyState, height: document.body.scrollHeight,
scrollY: Math.round(scrollY), viewport: innerHeight, islands: document.querySelectorAll("astro-island").length })`,
returnByValue: true,
});
bad.push(`page state: ${result?.value ?? "unreadable"}`);
}
if (bad.length) {
failed++;
console.error(`✗ ${page.path}`);
for (const problem of bad) console.error(` ${problem}`);
} else {
console.log(`✓ ${page.path}`);
}
}
close();
chrome.kill();
for (const text of TEXTS) {
const bad = await checkText(text);
if (bad.length) {
failed++;
console.error(`✗ ${text.path}`);
for (const problem of bad) console.error(` ${problem}`);
} else {
console.log(`✓ ${text.path}`);
}
}
if (failed) {
console.error(`\n${failed} page(s) failed the smoke check.`);
process.exit(1);
}
console.log("\nall pages rendered clean.");
}
main().catch((error) => {
console.error(error);
process.exit(1);
});

View File

@@ -0,0 +1,3 @@
# Files allowed over a size limit, and the most they may grow to. See scripts/size-check.py.
# <lines> <kind> <path> # reason
623 prod crates/luxe-core/src/event/events.rs # the published Event vocabulary, kept whole: thin variants and no logic, and splitting it into nested enums would retag the wire

128
scripts/size-check.py Executable file
View File

@@ -0,0 +1,128 @@
#!/usr/bin/env python3
"""File-size ratchet for the Rust tree.
Smaller files are cheaper to read and grep, for people and for agents alike. Three limits:
prod 500 lines of a source file outside its inline `#[cfg(test)] mod … { … }` blocks
tests 150 lines of those inline test blocks; past it, move them to `foo/tests.rs`
testfile 800 lines of a test-only file: under `tests/`, named `tests.rs`, `*_tests.rs` or
`test_support.rs`, declared as `#[cfg(test)] mod name;`, or a module of one of those
A file over a limit fails unless `scripts/size-allowlist.txt` lists it, and then it may not grow
past the number recorded there. The list only shrinks: an entry whose file is back under the limit,
or smaller than recorded, fails as stale until `--tighten` rewrites it. Give each entry a reason;
`baseline` marks one nobody has looked at yet.
scripts/size-check.py check
scripts/size-check.py --tighten lower recorded sizes to current, drop entries now under the limit
scripts/size-check.py --report the files over a limit, largest first
"""
import sys
from pathlib import Path
import rust_source
ROOT = Path(__file__).resolve().parent.parent
ALLOWLIST = ROOT / "scripts" / "size-allowlist.txt"
LIMITS = {"prod": 500, "tests": 150, "testfile": 800}
def measure(path: str) -> dict[str, int]:
masked = rust_source.masked_source(path)
total = masked.count("\n") + 1
if path in rust_source.test_files():
return {"testfile": total}
inline = sum(last - first + 1 for first, last in rust_source.test_modules(masked))
return {"prod": total - inline, "tests": inline} if inline else {"prod": total}
def current() -> dict[tuple[str, str], int]:
sizes = {}
for path in rust_source.rust_files():
for kind, size in measure(path).items():
sizes[(path, kind)] = size
return sizes
def load_allowlist() -> dict[tuple[str, str], tuple[int, str]]:
entries = {}
if not ALLOWLIST.exists():
return entries
for raw in ALLOWLIST.read_text().splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
body, _, reason = line.partition("#")
size, kind, path = body.split()
entries[(path, kind)] = (int(size), reason.strip())
return entries
def write_allowlist(entries: dict[tuple[str, str], tuple[int, str]]) -> None:
header = [
"# Files allowed over a size limit, and the most they may grow to. See scripts/size-check.py.",
"# <lines> <kind> <path> # reason",
]
rows = sorted(entries.items(), key=lambda item: (item[0][1], -item[1][0], item[0][0]))
body = [f"{size:>5} {kind:<8} {path} # {reason}" for (path, kind), (size, reason) in rows]
ALLOWLIST.write_text("\n".join(header + body) + "\n")
def over(sizes: dict[tuple[str, str], int]) -> dict[tuple[str, str], int]:
return {key: size for key, size in sizes.items() if size > LIMITS[key[1]]}
def check() -> int:
sizes, allowed = current(), load_allowlist()
problems = []
for (path, kind), size in sorted(over(sizes).items()):
limit = LIMITS[kind]
if (path, kind) not in allowed:
fix = "move the test module to a sibling tests.rs" if kind == "tests" else "split it by responsibility"
problems.append(f"{path}: {size} {kind} lines, over {limit}: {fix}")
elif size > allowed[(path, kind)][0]:
problems.append(f"{path}: {size} {kind} lines, grew past its allowance of {allowed[(path, kind)][0]}")
for (path, kind), (size, _) in sorted(allowed.items()):
now = sizes.get((path, kind), 0)
if now <= LIMITS[kind] or now < size:
problems.append(f"{path}: allowlist says {size} {kind} lines, now {now}: run scripts/size-check.py --tighten")
if problems:
print("size check failed:")
print("\n".join(f" {problem}" for problem in problems))
return 1
print(f"size check: {len(sizes)} measurements, {len(allowed)} allowlisted, none over")
return 0
def tighten() -> int:
sizes, allowed = current(), load_allowlist()
kept = {}
for key, (size, reason) in allowed.items():
now = sizes.get(key, 0)
if now > LIMITS[key[1]]:
kept[key] = (min(size, now), reason)
write_allowlist(kept)
print(f"allowlist: {len(allowed)} -> {len(kept)} entries")
return 0
def report() -> int:
for (path, kind), size in sorted(over(current()).items(), key=lambda item: -item[1]):
print(f"{size:>5} {kind:<8} {path}")
return 0
def freeze() -> int:
"""Seed the allowlist with everything over a limit today. Used once, when the ratchet starts."""
write_allowlist({key: (size, "baseline") for key, size in over(current()).items()})
return 0
if __name__ == "__main__":
command = sys.argv[1] if len(sys.argv) > 1 else "--check"
actions = {"--check": check, "--tighten": tighten, "--report": report, "--freeze": freeze}
if command not in actions:
print(__doc__)
sys.exit(2)
sys.exit(actions[command]())

53
scripts/social-card.sh Executable file
View File

@@ -0,0 +1,53 @@
#!/usr/bin/env bash
# Render the Open Graph card to web/public/social.png.
#
# The card is a page (`web/src/pages/social-card.astro`), not a design file, so it is built from the
# same tokens, fonts and logotype as the site and cannot drift from what it advertises. This just
# photographs it at the exact size the platforms want.
#
# Separate from `site-assets.sh` on purpose: that one turns Rust into assets and CI checks it, and
# it should not need Node, a build, and a browser to do so.
#
# Usage: scripts/social-card.sh
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
web_dir="${repo_root}/web"
out="${web_dir}/public/social.png"
port="${PORT:-4331}"
chrome=""
for candidate in chromium google-chrome-stable google-chrome chrome; do
command -v "${candidate}" >/dev/null && chrome="${candidate}" && break
done
[[ -n "${chrome}" ]] || {
echo "no chromium/chrome on PATH" >&2
exit 1
}
cd "${web_dir}"
npm run build >/dev/null
npx astro preview --port "${port}" >/dev/null 2>&1 </dev/null &
preview=$!
trap 'kill "${preview}" 2>/dev/null || true' EXIT
for _ in $(seq 1 30); do
sleep 1
if curl -sf -o /dev/null "http://localhost:${port}/social-card"; then
break
fi
done
curl -sf -o /dev/null "http://localhost:${port}/social-card" || {
echo "preview never came up on :${port}" >&2
exit 1
}
# `--virtual-time-budget` waits for the webfonts and the wordmark rather than shooting a blank frame.
"${chrome}" --headless --disable-gpu --hide-scrollbars \
--force-device-scale-factor=1 --window-size=1200,630 \
--virtual-time-budget=5000 \
--screenshot="${out}" "http://localhost:${port}/social-card" 2>/dev/null
printf 'wrote %s (%s bytes)\n' "${out}" "$(stat -c%s "${out}")"

39
scripts/tool-bench.sh Executable file
View File

@@ -0,0 +1,39 @@
#!/usr/bin/env bash
# Measure each tool against the shell command it replaces, for the site's Tools page.
#
# scripts/tool-bench.sh NAME=REPO:CASES ...
#
# Each argument is a checkout to measure in and the cases to run there (scripts/tool-bench/);
# Luxe's own checkout is always measured last, with the cases built into the example. The first
# repository is the one the page draws its bars from.
#
# A recording, not a generated asset: the numbers depend on the trees they run in, build output
# and virtualenvs included, so nothing checks them. Run it after a build, and commit the JSON,
# which names each repository's commit. Needs network for the web_fetch row.
set -euo pipefail
cd "$(dirname "$0")/.."
root=$PWD
cargo build -q --release -p luxe-cli --example tool_bench
bench="$root/target/release/examples/tool_bench"
out=$(mktemp -d)
names=()
for spec in "$@"; do
name=${spec%%=*}
rest=${spec#*=}
repo=${rest%%:*}
cases=${rest#*:}
(cd "$repo" && TOOL_BENCH_CASES="$root/$cases" "$bench" "$out/$name.json")
names+=("$name")
done
"$bench" "$out/Luxe.json"
names+=("Luxe")
python3 - "$out" "${names[@]}" <<'PY' > web/src/data/tool-bench.json
import json, sys
out, names = sys.argv[1], sys.argv[2:]
repos = []
for name in names:
data = json.load(open(f"{out}/{name}.json"))
repos.append({"name": name, "commit": data["commit"], "rows": data["rows"]})
print(json.dumps({"repositories": repos}, indent=2))
PY
rm -rf "$out"

View File

@@ -0,0 +1,67 @@
[
{
"id": "glob",
"shell": "find . -name '*.py'",
"tool": "glob",
"args": {
"pattern": "**/*.py"
}
},
{
"id": "grep",
"shell": "rg -n 'def delete'",
"tool": "grep",
"args": {
"pattern": "def delete"
}
},
{
"id": "bash",
"shell": "git log --stat -n 30",
"tool": "bash",
"args": {
"command": "git log --stat -n 30"
}
},
{
"id": "test",
"shell": "cd tests && ../.venv/bin/python runtests.py --settings=test_sqlite --parallel 1 delete",
"tool": "test",
"args": {
"command": "cd tests && ../.venv/bin/python runtests.py --settings=test_sqlite --parallel 1 delete"
}
},
{
"id": "git",
"shell": "git log",
"tool": "git",
"args": {
"action": "log"
}
},
{
"id": "read_symbol",
"shell": "cat django/db/models/deletion.py",
"tool": "read_symbol",
"args": {
"path": "django/db/models/deletion.py",
"symbol": "can_fast_delete"
}
},
{
"id": "module_report",
"shell": "cat django/db/models/query.py",
"tool": "module_report",
"args": {
"path": "django/db/models/query.py"
}
},
{
"id": "read",
"shell": "cat django/db/models/query.py",
"tool": "read",
"args": {
"path": "django/db/models/query.py"
}
}
]

View File

@@ -0,0 +1,67 @@
[
{
"id": "glob",
"shell": "find . -name '*.rs'",
"tool": "glob",
"args": {
"pattern": "**/*.rs"
}
},
{
"id": "grep",
"shell": "rg -n 'fn new'",
"tool": "grep",
"args": {
"pattern": "fn new"
}
},
{
"id": "bash",
"shell": "cargo tree",
"tool": "bash",
"args": {
"command": "cargo tree"
}
},
{
"id": "test",
"shell": "cargo test -p grep-regex",
"tool": "test",
"args": {
"command": "cargo test -p grep-regex"
}
},
{
"id": "git",
"shell": "git log",
"tool": "git",
"args": {
"action": "log"
}
},
{
"id": "read_symbol",
"shell": "cat crates/searcher/src/searcher/mod.rs",
"tool": "read_symbol",
"args": {
"path": "crates/searcher/src/searcher/mod.rs",
"symbol": "search_path"
}
},
{
"id": "module_report",
"shell": "cat crates/searcher/src/searcher/mod.rs",
"tool": "module_report",
"args": {
"path": "crates/searcher/src/searcher/mod.rs"
}
},
{
"id": "read",
"shell": "cat crates/searcher/src/searcher/mod.rs",
"tool": "read",
"args": {
"path": "crates/searcher/src/searcher/mod.rs"
}
}
]

286
scripts/tui-drive.sh Executable file
View File

@@ -0,0 +1,286 @@
#!/usr/bin/env bash
# Drive the TUI through a scripted sequence and capture screenshots along the way.
#
# The agent-loop `screenshot` tool launches a command, waits, types every key at once and shoots
# immediately — which is useless for anything with latency (a review capture, a provider round-trip)
# or for stepping a surface. This drives a real terminal with explicit pauses between steps, so what
# lands in the image is the state you meant to look at.
#
# Usage:
# scripts/tui-drive.sh [options] -- <script-file>
# scripts/tui-drive.sh [options] -s 'step; step; …'
#
# Options:
# --cols N terminal columns (default 170)
# --rows N terminal rows (default 48)
# --theme NAME LUXE theme override written to the throwaway config
# --out DIR screenshot directory (default .pi/agent-loop/shots)
# --cmd 'CMDLINE' what to run in the terminal (default: target/release/luxe)
# --keep leave the terminal open when the script ends
# -s 'STEPS' inline steps, separated by `;` or newlines
#
# Steps (one per line, `#` comments allowed):
# sleep <seconds> wait (fractions fine)
# type <text> type literal text (no Enter)
# enter <text> type text then press Return
# key <keysym>[ xN] press a key by xkb name (Return, Escape, Tab, Down, F5, …), N times
# mod <mods> <keysym> press a chord, mods among ctrl/alt/shift/logo joined by `+`
# shot <name> capture the window to <out>/<name>.png (+ a downscaled .jpg)
# log <text> echo a progress note
#
# Environment passed through to the app: anything already exported, plus LUXE_* set by the caller.
# A throwaway XDG_CONFIG_HOME is built from your real ~/.config/luxe with the startup dashboard
# disabled, so the first keystroke always reaches the composer instead of a splash screen.
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cols=170
rows=48
theme=""
out_dir="${repo_root}/.pi/agent-loop/shots"
app_cmd="${repo_root}/target/release/luxe"
keep=false
inline_steps=""
script_file=""
usage() { sed -n '2,33p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
while [[ $# -gt 0 ]]; do
case "$1" in
--cols)
cols="$2"
shift 2
;;
--rows)
rows="$2"
shift 2
;;
--theme)
theme="$2"
shift 2
;;
--out)
out_dir="$2"
shift 2
;;
--cmd)
app_cmd="$2"
shift 2
;;
--keep)
keep=true
shift
;;
-s)
inline_steps="$2"
shift 2
;;
-h | --help)
usage
exit 0
;;
--)
shift
script_file="${1:-}"
shift || true
;;
*)
script_file="$1"
shift
;;
esac
done
for tool in alacritty wtype grim hyprctl jq; do
command -v "$tool" >/dev/null || {
echo "missing required tool: $tool" >&2
exit 2
}
done
mkdir -p "$out_dir"
# A throwaway config dir mirroring the user's (keys, providers) with the dashboard off: typing has
# to land in the composer, and the splash screen swallows the first keystrokes.
config_home="$(mktemp -d /tmp/luxe-drive-XXXXXX)"
mkdir -p "${config_home}/luxe"
if [[ -d "${XDG_CONFIG_HOME:-$HOME/.config}/luxe" ]]; then
cp -r "${XDG_CONFIG_HOME:-$HOME/.config}/luxe/." "${config_home}/luxe/" 2>/dev/null || true
fi
python3 - "$config_home" "$theme" <<'PY'
import json, pathlib, sys
home, theme = sys.argv[1], sys.argv[2]
path = pathlib.Path(home) / "luxe" / "config.json"
config = {}
if path.exists():
try:
config = json.loads(path.read_text())
except Exception:
config = {}
config["dashboard"] = False
config["notifications"] = False
if theme:
config["theme"] = theme
path.write_text(json.dumps(config, indent=2))
PY
title="luxe-drive-$$"
window_class="luxe-drive"
font_size="${LUXE_DRIVE_FONT_SIZE:-11}"
# Hyprland 0.56 moved `dispatch` and the config parser to Lua, so the legacy spellings below now
# fail — and under `set -e` a failed `hyprctl` took the whole drive down before a single step ran.
# Both forms are tried, and neither is fatal: the worst case is a tiled window whose grid the tile
# decided, which `refresh_geometry` reads back anyway.
hypr() {
hyprctl dispatch "$1" >/dev/null 2>&1 && return 0
hyprctl dispatch "$2" >/dev/null 2>&1 && return 0
return 0
}
# Float the terminal so the compositor honors the geometry alacritty asks for; tiled, the tile
# decides the grid and `--cols/--rows` become suggestions (a 170x48 request rendered 230x74).
hyprctl keyword windowrulev2 "float, class:^(${window_class})\$" >/dev/null 2>&1 || true
cleanup() {
if [[ "$keep" == false && -n "${term_pid:-}" ]]; then
kill "$term_pid" 2>/dev/null || true
fi
rm -rf "$config_home"
}
trap cleanup EXIT
# The throwaway XDG_CONFIG_HOME is for Luxe alone. gh finds its hosts.yml under the same variable,
# so without this every GitHub surface in the drive reads "not signed in" while gh is fine
export GH_CONFIG_DIR="${GH_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/gh}"
XDG_CONFIG_HOME="$config_home" alacritty \
--class "$window_class,$window_class" \
--title "$title" \
-o "window.dimensions.columns=$cols" \
-o "window.dimensions.lines=$rows" \
-o "font.size=$font_size" \
-e bash -lc "cd '$repo_root' && $app_cmd" &
term_pid=$!
# Wait for the window to map before typing at it.
geometry=""
for _ in $(seq 1 60); do
geometry="$(hyprctl clients -j | jq -r --arg t "$title" '.[] | select(.title==$t) | "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"' | head -1)"
[[ -n "$geometry" ]] && break
sleep 0.2
done
if [[ -z "$geometry" ]]; then
echo "terminal window '$title' never appeared" >&2
exit 1
fi
# Focus it so keystrokes land here and not in whatever had focus.
hypr "hl.dsp.focus({ window = \"title:$title\" })" "focuswindow title:$title"
refresh_geometry() {
geometry="$(hyprctl clients -j | jq -r --arg t "$title" '.[] | select(.title==$t) | "\(.at[0]),\(.at[1]) \(.size[0])x\(.size[1])"' | head -1)"
}
# Wait without going idle.
#
# A drive is mostly waiting on a provider, which to the compositor looks like nobody is at the
# keyboard — long enough and the screensaver/lock takes the screen, the captures become pictures of
# hyprlock, and every subsequent scripted keystroke is typed into a password field. So long waits
# are broken up and punctuated with a bare modifier press: real input to the compositor, a no-op to
# the app under test.
idle_safe_sleep() {
local remaining="$1" chunk
while awk -v r="$remaining" 'BEGIN { exit !(r > 0) }'; do
chunk="$(awk -v r="$remaining" 'BEGIN { print (r > 30 ? 30 : r) }')"
sleep "$chunk"
remaining="$(awk -v r="$remaining" -v c="$chunk" 'BEGIN { print r - c }')"
if awk -v r="$remaining" 'BEGIN { exit !(r > 0) }'; then
wtype -M shift -m shift
fi
done
}
shot() {
local name="$1"
refresh_geometry
local png="${out_dir}/${name}.png"
# A locked or blanked screen draws no frames, and grim waits for one forever
if ! timeout 15 grim -g "$geometry" "$png"; then
echo "tui-drive: no capture within 15s; the screen is probably locked or asleep" >&2
exit 1
fi
if command -v magick >/dev/null; then
magick "$png" -resize 1280x -quality 88 "${out_dir}/${name}.jpg"
fi
echo "shot ${out_dir}/${name}.png"
}
run_step() {
local line="$1"
line="${line%%$'\r'}"
# Leading space is how an inline `-s 'a; b'` arrives, and it used to make every step after
# the first an unknown one.
line="${line#"${line%%[![:space:]]*}"}"
[[ -z "${line// /}" || "$line" == \#* ]] && return 0
local verb="${line%% *}"
local rest="${line#"$verb"}"
rest="${rest# }"
case "$verb" in
sleep) idle_safe_sleep "$rest" ;;
log) echo "-- $rest" ;;
type) wtype -- "$rest" ;;
enter)
[[ -n "$rest" ]] && wtype -- "$rest"
sleep 0.15
wtype -k Return
;;
key)
local keysym count
keysym="${rest%% *}"
count="${rest#"$keysym"}"
count="${count// /}"
[[ "$count" =~ ^x[0-9]+$ ]] && count="${count#x}" || count=1
for _ in $(seq 1 "$count"); do
wtype -k "$keysym"
sleep 0.08
done
;;
mod)
local mods keysym
mods="${rest%% *}"
keysym="${rest#"$mods"}"
keysym="${keysym# }"
local args=()
IFS='+' read -ra parts <<<"$mods"
for part in "${parts[@]}"; do args+=(-M "$part"); done
args+=(-k "$keysym")
for part in "${parts[@]}"; do args+=(-m "$part"); done
wtype "${args[@]}"
;;
shot) shot "$rest" ;;
*)
echo "unknown step: $line" >&2
return 1
;;
esac
return 0
}
steps() {
if [[ -n "$inline_steps" ]]; then
printf '%s\n' "${inline_steps//;/$'\n'}"
elif [[ -n "$script_file" ]]; then
cat "$script_file"
else
cat # stdin
fi
}
while IFS= read -r line; do
run_step "$line"
done < <(steps)
if [[ "$keep" == true ]]; then
echo "terminal left open (pid $term_pid)"
fi

229
scripts/tui-latency.py Executable file
View File

@@ -0,0 +1,229 @@
#!/usr/bin/env python3
"""Type at the real TUI through a pty and measure how far behind the input it falls.
Frame cost is easy to reason about wrongly and easy to measure directly. This spawns `luxe` on a
pty, waits for the first frame to settle, then types at a fixed rate and records what the process
did about it: how soon each key was answered, how much it wrote, how much CPU it burned, and — the
number that actually describes a freeze — how long it kept catching up after the typing stopped.
scripts/tui-latency.py --resume <session-id> --keys 240 --rate 80
Pair it with `LUXE_FRAME_PROFILE`, which the binary reads to dump per-frame timings:
scripts/tui-latency.py --resume <id> --env LUXE_FRAME_PROFILE=/tmp/frame.csv
`scripts/make-big-session.py` builds a long session to point it at.
"""
from __future__ import annotations
import argparse
import fcntl
import os
import pty
import select
import signal
import struct
import sys
import termios
import time
# Startup probes crossterm and the graphics layer send that block until something answers. A pty is
# not a terminal, so the harness plays one well enough to get past them.
PROBES: tuple[tuple[bytes, bytes], ...] = (
(b"\x1b[6n", b"\x1b[1;1R"), # cursor position
(b"\x1b[c", b"\x1b[?62;c"), # primary device attributes
(b"\x1b[?u", b"\x1b[?0u"), # kitty keyboard protocol
)
def set_winsize(fd: int, rows: int, cols: int) -> None:
fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
def answer_probes(fd: int, chunk: bytes) -> None:
for probe, reply in PROBES:
for _ in range(chunk.count(probe)):
os.write(fd, reply)
def drain(fd: int, quiet_for: float, limit: float) -> tuple[int, float]:
"""Read until the child has been silent for `quiet_for`. Returns (bytes, seconds)."""
started = time.monotonic()
last = started
total = 0
while True:
now = time.monotonic()
if now - last >= quiet_for:
return total, last - started
if now - started >= limit:
return total, now - started
if not select.select([fd], [], [], quiet_for)[0]:
continue
try:
chunk = os.read(fd, 1 << 16)
except OSError:
return total, time.monotonic() - started
if not chunk:
return total, time.monotonic() - started
answer_probes(fd, chunk)
total += len(chunk)
last = time.monotonic()
def read_for(fd: int, seconds: float) -> None:
"""Read and discard for `seconds`, answering probes, so the child never blocks on its output."""
until = time.monotonic() + seconds
while (remaining := until - time.monotonic()) > 0:
if not select.select([fd], [], [], remaining)[0]:
continue
try:
chunk = os.read(fd, 1 << 16)
except OSError:
return
if not chunk:
return
answer_probes(fd, chunk)
def cpu_of(pid: int) -> float:
"""User + system CPU seconds the process has burned."""
with open(f"/proc/{pid}/stat", "rb") as handle:
fields = handle.read().rsplit(b")", 1)[1].split()
return (int(fields[11]) + int(fields[12])) / os.sysconf("SC_CLK_TCK")
def rss_of(pid: int) -> int:
"""Resident set size, in KiB."""
with open(f"/proc/{pid}/status", "rb") as handle:
for line in handle:
if line.startswith(b"VmRSS:"):
return int(line.split()[1])
return 0
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--binary", default="target/release/luxe")
parser.add_argument("--resume", help="session id to resume, so the transcript has some length")
parser.add_argument("--rows", type=int, default=50)
parser.add_argument("--cols", type=int, default=200)
parser.add_argument("--keys", type=int, default=240)
parser.add_argument("--rate", type=float, default=80.0, help="keystrokes per second")
parser.add_argument("--settle", type=float, default=10.0, help="seconds to let startup finish")
parser.add_argument("--char", default="x", help="the character to type")
parser.add_argument(
"--prompt",
help="submit this first and measure while the turn streams, which is the harder case: "
"the reveal drives the loop at ~80fps and the tail relays out on every one of them",
)
parser.add_argument(
"--warmup", type=float, default=8.0, help="seconds to let a --prompt turn get going"
)
parser.add_argument("--env", action="append", default=[], help="NAME=VALUE for the child")
args = parser.parse_args()
argv = [args.binary] + (["--resume", args.resume] if args.resume else [])
env = dict(os.environ, TERM="xterm-256color")
for pair in args.env:
name, _, value = pair.partition("=")
env[name] = value
pid, fd = pty.fork()
if pid == 0:
os.execvpe(argv[0], argv, env)
os._exit(127)
set_winsize(fd, args.rows, args.cols)
try:
startup, _ = drain(fd, quiet_for=0.5, limit=args.settle)
print(f"startup: {startup / 1024:.0f} KiB, cpu {cpu_of(pid):.2f}s, rss {rss_of(pid) / 1024:.0f} MiB")
if args.prompt:
os.write(fd, args.prompt.encode() + b"\r")
# Let the request go out and the first tokens land, so the burst below falls in the
# middle of a stream rather than before one.
read_for(fd, args.warmup)
print(f"prompt submitted, {args.warmup:g}s ago; measuring while it streams")
interval = 1.0 / args.rate
payload = args.char.encode()
cpu_before, rss_before = cpu_of(pid), rss_of(pid)
written = 0
latencies: list[float] = []
unanswered = 0
start = time.monotonic()
for index in range(args.keys):
deadline = start + index * interval
if (slack := deadline - time.monotonic()) > 0:
time.sleep(slack)
sent = time.monotonic()
os.write(fd, payload)
# Read whatever comes back inside this keystroke's slot; the first byte of the answer
# is the frame that belongs to it.
first = None
while (remaining := deadline + interval - time.monotonic()) > 0:
if not select.select([fd], [], [], remaining)[0]:
break
chunk = os.read(fd, 1 << 16)
if not chunk:
break
answer_probes(fd, chunk)
first = first if first is not None else time.monotonic() - sent
written += len(chunk)
if first is None:
unanswered += 1
else:
latencies.append(first)
typing = time.monotonic() - start
cpu_after = cpu_of(pid)
tail_bytes, tail_seconds = drain(fd, quiet_for=0.25, limit=10.0)
latencies.sort()
def percentile(fraction: float) -> float:
if not latencies:
return float("nan")
return latencies[min(int(len(latencies) * fraction), len(latencies) - 1)] * 1000
print()
print(f"typed {args.keys} keys at {args.rate:g}/s over {typing:.2f}s")
print(f" keys with no frame inside their slot : {unanswered}")
print(
f" first-byte latency p50 {percentile(0.5):6.1f} ms "
f"p95 {percentile(0.95):6.1f} ms max {percentile(1.0):6.1f} ms"
)
print(
f" bytes written while typing : {written / 1024:.0f} KiB "
f"({written / max(typing, 1e-9) / 1024:.0f} KiB/s)"
)
# With a turn in flight this is the stream, not a backlog; `unanswered` and the latency
# percentiles above are what say whether the loop actually fell behind.
label = "output after the last key" if args.prompt else "still catching up after the last key"
print(f" {label:<36} : {tail_seconds * 1000:.0f} ms, {tail_bytes / 1024:.0f} KiB")
print(
f" cpu burned while typing : {cpu_after - cpu_before:.2f}s "
f"({(cpu_after - cpu_before) / max(typing, 1e-9) * 100:.0f}% of one core)"
)
print(f" rss : {rss_before / 1024:.0f} -> {rss_of(pid) / 1024:.0f} MiB")
return 0
finally:
# Twice: the first interrupt ends a running turn, the second ends the session. The frame
# profile is written on the way out, so the wait has to be long enough for it.
try:
for _ in range(2):
os.write(fd, b"\x03")
read_for(fd, 0.6)
except OSError:
pass
try:
os.kill(pid, signal.SIGKILL)
except ProcessLookupError:
pass
os.close(fd)
os.waitpid(pid, 0)
if __name__ == "__main__":
sys.exit(main())

109
scripts/update-models-snapshot.sh Executable file
View File

@@ -0,0 +1,109 @@
#!/usr/bin/env bash
# Regenerate the embedded models.dev snapshot.
#
# Luxe resolves model metadata from four layers (defaults -> snapshot -> cache -> config). The
# snapshot is the offline/first-run floor: it's what a fresh install with no network knows. The
# runtime refresh keeps a live install current, so this only needs to run at release cadence —
# CI does it weekly and opens a PR when the bytes change.
#
# The projection keeps only the fields `luxe_providers::catalog::schema` reads, then gzips, which
# takes the 3.2 MB API response down to ~150 KB in the binary.
#
# Usage:
# scripts/update-models-snapshot.sh [--url URL]
set -euo pipefail
URL="${MODELS_DEV_URL:-https://models.dev/api.json}"
while [[ $# -gt 0 ]]; do
case "$1" in
--url)
URL="$2"
shift 2
;;
*)
echo "unknown argument: $1" >&2
exit 2
;;
esac
done
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
OUT="$ROOT/crates/luxe-providers/data/models-dev-snapshot.json.gz"
TMP="$(mktemp -d)"
trap 'rm -rf "$TMP"' EXIT
echo "fetching $URL"
curl --fail --silent --show-error --location --max-time 60 --compressed "$URL" -o "$TMP/api.json"
python3 - "$TMP/api.json" "$TMP/snapshot.json" <<'PY'
import json, sys
MODEL_FIELDS = (
"name", "reasoning", "tool_call", "release_date", "status",
"limit", "cost", "modalities", "reasoning_options",
)
COST_FIELDS = ("input", "output", "cache_read", "cache_write")
def clean(value):
"""Drop nulls and empties so the snapshot matches what the schema re-serializes.
Upstream does ship the occasional null inside a string array (sarvam-*), which the strict
Rust schema would reject; stripping here keeps the rest of that entry usable.
"""
if isinstance(value, dict):
out = {k: clean(v) for k, v in value.items() if v is not None}
return {k: v for k, v in out.items() if v not in ({}, [], None)}
if isinstance(value, list):
return [clean(v) for v in value if v is not None]
return value
def project_model(model):
out = {}
for field in MODEL_FIELDS:
value = model.get(field)
if value in (None, {}, []):
continue
if field == "cost":
value = {k: value[k] for k in COST_FIELDS if value.get(k) is not None}
elif field == "modalities":
# Only input modalities are read; output is always ["text"] for chat models.
value = {k: value[k] for k in ("input",) if value.get(k)}
elif field == "reasoning_options":
value = [clean(option) for option in value]
out[field] = clean(value)
return {k: v for k, v in out.items() if v not in ({}, [], None)}
source = json.load(open(sys.argv[1]))
snapshot = {}
for provider_id, provider in sorted(source.items()):
models = {
model_id: project_model(model)
for model_id, model in sorted(provider.get("models", {}).items())
}
if not models:
continue
block = {"models": models}
if provider.get("name"):
block["name"] = provider["name"]
snapshot[provider_id] = block
json.dump(snapshot, open(sys.argv[2], "w"), separators=(",", ":"), sort_keys=True)
print(
f"projected {len(snapshot)} providers / "
f"{sum(len(p['models']) for p in snapshot.values())} models",
file=sys.stderr,
)
PY
# -n so the gzip header carries no name/mtime: identical input yields identical bytes, which
# keeps the weekly CI job from opening a PR that changes nothing.
gzip -9 -n -c "$TMP/snapshot.json" >"$TMP/snapshot.json.gz"
mkdir -p "$(dirname "$OUT")"
if [[ -f "$OUT" ]] && cmp -s "$TMP/snapshot.json.gz" "$OUT"; then
echo "snapshot unchanged ($(wc -c <"$OUT") bytes)"
exit 0
fi
mv "$TMP/snapshot.json.gz" "$OUT"
echo "wrote $OUT ($(wc -c <"$OUT") bytes)"

152
scripts/version-check.py Executable file
View File

@@ -0,0 +1,152 @@
#!/usr/bin/env python3
"""version-check — a change that ships says which version it ships as.
Compares the workspace version against a base ref, normally the pull request's target:
- a change to what reaches crates.io (anything under `crates/`, `Cargo.toml`, `Cargo.lock`) has to
raise the version, and by exactly one semver step, so a typo cannot skip a release;
- the version never goes down, shipped change or not;
- every internal path dependency names the workspace version, because cargo publishes that number
and a stale `0.1.0` still resolves locally against a `0.1.1` beside it;
- `CHANGELOG.md` has a section for the version, which is what a release's notes are cut from.
Usage: scripts/version-check.py [base-ref] (default: origin/main)
"""
from __future__ import annotations
import re
import subprocess
import sys
import tomllib
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
SEMVER = re.compile(
r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
r"(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?"
r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
)
SHIPPED_FILES = {"Cargo.toml", "Cargo.lock"}
DEPENDENCY_TABLES = ("dependencies", "dev-dependencies", "build-dependencies")
class VersionError(Exception):
"""A version that is not semver."""
def parse(version: str) -> tuple[int, int, int, tuple[str, ...]]:
"""`(major, minor, patch, pre-release identifiers)`; build metadata carries no precedence."""
match = SEMVER.match(version)
if not match:
raise VersionError(f"{version!r} is not a semver version")
major, minor, patch, pre = match.groups()
return int(major), int(minor), int(patch), tuple(pre.split(".")) if pre else ()
def precedence(version: str) -> tuple:
"""A sort key that orders versions the way semver 2.0.0 section 11 does."""
major, minor, patch, pre = parse(version)
# A release outranks every pre-release of the same core
release = (1,) if not pre else (0,)
# Numeric identifiers rank below alphanumeric ones and compare as numbers
identifiers = tuple((0, int(part), "") if part.isdigit() else (1, 0, part) for part in pre)
return (major, minor, patch, release, identifiers)
def is_one_step(base: str, head: str) -> bool:
"""Whether `head` follows `base` by one release: a patch, minor or major bump, a pre-release of
one, or the release (or a later pre-release) of the core `base` was a pre-release of."""
if precedence(head) <= precedence(base):
return False
major, minor, patch, base_pre = parse(base)
core = parse(head)[:3]
steps = {(major, minor, patch + 1), (major, minor + 1, 0), (major + 1, 0, 0)}
if base_pre:
steps.add((major, minor, patch))
return core in steps
def ships(paths: list[str]) -> bool:
"""Whether any changed path reaches what crates.io publishes."""
return any(path.startswith("crates/") or path in SHIPPED_FILES for path in paths)
def stale_pins(manifests: dict[str, str], version: str) -> list[str]:
"""Internal path dependencies whose `version` is not the workspace's, as `file: name = pin`."""
stale = []
for name, text in manifests.items():
manifest = tomllib.loads(text)
for table in DEPENDENCY_TABLES:
for dependency, spec in manifest.get(table, {}).items():
if not isinstance(spec, dict) or "path" not in spec or "version" not in spec:
continue
if spec["version"].lstrip("=^") != version:
stale.append(f"{name}: {dependency} = {spec['version']!r}")
return stale
def changelog_has(changelog: str, version: str) -> bool:
"""Whether the changelog has a `## [version]` (or bare `## version`) section."""
heading = rf"^## \[?{re.escape(version)}\]?(?:\s|$)"
return re.search(heading, changelog, re.MULTILINE) is not None
def workspace_version(cargo_toml: str) -> str:
"""The `[workspace.package]` version every crate inherits."""
try:
return tomllib.loads(cargo_toml)["workspace"]["package"]["version"]
except KeyError as missing:
raise VersionError(f"Cargo.toml has no workspace.package.version ({missing})") from None
def git(*args: str) -> str:
"""Runs git in the repository and returns its stdout, failing loudly on a bad ref."""
result = subprocess.run(["git", *args], cwd=ROOT, capture_output=True, text=True)
if result.returncode != 0:
raise SystemExit(f"version-check: git {' '.join(args)} failed: {result.stderr.strip()}")
return result.stdout
def problems(base_ref: str) -> list[str]:
"""Everything wrong with the working tree's version against `base_ref`, empty when it is fine."""
head = workspace_version((ROOT / "Cargo.toml").read_text())
base = workspace_version(git("show", f"{base_ref}:Cargo.toml"))
changed = git("diff", "--name-only", f"{base_ref}...HEAD").split()
found = []
if precedence(head) < precedence(base):
found.append(f"the version went down: {base} -> {head}")
elif ships(changed) and not is_one_step(base, head):
found.append(bump_message(base, head))
manifests = {str(p.relative_to(ROOT)): p.read_text() for p in ROOT.glob("crates/*/Cargo.toml")}
found += [f"internal dependency not pinned to {head}: {pin}" for pin in stale_pins(manifests, head)]
changelog = ROOT / "CHANGELOG.md"
if not changelog.exists() or not changelog_has(changelog.read_text(), head):
found.append(f"CHANGELOG.md has no `## [{head}]` section")
return found
def bump_message(base: str, head: str) -> str:
"""Says what a shipped change needed, naming the three versions it could have taken."""
major, minor, patch, _ = parse(base)
options = f"{major}.{minor}.{patch + 1}, {major}.{minor + 1}.0 or {major + 1}.0.0"
if head == base:
return f"this changes what ships but leaves the version at {base}; bump it to {options}"
return f"{base} -> {head} is not one semver step; the next version is {options}"
def main() -> int:
base_ref = sys.argv[1] if len(sys.argv) > 1 else "origin/main"
try:
found = problems(base_ref)
except VersionError as error:
found = [str(error)]
for problem in found:
print(f"version-check: {problem}", file=sys.stderr)
if not found:
print(f"version-check: ok against {base_ref}")
return 1 if found else 0
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,167 @@
#!/usr/bin/env python3
"""Tests for version-check.py. Run: python3 scripts/version_check_test.py"""
import importlib.util
import subprocess
import tempfile
import unittest
from pathlib import Path
from typing import Any
# The script's name has a hyphen, like its neighbors, so it is loaded by path rather than imported
SPEC = importlib.util.spec_from_file_location(
"version_check", Path(__file__).with_name("version-check.py")
)
assert SPEC and SPEC.loader, "version-check.py sits beside this file"
vc: Any = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(vc)
class Precedence(unittest.TestCase):
def test_orders_the_spec_example(self):
ordered = [
"1.0.0-alpha",
"1.0.0-alpha.1",
"1.0.0-alpha.beta",
"1.0.0-beta",
"1.0.0-beta.2",
"1.0.0-beta.11",
"1.0.0-rc.1",
"1.0.0",
"1.0.1",
"1.1.0",
"2.0.0",
]
self.assertEqual(sorted(reversed(ordered), key=vc.precedence), ordered)
def test_build_metadata_carries_no_precedence(self):
self.assertEqual(vc.precedence("1.0.0+build.7"), vc.precedence("1.0.0"))
def test_rejects_what_is_not_semver(self):
for bad in ["1.0", "01.0.0", "v1.0.0", "1.0.0-", "1.0.0-01"]:
with self.subTest(bad), self.assertRaises(vc.VersionError):
vc.parse(bad)
class OneStep(unittest.TestCase):
def test_each_bump_is_one_step(self):
for head in ["0.1.4", "0.2.0", "1.0.0", "0.2.0-rc.1"]:
with self.subTest(head):
self.assertTrue(vc.is_one_step("0.1.3", head))
def test_a_skipped_or_unzeroed_bump_is_not(self):
for head in ["0.1.5", "0.3.0", "0.2.3", "2.0.0", "1.1.0"]:
with self.subTest(head):
self.assertFalse(vc.is_one_step("0.1.3", head))
def test_the_same_version_is_not_a_step(self):
self.assertFalse(vc.is_one_step("0.1.3", "0.1.3"))
self.assertFalse(vc.is_one_step("0.2.0-rc.1", "0.2.0-rc.1"))
def test_a_pre_release_steps_to_its_release_or_a_later_one(self):
self.assertTrue(vc.is_one_step("0.2.0-rc.1", "0.2.0"))
self.assertTrue(vc.is_one_step("0.2.0-rc.1", "0.2.0-rc.2"))
self.assertFalse(vc.is_one_step("0.2.0-rc.2", "0.2.0-rc.1"))
def test_a_release_cannot_step_to_its_own_pre_release(self):
self.assertFalse(vc.is_one_step("0.2.0", "0.2.0-rc.1"))
class Ships(unittest.TestCase):
def test_crates_and_the_root_manifests_ship(self):
for path in ["crates/luxe-core/src/lib.rs", "Cargo.toml", "Cargo.lock"]:
with self.subTest(path):
self.assertTrue(vc.ships([path]))
def test_the_site_docs_and_lookalikes_do_not(self):
for path in ["web/src/pages/index.astro", "docs/guide/index.md", "cratesfoo", "web/Cargo.toml"]:
with self.subTest(path):
self.assertFalse(vc.ships([path]))
class Pins(unittest.TestCase):
def manifest(self, line):
return {"crates/a/Cargo.toml": f"[package]\nname = 'a'\n\n[dependencies]\n{line}\n"}
def test_a_stale_internal_pin_is_named(self):
stale = vc.stale_pins(self.manifest('b = { path = "../b", version = "0.1.0" }'), "0.2.0")
self.assertEqual(stale, ["crates/a/Cargo.toml: b = '0.1.0'"])
def test_a_current_or_exact_pin_passes(self):
for pin in ["0.2.0", "=0.2.0"]:
line = f'b = {{ path = "../b", version = "{pin}" }}'
with self.subTest(pin):
self.assertEqual(vc.stale_pins(self.manifest(line), "0.2.0"), [])
def test_registry_and_unversioned_path_deps_are_not_internal_pins(self):
self.assertEqual(vc.stale_pins(self.manifest('serde = { version = "1" }'), "0.2.0"), [])
self.assertEqual(vc.stale_pins(self.manifest('b = { path = "../b" }'), "0.2.0"), [])
def test_dev_dependencies_are_checked_too(self):
text = '[dev-dependencies]\nb = { path = "../b", version = "0.1.0" }\n'
self.assertEqual(len(vc.stale_pins({"m": text}, "0.2.0")), 1)
class Changelog(unittest.TestCase):
def test_finds_a_bracketed_or_bare_heading(self):
self.assertTrue(vc.changelog_has("# Changelog\n\n## [0.2.0] - 2026-11-01\n", "0.2.0"))
self.assertTrue(vc.changelog_has("## 0.2.0\n", "0.2.0"))
def test_another_version_or_level_does_not_count(self):
self.assertFalse(vc.changelog_has("## [0.2.0-rc.1]\n", "0.2.0"))
self.assertFalse(vc.changelog_has("## [0.2.01]\n", "0.2.0"))
self.assertFalse(vc.changelog_has("### [0.2.0]\n", "0.2.0"))
class AgainstARepository(unittest.TestCase):
"""The git wiring: a real repository, a base branch, and a change on top of it."""
def setUp(self):
self.dir = tempfile.TemporaryDirectory()
self.root = Path(self.dir.name)
self.saved_root, vc.ROOT = vc.ROOT, self.root
self.write_version("0.1.0")
self.write("crates/a/src/lib.rs", "")
self.run_git("init", "-q", "-b", "main")
self.commit("base")
self.run_git("checkout", "-q", "-b", "change")
def tearDown(self):
vc.ROOT = self.saved_root
self.dir.cleanup()
def write(self, path, text):
(self.root / path).parent.mkdir(parents=True, exist_ok=True)
(self.root / path).write_text(text)
def write_version(self, version):
self.write("Cargo.toml", f"[workspace.package]\nversion = '{version}'\n")
self.write("CHANGELOG.md", f"## [{version}]\n")
self.write("crates/a/Cargo.toml", f"[dependencies]\nb = {{ path = '../b', version = '{version}' }}\n")
def run_git(self, *args):
subprocess.run(["git", *args], cwd=self.root, check=True, capture_output=True)
def commit(self, message):
self.run_git("add", "-A")
self.run_git("-c", "user.name=t", "-c", "user.email=t@example.invalid", "commit", "-qm", message)
def test_a_shipped_change_without_a_bump_fails(self):
self.write("crates/a/src/lib.rs", "pub fn new() {}\n")
self.commit("change")
self.assertIn("leaves the version at 0.1.0", " ".join(vc.problems("main")))
def test_a_shipped_change_with_a_bump_passes(self):
self.write("crates/a/src/lib.rs", "pub fn new() {}\n")
self.write_version("0.1.1")
self.commit("change")
self.assertEqual(vc.problems("main"), [])
def test_a_site_change_needs_no_bump(self):
self.write("web/index.html", "<p>hi</p>\n")
self.commit("change")
self.assertEqual(vc.problems("main"), [])
if __name__ == "__main__":
unittest.main()

278
scripts/voice-check.py Executable file
View File

@@ -0,0 +1,278 @@
#!/usr/bin/env python3
"""Check shipped prose against `docs/brand/voice.md`.
Taste that cannot be asserted drifts. This asserts the one part of the voice that a machine can
actually judge: the words the rule bans outright. Everything else in that document — evidence with
claims, naming the trade-off, sentence variance — is a human's call, and pretending otherwise would
produce a checker nobody trusts.
Two severities, because they are different promises:
banned marketing adjectives with no defensible use. Exits non-zero.
review words that are usually filler but sometimes correct English ("just above the prompt").
Reported, never fatal.
Code is not prose: fenced blocks and inline spans are skipped, so a banned word inside a command is
a command. `docs/brand/voice.md` is skipped entirely — it quotes every one of these on purpose.
python3 scripts/voice-check.py # everything shipped
python3 scripts/voice-check.py --review # include the judgement calls
"""
from __future__ import annotations
import argparse
import pathlib
import re
import subprocess
ROOT = pathlib.Path(__file__).resolve().parent.parent
# Lowercase, matched case-insensitively. Proper nouns that collide (Delve, the Go debugger) are
# handled by CASE_SENSITIVE below rather than by dropping the word.
BANNED = [
"leverage",
"delve",
"robust",
"seamless",
"seamlessly",
"intricate",
"pivotal",
"realm",
"effortless",
"effortlessly",
"magical",
"blazingly",
"revolutionary",
"game-changing",
"supercharge",
"supercharged",
"next-generation",
"unleash",
"elevate",
"cutting-edge",
"best-in-class",
"world-class",
"empower",
"utilize",
"plethora",
"myriad",
]
# Words whose *capitalised* form is a name, not an adjective. Only the lowercase use is a finding.
CASE_SENSITIVE = {"delve"}
# Usually filler, sometimes the right word. "Just above the prompt" is a position; "just run it" is
# a shrug at someone's difficulty.
REVIEW = ["simply", "just", "easily", "obviously", "basically"]
# British spellings, and the American ones this project writes.
#
# These are stems, not words: the "colour" entry also catches colours/coloured/colouring. They get a
# wider net than the banned words above, because a reader meets this project's prose in doc comments
# and identifiers as much as on the website, and half-converted spelling reads worse than either
# convention held consistently. None is a legitimate identifier here, so a hit is always a lapse.
#
# The keys are spellings this project does NOT use, which makes this table the one place in the repo
# that must keep them — hence the skip entry for this file below, and the self-check in `spelling()`.
BRITISH = {
"colour": "color",
"behaviour": "behavior",
"neighbour": "neighbor",
"honour": "honor",
"favour": "favor",
"labour": "labor",
"humour": "humor",
"rumour": "rumor",
"labelled": "labeled",
"labelling": "labeling",
"travelling": "traveling",
"emphasise": "emphasize",
"recognise": "recognize",
"serialise": "serialize",
"initialise": "initialize",
"organise": "organize",
"realise": "realize",
"analyse": "analyze",
"prioritise": "prioritize",
"summarise": "summarize",
"normalise": "normalize",
"customise": "customize",
"minimise": "minimize",
"maximise": "maximize",
"specialise": "specialize",
"synchronise": "synchronize",
"centre": "center",
"theatre": "theater",
"licence": "license",
"defence": "defense",
"grey": "gray",
"storey": "story",
"catalogue": "catalog",
"artefact": "artifact",
"sceptical": "skeptical",
"calibre": "caliber",
"fibre": "fiber",
"lustre": "luster",
"whilst": "while",
"amongst": "among",
"learnt": "learned",
"spelt": "spelled",
}
# Text we did not write, plus this file — which contains every banned spelling by definition, the
# same reason `docs/brand/voice.md` is skipped above. Lockfiles are resolver output and can name a
# real package `@img/color`; upstream license grants keep whatever spelling they shipped with. The
# GitHub fixtures are GitHub's own answers, saved verbatim, with strangers' titles in them.
SPELLING_SKIP = (
".pi/",
"crates/luxe-core/src/github/fixtures/",
"web/public/fonts/",
"web/src/assets/generated/",
"node_modules/",
"scripts/voice-check.py",
)
SPELLING_SKIP_EXT = (
".lock",
"-lock.json",
".png",
".jpg",
".jpeg",
".svg",
".cast",
".woff2",
".woff",
".ico",
".webp",
)
# Prose that ships. The planning docs and the journal are development-only and write for a different
# reader; holding them to the product's voice would be a category error.
INCLUDE = ["README.md", "docs/guide/*.md", "web/src/**/*.astro", "web/src/**/*.svelte"]
SKIP = {"docs/brand/voice.md"}
def prose(text: str) -> str:
"""The document with code and quoted words removed, line count preserved.
Two things are not the author using a word. **Code** — a banned word inside a command is a
command. And a word set in **emphasis on its own**, which is how both the voice document and the
page describing it point at the words to avoid: those are mentioning the word, not using it.
"""
def blank(match: re.Match[str]) -> str:
return "\n" * match.group(0).count("\n")
text = re.sub(r"```.*?```", blank, text, flags=re.S)
text = re.sub(r"`[^`\n]*`", "", text)
return re.sub(r"(?<!\*)\*([A-Za-z][A-Za-z -]{0,24})\*(?!\*)", "", text)
def findings(
path: pathlib.Path, words: list[str], case_sensitive: set[str]
) -> list[str]:
text = prose(path.read_text(encoding="utf-8", errors="replace"))
lines = text.split("\n")
found = []
for word in words:
flags = 0 if word in case_sensitive else re.IGNORECASE
for match in re.finditer(rf"\b{re.escape(word)}\b", text, flags):
number = text[: match.start()].count("\n")
found.append(
f"{path.relative_to(ROOT)}:{number + 1} {word} \u2014 {lines[number].strip()[:88]}"
)
return found
def spelling() -> list[str]:
"""Every British spelling in text this project actually wrote.
Deliberately a raw substring scan over the whole tree rather than the prose-only extraction the
banned words get: an identifier spelled `honors_ignore_files` is as much a lapse as a sentence
that says it, and none of these stems has a defensible use here.
"""
# A blanket search-and-replace over the repo will happily rewrite the table above into
# `{"color": "color", ...}`, after which every correct word matches and the checker condemns the
# very spelling it exists to enforce. Ask for that mistake out loud rather than acting on it.
flattened = sorted(k for k, v in BRITISH.items() if k == v)
if flattened:
raise SystemExit(
f"voice-check: BRITISH maps {flattened[0]!r} to itself — the table was rewritten by a "
"spelling pass and no longer distinguishes the two conventions."
)
listing = subprocess.run(
["git", "ls-files", "--cached", "--others", "--exclude-standard"],
capture_output=True,
text=True,
cwd=ROOT,
).stdout.split()
pattern = re.compile(
"|".join(sorted(BRITISH, key=len, reverse=True)), re.IGNORECASE
)
found = []
for name in listing:
if name.startswith(SPELLING_SKIP) or name.endswith(SPELLING_SKIP_EXT):
continue
try:
text = (ROOT / name).read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
for match in pattern.finditer(text):
number = text[: match.start()].count("\n")
word = match.group(0)
line = text.split("\n")[number].strip()[:76]
found.append(
f"{name}:{number + 1} {word} \u2192 {BRITISH[word.lower()]} \u2014 {line}"
)
return found
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument(
"--review", action="store_true", help="also report the judgement calls"
)
args = parser.parse_args()
paths = sorted(
{
p
for pattern in INCLUDE
for p in ROOT.glob(pattern)
if str(p.relative_to(ROOT)) not in SKIP
}
)
banned = [f for p in paths for f in findings(p, BANNED, CASE_SENSITIVE)]
print(f"voice check \u2014 {len(paths)} files")
if banned:
print(f"\n{len(banned)} banned word(s):")
for line in banned:
print(f" {line}")
else:
print(" no banned words")
british = spelling()
if british:
print(f"\n{len(british)} British spelling(s):")
for line in british:
print(f" {line}")
else:
print(" no British spellings")
if args.review:
soft = [f for p in paths for f in findings(p, REVIEW, set())]
print(
f"\n{len(soft)} for review (never fatal \u2014 most are correct English):"
)
for line in soft:
print(f" {line}")
return 1 if banned or british else 0
if __name__ == "__main__":
raise SystemExit(main())

169
scripts/win-check.sh Executable file
View File

@@ -0,0 +1,169 @@
#!/usr/bin/env bash
# Build and run the whole suite for Windows, from Linux, in about twenty seconds.
#
# CI's `windows-latest` job is the authority, but it is a thirteen-minute round trip and it lies by
# omission: GitHub's image puts Git-for-Windows' `usr/bin` on `PATH`, so `sh`, `bash` and `grep` are
# all present there and none of the "there is no POSIX shell" failures ever surface. A default Git
# for Windows install puts only `Git\cmd` on `PATH` — `git.exe` and nothing else.
#
# So this runs the *stricter* environment: cross-compile with clang-cl (`cargo-xwin` fetches the MSVC
# CRT and Windows SDK headers), execute under wine, and hand it MinGit and nothing more. What passes
# here passes on a real Windows box; what CI reports green may still be broken there.
#
# Wine is an approximation, not Windows. It gets `FlushFileBuffers`, path semantics, `PATH` order and
# process spawning right, which is where our bugs live; it does not get ACLs, antivirus, or console
# rendering right. Treat a green run here as "worth pushing", never as "shipped".
#
# Requires: clang-cl + lld-link + llvm-lib (Arch: clang lld), wine, cargo-xwin
# (`cargo install cargo-xwin`), cargo-nextest.
#
# Usage:
# scripts/win-check.sh [options] [-- <extra nextest args>]
#
# Options:
# --no-git don't set up MinGit (the git-backed tests will fail; useful for isolating)
# --setup fetch MinGit and prime the wine prefix, then exit
# --clippy run clippy for the Windows target instead of the tests
# --build build only
# -h, --help this text
#
# Examples:
# scripts/win-check.sh
# scripts/win-check.sh -- -p luxe-tools -E 'test(glob)'
set -euo pipefail
TARGET=x86_64-pc-windows-msvc
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# 19 GB of Windows objects: keep them on real disk, not on a tmpfs /tmp.
WIN_TARGET_DIR="$ROOT/target/win"
MINGIT_DIR="${LUXE_MINGIT_DIR:-$ROOT/target/win-mingit}"
MINGIT_VERSION="${LUXE_MINGIT_VERSION:-2.51.0}"
MINGIT_URL="https://github.com/git-for-windows/git/releases/download/v${MINGIT_VERSION}.windows.1/MinGit-${MINGIT_VERSION}-64-bit.zip"
mode=test
want_git=1
extra=()
while [[ $# -gt 0 ]]; do
case "$1" in
--no-git)
want_git=0
shift
;;
--setup)
mode=setup
shift
;;
--clippy)
mode=clippy
shift
;;
--build)
mode=build
shift
;;
-h | --help)
# The header comment IS the help text, so read it rather than hardcoding a line range —
# which silently truncated the moment a paragraph was added above it.
awk 'NR > 1 && /^#/ { sub(/^# ?/, ""); print; next } NR > 1 { exit }' "${BASH_SOURCE[0]}"
exit 0
;;
--)
shift
extra=("$@")
break
;;
*)
echo "unknown option: $1 (see --help)" >&2
exit 2
;;
esac
done
have() { command -v "$1" >/dev/null 2>&1; }
missing=()
for tool in clang-cl lld-link llvm-lib wine cargo; do
have "$tool" || missing+=("$tool")
done
have cargo-xwin || cargo xwin --version >/dev/null 2>&1 || missing+=("cargo-xwin (cargo install cargo-xwin)")
if [[ ${#missing[@]} -gt 0 ]]; then
printf 'missing: %s\n' "${missing[*]}" >&2
exit 1
fi
# The Windows standard library, which is the prerequisite nothing else checks for. Without it the
# build fails hundreds of crates deep with `can't find crate for core`, whose own suggestion is to
# run a command that a distribution's Rust package does not have. Say the useful thing instead.
if have rustup; then
if ! rustup target list --installed 2>/dev/null | grep -qx "$TARGET"; then
cat >&2 <<-EOF
missing: the $TARGET standard library
rustup target add $TARGET
If mise manages your Rust, declare it instead so a toolchain update keeps it:
rust = { version = "stable", targets = ["$TARGET"] }
EOF
exit 1
fi
else
# No rustup at all: a distribution package ships one target and cannot add another, so the
# build below is going to fail and the reason will not be obvious from its output.
cat >&2 <<-EOF
missing: rustup, which is the only way to install the $TARGET standard library
A distribution's \`rust\` package ships one target and no way to add another.
mise use -g rust@stable # mise manages rustup underneath
# or: https://rustup.rs
EOF
exit 1
fi
# MinGit, unzipped. Only `cmd/` goes on the wine PATH: that is what the Git for Windows installer
# adds by default, and the whole point is to *not* hand ourselves the unix tools a real user lacks.
setup_mingit() {
# `-f`, not `-x`: the archive carries no unix modes, so nothing unpacks executable.
if [[ -f "$MINGIT_DIR/cmd/git.exe" ]]; then
return
fi
echo "fetching MinGit $MINGIT_VERSION -> $MINGIT_DIR"
mkdir -p "$MINGIT_DIR"
local zip="$MINGIT_DIR/../mingit.zip"
curl -fsSL -o "$zip" "$MINGIT_URL"
(cd "$MINGIT_DIR" && unzip -q -o "$zip")
rm -f "$zip"
[[ -f "$MINGIT_DIR/cmd/git.exe" ]] || {
echo "MinGit unpacked but git.exe is missing" >&2
exit 1
}
}
if [[ $want_git -eq 1 ]]; then
setup_mingit
fi
cd "$ROOT"
# `cargo xwin env` exports the clang-cl/lld-link toolchain *and* sets the target runner to wine, so
# `cargo nextest run --target …` just works from here.
eval "$(cargo xwin env --target "$TARGET")"
export CARGO_TARGET_DIR="$WIN_TARGET_DIR"
export WINEDEBUG="${WINEDEBUG:--all}"
export WINEPREFIX="${WINEPREFIX:-$HOME/.wine-luxe}"
# NOTE: wine initializes a display driver even for console programs, and on a GPU whose mesa build
# can't answer its EGL probe it prints a handful of `libEGL warning:` lines into the captured stderr
# of every test. Cosmetic — ignore them; they are wine's, not ours.
if [[ $want_git -eq 1 ]]; then
export WINEPATH="$MINGIT_DIR/cmd"
fi
case "$mode" in
setup)
# A cold prefix prints its first-run noise into whatever runs next; get it over with.
wine cmd /c ver >/dev/null 2>&1 || true
echo "wine prefix: $WINEPREFIX"
echo "mingit: ${WINEPATH:-<none>}"
;;
build) cargo build --workspace --all-targets --target "$TARGET" "${extra[@]}" ;;
clippy) cargo clippy --workspace --all-targets --target "$TARGET" "${extra[@]}" -- -D warnings ;;
test) cargo nextest run --workspace --target "$TARGET" --no-fail-fast "${extra[@]}" ;;
esac