@sylphx/flow 1.8.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @sylphx/flow
 
+## 2.0.0
+
+### Major Changes
+
+- aaadcaa: Settings-based configuration and improved user experience
+
+  **New Features:**
+
+  - **Settings management**: Configure agents, rules, and output styles via `sylphx-flow settings`
+    - Select which agents are enabled
+    - Set default agent to use
+    - Enable/disable specific rules (core, code-standards, workspace)
+    - Enable/disable output styles (silent)
+  - **Settings-driven execution**: Flow respects your settings and only loads enabled components
+  - **Config files**: All settings stored in `~/.sylphx-flow/` (settings.json, flow-config.json, provider-config.json, mcp-config.json)
+  - **Git skip-worktree integration**: Flow automatically hides `.claude/` and `.opencode/` changes from git
+    - Uses `git update-index --skip-worktree` to hide Flow's temporary modifications
+    - Prevents LLM from seeing or committing Flow's settings changes
+    - Automatically restores git tracking after execution
+    - Works seamlessly with version-controlled settings
+
+  **Breaking Changes:**
+
+  - Removed `--quick` flag - no longer needed
+  - Removed first-run setup wizard - configs are created automatically with sensible defaults
+  - Agent loading now respects enabled rules and output styles from settings
+
+  **Improvements:**
+
+  - Config files are automatically initialized on first use with default values
+  - Provider selection happens inline when needed (if set to "ask-every-time")
+  - Fixed Ctrl+C handling to ensure settings are restored immediately
+  - Simplified CLI options - only `--merge` flag for attach strategy
+  - Default agent can be set in settings (falls back to 'coder' if not set)
+
+  **Ctrl+C Fix:**
+  When users press Ctrl+C during interactive prompts, the application now:
+
+  - Catches the cancellation gracefully
+  - Runs cleanup (restores backed-up settings)
+  - Shows a friendly cancellation message
+  - Exits cleanly
+
+  Previously, pressing Ctrl+C would exit immediately without restoring settings, requiring recovery on the next run.
+
+### Minor Changes
+
+- 9fa65d4: Add automatic upgrade detection with smart package manager support
+
+  - Auto-detect updates on startup with non-intrusive notifications
+  - Enhanced `upgrade` command with `--auto` flag for automatic installation
+  - Smart package manager detection (npm, bun, pnpm, yarn)
+  - Version checking against npm registry for both Flow and target platforms
+  - Package-manager-specific upgrade commands in notifications
+  - New UPGRADE.md documentation with package manager support
+  - Silent background checks that don't block execution
+  - Support for both interactive and automatic upgrade flows
+  - Comprehensive test coverage for package manager detection
+
+## 1.8.2
+
+### Patch Changes
+
+- 9059450: Enhance Next Actions section with suggestions when no clear next step
+
+  Updated completion report structure to include proactive suggestions in Next Actions section:
+
+  - Remaining work (existing functionality)
+  - Suggestions when no clear next step (new)
+
+  Benefits:
+
+  - Guides user on potential improvements
+  - Provides proactive recommendations
+  - Helps prevent "what's next?" moments
+  - Encourages continuous iteration
+
+  Example updated to show suggestion format: "Consider adding rate limiting, implement refresh token rotation, add logging for security events"
+
 ## 1.8.1
 
 ### Patch Changes

package/UPGRADE.md

