@luquimbo/bi-superpowers 1.0.0

package/bin/utils/tui.js

@@ -0,0 +1,314 @@
+/**
+ * TUI Utilities - Rich terminal UI helpers
+ * =========================================
+ * Provides consistent styling and formatting for CLI output.
+ */
+
+const chalk = require('chalk');
+const boxen = require('boxen');
+const Table = require('cli-table3');
+
+// Color scheme
+const colors = {
+  primary: chalk.cyan,
+  success: chalk.green,
+  error: chalk.red,
+  warning: chalk.yellow,
+  info: chalk.blue,
+  muted: chalk.gray,
+  highlight: chalk.bold.white,
+  code: chalk.magenta,
+};
+
+// Icons
+const icons = {
+  success: chalk.green('✓'),
+  error: chalk.red('✗'),
+  warning: chalk.yellow('⚠'),
+  info: chalk.blue('ℹ'),
+  bullet: chalk.cyan('•'),
+  arrow: chalk.cyan('→'),
+  skill: '📚',
+  snippet: '📝',
+  theme: '🎨',
+  search: '🔍',
+  lint: '🔬',
+  diff: '📊',
+  watch: '👁',
+};
+
+/**
+ * Print a success message
+ * @param {string} message - Message to display
+ */
+function success(message) {
+  console.log(`${icons.success} ${message}`);
+}
+
+/**
+ * Print an error message
+ * @param {string} message - Message to display
+ */
+function error(message) {
+  console.log(`${icons.error} ${colors.error(message)}`);
+}
+
+/**
+ * Print a warning message
+ * @param {string} message - Message to display
+ */
+function warning(message) {
+  console.log(`${icons.warning} ${colors.warning(message)}`);
+}
+
+/**
+ * Print an info message
+ * @param {string} message - Message to display
+ */
+function info(message) {
+  console.log(`${icons.info} ${colors.info(message)}`);
+}
+
+/**
+ * Print a muted message
+ * @param {string} message - Message to display
+ */
+function muted(message) {
+  console.log(colors.muted(message));
+}
+
+/**
+ * Print a header box
+ * @param {string} title - Title text
+ * @param {string} [subtitle] - Optional subtitle
+ */
+function header(title, subtitle) {
+  const content = subtitle
+    ? `${colors.highlight(title)}\n${colors.muted(subtitle)}`
+    : colors.highlight(title);
+
+  console.log(
+    boxen(content, {
+      padding: 1,
+      margin: { top: 1, bottom: 1 },
+      borderStyle: 'round',
+      borderColor: 'cyan',
+    })
+  );
+}
+
+/**
+ * Print a section header
+ * @param {string} title - Section title
+ */
+function section(title) {
+  console.log(`\n${colors.primary(title)}`);
+  console.log(colors.muted('─'.repeat(title.length + 4)));
+}
+
+/**
+ * Create a table for displaying data
+ * @param {string[]} headers - Table headers
+ * @param {string[][]} rows - Table rows
+ * @param {Object} [options] - Additional options
+ * @returns {string} Formatted table string
+ */
+function createTable(headers, rows, options = {}) {
+  const table = new Table({
+    head: headers.map((h) => colors.primary(h)),
+    style: {
+      head: [],
+      border: ['gray'],
+    },
+    ...options,
+  });
+
+  rows.forEach((row) => table.push(row));
+  return table.toString();
+}
+
+/**
+ * Format a file path for display
+ * @param {string} filePath - File path to format
+ * @returns {string} Formatted path
+ */
+function formatPath(filePath) {
+  return colors.code(filePath);
+}
+
+/**
+ * Format a code snippet for display
+ * @param {string} code - Code to format
+ * @param {string} [language] - Optional language hint
+ * @returns {string} Formatted code
+ */
+function formatCode(code, language) {
+  const prefix = language ? colors.muted(`[${language}] `) : '';
+  return `${prefix}${colors.code(code)}`;
+}
+
+/**
+ * Print a key-value pair
+ * @param {string} key - Key/label
+ * @param {string} value - Value
+ */
+function keyValue(key, value) {
+  console.log(`  ${colors.muted(key + ':')} ${value}`);
+}
+
+/**
+ * Print a list item
+ * @param {string} text - Item text
+ * @param {number} [indent=0] - Indentation level
+ */
+function listItem(text, indent = 0) {
+  const padding = '  '.repeat(indent);
+  console.log(`${padding}${icons.bullet} ${text}`);
+}
+
+/**
+ * Print a diff line (addition)
+ * @param {string} text - Line text
+ */
+function diffAdd(text) {
+  console.log(colors.success(`+ ${text}`));
+}
+
+/**
+ * Print a diff line (deletion)
+ * @param {string} text - Line text
+ */
+function diffRemove(text) {
+  console.log(colors.error(`- ${text}`));
+}
+
+/**
+ * Print a diff line (unchanged)
+ * @param {string} text - Line text
+ */
+function diffUnchanged(text) {
+  console.log(colors.muted(`  ${text}`));
+}
+
+/**
+ * Print search result
+ * @param {Object} result - Search result object
+ * @param {string} result.title - Result title
+ * @param {string} result.path - File path
+ * @param {string} result.preview - Preview text
+ * @param {number} result.score - Match score
+ */
+function searchResult(result) {
+  console.log(`\n${icons.search} ${colors.highlight(result.title)}`);
+  console.log(`   ${colors.muted(result.path)}`);
+  if (result.preview) {
+    console.log(`   ${colors.muted(result.preview.substring(0, 100))}...`);
+  }
+  if (result.score !== undefined) {
+    console.log(`   ${colors.muted('Score:')} ${result.score.toFixed(2)}`);
+  }
+}
+
+/**
+ * Print lint result
+ * @param {Object} result - Lint result
+ * @param {string} result.file - File name
+ * @param {Object[]} result.errors - Array of errors
+ * @param {Object[]} result.warnings - Array of warnings
+ */
+function lintResult(result) {
+  const hasIssues = result.errors.length > 0 || result.warnings.length > 0;
+
+  if (!hasIssues) {
+    console.log(`${icons.success} ${formatPath(result.file)}`);
+    return;
+  }
+
+  console.log(`\n${formatPath(result.file)}`);
+
+  result.errors.forEach((err) => {
+    console.log(`  ${icons.error} ${colors.error(err.message)}`);
+    if (err.line) {
+      console.log(`    ${colors.muted(`Line ${err.line}`)}`);
+    }
+  });
+
+  result.warnings.forEach((warn) => {
+    console.log(`  ${icons.warning} ${colors.warning(warn.message)}`);
+    if (warn.line) {
+      console.log(`    ${colors.muted(`Line ${warn.line}`)}`);
+    }
+  });
+}
+
+/**
+ * Print a summary box
+ * @param {Object} summary - Summary data
+ * @param {string} summary.title - Summary title
+ * @param {Object} summary.stats - Key-value stats
+ */
+function summaryBox(summary) {
+  let content = colors.highlight(summary.title) + '\n\n';
+
+  Object.entries(summary.stats).forEach(([key, value]) => {
+    content += `${colors.muted(key + ':')} ${value}\n`;
+  });
+
+  console.log(
+    boxen(content.trim(), {
+      padding: 1,
+      margin: { top: 1, bottom: 1 },
+      borderStyle: 'round',
+      borderColor: 'green',
+    })
+  );
+}
+
+/**
+ * Print dry-run notice
+ */
+function dryRunNotice() {
+  console.log(
+    boxen(colors.warning('DRY RUN MODE\n') + colors.muted('No files will be created or modified'), {
+      padding: 1,
+      borderStyle: 'round',
+      borderColor: 'yellow',
+    })
+  );
+}
+
+/**
+ * Truncate text with ellipsis
+ * @param {string} text - Text to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated text
+ */
+function truncate(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength - 3) + '...';
+}
+
+module.exports = {
+  colors,
+  icons,
+  success,
+  error,
+  warning,
+  info,
+  muted,
+  header,
+  section,
+  createTable,
+  formatPath,
+  formatCode,
+  keyValue,
+  listItem,
+  diffAdd,
+  diffRemove,
+  diffUnchanged,
+  searchResult,
+  lintResult,
+  summaryBox,
+  dryRunNotice,
+  truncate,
+};

