@within-7/minto 0.1.7 → 0.3.0

package/dist/utils/userFriendlyError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/userFriendlyError.ts"],
+  "sourcesContent": ["/**\n * User-Friendly Error System\n *\n * Transforms technical errors into friendly messages for non-developer users.\n * Provides structured logging for debugging and optional cloud reporting.\n *\n * Design Philosophy:\n * - User layer: Simple, actionable messages in their language\n * - Developer layer: Full technical details for debugging\n * - Operations layer: Structured data for analysis and improvement\n */\n\nimport { randomUUID } from 'crypto'\nimport * as fs from 'fs'\nimport * as path from 'path'\nimport { t, tSafe } from '@i18n/index'\n\n// ============================================================================\n// Error Categories\n// ============================================================================\n\n/**\n * High-level error categories that map to user-understandable concepts\n */\nexport enum ErrorCategory {\n  // Network & Connectivity\n  NETWORK_CONNECTION = 'network_connection', // Can't reach the server\n  NETWORK_TIMEOUT = 'network_timeout', // Request took too long\n  NETWORK_DNS = 'network_dns', // Can't find the server\n\n  // API & Service\n  API_RATE_LIMIT = 'api_rate_limit', // Too many requests\n  API_AUTH = 'api_auth', // Authentication failed\n  API_QUOTA = 'api_quota', // Usage quota exceeded\n  API_SERVER_ERROR = 'api_server_error', // Server is having issues\n  API_INVALID_RESPONSE = 'api_invalid_response', // Unexpected response\n\n  // File & Storage\n  FILE_NOT_FOUND = 'file_not_found', // File doesn't exist\n  FILE_PERMISSION = 'file_permission', // Can't access file\n  FILE_TOO_LARGE = 'file_too_large', // File is too big\n  FILE_ENCODING = 'file_encoding', // Can't read file format\n\n  // Configuration\n  CONFIG_MISSING = 'config_missing', // Missing required setting\n  CONFIG_INVALID = 'config_invalid', // Invalid setting value\n  CONFIG_API_KEY = 'config_api_key', // API key issue\n\n  // Model & AI\n  MODEL_UNAVAILABLE = 'model_unavailable', // Model not accessible\n  MODEL_CONTEXT_LENGTH = 'model_context_length', // Input too long\n  MODEL_CONTENT_FILTER = 'model_content_filter', // Content blocked\n\n  // System\n  SYSTEM_MEMORY = 'system_memory', // Out of memory\n  SYSTEM_PROCESS = 'system_process', // Process error\n\n  // Unknown\n  UNKNOWN = 'unknown', // Unclassified error\n}\n\n// ============================================================================\n// User-Friendly Messages (Multi-language support via i18n)\n// ============================================================================\n\ninterface FriendlyMessage {\n  title: string\n  description: string\n  suggestions: string[]\n}\n\n/**\n * Maps error categories to i18n translation key prefixes\n */\nconst CATEGORY_TO_I18N_PREFIX: Record<ErrorCategory, string> = {\n  [ErrorCategory.NETWORK_CONNECTION]: 'friendlyError.networkConnection',\n  [ErrorCategory.NETWORK_TIMEOUT]: 'friendlyError.networkTimeout',\n  [ErrorCategory.NETWORK_DNS]: 'friendlyError.networkDns',\n  [ErrorCategory.API_RATE_LIMIT]: 'friendlyError.apiRateLimit',\n  [ErrorCategory.API_AUTH]: 'friendlyError.apiAuth',\n  [ErrorCategory.API_QUOTA]: 'friendlyError.apiQuota',\n  [ErrorCategory.API_SERVER_ERROR]: 'friendlyError.apiServerError',\n  [ErrorCategory.API_INVALID_RESPONSE]: 'friendlyError.apiInvalidResponse',\n  [ErrorCategory.FILE_NOT_FOUND]: 'friendlyError.fileNotFound',\n  [ErrorCategory.FILE_PERMISSION]: 'friendlyError.filePermission',\n  [ErrorCategory.FILE_TOO_LARGE]: 'friendlyError.fileTooLarge',\n  [ErrorCategory.FILE_ENCODING]: 'friendlyError.fileEncoding',\n  [ErrorCategory.CONFIG_MISSING]: 'friendlyError.configMissing',\n  [ErrorCategory.CONFIG_INVALID]: 'friendlyError.configInvalid',\n  [ErrorCategory.CONFIG_API_KEY]: 'friendlyError.configApiKey',\n  [ErrorCategory.MODEL_UNAVAILABLE]: 'friendlyError.modelUnavailable',\n  [ErrorCategory.MODEL_CONTEXT_LENGTH]: 'friendlyError.modelContextLength',\n  [ErrorCategory.MODEL_CONTENT_FILTER]: 'friendlyError.modelContentFilter',\n  [ErrorCategory.SYSTEM_MEMORY]: 'friendlyError.systemMemory',\n  [ErrorCategory.SYSTEM_PROCESS]: 'friendlyError.systemProcess',\n  [ErrorCategory.UNKNOWN]: 'friendlyError.unknown',\n}\n\n/**\n * Get friendly message using i18n\n * Designed for non-technical users (analysts, researchers, writers, etc.)\n */\nfunction getFriendlyMessage(category: ErrorCategory): FriendlyMessage {\n  const prefix = CATEGORY_TO_I18N_PREFIX[category]\n\n  // Build suggestions array dynamically (use tSafe to avoid warnings for missing keys)\n  const suggestions: string[] = []\n  for (let i = 1; i <= 3; i++) {\n    const suggestion = tSafe(`${prefix}.suggestion${i}`)\n    if (suggestion) {\n      suggestions.push(suggestion)\n    }\n  }\n\n  return {\n    title: tSafe(`${prefix}.title`) || category,\n    description: tSafe(`${prefix}.description`) || '',\n    suggestions,\n  }\n}\n\n/**\n * Legacy FRIENDLY_MESSAGES for backward compatibility\n * @deprecated Use getFriendlyMessage() for i18n support\n */\nconst FRIENDLY_MESSAGES: Record<ErrorCategory, FriendlyMessage> =\n  Object.fromEntries(\n    Object.values(ErrorCategory).map(category => [\n      category,\n      getFriendlyMessage(category),\n    ]),\n  ) as Record<ErrorCategory, FriendlyMessage>\n\n// ============================================================================\n// Error Classification Logic\n// ============================================================================\n\ninterface ErrorPattern {\n  category: ErrorCategory\n  patterns: (string | RegExp)[]\n}\n\n/**\n * Patterns to classify raw errors into categories\n * Order matters - more specific patterns should come first\n */\nconst ERROR_PATTERNS: ErrorPattern[] = [\n  // Network errors\n  {\n    category: ErrorCategory.NETWORK_CONNECTION,\n    patterns: [\n      'socket.*closed',\n      'ECONNREFUSED',\n      'ECONNRESET',\n      'ENOTFOUND',\n      'connection.*refused',\n      'connection.*closed',\n      'network.*error',\n      'fetch failed',\n    ],\n  },\n  {\n    category: ErrorCategory.NETWORK_TIMEOUT,\n    patterns: [\n      'timeout',\n      'ETIMEDOUT',\n      'timed out',\n      'deadline exceeded',\n      'request.*timeout',\n    ],\n  },\n  {\n    category: ErrorCategory.NETWORK_DNS,\n    patterns: ['ENOTFOUND', 'getaddrinfo', 'DNS', 'resolve.*failed'],\n  },\n\n  // API errors\n  {\n    category: ErrorCategory.API_RATE_LIMIT,\n    patterns: ['rate.*limit', '429', 'too many requests', 'quota.*exceeded'],\n  },\n  {\n    category: ErrorCategory.API_AUTH,\n    patterns: [\n      '401',\n      'unauthorized',\n      'authentication.*failed',\n      'invalid.*key',\n      'api.*key.*invalid',\n    ],\n  },\n  {\n    category: ErrorCategory.API_QUOTA,\n    patterns: [\n      'insufficient.*quota',\n      'billing',\n      'credit',\n      'exceeded.*quota',\n      '402',\n    ],\n  },\n  {\n    category: ErrorCategory.API_SERVER_ERROR,\n    patterns: ['500', '502', '503', '504', 'internal.*error', 'server.*error'],\n  },\n\n  // File errors\n  {\n    category: ErrorCategory.FILE_NOT_FOUND,\n    patterns: ['ENOENT', 'no such file', 'file.*not.*found', 'does not exist'],\n  },\n  {\n    category: ErrorCategory.FILE_PERMISSION,\n    patterns: ['EACCES', 'EPERM', 'permission.*denied', 'access.*denied'],\n  },\n  {\n    category: ErrorCategory.FILE_TOO_LARGE,\n    patterns: ['file.*too.*large', 'EFBIG', 'size.*limit'],\n  },\n\n  // Model errors\n  {\n    category: ErrorCategory.MODEL_CONTEXT_LENGTH,\n    patterns: [\n      'context.*length',\n      'token.*limit',\n      'max.*tokens',\n      'too.*long',\n      'exceeds.*maximum',\n    ],\n  },\n  {\n    category: ErrorCategory.MODEL_CONTENT_FILTER,\n    patterns: ['content.*filter', 'safety', 'blocked', 'moderation'],\n  },\n  {\n    category: ErrorCategory.MODEL_UNAVAILABLE,\n    patterns: ['model.*not.*found', 'model.*unavailable', 'does not exist'],\n  },\n\n  // Config errors\n  {\n    category: ErrorCategory.CONFIG_API_KEY,\n    patterns: [\n      'api.*key.*not.*set',\n      'missing.*api.*key',\n      'ANTHROPIC_API_KEY',\n      'OPENAI_API_KEY',\n    ],\n  },\n\n  // System errors\n  {\n    category: ErrorCategory.SYSTEM_MEMORY,\n    patterns: ['ENOMEM', 'out of memory', 'heap', 'memory.*limit'],\n  },\n]\n\n/**\n * Classifies a raw error into a category\n */\nexport function classifyError(error: unknown): ErrorCategory {\n  const errorString = getErrorString(error).toLowerCase()\n\n  for (const { category, patterns } of ERROR_PATTERNS) {\n    for (const pattern of patterns) {\n      if (typeof pattern === 'string') {\n        if (errorString.includes(pattern.toLowerCase())) {\n          return category\n        }\n      } else if (pattern.test(errorString)) {\n        return category\n      }\n    }\n  }\n\n  return ErrorCategory.UNKNOWN\n}\n\nfunction getErrorString(error: unknown): string {\n  if (error instanceof Error) {\n    return `${error.name}: ${error.message} ${error.stack || ''}`\n  }\n  return String(error)\n}\n\n// ============================================================================\n// User-Friendly Error Class\n// ============================================================================\n\nexport interface ErrorContext {\n  /** Operation being performed (e.g., \"reading file\", \"calling API\") */\n  operation?: string\n  /** Model being used */\n  model?: string\n  /** File path involved */\n  filePath?: string\n  /** API endpoint */\n  endpoint?: string\n  /** Additional context */\n  [key: string]: unknown\n}\n\nexport interface ErrorLogEntry {\n  id: string\n  timestamp: string\n  category: ErrorCategory\n  friendlyTitle: string\n  technicalMessage: string\n  stack?: string\n  context: ErrorContext\n  systemInfo: {\n    platform: string\n    nodeVersion: string\n    mintoVersion: string\n  }\n}\n\n/**\n * User-Friendly Error wrapper\n * Provides both user-facing messages and technical details\n */\nexport class UserFriendlyError extends Error {\n  readonly id: string\n  readonly category: ErrorCategory\n  readonly friendlyMessage: FriendlyMessage\n  readonly originalError: unknown\n  readonly context: ErrorContext\n  readonly timestamp: Date\n\n  constructor(\n    originalError: unknown,\n    context: ErrorContext = {},\n    categoryOverride?: ErrorCategory,\n  ) {\n    const category = categoryOverride || classifyError(originalError)\n    const friendly = FRIENDLY_MESSAGES[category]\n\n    super(friendly.title)\n    this.name = 'UserFriendlyError'\n    this.id = randomUUID().slice(0, 8)\n    this.category = category\n    this.friendlyMessage = friendly\n    this.originalError = originalError\n    this.context = context\n    this.timestamp = new Date()\n\n    // Preserve original stack\n    if (originalError instanceof Error && originalError.stack) {\n      this.stack = originalError.stack\n    }\n  }\n\n  /**\n   * Get user-facing display message\n   */\n  getUserMessage(): string {\n    // Get fresh translations (in case language changed)\n    const message = getFriendlyMessage(this.category)\n    const suggestionLabel = t('friendlyError.suggestionLabel')\n    const errorIdLabel = t('friendlyError.errorIdLabel')\n\n    const lines = [\n      `\u26A0\uFE0F ${message.title}`,\n      '',\n      message.description,\n      '',\n      `\uD83D\uDCA1 ${suggestionLabel}:`,\n      ...message.suggestions.map(s => `  \u2022 ${s}`),\n      '',\n      `\uD83D\uDCCB ${errorIdLabel}: ${this.id}`,\n    ]\n    return lines.join('\\n')\n  }\n\n  /**\n   * Get technical message for developers\n   */\n  getTechnicalMessage(): string {\n    const original =\n      this.originalError instanceof Error\n        ? this.originalError.message\n        : String(this.originalError)\n    return `[${this.category}] ${original}`\n  }\n\n  /**\n   * Create structured log entry\n   */\n  toLogEntry(): ErrorLogEntry {\n    return {\n      id: this.id,\n      timestamp: this.timestamp.toISOString(),\n      category: this.category,\n      friendlyTitle: this.friendlyMessage.title,\n      technicalMessage: this.getTechnicalMessage(),\n      stack: this.stack,\n      context: this.context,\n      systemInfo: {\n        platform: process.platform,\n        nodeVersion: process.version,\n        mintoVersion: getMintoVersion(),\n      },\n    }\n  }\n}\n\n// ============================================================================\n// Error Logging\n// ============================================================================\n\nlet errorLogPath: string | null = null\n\nfunction getErrorLogPath(): string {\n  if (!errorLogPath) {\n    const logDir = path.join(process.env.HOME || '', '.minto', 'logs')\n    errorLogPath = path.join(logDir, 'errors.jsonl')\n  }\n  return errorLogPath\n}\n\n/**\n * Log error to local file (JSONL format for easy analysis)\n */\nexport function logUserFriendlyError(error: UserFriendlyError): void {\n  try {\n    const logPath = getErrorLogPath()\n    const logDir = path.dirname(logPath)\n\n    // Ensure log directory exists\n    if (!fs.existsSync(logDir)) {\n      fs.mkdirSync(logDir, { recursive: true })\n    }\n\n    const entry = error.toLogEntry()\n    fs.appendFileSync(logPath, JSON.stringify(entry) + '\\n')\n  } catch {\n    // Silent fail - don't let logging errors break the app\n  }\n}\n\n/**\n * Get recent errors for debugging\n */\nexport function getRecentErrors(limit = 10): ErrorLogEntry[] {\n  try {\n    const logPath = getErrorLogPath()\n    if (!fs.existsSync(logPath)) {\n      return []\n    }\n\n    const content = fs.readFileSync(logPath, 'utf-8')\n    const lines = content.trim().split('\\n').filter(Boolean)\n    const entries = lines\n      .slice(-limit)\n      .map(line => {\n        try {\n          return JSON.parse(line) as ErrorLogEntry\n        } catch {\n          return null\n        }\n      })\n      .filter((e): e is ErrorLogEntry => e !== null)\n\n    return entries.reverse()\n  } catch {\n    return []\n  }\n}\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\nfunction getMintoVersion(): string {\n  try {\n    const packageJsonPath = path.join(__dirname, '../../package.json')\n    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))\n    return packageJson.version || 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\n/**\n * Wrap any error into a UserFriendlyError\n */\nexport function toUserFriendlyError(\n  error: unknown,\n  context?: ErrorContext,\n): UserFriendlyError {\n  if (error instanceof UserFriendlyError) {\n    return error\n  }\n  return new UserFriendlyError(error, context)\n}\n\n/**\n * Format error for display to user\n * Returns the friendly message, optionally with technical details\n */\nexport function formatErrorForUser(\n  error: unknown,\n  options: { showTechnical?: boolean; context?: ErrorContext } = {},\n): string {\n  const friendly = toUserFriendlyError(error, options.context)\n\n  // Log the error\n  logUserFriendlyError(friendly)\n\n  let message = friendly.getUserMessage()\n\n  if (options.showTechnical) {\n    const technicalLabel = t('friendlyError.technicalDetailsLabel')\n    message += `\\n\\n\uD83D\uDD27 ${technicalLabel}: ${friendly.getTechnicalMessage()}`\n  }\n\n  return message\n}\n\n// ============================================================================\n// Exports for Integration\n// ============================================================================\n\nexport { FRIENDLY_MESSAGES, ERROR_PATTERNS }\n"],
+  "mappings": "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",
+  "names": ["ErrorCategory"]
+}

