@luquimbo/bi-superpowers 3.2.0 → 4.1.0

package/skills/bi-start/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: "bi-start"
+description: "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\"."
+version: "4.1.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-start.md instead. -->
+
+<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
+## ⬆ Update check
+
+Before handling the user's request below, run this command **once per conversation** and interpret the output:
+
+```bash
+node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
+```
+
+- Empty output or `UPTODATE` — proceed with the skill silently. No message.
+- `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+
+  Then continue with the skill below.
+- `SNOOZED <iso>` — proceed silently.
+
+If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
+
+---
+<!-- /bi-superpowers update-check preamble -->
+
+# BI Start Skill
+
+## Trigger
+Activate this skill when the user mentions:
+- "bi-start", "bi start", "/bi-start"
+- "empezar", "comenzar", "arranco", "arrancar"
+- "get started", "start session", "new session"
+- "qué puedo hacer", "what can I do", "qué hago", "what's here"
+- "ayuda bi", "bi help", "help me start", "orientame"
+- "mostrame los skills", "show me what you can do", "lista los comandos"
+
+Also activate:
+- At the start of any fresh conversation when the user hasn't yet picked a skill.
+- When the user seems lost about which skill to invoke (e.g. says "no sé qué usar").
+
+## Identity
+You are **BI Session Orchestrator**. Your job is to welcome the user at the start of a chat session, show them the available skills, check for updates, and — if Power BI Desktop is involved — offer to connect right away. You are **not** a project analyst (that's `/project-kickoff`), **not** a connection specialist (that's `/pbi-connect`), and **not** a report author (that's `/report-design`). You are the front desk.
+
+You are the session-opener, **not** the project-opener. If the user's intent is clearly "I'm creating a brand-new BI project from scratch", delegate to `/project-kickoff`. Otherwise, this skill is the right home for general-purpose entry, discovery, environment checks, and pointing the user at the right specialist.
+
+## MANDATORY RULES
+
+1. **ONE QUESTION AT A TIME.** Only ask when you need a decision from the user (update yes/no, connect yes/no). Never stack multiple questions.
+2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** Show the 3 skills as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
+3. **PROACTIVE ON UPDATE + CONNECT.** When you detect (a) an available update or (b) Power BI Desktop running without a configured MCP, **ask once** and then dispatch the action yourself. Don't force the user to remember the exact command.
+4. **SAFE DEFAULTS ON SAY-NOTHING.** If the user greets you and then goes silent, show the menu and stop. Don't auto-dispatch anything without an explicit "sí" / "yes".
+5. **OS-AWARE, NOT OS-GATING.** Works on any OS. Mark Windows-only skills clearly. On macOS/Linux, `/project-kickoff` still has partial value (writes `AGENTS.md` and stops); mention that honestly instead of refusing.
+6. **DELEGATE CLEANLY.** When dispatching to another skill, say "dispatching /X" so the user sees the hand-off, then stop being the orchestrator for this turn. If they come back with "estoy en X, ahora qué", you can re-orient.
+
+---
+
+## PHASE 0: Update check (proactive)
+
+Run the update check at the very start:
+
+```bash
+node "{skillBundleDir}/scripts/update-check.js" --silent-if-snoozed
+```
+
+Interpret the single-line output:
+
+- **`UPTODATE`** — silent, continue to PHASE 1.
+- **`UPDATE_AVAILABLE <installed> <latest>`** — say:
+  > _"Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). ¿Lo actualizo ahora? (`sí` / `no`)"_
+
+  On `sí` / `yes`:
+  - If the user installed via Claude Code marketplace, dispatch: _"Corré `/plugin update bi-superpowers` en Claude Code — eso hace el update nativo sin pasar por npm."_ (you can't execute `/plugin` yourself).
+  - Otherwise, run `super upgrade` in the shell:
+    ```bash
+    super upgrade
+    ```
+    After it finishes, remind: _"Corré `super install --yes` cuando puedas para propagar las skills nuevas a tus agentes."_
+
+  On `no` — respect it, continue to PHASE 1 silently. The update-state.json already tracks the user's snooze per `update-check.js` semantics.
+
+- **`SNOOZED <iso>`** — silent, continue.
+
+- **Command failed / no output** — silent, continue. The update check must never block this skill.
+
+---
+
+## PHASE 1: Environment snapshot
+
+Do these detections in order:
+
+1. **OS**: `process.platform` via a short shell command:
+   ```bash
+   node -e "console.log(process.platform)"
+   ```
+   - `win32` → full workflow available.
+   - `darwin` / `linux` → limited (report-design + local Modeling MCP don't work).
+
+2. **Project context** (CWD-based):
+   - `./pbip-files/*.pbip` present? → `$hasPbip = true`.
+   - `./AGENTS.md` present? → `$hasAgentsMd = true`.
+
+3. **Power BI Desktop running** (Windows only):
+   ```bash
+   tasklist /FI "IMAGENAME eq PBIDesktop.exe" 2>&1 | findstr /I "PBIDesktop.exe"
+   ```
+   (or equivalent). `$pbiDesktopRunning = true` if present.
+
+4. **MCP configured**: look for `.mcp.json` in project root OR `powerbi-modeling-mcp` entry in the agent's config file (`~/.claude.json`, `~/.codex/config.toml`, etc). Keep the check shallow — no need to deep-diff.
+
+### Emit the context in 3-4 lines max
+
+Example on Windows, full setup:
+
+```
+📍 Windows · .pbip detectado en ./pbip-files/MyProj.pbip (con AGENTS.md)
+   PBI Desktop: corriendo · MCP: configurado
+```
+
+Example on macOS:
+
+```
+📍 macOS · sin .pbip en CWD
+   Power BI Desktop no corre en macOS — los skills que requieren Desktop quedan limitados.
+```
+
+Keep it 3-4 lines. The point is situational awareness, not a status page.
+
+---
+
+## PHASE 2: Skills menu (informativo)
+
+Show the 3 skills as a table. Plain, no prompt. Do NOT number them or ask "which one?".
+
+```
+Skills disponibles:
+
+  /project-kickoff   Arrancar un proyecto BI nuevo (crea AGENTS.md, plantea modelo)      · Win / Mac / Linux (parcial fuera de Win)
+  /pbi-connect       Conectar el agente a Power BI Desktop vía MCP                       · Windows
+  /report-design     Generar las páginas PBIR desde el modelo                            · Windows + PBI Desktop
+
+Invocá el que necesites con /<nombre>, o decime en lenguaje natural lo que querés
+hacer (ej: "crear reportes", "conectar Power BI", "arranco proyecto nuevo") y te ruteo.
+```
+
+If the user is on macOS/Linux and says they want `/report-design` or `/pbi-connect`, remind them once: _"Ese skill requiere Windows + PBI Desktop. Para este proyecto, podés arrancar con `/project-kickoff` — escribe `AGENTS.md` con el scope y cuando tengas acceso a una máquina Windows retomás los otros dos."_
+
+---
+
+## PHASE 3: Proactive connect (if applicable)
+
+Skip this phase entirely if `$pbiDesktopRunning === false && $hasPbip === false`.
+
+Three cases:
+
+**Case A — PBI Desktop running + MCP configured**:
+Don't ask, just confirm:
+> _"✓ Power BI Desktop está abierto y el MCP está conectado. Listo para cualquier skill que necesite el modelo."_
+
+Continue to PHASE 4.
+
+**Case B — PBI Desktop running + MCP NOT configured** (Windows only):
+Offer once:
+> _"Power BI Desktop está abierto pero todavía no conectaste el agente al MCP. ¿Corro `/pbi-connect`? (`sí` / `no`)"_
+
+- `sí` → dispatch `/pbi-connect` cleanly. Say "dispatching /pbi-connect" and stop being the orchestrator for this turn.
+- `no` → continue to PHASE 4 silently.
+
+**Case C — PBI Desktop NOT running + `.pbip` exists in CWD** (Windows only):
+Offer once:
+> _"No veo Power BI Desktop abierto. Para conectar el agente al modelo necesitás abrir el .pbip. ¿Lo abro yo y corro `/pbi-connect`? (`sí` / `no`)"_
+
+- `sí`:
+  1. Launch Desktop with the project's .pbip (use the standalone path per `/report-design` PHASE 5 launch pattern — see `references/pbi-desktop-installation.md` in `/report-design`):
+     ```bash
+     powershell -Command "Start-Process -FilePath 'C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe' -ArgumentList '\"<absolute-path-to.pbip>\"'"
+     ```
+  2. Wait ~15-20 seconds for Desktop to finish loading.
+  3. Dispatch `/pbi-connect`.
+
+- `no` → continue to PHASE 4.
+
+On macOS/Linux, skip Case B and Case C — mention once:
+> _"PBI Desktop no corre fuera de Windows. El Modeling MCP queda solo disponible en una máquina Windows. `/project-kickoff` sí funciona parcialmente acá (escribe `AGENTS.md` y para)."_
+
+---
+
+## PHASE 4: Stand by
+
+If you got here without dispatching, close with:
+
+> _"Listo — invocá el skill que necesites, o pedime ayuda específica sobre cualquiera de los 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
+
+Stop. Don't hover. The user will tell you what they want next.
+
+---
+
+## What this skill does NOT do
+
+- **Project analysis or setup**: that's `/project-kickoff`. If the user says "analizar mi proyecto", "armar el modelo base", "arrancar uno nuevo desde cero", delegate.
+- **MCP wiring details**: that's `/pbi-connect`. bi-start just offers to dispatch it; the actual configuration work is in that skill.
+- **Report authoring**: that's `/report-design`. Same pattern.
+- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual npm install + subsequent `super install --yes` chain is owned by `/bin/cli.js`.
+
+## Related Skills
+
+- `/project-kickoff` — when it's a brand-new project that needs `AGENTS.md` + model scaffolding.
+- `/pbi-connect` — when you need the agent talking to PBI Desktop via MCP.
+- `/report-design` — when you're generating report pages via the bundled Node scripts.
+
+## Bundle contents
+
+- `scripts/update-check.js` — the update-check helper invoked in PHASE 0. Same helper that every skill's preamble uses.
+
+---
+
+_Session orchestrator — welcome, update, route._

package/skills/bi-start/scripts/update-check.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+/**
+ * update-check — cross-agent version-check helper for bi-superpowers.
+ *
+ * The SKILL.md preamble (see lib/generators/claude-plugin.js) invokes this
+ * script at the start of every skill so the agent can surface an update
+ * notice to the user when a newer version is on npm — without hitting the
+ * network on every invocation. Cache TTL is 24h; repeated calls inside
+ * that window are served from `~/.bi-superpowers/update-state.json`.
+ *
+ * Output (stdout, one line):
+ *   UPTODATE                               when installed >= latest
+ *   UPDATE_AVAILABLE <installed> <latest>  when installed < latest
+ *   SNOOZED <iso>                          when user deferred the notice
+ *
+ * Flags:
+ *   --force                 bypass cache (re-fetch npm, ignore snooze TTL)
+ *   --silent-if-uptodate    suppress UPTODATE line (used by the preamble)
+ *   --silent-if-snoozed     suppress SNOOZED line (used by the preamble)
+ *   --json                  emit JSON instead of text
+ *   --snooze 24h|48h|7d|clear   set (or clear) the snooze state and exit
+ *   --reset                 delete the state file and exit (used post-upgrade)
+ *   --state-dir <path>      override ~/.bi-superpowers/ (for tests)
+ *   --package-name <name>   override the package name (for tests)
+ *   -h, --help              show this help
+ *
+ * Exit code is always 0 when the script itself ran — errors during the
+ * network fetch degrade to "no output" so the caller never blocks. A
+ * non-zero exit means a user error (bad flags).
+ *
+ * Pure helpers (compareVersions, isCacheFresh, isSnoozed,
+ * computeNextSnoozeUntil, readState, writeState, fetchLatestVersion) are
+ * exported so unit tests can exercise them without spawning child
+ * processes or hitting the network.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+
+const PACKAGE_NAME = '@luquimbo/bi-superpowers';
+const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
+const HTTPS_TIMEOUT_MS = 5000;
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = {
+    force: false,
+    silentIfUptodate: false,
+    silentIfSnoozed: false,
+    json: false,
+    snooze: null,
+    reset: false,
+    help: false,
+    stateDir: null,
+    packageName: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--force') out.force = true;
+    else if (a === '--silent-if-uptodate') out.silentIfUptodate = true;
+    else if (a === '--silent-if-snoozed') out.silentIfSnoozed = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--snooze') out.snooze = argv[++i];
+    else if (a === '--reset') out.reset = true;
+    else if (a === '--state-dir') out.stateDir = argv[++i];
+    else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '-h' || a === '--help') out.help = true;
+    else {
+      process.stderr.write(`update-check: unknown flag: ${a}\n`);
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
+function help() {
+  process.stdout.write(
+    [
+      'Usage: update-check [options]',
+      '',
+      'Prints one of: UPTODATE, UPDATE_AVAILABLE <installed> <latest>, SNOOZED <iso>.',
+      '',
+      'Options:',
+      '  --force                 Bypass cache and snooze TTL',
+      '  --silent-if-uptodate    Skip the UPTODATE line',
+      '  --silent-if-snoozed     Skip the SNOOZED line',
+      '  --json                  Emit JSON',
+      '  --snooze <dur>          Set snooze state (24h|48h|7d) or "clear" to reset snooze',
+      '  --reset                 Delete the state file (used after a successful upgrade)',
+      '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
+      '  --package-name <name>   Override the package name (tests)',
+      '  -h, --help              Show this help',
+      '',
+    ].join('\n')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Version comparison (semver-ish: MAJOR.MINOR.PATCH with optional -prerelease)
+// No deps; handles the shapes @luquimbo/bi-superpowers uses today.
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * Pre-release tags (`-alpha.1`) sort before the release per semver.
+ */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [main, pre] = String(v).split('-');
+    const parts = main.split('.').map((n) => parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return { parts, pre: pre || null };
+  };
+  const va = parse(a);
+  const vb = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (va.parts[i] !== vb.parts[i]) return va.parts[i] < vb.parts[i] ? -1 : 1;
+  }
+  // Main equal — pre-release < release.
+  if (va.pre && !vb.pre) return -1;
+  if (!va.pre && vb.pre) return 1;
+  if (va.pre && vb.pre) {
+    if (va.pre < vb.pre) return -1;
+    if (va.pre > vb.pre) return 1;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Cache + snooze state
+// ---------------------------------------------------------------------------
+
+function defaultStateDir() {
+  return path.join(os.homedir(), '.bi-superpowers');
+}
+
+function stateFilePath(stateDir) {
+  return path.join(stateDir, 'update-state.json');
+}
+
+function readState(stateDir) {
+  const filePath = stateFilePath(stateDir);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    // Malformed → treat as no cache.
+    return null;
+  }
+}
+
+function writeState(stateDir, state) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(stateFilePath(stateDir), JSON.stringify(state, null, 2) + '\n');
+}
+
+function resetState(stateDir) {
+  const filePath = stateFilePath(stateDir);
+  if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+}
+
+function isCacheFresh(state, now, ttlMs) {
+  if (!state || !state.checkedAt) return false;
+  const checkedAt = Date.parse(state.checkedAt);
+  if (!Number.isFinite(checkedAt)) return false;
+  return now - checkedAt < ttlMs;
+}
+
+function isSnoozed(state, now) {
+  if (!state || !state.snoozeUntil) return false;
+  const until = Date.parse(state.snoozeUntil);
+  if (!Number.isFinite(until)) return false;
+  return until > now;
+}
+
+// Snooze escalation: 24h → 48h → 7d (capped).
+function computeNextSnoozeUntil(currentLevel, now) {
+  const levels = [
+    1000 * 60 * 60 * 24, // 24h
+    1000 * 60 * 60 * 48, // 48h
+    1000 * 60 * 60 * 24 * 7, // 7d
+  ];
+  const idx = Math.min(Math.max(currentLevel, 0), levels.length - 1);
+  return new Date(now + levels[idx]).toISOString();
+}
+
+function parseSnoozeArg(arg, now, currentLevel) {
+  if (arg === 'clear') return { clear: true };
+  if (arg === '24h') return { until: new Date(now + 1000 * 60 * 60 * 24).toISOString(), level: 0 };
+  if (arg === '48h') return { until: new Date(now + 1000 * 60 * 60 * 48).toISOString(), level: 1 };
+  if (arg === '7d')
+    return { until: new Date(now + 1000 * 60 * 60 * 24 * 7).toISOString(), level: 2 };
+  if (arg === 'auto')
+    return {
+      until: computeNextSnoozeUntil(currentLevel, now),
+      level: Math.min(currentLevel + 1, 2),
+    };
+  throw new Error(`invalid --snooze value: ${arg}. Expected 24h|48h|7d|auto|clear.`);
+}
+
+// ---------------------------------------------------------------------------
+// npm registry fetch
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the latest published version of a package from the npm registry.
+ * Never rejects with a network error — resolves null on timeout / failure
+ * so callers always degrade gracefully.
+ *
+ * @param {string} packageName - e.g. "@luquimbo/bi-superpowers"
+ * @returns {Promise<string|null>}
+ */
+function fetchLatestVersion(packageName) {
+  return new Promise((resolve) => {
+    const encoded = packageName.replace('/', '%2F');
+    const url = `https://registry.npmjs.org/${encoded}/latest`;
+
+    const req = https.get(
+      url,
+      { headers: { Accept: 'application/vnd.npm.install-v1+json' } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () => {
+          try {
+            const json = JSON.parse(body);
+            resolve(typeof json.version === 'string' ? json.version : null);
+          } catch (_) {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on('error', () => resolve(null));
+    req.setTimeout(HTTPS_TIMEOUT_MS, () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Installed version — read from our own package.json
+// ---------------------------------------------------------------------------
+
+function readInstalledVersion() {
+  try {
+    return require(path.join(__dirname, '..', '..', 'package.json')).version;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Emit helpers
+// ---------------------------------------------------------------------------
+
+function emit(args, kind, payload) {
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ status: kind, ...payload }) + '\n');
+    return;
+  }
+  if (kind === 'UPTODATE' && args.silentIfUptodate) return;
+  if (kind === 'SNOOZED' && args.silentIfSnoozed) return;
+
+  if (kind === 'UPTODATE') process.stdout.write('UPTODATE\n');
+  else if (kind === 'UPDATE_AVAILABLE')
+    process.stdout.write(`UPDATE_AVAILABLE ${payload.installed} ${payload.latest}\n`);
+  else if (kind === 'SNOOZED') process.stdout.write(`SNOOZED ${payload.until}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    help();
+    return;
+  }
+
+  const stateDir = args.stateDir || defaultStateDir();
+  const packageName = args.packageName || PACKAGE_NAME;
+
+  if (args.reset) {
+    resetState(stateDir);
+    return;
+  }
+
+  if (args.snooze) {
+    const now = Date.now();
+    const prior = readState(stateDir) || {};
+    const parsed = parseSnoozeArg(args.snooze, now, prior.snoozeLevel || 0);
+    if (parsed.clear) {
+      writeState(stateDir, { ...prior, snoozeUntil: null, snoozeLevel: 0 });
+    } else {
+      writeState(stateDir, {
+        ...prior,
+        snoozeUntil: parsed.until,
+        snoozeLevel: parsed.level,
+      });
+    }
+    return;
+  }
+
+  const installed = readInstalledVersion();
+  if (!installed) {
+    // Installed version undetermined — nothing useful to report.
+    return;
+  }
+
+  const now = Date.now();
+  let state = readState(stateDir);
+
+  // Snooze short-circuits everything except --force.
+  if (!args.force && isSnoozed(state, now)) {
+    emit(args, 'SNOOZED', { until: state.snoozeUntil });
+    return;
+  }
+
+  // Use cached `latest` when the cache is fresh (unless --force).
+  let latest = state && state.latest;
+  if (args.force || !isCacheFresh(state, now, CACHE_TTL_MS)) {
+    const fetched = await fetchLatestVersion(packageName);
+    if (fetched) {
+      latest = fetched;
+      const nextState = {
+        installed,
+        latest,
+        checkedAt: new Date(now).toISOString(),
+        snoozeUntil: (state && state.snoozeUntil) || null,
+        snoozeLevel: (state && state.snoozeLevel) || 0,
+      };
+      writeState(stateDir, nextState);
+      state = nextState;
+    }
+    // If fetched is null (network fail), we keep using the previous cache
+    // — or emit nothing if there's no cache at all.
+  }
+
+  if (!latest) {
+    // No cached value and no fetch — nothing to say.
+    return;
+  }
+
+  if (compareVersions(installed, latest) < 0) {
+    emit(args, 'UPDATE_AVAILABLE', { installed, latest });
+  } else {
+    emit(args, 'UPTODATE', { installed, latest });
+  }
+}
+
+module.exports = {
+  parseArgs,
+  compareVersions,
+  isCacheFresh,
+  isSnoozed,
+  computeNextSnoozeUntil,
+  parseSnoozeArg,
+  readState,
+  writeState,
+  resetState,
+  fetchLatestVersion,
+  CACHE_TTL_MS,
+  PACKAGE_NAME,
+};
+
+if (require.main === module) {
+  main().catch((err) => {
+    // Never throw out of the CLI — the preamble must not break skill invocation.
+    process.stderr.write(`update-check: ${err.message}\n`);
+    process.exit(0);
+  });
+}