@sylphx/flow 1.0.1 → 1.0.3

package/src/core/functional/result.ts

@@ -0,0 +1,204 @@
+/**
+ * Result type for functional error handling
+ * Represents success or failure without exceptions
+ *
+ * DESIGN RATIONALE:
+ * - Explicit error handling at type level
+ * - Composable through map/flatMap
+ * - Forces caller to handle errors
+ * - No hidden control flow (no thrown exceptions)
+ */
+
+export type Result<T, E = Error> = Success<T> | Failure<E>;
+
+export interface Success<T> {
+  readonly _tag: 'Success';
+  readonly value: T;
+}
+
+export interface Failure<E> {
+  readonly _tag: 'Failure';
+  readonly error: E;
+}
+
+/**
+ * Constructors
+ */
+
+export const success = <T>(value: T): Success<T> => ({
+  _tag: 'Success',
+  value,
+});
+
+export const failure = <E>(error: E): Failure<E> => ({
+  _tag: 'Failure',
+  error,
+});
+
+/**
+ * Type guards
+ */
+
+export const isSuccess = <T, E>(result: Result<T, E>): result is Success<T> =>
+  result._tag === 'Success';
+
+export const isFailure = <T, E>(result: Result<T, E>): result is Failure<E> =>
+  result._tag === 'Failure';
+
+/**
+ * Transformations
+ */
+
+/**
+ * Transform the success value
+ * Failure propagates unchanged
+ */
+export const map =
+  <T, U, E>(fn: (value: T) => U) =>
+  (result: Result<T, E>): Result<U, E> => {
+    if (isSuccess(result)) {
+      return success(fn(result.value));
+    }
+    return result;
+  };
+
+/**
+ * Transform the success value with a function that returns a Result
+ * Enables chaining operations that can fail
+ * Failure propagates unchanged
+ */
+export const flatMap =
+  <T, U, E>(fn: (value: T) => Result<U, E>) =>
+  (result: Result<T, E>): Result<U, E> => {
+    if (isSuccess(result)) {
+      return fn(result.value);
+    }
+    return result;
+  };
+
+/**
+ * Transform the error
+ * Success propagates unchanged
+ */
+export const mapError =
+  <T, E, F>(fn: (error: E) => F) =>
+  (result: Result<T, E>): Result<T, F> => {
+    if (isFailure(result)) {
+      return failure(fn(result.error));
+    }
+    return result;
+  };
+
+/**
+ * Extract value or provide default
+ */
+export const getOrElse =
+  <T>(defaultValue: T) =>
+  <E>(result: Result<T, E>): T => {
+    if (isSuccess(result)) {
+      return result.value;
+    }
+    return defaultValue;
+  };
+
+/**
+ * Extract value or compute default
+ */
+export const getOrElseLazy =
+  <T>(fn: () => T) =>
+  <E>(result: Result<T, E>): T => {
+    if (isSuccess(result)) {
+      return result.value;
+    }
+    return fn();
+  };
+
+/**
+ * Pattern matching
+ */
+export const match =
+  <T, E, U>(onSuccess: (value: T) => U, onFailure: (error: E) => U) =>
+  (result: Result<T, E>): U => {
+    if (isSuccess(result)) {
+      return onSuccess(result.value);
+    }
+    return onFailure(result.error);
+  };
+
+/**
+ * Convert thrown exception to Result
+ */
+export const tryCatch = <T, E = Error>(
+  fn: () => T,
+  onError: (error: unknown) => E = (error: unknown) => error as E
+): Result<T, E> => {
+  try {
+    return success(fn());
+  } catch (error) {
+    return failure(onError(error));
+  }
+};
+
+/**
+ * Convert Promise to Result
+ */
+export const tryCatchAsync = async <T, E = Error>(
+  fn: () => Promise<T>,
+  onError: (error: unknown) => E = (error: unknown) => error as E
+): Promise<Result<T, E>> => {
+  try {
+    const value = await fn();
+    return success(value);
+  } catch (error) {
+    return failure(onError(error));
+  }
+};
+
+/**
+ * Combine multiple Results into a single Result containing an array
+ * Fails if any Result is a Failure (short-circuits on first failure)
+ */
+export const all = <T, E>(results: Result<T, E>[]): Result<T[], E> => {
+  const values: T[] = [];
+
+  for (const result of results) {
+    if (isFailure(result)) {
+      return result;
+    }
+    values.push(result.value);
+  }
+
+  return success(values);
+};
+
+/**
+ * Run side effect for success case
+ */
+export const tap =
+  <T, E>(fn: (value: T) => void) =>
+  (result: Result<T, E>): Result<T, E> => {
+    if (isSuccess(result)) {
+      fn(result.value);
+    }
+    return result;
+  };
+
+/**
+ * Run side effect for failure case
+ */
+export const tapError =
+  <T, E>(fn: (error: E) => void) =>
+  (result: Result<T, E>): Result<T, E> => {
+    if (isFailure(result)) {
+      fn(result.error);
+    }
+    return result;
+  };
+
+/**
+ * Functional pipe for composing Result transformations
+ */
+export const pipe =
+  <T, E>(result: Result<T, E>) =>
+  <U>(fn: (result: Result<T, E>) => U): U =>
+    fn(result);