package/dist/version.js

@@ -1,5 +1,5 @@
-const VERSION = "0.1.7";
-const BUILD_DATE = "2026-01-05T08:18:26.755Z";
+const VERSION = "0.3.0";
+const BUILD_DATE = "2026-02-02T01:21:32.241Z";
 export {
   BUILD_DATE,
   VERSION

package/dist/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/version.ts"],
-  "sourcesContent": ["/**\n * Application version\n * This file is auto-generated during build process\n */\n\nexport const VERSION = '0.1.7'\nexport const BUILD_DATE = '2026-01-05T08:18:26.755Z'\n"],
+  "sourcesContent": ["/**\n * Application version\n * This file is auto-generated during build process\n */\n\nexport const VERSION = '0.3.0'\nexport const BUILD_DATE = '2026-02-02T01:21:32.241Z'\n"],
   "mappings": "AAKO,MAAM,UAAU;AAChB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@within-7/minto",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "bin": {
     "minto": "cli.js"
   },
@@ -27,7 +27,8 @@
   "scripts": {
     "dev": "bun run ./src/entrypoints/cli.tsx --verbose",
     "build": "node scripts/build.mjs",
-    "clean": "rm -rf cli.js",
+    "build:packages": "node scripts/build-platform-packages.mjs",
+    "clean": "rm -rf cli.js binaries packages",
     "prepublishOnly": "node scripts/build.mjs && node scripts/prepublish-check.js",
     "postinstall": "node scripts/postinstall.js || true",
     "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
@@ -37,8 +38,18 @@
     "test": "cd tests && bun test",
     "typecheck": "tsc --noEmit",
     "prepare": "",
+    "publish:packages": "node scripts/publish-platform-packages.mjs",
     "publish:dev": "node scripts/publish-dev.js",
-    "publish:release": "node scripts/publish-release.js"
+    "publish:release": "node scripts/publish-release.js",
+    "release": "node scripts/release-full.js",
+    "release:dry-run": "node scripts/release-full.js --dry-run"
+  },
+  "optionalDependencies": {
+    "@within-7/minto-darwin-arm64": "0.3.0",
+    "@within-7/minto-darwin-x64": "0.3.0",
+    "@within-7/minto-linux-arm64": "0.3.0",
+    "@within-7/minto-linux-x64": "0.3.0",
+    "@within-7/minto-win32-x64": "0.3.0"
   },
   "dependencies": {
     "@anthropic-ai/bedrock-sdk": "^0.12.6",
@@ -49,7 +60,6 @@
     "@modelcontextprotocol/sdk": "^1.15.1",
     "@types/lodash-es": "^4.17.12",
     "@types/react": "^19.1.8",
-    "@within-7/minto": "0.1.5",
     "ansi-escapes": "^7.0.0",
     "chalk": "^5.4.1",
     "cli-highlight": "^2.1.11",
@@ -70,6 +80,7 @@
     "lodash-es": "^4.17.21",
     "lru-cache": "^11.1.0",
     "marked": "^15.0.12",
+    "minimatch": "10.1.1",
     "nanoid": "^5.1.5",
     "node-fetch": "^3.3.2",
     "node-html-parser": "^7.0.1",
@@ -92,6 +103,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/jest": "^30.0.0",
+    "@types/minimatch": "6.0.0",
     "@types/node": "^24.1.0",
     "bun-types": "latest",
     "esbuild": "^0.25.9",
@@ -112,4 +124,4 @@
     "formdata-node": "^6.0.3",
     "node-domexception": "npm:domexception@^4.0.0"
   }
-}
+}

