@sns-myagent/cli 0.2.0

package/scripts/diagnose.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# scripts/diagnose.sh — self-diagnosing health check for sns-myagent
+# Exits 0 on PASS, 1 on FAIL. Safe to run from anywhere; cd's to repo root.
+
+set -e
+
+# Resolve repo root (script lives in scripts/, so parent of parent)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Colors only when TTY (avoid ANSI in cron logs)
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; BOLD=$'\033[1m'; RESET=$'\033[0m'
+else
+  RED=""; GREEN=""; YELLOW=""; BOLD=""; RESET=""
+fi
+
+FAIL=0
+WARN=0
+PASS_COUNT=0
+
+ok()   { echo "${GREEN}[PASS]${RESET} $*"; PASS_COUNT=$((PASS_COUNT+1)); }
+warn() { echo "${YELLOW}[WARN]${RESET} $*"; WARN=$((WARN+1)); }
+bad()  { echo "${RED}[FAIL]${RESET} $*"; FAIL=$((FAIL+1)); }
+hdr()  { echo; echo "${BOLD}== $* ==${RESET}"; }
+
+hdr "1. Runtime checks"
+
+# Bun version
+if command -v bun >/dev/null 2>&1; then
+  BUN_VER="$(bun --version 2>/dev/null || echo unknown)"
+  if printf '%s\n1.3.14\n' "$BUN_VER" | sort -V -C 2>/dev/null; then
+    ok "Bun $BUN_VER (>=1.3.14)"
+  else
+    bad "Bun $BUN_VER too old (need >=1.3.14)"
+  fi
+else
+  bad "Bun not installed"
+fi
+
+# Node (for fallback)
+if command -v node >/dev/null 2>&1; then
+  ok "Node $(node --version)"
+else
+  warn "Node not installed (needed for fallback)"
+fi
+
+# git available
+if command -v git >/dev/null 2>&1; then
+  ok "git available"
+else
+  bad "git missing"
+fi
+
+hdr "2. Repository state"
+
+if [ -d .git ]; then
+  ok "git repo initialized"
+else
+  bad "not a git repo"
+fi
+
+# Clean working tree?
+if git status --porcelain 2>/dev/null | grep -q .; then
+  UNCOMMITTED="$(git status --short 2>/dev/null | wc -l | tr -d ' ')"
+  warn "$UNCOMMITTED uncommitted change(s):"
+  git status --short | sed 's/^/    /'
+else
+  ok "working tree clean"
+fi
+
+# Current branch + last commit
+BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
+LAST="$(git log -1 --oneline 2>/dev/null || echo 'none')"
+echo "    branch: $BRANCH"
+echo "    last:   $LAST"
+
+hdr "3. TypeScript type check"
+
+if [ ! -f tsconfig.json ]; then
+  bad "tsconfig.json missing"
+else
+  ok "tsconfig.json present"
+fi
+
+# Prefer tsgo (project uses it), fall back to tsc
+TSC_CMD=""
+if [ -x node_modules/.bin/tsgo ]; then
+  TSC_CMD="node_modules/.bin/tsgo -p tsconfig.json --noEmit"
+elif command -v tsgo >/dev/null 2>&1; then
+  TSC_CMD="tsgo -p tsconfig.json --noEmit"
+elif [ -x node_modules/.bin/tsc ]; then
+  TSC_CMD="node_modules/.bin/tsc -p tsconfig.json --noEmit"
+elif command -v npx >/dev/null 2>&1; then
+  TSC_CMD="npx --yes tsc -p tsconfig.json --noEmit"
+fi
+
+if [ -z "$TSC_CMD" ]; then
+  bad "no TypeScript compiler found"
+else
+  echo "    running: $TSC_CMD"
+  TSC_OUT="$(eval "$TSC_CMD" 2>&1 || true)"
+  TSC_EXIT=$?
+  if [ -z "$TSC_OUT" ]; then
+    ok "TSC clean (no errors)"
+  else
+    TOTAL_LINES="$(printf '%s\n' "$TSC_OUT" | wc -l | tr -d ' ')"
+    bad "TSC found errors ($TOTAL_LINES lines)"
+    echo
+    echo "${BOLD}Top error files:${RESET}"
+    printf '%s\n' "$TSC_OUT" \
+      | grep -E '\.ts\([0-9]+,[0-9]+\):' \
+      | sed -E 's/^([^[:space:]]+\.ts)\([0-9]+,[0-9]+\):.*/\1/' \
+      | sort | uniq -c | sort -rn | head -10 \
+      | sed 's/^/    /'
+    echo
+    echo "${BOLD}First 15 error lines:${RESET}"
+    printf '%s\n' "$TSC_OUT" | head -15 | sed 's/^/    /'
+  fi
+fi
+
+hdr "4. Build output"
+
+if [ -d dist ]; then
+  DIST_FILES="$(find dist -type f 2>/dev/null | wc -l | tr -d ' ')"
+  if [ "$DIST_FILES" -gt 0 ]; then
+    ok "dist/ present ($DIST_FILES files)"
+  else
+    bad "dist/ empty (no successful build)"
+  fi
+else
+  bad "dist/ missing (never built)"
+fi
+
+hdr "5. Postinstall hang risk"
+
+# Detect postinstall hooks that fetch binaries (known hang risk)
+if grep -q '"postinstall"' package.json 2>/dev/null; then
+  POST_SCRIPT="$(node -e "try { console.log(require('./package.json').scripts.postinstall||'') } catch(e){}" 2>/dev/null || true)"
+  if [ -n "$POST_SCRIPT" ]; then
+    # Risk if it tries to download from network without timeout
+    if printf '%s' "$POST_SCRIPT" | grep -qE 'fetch-binary|curl |wget |https?://'; then
+      warn "postinstall does network I/O: $POST_SCRIPT"
+      warn "    risk: hangs >5min on slow networks. Consider: SKIP_POSTINSTALL=1"
+    else
+      ok "postinstall: $POST_SCRIPT (low risk)"
+    fi
+  fi
+else
+  ok "no postinstall hook"
+fi
+
+# node_modules sanity
+if [ -d node_modules ]; then
+  NM_COUNT="$(find node_modules -maxdepth 2 -mindepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')"
+  if [ "$NM_COUNT" -lt 10 ]; then
+    bad "node_modules sparse ($NM_COUNT entries) — install failed?"
+  else
+    ok "node_modules populated ($NM_COUNT top-level entries)"
+  fi
+else
+  bad "node_modules missing"
+fi
+
+hdr "Summary"
+echo "  ${GREEN}PASS${RESET}: $PASS_COUNT"
+echo "  ${YELLOW}WARN${RESET}: $WARN"
+echo "  ${RED}FAIL${RESET}: $FAIL"
+echo
+
+if [ "$FAIL" -gt 0 ]; then
+  echo "${RED}${BOLD}DIAGNOSE: FAIL${RESET}"
+  exit 1
+fi
+
+if [ "$WARN" -gt 0 ]; then
+  echo "${YELLOW}${BOLD}DIAGNOSE: PASS (with warnings)${RESET}"
+  exit 0
+fi
+
+echo "${GREEN}${BOLD}DIAGNOSE: PASS${RESET}"
+exit 0