package/src/core/functional/validation.ts

@@ -0,0 +1,138 @@
+/**
+ * Validation utilities for accumulating errors
+ * Unlike Result which short-circuits on first error,
+ * Validation accumulates all errors
+ *
+ * DESIGN RATIONALE:
+ * - Form validation needs all errors, not just first
+ * - Applicative functor for combining validations
+ * - Errors accumulated in array
+ * - Success only if all validations pass
+ */
+
+import type { Result } from './result.js';
+import { failure, isSuccess, success } from './result.js';
+
+/**
+ * Validation result with accumulated errors
+ */
+export type Validation<T, E = string> = Result<T, E[]>;
+
+/**
+ * Create a successful validation
+ */
+export const valid = <T, E = string>(value: T): Validation<T, E> => success(value);
+
+/**
+ * Create a failed validation with one or more errors
+ */
+export const invalid = <T, E = string>(...errors: E[]): Validation<T, E> => failure(errors);
+
+/**
+ * Combine multiple validations
+ * Collects all errors if any validation fails
+ */
+export const combine = <T, E = string>(validations: Validation<T, E>[]): Validation<T[], E> => {
+  const values: T[] = [];
+  const errors: E[] = [];
+
+  for (const validation of validations) {
+    if (isSuccess(validation)) {
+      values.push(validation.value);
+    } else {
+      errors.push(...validation.error);
+    }
+  }
+
+  if (errors.length > 0) {
+    return invalid(...errors);
+  }
+
+  return valid(values);
+};
+
+/**
+ * Validate a value against multiple validators
+ * Returns first error or success
+ */
+export const validateAll =
+  <T, E = string>(...validators: Array<(value: T) => Validation<T, E>>) =>
+  (value: T): Validation<T, E> => {
+    const errors: E[] = [];
+
+    for (const validator of validators) {
+      const result = validator(value);
+      if (!isSuccess(result)) {
+        errors.push(...result.error);
+      }
+    }
+
+    if (errors.length > 0) {
+      return invalid(...errors);
+    }
+
+    return valid(value);
+  };
+
+/**
+ * Common validators
+ */
+
+export const nonEmpty =
+  (message: string) =>
+  (value: string): Validation<string, string> => {
+    if (value.trim().length === 0) {
+      return invalid(message);
+    }
+    return valid(value);
+  };
+
+export const minLength =
+  (min: number, message: string) =>
+  (value: string): Validation<string, string> => {
+    if (value.length < min) {
+      return invalid(message);
+    }
+    return valid(value);
+  };
+
+export const maxLength =
+  (max: number, message: string) =>
+  (value: string): Validation<string, string> => {
+    if (value.length > max) {
+      return invalid(message);
+    }
+    return valid(value);
+  };
+
+export const matches =
+  (pattern: RegExp, message: string) =>
+  (value: string): Validation<string, string> => {
+    if (!pattern.test(value)) {
+      return invalid(message);
+    }
+    return valid(value);
+  };
+
+export const isEmail = (message: string) => matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, message);
+
+export const isUrl = (message: string) => matches(/^https?:\/\/.+/, message);
+
+export const isNumber =
+  (message: string) =>
+  (value: string): Validation<number, string> => {
+    const num = Number(value);
+    if (Number.isNaN(num)) {
+      return invalid(message);
+    }
+    return valid(num);
+  };
+
+export const range =
+  (min: number, max: number, message: string) =>
+  (value: number): Validation<number, string> => {
+    if (value < min || value > max) {
+      return invalid(message);
+    }
+    return valid(value);
+  };

