code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/flux_bootstrap/bundled/scripts/flux_status.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Render a colorized /flux/status panel for the terminal.
+
+This is the code-puppy equivalent of Wibey's native `ui-mode: flux-status`
+renderer. Wibey draws an interactive Ink overlay; code-puppy can't host an
+interactive UI, so this script prints a static but fully-colored panel.
+
+Data model (all under ~/.flux/<flattened-cwd>/):
+  todo/*.md                 -> frontmatter `stage` + `status`
+  done/<timestamp>/*.md     -> completed tasks, grouped by run timestamp
+  review/<severity>/*.md    -> severity is the folder name
+
+Usage:
+  flux_status.py [--base DIR] [--sections todo,done,review] [--no-color]
+
+If --base is omitted, the flux base is derived from the current working
+directory exactly the way the //flux commands do it (every run of
+non-alphanumeric chars in the absolute path becomes a single hyphen).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+# --- ANSI palette -----------------------------------------------------------
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+MAGENTA = "\033[1;35m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+RED = "\033[31m"
+ORANGE = "\033[38;5;208m"
+TEAL = "\033[38;5;43m"
+GREY = "\033[90m"
+WHITE = "\033[1;37m"
+
+# --- glyphs (escaped so emoji-stripping file writers leave them intact) -----
+FRAKTUR_F = "\U0001d571"  # mathematical bold fraktur capital F
+ICON_PROGRESS = "\U0001f504"  # clockwise arrows
+ICON_DONE = "\u2705"  # white heavy check mark on green
+ICON_REWORK = "\U0001f501"  # repeat
+DOT = "\u25cf"  # solid circle
+
+STATUS_STYLE = {
+    "in-progress": (ICON_PROGRESS, ORANGE),
+    "needs-rework": (ICON_REWORK, RED),
+    "done": (ICON_DONE, GREEN),
+    "completed": (ICON_DONE, GREEN),
+}
+
+SEVERITIES = ("critical", "high", "medium", "low")
+SEVERITY_COLOR = {
+    "critical": RED,
+    "high": ORANGE,
+    "medium": TEAL,
+    "low": GREEN,
+}
+# column header label -> fixed display width for the review grid
+SEV_COL_WIDTH = {"critical": 10, "high": 6, "medium": 8, "low": 5}
+
+# Panel layout constants (named so a column-width tweak can't silently break
+# the header/rule alignment).
+_SECTION_PAD = 18  # extra width added to name_w + stage_w for section rules
+_MIN_PANEL_W = 48  # floor so short content still frames nicely
+
+
+class Theme:
+    """Wraps color usage so --no-color collapses every code to ''."""
+
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def __call__(self, code: str, text: str) -> str:
+        if not self.enabled:
+            return text
+        return f"{code}{text}{RESET}"
+
+
+def flatten_cwd(cwd: str) -> str:
+    """Replace runs of non-alphanumerics with single hyphens (flux convention)."""
+    return re.sub(r"[^a-zA-Z0-9]+", "-", cwd)
+
+
+def derive_base(explicit: str | None) -> Path:
+    if explicit:
+        return Path(explicit).expanduser()
+    home = Path.home()
+    return home / ".flux" / flatten_cwd(os.getcwd())
+
+
+def parse_frontmatter(path: Path) -> dict[str, str]:
+    """Read the leading `--- ... ---` YAML-ish block into a flat dict."""
+    data: dict[str, str] = {}
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return data
+    if not text.startswith("---"):
+        return data
+    lines = text.splitlines()
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if ":" in line:
+            key, _, val = line.partition(":")
+            data[key.strip()] = val.strip()
+    return data
+
+
+def status_cell(status: str, theme: Theme) -> str:
+    icon, color = STATUS_STYLE.get(status, ("", GREY))
+    label = theme(color, status) if status else theme(GREY, "(unknown)")
+    return f"{icon}  {label}".strip() if icon else label
+
+
+def rule(width: int, char: str, color: str, theme: Theme) -> str:
+    return theme(color, char * width)
+
+
+def visible_len(name: str) -> int:
+    return len(name)
+
+
+def collect_todos(base: Path) -> list[tuple[str, str, str]]:
+    rows = []
+    todo = base / "todo"
+    if not todo.is_dir():
+        return rows
+    for md in sorted(todo.glob("*.md")):
+        fm = parse_frontmatter(md)
+        rows.append((md.stem, fm.get("stage", ""), fm.get("status", "")))
+    return rows
+
+
+def collect_done(base: Path) -> list[tuple[str, list[tuple[str, str, str]]]]:
+    """Returns [(timestamp_label, [(name, stage, status), ...]), ...]."""
+    groups = []
+    done = base / "done"
+    if not done.is_dir():
+        return groups
+    for ts_dir in sorted(done.iterdir(), reverse=True):
+        if not ts_dir.is_dir():
+            continue
+        rows = []
+        for md in sorted(ts_dir.glob("*.md")):
+            fm = parse_frontmatter(md)
+            rows.append((md.stem, fm.get("stage", ""), fm.get("status", "completed")))
+        if rows:
+            groups.append((format_timestamp(ts_dir.name), rows))
+    return groups
+
+
+def format_timestamp(dirname: str) -> str:
+    """`2026-04-29-16-57` -> `2026-04-29 16:57`; pass through anything odd."""
+    parts = dirname.split("-")
+    if len(parts) == 5:
+        return f"{parts[0]}-{parts[1]}-{parts[2]} {parts[3]}:{parts[4]}"
+    return dirname
+
+
+def collect_reviews(base: Path) -> list[tuple[str, str]]:
+    """Returns [(review_name, severity), ...] ordered critical->low."""
+    out = []
+    review = base / "review"
+    if not review.is_dir():
+        return out
+    for sev in SEVERITIES:
+        sev_dir = review / sev
+        if not sev_dir.is_dir():
+            continue
+        for md in sorted(sev_dir.glob("*.md")):
+            out.append((md.stem, sev))
+    return out
+
+
+def render(base: Path, sections: set[str], theme: Theme) -> str:
+    todos = collect_todos(base) if "todo" in sections else []
+    done_groups = collect_done(base) if "done" in sections else []
+    reviews = collect_reviews(base) if "review" in sections else []
+
+    # column width across everything we will print on the left
+    names = [r[0] for r in todos]
+    names += [r[0] for g in done_groups for r in g[1]]
+    names += [r[0] for r in reviews]
+    name_w = max([visible_len(n) for n in names] + [len("TODO-FILE")]) + 2
+    name_w = min(name_w, 50)
+    stage_w = 8
+    total_w = max(name_w + stage_w + _SECTION_PAD, _MIN_PANEL_W)
+
+    lines: list[str] = []
+    lines.append(theme(MAGENTA, f"{FRAKTUR_F} FLUX STATUS"))
+    lines.append(rule(total_w, "\u2550", MAGENTA, theme))
+    rendered_any = False  # have we emitted a body section yet?
+
+    # --- TODO section -------------------------------------------------------
+    if "todo" in sections:
+        rendered_any = True
+        header = (
+            theme(WHITE, "TODO-FILE".ljust(name_w))
+            + theme(WHITE, "STAGE".ljust(stage_w))
+            + theme(WHITE, "STATUS")
+        )
+        lines.append("")
+        lines.append(header)
+        lines.append(rule(total_w, "\u2500", GREY, theme))
+        if not todos:
+            lines.append(theme(GREY, "(no todos)"))
+        for name, stage, status in todos:
+            lines.append(
+                theme(CYAN, name.ljust(name_w))
+                + stage.ljust(stage_w)
+                + status_cell(status, theme)
+            )
+
+    # --- COMPLETED section --------------------------------------------------
+    if "done" in sections and done_groups:
+        lines.append("")
+        if rendered_any:
+            lines.append(rule(total_w, "\u2550", MAGENTA, theme))
+        rendered_any = True
+        lines.append(theme(MAGENTA, "COMPLETED TASKS"))
+        lines.append("")
+        lines.append(
+            theme(WHITE, "TASK-FILE".ljust(name_w))
+            + theme(WHITE, "STAGE".ljust(stage_w))
+            + theme(WHITE, "STATUS")
+        )
+        for ts_label, rows in done_groups:
+            lines.append(theme(GREY, f"\u2500\u2500 {ts_label} \u2500\u2500"))
+            for name, stage, status in rows:
+                lines.append(
+                    theme(CYAN, name.ljust(name_w))
+                    + stage.ljust(stage_w)
+                    + status_cell(status, theme)
+                )
+
+    # --- REVIEW section -----------------------------------------------------
+    if "review" in sections and reviews:
+        lines.append("")
+        if rendered_any:
+            lines.append(rule(total_w, "\u2550", MAGENTA, theme))
+        rendered_any = True
+        lines.append(theme(ORANGE, "REVIEW TASKS"))
+        lines.append("")
+        # column header
+        head = theme(WHITE, "REVIEW-FILE".ljust(name_w))
+        for sev in SEVERITIES:
+            head += theme(SEVERITY_COLOR[sev], sev.upper().ljust(SEV_COL_WIDTH[sev]))
+        lines.append(head)
+        # Underline width = ACTUAL review columns (name + severities), not total_w,
+        # or the rule drifts short whenever SEV_COL_WIDTH changes.
+        review_w = max(name_w + sum(SEV_COL_WIDTH[s] for s in SEVERITIES), _MIN_PANEL_W)
+        lines.append(rule(review_w, "\u2500", GREY, theme))
+        for name, sev in reviews:
+            row = theme(CYAN, name.ljust(name_w))
+            for col in SEVERITIES:
+                if col == sev:
+                    cell = theme(SEVERITY_COLOR[sev], DOT)
+                    row += cell + " " * (SEV_COL_WIDTH[col] - 1)
+                else:
+                    row += " " * SEV_COL_WIDTH[col]
+            lines.append(row.rstrip())
+
+    lines.append(rule(total_w, "\u2550", MAGENTA, theme))
+    return "\n".join(lines)
+
+
+def force_utf8_stdout() -> None:
+    """Reconfigure stdout to UTF-8 so emoji survive legacy Windows codepages.
+
+    Under the exec runner the env already forces UTF-8 (PYTHONIOENCODING);
+    this covers standalone runs in a cp1252 console, where printing a single
+    emoji or box-drawing glyph would otherwise raise UnicodeEncodeError.
+    Best-effort by design -- these scripts must never crash on an IO quirk.
+    (Duplicated across the flux_* scripts on purpose: each is a standalone,
+    dependency-free file.)
+    """
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    force_utf8_stdout()
+    parser = argparse.ArgumentParser(description="Render /flux/status panel")
+    parser.add_argument("--base", default=None, help="Explicit flux base dir")
+    parser.add_argument(
+        "--sections",
+        default="todo,done,review",
+        help="Comma list of: todo,done,review (default: all)",
+    )
+    parser.add_argument(
+        "sections_pos",
+        nargs="*",
+        default=[],
+        help="Optional positional section filter (todo/done/review); overrides --sections.",
+    )
+    parser.add_argument("--no-color", action="store_true", help="Disable ANSI color")
+    args = parser.parse_args(argv)
+
+    # valid_sections by hand, not argparse `choices=`: choices + nargs='*' rejects the
+    # empty-list default. Validated below after merging both input paths.
+    valid_sections = {"todo", "done", "review"}
+
+    base = derive_base(args.base)
+    # Positional section args (e.g. `flux_status.py todo review`) override
+    # --sections so command-line callers don't need to remember the flag name.
+    if args.sections_pos:
+        sections = {s.strip() for s in args.sections_pos if s.strip()}
+    else:
+        sections = {s.strip() for s in args.sections.split(",") if s.strip()}
+
+    # Validate the resolved set once so a typo via EITHER input path (positional
+    # or --sections) fails loudly instead of silently rendering a blank panel.
+    bad = sorted(sections - valid_sections)
+    if bad:
+        parser.error(
+            f"invalid section(s): {', '.join(bad)} "
+            f"(choose from {', '.join(sorted(valid_sections))})"
+        )
+
+    # The exec runner pipes stdout + injects FORCE_COLOR=1 (see _run_exec_directive), so
+    # color stays on despite isatty()==False. Keep the FORCE_COLOR branch so panels
+    # don't silently go monochrome under the runner.
+    color_on = not args.no_color and (
+        sys.stdout.isatty() or os.environ.get("FORCE_COLOR")
+    )
+    theme = Theme(bool(color_on))
+
+    if not base.exists():
+        print(theme(GREY, f"(no flux state at {base})"))
+        return 0
+
+    print(render(base, sections, theme))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_puppy_core_plugins/flux_bootstrap/installer.py

@@ -0,0 +1,256 @@
+"""Install the bundled Flux command set into ``~/.code_puppy``.
+
+The plugin ships a snapshot of the Flux slash-command suite (markdown command
+files + a couple of ``exec:`` helper scripts) as package data under
+``bundled/``. On a fresh install -- or after code-puppy is upgraded -- we copy
+that payload into the user config dir so ``/flux/...`` commands are available
+out of the box.
+
+Design goals:
+
+* **Idempotent.** Re-running with the same bundled content is a no-op.
+* **Non-destructive.** A file the user has hand-edited is never silently
+  clobbered -- it is backed up to ``<name>.bak`` before the fresh copy lands.
+  We tell "user edited it" from "we wrote it last time" via a manifest of the
+  SHA-256 hashes we installed (``.flux_bootstrap_manifest.json``).
+* **Version-gated.** We only walk the tree when the installed code-puppy
+  version differs from the marker we stored last run, so steady-state startup
+  stays cheap.
+* **Fails closed, never fatal.** Any error is swallowed by the caller; a broken
+  install must not take down the whole app.
+
+The manifest + version marker are dot-files, so they never register as
+slash-commands and stay out of the way of the command loader.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - Windows has no fcntl
+    fcntl = None  # type: ignore[assignment]
+
+# Best-effort cross-process lock so two instances can't both walk/copy the tree during
+# the one-time install window (torn reads, spurious .bak). Dot-file -> loader ignores it.
+LOCK_NAME = ".flux_bootstrap.lock"
+
+# Directory holding the shipped payload (``bundled/commands`` + ``bundled/scripts``).
+BUNDLED_DIR = Path(__file__).parent / "bundled"
+
+# Dot-files live at the root of the config dir so the command loader (which
+# skips ``.``-prefixed namespaces) never picks them up.
+VERSION_MARKER_NAME = ".flux_bootstrap_version"
+MANIFEST_NAME = ".flux_bootstrap_manifest.json"
+
+
+@dataclass
+class InstallReport:
+    """Summary of what an install pass did (handy for logging + tests)."""
+
+    installed: List[str] = field(default_factory=list)
+    updated: List[str] = field(default_factory=list)
+    backed_up: List[str] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.installed or self.updated or self.backed_up)
+
+    def summary(self) -> str:
+        return (
+            f"{len(self.installed)} new, {len(self.updated)} updated, "
+            f"{len(self.backed_up)} backed up, {len(self.skipped)} unchanged"
+        )
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` via a temp file + atomic replace.
+
+    A crash mid-write leaves the previous file intact (or absent) rather than a
+    half-written, corrupt one. ``os.replace`` is atomic on the same filesystem.
+    """
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _write_bytes_preserving_mode(dest: Path, payload: bytes, src: Path) -> None:
+    """Write ``payload`` to ``dest`` atomically and copy ``src``'s mode bits.
+
+    Writes to a temp file, chmods it to match ``src`` (executable/mode metadata
+    on installed scripts so a future direct-exec doesn't lose the +x bit), then
+    atomically replaces ``dest``. A crash mid-write leaves the previous file
+    intact rather than a truncated one -- the same crash-safety the manifest and
+    version marker already get via :func:`_atomic_write_text`. Chmod failures
+    are non-fatal; the content landing is what matters.
+    """
+    tmp = dest.with_name(dest.name + ".tmp")
+    tmp.write_bytes(payload)
+    try:
+        tmp.chmod(stat.S_IMODE(src.stat().st_mode))
+    except OSError:
+        pass
+    os.replace(tmp, dest)
+
+
+def _unique_backup_path(dest: Path) -> Path:
+    """Return a non-colliding ``<name>.bak`` (or ``.bak.1``, ``.bak.2``, ...).
+
+    Successive version bumps against a repeatedly hand-edited file would
+    otherwise clobber the previous backup. Find the first free slot instead.
+    """
+    backup = dest.with_name(dest.name + ".bak")
+    if not backup.exists():
+        return backup
+    i = 1
+    while True:
+        candidate = dest.with_name(f"{dest.name}.bak.{i}")
+        if not candidate.exists():
+            return candidate
+        i += 1
+
+
+def _iter_bundled_files() -> List[Path]:
+    """Every regular file under ``bundled/`` (skipping OS junk)."""
+    if not BUNDLED_DIR.is_dir():
+        return []
+    return sorted(
+        p for p in BUNDLED_DIR.rglob("*") if p.is_file() and p.name != ".DS_Store"
+    )
+
+
+def _load_manifest(config_dir: Path) -> Dict[str, str]:
+    manifest_path = config_dir / MANIFEST_NAME
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_manifest(config_dir: Path, manifest: Dict[str, str]) -> None:
+    manifest_path = config_dir / MANIFEST_NAME
+    _atomic_write_text(manifest_path, json.dumps(manifest, indent=2, sort_keys=True))
+
+
+def read_installed_version(config_dir: Path) -> str | None:
+    """Return the code-puppy version recorded on the last successful install."""
+    marker = config_dir / VERSION_MARKER_NAME
+    try:
+        return marker.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def _write_version(config_dir: Path, version: str) -> None:
+    _atomic_write_text(config_dir / VERSION_MARKER_NAME, version)
+
+
+def needs_install(config_dir: Path, current_version: str) -> bool:
+    """True on a fresh install (no marker) or after a version bump."""
+    return read_installed_version(config_dir) != current_version
+
+
+def _install_pass(config_dir: Path, current_version: str) -> InstallReport:
+    """Copy the bundled payload into ``config_dir`` (the actual work).
+
+    Separated from :func:`install_bundled_commands` so the latter can wrap this
+    in a best-effort cross-process lock without deepening the copy logic.
+    """
+    report = InstallReport()
+    manifest = _load_manifest(config_dir)
+    new_manifest: Dict[str, str] = {}
+
+    for src in _iter_bundled_files():
+        rel = src.relative_to(BUNDLED_DIR).as_posix()
+        dest = config_dir / rel
+        payload = src.read_bytes()
+        payload_hash = _sha256_bytes(payload)
+
+        if not dest.exists():
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            _write_bytes_preserving_mode(dest, payload, src)
+            report.installed.append(rel)
+            new_manifest[rel] = payload_hash
+            continue
+
+        current_hash = _sha256(dest)
+        if current_hash == payload_hash:
+            # Already exactly our payload -- idempotent no-op. Claim it so we
+            # keep ownership across future bumps.
+            report.skipped.append(rel)
+            new_manifest[rel] = payload_hash
+            continue
+
+        # Content differs from what we ship. Two cases:
+        #   1) ``rel not in manifest``: a pre-existing user-owned file with the same
+        #      name — preserve it in place forever (never back up/overwrite/claim it),
+        #      so a fresh install can't stomp the user's own global command.
+        #   2) ``rel in manifest``: ours. Untouched (hash matches) -> overwrite freely;
+        #      otherwise the user hand-edited it -> keep theirs as a unique ``.bak``.
+        if rel not in manifest:
+            report.skipped.append(rel)
+            continue
+
+        if manifest.get(rel) != current_hash:
+            backup = _unique_backup_path(dest)
+            shutil.copy2(dest, backup)
+            report.backed_up.append(backup.relative_to(config_dir).as_posix())
+
+        _write_bytes_preserving_mode(dest, payload, src)
+        report.updated.append(rel)
+        new_manifest[rel] = payload_hash
+
+    _save_manifest(config_dir, new_manifest)
+    _write_version(config_dir, current_version)
+    return report
+
+
+def install_bundled_commands(config_dir: Path, current_version: str) -> InstallReport:
+    """Copy the bundled Flux payload into ``config_dir``.
+
+    ``bundled/commands/...`` -> ``config_dir/commands/...``
+    ``bundled/scripts/...``  -> ``config_dir/scripts/...``
+
+    Returns an :class:`InstallReport`. Writes the version marker + manifest only
+    after a clean pass so a crash mid-install re-runs next time.
+
+    Guarded by a best-effort exclusive ``flock`` on ``.flux_bootstrap.lock``: if
+    another instance already holds it (a concurrent first-launch install), we
+    skip and return an empty report rather than racing. The lock auto-releases
+    when the holding process dies, so a crashed install can't wedge future ones.
+    Where ``fcntl`` is unavailable (Windows), the pass runs unlocked -- the same
+    behavior as before this guard existed.
+    """
+    config_dir = Path(config_dir)
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    if fcntl is None:
+        return _install_pass(config_dir, current_version)
+
+    lock_fd = os.open(config_dir / LOCK_NAME, os.O_CREAT | os.O_WRONLY, 0o644)
+    try:
+        try:
+            fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            # Another process holds the lock -- it's installing; skip.
+            return InstallReport()
+        return _install_pass(config_dir, current_version)
+    finally:
+        os.close(lock_fd)  # releases the flock

code_puppy_core_plugins/flux_bootstrap/register_callbacks.py

@@ -0,0 +1,71 @@
+"""Flux bootstrap plugin.
+
+Installs the bundled Flux slash-command suite into ``~/.code_puppy`` on a fresh
+install and after every code-puppy version bump, so ``/flux/...`` commands work
+out of the box without the user copying anything by hand.
+
+The heavy lifting (copy / backup / version-gating) lives in :mod:`installer`;
+this module only wires it to the ``startup`` hook and makes sure a failure can
+never crash the app.
+"""
+
+from pathlib import Path
+
+from code_puppy.callbacks import register_callback
+from code_puppy.config import CONFIG_DIR
+from code_puppy.messaging import emit_info, emit_warning
+
+from .installer import install_bundled_commands, needs_install
+
+
+def _reload_command_cache() -> None:
+    """Ask the customizable_commands loader to rescan its dirs. Never raises.
+
+    Imported lazily (not at module scope) so a refactor/rename of that plugin
+    can't break flux_bootstrap's own import, and so we don't create a hard
+    load-order dependency between the two plugins.
+    """
+    try:
+        from code_puppy_core_plugins.customizable_commands.register_callbacks import (
+            reload_commands,
+        )
+
+        reload_commands()
+    except Exception as exc:  # a stale cache is not worth crashing over
+        emit_warning(f"Flux installed but command cache reload failed: {exc}")
+
+
+def _current_version() -> str:
+    try:
+        from code_puppy import __version__
+
+        return str(__version__)
+    except Exception:
+        return "0.0.0-dev"
+
+
+def _install_flux_commands() -> None:
+    """Version-gated install of the bundled Flux command set. Never raises."""
+    try:
+        config_dir = Path(CONFIG_DIR)
+        version = _current_version()
+
+        if not needs_install(config_dir, version):
+            return
+
+        report = install_bundled_commands(config_dir, version)
+        if report.changed:
+            emit_info(f"Flux commands installed -> {config_dir} ({report.summary()})")
+            if report.backed_up:
+                emit_warning(
+                    "Backed up locally-modified Flux files (see *.bak): "
+                    + ", ".join(report.backed_up)
+                )
+            # Command cache was populated at import time, before we wrote these files —
+            # rescan so /flux/... dispatches this session instead of after a restart.
+            _reload_command_cache()
+    except Exception as exc:  # never let bootstrap break startup
+        emit_warning(f"Flux bootstrap skipped (install failed): {exc}")
+
+
+register_callback("startup", _install_flux_commands)

code_puppy_core_plugins/force_push_guard/__init__.py

@@ -0,0 +1,5 @@
+"""Force push guard plugin.
+
+Blocks git force push commands and asks for explicit permission before
+allowing them through. Prevents the classic "oops I nuked main" scenario.
+"""