@@ -0,0 +1,140 @@
+# Upgrade Guide
+
+Sylphx Flow includes built-in upgrade detection and automatic update capabilities with **smart package manager detection**.
+
+## Auto-Detection on Startup
+
+Every time you run Sylphx Flow, it automatically checks for available updates in the background. If an update is available, you'll see a notification like:
+
+```
+📦 Sylphx Flow update available: 1.8.1 → 1.9.0
+   Quick upgrade: sylphx-flow upgrade --auto
+   Or run: bun install -g @sylphx/flow@latest
+```
+
+The upgrade command is automatically tailored to your detected package manager (npm, bun, pnpm, or yarn).
+
+This check is non-intrusive and won't block your workflow. Use `--quick` mode to skip the check entirely.
+
+## Manual Upgrade Check
+
+Check for available updates without installing:
+
+```bash
+sylphx-flow upgrade --check
+```
+
+## Upgrade Commands
+
+### Upgrade Sylphx Flow
+
+Upgrade to the latest version:
+
+```bash
+# Interactive upgrade (manual installation required)
+sylphx-flow upgrade
+
+# Automatic installation via npm
+sylphx-flow upgrade --auto
+```
+
+### Upgrade Target Platform
+
+Upgrade Claude Code or other target platforms:
+
+```bash
+# Interactive upgrade
+sylphx-flow upgrade --target
+
+# Automatic installation via npm
+sylphx-flow upgrade --target --auto
+```
+
+### Combined Upgrade
+
+Upgrade both Sylphx Flow and target platform:
+
+```bash
+sylphx-flow upgrade --target --auto
+```
+
+## Options
+
+- `--check` - Only check for updates, don't install
+- `--auto` - Automatically install updates via npm (no manual steps)
+- `--target` - Include target platform (Claude Code/OpenCode) upgrade
+- `--verbose` - Show detailed installation output
+
+## Package Manager Detection
+
+Sylphx Flow automatically detects which package manager you're using:
+
+1. **From Environment** (`npm_config_user_agent`): Most reliable when running as npm script
+2. **From Lock Files**: Checks for `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`
+3. **Default**: Falls back to `npm` if no detection method works
+
+**Priority Order**: bun > pnpm > yarn > npm
+
+### Supported Package Managers
+
+| Package Manager | Global Install Command |
+|----------------|------------------------|
+| npm            | `npm install -g @sylphx/flow@latest` |
+| bun            | `bun install -g @sylphx/flow@latest` |
+| pnpm           | `pnpm install -g @sylphx/flow@latest` |
+| yarn           | `yarn global add @sylphx/flow@latest` |
+
+## How It Works
+
+1. **Version Detection**: Checks npm registry for latest published versions
+2. **Comparison**: Compares installed version with latest available
+3. **Package Manager Detection**: Automatically detects npm/bun/pnpm/yarn
+4. **Notification**: Shows update availability with package-manager-specific command
+5. **Installation**:
+   - Without `--auto`: Shows manual install command for your package manager
+   - With `--auto`: Runs the appropriate install command automatically
+
+## Disabling Auto-Check
+
+Use `--quick` mode to skip automatic update checks:
+
+```bash
+sylphx-flow --quick "your prompt here"
+```
+
+## Troubleshooting
+
+### Auto-Install Fails
+
+If `--auto` installation fails, the error message will show the exact command to run manually. The command is tailored to your package manager:
+
+```bash
+# Example for bun users
+bun install -g @sylphx/flow@latest
+
+# Example for npm users
+npm install -g @sylphx/flow@latest
+```
+
+### Version Mismatch
+
+If you see version mismatches after upgrade, try:
+
+```bash
+# Re-sync components with latest templates
+sylphx-flow --sync
+```
+
+### Offline Mode
+
+Update checks require internet connection. If offline, checks will fail silently and won't block execution.
+
+## Version Compatibility
+
+Sylphx Flow follows semantic versioning:
+
+- **Patch** (1.8.x): Bug fixes, safe to upgrade
+- **Minor** (1.x.0): New features, backward compatible
+- **Major** (x.0.0): Breaking changes, check migration guide
+
+Always check CHANGELOG.md for breaking changes before upgrading major versions.

package/assets/output-styles/silent.md

@@ -68,6 +68,7 @@ Report what was accomplished. Structured, comprehensive, reviewable.
 
 ## Next Actions
 - [ ] [Remaining work]
+- [Suggestions when no clear next step]
 ```
 
 #### 🔵 Tier 3: Major Changes Only
@@ -138,6 +139,9 @@ Refactored authentication system to use JWT tokens instead of sessions.
 - Added: jsonwebtoken@9.0.0 (JWT signing/verification)
 - Removed: express-session@1.17.0 (replaced by JWT)
 
+## Next Actions
+- Suggestions: Consider adding rate limiting, implement refresh token rotation, add logging for security events
+
 ## Migration
 Users need to:
 1. Update client to store tokens: `localStorage.setItem('token', response.token)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/flow",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "AI-powered development workflow automation with autonomous loop mode and smart configuration",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
     "README.md",
     "CHANGELOG.md",
     "LOOP_MODE.md",