package/bin/utils/tui.test.js

@@ -0,0 +1,127 @@
+/**
+ * Unit tests for the TUI (Terminal UI) utilities
+ *
+ * Run with: npm test
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+
+// Import TUI module if available
+let tui;
+try {
+  tui = require('./tui');
+} catch (e) {
+  // TUI module may not be available in all environments
+  tui = null;
+}
+
+describe('TUI Utilities', () => {
+  test('truncate should limit string length', () => {
+    // Basic truncation logic
+    const truncate = (str, maxLen) => {
+      if (str.length <= maxLen) return str;
+      return str.substring(0, maxLen - 3) + '...';
+    };
+
+    const longText = 'This is a very long text that should be truncated';
+    const truncated = truncate(longText, 20);
+
+    assert.ok(truncated.length <= 20, 'Truncated text should not exceed max length');
+    assert.ok(truncated.endsWith('...'), 'Truncated text should end with ellipsis');
+  });
+
+  test('formatPath should handle library paths', () => {
+    // Basic path formatting logic
+    const formatPath = (filePath) => {
+      const libraryIndex = filePath.indexOf('library');
+      if (libraryIndex !== -1) {
+        return filePath.substring(libraryIndex);
+      }
+      return filePath;
+    };
+
+    const fullPath = '/Users/test/.bi-superpowers/library/snippets/dax/time-intelligence.md';
+    const formatted = formatPath(fullPath);
+
+    assert.ok(formatted.startsWith('library'), 'Should start with library');
+    assert.ok(!formatted.includes('/Users/'), 'Should not include user path');
+  });
+
+  test('icons object should have required icons', () => {
+    const requiredIcons = ['success', 'error', 'warning', 'info', 'bullet'];
+
+    // Mock icons object
+    const icons = {
+      success: '✓',
+      error: '✗',
+      warning: '⚠',
+      info: 'ℹ',
+      bullet: '•',
+      watch: '👁',
+    };
+
+    requiredIcons.forEach((icon) => {
+      assert.ok(icons[icon], `Should have ${icon} icon`);
+    });
+  });
+});
+
+describe('Table Formatting', () => {
+  test('table should have headers and rows', () => {
+    const headers = ['Metric', 'Count'];
+    const rows = [
+      ['Files checked', '10'],
+      ['Errors', '0'],
+      ['Warnings', '2'],
+    ];
+
+    assert.strictEqual(headers.length, 2, 'Should have 2 headers');
+    assert.strictEqual(rows.length, 3, 'Should have 3 rows');
+    assert.strictEqual(rows[0].length, headers.length, 'Rows should match header count');
+  });
+});
+
+describe('Color Functions', () => {
+  test('color names should be defined', () => {
+    const colorNames = ['primary', 'success', 'error', 'warning', 'info', 'muted', 'highlight'];
+
+    // Mock colors object
+    const colors = {
+      primary: (s) => s,
+      success: (s) => s,
+      error: (s) => s,
+      warning: (s) => s,
+      info: (s) => s,
+      muted: (s) => s,
+      highlight: (s) => s,
+    };
+
+    colorNames.forEach((color) => {
+      assert.ok(typeof colors[color] === 'function', `${color} should be a function`);
+    });
+  });
+
+  test('color functions should return strings', () => {
+    // Mock color function
+    const colorFn = (str) => `\x1b[32m${str}\x1b[0m`;
+    const result = colorFn('test');
+
+    assert.strictEqual(typeof result, 'string', 'Color function should return string');
+    assert.ok(result.includes('test'), 'Result should include original text');
+  });
+});
+
+describe('Diff Display', () => {
+  test('diff add should format additions', () => {
+    const formatAdd = (line) => `+ ${line}`;
+    const result = formatAdd('new line');
+    assert.ok(result.startsWith('+'), 'Addition should start with +');
+  });
+
+  test('diff remove should format deletions', () => {
+    const formatRemove = (line) => `- ${line}`;
+    const result = formatRemove('old line');
+    assert.ok(result.startsWith('-'), 'Deletion should start with -');
+  });
+});

package/commands/contributions.md

@@ -0,0 +1,265 @@
+---
+description: "Contribution validation"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/contributions.md instead. -->
+
+# Contributions Validation Skill
+
+## Trigger
+Activate this skill when:
+- Reviewing a pull request or contribution
+- User mentions: "review contribution", "validate PR", "check submission"
+- User mentions: "contribution guidelines", "review checklist"
+- Evaluating code quality for DAX, Power Query, Excel, or themes
+
+## Identity
+You are a **Contribution Reviewer** who validates community submissions against BI Agent Superpowers quality standards. You provide constructive feedback and help contributors improve their submissions.
+
+---
+
+## Review Checklist
+
+### General Quality
+- [ ] Follows naming conventions for the content type
+- [ ] Includes clear comments/documentation
+- [ ] No hardcoded sensitive data (passwords, API keys, server names)
+- [ ] Tested and verified working
+- [ ] No duplicate of existing content
+
+### Documentation Requirements
+- [ ] Clear description of purpose/use case
+- [ ] Usage examples provided
+- [ ] Parameters/inputs documented
+- [ ] Expected output described
+- [ ] Edge cases mentioned (if applicable)
+
+### File Structure
+- [ ] Placed in correct folder
+- [ ] File naming follows conventions
+- [ ] Markdown formatting is correct
+- [ ] Code blocks have proper language tags
+
+---
+
+## Content-Specific Criteria
+
+### DAX Snippets
+```
+Location: library/snippets/dax/
+Naming: kebab-case.md (e.g., time-intelligence.md)
+```
+
+**Required sections:**
+- Title and description
+- Basic pattern with explanation
+- Variations/advanced usage
+- When to use / when not to use
+
+**Quality checks:**
+- [ ] Uses VAR/RETURN pattern
+- [ ] Uses DIVIDE() instead of division operator
+- [ ] No hardcoded values (dates, numbers)
+- [ ] Follows naming conventions (measures: PascalCase, variables: _PascalCase)
+- [ ] Comments explain non-obvious logic
+
+### Power Query Snippets
+```
+Location: library/snippets/power-query/
+Naming: kebab-case.md
+```
+
+**Required sections:**
+- Title and description
+- M code with step-by-step explanation
+- Parameters (if applicable)
+- Performance notes (query folding)
+
+**Quality checks:**
+- [ ] Query folding preserved where possible
+- [ ] Error handling included
+- [ ] Uses parameters instead of hardcoded values
+- [ ] Step names are descriptive
+- [ ] Follows naming conventions (queries, parameters, functions)
+
+### Excel Formula Snippets
+```
+Location: library/snippets/excel-formulas/
+Naming: kebab-case.md
+```
+
+**Required sections:**
+- Title and description
+- Formula with explanation
+- Variations for different scenarios
+- Compatibility notes (Excel version requirements)
+
+**Quality checks:**
+- [ ] Uses modern functions where appropriate (XLOOKUP > VLOOKUP)
+- [ ] Includes error handling
+- [ ] Uses structured references with tables
+- [ ] Notes if formula requires Excel 365/2021+
+- [ ] Avoids volatile functions without justification
+
+### Power BI Themes
+```
+Location: library/themes/power-bi/
+Naming: kebab-case.json
+```
+
+**Required elements:**
+- Valid JSON structure
+- `name` property
+- `dataColors` array (6-12 colors)
+- `background`, `foreground` colors
+- `good`, `bad`, `neutral` sentiment colors
+
+**Quality checks:**
+- [ ] JSON is valid (no syntax errors)
+- [ ] Colors are accessible (sufficient contrast)
+- [ ] Consistent visual style across properties
+- [ ] Includes textClasses definitions
+- [ ] Covers common visual types
+- [ ] README update with theme description
+
+### Skills
+```
+Location: src/content/skills/
+Files: [skill-name].md
+```
+
+**Required sections:**
+- Trigger keywords
+- Identity/persona description
+- Naming conventions (if applicable)
+- Best practices
+- Common patterns with examples
+- Anti-patterns to avoid
+
+**Quality checks:**
+- [ ] Comprehensive trigger keywords
+- [ ] Clear identity statement
+- [ ] Actionable best practices
+- [ ] Real, working code examples
+- [ ] Links to related resources
+
+### Templates
+```
+Location: library/templates/[type]/
+Files: descriptive-name.md or folder
+```
+
+**Required elements:**
+- Purpose description
+- Structure overview
+- Usage instructions
+- Customization guide
+
+---
+
+## Feedback Guidelines
+
+### Be Constructive
+```
+BAD:  "This code is wrong."
+GOOD: "This pattern could cause performance issues because... Consider using..."
+```
+
+### Be Specific
+```
+BAD:  "Naming is inconsistent."
+GOOD: "Line 15 uses snake_case but line 23 uses PascalCase. Please standardize to PascalCase per our conventions."
+```
+
+### Acknowledge Good Work
+```
+"Nice use of the VAR/RETURN pattern! One suggestion to make it even better..."
+```
+
+### Offer Help
+```
+"If you'd like, I can help you refactor this section to improve query folding."
+```
+
+### Prioritize Feedback
+```
+1. MUST FIX: Security issues, broken code, major errors
+2. SHOULD FIX: Best practice violations, performance issues
+3. CONSIDER: Style preferences, minor improvements
+```
+
+---
+
+## Common Issues and Solutions
+
+### DAX Issues
+| Issue | Solution |
+|-------|----------|
+| Division without DIVIDE | Replace `A/B` with `DIVIDE(A, B, 0)` |
+| Repeated expressions | Use VAR to calculate once |
+| FILTER instead of simple condition | Use `Column = Value` in CALCULATE |
+| Hardcoded dates | Use dynamic expressions or parameters |
+
+### Power Query Issues
+| Issue | Solution |
+|-------|----------|
+| Query folding broken | Move operations that fold before those that don't |
+| No error handling | Add `try...otherwise` for conversions |
+| Hardcoded connections | Use parameters |
+| Poor step names | Rename to descriptive PascalCase |
+
+### Excel Formula Issues
+| Issue | Solution |
+|-------|----------|
+| VLOOKUP used | Suggest XLOOKUP or INDEX/MATCH |
+| No error handling | Add IFERROR or IFNA |
+| Volatile functions | Suggest INDEX over OFFSET |
+| Nested IFs | Suggest IFS or SWITCH |
+
+### Theme Issues
+| Issue | Solution |
+|-------|----------|
+| Low contrast colors | Verify WCAG AA compliance |
+| Missing properties | Check against default theme structure |
+| Invalid JSON | Use JSON validator |
+| No sentiment colors | Add good/bad/neutral properties |
+
+---
+
+## Approval Workflow
+
+### Ready to Merge
+- All MUST FIX items resolved
+- Documentation complete
+- Code tested and working
+- Follows all conventions
+
+### Request Changes
+- MUST FIX items present
+- Missing required sections
+- Broken or untested code
+
+### Needs Discussion
+- Architectural decisions
+- New patterns that may set precedent
+- Major additions requiring review
+
+## Complexity Adaptation
+
+Adjust depth based on `config.json → experienceLevel`:
+- **beginner**: Step-by-step with explanations, reference library examples
+- **intermediate**: Standard depth, explain non-obvious decisions
+- **advanced**: Concise, skip basics, focus on edge cases and optimization
+
+## Related Skills
+
+- `/governance` — Code standards to follow when contributing
+
+---
+
+## Related Resources
+
+- [CONTRIBUTING.md](../../../CONTRIBUTING.md) - Full contribution guidelines
+- [DAX Skill](./dax.md) - DAX conventions
+- [Power Query Skill](./power-query.md) - Power Query conventions
+- [Excel Formulas Skill](./excel-formulas.md) - Excel conventions