@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/llm/assist.mjs

@@ -0,0 +1,260 @@
+import { detectInstalledLlmTools } from './tools.mjs';
+import { buildCodexExecScript, CODEX_PERMISSION_MODES, runCodexExecHere } from './codex_exec.mjs';
+import { canLaunchNewTerminal, launchScriptInNewTerminal } from '../ui/terminal_launcher.mjs';
+import { clipboardAvailable, copyTextToClipboard } from '../ui/clipboard.mjs';
+import { isTty, promptSelect, withRl } from '../cli/wizard.mjs';
+import { banner, bullets, cmd as cmdFmt, sectionTitle } from '../ui/layout.mjs';
+import { bold, cyan, dim, green, red, yellow } from '../ui/ansi.mjs';
+import { run } from '../proc/proc.mjs';
+
+function codexPermissionOptions() {
+  return [
+    { value: 'full-auto', label: `${green('recommended')} — full-auto (approvals on request + workspace sandbox)` },
+    { value: 'safe', label: `safe — always ask on risky actions (workspace sandbox)` },
+    { value: 'yolo', label: `${red('danger')} — run without approvals/sandbox (YOLO)` },
+  ];
+}
+
+function shouldAsk(options) {
+  return isTty() && options.length > 1;
+}
+
+function buildInteractiveLaunchScript({ toolCmd, cd, title, promptText }) {
+  const t = String(title ?? 'hstack (LLM)').trim();
+  const cwd = String(cd ?? '').trim();
+  const cmd = String(toolCmd ?? '').trim();
+  const prompt = String(promptText ?? '').trimEnd();
+  if (!cwd) throw new Error('[llm] launch: missing cwd');
+  if (!cmd) throw new Error('[llm] launch: missing toolCmd');
+
+  const execLine = (() => {
+    // Prefer providing the prompt directly when the CLI supports it.
+    // - Claude Code: `claude "query"` starts an interactive session with an initial prompt.
+    // - OpenCode: `opencode --prompt "..."` starts the TUI with an initial prompt.
+    if (cmd === 'claude') return 'exec command claude "$HS_PROMPT"';
+    if (cmd === 'opencode') return 'exec command opencode --prompt "$HS_PROMPT"';
+    // Fallback: start the tool and ask the user to paste.
+    return `exec command ${JSON.stringify(cmd)}`;
+  })();
+
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    '',
+    `cd ${JSON.stringify(cwd)}`,
+    '',
+    `echo ${JSON.stringify(t)}`,
+    'echo',
+    'echo "Prompt:"',
+    'echo "------------------------------------------------------------"',
+    'HS_PROMPT="$(cat <<\'HS_PROMPT_EOF\'',
+    prompt,
+    'HS_PROMPT_EOF',
+    ')"',
+    'echo "$HS_PROMPT"',
+    'echo "------------------------------------------------------------"',
+    'echo',
+    'if command -v pbcopy >/dev/null 2>&1; then',
+    '  printf "%s" "$HS_PROMPT" | pbcopy',
+    '  echo "Copied prompt to clipboard (pbcopy)."',
+    'fi',
+    'echo',
+    'echo "Press Enter to start now, or Ctrl+C to cancel."',
+    'read -r _',
+    execLine,
+    '',
+  ].join('\n');
+}
+
+export async function launchLlmAssistant({
+  rl: providedRl = null,
+  title,
+  subtitle,
+  promptText,
+  cwd,
+  preferredToolId = '',
+  env = process.env,
+  allowRunHere = true,
+  allowCopyOnly = true,
+  defaultPermissionMode = 'full-auto',
+}) {
+  const prompt = String(promptText ?? '').trimEnd();
+  const cd = String(cwd ?? '').trim();
+  if (!prompt) return { ok: false, reason: 'empty prompt' };
+  if (!cd) return { ok: false, reason: 'missing cwd' };
+
+  const tools = await detectInstalledLlmTools();
+  const terminalSupport = await canLaunchNewTerminal({ env });
+
+  if (tools.length === 0) {
+    return { ok: false, reason: 'no supported LLM CLI detected', terminalSupport };
+  }
+
+  const withMaybeRl = async (fn) => {
+    if (providedRl) return await fn(providedRl);
+    return await withRl(fn);
+  };
+
+  const chosenTool =
+    tools.length === 1
+      ? tools[0]
+      : tools.find((t) => t.id === preferredToolId) ||
+        (!isTty()
+          ? tools.find((t) => t.id === 'codex') || tools[0]
+          : await withMaybeRl(async (rl) => {
+              const defaultIndex = Math.max(0, tools.findIndex((t) => t.id === 'codex'));
+              const picked = await promptSelect(rl, {
+                title:
+                  `${bold('Pick an LLM CLI')}\n` +
+                  `${dim('We will launch it with a pre-filled migration prompt so it can run the port and resolve conflicts.')}`,
+                options: tools.map((t) => ({
+                  value: t.id,
+                  label: `${cyan(t.id)} — ${t.label}${t.note ? ` ${dim(`— ${t.note}`)}` : ''}`,
+                })),
+                defaultIndex,
+              });
+              return tools.find((t) => t.id === picked) || tools[0];
+            }));
+
+  const launchOptions = [];
+  if (terminalSupport.ok) {
+    launchOptions.push({ value: 'new-terminal', label: `${green('recommended')} — launch in a new terminal window` });
+  }
+  if (allowRunHere) {
+    launchOptions.push({ value: 'here', label: `run in this terminal ${dim('(will take over this session)')}` });
+  }
+  if (allowCopyOnly) {
+    launchOptions.push({ value: 'copy', label: `copy the prompt and run it yourself` });
+  }
+
+  const launchMode =
+    launchOptions.length === 1
+      ? launchOptions[0].value
+      : !isTty()
+        ? launchOptions[0].value
+        : await withMaybeRl(async (rl) => {
+            return await promptSelect(rl, {
+              title: `${bold('How do you want to run the migration assistant?')}`,
+              options: launchOptions,
+              defaultIndex: 0,
+            });
+          });
+
+  const permissionMode =
+    chosenTool.id !== 'codex'
+      ? null
+      : CODEX_PERMISSION_MODES.length === 1 || !isTty()
+        ? defaultPermissionMode
+        : await withMaybeRl(async (rl) => {
+            const opts = codexPermissionOptions();
+            const v = await promptSelect(rl, {
+              title:
+                `${bold('LLM permissions')}\n` +
+                `${dim('Choose how much autonomy the LLM should have while running commands to migrate + resolve conflicts.')}`,
+              options: opts,
+              defaultIndex: Math.max(0, opts.findIndex((o) => o.value === defaultPermissionMode)),
+            });
+            return String(v || defaultPermissionMode);
+          });
+
+  if (launchMode === 'copy') {
+    return { ok: true, launched: false, mode: 'copy', tool: chosenTool.id, permissionMode, terminalSupport };
+  }
+
+  // Auto-exec path (Codex only for now).
+  if (chosenTool.id === 'codex') {
+    if (launchMode === 'here') {
+      await runCodexExecHere({ cd, permissionMode: permissionMode || defaultPermissionMode, promptText: prompt, env });
+      return { ok: true, launched: true, mode: 'here', tool: chosenTool.id, permissionMode, terminalSupport };
+    }
+
+    // new-terminal
+    const script = buildCodexExecScript({ cd, permissionMode: permissionMode || defaultPermissionMode, promptText: prompt });
+    const res = await launchScriptInNewTerminal({ scriptText: script, title: title || 'hstack migration (LLM)' });
+    if (!res.ok) {
+      return { ok: false, reason: res.reason || 'failed to launch terminal', terminalSupport };
+    }
+    return { ok: true, launched: true, mode: 'new-terminal', tool: chosenTool.id, permissionMode, terminalSupport };
+  }
+
+  // Interactive launch path (Claude/OpenCode/Aider/etc).
+  // Best-effort: copy prompt to clipboard now; the terminal script will print it too.
+  if (await clipboardAvailable()) {
+    await copyTextToClipboard(prompt).catch(() => {});
+  }
+
+  if (launchMode === 'here') {
+    // Print prompt and then start the CLI (interactive).
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(banner(title || 'LLM prompt', { subtitle: subtitle || 'Paste this into your LLM CLI to run the migration.' }));
+    // eslint-disable-next-line no-console
+    console.log(prompt);
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(dim(`Starting: ${chosenTool.cmd}`));
+
+    if (chosenTool.cmd === 'claude') {
+      // Claude Code supports starting interactive mode with an initial prompt:
+      // `claude "query"`.
+      await run('claude', [prompt], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    } else if (chosenTool.cmd === 'opencode') {
+      // OpenCode supports starting the TUI with an initial prompt:
+      // `opencode --prompt "..."`.
+      await run('opencode', ['--prompt', prompt], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    } else {
+      await run(chosenTool.cmd, [], { cwd: cd, env: env ?? process.env, stdio: 'inherit' });
+    }
+    return { ok: true, launched: true, mode: 'here', tool: chosenTool.id, permissionMode, terminalSupport };
+  }
+
+  // new-terminal
+  const script = buildInteractiveLaunchScript({
+    toolCmd: chosenTool.cmd,
+    cd,
+    title: title || `hstack (${chosenTool.id})`,
+    promptText: prompt,
+  });
+  const res = await launchScriptInNewTerminal({ scriptText: script, title: title || `hstack (${chosenTool.id})` });
+  if (!res.ok) {
+    return { ok: false, reason: res.reason || 'failed to launch terminal', terminalSupport };
+  }
+  return { ok: true, launched: true, mode: 'new-terminal', tool: chosenTool.id, permissionMode, terminalSupport };
+}
+
+export async function printAndMaybeCopyPrompt({ promptText, copy = false }) {
+  const prompt = String(promptText ?? '').trimEnd();
+  // eslint-disable-next-line no-console
+  console.log(prompt);
+  if (!copy) return { ok: true, copied: false };
+  if (!(await clipboardAvailable())) return { ok: true, copied: false };
+  const res = await copyTextToClipboard(prompt);
+  return { ok: true, copied: Boolean(res.ok) };
+}
+
+export function renderLlmHelpBlock({ title, subtitle, promptText, detectedTools, terminalSupport }) {
+  const tools = Array.isArray(detectedTools) ? detectedTools : [];
+  const lines = [];
+  lines.push('');
+  lines.push(banner(title || 'LLM help', { subtitle: subtitle || 'Copy/paste this into your LLM to drive the migration.' }));
+  lines.push(promptText);
+  if (tools.length) {
+    lines.push('');
+    lines.push(sectionTitle('Detected LLM CLIs'));
+    lines.push(bullets(tools.map((t) => `- ${dim(t.id)}: ${t.label}${t.note ? ` ${dim(`— ${t.note}`)}` : ''}`)));
+  } else {
+    lines.push('');
+    lines.push(dim('No supported LLM CLI detected. You can still paste the prompt into any LLM UI.'));
+  }
+  if (terminalSupport?.ok) {
+    lines.push('');
+    lines.push(dim(`Terminal launch: ${green('supported')}`));
+  } else if (terminalSupport) {
+    lines.push('');
+    lines.push(dim(`Terminal launch: ${yellow('not available')} ${dim(`(${terminalSupport.reason || 'unknown'})`)}`));
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/scripts/utils/llm/codex_exec.mjs

@@ -0,0 +1,61 @@
+import { run } from '../proc/proc.mjs';
+
+export const CODEX_PERMISSION_MODES = /** @type {const} */ (['safe', 'full-auto', 'yolo']);
+
+export function buildCodexExecArgs({ cd, permissionMode }) {
+  const cwd = String(cd ?? '').trim();
+  if (!cwd) throw new Error('[llm] codex: missing cd');
+
+  const mode = String(permissionMode ?? '').trim() || 'full-auto';
+  if (!CODEX_PERMISSION_MODES.includes(mode)) {
+    throw new Error(`[llm] codex: invalid permission mode: ${mode}`);
+  }
+
+  const args = ['exec', '--cd', cwd];
+  if (mode === 'safe') {
+    args.push('--sandbox', 'workspace-write', '--ask-for-approval', 'on-request');
+  } else if (mode === 'full-auto') {
+    args.push('--full-auto');
+  } else if (mode === 'yolo') {
+    args.push('--dangerously-bypass-approvals-and-sandbox');
+  }
+
+  // Read the prompt from stdin.
+  args.push('-');
+  return args;
+}
+
+function pickHereDocMarker(text) {
+  const s = String(text ?? '');
+  for (let i = 0; i < 50; i++) {
+    const marker = `HS_CODEX_PROMPT_${Math.random().toString(16).slice(2)}_${Date.now()}`;
+    if (!s.includes(marker)) return marker;
+  }
+  return `HS_CODEX_PROMPT_${Date.now()}`;
+}
+
+export function buildCodexExecScript({ cd, permissionMode, promptText }) {
+  const args = buildCodexExecArgs({ cd, permissionMode });
+  const marker = pickHereDocMarker(promptText);
+  const prompt = String(promptText ?? '').trimEnd();
+
+  // Use `command` to avoid shell aliases and ensure the expected binary is used.
+  const codexCmd = ['command', 'codex', ...args.map((a) => JSON.stringify(String(a)))].join(' ');
+
+  return [
+    '#!/usr/bin/env bash',
+    'set -euo pipefail',
+    '',
+    `cat <<'${marker}' | ${codexCmd}`,
+    prompt,
+    marker,
+    '',
+  ].join('\n');
+}
+
+export async function runCodexExecHere({ cd, permissionMode, promptText, env }) {
+  const args = buildCodexExecArgs({ cd, permissionMode });
+  const input = String(promptText ?? '');
+  await run('codex', args, { cwd: cd, env: env ?? process.env, input });
+}
+

package/scripts/utils/llm/codex_exec.test.mjs

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildCodexExecArgs, buildCodexExecScript } from './codex_exec.mjs';
+
+test('buildCodexExecArgs builds stdin-prompt args for each permission mode', () => {
+  const cd = '/tmp/repo';
+
+  const safe = buildCodexExecArgs({ cd, permissionMode: 'safe' });
+  assert.deepEqual(safe, ['exec', '--cd', cd, '--sandbox', 'workspace-write', '--ask-for-approval', 'on-request', '-']);
+
+  const full = buildCodexExecArgs({ cd, permissionMode: 'full-auto' });
+  assert.deepEqual(full, ['exec', '--cd', cd, '--full-auto', '-']);
+
+  const yolo = buildCodexExecArgs({ cd, permissionMode: 'yolo' });
+  assert.deepEqual(yolo, ['exec', '--cd', cd, '--dangerously-bypass-approvals-and-sandbox', '-']);
+});
+
+test('buildCodexExecScript embeds prompt via heredoc', () => {
+  const script = buildCodexExecScript({ cd: '/tmp/repo', permissionMode: 'full-auto', promptText: 'hello\nworld\n' });
+  assert.ok(script.includes('cat <<'));
+  assert.ok(script.includes('hello'));
+  assert.ok(script.includes('world'));
+  assert.ok(script.includes('codex'));
+  assert.ok(script.includes('exec'));
+});
+
+test('buildCodexExecArgs defaults to full-auto when permission mode is blank', () => {
+  const args = buildCodexExecArgs({ cd: '/tmp/repo', permissionMode: '   ' });
+  assert.deepEqual(args, ['exec', '--cd', '/tmp/repo', '--full-auto', '-']);
+});
+
+test('buildCodexExecArgs rejects missing cd and invalid permission modes', () => {
+  assert.throws(() => buildCodexExecArgs({ cd: '', permissionMode: 'safe' }), /missing cd/i);
+  assert.throws(() => buildCodexExecArgs({ cd: '/tmp/repo', permissionMode: 'unsafe' }), /invalid permission mode/i);
+});
+
+test('buildCodexExecScript preserves quoted prompt content in heredoc body', () => {
+  const prompt = `Line "one"\nLine 'two'\n$HOME`;
+  const script = buildCodexExecScript({ cd: '/tmp/repo', permissionMode: 'safe', promptText: prompt });
+  assert.match(script, /cat <<'HS_CODEX_PROMPT_/);
+  assert.match(script, /Line "one"/);
+  assert.match(script, /Line 'two'/);
+  assert.match(script, /\$HOME/);
+  assert.match(script, /"--ask-for-approval" "on-request"/);
+});

package/scripts/utils/llm/hstack_runner.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Returns an absolute path to this package's `bin/hstack.mjs` if present.
+ * This is the most reliable way to re-run hstack commands from an LLM prompt
+ * when `npx` is unreliable (e.g. npm cache permission issues).
+ */
+export function resolveLocalhstackBinPath() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // scripts/utils/llm
+    const root = resolve(here, '../../..'); // package root (contains bin/ and scripts/)
+    const p = join(root, 'bin', 'hstack.mjs');
+    return existsSync(p) ? p : '';
+  } catch {
+    return '';
+  }
+}
+
+export function buildhstackRunnerShellSnippet({ preferLocalBin = true } = {}) {
+  const localBin = preferLocalBin ? resolveLocalhstackBinPath() : '';
+  const localClause = localBin
+    ? [
+        `hstack_LOCAL_BIN=${JSON.stringify(localBin)}`,
+        '  if [ -f "$hstack_LOCAL_BIN" ]; then',
+        '    node "$hstack_LOCAL_BIN" "$@"',
+        '    return $?',
+        '  fi',
+      ].join('\n')
+    : '';
+
+  return [
+    'hstack (Happier Stack) command runner:',
+    '- In the commands below, run `hstack ...`.',
+    '- This avoids `npx` flakiness by preferring a local `bin/hstack.mjs` when available.',
+    '',
+    '```bash',
+    'hstack() {',
+    '  # Prefer an installed `hstack` if present.',
+    '  if command -v hstack >/dev/null 2>&1; then',
+    '    command hstack "$@"',
+    '    return $?',
+    '  fi',
+    localClause,
+    '  # Fallback: npx. Work around broken ~/.npm perms by using a fresh writable cache dir.',
+    '  if command -v npx >/dev/null 2>&1; then',
+    '    local cache_dir',
+    '    cache_dir="${HAPPIER_STACK_NPX_CACHE_DIR:-$(mktemp -d)}"',
+    '    npm_config_cache="$cache_dir" npm_config_update_notifier=false npx --yes -p @happier-dev/stack@latest hstack "$@"',
+    '    return $?',
+    '  fi',
+    '  echo "Missing hstack and npx. Install Node/npm or install @happier-dev/stack."',
+    '  return 1',
+    '}',
+    '```',
+    '',
+  ].join('\n');
+}

package/scripts/utils/llm/tools.mjs

@@ -0,0 +1,56 @@
+import { commandExists } from '../proc/commands.mjs';
+
+/**
+ * We keep this list intentionally small and capability-driven.
+ * The important distinction is whether we can run an agent with a pre-filled prompt reliably.
+ */
+const KNOWN_LLM_TOOLS = [
+  {
+    id: 'codex',
+    cmd: 'codex',
+    label: 'Codex CLI',
+    note: 'Supports non-interactive runs with a prompt.',
+    supportsPromptStdin: true,
+    supportsAutoExec: true,
+  },
+  {
+    id: 'claude',
+    cmd: 'claude',
+    label: 'Claude CLI',
+    note: 'Supports starting interactive mode with an initial prompt.',
+    supportsPromptStdin: false,
+    supportsAutoExec: false,
+  },
+  {
+    id: 'opencode',
+    cmd: 'opencode',
+    label: 'OpenCode',
+    note: 'Supports starting TUI with an initial prompt.',
+    supportsPromptStdin: false,
+    supportsAutoExec: false,
+  },
+  {
+    id: 'aider',
+    cmd: 'aider',
+    label: 'Aider',
+    note: 'Prompt injection varies by mode; copy/paste fallback supported.',
+    supportsPromptStdin: false,
+    supportsAutoExec: false,
+  },
+];
+
+export function getKnownLlmTools() {
+  return [...KNOWN_LLM_TOOLS];
+}
+
+export async function detectInstalledLlmTools({ onlyAutoExec = false } = {}) {
+  const installed = [];
+  for (const t of KNOWN_LLM_TOOLS) {
+    if (onlyAutoExec && !t.supportsAutoExec) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const ok = await commandExists(t.cmd);
+    if (ok) installed.push(t);
+  }
+  return installed;
+}
+

package/scripts/utils/llm/tools.test.mjs

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { detectInstalledLlmTools } from './tools.mjs';
+
+async function writeStubCmd(binDir, name) {
+  const p = join(binDir, name);
+  await writeFile(p, ['#!/usr/bin/env bash', 'exit 0'].join('\n') + '\n', 'utf-8');
+  await chmod(p, 0o755);
+  return p;
+}
+
+function withPatchedPath(t, value) {
+  const prevPath = process.env.PATH;
+  t.after(() => {
+    process.env.PATH = prevPath;
+  });
+  process.env.PATH = value;
+}
+
+test('detectInstalledLlmTools finds tools on PATH and filters onlyAutoExec', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-llm-tools-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const binDir = join(root, 'bin');
+  await mkdir(binDir, { recursive: true });
+
+  await writeStubCmd(binDir, 'codex');
+  await writeStubCmd(binDir, 'claude');
+
+  withPatchedPath(t, `${binDir}:${process.env.PATH ?? ''}`);
+
+  const all = await detectInstalledLlmTools();
+  assert.ok(all.some((t) => t.id === 'codex'));
+  assert.ok(all.some((t) => t.id === 'claude'));
+
+  const auto = await detectInstalledLlmTools({ onlyAutoExec: true });
+  assert.deepEqual(
+    auto.map((t) => t.id),
+    ['codex']
+  );
+});
+
+test('detectInstalledLlmTools returns empty list when PATH is blank', async (t) => {
+  withPatchedPath(t, '');
+  const all = await detectInstalledLlmTools();
+  assert.deepEqual(all, []);
+});
+
+test('detectInstalledLlmTools onlyAutoExec excludes non-auto tools even when present', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-llm-tools-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+  const binDir = join(root, 'bin');
+  await mkdir(binDir, { recursive: true });
+  await writeStubCmd(binDir, 'claude');
+
+  withPatchedPath(t, binDir);
+  const auto = await detectInstalledLlmTools({ onlyAutoExec: true });
+  assert.deepEqual(auto, []);
+});