package/scripts/embed-mupdf-wasm.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+
+// Embeds mupdf's `mupdf-wasm.wasm` into the compiled single-file binary.
+//
+// mupdf loads its wasm by reading the `mupdf-wasm.wasm` sibling of its own
+// module via `new URL(..., import.meta.url)` + `readFileSync`. A `bun --compile`
+// binary has no node_modules, so that read fails (`ENOENT .../mupdf-wasm.wasm`),
+// and marking mupdf `--external` instead makes `bun --compile` eagerly fail to
+// resolve the package at startup (the static `import * as mupdf` lives in a lazy
+// chunk but is hoisted). So the binary build bundles mupdf and embeds the wasm
+// bytes here, handing them to the WASM module as `$libmupdf_wasm_Module.wasmBinary`
+// (see src/utils/markit.ts).
+//
+// `--generate` copies the wasm next to src/utils/mupdf-wasm-embed.ts and rewrites
+// that module to import it via `with { type: "file" }`; `--reset` restores the
+// checked-in placeholder and removes the copy. The npm `dist/cli.js` bundle never
+// runs this — it keeps mupdf external and loads the wasm from node_modules.
+
+import * as fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+
+const utilsDir = path.join(import.meta.dir, "..", "src", "utils");
+const helperPath = path.join(utilsDir, "mupdf-wasm-embed.ts");
+const wasmCopyPath = path.join(utilsDir, "mupdf-wasm.wasm");
+
+const placeholder = `// AUTOGENERATED -- managed by scripts/embed-mupdf-wasm.ts. Do not edit by hand.
+//
+// Compiled single-file binaries cannot let mupdf resolve its \`mupdf-wasm.wasm\`
+// sibling from the read-only bunfs, so the binary build (scripts/build-binary.ts
+// and scripts/ci-release-build-binaries.ts) regenerates this module to embed the
+// wasm bytes via \`with { type: "file" }\` and copies the wasm next to it. Source
+// checkouts, \`bun test\`, and the npm \`dist/cli.js\` bundle keep mupdf external and
+// load the wasm from node_modules, so this placeholder returns undefined and the
+// build resets back to it afterward.
+export function loadEmbeddedMupdfWasm(): Uint8Array | undefined {
+\treturn undefined;
+}
+`;
+
+const generated = `// AUTOGENERATED -- managed by scripts/embed-mupdf-wasm.ts. Do not edit or commit.
+import { readFileSync } from "node:fs";
+import wasmPath from "./mupdf-wasm.wasm" with { type: "file" };
+
+export function loadEmbeddedMupdfWasm(): Uint8Array | undefined {
+\treturn readFileSync(wasmPath);
+}
+`;
+
+if (process.argv.includes("--reset")) {
+	await Bun.write(helperPath, placeholder);
+	try {
+		await fs.unlink(wasmCopyPath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+	}
+	process.exit(0);
+}
+
+const wasmSource = path.join(path.dirname(createRequire(import.meta.url).resolve("mupdf")), "mupdf-wasm.wasm");
+const wasmFile = Bun.file(wasmSource);
+if (!(await wasmFile.exists())) {
+	throw new Error(`mupdf wasm not found at ${wasmSource}; run \`bun install\` first.`);
+}
+await Bun.write(wasmCopyPath, wasmFile);
+await Bun.write(helperPath, generated);
+console.log(`Embedded mupdf wasm (${wasmFile.size} bytes) into ${path.relative(process.cwd(), wasmCopyPath)}`);

package/scripts/fetch-binary.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+// fetch-binary.mjs — Node.js postinstall for @sns-myagent/cli (Opsi B: dual-runtime npm support)
+//
+// Downloads the prebuilt `snscoder` binary from the latest GitHub release
+// and unpacks it to <repo>/bin/. Runs under plain Node 18+ (no `npm install`
+// dependencies allowed — npm postinstall executes BEFORE package deps install).
+//
+// Strategy:
+//   1. Detect platform + arch (process.platform, process.arch).
+//   2. On linux, attempt a musl probe via `ldd /proc/self/exe` — if no glibc
+//      dependency is reported we pick the musl asset, otherwise the glibc one.
+//      If the probe fails or is inconclusive, fall back to glibc.
+//   3. GET https://api.github.com/repos/Reihantt6/sns-myagent/releases/latest
+//      (honors GITHUB_TOKEN env var for 60-req/hr anonymous → 5000-req/hr auth).
+//   4. Find the matching asset, download its zip, and unpack into bin/.
+//      Unix uses `unzip -o`; Windows uses `Expand-Archive` via PowerShell.
+//   5. chmod 755 the resulting binary on unix.
+//   6. On any failure path (no release, missing asset, network down) print a
+//      friendly warning and exit 0 — we must NOT break `npm install`.
+//
+// Spec conventions assumed for release assets (Bun-style):
+//   snscoder-linux-x64.zip       (glibc fallback)
+//   snscoder-linux-x64-musl.zip  (musl/alpine)
+//   snscoder-linux-arm64.zip
+//   snscoder-darwin-x64.zip
+//   snscoder-darwin-arm64.zip
+//   snscoder-windows-x64.zip
+//   Each archive contains a single file named `snscoder` (or `snscoder.exe`).
+
+import { execFileSync } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync } from "node:fs";
+import { chmod, mkdtemp, readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import https from "node:https";
+
+const REPO = "Reihantt6/sns-myagent";
+const RELEASE_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+const UA = "sns-myagent-fetch-binary/0.1.0 (npm postinstall)";
+
+// Resolve repo root: this script lives at <repo>/scripts/fetch-binary.mjs
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, "..");
+const BIN_DIR = join(REPO_ROOT, "bin");
+
+const isWin = process.platform === "win32";
+
+// --- Pretty logging ---------------------------------------------------------
+
+const c = {
+	reset: "\u001b[0m",
+	dim: "\u001b[2m",
+	red: "\u001b[31m",
+	green: "\u001b[32m",
+	yellow: "\u001b[33m",
+	cyan: "\u001b[36m",
+	bold: "\u001b[1m",
+};
+
+function info(msg) {
+	process.stdout.write(`${c.cyan}info${c.reset}  ${msg}\n`);
+}
+function warn(msg) {
+	process.stdout.write(`${c.yellow}warn${c.reset}  ${msg}\n`);
+}
+function error(msg) {
+	process.stdout.write(`${c.red}error${c.reset} ${msg}\n`);
+}
+function ok(msg) {
+	process.stdout.write(`${c.green}ok${c.reset}    ${msg}\n`);
+}
+
+// --- Platform / asset mapping ----------------------------------------------
+
+/**
+ * Map (platform, arch, isMusl) → asset filename.
+ * Returns null when the platform/arch combo is unsupported.
+ */
+function pickAssetName(platform, arch, isMusl) {
+	if (platform === "linux") {
+		if (arch === "x64") return isMusl ? "snscoder-linux-x64-musl.zip" : "snscoder-linux-x64.zip";
+		if (arch === "arm64") return "snscoder-linux-arm64.zip";
+		return null;
+	}
+	if (platform === "darwin") {
+		if (arch === "x64") return "snscoder-darwin-x64.zip";
+		if (arch === "arm64") return "snscoder-darwin-arm64.zip";
+		return null;
+	}
+	if (platform === "win32") {
+		if (arch === "x64") return "snscoder-windows-x64.zip";
+		return null;
+	}
+	return null;
+}
+
+/**
+ * Musl heuristic: run `ldd /proc/self/exe` and look for `libc.so.*` (glibc).
+ * - musl systems (Alpine, Void with musl, etc.) print "Not a valid dynamic
+ *   program" or `ldd: can't find dynamic linker info` AND no `libc.so.6` line.
+ * - glibc systems show `libc.so.6 => /lib64/libc.so.6` etc.
+ *
+ * Heuristic limitations:
+ * - Static binaries report "not a dynamic executable" — we conservatively
+ *   treat that as glibc (more common on developer machines).
+ * - BusyBox `ldd` is a shell wrapper; it sometimes prints to stdout but not
+ *   stderr. We merge both streams before scanning.
+ */
+function detectMuslLinux() {
+	if (process.platform !== "linux") return false;
+	try {
+		const out = execFileSync("ldd", ["/proc/self/exe"], {
+			stdio: ["ignore", "pipe", "pipe"],
+			encoding: "utf8",
+			timeout: 3000,
+		});
+		// glibc leaves a libc.so.6 line; musl leaves musl libc.so line.
+		if (/libc\.so\.6/.test(out)) return false;
+		if (/musl/.test(out)) return true;
+		// No glibc marker found and not explicitly musl → assume musl
+		// (Alpine, Void-musl, etc.). Falls back wrong on static binaries
+		// — see heuristic note above.
+		return true;
+	} catch {
+		// ldd missing OR failed → can't tell. Default to glibc (most common).
+		return false;
+	}
+}
+
+// --- HTTP helpers -----------------------------------------------------------
+
+/**
+ * https.get wrapper that returns a Buffer and follows up to 3 redirects
+ * (GitHub release redirects to S3, which redirects to Cloudfront).
+ */
+function fetchBuffer(url, redirectsLeft = 3) {
+	return new Promise((resolveP, rejectP) => {
+		const headers = {
+			"User-Agent": UA,
+			Accept: "application/octet-stream",
+		};
+		if (process.env.GITHUB_TOKEN) {
+			headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+		}
+
+		const req = https.get(url, { headers }, (res) => {
+			const status = res.statusCode ?? 0;
+			// Follow redirects (GitHub release downloads 302 to S3 → Cloudfront)
+			if (status >= 300 && status < 400 && res.headers.location) {
+				res.resume();
+				if (redirectsLeft <= 0) {
+					rejectP(new Error(`too many redirects for ${url}`));
+					return;
+				}
+				resolveP(fetchBuffer(res.headers.location, redirectsLeft - 1));
+				return;
+			}
+			if (status === 404) {
+				res.resume();
+				rejectP(Object.assign(new Error("not found"), { httpStatus: 404 }));
+				return;
+			}
+			if (status !== 200) {
+				res.resume();
+				rejectP(new Error(`HTTP ${status} for ${url}`));
+				return;
+			}
+
+			const chunks = [];
+			res.on("data", (c2) => chunks.push(c2));
+			res.on("end", () => resolveP(Buffer.concat(chunks)));
+			res.on("error", rejectP);
+		});
+
+		req.on("error", rejectP);
+		req.setTimeout(30_000, () => {
+			req.destroy(new Error(`timeout after 30s: ${url}`));
+		});
+	});
+}
+
+function fetchJson(url) {
+	return new Promise((resolveP, rejectP) => {
+		const headers = {
+			"User-Agent": UA,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28",
+		};
+		if (process.env.GITHUB_TOKEN) {
+			headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+		}
+
+		const req = https.get(url, { headers }, (res) => {
+			const status = res.statusCode ?? 0;
+			const chunks = [];
+			res.on("data", (c2) => chunks.push(c2));
+			res.on("end", () => {
+				const body = Buffer.concat(chunks).toString("utf8");
+				if (status === 404) {
+					rejectP(Object.assign(new Error("release not found"), { httpStatus: 404 }));
+					return;
+				}
+				if (status !== 200) {
+					rejectP(new Error(`GitHub API HTTP ${status}: ${body.slice(0, 200)}`));
+					return;
+				}
+				try {
+					resolveP(JSON.parse(body));
+				} catch (e) {
+					rejectP(new Error(`invalid JSON from GitHub: ${e.message}`));
+				}
+			});
+			res.on("error", rejectP);
+		});
+
+		req.on("error", rejectP);
+		req.setTimeout(30_000, () => {
+			req.destroy(new Error(`timeout after 30s: ${url}`));
+		});
+	});
+}
+
+// --- Zip unpack (delegates to system tools) --------------------------------
+
+/**
+ * Unzip an archive into destDir. On unix uses `unzip -o`; on Windows uses
+ * PowerShell's `Expand-Archive`. Both are preinstalled on the respective
+ * platforms (unzip is on virtually every macOS/Linux dev box; Expand-Archive
+ * ships with PowerShell 5+).
+ *
+ * Throws if neither tool is available — caller decides whether that's fatal.
+ */
+function unzip(archivePath, destDir) {
+	if (isWin) {
+		// PowerShell Expand-Archive needs a non-existent OR empty dest dir.
+		execFileSync(
+			"powershell.exe",
+			[
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				`Expand-Archive -Path '${archivePath.replace(/'/g, "''")}' -DestinationPath '${destDir.replace(/'/g, "''")}' -Force`,
+			],
+			{ stdio: ["ignore", "inherit", "inherit"] },
+		);
+	} else {
+		execFileSync("unzip", ["-o", archivePath, "-d", destDir], {
+			stdio: ["ignore", "inherit", "inherit"],
+		});
+	}
+}
+
+// --- Main flow --------------------------------------------------------------
+
+async function main() {
+	const platform = process.platform;
+	const arch = process.arch;
+	const isMusl = detectMuslLinux();
+	const assetName = pickAssetName(platform, arch, isMusl);
+
+	if (!assetName) {
+		warn(
+			`unsupported platform/arch combo: ${platform}/${arch}. ` +
+				`Build from source instead: https://github.com/${REPO}#from-source`,
+		);
+		return;
+	}
+
+	info(`target: ${platform}/${arch}${isMusl ? " (musl)" : ""} → ${assetName}`);
+
+	let release;
+	try {
+		release = await fetchJson(RELEASE_API);
+	} catch (e) {
+		if (e.httpStatus === 404) {
+			warn(
+				`no release found at github.com/${REPO}/releases — ` +
+					`maintainer must publish v0.1.0 first. Falling back to Bun install.`,
+			);
+			return;
+		}
+		warn(
+			`could not reach GitHub API (${e.message}). ` +
+				`Skipping binary fetch. Run 'npm rebuild' after going online.`,
+		);
+		return;
+	}
+
+	const asset = (release.assets ?? []).find((a) => a.name === assetName);
+	if (!asset || !asset.browser_download_url) {
+		warn(
+			`release ${release.tag_name ?? "(unknown)"} has no asset '${assetName}'. ` +
+				`Available: ${(release.assets ?? []).map((a) => a.name).join(", ") || "(none)"}. ` +
+				`Falling back to Bun install.`,
+		);
+		return;
+	}
+
+	// Download into a temp dir so a half-finished install never clobbers bin/.
+	const tmp = await mkdtemp(join(tmpdir(), "snscoder-"));
+	const archivePath = join(tmp, assetName);
+	info(`downloading ${asset.browser_download_url}`);
+
+	let zipBuf;
+	try {
+		zipBuf = await fetchBuffer(asset.browser_download_url);
+	} catch (e) {
+		warn(`download failed (${e.message}). Skipping binary fetch.`);
+		await rm(tmp, { recursive: true, force: true });
+		return;
+	}
+
+	await new Promise((resolveP, rejectP) => {
+		const ws = createWriteStream(archivePath);
+		ws.on("error", rejectP);
+		ws.on("finish", resolveP);
+		ws.end(zipBuf);
+	});
+
+	info(`extracting → ${BIN_DIR}`);
+	mkdirSync(BIN_DIR, { recursive: true });
+	try {
+		unzip(archivePath, BIN_DIR);
+	} catch (e) {
+		warn(`unzip failed (${e.message}). Binaries like 'unzip' or PowerShell Expand-Archive are required.`);
+		await rm(tmp, { recursive: true, force: true });
+		return;
+	}
+
+	const binaryName = isWin ? "snscoder.exe" : "snscoder";
+	const binaryPath = join(BIN_DIR, binaryName);
+
+	if (!existsSync(binaryPath)) {
+		// Sometimes archives use a different internal name — try to discover.
+		const entries = await readdir(BIN_DIR);
+		warn(
+			`expected '${binaryName}' in archive but found: ${entries.join(", ") || "(empty)"}. ` +
+				`Adjust scripts/fetch-binary.mjs to match the release asset layout.`,
+		);
+		await rm(tmp, { recursive: true, force: true });
+		return;
+	}
+
+	if (!isWin) {
+		await chmod(binaryPath, 0o755);
+	}
+	const st = await stat(binaryPath);
+	ok(`${binaryName} ready (${(st.size / 1024 / 1024).toFixed(2)} MB)`);
+
+	await rm(tmp, { recursive: true, force: true });
+}
+
+main().catch((e) => {
+	// Catch-all: never break npm install. Print + exit 0.
+	error(`unexpected: ${e?.stack ?? e?.message ?? e}`);
+	process.exit(0);
+});

