bi-superpowers 1.0.0

package/bin/lib/agents.js

@@ -0,0 +1,62 @@
+/**
+ * Agent Registry - Supported AI coding agents
+ * =============================================
+ *
+ * Single source of truth for the agents that bi-superpowers officially
+ * supports. Used by the install command (skill installation paths) and
+ * any future command that needs to know which agents exist.
+ *
+ * Each agent has:
+ * - A stable ID (used as CLI flag value, e.g. --agent claude-code)
+ * - A human-readable name (shown in the UI)
+ * - A directory relative to the user's home where its skills live
+ *
+ * UNIVERSAL_DIR is the path most agents read from by convention
+ * (.agents/skills/). The installer always writes here first, then
+ * symlinks agent-specific directories to it. Agents whose dir === UNIVERSAL_DIR
+ * (e.g. Codex, OpenCode) are served directly by the universal install.
+ *
+ * @module lib/agents
+ */
+
+/**
+ * Supported agents, in the order they appear in the interactive installer.
+ * Object insertion order matters — the installer renders the list in this order.
+ *
+ * IMPORTANT: the `dir` values are the USER-LEVEL skill directories for each
+ * agent. They're relative to the user's home directory (installed with
+ * `super install` at ~/). Each path comes from official docs — if you
+ * change one, verify it against the linked source first.
+ *
+ * Source docs:
+ * - GitHub Copilot: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills
+ *   "For personal skills, shared across projects, use ~/.copilot/skills"
+ *   (NOT ~/.github/skills — that's project-level for the cloud agent.)
+ * - Claude Code: https://code.claude.com/docs/en/skills
+ *   "Personal skills go in ~/.claude/skills/"
+ * - Codex: https://developers.openai.com/codex/skills
+ *   "Personal skills go in ~/.codex/skills or ~/.agents/skills"
+ *   We use the universal ~/.agents/skills path.
+ * - Gemini CLI: https://geminicli.com/docs/cli/skills/
+ *   "User skills in $HOME/.gemini/skills"
+ * - Kilo Code: https://kilo.ai/docs/customize/skills
+ *   "Global skills in ~/.kilo/skills/" (NOT ~/.kilocode/)
+ */
+const AGENTS = {
+  'github-copilot': { name: 'GitHub Copilot', dir: '.copilot/skills' },
+  'claude-code': { name: 'Claude Code', dir: '.claude/skills' },
+  codex: { name: 'Codex (OpenAI)', dir: '.agents/skills' },
+  'gemini-cli': { name: 'Gemini CLI', dir: '.gemini/skills' },
+  kilo: { name: 'Kilo Code', dir: '.kilo/skills' },
+};
+
+/**
+ * Universal path — most agents read from .agents/skills/ by the Agent Skills spec.
+ * The installer copies skills here first and symlinks agent-specific dirs to it.
+ */
+const UNIVERSAL_DIR = '.agents/skills';
+
+module.exports = {
+  AGENTS,
+  UNIVERSAL_DIR,
+};

package/bin/lib/base-template-smoke.js

