trinity-method-sdk 2.0.0

package/dist/cli/utils/error-classes.js

@@ -0,0 +1,84 @@
+/**
+ * Custom error classes for Trinity CLI
+ * Provides domain-specific error types with codes and context
+ * @module cli/utils/error-classes
+ */
+/**
+ * Base error class for Trinity CLI
+ * All custom errors extend this class
+ */
+export class TrinityCLIError extends Error {
+    /**
+     * Create a Trinity CLI error
+     * @param message - Human-readable error message
+     * @param code - Error code for categorization (e.g., 'DEPLOYMENT_ERROR')
+     * @param exitCode - Process exit code (default: 1)
+     * @param context - Additional context for debugging
+     */
+    constructor(message, code, exitCode = 1, context) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.context = context;
+        this.name = this.constructor.name;
+        // Fix prototype chain for instanceof checks in Node.js 22+
+        Object.setPrototypeOf(this, new.target.prototype);
+        // Capture stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Format error for user display
+     * @returns Formatted error message with code
+     */
+    format() {
+        return `Error ${this.code}: ${this.message}`;
+    }
+}
+/**
+ * User input validation errors
+ * Used when user provides invalid input or options
+ */
+export class ValidationError extends TrinityCLIError {
+    constructor(message, context) {
+        super(message, 'VALIDATION_ERROR', 1, context);
+    }
+}
+/**
+ * Filesystem operation errors
+ * Used when file/directory operations fail
+ */
+export class FilesystemError extends TrinityCLIError {
+    constructor(message, context) {
+        super(message, 'FILESYSTEM_ERROR', 1, context);
+    }
+}
+/**
+ * Deployment errors
+ * Used when Trinity deployment fails
+ */
+export class DeploymentError extends TrinityCLIError {
+    constructor(message, context) {
+        super(message, 'DEPLOYMENT_ERROR', 1, context);
+    }
+}
+/**
+ * Update errors
+ * Used when Trinity update fails
+ */
+export class UpdateError extends TrinityCLIError {
+    constructor(message, context) {
+        super(message, 'UPDATE_ERROR', 1, context);
+    }
+}
+/**
+ * Configuration errors
+ * Used when configuration is invalid or missing
+ */
+export class ConfigurationError extends TrinityCLIError {
+    constructor(message, context) {
+        super(message, 'CONFIG_ERROR', 1, context);
+    }
+}
+//# sourceMappingURL=error-classes.js.map

package/dist/cli/utils/error-handler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Centralized error handler with cleanup mechanisms
+ * Provides graceful error handling and resource cleanup
+ * @module cli/utils/error-handler
+ */
+/**
+ * Centralized error handler for Trinity CLI
+ * Manages cleanup tasks and provides graceful error handling
+ */
+declare class ErrorHandler {
+    private cleanupTasks;
+    /**
+     * Check if debug mode is enabled
+     * Reads from DEBUG environment variable at runtime
+     */
+    private get debugMode();
+    /**
+     * Register a cleanup task to run before process exit
+     * Cleanup tasks are executed in registration order
+     * @param name - Human-readable name for logging
+     * @param handler - Cleanup function (sync or async)
+     */
+    registerCleanup(name: string, handler: () => Promise<void> | void): void;
+    /**
+     * Run all registered cleanup tasks
+     * Failures in cleanup tasks are logged but don't stop other tasks
+     * @private
+     */
+    private runCleanup;
+    /**
+     * Handle error and exit gracefully
+     * Runs cleanup tasks, displays error, and exits with appropriate code
+     * @param error - Error to handle (any type)
+     * @returns Never returns (process exits)
+     */
+    handle(error: unknown): Promise<never>;
+    /**
+     * Wrap async function with error handling
+     * Catches errors and passes them to the error handler
+     * @param fn - Async function to wrap
+     * @returns Wrapped function with error handling
+     */
+    wrap<T extends unknown[], R>(fn: (...args: T) => Promise<R>): (...args: T) => Promise<R>;
+    /**
+     * Clear all registered cleanup tasks
+     * Useful for testing or when cleanup is handled externally
+     */
+    clearCleanup(): void;
+}
+export declare const errorHandler: ErrorHandler;
+/**
+ * Handle error and exit gracefully
+ * Convenience function that calls errorHandler.handle()
+ * @param error - Error to handle
+ * @returns Never returns (process exits)
+ */
+export declare function handleError(error: unknown): Promise<never>;
+export {};
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/utils/error-handler.js