package/scripts/utils/menubar/swiftbar.mjs

@@ -0,0 +1,121 @@
+import { runCapture } from '../proc/proc.mjs';
+import { readdir, stat, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function expandHomeQuick(p) {
+  const s = String(p ?? '').trim();
+  if (!s) return '';
+  if (s === '~') return homedir();
+  if (s.startsWith('~/')) return join(homedir(), s.slice(2));
+  return s;
+}
+
+async function isDir(p) {
+  const s = String(p ?? '').trim();
+  if (!s) return false;
+  try {
+    const st = await stat(s);
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function globToRegExp(glob) {
+  // Minimal glob support for our SwiftBar plugin filenames:
+  // - `*` matches any chars
+  // - `?` matches a single char
+  const g = String(glob ?? '').trim();
+  if (!g) return null;
+  const esc = (ch) => String(ch).replace(/[\\^$.*+?()[\]{}|/]/g, '\\$&');
+  let out = '^';
+  for (const ch of g) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += esc(ch);
+  }
+  out += '$';
+  return new RegExp(out);
+}
+
+function parseBool(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+function isPluginEntry(entry) {
+  return Boolean(entry?.isFile?.() || entry?.isSymbolicLink?.());
+}
+
+export async function resolveSwiftbarPluginsDir({ env = process.env } = {}) {
+  const override = (env.HAPPIER_STACK_SWIFTBAR_PLUGINS_DIR ?? '').trim();
+  if (override) {
+    const allowNonDarwinOverride = parseBool(env.HAPPIER_STACK_SWIFTBAR_ALLOW_OVERRIDE_NON_DARWIN);
+    if (process.platform !== 'darwin' && !allowNonDarwinOverride) {
+      return null;
+    }
+    const dir = expandHomeQuick(override);
+    return (await isDir(dir)) ? dir : null;
+  }
+
+  if (process.platform !== 'darwin') return null;
+  try {
+    const dir = (await runCapture('bash', [
+      '-lc',
+      'DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; if [[ -n "$DIR" && -d "$DIR" ]]; then echo "$DIR"; exit 0; fi; D="$HOME/Library/Application Support/SwiftBar/Plugins"; if [[ -d "$D" ]]; then echo "$D"; exit 0; fi; echo ""',
+    ])).trim();
+    return dir || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function detectSwiftbarPluginInstalled({ pluginsDir, patterns = null, env = process.env } = {}) {
+  const dir = pluginsDir ?? (await resolveSwiftbarPluginsDir({ env }));
+  if (!dir) return { pluginsDir: null, installed: false };
+
+  const pats = Array.isArray(patterns) && patterns.length ? patterns : ['hstack.*.sh'];
+  const regs = pats.map(globToRegExp).filter(Boolean);
+  if (regs.length === 0) return { pluginsDir: dir, installed: false };
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!isPluginEntry(e)) continue;
+      if (regs.some((r) => r.test(e.name))) {
+        return { pluginsDir: dir, installed: true };
+      }
+    }
+    return { pluginsDir: dir, installed: false };
+  } catch {
+    return { pluginsDir: dir, installed: false };
+  }
+}
+
+export async function removeSwiftbarPlugins({ pluginsDir, patterns = null, env = process.env } = {}) {
+  const dir = pluginsDir ?? (await resolveSwiftbarPluginsDir({ env }));
+  if (!dir) return { ok: true, removed: false, pluginsDir: null };
+
+  const pats = Array.isArray(patterns) && patterns.length ? patterns : ['hstack.*.sh'];
+  const regs = pats.map(globToRegExp).filter(Boolean);
+  if (regs.length === 0) return { ok: true, removed: false, pluginsDir: dir };
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    let removed = false;
+    for (const e of entries) {
+      if (!isPluginEntry(e)) continue;
+      if (!regs.some((r) => r.test(e.name))) continue;
+      try {
+        await unlink(join(dir, e.name));
+        removed = true;
+      } catch {
+        // ignore per-file errors (best effort)
+      }
+    }
+    return { ok: true, removed, pluginsDir: dir };
+  } catch {
+    return { ok: false, removed: false, pluginsDir: dir };
+  }
+}