suparank 1.2.5 → 1.2.7

package/mcp-client/tools/discovery.js

@@ -0,0 +1,132 @@
+/**
+ * Suparank MCP - Tool Discovery
+ *
+ * Functions for discovering and filtering available tools
+ * based on configuration and credentials
+ */
+
+import { TOOLS, ACTION_TOOLS, ORCHESTRATOR_TOOLS, VISIBLE_TOOLS } from './definitions.js'
+import { hasCredential } from '../services/credentials.js'
+
+/**
+ * Get tools to show in ListToolsRequestSchema
+ * Only returns visible tools, with action tools marked as disabled if no credentials
+ * @returns {Array} Array of tool definitions for MCP clients
+ */
+export function getAvailableTools() {
+  const tools = []
+
+  // Add visible TOOLS (keyword_research only from main tools)
+  for (const tool of TOOLS) {
+    if (VISIBLE_TOOLS.includes(tool.name)) {
+      tools.push({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      })
+    }
+  }
+
+  // Add visible orchestrator tools
+  for (const tool of ORCHESTRATOR_TOOLS) {
+    if (VISIBLE_TOOLS.includes(tool.name)) {
+      tools.push({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      })
+    }
+  }
+
+  // Add visible action tools (only if credentials are configured)
+  for (const tool of ACTION_TOOLS) {
+    if (VISIBLE_TOOLS.includes(tool.name)) {
+      if (hasCredential(tool.requiresCredential)) {
+        tools.push({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema
+        })
+      } else {
+        // Add disabled version with note
+        tools.push({
+          name: tool.name,
+          description: `[DISABLED - requires ${tool.requiresCredential} credentials] ${tool.description}`,
+          inputSchema: tool.inputSchema
+        })
+      }
+    }
+  }
+
+  return tools
+}
+
+/**
+ * Get ALL tools (visible + hidden) for tool execution
+ * This is used by CallToolRequestSchema to find tools by name
+ * @returns {Array} Array of all tool definitions
+ */
+export function getAllTools() {
+  const tools = [...TOOLS]
+
+  // Add all orchestrator tools
+  for (const tool of ORCHESTRATOR_TOOLS) {
+    tools.push({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    })
+  }
+
+  // Add all action tools
+  for (const tool of ACTION_TOOLS) {
+    tools.push({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      requiresCredential: tool.requiresCredential
+    })
+  }
+
+  return tools
+}
+
+/**
+ * Find a tool by name across all tool arrays
+ * @param {string} name - Tool name to find
+ * @returns {object|null} Tool definition or null
+ */
+export function findTool(name) {
+  // Check backend tools
+  const backendTool = TOOLS.find(t => t.name === name)
+  if (backendTool) return { ...backendTool, type: 'backend' }
+
+  // Check orchestrator tools
+  const orchestratorTool = ORCHESTRATOR_TOOLS.find(t => t.name === name)
+  if (orchestratorTool) return { ...orchestratorTool, type: 'orchestrator' }
+
+  // Check action tools
+  const actionTool = ACTION_TOOLS.find(t => t.name === name)
+  if (actionTool) return { ...actionTool, type: 'action' }
+
+  return null
+}
+
+/**
+ * Check if a tool name exists
+ * @param {string} name - Tool name to check
+ * @returns {boolean} Whether the tool exists
+ */
+export function toolExists(name) {
+  return findTool(name) !== null
+}
+
+/**
+ * Get the tool type (backend, orchestrator, action)
+ * @param {string} name - Tool name
+ * @returns {string|null} Tool type or null
+ */
+export function getToolType(name) {
+  const tool = findTool(name)
+  return tool ? tool.type : null
+}

package/mcp-client/tools/index.js