package/src/core/headless-display.ts

@@ -0,0 +1,96 @@
+/**
+ * Headless Display
+ * Formatting and display logic for headless mode (non-TUI)
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Format tool arguments for display
+ */
+function formatArgs(args: unknown): string {
+  if (!args || typeof args !== 'object') {
+    return '';
+  }
+
+  const argsStr = Object.keys(args).length === 0
+    ? ''
+    : JSON.stringify(args, null, 2);
+
+  if (!argsStr) {
+    return '';
+  }
+
+  const lines = argsStr.split('\n');
+  const truncated = lines.length > 5
+    ? lines.slice(0, 5).join('\n') + chalk.dim('\n     … +' + (lines.length - 5) + ' lines')
+    : argsStr;
+
+  return truncated;
+}
+
+/**
+ * Format tool result for display
+ */
+function formatResult(result: unknown): string {
+  const resultStr = JSON.stringify(result, null, 2);
+  const lines = resultStr.split('\n');
+  const truncated = lines.length > 5
+    ? lines.slice(0, 5).join('\n') + chalk.dim('\n     … +' + (lines.length - 5) + ' lines')
+    : resultStr;
+
+  return truncated;
+}
+
+/**
+ * Display callbacks for headless mode
+ */
+export function createHeadlessDisplay(quiet: boolean) {
+  let hasOutput = false;
+
+  return {
+    onToolCall: (toolName: string, args: unknown) => {
+      if (quiet) return;
+
+      // Flush stdout to ensure proper ordering
+      if (hasOutput) {
+        process.stdout.write('\n');
+      }
+
+      const argsStr = formatArgs(args);
+      if (argsStr) {
+        process.stderr.write(`\n${chalk.green('⏺')} ${chalk.bold(toolName)}\n`);
+        process.stderr.write(chalk.dim(`  ⎿ ${argsStr.split('\n').join('\n     ')}\n`));
+      } else {
+        process.stderr.write(`\n${chalk.green('⏺')} ${chalk.bold(toolName)}\n`);
+      }
+    },
+
+    onToolResult: (toolName: string, result: unknown, duration: number) => {
+      if (quiet) return;
+
+      const resultStr = formatResult(result);
+      process.stderr.write(`${chalk.green('●')} ${chalk.bold(toolName)} ${chalk.dim(`(${duration}ms)`)}\n`);
+      process.stderr.write(chalk.dim(`  ⎿ ${resultStr.split('\n').join('\n     ')}\n\n`));
+    },
+
+    onTextDelta: (text: string) => {
+      if (!hasOutput) {
+        hasOutput = true;
+        // Add newline before first text output if we're not in quiet mode
+        if (!quiet) {
+          process.stdout.write('\n');
+        }
+      }
+      process.stdout.write(text);
+    },
+
+    onComplete: () => {
+      if (hasOutput) {
+        process.stdout.write('\n\n');
+      }
+    },
+
+    hasOutput: () => hasOutput,
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Core functionality barrel export
+ * Centralized access to core system components
+ */
+
+export { targetManager } from './target-manager';