@@ -0,0 +1,299 @@
+/**
+ * Base Template Live Smoke Test Helpers
+ * =====================================
+ *
+ * Runs the canonical base-template validation playbook against the running
+ * Power BI Desktop session. The helper probes each local Desktop instance and
+ * keeps the one whose live evidence matches the template contract.
+ *
+ * @module lib/base-template-smoke
+ */
+
+const fs = require('fs');
+const path = require('path');
+const mcpDetect = require('../utils/mcp-detect');
+const { createPowerBiMcpSession } = require('./powerbi-mcp-session');
+
+const BASE_TEMPLATE_CASE_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  'validation',
+  'cases',
+  'base-template-smoke-test.md'
+);
+
+const SMOKE_QUERY_PATTERN = /## Smoke Query\s+```DAX\s+([\s\S]*?)```/i;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const DEMO_CUSTOMER_COUNT = 210;
+
+function extractSmokeQuery(caseMarkdown) {
+  const match = caseMarkdown.match(SMOKE_QUERY_PATTERN);
+  if (!match) {
+    throw new Error('Unable to find the smoke query in the validation case.');
+  }
+
+  return match[1].trim();
+}
+
+function formatLocalDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function addLocalDays(date, days) {
+  const result = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  result.setDate(result.getDate() + days);
+  return result;
+}
+
+function startOfMondayWeek(date) {
+  const result = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  const mondayOffset = (result.getDay() + 6) % 7;
+  result.setDate(result.getDate() - mondayOffset);
+  return result;
+}
+
+function countMondayWeeks(startDate, endDate) {
+  const firstWeek = startOfMondayWeek(startDate);
+  const lastWeek = startOfMondayWeek(endDate);
+  return Math.floor((lastWeek.getTime() - firstWeek.getTime()) / WEEK_MS) + 1;
+}
+
+function estimateVentasRows(weekCount, customerCount = DEMO_CUSTOMER_COUNT) {
+  let rows = 0;
+
+  for (let weekNumber = 1; weekNumber <= weekCount; weekNumber++) {
+    rows += Math.min(customerCount, weekNumber * 2);
+  }
+
+  return rows;
+}
+
+function getExpectedSmokeEvidence(referenceDate = new Date()) {
+  const currentDate = new Date(
+    referenceDate.getFullYear(),
+    referenceDate.getMonth(),
+    referenceDate.getDate()
+  );
+  const minDate = addLocalDays(currentDate, -729);
+  const validationStartDate = addLocalDays(currentDate, -719);
+  const ventasWeeks = countMondayWeeks(minDate, currentDate);
+  const validationWeeks = countMondayWeeks(validationStartDate, currentDate);
+
+  return {
+    Metricas: '56',
+    Equipos: '9',
+    BridgeRows: '63',
+    MetricTeamMin: '7',
+    MetricTeamMax: '7',
+    WindowWeeks: String(validationWeeks),
+    FactTablesWithFullWeeks: '13',
+    MetricCoverageFailures: '0',
+    MetricDimensionPairs: '379',
+    MetricDimensionFailures: '0',
+    VentasRows: String(estimateVentasRows(ventasWeeks)),
+    MinFecha: formatLocalDate(minDate),
+    MaxFecha: formatLocalDate(currentDate),
+  };
+}
+
+function normalizeMcpJsonResult(toolResult) {
+  const textContent = (toolResult && toolResult.content) || [];
+  const textItem = textContent.find((entry) => entry && entry.type === 'text' && entry.text);
+
+  if (!textItem) {
+    throw new Error('MCP response did not include a text payload.');
+  }
+
+  try {
+    return JSON.parse(textItem.text);
+  } catch (error) {
+    throw new Error(`Unable to parse MCP JSON payload: ${error.message}`);
+  }
+}
+
+function extractCsvText(toolResult) {
+  const resourceItems = (toolResult && toolResult.content) || [];
+  const resourceItem = resourceItems.find(
+    (entry) => entry && entry.type === 'resource' && entry.resource
+  );
+
+  if (!resourceItem || typeof resourceItem.resource.text !== 'string') {
+    throw new Error('DAX query result did not include a CSV resource.');
+  }
+
+  return resourceItem.resource.text;
+}
+
+function parseSingleRowCsv(csvText) {
+  const lines = String(csvText)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  if (lines.length < 2) {
+    throw new Error('Expected a CSV header and one data row from the smoke query.');
+  }
+
+  const headers = lines[0].split(',').map((header) => header.replace(/^\[(.*)\]$/, '$1'));
+  const values = lines[1].split(',');
+  const row = {};
+
+  headers.forEach((header, index) => {
+    row[header] = values[index] != null ? values[index] : '';
+  });
+
+  return row;
+}
+
+function selectConnectionForPort(connections, port) {
+  const portText = `localhost:${port}`;
+  const matchingConnections = connections.filter((connection) => {
+    return (
+      connection &&
+      typeof connection.serverConnectionString === 'string' &&
+      connection.serverConnectionString.includes(portText)
+    );
+  });
+
+  const candidates = matchingConnections.length > 0 ? matchingConnections : connections;
+  return candidates.slice().sort((left, right) => {
+    const leftTime = new Date(left.connectedAt || 0).getTime();
+    const rightTime = new Date(right.connectedAt || 0).getTime();
+    return rightTime - leftTime;
+  })[0];
+}
+
+function isExpectedSmokeEvidence(row, expected) {
+  return Object.entries(expected).every(([key, value]) => String(row[key] ?? '') === String(value));
+}
+
+function formatEvidence(row) {
+  return Object.entries(row)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(', ');
+}
+
+async function runBaseTemplateLiveSmokeTest(options = {}) {
+  const casePath = options.casePath || BASE_TEMPLATE_CASE_PATH;
+  const sessionFactory = options.sessionFactory || ((exePath) => createPowerBiMcpSession(exePath));
+  const referenceDate = options.referenceDate || new Date();
+  const serverPath = options.mcpPath || mcpDetect.findLocalMcp();
+
+  if (!serverPath) {
+    throw new Error(mcpDetect.getModelingMcpError());
+  }
+
+  if (!fs.existsSync(casePath)) {
+    throw new Error(`Smoke test case not found: ${casePath}`);
+  }
+
+  const smokeQuery = extractSmokeQuery(fs.readFileSync(casePath, 'utf8'));
+  const expected = getExpectedSmokeEvidence(referenceDate);
+  const session = sessionFactory(serverPath);
+  const attempts = [];
+
+  try {
+    await session.initialize(options.clientInfo);
+
+    const localInstancesResult = await session.callTool('connection_operations', {
+      request: {
+        operation: 'ListLocalInstances',
+      },
+    });
+    const localInstances = normalizeMcpJsonResult(localInstancesResult).data || [];
+
+    for (const instance of localInstances) {
+      const attempt = {
+        processId: instance.processId,
+        port: instance.port,
+        connectionName: null,
+        observed: null,
+        matched: false,
+        error: null,
+      };
+
+      try {
+        await session.callTool('connection_operations', {
+          request: {
+            operation: 'Connect',
+            connectionString: `Provider=MSOLAP;Data Source=localhost:${instance.port};Application Name=MCP-PBIModeling`,
+          },
+        });
+
+        const connectionsResult = await session.callTool('connection_operations', {
+          request: {
+            operation: 'ListConnections',
+          },
+        });
+        const connections = normalizeMcpJsonResult(connectionsResult).data || [];
+        const selectedConnection = selectConnectionForPort(connections, instance.port);
+        attempt.connectionName = selectedConnection ? selectedConnection.connectionName : null;
+
+        const daxResult = await session.callTool('dax_query_operations', {
+          request: {
+            operation: 'Execute',
+            connectionName: attempt.connectionName || undefined,
+            timeoutSeconds: 180,
+            maxRows: 1,
+            query: smokeQuery,
+          },
+        });
+
+        const observed = parseSingleRowCsv(extractCsvText(daxResult));
+        attempt.observed = observed;
+        attempt.matched = isExpectedSmokeEvidence(observed, expected);
+      } catch (error) {
+        attempt.error = error.message;
+      }
+
+      attempts.push(attempt);
+
+      if (attempt.matched) {
+        return {
+          success: true,
+          caseId: 'base-template-smoke-test',
+          casePath,
+          expected,
+          observed: attempt.observed,
+          matchedInstance: {
+            processId: attempt.processId,
+            port: attempt.port,
+            connectionName: attempt.connectionName,
+          },
+          attempts,
+        };
+      }
+    }
+
+    return {
+      success: false,
+      caseId: 'base-template-smoke-test',
+      casePath,
+      expected,
+      observed: null,
+      matchedInstance: null,
+      attempts,
+    };
+  } finally {
+    session.close();
+  }
+}
+
+module.exports = {
+  BASE_TEMPLATE_CASE_PATH,
+  extractSmokeQuery,
+  formatLocalDate,
+  getExpectedSmokeEvidence,
+  normalizeMcpJsonResult,
+  extractCsvText,
+  parseSingleRowCsv,
+  selectConnectionForPort,
+  isExpectedSmokeEvidence,
+  formatEvidence,
+  runBaseTemplateLiveSmokeTest,
+};

