@zibby/core 0.1.0

package/src/utils/adf-converter.js

@@ -0,0 +1,68 @@
+/**
+ * Convert Atlassian Document Format (ADF) to plain text
+ * Used to convert Jira ticket descriptions from ADF JSON format to readable text
+ */
+
+/**
+ * Convert ADF document to plain text
+ * @param {Object|string} adf - Atlassian Document Format object or string
+ * @returns {string} Plain text representation
+ */
+export function adfToText(adf) {
+  if (!adf || typeof adf !== 'object') {
+    return String(adf || '');
+  }
+  
+  // If it's ADF format, extract text recursively
+  if (adf.type === 'doc' && Array.isArray(adf.content)) {
+    return adf.content.map(node => adfNodeToText(node)).join('\n\n');
+  }
+  
+  // Fallback to JSON stringify
+  return JSON.stringify(adf, null, 2);
+}
+
+/**
+ * Convert a single ADF node to plain text
+ * @param {Object} node - ADF node
+ * @returns {string} Plain text representation of the node
+ */
+function adfNodeToText(node) {
+  if (!node) return '';
+  
+  if (node.type === 'text') {
+    return node.text || '';
+  }
+  
+  if (node.type === 'paragraph' && Array.isArray(node.content)) {
+    return node.content.map(adfNodeToText).join('');
+  }
+  
+  if (node.type === 'heading' && Array.isArray(node.content)) {
+    return node.content.map(adfNodeToText).join('');
+  }
+  
+  if (node.type === 'bulletList' && Array.isArray(node.content)) {
+    return node.content.map(item => `• ${  adfNodeToText(item)}`).join('\n');
+  }
+  
+  if (node.type === 'orderedList' && Array.isArray(node.content)) {
+    return node.content.map((item, i) => `${i + 1}. ${  adfNodeToText(item)}`).join('\n');
+  }
+  
+  if (node.type === 'listItem' && Array.isArray(node.content)) {
+    return node.content.map(adfNodeToText).join('');
+  }
+  
+  if (node.type === 'codeBlock' && Array.isArray(node.content)) {
+    const code = node.content.map(adfNodeToText).join('');
+    const lang = node.attrs?.language || '';
+    return `\`\`\`${lang}\n${code}\n\`\`\``;
+  }
+  
+  if (Array.isArray(node.content)) {
+    return node.content.map(adfNodeToText).join('');
+  }
+  
+  return '';
+}

package/src/utils/ast-utils.js

@@ -0,0 +1,37 @@
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+
+export function hasAgentCall(code) {
+  if (!code || typeof code !== 'string') return false;
+
+  try {
+    const wrappedCode = code.trimStart().startsWith('async')
+      ? `const __fn = ${code}`
+      : code;
+
+    const ast = acorn.parse(wrappedCode, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowAwaitOutsideModules: true
+    });
+
+    let found = false;
+    walk.simple(ast, {
+      CallExpression(node) {
+        if (found) return;
+        const callee = node.callee;
+        if (callee.type === 'Identifier' && callee.name === 'invokeAgent') {
+          found = true;
+        }
+        if (callee.type === 'MemberExpression' &&
+            callee.property.type === 'Identifier' &&
+            callee.property.name === 'invokeAgent') {
+          found = true;
+        }
+      }
+    });
+    return found;
+  } catch {
+    return true;
+  }
+}

package/src/utils/ci-setup.js