@@ -0,0 +1,127 @@
+/**
+ * Centralized error handler with cleanup mechanisms
+ * Provides graceful error handling and resource cleanup
+ * @module cli/utils/error-handler
+ */
+import chalk from 'chalk';
+import { displayError, displayInfo, getErrorMessage } from './errors.js';
+import { TrinityCLIError } from './error-classes.js';
+/**
+ * Centralized error handler for Trinity CLI
+ * Manages cleanup tasks and provides graceful error handling
+ */
+class ErrorHandler {
+    constructor() {
+        this.cleanupTasks = [];
+    }
+    /**
+     * Check if debug mode is enabled
+     * Reads from DEBUG environment variable at runtime
+     */
+    get debugMode() {
+        return process.env.DEBUG === 'true';
+    }
+    /**
+     * Register a cleanup task to run before process exit
+     * Cleanup tasks are executed in registration order
+     * @param name - Human-readable name for logging
+     * @param handler - Cleanup function (sync or async)
+     */
+    registerCleanup(name, handler) {
+        this.cleanupTasks.push({ name, handler });
+    }
+    /**
+     * Run all registered cleanup tasks
+     * Failures in cleanup tasks are logged but don't stop other tasks
+     * @private
+     */
+    async runCleanup() {
+        if (this.cleanupTasks.length === 0)
+            return;
+        console.log(chalk.blue('\nCleaning up...'));
+        for (const task of this.cleanupTasks) {
+            try {
+                await task.handler();
+                console.log(chalk.gray(`  ✓ ${task.name}`));
+            }
+            catch {
+                displayInfo(`Failed to cleanup: ${task.name}`);
+            }
+        }
+        this.cleanupTasks = [];
+    }
+    /**
+     * Handle error and exit gracefully
+     * Runs cleanup tasks, displays error, and exits with appropriate code
+     * @param error - Error to handle (any type)
+     * @returns Never returns (process exits)
+     */
+    async handle(error) {
+        // Run cleanup tasks first
+        await this.runCleanup();
+        // Handle Trinity CLI errors
+        if (error instanceof TrinityCLIError) {
+            displayError(error.format());
+            if (error.context && this.debugMode) {
+                console.error(chalk.gray('Context:'));
+                console.error(chalk.gray(JSON.stringify(error.context, null, 2)));
+            }
+            if (this.debugMode && error.stack) {
+                console.error(chalk.gray('\nStack trace:'));
+                console.error(chalk.gray(error.stack));
+            }
+            process.exit(error.exitCode);
+        }
+        // Handle standard Error instances
+        if (error instanceof Error) {
+            displayError(getErrorMessage(error));
+            if (this.debugMode && error.stack) {
+                console.error(chalk.gray('\nStack trace:'));
+                console.error(chalk.gray(error.stack));
+            }
+            process.exit(1);
+        }
+        // Handle unknown error types
+        displayError('Unknown error occurred');
+        console.error(chalk.gray(String(error)));
+        process.exit(1);
+    }
+    /**
+     * Wrap async function with error handling
+     * Catches errors and passes them to the error handler
+     * @param fn - Async function to wrap
+     * @returns Wrapped function with error handling
+     */
+    wrap(fn) {
+        return async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (error) {
+                await this.handle(error);
+                // TypeScript doesn't know handle() never returns (calls process.exit)
+                // This line is unreachable but satisfies the compiler
+                throw error;
+            }
+        };
+    }
+    /**
+     * Clear all registered cleanup tasks
+     * Useful for testing or when cleanup is handled externally
+     */
+    clearCleanup() {
+        this.cleanupTasks = [];
+    }
+}
+// Export singleton instance
+export const errorHandler = new ErrorHandler();
+/**
+ * Handle error and exit gracefully
+ * Convenience function that calls errorHandler.handle()
+ * @param error - Error to handle
+ * @returns Never returns (process exits)
+ */
+export async function handleError(error) {
+    return errorHandler.handle(error);
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/utils/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Error handling utilities for type-safe error management
+ * @module cli/utils/errors
+ */
+/**
+ * Error severity levels for display formatting
+ */
+export declare enum ErrorSeverity {
+    ERROR = "error",
+    WARNING = "warning",
+    INFO = "info"
+}
+/**
+ * Options for error display customization
+ */
+export interface ErrorDisplayOptions {
+    severity?: ErrorSeverity;
+    prefix?: string;
+    showStack?: boolean;
+}
+/**
+ * Type guard to check if an unknown value is an Error instance
+ */
+export declare function isError(error: unknown): error is Error;
+/**
+ * Safely extract error message from unknown error value
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Safely extract error stack from unknown error value
+ */
+export declare function getErrorStack(error: unknown): string | undefined;
+/**
+ * Display error with consistent formatting and colors
+ *
+ * @param error - Error to display (Error instance, string, or unknown)
+ * @param options - Display customization options
+ */
+export declare function displayError(error: unknown, options?: ErrorDisplayOptions): void;
+/**
+ * Display warning message with yellow color and emoji
+ *
+ * @param message - Warning message to display
+ */
+export declare function displayWarning(message: string): void;
+/**
+ * Display informational message with blue color and emoji
+ *
+ * @param message - Info message to display
+ */
+export declare function displayInfo(message: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cli/utils/errors.js

@@ -0,0 +1,102 @@
+/**
+ * Error handling utilities for type-safe error management
+ * @module cli/utils/errors
+ */
+import chalk from 'chalk';
+/**
+ * Error severity levels for display formatting
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    ErrorSeverity["ERROR"] = "error";
+    ErrorSeverity["WARNING"] = "warning";
+    ErrorSeverity["INFO"] = "info";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * Type guard to check if an unknown value is an Error instance
+ */
+export function isError(error) {
+    return error instanceof Error;
+}
+/**
+ * Safely extract error message from unknown error value
+ */
+export function getErrorMessage(error) {
+    if (isError(error)) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Safely extract error stack from unknown error value
+ */
+export function getErrorStack(error) {
+    if (isError(error)) {
+        return error.stack;
+    }
+    return undefined;
+}
+/**
+ * Display error with consistent formatting and colors
+ *
+ * @param error - Error to display (Error instance, string, or unknown)
+ * @param options - Display customization options
+ */
+export function displayError(error, options = {}) {
+    const { severity = ErrorSeverity.ERROR, prefix, showStack = false } = options;
+    const message = getErrorMessage(error);
+    // Select emoji and color based on severity
+    let emoji;
+    let color;
+    switch (severity) {
+        case ErrorSeverity.ERROR:
+            emoji = '❌';
+            color = chalk.red;
+            break;
+        case ErrorSeverity.WARNING:
+            emoji = '⚠️';
+            color = chalk.yellow;
+            break;
+        case ErrorSeverity.INFO:
+            emoji = 'ℹ️';
+            color = chalk.blue;
+            break;
+    }
+    // Build output message
+    const parts = [emoji];
+    if (prefix) {
+        parts.push(prefix);
+    }
+    parts.push(message);
+    console.error(color(parts.join(' ')));
+    // Optionally display stack trace
+    if (showStack) {
+        const stack = getErrorStack(error);
+        if (stack) {
+            console.error(chalk.gray(stack));
+        }
+    }
+}
+/**
+ * Display warning message with yellow color and emoji
+ *
+ * @param message - Warning message to display
+ */
+export function displayWarning(message) {
+    displayError(message, { severity: ErrorSeverity.WARNING });
+}
+/**
+ * Display informational message with blue color and emoji
+ *
+ * @param message - Info message to display
+ */
+export function displayInfo(message) {
+    displayError(message, { severity: ErrorSeverity.INFO });
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/utils/get-sdk-path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility to get SDK path - works in both ESM runtime and CommonJS tests
+ * Automatically detects whether running from SDK root (dev/test) or installed package
+ */
+/**
+ * Get the SDK root directory path
+ * Auto-detects: SDK root (tests/dev) or node_modules/@trinity-method/sdk (production)
+ */
+export declare function getSDKPath(): Promise<string>;
+/**
+ * Get the templates directory path
+ */
+export declare function getTemplatesPath(): Promise<string>;
+/**
+ * Get the package.json path
+ */
+export declare function getPackageJsonPath(): Promise<string>;
+//# sourceMappingURL=get-sdk-path.d.ts.map

package/dist/cli/utils/get-sdk-path.js

@@ -0,0 +1,31 @@
+/**
+ * Utility to get SDK path - works in both ESM runtime and CommonJS tests
+ * Automatically detects whether running from SDK root (dev/test) or installed package
+ */
+import path from 'path';
+import fs from 'fs-extra';
+/**
+ * Get the SDK root directory path
+ * Auto-detects: SDK root (tests/dev) or node_modules/@trinity-method/sdk (production)
+ */
+export async function getSDKPath() {
+    // Check if dist/templates exists in current directory (running from SDK root)
+    if (await fs.pathExists(path.join(process.cwd(), 'dist/templates'))) {
+        return process.cwd();
+    }
+    // Otherwise assume installed as npm package
+    return path.join(process.cwd(), 'node_modules', '@trinity-method', 'sdk');
+}
+/**
+ * Get the templates directory path
+ */
+export async function getTemplatesPath() {
+    return path.join(await getSDKPath(), 'dist/templates');
+}
+/**
+ * Get the package.json path
+ */
+export async function getPackageJsonPath() {
+    return path.join(await getSDKPath(), 'package.json');
+}
+//# sourceMappingURL=get-sdk-path.js.map

package/dist/cli/utils/inject-dependencies.d.ts

@@ -0,0 +1,2 @@
+export declare function injectLintingDependencies(dependencies: string[], scripts: Record<string, string>, framework: string): Promise<void>;
+//# sourceMappingURL=inject-dependencies.d.ts.map

package/dist/cli/utils/inject-dependencies.js

@@ -0,0 +1,55 @@
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import { validatePath } from './validate-path.js';
+export async function injectLintingDependencies(dependencies, scripts, framework) {
+    if (framework === 'Node.js' || framework === 'React' || framework === 'Next.js') {
+        await injectNodeDependencies(dependencies, scripts);
+    }
+    else if (framework === 'Python') {
+        await injectPythonDependencies(dependencies);
+    }
+    // Rust and Flutter have built-in tools, no injection needed
+}
+async function injectNodeDependencies(dependencies, scripts) {
+    const packageJsonPath = 'package.json';
+    if (!(await fs.pathExists(packageJsonPath))) {
+        console.warn(chalk.yellow('   Warning: package.json not found, skipping dependency injection'));
+        return;
+    }
+    const packageJson = await fs.readJson(packageJsonPath);
+    // Add devDependencies
+    packageJson.devDependencies = packageJson.devDependencies || {};
+    dependencies.forEach((dep) => {
+        // Handle scoped packages like @typescript-eslint/parser@^6.7.0
+        const lastAtIndex = dep.lastIndexOf('@');
+        const name = dep.substring(0, lastAtIndex);
+        const version = dep.substring(lastAtIndex + 1);
+        packageJson.devDependencies[name] = version;
+    });
+    // Add Scripts
+    packageJson.scripts = packageJson.scripts || {};
+    Object.entries(scripts).forEach(([name, command]) => {
+        if (!packageJson.scripts[name]) {
+            packageJson.scripts[name] = command;
+        }
+    });
+    // Write back with formatting
+    await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+}
+async function injectPythonDependencies(dependencies) {
+    const requirementsPath = 'requirements-dev.txt';
+    // Create or append to requirements-dev.txt
+    let content = '';
+    if (await fs.pathExists(requirementsPath)) {
+        content = await fs.readFile(requirementsPath, 'utf8');
+    }
+    dependencies.forEach((dep) => {
+        if (!content.includes(dep.split('>=')[0])) {
+            content += `${dep}\n`;
+        }
+    });
+    // Validate destination path for security
+    const validatedPath = validatePath(requirementsPath);
+    await fs.writeFile(validatedPath, content);
+}
+//# sourceMappingURL=inject-dependencies.js.map

package/dist/cli/utils/linting-tools.d.ts

@@ -0,0 +1,8 @@
+import { LintingTool, PostInstallInstruction } from '../types.js';
+export declare const lintingTools: Record<string, LintingTool[]>;
+export declare function getToolsForFramework(framework: string, language: string): LintingTool[];
+export declare function getRecommendedTools(framework: string, language: string): LintingTool[];
+export declare function getDependenciesForTools(selectedTools: LintingTool[]): string[];
+export declare function getScriptsForTools(selectedTools: LintingTool[]): Record<string, string>;
+export declare function getPostInstallInstructions(selectedTools: LintingTool[], _framework: string): PostInstallInstruction[];
+//# sourceMappingURL=linting-tools.d.ts.map