package/bin/lib/claude-hooks.js

@@ -0,0 +1,160 @@
+/**
+ * Claude Code SessionStart hook registration
+ * ===========================================
+ *
+ * Helpers to register / unregister a single `SessionStart` hook in the
+ * user's `~/.claude/settings.json`, used by `super autoupdate on|off`.
+ *
+ * Claude Code's hook schema for SessionStart is a list of matcher groups:
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [
+ *         { "hooks": [ { "type": "command", "command": "...", "timeout": 20 } ] }
+ *       ]
+ *     }
+ *   }
+ *
+ * We omit the optional `matcher` so the hook fires on every SessionStart
+ * source (startup / resume / clear / compact); the auto-update script's own
+ * throttle (once/hour) keeps that cheap. The hook command contains the
+ * marker `session-update.js`, which we use to find and dedupe our own entry
+ * without disturbing the user's other hooks.
+ *
+ * All writes reuse the installer's safe pattern (atomic + `.bak` + symlink
+ * rejection + strict parse) from lib/mcp-config so a corrupt or
+ * symlink-attacked settings.json is refused, never clobbered.
+ *
+ * @module lib/claude-hooks
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { readJsonStrict, writeJson, isObjectRecord } = require('./mcp-config');
+
+// Any hook command containing this substring is considered ours.
+const HOOK_MARKER = 'session-update.js';
+
+/**
+ * Absolute path to the user-level Claude Code settings file.
+ */
+function claudeSettingsPath() {
+  return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+/**
+ * Build the SessionStart matcher group we register.
+ * @param {string} commandStr - Full shell command (e.g. `node "<abs>/session-update.js"`)
+ */
+function buildHookGroup(commandStr) {
+  return {
+    hooks: [{ type: 'command', command: commandStr, timeout: 20 }],
+  };
+}
+
+/**
+ * Is this matcher group one of ours (its command mentions the marker)?
+ */
+function isOurGroup(group) {
+  return (
+    isObjectRecord(group) &&
+    Array.isArray(group.hooks) &&
+    group.hooks.some(
+      (h) => isObjectRecord(h) && typeof h.command === 'string' && h.command.includes(HOOK_MARKER)
+    )
+  );
+}
+
+/**
+ * Register (or refresh) our SessionStart hook, preserving every other
+ * setting and hook. Idempotent: any prior entry of ours is replaced so the
+ * absolute command path stays current after a package move/upgrade.
+ *
+ * @param {string} commandStr - The shell command the hook runs.
+ * @param {{ settingsFile?: string }} [opts]
+ * @returns {{ file: string, action: 'created'|'updated' }}
+ */
+function registerSessionStartHook(commandStr, opts = {}) {
+  const file = opts.settingsFile || claudeSettingsPath();
+  const existed = fs.existsSync(file);
+  const parsed = readJsonStrict(file);
+  const settings = isObjectRecord(parsed) ? parsed : {};
+
+  if (!isObjectRecord(settings.hooks)) settings.hooks = {};
+  const current = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
+
+  const others = current.filter((g) => !isOurGroup(g));
+  others.push(buildHookGroup(commandStr));
+  settings.hooks.SessionStart = others;
+
+  writeJson(file, settings);
+  return { file, action: existed ? 'updated' : 'created' };
+}
+
+/**
+ * Remove our SessionStart hook, leaving all other settings and hooks intact.
+ * Tidies away now-empty `SessionStart` array and `hooks` object.
+ *
+ * @param {{ settingsFile?: string }} [opts]
+ * @returns {{ file: string, removed: boolean }}
+ */
+function unregisterSessionStartHook(opts = {}) {
+  const file = opts.settingsFile || claudeSettingsPath();
+  if (!fs.existsSync(file)) return { file, removed: false };
+
+  const settings = readJsonStrict(file);
+  if (
+    !isObjectRecord(settings) ||
+    !isObjectRecord(settings.hooks) ||
+    !Array.isArray(settings.hooks.SessionStart)
+  ) {
+    return { file, removed: false };
+  }
+
+  const kept = settings.hooks.SessionStart.filter((g) => !isOurGroup(g));
+  const removed = kept.length < settings.hooks.SessionStart.length;
+  if (!removed) return { file, removed: false };
+
+  if (kept.length > 0) {
+    settings.hooks.SessionStart = kept;
+  } else {
+    delete settings.hooks.SessionStart;
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+  }
+
+  writeJson(file, settings);
+  return { file, removed: true };
+}
+
+/**
+ * Is our SessionStart hook currently registered?
+ * @param {{ settingsFile?: string }} [opts]
+ * @returns {boolean}
+ */
+function isSessionStartHookRegistered(opts = {}) {
+  const file = opts.settingsFile || claudeSettingsPath();
+  if (!fs.existsSync(file)) return false;
+  let settings;
+  try {
+    settings = readJsonStrict(file);
+  } catch (_) {
+    return false;
+  }
+  const arr =
+    isObjectRecord(settings) && isObjectRecord(settings.hooks) && settings.hooks.SessionStart;
+  return Array.isArray(arr) && arr.some((g) => isOurGroup(g));
+}
+
+module.exports = {
+  HOOK_MARKER,
+  claudeSettingsPath,
+  buildHookGroup,
+  isOurGroup,
+  registerSessionStartHook,
+  unregisterSessionStartHook,
+  isSessionStartHookRegistered,
+};