package/scripts/format-prompts.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+import { prompt } from "@oh-my-pi/pi-utils";
+/**
+ * Format prompt files (mixed XML + Markdown + Handlebars).
+ *
+ * Rules:
+ * 1. No blank line before list items
+ * 2. No blank line after opening XML tag or Handlebars block
+ * 3. No blank line before closing XML tag or Handlebars block
+ * 4. Strip leading whitespace from top-level closing XML tags (opened at col 0) and Handlebars (lines starting with {{)
+ * 5. Compact markdown tables (remove padding)
+ * 6. Collapse 2+ blank lines to single blank line
+ * 7. Trim trailing whitespace (preserve indentation)
+ * 8. Trailing newline at EOF (disk only; runtime omits it)
+ * 9. Bold RFC 2119 keywords (MUST, SHOULD, MAY, etc.) in prompt content
+ */
+import { Glob } from "bun";
+
+const PROMPTS_DIR = `${import.meta.dir}/../src/prompts/`;
+const COMMIT_PROMPTS_DIR = `${import.meta.dir}/../src/commit/prompts/`;
+const AGENTIC_PROMPTS_DIR = `${import.meta.dir}/../src/commit/agentic/prompts/`;
+
+const PROMPT_DIRS = [PROMPTS_DIR, COMMIT_PROMPTS_DIR, AGENTIC_PROMPTS_DIR];
+
+const PROMPT_FORMAT_OPTIONS = {
+	renderPhase: "pre-render",
+	replaceAsciiSymbols: true,
+	normalizeRfc2119: true,
+} as const;
+
+async function main() {
+	const glob = new Glob("**/*.md");
+	const files: string[] = [];
+	let changed = 0;
+	const check = process.argv.includes("--check");
+
+	for (const dir of PROMPT_DIRS) {
+		for await (const path of glob.scan(dir)) {
+			files.push(`${dir}${path}`);
+		}
+	}
+
+	for (const fullPath of files) {
+		const original = await Bun.file(fullPath).text();
+		const formatted = prompt.format(original, PROMPT_FORMAT_OPTIONS);
+
+		if (original !== `${formatted}\n`) {
+			if (check) {
+				console.log(`Would format: ${fullPath}`);
+			} else {
+				await Bun.write(fullPath, `${formatted}\n`);
+				console.log(`Formatted: ${fullPath}`);
+			}
+			changed++;
+		}
+	}
+
+	if (check && changed > 0) {
+		console.log(`\n${changed} file(s) need formatting. Run 'bun run format-prompts' to fix.`);
+		process.exit(1);
+	} else if (changed === 0) {
+		console.log("All prompt files are formatted.");
+	} else {
+		console.log(`\nFormatted ${changed} file(s).`);
+	}
+}
+
+main();