@@ -0,0 +1,22 @@
+/**
+ * Suparank MCP - Tools Module
+ *
+ * Re-exports all tool definitions and discovery functions
+ */
+
+// Tool definitions
+export {
+  TOOLS,
+  ACTION_TOOLS,
+  ORCHESTRATOR_TOOLS,
+  VISIBLE_TOOLS
+} from './definitions.js'
+
+// Tool discovery functions
+export {
+  getAvailableTools,
+  getAllTools,
+  findTool,
+  toolExists,
+  getToolType
+} from './discovery.js'

package/mcp-client/utils/content.js

@@ -0,0 +1,126 @@
+/**
+ * Suparank MCP - Content Utilities
+ *
+ * Content saving and folder management utilities
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { log, progress } from './logging.js'
+import {
+  ensureContentDir,
+  getContentFolderSafe,
+  atomicWriteSync,
+  slugify
+} from './paths.js'
+import { sessionState } from '../services/session-state.js'
+import { projectSlug } from '../config.js'
+
+/**
+ * Save current article content to a folder on disk
+ * Creates a folder with article.md, metadata.json, and optional workflow.json
+ * @returns {string|null} Folder path on success, null on failure
+ */
+export function saveContentToFolder() {
+  if (!sessionState.title || !sessionState.article) {
+    return null
+  }
+
+  try {
+    ensureContentDir()
+
+    // Create folder name: YYYY-MM-DD-slug (slugify removes dangerous characters)
+    const date = new Date().toISOString().split('T')[0]
+    const slug = slugify(sessionState.title)
+    const folderName = `${date}-${slug}`
+
+    // Use safe path function to prevent any path traversal
+    const folderPath = getContentFolderSafe(folderName)
+
+    // Create folder if doesn't exist
+    if (!fs.existsSync(folderPath)) {
+      fs.mkdirSync(folderPath, { recursive: true })
+    }
+
+    // Save markdown article
+    atomicWriteSync(
+      path.join(folderPath, 'article.md'),
+      sessionState.article
+    )
+
+    // Save metadata
+    const metadata = {
+      title: sessionState.title,
+      keywords: sessionState.keywords || [],
+      metaDescription: sessionState.metaDescription || '',
+      metaTitle: sessionState.metaTitle || sessionState.title,
+      imageUrl: sessionState.imageUrl,
+      inlineImages: sessionState.inlineImages || [],
+      wordCount: sessionState.article.split(/\s+/).length,
+      createdAt: new Date().toISOString(),
+      projectSlug: projectSlug
+    }
+    atomicWriteSync(
+      path.join(folderPath, 'metadata.json'),
+      JSON.stringify(metadata, null, 2)
+    )
+
+    // Save workflow state for resuming
+    if (sessionState.currentWorkflow) {
+      atomicWriteSync(
+        path.join(folderPath, 'workflow.json'),
+        JSON.stringify({
+          workflow: sessionState.currentWorkflow,
+          stepResults: sessionState.stepResults,
+          savedAt: new Date().toISOString()
+        }, null, 2)
+      )
+    }
+
+    // Store folder path in session
+    sessionState.contentFolder = folderPath
+
+    progress('Content', `Saved to folder: ${folderPath}`)
+    return folderPath
+  } catch (error) {
+    log(`Warning: Failed to save content to folder: ${error.message}`)
+    return null
+  }
+}
+
+/**
+ * Extract image prompts from article content
+ * Looks for [IMAGE: description] placeholders
+ * @param {string} content - Article content
+ * @returns {string[]} Array of image prompt descriptions
+ */
+export function extractImagePromptsFromArticle(content) {
+  const prompts = []
+  const regex = /\[IMAGE:\s*([^\]]+)\]/gi
+  let match
+
+  while ((match = regex.exec(content)) !== null) {
+    prompts.push(match[1].trim())
+  }
+
+  return prompts
+}
+
+/**
+ * Inject image URLs into article content
+ * Replaces [IMAGE: ...] placeholders with markdown images
+ * @param {string} content - Article content with placeholders
+ * @param {string[]} imageUrls - Array of image URLs to inject
+ * @returns {string} Content with images injected
+ */
+export function injectImagesIntoContent(content, imageUrls) {
+  let imageIndex = 0
+  return content.replace(/\[IMAGE:\s*([^\]]+)\]/gi, (match, description) => {
+    if (imageIndex < imageUrls.length) {
+      const imgUrl = imageUrls[imageIndex]
+      imageIndex++
+      return `![${description.trim()}](${imgUrl})`
+    }
+    return match // Keep placeholder if no image available
+  })
+}

