@miphamai/cli 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/agent-context.ts

@@ -1,4 +1,7 @@
 // apps/cli/src/agent/agent-context.ts
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { ContextManager } from '../core/context'
 import type { ToolDefinition } from '../shared/index.ts'
 import type { AgentDefinition } from './types'
@@ -8,6 +11,50 @@ export interface AgentContextResult {
   allowedTools: ToolDefinition[]
 }
 
+/**
+ * Load agent memory files from the appropriate scope directory.
+ * Returns combined content for injection into the system prompt.
+ */
+function loadAgentMemory(agentName: string, scope: 'user' | 'project' | 'local'): string {
+  let memoryDir: string
+  const home = homedir()
+
+  switch (scope) {
+    case 'user':
+      memoryDir = join(home, '.mipham', 'agent-memory', agentName)
+      break
+    case 'project':
+      memoryDir = join(process.cwd(), '.mipham', 'agent-memory', agentName)
+      break
+    case 'local':
+      memoryDir = join(process.cwd(), '.mipham', 'agent-memory-local', agentName)
+      break
+  }
+
+  if (!existsSync(memoryDir)) return ''
+
+  try {
+    const files = readdirSync(memoryDir).filter((f) => f.endsWith('.md'))
+    if (files.length === 0) return ''
+
+    const contents: string[] = []
+    for (const file of files.slice(0, 10)) {
+      // max 10 files
+      try {
+        const content = readFileSync(join(memoryDir, file), 'utf-8').trim()
+        if (content) contents.push(content)
+      } catch {
+        // skip unreadable
+      }
+    }
+
+    if (contents.length === 0) return ''
+    return [`[Agent Memory — ${scope} scope]`, ...contents].join('\n\n')
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Create an isolated context and tool set for a sub-agent.
  *
@@ -15,6 +62,9 @@ export interface AgentContextResult {
  * 1. If `tools` is set, only those tools are allowed.
  * 2. If `disallowedTools` is set, those are removed from the full set.
  * 3. If neither is set, all tools are available.
+ *
+ * Agent memory: if agentDef.memory is set, loads memory files from the
+ * appropriate scope and injects them into the system prompt.
  */
 export function createAgentContext(
   agentDef: AgentDefinition,
@@ -27,7 +77,16 @@ export function createAgentContext(
     compactionThreshold: 0.85,
   })
 
-  context.setSystemPrompt(agentDef.systemPrompt)
+  // Build system prompt with optional agent memory
+  let systemPrompt = agentDef.systemPrompt
+  if (agentDef.memory) {
+    const memory = loadAgentMemory(agentDef.name, agentDef.memory)
+    if (memory) {
+      systemPrompt = `${systemPrompt}\n\n---\n\n${memory}`
+    }
+  }
+
+  context.setSystemPrompt(systemPrompt)
 
   // Scope tools
   let allowedTools = Array.from(toolRegistry.values())

package/src/agent/agent-registry.ts

@@ -74,6 +74,7 @@ export class AgentRegistry {
                 .map((s) => s.trim())
             : undefined,
           background: (data.background as boolean) || false,
+          memory: data.memory as 'user' | 'project' | 'local' | undefined,
           source,
           filePath: fullPath,
         }

package/src/agent/types.ts

@@ -12,6 +12,7 @@ export interface AgentFrontmatter {
   maxTurns?: number
   skills?: string
   background?: boolean
+  memory?: 'user' | 'project' | 'local' // agent memory scope
 }
 
 export interface AgentDefinition {
@@ -27,6 +28,7 @@ export interface AgentDefinition {
   background: boolean
   source: 'builtin' | 'project' | 'user'
   filePath?: string
+  memory?: 'user' | 'project' | 'local' // agent memory scope
 }
 
 export interface SubAgentOptions {

package/src/core/engine.ts

@@ -10,6 +10,7 @@ import { getMemoryManager } from './memory/memory-loader'
 import type { AgentViewManager } from '../agent-view/agent-view-manager'
 import type { SkillsLoader } from '../skills/loader'
 import { getBackgroundAgentRegistry } from '../agent/background-registry'
+import { RulesLoader } from './rules-loader'
 
 export class QueryEngine {
   private hookEngine?: HookEngine
@@ -71,9 +72,40 @@ export class QueryEngine {
     this.skillsLoader = loader
   }
 
+  /** Rules loader for path-scoped rules injection. */
+  private rulesLoader?: RulesLoader
+  /** Files touched in the current turn (for rules matching). */
+  private touchedFiles: Set<string> = new Set()
+
+  /** Register the rules loader. */
+  setRulesLoader(loader: RulesLoader): void {
+    this.rulesLoader = loader
+    this.rulesLoader.load()
+  }
+
   /** Pending task notifications from background agents (cleared after draining). */
   private pendingTaskNotifications: Array<StreamChunk> = []
 
+  /** Track files touched by tools for rules matching. */
+  private trackTouchedFile(toolName: string, params: Record<string, unknown>): void {
+    const fileTools = ['Read', 'Write', 'Edit', 'Glob', 'Grep']
+    if (!fileTools.includes(toolName)) return
+    const filePath = (params.file_path || params.path || params.file) as string | undefined
+    if (filePath && typeof filePath === 'string') {
+      this.touchedFiles.add(filePath)
+    }
+  }
+
+  /** Inject matching rules as context after tool execution. */
+  private injectRules(): void {
+    if (!this.rulesLoader || this.touchedFiles.size === 0) return
+    const files = Array.from(this.touchedFiles)
+    const block = this.rulesLoader.buildContextBlock(files)
+    if (!block) return
+    this.context.addMessage({ role: 'user', content: block })
+    this.touchedFiles.clear()
+  }
+
   /**
    * Drain pending background task notifications.
    * Call this after tool execution to surface completed/failed background agent results.
@@ -351,6 +383,9 @@ export class QueryEngine {
       })
     }
 
+    // Inject path-scoped rules for touched files
+    this.injectRules()
+
     // Drain task notifications after tool execution
     for (const chunk of this.drainTaskNotifications()) {
       yield chunk
@@ -633,6 +668,9 @@ export class QueryEngine {
         backgroundAgentRegistry: getBackgroundAgentRegistry(),
       })
 
+      // Track touched files for rules matching
+      this.trackTouchedFile(name, effectiveParams)
+
       // Run PostToolUse hooks
       if (this.hookEngine) {
         await this.hookEngine.executePostToolUse(name, effectiveParams, result, 'session-1')

package/src/core/output-styles.ts

@@ -0,0 +1,95 @@
+/**
+ * OutputStylesLoader — loads custom response persona styles from .mipham/output-styles/.
+ *
+ * Each .md file in the directory is a named style. The active style's content
+ * is injected into the system prompt to shape the AI's tone and communication style.
+ *
+ * Usage:
+ *   const loader = new OutputStylesLoader(cwd)
+ *   loader.list()               // ['concise', 'academic', ...]
+ *   loader.get('concise')       // style content or undefined
+ *   loader.setActive('concise') // switch active style
+ *   loader.getActiveContent()   // active style content (for system prompt)
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, basename, extname } from 'node:path'
+
+export class OutputStylesLoader {
+  private stylesDir: string
+  private activeStyle: string | null = null
+
+  constructor(cwd: string) {
+    this.stylesDir = join(cwd, '.mipham', 'output-styles')
+  }
+
+  /**
+   * List all available style names (filename without .md extension).
+   */
+  list(): string[] {
+    if (!existsSync(this.stylesDir)) return []
+    try {
+      return readdirSync(this.stylesDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => basename(f, extname(f)))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Get the content of a named style. Returns undefined if not found.
+   */
+  get(name: string): string | undefined {
+    if (!existsSync(this.stylesDir)) return undefined
+    const filepath = join(this.stylesDir, `${name}.md`)
+    if (!existsSync(filepath)) return undefined
+    try {
+      return readFileSync(filepath, 'utf-8').trim()
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Set the active output style.
+   */
+  setActive(name: string): boolean {
+    const content = this.get(name)
+    if (!content) return false
+    this.activeStyle = name
+    return true
+  }
+
+  /**
+   * Clear the active output style (revert to default personality).
+   */
+  clearActive(): void {
+    this.activeStyle = null
+  }
+
+  /**
+   * Get the active style name (null if none selected).
+   */
+  getActiveName(): string | null {
+    return this.activeStyle
+  }
+
+  /**
+   * Get the active style content for system prompt injection.
+   * Returns empty string if no style is active.
+   */
+  getActiveContent(): string {
+    if (!this.activeStyle) return ''
+    const content = this.get(this.activeStyle)
+    if (!content) return ''
+    return [
+      `[Output Style: ${this.activeStyle}]`,
+      'Adopt the following communication style in all your responses:',
+      '',
+      content,
+      '',
+      '---',
+    ].join('\n')
+  }
+}

package/src/core/rules-loader.ts

@@ -0,0 +1,175 @@
+/**
+ * RulesLoader — path-scoped rules from .mipham/rules/.
+ *
+ * Rules are markdown files with YAML frontmatter. They are injected into
+ * the conversation when the AI touches matching files.
+ *
+ * Directory structure:
+ *   .mipham/rules/
+ *     always.md        — always loaded (no paths filter)
+ *     typescript.md    — loaded when touching *.ts files
+ *     security.md      — loaded when touching auth/ or crypto/ paths
+ *
+ * Frontmatter:
+ *   ---
+ *   paths: "apps/cli/src/**\/*.ts"
+ *   description: TypeScript coding standards
+ *   ---
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+interface RuleFile {
+  name: string
+  paths: string[] // glob patterns, empty = always loaded
+  description: string
+  content: string
+}
+
+export class RulesLoader {
+  private rules: RuleFile[] = []
+  private rulesDir: string
+
+  constructor(cwd: string) {
+    this.rulesDir = join(cwd, '.mipham', 'rules')
+  }
+
+  /**
+   * Load all rules from .mipham/rules/. Call once at startup.
+   */
+  load(): void {
+    this.rules = []
+    if (!existsSync(this.rulesDir)) return
+
+    try {
+      const files = readdirSync(this.rulesDir).filter((f) => f.endsWith('.md'))
+      for (const file of files) {
+        const filepath = join(this.rulesDir, file)
+        try {
+          const raw = readFileSync(filepath, 'utf-8')
+          const { paths, description, content } = this.parseRule(raw, file)
+          this.rules.push({ name: file.replace(/\.md$/, ''), paths, description, content })
+        } catch {
+          // Skip unparseable files
+        }
+      }
+    } catch {
+      // Directory read error — rules unavailable
+    }
+  }
+
+  /**
+   * Get rules that match the given file paths.
+   * Rules with no paths filter ("always") are always included.
+   */
+  getMatchingRules(touchedFiles: string[]): RuleFile[] {
+    const matched: RuleFile[] = []
+
+    for (const rule of this.rules) {
+      // Always rules — no paths filter
+      if (rule.paths.length === 0) {
+        matched.push(rule)
+        continue
+      }
+
+      // Check if any touched file matches any rule path pattern
+      for (const file of touchedFiles) {
+        for (const pattern of rule.paths) {
+          if (this.matchPath(file, pattern)) {
+            matched.push(rule)
+            // Break inner loops — rule already matched
+            break
+          }
+        }
+        if (matched.includes(rule)) break
+      }
+    }
+
+    return matched
+  }
+
+  /**
+   * Build a context block to inject into the conversation.
+   */
+  buildContextBlock(touchedFiles: string[]): string {
+    const matched = this.getMatchingRules(touchedFiles)
+    if (matched.length === 0) return ''
+
+    const blocks = matched.map(
+      (r) => `[Rule: ${r.name}]${r.description ? ` — ${r.description}` : ''}\n${r.content}`,
+    )
+    return `\n<!-- Path-scoped rules matching: ${touchedFiles.join(', ')} -->\n${blocks.join('\n\n')}\n`
+  }
+
+  /**
+   * Count loaded rules.
+   */
+  count(): number {
+    return this.rules.length
+  }
+
+  /**
+   * List loaded rule names.
+   */
+  list(): string[] {
+    return this.rules.map((r) => r.name)
+  }
+
+  /**
+   * Simple glob matching. Supports **, *, and exact file matching.
+   * Returns true if file matches pattern.
+   */
+  private matchPath(file: string, pattern: string): boolean {
+    // Convert glob pattern to regex
+    let regexStr = pattern
+      .replace(/\./g, '\\.')
+      .replace(/\*\*/g, '<<GLOBSTAR>>')
+      .replace(/\*/g, '[^/]*')
+      .replace(/<<GLOBSTAR>>/g, '.*')
+
+    // If pattern doesn't start with ** or *, anchor to be a suffix match
+    if (!pattern.startsWith('**') && !pattern.startsWith('*')) {
+      regexStr = regexStr + '$'
+    }
+
+    try {
+      return new RegExp(regexStr).test(file)
+    } catch {
+      // Invalid pattern — fallback to simple includes
+      return file.includes(pattern.replace(/\*\*/g, '').replace(/\*/g, ''))
+    }
+  }
+
+  /**
+   * Parse a rule file — extract frontmatter and body.
+   */
+  private parseRule(
+    raw: string,
+    filename: string,
+  ): { paths: string[]; description: string; content: string } {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+    if (!match) {
+      return { paths: [], description: '', content: raw.trim() }
+    }
+
+    const frontmatter = match[1] || ''
+    const body = (match[2] || '').trim()
+
+    const paths: string[] = []
+    let description = ''
+
+    for (const line of frontmatter.split('\n')) {
+      const pathMatch = line.match(/^paths:\s*"(.+)"$/)
+      if (pathMatch) {
+        pathMatch[1]!.split(',').forEach((p) => paths.push(p.trim()))
+      }
+      const descMatch = line.match(/^description:\s*(.+)$/)
+      if (descMatch) {
+        description = descMatch[1]!.trim()
+      }
+    }
+
+    return { paths, description, content: body }
+  }
+}

package/src/mcp/client.ts

@@ -151,6 +151,15 @@ export class McpClient {
     return this.connections.get(name)?.tools || []
   }
 
+  /** List all currently connected MCP server names. */
+  getConnectedServers(): string[] {
+    const names: string[] = []
+    for (const [name, conn] of this.connections) {
+      if (conn.status === 'connected') names.push(name)
+    }
+    return names
+  }
+
   async callTool(
     serverName: string,
     toolName: string,

package/src/tools/index.ts

@@ -20,6 +20,7 @@ import { webFetchTool } from './network/web-fetch'
 import { webSearchTool } from './network/web-search'
 import { configTool } from './system/config'
 import { mcpTool } from './system/mcp'
+import { toolSearchTool } from './system/tool-search'
 import { artifactTool } from './artifact/artifact'
 import { reportFindingsTool } from './agent/report-findings'
 import { sendMessageTool } from './agent/send-message'
@@ -134,6 +135,7 @@ export function createToolRegistry(): Map<string, ToolDefinition> {
     // System tools
     withValidation(configTool),
     withValidation(mcpTool),
+    withValidation(toolSearchTool),
     // Artifact tools
     withValidation(artifactTool),
     // Computer Use tools

package/src/tools/system/tool-search.ts

@@ -0,0 +1,143 @@
+/**
+ * ToolSearch — search MCP server tools by name or description.
+ *
+ * Instead of loading all MCP tool definitions into the context upfront,
+ * the AI can call ToolSearch to discover relevant tools on demand.
+ * This saves ~85% of context tokens for large MCP servers (50-100 tools).
+ */
+
+import type { ToolDefinition } from '../../shared/index.ts'
+import { McpClient } from '../../mcp/client'
+
+export const toolSearchTool: ToolDefinition = {
+  name: 'ToolSearch',
+  description:
+    'Search available MCP server tools by name or description. ' +
+    'Use this to discover tools on demand instead of loading all tool definitions into context. ' +
+    'Returns matching tool names with their server and description.',
+  category: 'system',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description:
+          'Search query — matches against tool names and descriptions. Leave empty to list all available MCP tools.',
+      },
+      server: {
+        type: 'string',
+        description: 'Optional: limit search to a specific MCP server name.',
+      },
+      limit: {
+        type: 'integer',
+        description: 'Max results to return (default: 20).',
+      },
+    },
+    required: [],
+  },
+  async execute(params, _ctx) {
+    const query = ((params.query as string) || '').toLowerCase()
+    const serverFilter = (params.server as string) || ''
+    const limit = (params.limit as number) || 20
+
+    const client = McpClient.getInstance()
+    const connectedServers = client.getConnectedServers()
+
+    if (connectedServers.length === 0) {
+      return {
+        success: true,
+        content:
+          '── MCP Tool Search ──\n\n' +
+          'No MCP servers connected.\n\n' +
+          'Connect MCP servers in .mcp.json or via /mcp add <name> <url>.',
+      }
+    }
+
+    // Filter by server if specified
+    const servers = serverFilter
+      ? connectedServers.filter((s) => s.toLowerCase().includes(serverFilter))
+      : connectedServers
+
+    if (serverFilter && servers.length === 0) {
+      return {
+        success: true,
+        content:
+          `── MCP Tool Search ──\n\n` +
+          `No connected server matching "${serverFilter}".\n\n` +
+          `Connected servers: ${connectedServers.join(', ')}`,
+      }
+    }
+
+    // Collect matching tools
+    interface Match {
+      server: string
+      tool: string
+      description: string
+    }
+
+    const matches: Match[] = []
+
+    for (const serverName of servers) {
+      try {
+        const tools = client.getTools(serverName)
+        for (const tool of tools) {
+          const nameMatch = !query || tool.name.toLowerCase().includes(query)
+          const descMatch = !query || (tool.description || '').toLowerCase().includes(query)
+          if (nameMatch || descMatch) {
+            matches.push({
+              server: serverName,
+              tool: tool.name,
+              description: (tool.description || '').slice(0, 120),
+            })
+          }
+        }
+      } catch {
+        // Server disconnected mid-search — skip
+      }
+    }
+
+    if (matches.length === 0) {
+      return {
+        success: true,
+        content:
+          `── MCP Tool Search ──\n\n` +
+          `No tools matching "${query}" across ${servers.length} server(s).\n\n` +
+          `Try a different query, or omit the query to list all tools.`,
+      }
+    }
+
+    // Truncate to limit
+    const limited = matches.slice(0, limit)
+
+    const lines: string[] = [
+      `── MCP Tool Search ──`,
+      '',
+      `${limited.length} of ${matches.length} matching tool(s) across ${servers.length} server(s):`,
+      '',
+    ]
+
+    // Group by server
+    const byServer = new Map<string, Match[]>()
+    for (const m of limited) {
+      const list = byServer.get(m.server) || []
+      list.push(m)
+      byServer.set(m.server, list)
+    }
+
+    for (const [server, tools] of byServer) {
+      lines.push(`  ${server} (${tools.length}):`)
+      for (const t of tools) {
+        const desc = t.description ? ` — ${t.description}` : ''
+        lines.push(`    mcp__${server.replace(/[^a-z0-9-]/g, '_')}__${t.tool}${desc}`)
+      }
+      lines.push('')
+    }
+
+    if (matches.length > limit) {
+      lines.push(`... and ${matches.length - limit} more. Use "query" to narrow results.`)
+    }
+
+    return { success: true, content: lines.join('\n') }
+  },
+}

package/src/ui/commands.ts

@@ -3182,64 +3182,183 @@ Full changelog: https://mipham.ai/code/releases`,
 // IDE — IDE integration guide
 // ═══════════════════════════════════════════════════════════════
 
-const ideCmd: CommandHandler = () => ({
-  content: `── IDE Integration ──
-
-VS Code:
-  Install the Mipham Code extension from the VS Code marketplace.
-  • Open Command Palette (Cmd+Shift+P)
-  • Search "Mipham Code: Start"
-  • The terminal panel opens with Mipham Code loaded
+const ideCmd: CommandHandler = async (_ctx) => {
+  const { mkdirSync, writeFileSync, existsSync } = await import('node:fs')
+  const { join } = await import('node:path')
 
-  Or manually: add to .vscode/settings.json
-  {
-    "terminal.integrated.profiles.osx": {
-      "mipham": { "path": "bun", "args": ["run", "mipham"] }
-    }
-  }
+  const cwd = process.cwd()
+  const vscodeDir = join(cwd, '.vscode')
+  mkdirSync(vscodeDir, { recursive: true })
 
-JetBrains (IntelliJ / WebStorm / PyCharm):
-  • Settings → Tools → Terminal → Shell path
-  • Set to: bun run ~/path/to/mipham-code/apps/cli/bin/mipham
+  const files: string[] = []
 
-Terminal (any):
-  alias mipham='cd your-project && bun run path/to/mipham'
+  // ── Detect bun path ──
+  let bunPath = '/opt/homebrew/bin/bun'
+  try {
+    const { execSync } = await import('node:child_process')
+    const detected = execSync('which bun 2>/dev/null || echo /opt/homebrew/bin/bun', {
+      encoding: 'utf-8',
+    }).trim()
+    if (detected) bunPath = detected
+  } catch {
+    // Use default
+  }
+
+  // ── settings.json: terminal profile ──
+  const settingsPath = join(vscodeDir, 'settings.json')
+  const settings = {
+    'terminal.integrated.profiles.osx': {
+      mipham: {
+        path: bunPath,
+        args: ['run', 'mipham'],
+        cwd: '${workspaceFolder}',
+      },
+    },
+  }
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8')
+  files.push('.vscode/settings.json')
+
+  // ── keybindings.json: Cmd+Esc launch ──
+  const keybindingsPath = join(vscodeDir, 'keybindings.json')
+  const keybindings = [
+    {
+      key: 'cmd+escape',
+      command: 'workbench.action.terminal.focus',
+      when: 'terminalProcessSupported',
+    },
+    {
+      key: 'cmd+shift+m',
+      command: 'workbench.action.terminal.new',
+    },
+  ]
+  writeFileSync(keybindingsPath, JSON.stringify(keybindings, null, 2) + '\n', 'utf-8')
+  files.push('.vscode/keybindings.json')
 
-Or install globally: ${NPM_INSTALL_COMMAND}
+  // ── extensions.json: recommended ──
+  const extensionsPath = join(vscodeDir, 'extensions.json')
+  const extensions = {
+    recommendations: ['miphamai.mipham-code'],
+  }
+  writeFileSync(extensionsPath, JSON.stringify(extensions, null, 2) + '\n', 'utf-8')
+  files.push('.vscode/extensions.json')
 
-Coming soon: dedicated VS Code & JetBrains plugin extensions.`,
-})
+  return {
+    content: [
+      '── VS Code Integration ──',
+      '',
+      `Generated in ${vscodeDir}:`,
+      ...files.map((f) => `  ✅ ${f}`),
+      '',
+      'What was configured:',
+      '  • Terminal profile "mipham" — opens Mipham Code in integrated terminal',
+      '  • Keyboard shortcut Cmd+Esc — focus terminal',
+      '  • Cmd+Shift+M — new terminal',
+      '',
+      'To use:',
+      '  1. Restart VS Code (or reload window: Cmd+Shift+P → Reload Window)',
+      '  2. Open terminal: Ctrl+` or Cmd+Esc',
+      '  3. Select "mipham" profile from the terminal dropdown',
+      '',
+      'Install the VS Code extension for full integration:',
+      `  code --install-extension miphamai.mipham-code`,
+      '',
+      'JetBrains: Settings → Tools → Terminal → Shell path → bun run mipham',
+    ].join('\n'),
+  }
+}
 
 // ═══════════════════════════════════════════════════════════════
 // Terminal Setup — shell integration guide
 // ═══════════════════════════════════════════════════════════════
 
-const terminalSetupCmd: CommandHandler = () => ({
-  content: `── Terminal Setup ──
-
-Install globally:
-  ${NPM_INSTALL_COMMAND}
-  mipham
-
-One-liner install:
-  curl -fsSL https://mipham.ai/install.sh | bash
+const terminalSetupCmd: CommandHandler = async () => {
+  const { writeFileSync, appendFileSync, existsSync, mkdirSync } = await import('node:fs')
+  const { join } = await import('node:path')
+  const { homedir } = await import('node:os')
 
-Add to shell profile (~/.zshrc or ~/.bashrc):
-  alias mipham='bun run ~/path/to/mipham-code/apps/cli/bin/mipham'
+  const home = homedir()
+  const lines: string[] = ['── Terminal Setup ──', '']
+
+  // ── 1. Generate standalone shell setup script ──
+  const miphamDir = join(home, '.mipham')
+  mkdirSync(miphamDir, { recursive: true })
+
+  const shellScript = join(miphamDir, 'shell-setup.sh')
+  const shellContent = [
+    '#!/bin/bash',
+    '# Mipham Code — Shell Integration',
+    '# Source this file in your shell profile:',
+    '#   source ~/.mipham/shell-setup.sh',
+    '',
+    `export MIPHAM_HOME="${home}/.mipham"`,
+    '',
+    '# Alias: launch Mipham Code in current directory',
+    `alias mipham='cd $(pwd) && ${NPM_INSTALL_COMMAND} > /dev/null 2>&1; mipham'`,
+    '',
+    '# Or use the local development version:',
+    '# alias mipham="bun run /path/to/mipham-code/apps/cli/bin/mipham"',
+    '',
+    '# Auto-detect provider from config',
+    'if [ -f ~/.mipham/config.yml ]; then',
+    '  export MIPHAM_PROVIDER=$(grep "defaultProvider:" ~/.mipham/config.yml | awk "{print \$2}")',
+    'fi',
+  ].join('\n')
+  writeFileSync(shellScript, shellContent + '\n', 'utf-8')
+  lines.push(`  ✅ Generated: ${shellScript}`)
+
+  // ── 2. Append to shell profile ──
+  const shell = process.env.SHELL || '/bin/zsh'
+  const profileName = shell.includes('zsh') ? '.zshrc' : '.bashrc'
+  const profilePath = join(home, profileName)
+  const sourceLine = `\n# Mipham Code shell integration\n[ -f ~/.mipham/shell-setup.sh ] && source ~/.mipham/shell-setup.sh\n`
 
-  # Or with a specific provider/model:
-  alias mipham='mipham --provider anthropic --model claude-opus-4-8'
+  try {
+    const existing = existsSync(profilePath)
+      ? require('node:fs').readFileSync(profilePath, 'utf-8')
+      : ''
+    if (existing.includes('shell-setup.sh')) {
+      lines.push(`  ⏭  ${profileName} already has Mipham Code integration`)
+    } else {
+      appendFileSync(profilePath, sourceLine, 'utf-8')
+      lines.push(`  ✅ Added to ~/${profileName}`)
+    }
+  } catch {
+    lines.push(`  ⚠️  Could not update ~/${profileName}. Add manually:`)
+    lines.push(`     echo '${sourceLine.trim()}' >> ~/${profileName}`)
+  }
 
-Upgrade:
-  curl -fsSL https://mipham.ai/install.sh | bash
-  # or:   ${NPM_UPDATE_COMMAND}
+  // ── 3. Global install check ──
+  lines.push('')
+  lines.push('── Installation ──')
+  try {
+    const { execSync } = await import('node:child_process')
+    const miphamPath = execSync('which mipham 2>/dev/null || echo ""', { encoding: 'utf-8' }).trim()
+    if (miphamPath) {
+      lines.push(`  ✅ mipham found at: ${miphamPath}`)
+      const version = execSync('mipham --version 2>/dev/null || echo "unknown"', {
+        encoding: 'utf-8',
+      }).trim()
+      lines.push(`  📦 Version: ${version}`)
+    } else {
+      lines.push(`  ⚠️  mipham not in PATH. Install globally:`)
+      lines.push(`     ${NPM_INSTALL_COMMAND}`)
+      lines.push(`     or: curl -fsSL https://mipham.ai/install.sh | bash`)
+    }
+  } catch {
+    lines.push(`  💡 Install: ${NPM_INSTALL_COMMAND}`)
+  }
 
-Verify installation:
-  mipham --version
-  mipham --help
+  // ── 4. Verify ──
+  lines.push('')
+  lines.push('── Next Steps ──')
+  lines.push('  1. Restart your terminal or run: source ~/.mipham/shell-setup.sh')
+  lines.push('  2. Run: mipham --version')
+  lines.push('  3. Start coding: cd your-project && mipham')
+  lines.push('')
+  lines.push(`Works with: Zsh, Bash. Shell: ${shell}`)
 
-Works with: Bash, Zsh, Fish, PowerShell, Windows Terminal`,
-})
+  return { content: lines.join('\n') }
+}
 
 // ═══════════════════════════════════════════════════════════════
 // Phase 4 — MCP Server Management