package/scripts/postinstall.js

@@ -1,11 +1,27 @@
 #!/usr/bin/env node
 
+/**
+ * Minto Post-Install Script
+ *
+ * This script runs after npm install to:
+ * 1. Check if the platform-specific binary was installed
+ * 2. Display helpful getting-started information
+ *
+ * The binary is installed automatically via optionalDependencies.
+ * If it fails (e.g., unsupported platform), we fall back to JS mode.
+ */
+
 const fs = require('fs');
 const path = require('path');
 
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+/**
+ * Get the package version from package.json
+ */
 function getPackageVersion() {
   try {
-    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkgPath = path.join(PACKAGE_ROOT, 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     return pkg.version;
   } catch {
@@ -13,50 +29,124 @@ function getPackageVersion() {
   }
 }
 
-function postinstallNotice() {
-  // Only print informational hints; never fail install.
-  // Use console.error (stderr) to ensure output is visible in npm install
-  try {
-    const version = getPackageVersion();
-    const isGlobal = process.env.npm_config_global === 'true';
+/**
+ * Get the expected package name for this platform
+ */
+function getPlatformPackageName() {
+  const platform = process.platform; // darwin, linux, win32
+  const arch = process.arch; // arm64, x64
+  return `@within-7/minto-${platform}-${arch}`;
+}
 
-    console.error('');
-    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.error('');
-    console.error('  ✨ Minto installed successfully!');
-    console.error('  📦 Version: ' + version);
-    console.error('');
-    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.error('');
-    console.error('  🚀 Quick Start:');
-    console.error('');
+/**
+ * Check if the platform binary package was installed
+ */
+function checkBinaryInstalled() {
+  const packageName = getPlatformPackageName();
+  const binaryName = process.platform === 'win32' ? 'minto.exe' : 'minto';
+
+  // Check possible installation locations
+  const possiblePaths = [
+    // Standard npm install location
+    path.join(PACKAGE_ROOT, 'node_modules', packageName, binaryName),
+    // Hoisted location
+    path.join(PACKAGE_ROOT, '..', packageName, binaryName),
+    // Global install
+    path.join(PACKAGE_ROOT, '..', '..', packageName, binaryName),
+  ];
 
-    if (isGlobal) {
-      console.error('     minto              # Start interactive mode');
-      console.error('     minto --help       # Show all commands');
-      console.error('     mt                 # Short alias for minto');
-    } else {
-      console.error('     npx minto          # Start interactive mode');
-      console.error('     npx minto --help   # Show all commands');
+  for (const binaryPath of possiblePaths) {
+    if (fs.existsSync(binaryPath)) {
+      // Ensure executable permission on Unix
+      if (process.platform !== 'win32') {
+        try {
+          fs.chmodSync(binaryPath, 0o755);
+        } catch {
+          // Ignore permission errors
+        }
+      }
+      return {
+        installed: true,
+        path: binaryPath,
+        packageName,
+      };
     }
+  }
 
+  return {
+    installed: false,
+    packageName,
+  };
+}
+
+/**
+ * Display installation success message
+ */
+function displaySuccessMessage(binaryStatus) {
+  const version = getPackageVersion();
+  const isGlobal = process.env.npm_config_global === 'true';
+
+  console.error('');
+  console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.error('');
+  console.error('  ✨ Minto 安装成功！');
+  console.error('  📦 版本: ' + version);
+
+  if (binaryStatus.installed) {
+    console.error('  🚀 运行模式: 原生二进制 (最佳性能)');
+  } else {
+    console.error('  📋 运行模式: JavaScript');
+    console.error('  💡 提示: 原生二进制不可用，将使用 JS 回退模式');
+  }
+
+  console.error('');
+  console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.error('');
+  console.error('  🚀 快速开始:');
+  console.error('');
+
+  if (isGlobal) {
+    console.error('     minto              # 启动交互模式');
+    console.error('     minto --help       # 查看所有命令');
+  } else {
+    console.error('     npx minto          # 启动交互模式');
+    console.error('     npx minto --help   # 查看所有命令');
+  }
+
+  console.error('');
+  console.error('  📚 文档: https://within-7.com/minto');
+  console.error('  🐛 问题反馈: https://github.com/within-7/minto/issues');
+  console.error('');
+  console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.error('');
+
+  if (!isGlobal) {
+    console.error('  💡 提示: 全局安装可以更方便地使用:');
+    console.error('     npm install -g @within-7/minto');
     console.error('');
-    console.error('  📚 Documentation: https://within-7.com/minto');
-    console.error('  🐛 Issues: https://github.com/within-7/minto/issues');
-    console.error('');
-    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-    console.error('');
+  }
+}
 
-    if (!isGlobal) {
-      console.error('  💡 Tip: Install globally for easier access:');
-      console.error('     npm install -g @within-7/minto');
-      console.error('');
-    }
+/**
+ * Main postinstall function
+ */
+function postinstall() {
+  // Only run during actual npm postinstall
+  if (process.env.npm_lifecycle_event !== 'postinstall') {
+    return;
+  }
+
+  try {
+    // Check if binary was installed
+    const binaryStatus = checkBinaryInstalled();
+
+    // Display success message
+    displaySuccessMessage(binaryStatus);
   } catch (err) {
-    // Silently fail - postinstall should never break the installation
+    // Silently fail - postinstall should never break installation
+    // Users can still use JavaScript fallback mode
   }
 }
 
-if (process.env.npm_lifecycle_event === 'postinstall') {
-  postinstallNotice();
-}
+// Run postinstall
+postinstall();