microwave-method 0.1.0__py3-none-any.whl

microwave_method/__init__.py

@@ -0,0 +1,131 @@
+"""microwave-method: `uvx microwave-method` drops Microwave into your repo.
+
+Stdlib only (ADR-007). This is the single install command. It copies the
+framework files into the current repo (additive, never overwrites), seeds the
+wiki, wires the pre-commit hook, then hands you to your coding agent: the
+guided welcome itself is played by the agent (flows/welcome.md), because
+Microwave is a method, not a runtime.
+"""
+from __future__ import annotations
+
+import importlib.resources as resources
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+PAYLOAD_DIRS = ["flows", "templates", "techniques", "slop", "gates",
+                "embodiment", "hooks", "harness"]
+WIKI_SPACES = ["agents", "adr", "projects", "_staging", "_archive"]
+WIKI_INDEX = (
+    "# Registry index\n\n"
+    "One line per artifact: `- [type] id: one-line summary -> path`\n\n"
+    "## Agents\n\n## ADR (meta)\n\n## Projects\n"
+)
+BANNER = "install/banner.txt"
+
+
+def _payload() -> Path:
+    return Path(str(resources.files("microwave_method"))) / "_payload"
+
+
+def _copy_tree(src: Path, dst: Path) -> int:
+    copied = 0
+    if not src.is_dir():
+        return 0
+    for root, _dirs, files in os.walk(src):
+        rel = Path(root).relative_to(src)
+        if "icons" in rel.parts:
+            continue
+        for name in files:
+            out = dst / rel / name
+            if not out.exists():
+                out.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(Path(root) / name, out)
+                copied += 1
+    return copied
+
+
+def _is_git_repo(target: Path) -> bool:
+    try:
+        r = subprocess.run(["git", "-C", str(target), "rev-parse",
+                            "--is-inside-work-tree"],
+                           capture_output=True, text=True)
+        return r.returncode == 0
+    except FileNotFoundError:
+        return False
+
+
+def main() -> None:
+    target = Path(os.environ.get("MICROWAVE_TARGET", os.getcwd())).resolve()
+    payload = _payload()
+
+    banner = payload / "banner.txt"
+    if banner.is_file():
+        print(banner.read_text(encoding="utf-8"))
+
+    print(f"Installing Microwave into {target}")
+    is_repo = _is_git_repo(target)
+    if not is_repo:
+        init = subprocess.run(["git", "-C", str(target), "init"],
+                              capture_output=True, text=True)
+        is_repo = init.returncode == 0
+        print("  initialized a git repo here (the gates need it)." if is_repo
+              else "  could not run git init; install git so the gates can guard it.")
+
+    copied = sum(_copy_tree(payload / d, target / d) for d in PAYLOAD_DIRS)
+
+    gh = target / ".github" / "workflows"
+    gh.mkdir(parents=True, exist_ok=True)
+    ci = gh / "gates.yml"
+    if not ci.exists():
+        shutil.copy2(payload / ".github" / "workflows" / "gates.yml", ci)
+
+    co = target / "CODEOWNERS"
+    if not co.exists():
+        text = (payload / "CODEOWNERS").read_text(encoding="utf-8")
+        co.write_text(text.replace("@microphage-create", "@your-gatekeeper"),
+                      encoding="utf-8", newline="\n")
+
+    wiki = target / "wiki"
+    for space in WIKI_SPACES:
+        (wiki / space).mkdir(parents=True, exist_ok=True)
+    index = wiki / "INDEX.md"
+    if not index.exists():
+        index.write_text(WIKI_INDEX, encoding="utf-8", newline="\n")
+
+    if is_repo:
+        hooks_dir = target / ".git" / "hooks"
+        src_hook = target / "hooks" / "pre-commit"
+        if hooks_dir.is_dir() and src_hook.is_file():
+            dest = hooks_dir / "pre-commit"
+            if not dest.exists():
+                shutil.copy2(src_hook, dest)
+                try:
+                    os.chmod(dest, 0o755)
+                except OSError:
+                    pass
+
+    print(f"\nDone. {copied} files installed.")
+
+    # True one-command experience: hand straight off to the coding agent on the
+    # welcome flow. Launch the detected agent (claude); fall back to printing
+    # the line when none is found or MICROWAVE_NO_LAUNCH=1 (tests, CI).
+    prompt = "run the Microwave welcome flow"
+    agent = shutil.which("claude")
+    if agent and os.environ.get("MICROWAVE_NO_LAUNCH") != "1":
+        print("\nStarting your agent on the welcome flow...\n")
+        try:
+            subprocess.run([agent, prompt], cwd=str(target))
+        except OSError as exc:
+            print(f"(could not launch the agent: {exc})")
+            print(f"Open your coding agent here and say: {prompt}")
+    else:
+        print("\nOne line to start: open your coding agent here and say\n")
+        print(f"    {prompt}\n")
+        print("It adapts to you, scans what you already have, and brings in your")
+        print("first agent. Nothing changes until you say so.")
+
+
+if __name__ == "__main__":
+    main()

