@sylphx/flow 3.16.0 → 3.17.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @sylphx/flow
 
+## 3.17.1 (2026-02-05)
+
+Add Hono RPC patterns and declarative engineering principles
+
+### 📚 Documentation
+
+- **builder:** prioritize declarative style in engineering principles ([f2e5bc4](https://github.com/SylphxAI/flow/commit/f2e5bc482ce554097e2bc90943c22f3d497f0925))
+- **builder:** add Hono RPC patterns for split clients ([c848796](https://github.com/SylphxAI/flow/commit/c8487965a8341aac1f9644d5de75c1dd36b1c661))
+
+## 3.17.0 (2026-02-05)
+
+### ♻️ Refactoring
+
+- **flow:** migrate CLI prompts to Clack and logging to Pino ([08aceb7](https://github.com/SylphxAI/flow/commit/08aceb7d))
+
+### 🐛 Bug Fixes
+
+- **flow:** remove unsafe separator pattern from Clack prompts ([aaf17a7](https://github.com/SylphxAI/flow/commit/aaf17a7d))
+
+### 📝 Documentation
+
+- **builder:** add Zod v4 to tech stack ([2b37327](https://github.com/SylphxAI/flow/commit/2b373279))
+- **builder:** restructure tech stack - Zod as standalone category ([90875ba](https://github.com/SylphxAI/flow/commit/90875baa))
+
 ## 3.16.0 (2026-02-05)
 
 ### ✨ Features

package/assets/agents/builder.md

@@ -46,13 +46,15 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 
 **Framework & Runtime:** Next.js 16+, React, Bun
 
+**Schema & Validation:** Zod v4
+
 **Data & API:** Hono + @hono/zod-openapi + hc (type-safe client), React Query, Drizzle ORM
 
 **Database & Infrastructure:** Neon PostgreSQL, Upstash Workflow, Vercel, Vercel Blob, Modal (serverless long-running)
 
 **UI & Styling:** Base UI, Tailwind CSS v4 (CSS-first), Motion v12 (animation)
 
-**Forms:** React Hook Form + Zod
+**Forms:** React Hook Form + @hookform/resolvers
 
 **Tables & Lists:** TanStack Table, TanStack Virtual
 
@@ -121,9 +123,10 @@ State-of-the-art industrial standard. Every time. Would you stake your reputatio
 
 ## Engineering
 
+- **Declarative over imperative** — describe WHAT, not HOW; prefer expressions over statements, data over control flow
+- **Pure functions** — no side effects, deterministic output; isolate impure code at boundaries
 - **Single Source of Truth** — one authoritative source for every state, behavior, and decision
 - **Type safety** — end-to-end across all boundaries (Hono RPC, Zod, strict TypeScript)
-- **Pure functions** — no side effects, deterministic output; isolate impure code at boundaries
 - **Decoupling** — minimize dependencies, use interfaces and dependency injection
 - **Modularisation** — single responsibility, clear boundaries, independent deployability
 - **Composition over inheritance** — build primitives that compose
@@ -183,6 +186,42 @@ drizzle-kit migrate && drizzle-kit push --dry-run
 ```
 If there's any diff, migration is incomplete — fail the build.
 
+## Hono RPC
+
+**Split clients by entity** — monolithic `hc<AppType>` kills IDE performance at 100+ routes.
+
+```typescript
+// ✅ Split: one Hono app + one client per entity
+const booksApp = new Hono()
+  .get('/', (c) => c.json([]))
+  .post('/', (c) => c.json({ id: 1 }))
+  .get('/:id', (c) => c.json({ id: c.req.param('id') }))
+
+const authorsApp = new Hono()
+  .get('/', (c) => c.json([]))
+  .post('/', (c) => c.json({ id: 1 }))
+
+// Main app — chain with .route()
+const app = new Hono()
+  .route('/books', booksApp)
+  .route('/authors', authorsApp)
+
+// Clients — split by entity, <100 routes each
+export const booksClient = hc<typeof booksApp>('/api/books')
+export const authorsClient = hc<typeof authorsApp>('/api/authors')
+```
+
+**Chain routes** — separate `app.get()` calls break type inference:
+```typescript
+// ✅ Chained — types work
+const app = new Hono().get('/', h1).post('/', h2)
+
+// ❌ Separate — types broken
+const app = new Hono()
+app.get('/', h1)
+app.post('/', h2)
+```
+
 ## Frontend
 
 - **Semantic HTML** — correct elements (nav, main, article, section, aside, header, footer)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.16.0",
+	"version": "3.17.1",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {
@@ -25,16 +25,17 @@
 		"prepublishOnly": "echo 'Using assets from packages/flow/assets'"
 	},
 	"dependencies": {
-		"commander": "^14.0.2",
-		"chalk": "^5.6.2",
+		"@clack/prompts": "^0.9.0",
 		"boxen": "^8.0.1",
+		"chalk": "^5.6.2",
+		"commander": "^14.0.2",
+		"debug": "^4.4.3",
 		"gradient-string": "^3.0.0",
-		"ora": "^9.0.0",
-		"inquirer": "^12.10.0",
 		"gray-matter": "^4.0.3",
+		"pino": "^9.0.0",
+		"pino-pretty": "^11.0.0",
 		"yaml": "^2.8.1",
-		"zod": "^4.1.12",
-		"debug": "^4.4.3"
+		"zod": "^4.1.12"
 	},
 	"devDependencies": {
 		"@types/node": "^24.9.2",

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

@@ -7,7 +7,6 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
-import inquirer from 'inquirer';
 import { FlowExecutor } from '../../core/flow-executor.js';
 import { targetManager } from '../../core/target-manager.js';
 import { AutoUpgrade } from '../../services/auto-upgrade.js';
@@ -18,6 +17,7 @@ import { extractAgentInstructions, loadAgentContent } from '../../utils/agent-en
 import { showAttachSummary, showHeader } from '../../utils/display/banner.js';
 import { CLIError } from '../../utils/error-handler.js';
 import { UserCancelledError } from '../../utils/errors.js';
+import { log, promptConfirm, promptSelect } from '../../utils/prompts/index.js';
 import { ensureTargetInstalled, promptForTargetSelection } from '../../utils/target-selection.js';
 import { resolvePrompt } from './prompt.js';
 import type { FlowOptions } from './types.js';
@@ -62,66 +62,52 @@ function configureProviderEnv(provider: 'kimi' | 'zai', apiKey: string): void {
  * Select and configure provider for Claude Code (silent unless prompting)
  */
 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 silently
-    if (defaultProvider !== 'ask-every-time') {
-      if (defaultProvider === 'kimi' || defaultProvider === 'zai') {
-        const provider = providerConfig.claudeCode.providers[defaultProvider];
-        if (provider?.apiKey) {
-          configureProviderEnv(defaultProvider, provider.apiKey);
-        }
+  const providerConfig = await configService.loadProviderConfig();
+  const defaultProvider = providerConfig.claudeCode.defaultProvider;
+
+  // If not "ask-every-time", use the default provider silently
+  if (defaultProvider !== 'ask-every-time') {
+    if (defaultProvider === 'kimi' || defaultProvider === 'zai') {
+      const provider = providerConfig.claudeCode.providers[defaultProvider];
+      if (provider?.apiKey) {
+        configureProviderEnv(defaultProvider, provider.apiKey);
       }
-      return;
-    }
-
-    // Ask user which provider to use for this session
-    const { selectedProvider, rememberChoice } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'selectedProvider',
-        message: 'Select provider:',
-        choices: [
-          { name: 'Default (Claude Code built-in)', value: 'default' },
-          { name: 'Kimi', value: 'kimi' },
-          { name: 'Z.ai', value: 'zai' },
-        ],
-        default: 'default',
-      },
-      {
-        type: 'confirm',
-        name: 'rememberChoice',
-        message: 'Remember this choice?',
-        default: true,
-      },
-    ]);
-
-    // Save choice if user wants to remember
-    if (rememberChoice) {
-      providerConfig.claudeCode.defaultProvider = selectedProvider;
-      await configService.saveProviderConfig(providerConfig);
     }
+    return;
+  }
 
-    // Configure environment variables based on selection
-    if (selectedProvider === 'kimi' || selectedProvider === 'zai') {
-      const provider = providerConfig.claudeCode.providers[selectedProvider];
+  // Ask user which provider to use for this session
+  const selectedProvider = await promptSelect({
+    message: 'Select provider:',
+    options: [
+      { label: 'Default (Claude Code built-in)', value: 'default' },
+      { label: 'Kimi', value: 'kimi' },
+      { label: 'Z.ai', value: 'zai' },
+    ],
+    initialValue: 'default',
+  });
+
+  const rememberChoice = await promptConfirm({
+    message: 'Remember this choice?',
+    initialValue: true,
+  });
+
+  // Save choice if user wants to remember
+  if (rememberChoice) {
+    providerConfig.claudeCode.defaultProvider = selectedProvider;
+    await configService.saveProviderConfig(providerConfig);
+  }
 
-      if (!provider?.apiKey) {
-        console.log(chalk.yellow('  API key not configured. Use: sylphx-flow settings'));
-        return;
-      }
+  // Configure environment variables based on selection
+  if (selectedProvider === 'kimi' || selectedProvider === 'zai') {
+    const provider = providerConfig.claudeCode.providers[selectedProvider];
 
-      configureProviderEnv(selectedProvider, provider.apiKey);
-    }
-  } catch (error: unknown) {
-    // Handle user cancellation (Ctrl+C)
-    const err = error as Error & { name?: string };
-    if (err.name === 'ExitPromptError' || err.message?.includes('force closed')) {
-      throw new UserCancelledError('Provider selection cancelled');
+    if (!provider?.apiKey) {
+      log.warn('API key not configured. Use: sylphx-flow settings');
+      return;
     }
-    throw error;
+
+    configureProviderEnv(selectedProvider, provider.apiKey);
   }
 }
 
@@ -221,11 +207,11 @@ export async function executeFlowV2(
 
     if (!installedTargets.includes(selectedTargetId)) {
       const installation = targetInstaller.getInstallationInfo(selectedTargetId);
-      console.log(chalk.yellow(`\n  ${installation?.name} not installed`));
+      log.warn(`${installation?.name} not installed`);
       const installed = await targetInstaller.install(selectedTargetId, true);
 
       if (!installed) {
-        console.log(chalk.red(`  Cannot proceed: installation failed\n`));
+        log.error('Cannot proceed: installation failed');
         process.exit(1);
       }
     }
@@ -313,7 +299,7 @@ export async function executeFlowV2(
   } catch (error) {
     // Handle user cancellation gracefully
     if (error instanceof UserCancelledError) {
-      console.log(chalk.yellow('\n  Cancelled'));
+      log.warn('Cancelled');
       try {
         await executor.cleanup(projectPath);
       } catch {

package/src/commands/settings/checkbox-config.ts

@@ -4,7 +4,7 @@
  */
 
 import chalk from 'chalk';
-import inquirer from 'inquirer';
+import { log, type MultiselectOption, promptMultiselect } from '../../utils/prompts/index.js';
 
 // ============================================================================
 // Types
@@ -47,16 +47,16 @@ export const getEnabledKeys = (config: ConfigMap): string[] =>
   Object.keys(config).filter((key) => config[key]?.enabled);
 
 /**
- * Build checkbox choices from available items
+ * Build multiselect options from available items
  */
-export const buildChoices = <T extends string>(
+export const buildOptions = <T extends string>(
   available: Record<T, string>,
   enabledKeys: string[]
-): Array<{ name: string; value: T; checked: boolean }> =>
+): MultiselectOption<T>[] =>
   Object.entries(available).map(([key, name]) => ({
-    name: name as string,
+    label: name as string,
     value: key as T,
-    checked: enabledKeys.includes(key),
+    hint: enabledKeys.includes(key) ? 'enabled' : undefined,
   }));
 
 /**
@@ -82,11 +82,11 @@ export const printHeader = (icon: string, title: string): void => {
 };
 
 /**
- * Print confirmation message
+ * Print confirmation message using Clack log
  */
 export const printConfirmation = (itemType: string, count: number): void => {
-  console.log(chalk.green(`\n✓ ${itemType} configuration saved`));
-  console.log(chalk.dim(`  Enabled ${itemType.toLowerCase()}: ${count}`));
+  log.success(`${itemType} configuration saved`);
+  log.info(`Enabled ${itemType.toLowerCase()}: ${count}`);
 };
 
 // ============================================================================
@@ -108,15 +108,15 @@ export const handleCheckboxConfig = async <T extends string>(
   // Get current enabled items
   const enabledKeys = getEnabledKeys(current);
 
-  // Show checkbox prompt
-  const { selected } = await inquirer.prompt([
-    {
-      type: 'checkbox',
-      name: 'selected',
-      message,
-      choices: buildChoices(available, enabledKeys),
-    },
-  ]);
+  // Build options for multiselect
+  const multiselectOptions = buildOptions(available, enabledKeys);
+
+  // Show multiselect prompt
+  const selected = await promptMultiselect<T>({
+    message,
+    options: multiselectOptions,
+    initialValues: enabledKeys as T[],
+  });
 
   // Update config
   const updated = updateConfig(available, selected);