feat(cli): interactive [Y/n] GitHub-star prompt that stars via gh (agbrowse-style)

Replace the passive printed star notice with an interactive prompt that, on yes, stars
the repo directly through the user's `gh` auth (gh api -X PUT /user/starred/...), matching
agbrowse's postinstall UX.
- scripts/postinstall.mjs: runs on `npm install -g opencodex` (TTY-only, gh-gated, once).
- src/star-prompt.ts: same [Y/n]+gh flow on first interactive `ocx start` — the reliable
  path for bun-native installs where `bun install -g` may skip postinstall. Both share the
  ~/.opencodex/.star-prompted marker, so it fires exactly once across install + start.
- package.json: add postinstall script + ship scripts/postinstall.mjs via "files".
No-op under OCX_SERVICE, non-TTY/CI, when already prompted, or when gh is absent; never
blocks install/start. Verified: tsc clean, postinstall no-ops in non-TTY (exit 0).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lidge-jun

package.json

@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "scripts/postinstall.mjs",
     "gui/dist",
     "README.md",
     "LICENSE"
@@ -22,6 +23,7 @@
     "start": "bun run src/cli.ts start",
     "typecheck": "bun x tsc --noEmit",
     "build:gui": "cd gui && bun install && bun run build",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepublishOnly": "bun run typecheck && bun run build:gui"
   },
   "dependencies": {

scripts/postinstall.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * postinstall — one-time GitHub-star prompt during `npm install -g opencodex`.
+ *
+ * Behavior:
+ *   - TTY-only (skips CI / piped installs)
+ *   - Requires `gh` CLI with auth (stars directly via `gh api`)
+ *   - Prompts once; shares the ~/.opencodex/.star-prompted marker with the first-`ocx start` prompt
+ *     (so bun users — where postinstall may not run on `-g` — still get it exactly once on start)
+ *   - Never blocks the install (all errors silently caught)
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { homedir } from "node:os";
+
+const REPO = "lidge-jun/opencodex";
+const MARKER = join(homedir(), ".opencodex", ".star-prompted");
+
+function ghInstalled() {
+  const r = spawnSync("gh", ["--version"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+  return !r.error && r.status === 0;
+}
+
+function starRepo() {
+  const r = spawnSync("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true });
+  if (r.error) return { ok: false, error: r.error.message };
+  if (r.status !== 0) return { ok: false, error: (r.stderr || r.stdout || "").trim() || `gh exited ${r.status}` };
+  return { ok: true };
+}
+
+async function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const a = (await rl.question(question)).trim().toLowerCase();
+    return a === "" || a === "y" || a === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+  if (existsSync(MARKER)) return;
+  if (!ghInstalled()) return;
+
+  try { mkdirSync(join(homedir(), ".opencodex"), { recursive: true }); writeFileSync(MARKER, new Date().toISOString()); } catch { /* best-effort */ }
+
+  const yes = await askYesNo("[opencodex] Enjoying opencodex? Star it on GitHub? [Y/n] ");
+  if (!yes) return;
+  const r = starRepo();
+  console.log(r.ok ? "[opencodex] Thanks for the star! ⭐" : `[opencodex] Couldn't star automatically: ${r.error}`);
+}
+
+main().catch(() => { /* never fail the install */ });

src/cli.ts

@@ -66,7 +66,7 @@ function handleStart() {
   const server = startServer(port);
   writePid(process.pid);
 
-  maybeShowStarPrompt(); // once-only GitHub-star request on first interactive start
+  void maybeShowStarPrompt(); // once-only [Y/n] GitHub-star prompt on first interactive start
   syncModelsToCodex(port).catch(() => {});
 
   const shutdown = () => {

src/star-prompt.ts

@@ -1,30 +1,50 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 import { getConfigDir } from "./config";
 
-const REPO_URL = "https://github.com/lidge-jun/opencodex";
-/** Marker so the prompt is shown exactly once per install. */
+const REPO = "lidge-jun/opencodex";
+/** Shared with scripts/postinstall.mjs so the prompt fires exactly once across install + first start. */
 const MARKER = ".star-prompted";
 
+function ghAvailable(): boolean {
+  const r = spawnSync("gh", ["--version"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+  return !r.error && r.status === 0;
+}
+
+function starRepo(): { ok: boolean; error?: string } {
+  const r = spawnSync("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true });
+  if (r.error) return { ok: false, error: r.error.message };
+  if (r.status !== 0) return { ok: false, error: (r.stderr || r.stdout || "").trim() || `gh exited ${r.status}` };
+  return { ok: true };
+}
+
 /**
- * On the FIRST interactive `ocx start`, print a one-time GitHub-star request and drop a marker file
- * so it never shows again. No-op for the background service (OCX_SERVICE=1) and non-TTY/piped runs.
+ * First interactive `ocx start`: a one-time `[Y/n]` "star on GitHub?" prompt. On yes, stars the repo
+ * via the user's `gh` auth (same approach as the npm postinstall). No-op under the background service,
+ * for non-TTY/piped runs, when already prompted, or when `gh` is unavailable. Never throws.
  */
-export function maybeShowStarPrompt(): void {
-  if (process.env.OCX_SERVICE || !process.stdout.isTTY) return;
-  const dir = getConfigDir();
-  const marker = join(dir, MARKER);
-  if (existsSync(marker)) return;
+export async function maybeShowStarPrompt(): Promise<void> {
   try {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(marker, new Date().toISOString());
-  } catch { /* best-effort: if the marker can't be written, still show it this once */ }
+    if (process.env.OCX_SERVICE || !process.stdin.isTTY || !process.stdout.isTTY) return;
+    const dir = getConfigDir();
+    const marker = join(dir, MARKER);
+    if (existsSync(marker)) return;
+    if (!ghAvailable()) return; // can't star without gh — stay silent and re-check on a later start
+    try { mkdirSync(dir, { recursive: true }); writeFileSync(marker, new Date().toISOString()); } catch { /* best-effort */ }
 
-  const RESET = "\x1b[0m", PURPLE = "\x1b[38;5;141m", BOLD = "\x1b[1m", UL = "\x1b[4m", DIM = "\x1b[2m";
-  console.log("");
-  console.log(`  ${PURPLE}${BOLD}⭐  Enjoying opencodex?${RESET}`);
-  console.log("  A GitHub star genuinely helps the project grow — thank you!");
-  console.log(`  ${UL}${PURPLE}${REPO_URL}${RESET}`);
-  console.log(`  ${DIM}(shown once)${RESET}`);
-  console.log("");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let yes = false;
+    try {
+      const ans = (await rl.question("\n  \x1b[38;5;141m⭐ Enjoying opencodex? Star it on GitHub?\x1b[0m [Y/n] ")).trim().toLowerCase();
+      yes = ans === "" || ans === "y" || ans === "yes";
+    } finally {
+      rl.close();
+    }
+    if (!yes) return;
+    const r = starRepo();
+    console.log(r.ok ? "  Thanks for the star! ⭐\n" : `  Couldn't star automatically (${r.error}) — ${REPO}\n`);
+  } catch { /* never let the star prompt disrupt startup */ }
 }