@sylphx/flow 1.0.1 → 1.0.3

package/src/composables/functional/useEnvironment.ts

@@ -0,0 +1,171 @@
+/**
+ * Functional composable for environment variables
+ * Type-safe access to environment with validation
+ *
+ * DESIGN RATIONALE:
+ * - Explicit handling of missing variables
+ * - Type-safe environment access
+ * - Validation support
+ * - Option type for optional values
+ */
+
+import type { ConfigError } from '../../core/functional/error-types.js';
+import { configError } from '../../core/functional/error-types.js';
+import type { Option } from '../../core/functional/option.js';
+import { fromNullable } from '../../core/functional/option.js';
+import type { Result } from '../../core/functional/result.js';
+import { failure, success } from '../../core/functional/result.js';
+
+/**
+ * Get environment variable as Option
+ * Returns Some(value) if exists, None otherwise
+ */
+export const getEnvOpt = (key: string): Option<string> => {
+  return fromNullable(process.env[key]);
+};
+
+/**
+ * Get environment variable or default
+ */
+export const getEnvOrElse = (key: string, defaultValue: string): string => {
+  return process.env[key] || defaultValue;
+};
+
+/**
+ * Get required environment variable
+ * Returns Result with error if missing
+ */
+export const getEnvRequired = (key: string): Result<string, ConfigError> => {
+  const value = process.env[key];
+
+  if (value === undefined || value === '') {
+    return failure(
+      configError(`Required environment variable is missing: ${key}`, { configKey: key })
+    );
+  }
+
+  return success(value);
+};
+
+/**
+ * Get multiple required environment variables
+ * Returns Result with all errors if any are missing
+ */
+export const getEnvRequiredAll = (keys: string[]): Result<Record<string, string>, ConfigError> => {
+  const missing: string[] = [];
+  const values: Record<string, string> = {};
+
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value === undefined || value === '') {
+      missing.push(key);
+    } else {
+      values[key] = value;
+    }
+  }
+
+  if (missing.length > 0) {
+    return failure(
+      configError(`Required environment variables are missing: ${missing.join(', ')}`, {
+        context: { missing },
+      })
+    );
+  }
+
+  return success(values);
+};
+
+/**
+ * Parse environment variable as number
+ */
+export const getEnvNumber = (key: string): Result<number, ConfigError> => {
+  const value = process.env[key];
+
+  if (value === undefined || value === '') {
+    return failure(configError(`Environment variable is missing: ${key}`, { configKey: key }));
+  }
+
+  const parsed = Number(value);
+  if (Number.isNaN(parsed)) {
+    return failure(
+      configError(`Environment variable is not a valid number: ${key}`, {
+        configKey: key,
+        context: { value },
+      })
+    );
+  }
+
+  return success(parsed);
+};
+
+/**
+ * Parse environment variable as boolean
+ * Accepts: true, false, 1, 0, yes, no (case insensitive)
+ */
+export const getEnvBoolean = (key: string): Result<boolean, ConfigError> => {
+  const value = process.env[key]?.toLowerCase();
+
+  if (value === undefined || value === '') {
+    return failure(configError(`Environment variable is missing: ${key}`, { configKey: key }));
+  }
+
+  const trueValues = ['true', '1', 'yes'];
+  const falseValues = ['false', '0', 'no'];
+
+  if (trueValues.includes(value)) {
+    return success(true);
+  }
+
+  if (falseValues.includes(value)) {
+    return success(false);
+  }
+
+  return failure(
+    configError(`Environment variable is not a valid boolean: ${key}`, {
+      configKey: key,
+      context: { value },
+    })
+  );
+};
+
+/**
+ * Parse environment variable as enum
+ */
+export const getEnvEnum = <T extends string>(
+  key: string,
+  allowedValues: readonly T[]
+): Result<T, ConfigError> => {
+  const value = process.env[key];
+
+  if (value === undefined || value === '') {
+    return failure(configError(`Environment variable is missing: ${key}`, { configKey: key }));
+  }
+
+  if (!allowedValues.includes(value as T)) {
+    return failure(
+      configError(`Environment variable has invalid value: ${key}`, {
+        configKey: key,
+        context: {
+          value,
+          allowedValues: allowedValues as unknown as string[],
+        },
+      })
+    );
+  }
+
+  return success(value as T);
+};
+
+/**
+ * Get all environment variables
+ */
+export const getAllEnv = (): NodeJS.ProcessEnv => {
+  return process.env;
+};
+
+/**
+ * Check if environment variable is set
+ */
+export const hasEnv = (key: string): boolean => {
+  return key in process.env && process.env[key] !== undefined && process.env[key] !== '';
+};

package/src/composables/functional/useFileSystem.ts