package/mcp-client/utils/formatting.js

@@ -0,0 +1,71 @@
+/**
+ * Suparank MCP - Formatting Utilities
+ *
+ * Content formatting and conversion utilities
+ */
+
+import { marked } from 'marked'
+import { log } from './logging.js'
+
+/**
+ * Convert markdown to HTML using marked library
+ * Configured for WordPress/Ghost CMS compatibility
+ * @param {string} markdown - Markdown content
+ * @returns {string} HTML content
+ */
+export function markdownToHtml(markdown) {
+  // Configure marked for CMS compatibility
+  marked.setOptions({
+    gfm: true,        // GitHub Flavored Markdown
+    breaks: true,     // Convert line breaks to <br>
+    pedantic: false,
+    silent: true      // Don't throw on errors
+  })
+
+  try {
+    return marked.parse(markdown)
+  } catch (error) {
+    log(`Markdown conversion error: ${error.message}`)
+    // Fallback: return markdown wrapped in <p> tags
+    return `<p>${markdown.replace(/\n\n+/g, '</p><p>')}</p>`
+  }
+}
+
+/**
+ * Convert aspect ratio string to fal.ai image size
+ * @param {string} ratio - Aspect ratio (e.g., '16:9', '1:1')
+ * @returns {string} fal.ai size identifier
+ */
+export function aspectRatioToSize(ratio) {
+  const sizes = {
+    '1:1': 'square',
+    '16:9': 'landscape_16_9',
+    '9:16': 'portrait_16_9',
+    '4:3': 'landscape_4_3',
+    '3:4': 'portrait_4_3'
+  }
+  return sizes[ratio] || 'landscape_16_9'
+}
+
+/**
+ * Truncate text to a maximum length
+ * @param {string} text - Text to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated text
+ */
+export function truncate(text, maxLength = 100) {
+  if (!text || text.length <= maxLength) return text
+  return text.substring(0, maxLength) + '...'
+}
+
+/**
+ * Sanitize a string for use as a slug/filename
+ * @param {string} str - String to sanitize
+ * @returns {string} Sanitized string
+ */
+export function slugify(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}

package/mcp-client/utils/index.js

@@ -0,0 +1,10 @@
+/**
+ * Suparank MCP - Utils Index
+ *
+ * Re-exports all utility modules
+ */
+
+export * from './logging.js'
+export * from './paths.js'
+export * from './formatting.js'
+export * from './content.js'

package/mcp-client/utils/logging.js

@@ -0,0 +1,38 @@
+/**
+ * Suparank MCP - Logging Utilities
+ *
+ * Standardized logging to stderr (stdout is for MCP protocol)
+ */
+
+/**
+ * Log message to stderr with [suparank] prefix
+ * @param {...any} args - Arguments to log
+ */
+export function log(...args) {
+  console.error('[suparank]', ...args)
+}
+
+/**
+ * Structured progress logging for user visibility
+ * @param {string} step - Current step name
+ * @param {string} message - Progress message
+ */
+export function progress(step, message) {
+  console.error(`[suparank] ${step}: ${message}`)
+}
+
+/**
+ * Log warning message
+ * @param {...any} args - Arguments to log
+ */
+export function warn(...args) {
+  console.error('[suparank] WARNING:', ...args)
+}
+
+/**
+ * Log error message
+ * @param {...any} args - Arguments to log
+ */
+export function error(...args) {
+  console.error('[suparank] ERROR:', ...args)
+}

