@trolleroof/tui 0.2.3

package/scripts/materialize-agents-plugin.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_DIR="$ROOT_DIR/.agents/plugins/tui-gamepigeon"
+MARKER="Generated by tui-gamepigeon scripts/materialize-agents-plugin.sh"
+
+printf -v overlay_cmd 'bun %q' "$ROOT_DIR/scripts/overlay.ts"
+printf -v launcher_command 'bun %q --enable' "$ROOT_DIR/scripts/overlay.ts"
+
+mkdir -p "$PLUGIN_DIR"
+rm -f "$PLUGIN_DIR/plugin.json" "$PLUGIN_DIR/hooks.json" "$PLUGIN_DIR/skills"
+mkdir -p "$PLUGIN_DIR/skills/arcade"
+install -m 644 "$ROOT_DIR/.codex-plugin/plugin.json" "$PLUGIN_DIR/plugin.json"
+
+cat > "$ROOT_DIR/.agents/plugins/marketplace.json" <<EOF
+{
+  "name": "tui-gamepigeon-dev",
+  "interface": {
+    "displayName": "GamePigeon (local checkout)"
+  },
+  "plugins": [
+    {
+      "name": "tui-gamepigeon",
+      "source": {
+        "source": "local",
+        "path": "./.agents/plugins/tui-gamepigeon"
+      },
+      "policy": {
+        "installation": "AVAILABLE"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}
+EOF
+
+cat > "$PLUGIN_DIR/skills/arcade/SKILL.md" <<EOF
+---
+name: arcade
+description: Open or restore the native GamePigeon HTML overlay while the coding harness works.
+---
+
+# Arcade
+
+<!-- $MARKER -->
+
+Execute this command exactly once:
+
+\`$launcher_command\`
+
+Do not inspect the user's repository. Do not spawn another agent or task. Do not run any other command.
+
+GamePigeon opens as a borderless HTML overlay without a Dock or taskbar entry. Running Arcade again focuses the existing overlay.
+
+On success, respond only with \`Arcade opened.\`. On failure, relay the launcher's error without attempting another launch method.
+EOF
+
+cat > "$PLUGIN_DIR/hooks.json" <<EOF
+{
+  "tui-gamepigeon": {
+    "enabled": true,
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "$overlay_cmd --reset"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "$overlay_cmd --show"
+      }
+    ],
+    "SessionEnd": [
+      {
+        "type": "command",
+        "command": "$overlay_cmd --quit"
+      }
+    ]
+  }
+}
+EOF
+
+echo "Materialized Codex/Antigravity workspace plugin at $PLUGIN_DIR"

package/scripts/overlay.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  applyOverlayLease,
+  managedBinaryPath,
+  overlayBinaryCandidates,
+  overlayReleaseAsset,
+  parseAction,
+  readReleaseManifest,
+  resolveOverlayBinary,
+  setOverlayLease,
+} from "./overlay.js";
+
+describe("overlay launcher", () => {
+  test("opens only when the user submits a prompt; new sessions reset without popping the window open", () => {
+    const hooks = JSON.parse(readFileSync(new URL("../hooks/hooks.json", import.meta.url), "utf8")).hooks;
+    expect(hooks.SessionStart[0].hooks.map((hook: { args: string[] }) => hook.args)).toEqual([
+      ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-update.ts", "--check"],
+      ["${CLAUDE_PLUGIN_ROOT}/scripts/overlay.ts", "--reset"],
+    ]);
+    expect(hooks.UserPromptSubmit[0].hooks.map((hook: { args: string[] }) => hook.args)).toEqual([
+      ["${CLAUDE_PLUGIN_ROOT}/scripts/plugin-update.ts", "--nudge"],
+      ["${CLAUDE_PLUGIN_ROOT}/scripts/overlay.ts", "--show"],
+    ]);
+    // The overlay stays visible across turns; only SessionEnd tears it down.
+    expect(hooks.Stop).toBeUndefined();
+  });
+
+  test("accepts lifecycle actions and legacy hook aliases", () => {
+    expect(parseAction([])).toBe("show");
+    expect(parseAction(["--enable"])).toBe("enable");
+    expect(parseAction(["--pause"])).toBe("pause");
+    expect(parseAction(["--reset"])).toBe("reset");
+    expect(parseAction(["--stop"])).toBe("quit");
+    expect(() => parseAction(["--unknown"])).toThrow("Unknown overlay action");
+  });
+
+  test("session cleanup removes the lease watched by every overlay process", () => {
+    const path = join(mkdtempSync(join(tmpdir(), "gamepigeon-lease-")), "overlay.alive");
+    setOverlayLease(true, path);
+    expect(existsSync(path)).toBe(true);
+    setOverlayLease(false, path);
+    expect(existsSync(path)).toBe(false);
+  });
+
+  test("reset keeps the overlay lease alive while quit clears it", () => {
+    const path = join(mkdtempSync(join(tmpdir(), "gamepigeon-lease-")), "overlay.alive");
+    setOverlayLease(true, path);
+    applyOverlayLease("reset", path);
+    expect(existsSync(path)).toBe(true);
+    applyOverlayLease("quit", path);
+    expect(existsSync(path)).toBe(false);
+  });
+
+  test("prefers a packaged platform binary", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-overlay-"));
+    const candidate = overlayBinaryCandidates(root).find((path) => path.startsWith(join(root, "bin")))!;
+    mkdirSync(dirname(candidate), { recursive: true });
+    writeFileSync(candidate, "");
+    if (process.platform !== "win32") chmodSync(candidate, 0o755);
+    expect(resolveOverlayBinary(root)).toBe(candidate);
+  });
+
+  test("reads the release manifest committed by CI and ignores missing or malformed ones", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-overlay-"));
+    expect(readReleaseManifest(root)).toBeNull();
+    writeFileSync(join(root, "overlay-release.json"), "not json");
+    expect(readReleaseManifest(root)).toBeNull();
+    writeFileSync(join(root, "overlay-release.json"), JSON.stringify({ tag: "overlay-abc1234", version: "abc1234" }));
+    expect(readReleaseManifest(root)).toEqual({ tag: "overlay-abc1234", version: "abc1234" });
+  });
+
+  test("prefers the managed auto-updated binary over local development builds", () => {
+    const root = mkdtempSync(join(tmpdir(), "gamepigeon-overlay-"));
+    const manifest = { tag: "overlay-abc1234", version: "abc1234" };
+    const candidates = overlayBinaryCandidates(root, manifest);
+    expect(candidates[0]).toBe(managedBinaryPath(manifest.version));
+    expect(candidates.some((path) => path.startsWith(join(root, "bin")))).toBe(true);
+  });
+
+  test("falls back to the managed version in use when the manifest's version was pruned", () => {
+    const home = mkdtempSync(join(tmpdir(), "gamepigeon-bin-"));
+    const previous = process.env.GAMEPIGEON_OVERLAY_HOME;
+    process.env.GAMEPIGEON_OVERLAY_HOME = home;
+    try {
+      writeFileSync(join(home, "current"), "9.9.9\n");
+      const root = mkdtempSync(join(tmpdir(), "gamepigeon-overlay-"));
+      const candidates = overlayBinaryCandidates(root, { tag: "overlay-abc1234", version: "abc1234" });
+      expect(candidates.at(-1)).toBe(managedBinaryPath("9.9.9"));
+      // A dev checkout with no manifest keeps resolving its own builds only.
+      expect(overlayBinaryCandidates(root, null)).not.toContain(managedBinaryPath("9.9.9"));
+    } finally {
+      if (previous === undefined) delete process.env.GAMEPIGEON_OVERLAY_HOME;
+      else process.env.GAMEPIGEON_OVERLAY_HOME = previous;
+    }
+  });
+
+  test("names release assets by platform so the launcher and CI agree", () => {
+    const asset = overlayReleaseAsset();
+    expect(asset.startsWith("gamepigeon-overlay-")).toBe(true);
+    if (process.platform === "darwin") expect(asset).toBe(`gamepigeon-overlay-macos-${process.arch}`);
+    if (process.platform === "win32") expect(asset).toBe(`gamepigeon-overlay-windows-${process.arch}.exe`);
+  });
+});

package/scripts/overlay.ts

@@ -0,0 +1,385 @@
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { analytics } from "../src/analytics/posthog.js";
+import type { AnalyticsCloudEvent } from "../src/analytics/events.js";
+import { refreshSessionIfPresent } from "../src/auth.js";
+
+export type OverlayAction = "show" | "enable" | "pause" | "hide" | "reset" | "quit";
+
+export interface LaunchOptions {
+  gameId?: string;
+  variationId?: string;
+}
+
+export interface ReleaseManifest {
+  tag: string;
+  version: string;
+}
+
+const ROOT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_REPO = "Trolleroof/tui-gamepigeon";
+
+// When the user hits "Shutdown" in the overlay, the window writes this flag and
+// quits. While the flag exists we suppress `show`/`pause` so the overlay stops
+// popping open for the rest of the session; the SessionStart `--reset` clears it.
+const SHUTDOWN_FLAG = join(tmpdir(), ".gamepigeon-overlay.off");
+const OVERLAY_LEASE_FILE = join(tmpdir(), ".gamepigeon-overlay.alive");
+const PAUSED_FLAG = join(tmpdir(), ".gamepigeon-overlay.paused");
+const ANALYTICS_QUEUE = join(homedir(), ".tui-gamepigeon", "analytics-events.jsonl");
+
+async function flushAnalyticsQueue(): Promise<void> {
+  if (!process.env.POSTHOG_API_KEY || !existsSync(ANALYTICS_QUEUE)) return;
+  try {
+    const events = readFileSync(ANALYTICS_QUEUE, "utf8").trim().split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as AnalyticsCloudEvent);
+    for (const event of events) analytics.capture(event);
+    // Bounded: this runs on the shutdown path, where a hung upload would stall
+    // the session's exit. A dropped flush just stays queued for the next run.
+    const flushed = await Promise.race([
+      analytics.shutdown().then(() => true),
+      Bun.sleep(2000).then(() => false),
+    ]);
+    if (flushed) rmSync(ANALYTICS_QUEUE, { force: true });
+  } catch {
+    // Keep the queue for the next launcher run.
+  }
+}
+
+export function isShutDown(): boolean {
+  return existsSync(SHUTDOWN_FLAG);
+}
+
+function clearShutdown(): void {
+  try {
+    rmSync(SHUTDOWN_FLAG, { force: true });
+  } catch {
+    // Best-effort: a leftover flag only means the overlay stays hidden.
+  }
+}
+
+export function setOverlayLease(active: boolean, path = OVERLAY_LEASE_FILE): void {
+  if (active) writeFileSync(path, "", { mode: 0o600 });
+  else rmSync(path, { force: true });
+}
+
+export function parseAction(args: string[]): OverlayAction {
+  const value = args[0] ?? "--show";
+  if (value === "--show") return "show";
+  if (value === "--enable") return "enable";
+  if (value === "--pause") return "pause";
+  if (value === "--hide") return "hide";
+  if (value === "--reset") return "reset";
+  if (value === "--quit" || value === "--stop") return "quit";
+  throw new Error(`Unknown overlay action: ${value}`);
+}
+
+export function overlayExecutableName(): string {
+  return process.platform === "win32" ? "gamepigeon-overlay.exe" : "gamepigeon-overlay";
+}
+
+export function overlayReleaseAsset(): string {
+  const platform =
+    process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : process.platform;
+  const extension = process.platform === "win32" ? ".exe" : "";
+  return `gamepigeon-overlay-${platform}-${process.arch}${extension}`;
+}
+
+export function managedBinDir(): string {
+  return process.env.GAMEPIGEON_OVERLAY_HOME ?? join(homedir(), ".gamepigeon", "bin");
+}
+
+export function managedBinaryPath(version: string): string {
+  return join(managedBinDir(), version, overlayExecutableName());
+}
+
+export function readReleaseManifest(root = ROOT_DIR): ReleaseManifest | null {
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, "overlay-release.json"), "utf8"));
+    if (typeof parsed.tag === "string" && typeof parsed.version === "string") {
+      return { tag: parsed.tag, version: parsed.version };
+    }
+  } catch {
+    // No packaged release manifest; fall back to local builds.
+  }
+  return null;
+}
+
+export function repoSlug(root = ROOT_DIR): string {
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8"));
+    const match = /github\.com\/([^/]+\/[^/.]+)/.exec(parsed.repository ?? "");
+    if (match?.[1]) return match[1];
+  } catch {
+    // Use the default repository below.
+  }
+  return DEFAULT_REPO;
+}
+
+export function overlayBinaryCandidates(root = ROOT_DIR, manifest = readReleaseManifest(root)): string[] {
+  const executable = overlayExecutableName();
+  const platform = process.platform === "darwin" ? "macos" : process.platform;
+  // Last resort, for packaged copies only: the version named by `current`. A
+  // plugin whose manifest trails the managed dir (another checkout downloaded a
+  // newer overlay and pruned this one's version) would otherwise resolve nothing.
+  // Local builds still win, so a dev checkout is unaffected.
+  const current = manifest ? readCurrentVersion() : null;
+  return [
+    process.env.GAMEPIGEON_OVERLAY_BIN,
+    manifest ? managedBinaryPath(manifest.version) : undefined,
+    join(root, "bin", `${platform}-${process.arch}`, executable),
+    join(root, "tauri", "target", "release", executable),
+    join(root, "tauri", "target", "debug", executable),
+    current && current !== manifest?.version ? managedBinaryPath(current) : undefined,
+  ].filter((candidate): candidate is string => Boolean(candidate));
+}
+
+function isLaunchable(candidate: string): boolean {
+  try {
+    accessSync(candidate, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveOverlayBinary(root = ROOT_DIR, manifest = readReleaseManifest(root)): string {
+  for (const candidate of overlayBinaryCandidates(root, manifest)) {
+    if (isLaunchable(candidate)) return candidate;
+  }
+  throw new Error(
+    "GamePigeon overlay binary was not found. Run `bun run build:overlay` or install a packaged release.",
+  );
+}
+
+async function downloadReleaseBinary(manifest: ReleaseManifest, root: string): Promise<void> {
+  const destination = managedBinaryPath(manifest.version);
+  const staging = `${destination}.download`;
+  mkdirSync(dirname(destination), { recursive: true });
+
+  const asset = overlayReleaseAsset();
+  const slug = repoSlug(root);
+  let downloaded = false;
+
+  // `gh` authenticates against private repositories; plain fetch covers public ones.
+  try {
+    const gh = Bun.spawn(
+      ["gh", "release", "download", manifest.tag, "--repo", slug, "--pattern", asset, "--output", staging, "--clobber"],
+      { stdin: "ignore", stdout: "ignore", stderr: "ignore" },
+    );
+    downloaded = (await gh.exited) === 0;
+  } catch {
+    downloaded = false;
+  }
+
+  if (!downloaded) {
+    const response = await fetch(`https://github.com/${slug}/releases/download/${manifest.tag}/${asset}`);
+    if (!response.ok) {
+      throw new Error(`Overlay download failed (${response.status}) for ${manifest.tag}/${asset}`);
+    }
+    writeFileSync(staging, new Uint8Array(await response.arrayBuffer()));
+  }
+
+  if (process.platform !== "win32") chmodSync(staging, 0o755);
+  renameSync(staging, destination);
+}
+
+function pruneManagedBinaries(keepVersion: string): void {
+  try {
+    for (const entry of readdirSync(managedBinDir())) {
+      if (entry !== keepVersion && entry !== "current") {
+        rmSync(join(managedBinDir(), entry), { recursive: true, force: true });
+      }
+    }
+  } catch {
+    // Nothing to prune.
+  }
+}
+
+function readCurrentVersion(): string | null {
+  try {
+    return readFileSync(join(managedBinDir(), "current"), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Detached so a Ctrl+C that ends the session cannot take the quit down with it:
+// the signal reaches the whole foreground process group, and this child must
+// outlive that.
+//
+// `wait` is for the upgrade path, where the old instance has to be gone before
+// the new binary launches. The SessionEnd hook must not wait: every millisecond
+// it stays alive is a millisecond in which the exiting session can abort it and
+// print a "Hook cancelled" failure at the user. The detached child finishes the
+// quit on its own either way.
+function quitOverlay(binary: string, wait = true): Promise<unknown> {
+  const child = Bun.spawn([binary, "--quit"], {
+    detached: true,
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  child.unref();
+  if (!wait) return Promise.resolve();
+  return Promise.race([child.exited, Bun.sleep(2000)]);
+}
+
+/**
+ * Downloads the packaged overlay binary named by overlay-release.json when the
+ * managed copy is missing or stale, quitting a running older instance so the
+ * next launch runs the fresh build. Failures fall back to whatever binary is
+ * already resolvable so an offline session keeps working.
+ */
+export async function ensureOverlayBinary(root = ROOT_DIR): Promise<void> {
+  const manifest = readReleaseManifest(root);
+  if (!manifest) return;
+
+  const destination = managedBinaryPath(manifest.version);
+  if (!isLaunchable(destination)) {
+    try {
+      await downloadReleaseBinary(manifest, root);
+    } catch {
+      return;
+    }
+  }
+
+  const previous = readCurrentVersion();
+  if (previous && previous !== manifest.version) {
+    const stale = managedBinaryPath(previous);
+    if (isLaunchable(stale)) await quitOverlay(stale);
+  }
+  writeFileSync(join(managedBinDir(), "current"), manifest.version);
+  pruneManagedBinaries(manifest.version);
+}
+
+export function applyOverlayLease(action: OverlayAction, leasePath = OVERLAY_LEASE_FILE): void {
+  if (action === "quit") setOverlayLease(false, leasePath);
+  else if (action === "show" || action === "enable") setOverlayLease(true, leasePath);
+}
+
+function overlaySpawnArgs(action: OverlayAction, options: LaunchOptions = {}): string[] {
+  const args = [`--${action}`];
+  if (options.gameId) args.push("--game", options.gameId);
+  if (options.variationId) args.push("--variation", options.variationId);
+  return args;
+}
+
+export async function launchOverlay(
+  action: OverlayAction,
+  root = ROOT_DIR,
+  options: LaunchOptions = {},
+): Promise<void> {
+  // Not on the quit path: SessionEnd has to return immediately, and the queue is
+  // durable, so the next session's `--reset` flushes it from an async hook.
+  if (action !== "quit") await flushAnalyticsQueue();
+  if (
+    (action === "show" || action === "enable") &&
+    process.env.GAMEPIGEON_OVERLAY_DRY_RUN !== "1"
+  ) {
+    // Refresh an existing session only — never open a browser here. This runs
+    // on every UserPromptSubmit hook, so triggering interactive sign-in from
+    // it would pop a new login tab on every prompt while signed out. The
+    // overlay's own gate screen owns interactive sign-in (explicit click/Enter).
+    await refreshSessionIfPresent();
+  }
+  // A new session re-enables the overlay; every other action honors the shutdown flag.
+  applyOverlayLease(action);
+  if (action === "quit") {
+    try {
+      rmSync(PAUSED_FLAG, { force: true });
+    } catch {}
+  }
+  if (action === "reset" || action === "enable") clearShutdown();
+  else if ((action === "show" || action === "pause") && isShutDown()) return;
+
+  if (action === "pause") {
+    if (!existsSync(OVERLAY_LEASE_FILE) || existsSync(PAUSED_FLAG)) return;
+    try {
+      writeFileSync(PAUSED_FLAG, "", { mode: 0o600 });
+    } catch {}
+  } else if (action === "show" || action === "enable") {
+    try {
+      rmSync(PAUSED_FLAG, { force: true });
+    } catch {}
+  }
+
+  // An explicit binary is a development override: never replace it with a download.
+  // Shutdown never downloads either — it only widens the window for the session's
+  // Ctrl+C to kill this hook mid-flight.
+  if (
+    action !== "quit" &&
+    process.env.GAMEPIGEON_OVERLAY_DRY_RUN !== "1" &&
+    !process.env.GAMEPIGEON_OVERLAY_BIN
+  ) {
+    await ensureOverlayBinary(root);
+  }
+  // No resolvable binary means there is nothing running to shut down, so quit
+  // succeeds by doing nothing rather than failing the SessionEnd hook at the user.
+  let binary: string;
+  try {
+    binary = resolveOverlayBinary(root);
+  } catch (error) {
+    if (action === "quit") return;
+    throw error;
+  }
+  const spawnArgs = overlaySpawnArgs(action, options);
+  if (process.env.GAMEPIGEON_OVERLAY_DRY_RUN === "1") {
+    console.log(JSON.stringify([binary, ...spawnArgs]));
+    return;
+  }
+  if (action === "quit") {
+    await quitOverlay(binary, false);
+    return;
+  }
+  const child = Bun.spawn([binary, ...spawnArgs], {
+    cwd: root,
+    detached: true,
+    env: {
+      ...process.env,
+      GAMEPIGEON_OVERLAY_LEASE: OVERLAY_LEASE_FILE,
+      ...(options.gameId ? { GAMEPIGEON_GAME: options.gameId } : {}),
+      ...(options.variationId ? { GAMEPIGEON_VARIATION: options.variationId } : {}),
+    },
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  child.unref();
+}
+
+if (import.meta.main) {
+  try {
+    const args = process.argv.slice(2);
+    const action = parseAction(args);
+    // Ctrl+C signals the whole foreground group, so the SessionEnd hook takes the
+    // same SIGINT that ended the session and dies before it can tear the overlay
+    // down. Hold the signals off; the work here is short and always terminates.
+    if (action === "quit") {
+      process.on("SIGINT", () => {});
+      process.on("SIGTERM", () => {});
+      process.on("SIGHUP", () => {});
+    }
+    const gameFlag = args.indexOf("--game");
+    const variationFlag = args.indexOf("--variation");
+    const gameId = gameFlag >= 0 ? args[gameFlag + 1] : undefined;
+    const variationId = variationFlag >= 0 ? args[variationFlag + 1] : undefined;
+    await launchOverlay(action, ROOT_DIR, { gameId, variationId });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}