@sylphx/flow 1.0.1 → 1.0.3

package/src/domains/knowledge/tools.ts

@@ -0,0 +1,174 @@
+/**
+ * Knowledge tools
+ * All tools for working with knowledge base, documentation, and guides
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getSearchService } from '../../services/search/unified-search-service.js';
+import { getKnowledgeContent } from './resources.js';
+
+/**
+ * Register knowledge search tool
+ */
+export function registerKnowledgeSearchTool(server: McpServer): void {
+  server.registerTool(
+    'knowledge_search',
+    {
+      description: `Search knowledge base, documentation, guides, and reference materials. Use this for domain knowledge, best practices, setup instructions, and conceptual information.
+
+**IMPORTANT: Use this tool PROACTIVELY before starting work, not reactively when stuck.**
+
+This tool searches across all knowledge resources and returns the most relevant matches. Use include_content=false to reduce context usage, then use knowledge_get for specific documents.
+
+When to use this tool (BEFORE starting work):
+- **Before research/clarification**: Check relevant stack/universal knowledge to understand domain constraints
+- **Before design/architecture**: Review architecture patterns, security, and performance best practices
+- **Before implementation**: Consult framework-specific patterns, common pitfalls, and best practices
+- **Before testing/QA**: Review testing strategies, coverage requirements, and quality standards
+- **Before deployment**: Check deployment patterns, infrastructure, and monitoring guidance
+
+Available knowledge categories:
+- **stacks**: Framework-specific patterns (React, Next.js, Node.js)
+- **data**: Database patterns (SQL, indexing, migrations)
+- **guides**: Architecture guidance (SaaS, tech stack, UI/UX)
+- **universal**: Cross-cutting concerns (security, performance, testing, deployment)
+
+The knowledge is curated for LLM code generation - includes decision trees, common bugs, and practical patterns.
+
+**Best Practice**: Check relevant knowledge BEFORE making decisions or writing code, not after encountering issues.`,
+      inputSchema: {
+        query: z
+          .string()
+          .describe('Search query - use natural language, technology names, or topic keywords'),
+        limit: z
+          .number()
+          .default(10)
+          .optional()
+          .describe('Maximum number of results to return (default: 10)'),
+        include_content: z
+          .boolean()
+          .default(true)
+          .optional()
+          .describe(
+            'Include full content in results (default: true). Use false to reduce context, then knowledge_get for specific docs'
+          ),
+      },
+    },
+    async ({ query, limit = 10, include_content = true }) => {
+      try {
+        // Use unified search service - same logic as CLI
+        const searchService = getSearchService();
+        await searchService.initialize();
+
+        // Check knowledge base status
+        const status = await searchService.getStatus();
+
+        if (status.knowledge.isIndexing) {
+          const progressBar =
+            '█'.repeat(Math.floor((status.knowledge.progress || 0) / 5)) +
+            '░'.repeat(20 - Math.floor((status.knowledge.progress || 0) / 5));
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `⏳ **Knowledge Base Indexing In Progress**\n\nThe knowledge base is currently being indexed. Please wait...\n\n**Progress:** ${status.knowledge.progress || 0}%\n\`${progressBar}\`\n\n**Status:**\n- Documents: ${status.knowledge.documentCount || 0}\n- Building search index for knowledge resources\n\n**Estimated time:** ${status.knowledge.progress && status.knowledge.progress > 0 ? 'Less than 10 seconds' : 'Starting...'}\n\n💡 **Tip:** Knowledge base indexing is very fast. Try your search again in a few seconds.`,
+              },
+            ],
+          };
+        }
+
+        if (!status.knowledge.indexed) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: '📭 **No Knowledge Documents Available**\n\nThe knowledge base appears to be empty or not properly initialized.\n\n**To fix:**\n- Check if knowledge files exist in assets/knowledge/\n- Try restarting the MCP server to trigger indexing\n- Use CLI: `sylphx search status` for diagnostics\n\n**Expected knowledge files:**\n- stacks/ (framework-specific patterns)\n- guides/ (architecture guidance)\n- universal/ (cross-cutting concerns)\n- data/ (database patterns)',
+              },
+            ],
+          };
+        }
+
+        // Search knowledge base using unified service
+        const result = await searchService.searchKnowledge(query, {
+          limit,
+          include_content,
+        });
+
+        // Return MCP format using unified service formatter
+        return searchService.formatResultsForMCP(result.results, query, result.totalIndexed);
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✗ Knowledge search error: ${(error as Error).message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+}
+
+/**
+ * Register get_knowledge tool (for retrieving specific knowledge documents)
+ */
+export function registerGetKnowledgeTool(server: McpServer): void {
+  server.registerTool(
+    'knowledge_get',
+    {
+      description: `Get knowledge resource by exact URI.
+
+**NOTE: Prefer using 'knowledge_search' with include_content=false first, then use this tool for specific documents.**
+
+This tool retrieves a specific knowledge resource when you already know its exact URI from search results.
+
+The available URIs are dynamically generated from the indexed knowledge base. Use 'knowledge_search' to discover relevant URIs first.`,
+      inputSchema: {
+        uri: z.string().describe('Knowledge URI to access (e.g., "knowledge://stacks/react-app")'),
+      },
+    },
+    async ({ uri }) => {
+      try {
+        const content = await getKnowledgeContent(uri);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: content,
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+
+        // Dynamically get available URIs
+        const searchService = getSearchService();
+        const availableURIs = await searchService.getAvailableKnowledgeURIs();
+        const uriList =
+          availableURIs.length > 0
+            ? availableURIs.map((uri) => `• ${uri}`).join('\n')
+            : 'No knowledge documents available';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✗ Error: ${errorMessage}\n\nAvailable knowledge URIs:\n${uriList}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}
+
+/**
+ * Register all knowledge tools
+ */
+export function registerKnowledgeTools(server: McpServer): void {
+  registerKnowledgeSearchTool(server);
+  registerGetKnowledgeTool(server);
+}

package/src/domains/utilities/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Utilities Domain
+ * Common utility tools and helpers
+ */
+
+export * from './time/index.js';

package/src/domains/utilities/time/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Time utilities domain - Time and date operations
+ */
+
+export { registerTimeTools } from './tools.js';

package/src/domains/utilities/time/tools.ts

@@ -0,0 +1,291 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+// Logger utility
+const Logger = {
+  info: (message: string) => console.error(`[INFO] ${message}`),
+  success: (message: string) => console.error(`[SUCCESS] ${message}`),
+  error: (message: string, error?: unknown) => {
+    console.error(`[ERROR] ${message}`);
+    if (error) {
+      console.error(error);
+    }
+  },
+};
+
+// Helper function to validate IANA timezone
+function isValidTimezone(timezone: string): boolean {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: timezone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Helper function to validate time format (HH:MM)
+function isValidTimeFormat(time: string): boolean {
+  const timeRegex = /^([01]?[0-9]|2[0-3]):[0-5][0-9]$/;
+  return timeRegex.test(time);
+}
+
+// Get current time in a specific timezone
+function getCurrentTime(args: { timezone: string }): CallToolResult {
+  try {
+    const { timezone } = args;
+
+    // Validate timezone
+    if (!isValidTimezone(timezone)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✗ Invalid timezone: ${timezone}. Please use a valid IANA timezone name (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo').`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Get current time in specified timezone
+    const now = new Date();
+    const timeFormatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      timeZoneName: 'long',
+      hour12: false,
+    });
+
+    const parts = timeFormatter.formatToParts(now);
+    const formatObject: Record<string, string> = {};
+    for (const part of parts) {
+      formatObject[part.type] = part.value;
+    }
+
+    const time24 = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    }).format(now);
+
+    const isoString = now.toLocaleString('sv-SE', { timeZone: timezone });
+
+    Logger.info(`Retrieved current time for timezone: ${timezone}`);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              timezone,
+              current_time: {
+                date: `${formatObject.month} ${formatObject.day}, ${formatObject.year}`,
+                time_24h: time24,
+                time_with_seconds: timeFormatter.format(now),
+                timezone_name: formatObject.timeZoneName,
+                iso_format: `${isoString.replace(' ', 'T')}Z`,
+                unix_timestamp: Math.floor(now.getTime() / 1000),
+              },
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    Logger.error('Error getting current time', error);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `✗ Error getting current time: ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+// Convert time between timezones
+function convertTime(args: {
+  source_timezone: string;
+  time: string;
+  target_timezone: string;
+}): CallToolResult {
+  try {
+    const { source_timezone, time, target_timezone } = args;
+
+    // Validate timezones
+    if (!isValidTimezone(source_timezone)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✗ Invalid source timezone: ${source_timezone}. Please use a valid IANA timezone name.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!isValidTimezone(target_timezone)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✗ Invalid target timezone: ${target_timezone}. Please use a valid IANA timezone name.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Validate time format
+    if (!isValidTimeFormat(time)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✗ Invalid time format: ${time}. Please use 24-hour format (HH:MM).`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Parse the time and create a date object for today in source timezone
+    const [hours, minutes] = time.split(':').map(Number);
+    const now = new Date();
+
+    // Create a date object representing the time in source timezone
+    const sourceDate = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hours, minutes);
+
+    // Format the source time to get the correct representation
+    const sourceFormatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: source_timezone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+    });
+
+    const sourceParts = sourceFormatter.formatToParts(sourceDate);
+    const sourceFormatObject: Record<string, string> = {};
+    for (const part of sourceParts) {
+      sourceFormatObject[part.type] = part.value;
+    }
+
+    // Convert to target timezone
+    const targetFormatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: target_timezone,
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      timeZoneName: 'long',
+      hour12: false,
+    });
+
+    const targetTime24 = new Intl.DateTimeFormat('en-US', {
+      timeZone: target_timezone,
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    }).format(sourceDate);
+
+    const targetParts = targetFormatter.formatToParts(sourceDate);
+    const targetFormatObject: Record<string, string> = {};
+    for (const part of targetParts) {
+      targetFormatObject[part.type] = part.value;
+    }
+
+    const targetDate = new Date(sourceDate.toLocaleString('en-US', { timeZone: target_timezone }));
+    const timeDiffMs = targetDate.getTime() - sourceDate.getTime();
+    const timeDiffHours = Math.round(timeDiffMs / (1000 * 60 * 60));
+
+    Logger.info(`Converted time from ${source_timezone} to ${target_timezone}`);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              conversion: {
+                source: {
+                  timezone: source_timezone,
+                  time: time,
+                  formatted: sourceFormatter.format(sourceDate),
+                },
+                target: {
+                  timezone: target_timezone,
+                  time_24h: targetTime24,
+                  formatted: targetFormatter.format(sourceDate),
+                  date: `${targetFormatObject.month} ${targetFormatObject.day}, ${targetFormatObject.year}`,
+                  timezone_name: targetFormatObject.timeZoneName,
+                },
+                time_difference_hours: timeDiffHours,
+              },
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    Logger.error('Error converting time', error);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `✗ Error converting time: ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+// Register all time tools
+export function registerTimeTools(server: McpServer) {
+  server.registerTool(
+    'get_current_time',
+    {
+      description: 'Get current time in a specific timezone or system timezone',
+      inputSchema: {
+        timezone: z
+          .string()
+          .describe("IANA timezone name (e.g., 'America/New_York', 'Europe/London')"),
+      },
+    },
+    getCurrentTime
+  );
+
+  server.registerTool(
+    'convert_time',
+    {
+      description: 'Convert time between timezones',
+      inputSchema: {
+        source_timezone: z.string().describe('Source IANA timezone name'),
+        time: z.string().describe('Time in 24-hour format (HH:MM)'),
+        target_timezone: z.string().describe('Target IANA timezone name'),
+      },
+    },
+    convertTime
+  );
+}

package/src/index.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env bun
+/**
+ * Sylphx Flow - Legacy CLI
+ * Project initialization and development flow management
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { codebaseCommand } from './commands/codebase-command.js';
+import { hookCommand } from './commands/hook-command.js';
+import { knowledgeCommand } from './commands/knowledge-command.js';
+import {
+  flowCommand,
+  statusCommand,
+  setupCommand,
+  doctorCommand,
+  upgradeCommand,
+  executeFlow,
+} from './commands/flow-command.js';
+
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const VERSION = packageJson.version;
+
+/**
+ * Create the main CLI application with enhanced Commander.js configuration
+ */
+export function createCLI(): Command {
+  const program = new Command();
+
+  // Configure main program with better defaults
+  program
+    .name('sylphx-flow')
+    .description('Sylphx Flow - Type-safe development flow CLI')
+    .version(VERSION, '-V, --version', 'Show version number')
+    .helpOption('-h, --help', 'Display help for command')
+    .configureHelp({
+      sortSubcommands: true,
+      showGlobalOptions: true,
+    });
+
+  // Enable strict mode for better error handling
+  program.configureOutput({
+    writeErr: (str) => process.stderr.write(str),
+    writeOut: (str) => process.stdout.write(str),
+  });
+
+  // Default action: delegate to flow command for convenience
+  // This allows `sylphx-flow "prompt"` instead of requiring `sylphx-flow flow "prompt"`
+  program
+    .argument('[prompt]', 'Prompt to execute with agent (optional, supports @file.txt for file input)')
+    .option('--init-only', 'Only initialize, do not run')
+    .option('--run-only', 'Only run, skip initialization')
+    .option('--sync', 'Synchronize with Flow templates (delete and re-install template files)')
+    .option('--upgrade', 'Upgrade Sylphx Flow to latest version')
+    .option('--upgrade-target', 'Upgrade target platform (Claude Code/OpenCode)')
+    .option('--quick', 'Quick mode: use saved defaults and skip all prompts')
+    .option('--select-provider', 'Prompt to select provider each run')
+    .option('--select-agent', 'Prompt to select agent each run')
+    .option('--use-defaults', 'Skip prompts, use saved defaults')
+    .option('--provider <provider>', 'Override provider for this run (anthropic|z.ai|kimi)')
+    .option('--target <type>', 'Target platform (opencode, claude-code, auto-detect)')
+    .option('--verbose', 'Show detailed output')
+    .option('--dry-run', 'Show what would be done without making changes')
+    .option('--no-mcp', 'Skip MCP installation')
+    .option('--no-agents', 'Skip agents installation')
+    .option('--no-rules', 'Skip rules installation')
+    .option('--no-output-styles', 'Skip output styles installation')
+    .option('--no-slash-commands', 'Skip slash commands installation')
+    .option('--no-hooks', 'Skip hooks setup')
+    .option('--agent <name>', 'Agent to use (default: coder)', 'coder')
+    .option('--agent-file <path>', 'Load agent from specific file')
+    .option('-p, --print', 'Headless print mode (output only, no interactive)')
+    .option('-c, --continue', 'Continue previous conversation (requires print mode)')
+
+    // Loop mode options
+    .option('--loop [seconds]', 'Loop mode: wait N seconds between runs (default: 0 = immediate)', (value) => {
+      // If no value provided, default to 0 (no wait time)
+      return value ? parseInt(value) : 0;
+    })
+    .option('--max-runs <count>', 'Maximum iterations before stopping (default: infinite)', parseInt)
+
+    .action(async (prompt, options) => {
+      await executeFlow(prompt, options);
+    });
+
+  // Add subcommands - these can still be used explicitly
+  program.addCommand(flowCommand);
+  program.addCommand(setupCommand);
+  program.addCommand(statusCommand);
+  program.addCommand(doctorCommand);
+  program.addCommand(upgradeCommand);
+  program.addCommand(codebaseCommand);
+  program.addCommand(knowledgeCommand);
+  program.addCommand(hookCommand);
+
+  return program;
+}
+
+/**
+ * Run the CLI application with enhanced error handling and process management
+ */
+export async function runCLI(): Promise<void> {
+  const program = createCLI();
+
+  // Set up global error handling before parsing
+  setupGlobalErrorHandling();
+
+  try {
+    // Parse and execute commands - use parseAsync for async actions
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    handleCommandError(error);
+  }
+}
+
+/**
+ * Set up global error handlers for uncaught exceptions and unhandled rejections
+ */
+function setupGlobalErrorHandling(): void {
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error) => {
+    console.error('✗ Uncaught Exception:');
+    console.error(`  ${error.message}`);
+    if (process.env.NODE_ENV === 'development') {
+      console.error('  Stack trace:', error.stack);
+    }
+    process.exit(1);
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason, promise) => {
+    // Ignore AbortError - this is expected when user cancels operations
+    if (reason instanceof Error && reason.name === 'AbortError') {
+      return;
+    }
+
+    // Only log unhandled rejections in development mode
+    // Don't exit the process - let the application handle errors gracefully
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+      console.error('✗ Unhandled Promise Rejection:');
+      console.error(`  Reason: ${reason}`);
+      console.error('  Promise:', promise);
+    }
+  });
+
+  // Handle process termination gracefully
+  process.on('SIGINT', () => {
+    console.log('\nSylphx Flow CLI terminated by user');
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    console.log('\nSylphx Flow CLI terminated');
+    process.exit(0);
+  });
+
+  // Ensure clean exit by allowing the event loop to drain
+  process.on('beforeExit', () => {
+    // Node.js will exit automatically after this handler completes
+    // No explicit process.exit() needed
+  });
+}
+
+/**
+ * Handle command execution errors with proper formatting
+ */
+function handleCommandError(error: unknown): void {
+  if (error instanceof Error) {
+    // Handle Commander.js specific errors
+    if (error.name === 'CommanderError') {
+      const commanderError = error as any;
+
+      // Don't exit for help or version commands - they should already be handled
+      if (commanderError.code === 'commander.help' || commanderError.code === 'commander.version') {
+        return;
+      }
+
+      // For other Commander.js errors, show the message and exit
+      console.error(`✗ ${commanderError.message}`);
+      process.exit(commanderError.exitCode || 1);
+    }
+
+    // Handle CLI errors with better formatting
+    console.error(`✗ Error: ${error.message}`);
+
+    // Show stack trace in development mode
+    if (process.env.NODE_ENV === 'development' && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+  } else {
+    console.error(`✗ Unknown error: ${String(error)}`);
+  }
+
+  process.exit(1);
+}
+
+// Execute CLI when run as script
+(async () => {
+  try {
+    await runCLI();
+  } catch (error) {
+    handleCommandError(error);
+  }
+})();