@@ -0,0 +1,139 @@
+/**
+ * Functional composable for file system operations
+ * Returns Result instead of throwing exceptions
+ *
+ * DESIGN RATIONALE:
+ * - Explicit error handling
+ * - Composable file operations
+ * - Type-safe path handling
+ * - Separation of concerns (pure path operations vs side effects)
+ */
+
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import type { FileSystemError } from '../../core/functional/error-types.js';
+import { fileSystemError } from '../../core/functional/error-types.js';
+import type { Result } from '../../core/functional/result.js';
+import { tryCatchAsync } from '../../core/functional/result.js';
+
+/**
+ * Pure path operations (no side effects)
+ */
+
+export const joinPath = (...segments: string[]): string => path.join(...segments);
+
+export const resolvePath = (...segments: string[]): string => path.resolve(...segments);
+
+export const dirname = (filePath: string): string => path.dirname(filePath);
+
+export const basename = (filePath: string, ext?: string): string => path.basename(filePath, ext);
+
+export const extname = (filePath: string): string => path.extname(filePath);
+
+/**
+ * File system operations (side effects, return Result)
+ */
+
+export const readFile = async (filePath: string): Promise<Result<string, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      return await fsPromises.readFile(filePath, 'utf-8');
+    },
+    (error) =>
+      fileSystemError(`Failed to read file: ${filePath}`, filePath, 'read', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const writeFile = async (
+  filePath: string,
+  content: string
+): Promise<Result<void, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      await fsPromises.writeFile(filePath, content, 'utf-8');
+    },
+    (error) =>
+      fileSystemError(`Failed to write file: ${filePath}`, filePath, 'write', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const deleteFile = async (filePath: string): Promise<Result<void, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      await fsPromises.unlink(filePath);
+    },
+    (error) =>
+      fileSystemError(`Failed to delete file: ${filePath}`, filePath, 'delete', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const createDirectory = async (
+  dirPath: string,
+  options?: { recursive?: boolean }
+): Promise<Result<void, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      await fsPromises.mkdir(dirPath, { recursive: options?.recursive ?? true });
+    },
+    (error) =>
+      fileSystemError(`Failed to create directory: ${dirPath}`, dirPath, 'create', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const pathExists = async (filePath: string): Promise<Result<boolean, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      try {
+        await fsPromises.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    (error) =>
+      fileSystemError(`Failed to check if path exists: ${filePath}`, filePath, 'stat', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const readDirectory = async (
+  dirPath: string
+): Promise<Result<string[], FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      return await fsPromises.readdir(dirPath);
+    },
+    (error) =>
+      fileSystemError(`Failed to read directory: ${dirPath}`, dirPath, 'read', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};
+
+export const getStats = async (
+  filePath: string
+): Promise<Result<{ isFile: boolean; isDirectory: boolean; size: number }, FileSystemError>> => {
+  return tryCatchAsync(
+    async () => {
+      const stats = await fsPromises.stat(filePath);
+      return {
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory(),
+        size: stats.size,
+      };
+    },
+    (error) =>
+      fileSystemError(`Failed to get stats for: ${filePath}`, filePath, 'stat', {
+        cause: error instanceof Error ? error : undefined,
+      })
+  );
+};

package/src/composables/index.ts

@@ -0,0 +1,5 @@
+// Re-export all composables for easy importing
+
+export { useEnv, useEnvVar } from './useEnv.js';
+export { useIsCI, useIsDebug, useRuntimeConfig } from './useRuntimeConfig.js';
+export { useTargetConfig, useTargetConfigById } from './useTargetConfig.js';

package/src/composables/useEnv.ts

@@ -0,0 +1,13 @@
+/**
+ * Get environment variables with type safety
+ */
+export function useEnv(): NodeJS.ProcessEnv {
+  return process.env;
+}
+
+/**
+ * Get specific environment variable with optional default
+ */
+export function useEnvVar(key: string, defaultValue?: string): string | undefined {
+  return process.env[key] || defaultValue;
+}

package/src/composables/useRuntimeConfig.ts

@@ -0,0 +1,27 @@
+/**
+ * Get runtime configuration/state
+ * This can be extended to include more runtime context
+ */
+export function useRuntimeConfig() {
+  return {
+    isDebug: process.env.NODE_ENV === 'development' || process.env.DEBUG === 'true',
+    isCI: process.env.CI === 'true',
+    cwd: process.cwd(),
+    platform: process.platform,
+    nodeVersion: process.version,
+  };
+}
+
+/**
+ * Check if running in CI/CD environment
+ */
+export function useIsCI(): boolean {
+  return process.env.CI === 'true' || !!process.env.CI || !!process.env.CONTINUOUS_INTEGRATION;
+}
+
+/**
+ * Check if running in debug mode
+ */
+export function useIsDebug(): boolean {
+  return process.env.DEBUG === 'true' || process.env.NODE_ENV === 'development';
+}

package/src/composables/useTargetConfig.ts

@@ -0,0 +1,45 @@
+import { getTarget, getDefaultTargetUnsafe } from '../config/targets.js';
+import { projectSettings } from '../utils/settings.js';
+import type { MCPServerConfigFlags } from '../types.js';
+
+/**
+ * Get the current target's MCP server configuration
+ * Follows the same resolution pattern as targetManager.resolveTarget()
+ * Returns undefined if no target is set or target has no mcpServerConfig
+ */
+export async function useTargetConfig(): Promise<MCPServerConfigFlags | undefined> {
+  try {
+    // Try to get target from project settings first
+    const settings = await projectSettings.load();
+    const targetId = settings?.target;
+
+    if (targetId) {
+      const targetOption = getTarget(targetId);
+      if (targetOption._tag === 'Some') {
+        return targetOption.value.mcpServerConfig;
+      }
+    }
+
+    // Fall back to default target
+    const defaultTarget = getDefaultTargetUnsafe();
+    return defaultTarget.mcpServerConfig;
+  } catch {
+    // If no target can be resolved, return undefined
+    return undefined;
+  }
+}
+
+/**
+ * Get a specific target's MCP server configuration by ID
+ */
+export function useTargetConfigById(targetId: string): MCPServerConfigFlags | undefined {
+  try {
+    const targetOption = getTarget(targetId);
+    if (targetOption._tag === 'None') {
+      return undefined;
+    }
+    return targetOption.value.mcpServerConfig;
+  } catch {
+    return undefined;
+  }
+}