@@ -0,0 +1,124 @@
+import { spawn } from 'child_process';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export async function patchCursorAgentForCI() {
+  const versionsDir = join(homedir(), '.local/share/cursor-agent/versions');
+  
+  if (!existsSync(versionsDir)) {
+    throw new Error(`cursor-agent not found at ${versionsDir}. Please install cursor-agent first.`);
+  }
+
+  console.log('🔧 Patching cursor-agent for CI/CD...\n');
+
+  return new Promise((resolve, reject) => {
+    const pythonScript = join(__dirname, '../../scripts/patch-cursor-mcp.py');
+    
+    if (!existsSync(pythonScript)) {
+      reject(new Error('Patch script not found'));
+      return;
+    }
+
+    const patch = spawn('python3', [pythonScript], {
+      stdio: 'inherit',
+    });
+
+    patch.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true });
+      } else {
+        reject(new Error(`Patch failed with code ${code}`));
+      }
+    });
+
+    patch.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+export function checkCursorAgentPatched() {
+  const versionsDir = join(homedir(), '.local/share/cursor-agent/versions');
+  
+  if (!existsSync(versionsDir)) {
+    return { patched: false, installed: false };
+  }
+
+  try {
+    const versions = require('fs').readdirSync(versionsDir);
+    if (versions.length === 0) {
+      return { patched: false, installed: false };
+    }
+
+    const latestVersion = versions.sort().reverse()[0];
+    const indexFile = join(versionsDir, latestVersion, 'index.js');
+    
+    if (!existsSync(indexFile)) {
+      return { patched: false, installed: false };
+    }
+
+    const content = readFileSync(indexFile, 'utf-8');
+    const patched = content.includes('AUTO-APPROVE MCP TOOLS FOR CI/CD');
+
+    return { patched, installed: true, path: indexFile };
+  } catch (error) {
+    return { patched: false, installed: false, error: error.message };
+  }
+}
+
+export async function getApprovalKeys(projectPath) {
+  console.log('🔑 Getting MCP approval keys...\n');
+
+  return new Promise((resolve, reject) => {
+    const getKeys = spawn('cursor-agent', ['mcp', 'list'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+    });
+
+    let output = '';
+
+    getKeys.stdout.on('data', (data) => {
+      output += data.toString();
+      process.stdout.write(data);
+    });
+
+    getKeys.stderr.on('data', (data) => {
+      process.stderr.write(data);
+    });
+
+    getKeys.on('close', (code) => {
+      if (code === 0) {
+        const keys = parseApprovalKeys(output);
+        resolve({ success: true, keys, output });
+      } else {
+        reject(new Error(`Failed to get approval keys (exit code ${code})`));
+      }
+    });
+
+    getKeys.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+function parseApprovalKeys(output) {
+  const keys = {};
+  const regex = /🔑 APPROVAL KEY:\s+(\S+)\s+=>\s+(\S+)/g;
+  let match;
+
+  while ((match = regex.exec(output)) !== null) {
+    keys[match[1]] = match[2];
+  }
+
+  return keys;
+}
+
+export function saveApprovalKeys(projectPath, keys) {
+  const cursorDir = join(projectPath, '.cursor/projects');
+  const approvalsFile = join(cursorDir, 'mcp-approvals.json');
+
+  writeFileSync(approvalsFile, JSON.stringify(keys, null, 2));
+  console.log(`\n✅ Saved approval keys to: ${approvalsFile}\n`);
+}
+

package/src/utils/cursor-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Cursor Agent Utilities
+ * Check if cursor-agent CLI is installed
+ */
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const execAsync = promisify(exec);
+
+/**
+ * Find the cursor-agent binary path
+ * Checks PATH first, then common installation locations
+ */
+export async function findCursorAgentPath() {
+  // First try via PATH (standard check)
+  try {
+    await execAsync('cursor-agent --version');
+    return 'cursor-agent'; // Found in PATH
+  } catch (_error) {
+    // PATH check failed, try common installation locations
+    const commonPaths = [
+      join(homedir(), '.local', 'bin', 'cursor-agent'),
+      join(homedir(), '.cursor', 'bin', 'cursor-agent'),
+      join(homedir(), '.cursor-agent', 'bin', 'cursor-agent')
+    ];
+    
+    // Check if binary exists in common locations
+    for (const binaryPath of commonPaths) {
+      if (existsSync(binaryPath)) {
+        // Try running it directly
+        try {
+          await execAsync(`"${binaryPath}" --version`);
+          return binaryPath; // Found in common location
+        } catch (_e) {
+          // Binary exists but might not be executable, continue checking
+        }
+      }
+    }
+    
+    return null; // Not found
+  }
+}
+
+export async function checkCursorAgentInstalled() {
+  const path = await findCursorAgentPath();
+  return path !== null;
+}
+
+export function getCursorAgentInstallInstructions() {
+  return `
+❌ cursor-agent CLI not found!
+
+To use the Cursor agent, install it from:
+📦 https://github.com/getcursor/cursor-agent
+
+Installation:
+  curl https://cursor.com/install -fsS | bash
+
+After installation:
+  1. Add ~/.local/bin to your PATH:
+     For zsh: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+     For bash: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+  
+  2. Or restart your terminal/shell
+
+Then retry your command.
+`;
+}

package/src/utils/logger.js

@@ -0,0 +1,144 @@
+/**
+ * Zibby Logger - Structured logging with levels
+ * 
+ * Usage:
+ *   import { logger } from './utils/logger.js';
+ *   logger.debug('Starting process...');
+ *   logger.info('Test completed');
+ *   logger.warn('API rate limit approaching');
+ *   logger.error('Failed to connect', { error });
+ * 
+ * Configuration:
+ *   LOG_LEVEL=debug     - Show debug, info, warn, error
+ *   LOG_LEVEL=info      - Show info, warn, error
+ *   LOG_LEVEL=warn      - Show warn, error only (default)
+ *   LOG_LEVEL=error     - Show error only
+ *   LOG_LEVEL=silent    - No logs
+ * 
+ * CLI Flags:
+ *   --verbose           - Sets LOG_LEVEL=info (show progress)
+ *   --debug             - Sets LOG_LEVEL=debug (show everything)
+ * 
+ * Best Practice:
+ *   - Use console.log() for user-facing messages (always shown)
+ *   - Use logger.debug() for diagnostics (--debug only)
+ *   - Use logger.info() for progress/status (--verbose)
+ *   - Use logger.warn() for warnings (always shown)
+ *   - Use logger.error() for errors (always shown)
+ */
+
+import chalk from 'chalk';
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4
+};
+
+class Logger {
+  constructor() {
+    this._level = this._getLogLevel();
+  }
+
+  _getLogLevel() {
+    if (process.env.ZIBBY_DEBUG === 'true') {
+      return LOG_LEVELS.debug;
+    }
+    if (process.env.ZIBBY_VERBOSE === 'true') {
+      return LOG_LEVELS.info;
+    }
+
+    const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+    if (envLevel && envLevel in LOG_LEVELS) {
+      return LOG_LEVELS[envLevel];
+    }
+
+    return LOG_LEVELS.info;
+  }
+
+  _shouldLog(level) {
+    return LOG_LEVELS[level] >= this._level;
+  }
+
+  _formatMessage(level, message, meta = {}) {
+    const _timestamp = new Date().toISOString();
+    const prefix = this._getPrefix(level);
+    
+    let output = `${prefix} ${message}`;
+    
+    // Add metadata if present
+    if (Object.keys(meta).length > 0) {
+      output += chalk.dim(` ${JSON.stringify(meta)}`);
+    }
+    
+    return output;
+  }
+
+  _getPrefix(level) {
+    const prefixes = {
+      debug: chalk.gray('[DEBUG]'),
+      info: chalk.cyan('[INFO]'),
+      warn: chalk.yellow('[WARN]'),
+      error: chalk.red('❌ [ERROR]')
+    };
+    return prefixes[level] || '';
+  }
+
+  /**
+   * Debug - verbose diagnostic information
+   * Only shown with --debug or LOG_LEVEL=debug
+   */
+  debug(message, meta) {
+    if (!this._shouldLog('debug')) return;
+    console.log(this._formatMessage('debug', message, meta));
+  }
+
+  /**
+   * Info - general informational messages
+   * Shown with --verbose, --debug, or LOG_LEVEL=info
+   */
+  info(message, meta) {
+    if (!this._shouldLog('info')) return;
+    console.log(this._formatMessage('info', message, meta));
+  }
+
+  /**
+   * Warn - warning messages (potential issues)
+   * Always shown unless LOG_LEVEL=error or silent
+   */
+  warn(message, meta) {
+    if (!this._shouldLog('warn')) return;
+    console.warn(this._formatMessage('warn', message, meta));
+  }
+
+  /**
+   * Error - error messages (failures)
+   * Always shown unless LOG_LEVEL=silent
+   */
+  error(message, meta) {
+    if (!this._shouldLog('error')) return;
+    console.error(this._formatMessage('error', message, meta));
+  }
+
+  /**
+   * Set log level programmatically
+   */
+  setLevel(level) {
+    if (level in LOG_LEVELS) {
+      this._level = LOG_LEVELS[level];
+    }
+  }
+
+  /**
+   * Get current log level name
+   */
+  getLevel() {
+    return Object.keys(LOG_LEVELS).find(key => LOG_LEVELS[key] === this._level);
+  }
+}
+
+export const logger = new Logger();
+
+export { Logger, LOG_LEVELS };

package/src/utils/mcp-config-writer.js

@@ -0,0 +1,115 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getSkill } from '../framework/skill-registry.js';
+
+const MCP_CONFIG_PATH = join(homedir(), '.cursor', 'mcp.json');
+
+export function collectRequiredTools(nodeConfigs) {
+  const toolSet = new Set();
+  if (!nodeConfigs || typeof nodeConfigs !== 'object') return toolSet;
+
+  for (const nodeId of Object.keys(nodeConfigs)) {
+    const config = nodeConfigs[nodeId];
+    if (Array.isArray(config.tools)) {
+      for (const tool of config.tools) {
+        toolSet.add(tool);
+      }
+    }
+  }
+  return toolSet;
+}
+
+export function writeMcpConfig(nodeConfigs) {
+  const requiredTools = collectRequiredTools(nodeConfigs);
+  if (requiredTools.size === 0) {
+    console.log('[MCP Config] No tools requested — skipping MCP config write');
+    return false;
+  }
+
+  let mcpConfig = { mcpServers: {} };
+  try {
+    if (existsSync(MCP_CONFIG_PATH)) {
+      mcpConfig = JSON.parse(readFileSync(MCP_CONFIG_PATH, 'utf-8'));
+      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    }
+  } catch (err) {
+    console.warn(`[MCP Config] Could not read existing config, starting fresh: ${err.message}`);
+    mcpConfig = { mcpServers: {} };
+  }
+
+  let addedCount = 0;
+  for (const toolId of requiredTools) {
+    const skill = getSkill(toolId);
+    if (!skill) {
+      console.log(`[MCP Config] Unknown skill "${toolId}" — skipping`);
+      continue;
+    }
+
+    if (mcpConfig.mcpServers[skill.serverName]) {
+      console.log(`[MCP Config] Server "${skill.serverName}" already configured — skipping`);
+      continue;
+    }
+
+    const envVars = {};
+    let missingEnv = false;
+    for (const key of (skill.envKeys || [])) {
+      const value = process.env[key];
+      if (!value) {
+        console.warn(`[MCP Config] Missing env var ${key} for skill "${toolId}" — skipping server`);
+        missingEnv = true;
+        break;
+      }
+      envVars[key] = value;
+    }
+    if (missingEnv) continue;
+
+    const resolvedArgs = (skill.args || []).map(a => a);
+    if (skill.command === 'node' && resolvedArgs.length > 0 && !existsSync(resolvedArgs[0])) {
+      console.warn(`[MCP Config] Binary not found at ${resolvedArgs[0]} for "${toolId}" — skipping server`);
+      continue;
+    }
+
+    mcpConfig.mcpServers[skill.serverName] = {
+      command: skill.command,
+      args: resolvedArgs,
+      env: envVars,
+      description: skill.description,
+    };
+    addedCount++;
+    console.log(`[MCP Config] Added "${skill.serverName}" server`);
+  }
+
+  if (addedCount === 0) {
+    console.log('[MCP Config] No new MCP servers to add');
+    return false;
+  }
+
+  const configDir = join(homedir(), '.cursor');
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  writeFileSync(MCP_CONFIG_PATH, JSON.stringify(mcpConfig, null, 2), 'utf-8');
+  console.log(`[MCP Config] Wrote ${MCP_CONFIG_PATH} with ${Object.keys(mcpConfig.mcpServers).length} server(s)`);
+  return true;
+}
+
+export function getToolDescriptions(toolIds) {
+  if (!Array.isArray(toolIds) || toolIds.length === 0) return '';
+
+  const sections = [];
+  for (const toolId of toolIds) {
+    const skill = getSkill(toolId);
+    if (!skill) continue;
+
+    const toolList = (skill.tools || [])
+      .map(t => `- ${t.name}: ${t.description}`)
+      .join('\n');
+
+    sections.push(`### ${skill.description}\n${toolList}`);
+  }
+
+  if (sections.length === 0) return '';
+
+  return `\n\nAVAILABLE MCP TOOLS:\nYou have access to the following MCP tools. Use them when your task requires interacting with these services.\n\n${sections.join('\n\n')}`;
+}