package/mcp-client/utils/paths.js

@@ -0,0 +1,134 @@
+/**
+ * Suparank MCP - Path Utilities
+ *
+ * Safe path handling and directory management
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import * as os from 'os'
+
+/**
+ * Get the Suparank configuration directory
+ * @returns {string} Path to ~/.suparank
+ */
+export function getSuparankDir() {
+  return path.join(os.homedir(), '.suparank')
+}
+
+/**
+ * Get the content storage directory
+ * @returns {string} Path to ~/.suparank/content
+ */
+export function getContentDir() {
+  return path.join(getSuparankDir(), 'content')
+}
+
+/**
+ * Get session file path
+ * @returns {string} Path to ~/.suparank/session.json
+ */
+export function getSessionFilePath() {
+  return path.join(getSuparankDir(), 'session.json')
+}
+
+/**
+ * Get credentials file path
+ * @returns {string} Path to ~/.suparank/credentials.json
+ */
+export function getCredentialsFilePath() {
+  return path.join(getSuparankDir(), 'credentials.json')
+}
+
+/**
+ * Get stats file path
+ * @returns {string} Path to ~/.suparank/stats.json
+ */
+export function getStatsFilePath() {
+  return path.join(getSuparankDir(), 'stats.json')
+}
+
+/**
+ * Ensure the Suparank directory exists
+ */
+export function ensureSuparankDir() {
+  const dir = getSuparankDir()
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * Ensure the content directory exists
+ */
+export function ensureContentDir() {
+  const dir = getContentDir()
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+/**
+ * Sanitize and validate a path to prevent traversal attacks
+ * @param {string} userPath - User-provided path segment
+ * @param {string} allowedBase - Base directory that paths must stay within
+ * @returns {string} Resolved safe path
+ * @throws {Error} If path would escape the allowed base
+ */
+export function sanitizePath(userPath, allowedBase) {
+  // Remove any null bytes (common attack vector)
+  const cleanPath = userPath.replace(/\0/g, '')
+
+  // Resolve to absolute path
+  const resolved = path.resolve(allowedBase, cleanPath)
+
+  // Ensure the resolved path starts with the allowed base
+  const normalizedBase = path.normalize(allowedBase + path.sep)
+  const normalizedResolved = path.normalize(resolved + path.sep)
+
+  if (!normalizedResolved.startsWith(normalizedBase)) {
+    throw new Error(`Path traversal detected: "${userPath}" would escape allowed directory`)
+  }
+
+  return resolved
+}
+
+/**
+ * Get content folder path safely
+ * @param {string} folderName - Folder name (article ID or title slug)
+ * @returns {string} Safe path to content folder
+ */
+export function getContentFolderSafe(folderName) {
+  const contentDir = getContentDir()
+  return sanitizePath(folderName, contentDir)
+}
+
+/**
+ * Generate a slug from title for folder naming
+ * @param {string} text - Text to slugify
+ * @returns {string} URL-safe slug
+ */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 50)
+}
+
+/**
+ * Atomic file write - prevents corruption on concurrent writes
+ * @param {string} filePath - Target file path
+ * @param {string} data - Data to write
+ */
+export function atomicWriteSync(filePath, data) {
+  const tmpFile = filePath + '.tmp.' + process.pid
+  try {
+    fs.writeFileSync(tmpFile, data)
+    fs.renameSync(tmpFile, filePath) // Atomic on POSIX
+  } catch (error) {
+    // Clean up temp file if rename failed
+    try { fs.unlinkSync(tmpFile) } catch (e) { /* ignore */ }
+    throw error
+  }
+}

package/mcp-client/workflow/index.js

@@ -0,0 +1,10 @@
+/**
+ * Suparank MCP - Workflow Module
+ *
+ * Re-exports workflow planning functions
+ */
+
+export {
+  buildWorkflowPlan,
+  validateProjectConfig
+} from './planner.js'