microwave_method/_payload/.github/workflows/gates.yml

@@ -0,0 +1,34 @@
+name: gates
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Wiki integrity
+        run: python gates/gate_wiki.py
+      - name: Anti-slop sweep
+        run: python gates/gate_slop.py
+      - name: Generated docs are fresh
+        run: python gates/gate_docs.py
+      - name: All agent cards (active and staged)
+        run: |
+          set -e
+          found=0
+          for card in wiki/agents/*.md wiki/_staging/*.md; do
+            [ -e "$card" ] || continue
+            case "$card" in *README.md) continue;; esac
+            found=1
+            python gates/run_gates.py "$card"
+          done
+          [ "$found" = "1" ] || echo "no agent cards yet"

microwave_method/_payload/CODEOWNERS

@@ -0,0 +1,10 @@
+# The gatekeeper owns the protected space: no change to the rules, the flows,
+# or the meta wiki merges without their review (pair with branch protection,
+# see docs/governance.md "Repo layer").
+/gates/        @microphage-create
+/flows/        @microphage-create
+/hooks/        @microphage-create
+/harness/      @microphage-create
+/wiki/adr/     @microphage-create
+/.github/      @microphage-create
+/CODEOWNERS    @microphage-create

microwave_method/_payload/banner.txt

@@ -0,0 +1,10 @@
+  +------------------------+
+  |  +------------------+  |
+  |  |                  |  |   M I C R O W A V E
+  |  |  ~   ~   ~   ~   |  |
+  |  |    ~   ~   ~     |  |   an agent factory
+  |  |  ~   ~   ~   ~   |  |   with a governed memory
+  |  |                  |  |
+  |  +------------------+  |   context cooked once,
+  |                 (o)    |   reheated at cache price
+  +------------------------+

microwave_method/_payload/embodiment/adapters/linux.py

@@ -0,0 +1,78 @@
+"""Linux adapter: freedesktop .desktop entry + icon, terminal auto-detected.
+
+Supported terminals: kitty, wezterm, gnome-terminal; generic fallback via
+$TERMINAL. The PNG icon is used natively (no conversion needed).
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+APPS = Path.home() / ".local/share/applications"
+ICONS = Path.home() / ".local/share/icons"
+
+
+def _terminal_cmd(ident) -> str:
+    """Exec= lines get no shell expansion (freedesktop spec), so only
+    concrete binaries found on PATH are usable; $TERMINAL would be run
+    literally and can never work."""
+    launch = ident.launch or "exec $SHELL"
+    inner = f"cd '{ident.repo}' && {launch}"
+    if shutil.which("kitty"):
+        return f"kitty --title '{ident.name}' bash -lc \"{inner}\""
+    if shutil.which("wezterm"):
+        return f"wezterm start -- bash -lc \"{inner}\""
+    if shutil.which("gnome-terminal"):
+        return f"gnome-terminal --title='{ident.name}' -- bash -lc \"{inner}\""
+    for candidate in ("x-terminal-emulator", "xdg-terminal-exec", "konsole", "xterm"):
+        if shutil.which(candidate):
+            return f"{candidate} -e bash -lc \"{inner}\""
+    raise RuntimeError(
+        "no known terminal found (kitty, wezterm, gnome-terminal, "
+        "x-terminal-emulator, xdg-terminal-exec, konsole, xterm): "
+        "install one or open an issue naming yours")
+
+
+def apply(ident, dry_run: bool = False) -> None:
+    ident.png_bytes()  # same icon contract as the other adapters
+    desktop_file = APPS / f"microwave-{ident.slug}.desktop"
+    icon_dst = ICONS / f"microwave-{ident.slug}.png"
+    entry = (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        f"Name={ident.name}\n"
+        f"Comment=Microwave agent: {ident.slug}\n"
+        f"Exec={_terminal_cmd(ident)}\n"
+        f"Icon={icon_dst}\n"
+        "Terminal=false\n"
+        "Categories=Development;\n"
+    )
+    if dry_run:
+        print(f"[linux] would write {desktop_file} and {icon_dst}")
+        return
+    APPS.mkdir(parents=True, exist_ok=True)
+    ICONS.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(ident.icon_src, icon_dst)
+    desktop_file.write_text(entry, encoding="utf-8")
+    desktop_file.chmod(0o755)
+    desktop_dir = Path.home() / "Desktop"
+    if desktop_dir.is_dir():
+        desktop_copy = desktop_dir / desktop_file.name
+        shutil.copyfile(desktop_file, desktop_copy)
+        desktop_copy.chmod(0o755)
+    print(f"[linux] desktop entry: {desktop_file}")
+
+
+def remove(ident, dry_run: bool = False) -> None:
+    targets = [
+        APPS / f"microwave-{ident.slug}.desktop",
+        ICONS / f"microwave-{ident.slug}.png",
+        Path.home() / "Desktop" / f"microwave-{ident.slug}.desktop",
+    ]
+    if dry_run:
+        print("[linux] would remove: " + ", ".join(str(t) for t in targets))
+        return
+    for t in targets:
+        if t.exists():
+            t.unlink()
+    print("[linux] removed")

microwave_method/_payload/embodiment/adapters/macos.py

@@ -0,0 +1,109 @@
+"""macOS adapter: iTerm2 Dynamic Profile (additive, zero-risk) + minimal
+.app bundle launcher with .icns, so the agent exists in Dock/Spotlight.
+
+Falls back to Terminal.app in the launcher script when iTerm2 is absent.
+"""
+from __future__ import annotations
+
+import json
+import plistlib
+import shlex
+import shutil
+import stat
+from pathlib import Path
+
+DYNAMIC = Path.home() / "Library/Application Support/iTerm2/DynamicProfiles"
+APPS = Path.home() / "Applications"
+
+
+def _hexpair(c: str) -> dict:
+    r, g, b = (int(c.lstrip("#")[i:i + 2], 16) / 255 for i in (0, 2, 4))
+    return {"Red Component": r, "Green Component": g, "Blue Component": b}
+
+
+def _dynamic_profile(ident) -> dict:
+    launch = ident.launch or ""
+    cmd = f"cd '{ident.repo}'" + (f" && {launch}" if launch else "; exec $SHELL")
+    return {"Profiles": [{
+        "Name": ident.name,
+        "Guid": ident.guid,
+        "Custom Command": "Yes",
+        "Command": f"/bin/zsh -lc \"{cmd}\"",
+        "Background Color": _hexpair(ident.bg),
+        "Foreground Color": _hexpair(ident.fg),
+        "Cursor Color": _hexpair(ident.accent),
+        "Badge Text": ident.name,
+    }]}
+
+
+def _bundle(ident, icns: Path) -> Path:
+    app = APPS / f"{ident.name}.app"
+    macos_dir = app / "Contents/MacOS"
+    res_dir = app / "Contents/Resources"
+    macos_dir.mkdir(parents=True, exist_ok=True)
+    res_dir.mkdir(parents=True, exist_ok=True)
+    plistlib.dump({
+        "CFBundleName": ident.name,
+        "CFBundleIdentifier": f"dev.microwave.{ident.slug}",
+        "CFBundleExecutable": "run",
+        "CFBundleIconFile": "icon.icns",
+        "CFBundlePackageType": "APPL",
+    }, (app / "Contents/Info.plist").open("wb"))
+    shutil.copyfile(icns, res_dir / "icon.icns")
+
+    # Fallback launch script for Terminal.app: a plain .command file, so no
+    # nested AppleScript quoting is ever needed.
+    launch = ident.launch or "exec $SHELL"
+    command_file = res_dir / "launch.command"
+    command_file.write_text(f"#!/bin/zsh\ncd {shlex.quote(str(ident.repo))}\n{launch}\n",
+                            encoding="utf-8")
+    command_file.chmod(command_file.stat().st_mode | stat.S_IEXEC)
+
+    runner = macos_dir / "run"
+    runner.write_text(app_script(ident, command_file), encoding="utf-8")
+    runner.chmod(runner.stat().st_mode | stat.S_IEXEC)
+    return app
+
+
+def app_script(ident, command_file: Path) -> str:
+    # ident.name is constrained by gate_schema (letters, digits, space, _.-):
+    # safe inside AppleScript double quotes. The Terminal fallback opens the
+    # .command file instead of inlining any shell string.
+    return f"""#!/bin/zsh
+# Launcher for agent '{ident.name}': open its themed terminal profile.
+if [ -d "/Applications/iTerm.app" ]; then
+  osascript -e 'tell application "iTerm" to create window with profile "{ident.name}"' \\
+            -e 'tell application "iTerm" to activate'
+else
+  open -b com.apple.Terminal {shlex.quote(str(command_file))}
+fi
+"""
+
+
+def apply(ident, dry_run: bool = False) -> None:
+    profile_path = DYNAMIC / f"microwave-{ident.slug}.json"
+    if dry_run:
+        ident.png_bytes()  # validate the icon source, write nothing
+        print(f"[macos] would write dynamic profile {profile_path}")
+        print(f"[macos] would create {APPS / (ident.name + '.app')}")
+        return
+    icns = ident.write_icns()
+    DYNAMIC.mkdir(parents=True, exist_ok=True)
+    profile_path.write_text(json.dumps(_dynamic_profile(ident), indent=2),
+                            encoding="utf-8")
+    print(f"[macos] iTerm2 dynamic profile: {profile_path}")
+    app = _bundle(ident, icns)
+    print(f"[macos] launcher bundle: {app}")
+
+
+def remove(ident, dry_run: bool = False) -> None:
+    profile_path = DYNAMIC / f"microwave-{ident.slug}.json"
+    app = APPS / f"{ident.name}.app"
+    if dry_run:
+        print(f"[macos] would remove {profile_path} and {app}")
+        return
+    if profile_path.exists():
+        profile_path.unlink()
+    if app.exists():
+        shutil.rmtree(app)
+    print("[macos] removed")

microwave_method/_payload/embodiment/adapters/windows.py

@@ -0,0 +1,152 @@
+"""Windows adapter: Windows Terminal profile + color scheme + desktop .lnk.
+
+Additive and idempotent. Timestamped backup of settings.json before any edit.
+Override the settings path with the MICROWAVE_WT_SETTINGS env var if needed.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+WT_SETTINGS = Path(os.environ.get(
+    "MICROWAVE_WT_SETTINGS",
+    Path(os.environ.get("LOCALAPPDATA", "")) /
+    "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json",
+))
+
+
+def _strip_jsonc(text: str) -> str:
+    """Windows Terminal ships settings.json as JSONC: strip // and /* */
+    comments (outside strings) and trailing commas so json can parse it.
+    Comments are NOT preserved on rewrite; the timestamped backup keeps the
+    original."""
+    out, i, in_str, esc = [], 0, False, False
+    while i < len(text):
+        ch = text[i]
+        if in_str:
+            out.append(ch)
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+            i += 1
+            continue
+        if ch == '"':
+            in_str, esc = True, False
+            out.append(ch)
+            i += 1
+        elif text.startswith("//", i):
+            i = text.find("\n", i)
+            i = len(text) if i == -1 else i
+        elif text.startswith("/*", i):
+            j = text.find("*/", i + 2)
+            i = len(text) if j == -1 else j + 2
+        else:
+            out.append(ch)
+            i += 1
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
+
+
+def _load() -> dict:
+    if not WT_SETTINGS.exists():
+        raise RuntimeError(f"Windows Terminal settings not found: {WT_SETTINGS} "
+                           f"(set MICROWAVE_WT_SETTINGS to override)")
+    raw = WT_SETTINGS.read_text(encoding="utf-8-sig")
+    try:
+        data = json.loads(_strip_jsonc(raw))
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"cannot parse {WT_SETTINGS}: {e}. "
+                           f"Fix the file or point MICROWAVE_WT_SETTINGS elsewhere.")
+    profiles = data.get("profiles")
+    if isinstance(profiles, list):  # legacy schema: profiles was a bare list
+        data["profiles"] = {"list": profiles}
+    return data
+
+
+def _save(data: dict) -> Path:
+    bak = WT_SETTINGS.with_name(WT_SETTINGS.name + ".bak." + str(int(time.time())))
+    shutil.copyfile(WT_SETTINGS, bak)
+    WT_SETTINGS.write_text(json.dumps(data, indent=4, ensure_ascii=False),
+                           encoding="utf-8")
+    return bak
+
+
+def _psq(s: object) -> str:
+    """Escape for a PowerShell single-quoted string ('' = literal ')."""
+    return str(s).replace("'", "''")
+
+
+def _profile(ident, ico: Path) -> dict:
+    launch = ident.launch or ""
+    inner = f"cd '{_psq(ident.repo)}'" + (f"; {launch}" if launch else "")
+    return {
+        "name": ident.name,
+        "guid": "{" + ident.guid + "}",
+        "colorScheme": ident.name,
+        "icon": str(ico),
+        "cursorShape": "bar",
+        "commandline": f"pwsh.exe -NoExit -Command \"{inner}\"",
+    }
+
+
+def _desktop_lnk(ident, ico: Path) -> Path:
+    # ident.name is revalidated by Identity (no quotes); everything else is
+    # escaped anyway: defense in depth.
+    lnk = Path.home() / "Desktop" / f"{ident.name}.lnk"
+    ps = (
+        f"$s=(New-Object -ComObject WScript.Shell).CreateShortcut('{_psq(lnk)}');"
+        f"$s.TargetPath='wt.exe';"
+        f"$s.Arguments='-p \"{_psq(ident.name)}\"';"
+        f"$s.IconLocation='{_psq(ico)}';"
+        f"$s.Save()"
+    )
+    subprocess.run(["powershell", "-NoProfile", "-Command", ps], check=True)
+    return lnk
+
+
+def apply(ident, dry_run: bool = False) -> None:
+    if dry_run:
+        ident.png_bytes()  # validate the icon source, write nothing
+        print(f"[windows] would write {ident.build_dir / (ident.slug + '.ico')}")
+        print(f"[windows] would add scheme+profile '{ident.name}' to {WT_SETTINGS}")
+        print(f"[windows] would create desktop shortcut '{ident.name}.lnk'")
+        return
+
+    ico = ident.write_ico()
+    scheme = ident.scheme()
+    profile = _profile(ident, ico)
+
+    data = _load()
+    schemes = data.setdefault("schemes", [])
+    schemes[:] = [s for s in schemes if s.get("name") != scheme["name"]]
+    schemes.append(scheme)
+    plist = data.setdefault("profiles", {}).setdefault("list", [])
+    plist[:] = [p for p in plist if p.get("guid") != profile["guid"]]
+    plist.append(profile)
+    bak = _save(data)
+    print(f"[windows] scheme+profile '{ident.name}' written (backup: {bak.name})")
+
+    lnk = _desktop_lnk(ident, ico)
+    print(f"[windows] desktop shortcut: {lnk}")
+
+
+def remove(ident, dry_run: bool = False) -> None:
+    if dry_run:
+        print(f"[windows] would remove scheme/profile/shortcut '{ident.name}'")
+        return
+    data = _load()
+    data["schemes"] = [s for s in data.get("schemes", []) if s.get("name") != ident.name]
+    plist = data.get("profiles", {}).get("list", [])
+    plist[:] = [p for p in plist if p.get("guid") != "{" + ident.guid + "}"]
+    bak = _save(data)
+    lnk = Path.home() / "Desktop" / f"{ident.name}.lnk"
+    if lnk.exists():
+        lnk.unlink()
+    print(f"[windows] removed (backup: {bak.name})")