+    "UPGRADE.md",
     "package.json"
   ],
   "keywords": [

package/src/commands/flow/execute-v2.ts

@@ -0,0 +1,278 @@
+/**
+ * Execution Logic for Flow Command (V2 - Attach Mode)
+ * New execution flow with attach-mode lifecycle
+ */
+
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { FlowExecutor } from '../../core/flow-executor.js';
+import { targetManager } from '../../core/target-manager.js';
+import { UpgradeManager } from '../../core/upgrade-manager.js';
+import { showWelcome } from '../../utils/display/banner.js';
+import { loadAgentContent, extractAgentInstructions } from '../run-command.js';
+import { CLIError } from '../../utils/error-handler.js';
+import type { RunCommandOptions } from '../../types.js';
+import type { FlowOptions } from './types.js';
+import { resolvePrompt } from './prompt.js';
+import { GlobalConfigService } from '../../services/global-config.js';
+import { UserCancelledError } from '../../utils/errors.js';
+
+/**
+ * Select and configure provider for Claude Code
+ */
+async function selectProvider(
+  configService: GlobalConfigService
+): Promise<void> {
+  try {
+    const providerConfig = await configService.loadProviderConfig();
+    const defaultProvider = providerConfig.claudeCode.defaultProvider;
+
+  // If not "ask-every-time", use the default provider
+  if (defaultProvider !== 'ask-every-time') {
+    // Configure environment variables for the selected provider
+    if (defaultProvider === 'kimi' || defaultProvider === 'zai') {
+      const provider = providerConfig.claudeCode.providers[defaultProvider];
+      if (provider?.apiKey) {
+        if (defaultProvider === 'kimi') {
+          process.env.ANTHROPIC_BASE_URL = 'https://api.moonshot.cn/v1';
+          process.env.ANTHROPIC_API_KEY = provider.apiKey;
+        } else if (defaultProvider === 'zai') {
+          process.env.ANTHROPIC_BASE_URL = 'https://api.z.ai/v1';
+          process.env.ANTHROPIC_API_KEY = provider.apiKey;
+        }
+      }
+    }
+    return;
+  }
+
+  // Ask user which provider to use for this session
+  const { selectedProvider } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'selectedProvider',
+      message: 'Select provider for this session:',
+      choices: [
+        { name: 'Default (Claude Code built-in)', value: 'default' },
+        { name: 'Kimi', value: 'kimi' },
+        { name: 'Z.ai', value: 'zai' },
+      ],
+      default: 'default',
+    },
+  ]);
+
+  // Configure environment variables based on selection
+  if (selectedProvider === 'kimi' || selectedProvider === 'zai') {
+    const provider = providerConfig.claudeCode.providers[selectedProvider];
+
+    if (!provider?.apiKey) {
+      console.log(chalk.yellow('⚠ API key not configured. Use: sylphx-flow settings\n'));
+      return;
+    }
+
+    if (selectedProvider === 'kimi') {
+      process.env.ANTHROPIC_BASE_URL = 'https://api.moonshot.cn/v1';
+      process.env.ANTHROPIC_API_KEY = provider.apiKey;
+      console.log(chalk.green('✓ Using Kimi provider\n'));
+    } else if (selectedProvider === 'zai') {
+      process.env.ANTHROPIC_BASE_URL = 'https://api.z.ai/v1';
+      process.env.ANTHROPIC_API_KEY = provider.apiKey;
+      console.log(chalk.green('✓ Using Z.ai provider\n'));
+    }
+  } else {
+    console.log(chalk.green('✓ Using default Claude Code provider\n'));
+  }
+  } catch (error: any) {
+    // Handle user cancellation (Ctrl+C)
+    if (error.name === 'ExitPromptError' || error.message?.includes('force closed')) {
+      throw new UserCancelledError('Provider selection cancelled');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Execute command using target's executeCommand method
+ */
+async function executeTargetCommand(
+  targetId: string,
+  systemPrompt: string,
+  userPrompt: string,
+  options: RunCommandOptions
+): Promise<void> {
+  const targetOption = targetManager.getTarget(targetId);
+
+  if (targetOption._tag === 'None') {
+    throw new CLIError(`Target not found: ${targetId}`, 'TARGET_NOT_FOUND');
+  }
+
+  const target = targetOption.value;
+
+  if (!target.isImplemented || !target.executeCommand) {
+    throw new CLIError(
+      `Target '${targetId}' does not support command execution`,
+      'EXECUTION_NOT_SUPPORTED'
+    );
+  }
+
+  return target.executeCommand(systemPrompt, userPrompt, options);
+}
+
+/**
+ * Main flow execution with attach mode (V2)
+ */
+export async function executeFlowV2(
+  prompt: string | undefined,
+  options: FlowOptions
+): Promise<void> {
+  const projectPath = process.cwd();
+
+  // Show welcome banner
+  showWelcome();
+
+  // Mode info
+  if (options.merge) {
+    console.log(chalk.cyan('🔗 Merge mode: Flow settings will be merged with your existing settings'));
+    console.log(chalk.dim('   Settings will be restored after execution\n'));
+  } else {
+    console.log(chalk.yellow('🔄 Replace mode (default): All settings will use Flow configuration'));
+    console.log(chalk.dim('   Use --merge to keep your existing settings\n'));
+  }
+
+  // Initialize config service
+  const configService = new GlobalConfigService();
+  await configService.initialize();
+
+  // Create executor
+  const executor = new FlowExecutor();
+  const projectManager = executor.getProjectManager();
+
+  // Step 1: Check for upgrades (non-intrusive)
+  const upgradeManager = new UpgradeManager();
+  const updates = await upgradeManager.checkUpdates();
+
+  if (updates.flowUpdate || updates.targetUpdate) {
+    console.log(
+      chalk.yellow('📦 Updates available! Run: sylphx-flow upgrade --auto\n')
+    );
+  }
+
+  // Step 2: Execute attach mode lifecycle
+  try {
+    // Attach Flow environment (backup → attach → register cleanup)
+    await executor.execute(projectPath, {
+      verbose: options.verbose,
+      skipBackup: false,
+      skipSecrets: false,
+      merge: options.merge || false,
+    });
+
+    // Step 3: Detect target and load agent
+    const projectHash = projectManager.getProjectHash(projectPath);
+    const target = await projectManager.detectTarget(projectPath);
+
+    // Map target to targetManager's target IDs
+    const targetId = target === 'claude-code' ? 'claude-code' : 'opencode';
+
+    // Step 3.5: Provider selection (Claude Code only)
+    if (targetId === 'claude-code') {
+      await selectProvider(configService);
+    }
+
+    // Step 3.6: Load Flow settings and determine agent to use
+    const settings = await configService.loadSettings();
+    const flowConfig = await configService.loadFlowConfig();
+
+    // Determine which agent to use (CLI option > settings default > 'coder')
+    const agent = options.agent || settings.defaultAgent || 'coder';
+
+    // Check if agent is enabled
+    if (!flowConfig.agents[agent]?.enabled) {
+      console.log(chalk.yellow(`⚠️  Agent '${agent}' is not enabled in settings`));
+      console.log(chalk.yellow(`   Enable it with: sylphx-flow settings`));
+      console.log(chalk.yellow(`   Using 'coder' agent instead\n`));
+      // Fallback to first enabled agent or coder
+      const enabledAgents = await configService.getEnabledAgents();
+      const fallbackAgent = enabledAgents.length > 0 ? enabledAgents[0] : 'coder';
+      options.agent = fallbackAgent;
+    }
+
+    console.log(chalk.cyan(`🤖 Running agent: ${agent}\n`));
+
+    // Load enabled rules and output styles from config
+    const enabledRules = await configService.getEnabledRules();
+    const enabledOutputStyles = await configService.getEnabledOutputStyles();
+
+    console.log(chalk.dim(`   Enabled rules: ${enabledRules.join(', ')}`));
+    console.log(chalk.dim(`   Enabled output styles: ${enabledOutputStyles.join(', ')}\n`));
+
+    // Load agent content with only enabled rules and styles
+    const agentContent = await loadAgentContent(
+      agent,
+      options.agentFile,
+      enabledRules,
+      enabledOutputStyles
+    );
+    const agentInstructions = extractAgentInstructions(agentContent);
+
+    const systemPrompt = `AGENT INSTRUCTIONS:\n${agentInstructions}`;
+
+    const userPrompt = prompt?.trim() || '';
+
+    // Prepare run options
+    const runOptions: RunCommandOptions = {
+      target: targetId,
+      verbose: options.verbose || false,
+      dryRun: options.dryRun || false,
+      agent,
+      agentFile: options.agentFile,
+      prompt,
+      print: options.print,
+      continue: options.continue,
+    };
+
+    // Step 4: Execute command
+    await executeTargetCommand(targetId, systemPrompt, userPrompt, runOptions);
+
+    // Step 5: Cleanup (restore environment)
+    await executor.cleanup(projectPath);
+
+    console.log(chalk.green('✓ Session complete\n'));
+  } catch (error) {
+    // Handle user cancellation gracefully
+    if (error instanceof UserCancelledError) {
+      console.log(chalk.yellow('\n⚠️  Operation cancelled by user'));
+      try {
+        await executor.cleanup(projectPath);
+        console.log(chalk.green('   ✓ Settings restored\n'));
+      } catch (cleanupError) {
+        console.error(chalk.red('   ✗ Cleanup failed:'), cleanupError);
+      }
+      process.exit(0);
+    }
+
+    console.error(chalk.red.bold('\n✗ Execution failed:'), error);
+
+    // Ensure cleanup even on error
+    try {
+      await executor.cleanup(projectPath);
+    } catch (cleanupError) {
+      console.error(chalk.red('✗ Cleanup failed:'), cleanupError);
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Main flow execution entry point
+ */
+export async function executeFlow(
+  prompt: string | undefined,
+  options: FlowOptions
+): Promise<void> {
+  // Resolve prompt (handle file input)
+  const resolvedPrompt = await resolvePrompt(prompt);
+
+  // Use V2 attach mode execution
+  await executeFlowV2(resolvedPrompt, options);
+}

package/src/commands/flow/execute.ts

@@ -124,28 +124,11 @@ export async function executeFlowOnce(prompt: string | undefined, options: FlowO
       await showStatus(state);
     }
 
-    // Step 1: Check for upgrades
+    // Step 1: Check for upgrades (non-intrusive notification)
     if (!options.quick) {
       await checkUpgrades(state, options);
     }
 
-    // Step 1: Upgrade (if requested)
-    if (options.upgrade && state.outdated && state.latestVersion) {
-      console.log(chalk.cyan.bold('━━━ 📦 Upgrading Flow\n'));
-      await upgradeManager.upgradeFlow(state);
-      console.log(chalk.green('✓ Upgrade complete\n'));
-      // Re-detect after upgrade
-      state.version = state.latestVersion;
-      state.outdated = false;
-    }
-
-    // Step 2: Upgrade target (if requested)
-    if (options.upgradeTarget && state.target) {
-      console.log(chalk.cyan.bold(`━━━ 🎯 Upgrading ${state.target}\n`));
-      await upgradeManager.upgradeTarget(state);
-      console.log(chalk.green('✓ Target upgrade complete\n'));
-    }
-
     // Step 2.5: Check component integrity (only if we have valid state)
     await checkComponentIntegrity(state, options);
 

package/src/commands/flow/types.ts

@@ -26,14 +26,15 @@ export interface FlowOptions {
   // Smart configuration options
   selectProvider?: boolean;
   selectAgent?: boolean;
-  useDefaults?: boolean;
   provider?: string;
-  quick?: boolean;
 
   // Execution modes
   print?: boolean;
   continue?: boolean;
 
+  // Attach strategy
+  merge?: boolean; // Merge with user settings instead of replacing (default: replace)
+
   // Loop mode
   loop?: number;
   maxRuns?: number;