@within-7/minto 0.1.7 → 0.3.0

package/cli.js

@@ -1,59 +1,177 @@
 #!/usr/bin/env node
 
-// Cross-platform CLI wrapper for Minto
-// Prefers Bun but falls back to Node.js with tsx loader
+/**
+ * Minto CLI Wrapper
+ *
+ * This wrapper provides seamless execution across different environments:
+ *
+ * Priority 1: Pre-compiled native binary (from optionalDependencies)
+ *   - Best performance, no runtime dependencies
+ *   - Installed automatically via npm optionalDependencies
+ *
+ * Priority 2: Bun runtime
+ *   - Excellent PTY/stdin handling
+ *   - Fast startup time
+ *
+ * Priority 3: Node.js runtime
+ *   - Fallback for environments without Bun
+ *   - May have PTY issues in some terminals
+ */
 
-const { spawn } = require('child_process');
-const { existsSync } = require('fs');
+const { spawn, spawnSync } = require('child_process');
+const { existsSync, chmodSync } = require('fs');
 const path = require('path');
 
-// Get the directory where this CLI script is installed
 const mintoDir = __dirname;
-const distPath = path.join(mintoDir, 'dist', 'index.js');
+const args = process.argv.slice(2);
 
-// Check if we have a built version
-if (!existsSync(distPath)) {
-  console.error('❌ Built files not found. Run "bun run build" first.');
-  process.exit(1);
-}
+/**
+ * Get the native binary path from optionalDependencies
+ * npm installs platform-specific packages to node_modules
+ * @returns {string|null} Path to binary or null if not found
+ */
+function getNativeBinaryPath() {
+  const platform = process.platform;  // darwin, linux, win32
+  const arch = process.arch;          // arm64, x64
+  const packageName = `@within-7/minto-${platform}-${arch}`;
+  const binaryName = platform === 'win32' ? 'minto.exe' : 'minto';
 
-// Try to use Bun first, then fallback to Node.js with tsx
-const runWithBun = () => {
-  const proc = spawn('bun', ['run', distPath, ...process.argv.slice(2)], {
-    stdio: 'inherit',
-    cwd: process.cwd()  // Use current working directory, not minto installation directory
-  });
+  // Check in node_modules (installed via optionalDependencies)
+  const possiblePaths = [
+    // Standard npm install location
+    path.join(mintoDir, 'node_modules', packageName, binaryName),
+    // Hoisted location (npm/yarn may hoist)
+    path.join(mintoDir, '..', packageName, binaryName),
+    // pnpm symlink location
+    path.join(mintoDir, 'node_modules', '.pnpm', 'node_modules', packageName, binaryName),
+    // Global install - check parent node_modules
+    path.join(mintoDir, '..', '..', packageName, binaryName),
+  ];
 
-  proc.on('error', (err) => {
-    if (err.code === 'ENOENT') {
-      // Bun not found, try Node.js
-      runWithNode();
-    } else {
-      console.error('❌ Failed to start with Bun:', err.message);
-      process.exit(1);
+  for (const binaryPath of possiblePaths) {
+    if (existsSync(binaryPath)) {
+      // Ensure executable permission on Unix
+      if (platform !== 'win32') {
+        try {
+          chmodSync(binaryPath, 0o755);
+        } catch {
+          // Ignore - might already be executable or no permission
+        }
+      }
+      return binaryPath;
     }
-  });
+  }
 
-  proc.on('close', (code) => {
-    process.exit(code);
-  });
-};
+  // Also check legacy binaries/ directory (for backward compatibility)
+  const legacyPath = path.join(mintoDir, 'binaries', `minto-${platform}-${arch}${platform === 'win32' ? '.exe' : ''}`);
+  if (existsSync(legacyPath)) {
+    if (platform !== 'win32') {
+      try {
+        chmodSync(legacyPath, 0o755);
+      } catch {}
+    }
+    return legacyPath;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a runtime command is available
+ * @param {string} command - Command to check (e.g., 'bun', 'node')
+ * @returns {boolean}
+ */
+function isRuntimeAvailable(command) {
+  try {
+    const result = spawnSync(command, ['--version'], {
+      stdio: 'pipe',
+      timeout: 5000,
+      windowsHide: true
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
 
-const runWithNode = () => {
-  const proc = spawn('node', [distPath, ...process.argv.slice(2)], {
+/**
+ * Spawn a process and handle exit
+ * @param {string} command
+ * @param {string[]} cmdArgs
+ */
+function runAndExit(command, cmdArgs) {
+  const proc = spawn(command, cmdArgs, {
     stdio: 'inherit',
-    cwd: process.cwd()  // Use current working directory, not minto installation directory
+    cwd: process.cwd()
   });
 
   proc.on('error', (err) => {
-    console.error('❌ Failed to start with Node.js:', err.message);
+    console.error(`❌ Failed to start: ${err.message}`);
     process.exit(1);
   });
 
   proc.on('close', (code) => {
-    process.exit(code);
+    process.exit(code ?? 0);
   });
-};
+}
+
+/**
+ * Show helpful error message when no execution method is available
+ */
+function showInstallationHelp() {
+  console.error('');
+  console.error('❌ Minto 无法启动');
+  console.error('');
+  console.error('   当前平台缺少可用的运行环境。');
+  console.error('');
+  console.error('   请安装 Bun 运行时 (推荐，一行命令即可):');
+  console.error('');
+
+  if (process.platform === 'win32') {
+    console.error('   Windows (PowerShell 管理员模式):');
+    console.error('   powershell -c "irm bun.sh/install.ps1 | iex"');
+  } else if (process.platform === 'darwin') {
+    console.error('   macOS (终端):');
+    console.error('   curl -fsSL https://bun.sh/install | bash');
+  } else {
+    console.error('   Linux (终端):');
+    console.error('   curl -fsSL https://bun.sh/install | bash');
+  }
+
+  console.error('');
+  console.error('   安装完成后，重新打开终端并运行: minto');
+  console.error('');
+  console.error('   如有问题，请访问: https://github.com/within-7/minto/issues');
+  console.error('');
+}
+
+// ============ Main Execution Logic ============
+
+// Priority 1: Try native binary (best option)
+const nativeBinary = getNativeBinaryPath();
+if (nativeBinary) {
+  runAndExit(nativeBinary, args);
+  return; // Note: runAndExit handles process exit
+}
+
+// Priority 2: Try Bun runtime
+if (isRuntimeAvailable('bun')) {
+  const distPath = path.join(mintoDir, 'dist', 'index.js');
+  if (existsSync(distPath)) {
+    runAndExit('bun', ['run', distPath, ...args]);
+    return;
+  }
+}
+
+// Priority 3: Try Node.js runtime
+if (isRuntimeAvailable('node')) {
+  const distPath = path.join(mintoDir, 'dist', 'index.js');
+  if (existsSync(distPath)) {
+    runAndExit('node', [distPath, ...args]);
+    return;
+  }
+}
 
-// Start with Bun preference
-runWithBun();
+// No execution method available
+showInstallationHelp();
+process.exit(1);

package/dist/Tool.js

@@ -1 +1,39 @@
+function getToolDescription(tool) {
+  if (tool.cachedDescription) {
+    return tool.cachedDescription;
+  }
+  if (typeof tool.description === "string") {
+    return tool.description;
+  }
+  return `Tool: ${tool.name}`;
+}
+async function getToolDescriptionAsync(tool, input) {
+  if (typeof tool.description === "string") {
+    return tool.description;
+  }
+  if (typeof tool.description === "function") {
+    return await tool.description(input);
+  }
+  return `Tool: ${tool.name}`;
+}
+async function cacheToolDescriptions(tools) {
+  await Promise.all(
+    tools.map(async (tool) => {
+      if (typeof tool.description === "function" && !tool.cachedDescription) {
+        try {
+          tool.cachedDescription = await tool.description();
+        } catch (error) {
+          tool.cachedDescription = `Tool: ${tool.name}`;
+        }
+      } else if (typeof tool.description === "string" && !tool.cachedDescription) {
+        tool.cachedDescription = tool.description;
+      }
+    })
+  );
+}
+export {
+  cacheToolDescriptions,
+  getToolDescription,
+  getToolDescriptionAsync
+};
 //# sourceMappingURL=Tool.js.map

package/dist/Tool.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": [],
-  "sourcesContent": [],
-  "mappings": "",
+  "sources": ["../src/Tool.ts"],
+  "sourcesContent": ["import { z } from 'zod'\nimport * as React from 'react'\nimport type { UserQuestion, UserAnswer } from './types/askUserQuestion'\nimport type {\n  ToolUseOptions,\n  ResponseState,\n  ValidationResult as CoreValidationResult,\n} from './types/core'\n\n/**\n * Core Tool interface for Minto's extensible tool system\n * Provides standardized contract for all tool implementations\n *\n * IMPORTANT: Tool descriptions can be either:\n * - A string (synchronous, preferred for adapters)\n * - An async function (for dynamic descriptions)\n * - An async function that accepts input (for context-aware descriptions)\n *\n * Use getToolDescription() helper for safe synchronous access.\n */\n\nexport type SetToolJSXFn = (\n  jsx: {\n    jsx: React.ReactNode | null\n    shouldHidePromptInput: boolean\n  } | null,\n) => void\n\n/**\n * Function type for asking the user questions\n */\nexport type AskUserFn = (questions: UserQuestion[]) => Promise<UserAnswer[]>\n\nexport interface ToolUseContext {\n  messageId: string | undefined\n  agentId?: string\n  /** The tool_use ID from the API (for tracking concurrent executions) */\n  toolUseId?: string\n  safeMode?: boolean\n  abortController: AbortController\n  readFileTimestamps: { [filePath: string]: number }\n  options?: ToolUseOptions\n  responseState?: ResponseState\n}\n\nexport interface ExtendedToolUseContext extends ToolUseContext {\n  setToolJSX: SetToolJSXFn\n  askUser?: AskUserFn\n}\n\n// Re-export for backward compatibility\nexport type ValidationResult = CoreValidationResult\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface Tool<\n  TInput extends z.ZodObject<any> = z.ZodObject<any>,\n  TOutput = any,\n> {\n  name: string\n  /**\n   * Tool description - can be:\n   * - A string (synchronous, best for adapters)\n   * - An async function returning string (for dynamic descriptions)\n   * - An async function accepting input (for context-aware descriptions)\n   *\n   * Use getToolDescription() for safe synchronous access in adapters.\n   */\n  description?: string | ((input?: z.infer<TInput>) => Promise<string>)\n  /**\n   * Cached description for synchronous access.\n   * Populated by cacheToolDescriptions() at startup.\n   */\n  cachedDescription?: string\n  inputSchema: TInput\n  inputJSONSchema?: Record<string, unknown>\n  prompt: (options?: { safeMode?: boolean }) => Promise<string>\n  /**\n   * User-facing name for display. Can optionally accept input for context.\n   */\n  userFacingName?: (input?: z.infer<TInput>) => string\n  isEnabled: () => Promise<boolean>\n  /**\n   * Whether this tool only reads data (no side effects).\n   * Can optionally accept input to determine based on parameters.\n   */\n  isReadOnly: (input?: z.infer<TInput>) => boolean\n  /**\n   * Whether this tool is safe to run concurrently with other tools.\n   * Can optionally accept input to determine based on parameters.\n   */\n  isConcurrencySafe: (input?: z.infer<TInput>) => boolean\n  needsPermissions: (input?: z.infer<TInput>) => boolean\n  /**\n   * Whether this tool requires user interaction (e.g., confirmation dialogs).\n   */\n  requiresUserInteraction?: (input?: z.infer<TInput>) => boolean\n  validateInput?: (\n    input: z.infer<TInput>,\n    context?: ToolUseContext,\n  ) => Promise<ValidationResult>\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  renderResultForAssistant: (output: TOutput) => string | any[]\n  renderToolUseMessage: (\n    input: z.infer<TInput>,\n    options: { verbose: boolean },\n  ) => string | React.ReactElement | null\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  renderToolUseRejectedMessage?: (...args: any[]) => React.ReactElement | null\n  /**\n   * Render the tool result for display.\n   * @param output - The tool output\n   * @param options - Rendering options including verbose mode\n   */\n  renderToolResultMessage?: (\n    output: TOutput,\n    options?: { verbose: boolean },\n  ) => React.ReactNode\n  call: (\n    input: z.infer<TInput>,\n    context: ToolUseContext,\n  ) => AsyncGenerator<\n    | {\n        type: 'result'\n        data: TOutput\n        resultForAssistant?: string | any[]\n        /**\n         * New messages to add to the conversation\n         */\n        newMessages?: unknown[]\n        /**\n         * Context modifier for modifying context during execution\n         */\n        contextModifier?: {\n          modifyContext: (ctx: ToolUseContext) => ToolUseContext\n        }\n      }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    | {\n        type: 'progress'\n        content: any\n        normalizedMessages?: any[]\n        tools?: any[]\n      },\n    void,\n    unknown\n  >\n}\n\n/**\n * Get tool description synchronously.\n * Returns cached description if available, or falls back to string description,\n * or a default value if description is async and not cached.\n *\n * @param tool - The tool to get description from\n * @returns The tool description string\n */\nexport function getToolDescription(tool: Tool): string {\n  // First check cached description\n  if (tool.cachedDescription) {\n    return tool.cachedDescription\n  }\n\n  // If description is a string, return it directly\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  // Fallback for async descriptions that haven't been cached\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Get tool description asynchronously.\n * Always returns the actual description, resolving async functions if needed.\n *\n * @param tool - The tool to get description from\n * @param input - Optional input for context-aware descriptions\n * @returns Promise resolving to the tool description string\n */\nexport async function getToolDescriptionAsync(\n  tool: Tool,\n  input?: unknown,\n): Promise<string> {\n  if (typeof tool.description === 'string') {\n    return tool.description\n  }\n\n  if (typeof tool.description === 'function') {\n    return await tool.description(input)\n  }\n\n  return `Tool: ${tool.name}`\n}\n\n/**\n * Cache descriptions for all tools.\n * Should be called at startup to ensure synchronous access works.\n *\n * @param tools - Array of tools to cache descriptions for\n */\nexport async function cacheToolDescriptions(tools: Tool[]): Promise<void> {\n  await Promise.all(\n    tools.map(async tool => {\n      if (typeof tool.description === 'function' && !tool.cachedDescription) {\n        try {\n          tool.cachedDescription = await tool.description()\n        } catch (error) {\n          // Fallback on error\n          tool.cachedDescription = `Tool: ${tool.name}`\n        }\n      } else if (\n        typeof tool.description === 'string' &&\n        !tool.cachedDescription\n      ) {\n        tool.cachedDescription = tool.description\n      }\n    }),\n  )\n}\n"],
+  "mappings": "AA4JO,SAAS,mBAAmB,MAAoB;AAErD,MAAI,KAAK,mBAAmB;AAC1B,WAAO,KAAK;AAAA,EACd;AAGA,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAGA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAUA,eAAsB,wBACpB,MACA,OACiB;AACjB,MAAI,OAAO,KAAK,gBAAgB,UAAU;AACxC,WAAO,KAAK;AAAA,EACd;AAEA,MAAI,OAAO,KAAK,gBAAgB,YAAY;AAC1C,WAAO,MAAM,KAAK,YAAY,KAAK;AAAA,EACrC;AAEA,SAAO,SAAS,KAAK,IAAI;AAC3B;AAQA,eAAsB,sBAAsB,OAA8B;AACxE,QAAM,QAAQ;AAAA,IACZ,MAAM,IAAI,OAAM,SAAQ;AACtB,UAAI,OAAO,KAAK,gBAAgB,cAAc,CAAC,KAAK,mBAAmB;AACrE,YAAI;AACF,eAAK,oBAAoB,MAAM,KAAK,YAAY;AAAA,QAClD,SAAS,OAAO;AAEd,eAAK,oBAAoB,SAAS,KAAK,IAAI;AAAA,QAC7C;AAAA,MACF,WACE,OAAO,KAAK,gBAAgB,YAC5B,CAAC,KAAK,mBACN;AACA,aAAK,oBAAoB,KAAK;AAAA,MAChC;AAAA,IACF,CAAC;AAAA,EACH;AACF;",
   "names": []
 }