@miphamai/cli 0.3.0 → 0.4.0

package/src/providers/openai-compat.ts

@@ -1,10 +1,4 @@
-import type {
-  ProviderConfig,
-  ModelInfo,
-  Message,
-  StreamChunk,
-  ContentBlock,
-} from '../shared/index.ts'
+import type { ProviderConfig, ModelInfo, Message, StreamChunk } from '../shared/index.ts'
 import type { ProviderInstance, ChatRequest } from './registry'
 import { fetchWithRetry } from './fetch-utils'
 
@@ -49,10 +43,7 @@ export class OpenAICompatProvider implements ProviderInstance {
     let buffer = ''
 
     // Track incremental tool calls across streaming deltas
-    const pendingToolCalls = new Map<
-      number,
-      { id: string; name: string; arguments: string }
-    >()
+    const pendingToolCalls = new Map<number, { id: string; name: string; arguments: string }>()
 
     while (true) {
       const { done, value } = await reader.read()

package/src/shared/constants.ts

@@ -361,8 +361,15 @@ export const PROTOCOL_LABELS: Record<string, string> = {
   custom: 'Custom Protocol',
 }
 
-export const TOOL_CATEGORIES = ['file', 'exec', 'agent', 'network', 'system'] as const
+export const TOOL_CATEGORIES = ['file', 'exec', 'agent', 'network', 'system', 'artifact'] as const
 export const CONFIG_FILE_NAME = 'config.yml'
 export const MIPHAM_DIR = '.mipham'
 export const USER_CONFIG_DIR = '.mipham'
 export const MEMORY_DIR = 'memory'
+
+// ── Artifact Constants ──
+export const ARTIFACTS_DIR = 'artifacts'
+export const ARTIFACT_PORT = 9876
+export const ARTIFACT_MAX_PORT_TRIES = 10
+export const ARTIFACT_MAX_SIZE = 5 * 1024 * 1024 // 5MB
+export const ARTIFACT_ALLOWED_EXTENSIONS = ['.html', '.svg']

package/src/shared/types.ts

@@ -50,7 +50,7 @@ export interface Message {
 
 // ── Tool Types ──
 export type ToolPermission = 'auto' | 'ask' | 'bypass'
-export type ToolCategory = 'file' | 'exec' | 'agent' | 'network' | 'system'
+export type ToolCategory = 'file' | 'exec' | 'agent' | 'network' | 'system' | 'artifact'
 
 export interface ToolContext {
   cwd: string
@@ -59,6 +59,26 @@ export interface ToolContext {
   model: string
   skillsLoader?: import('../skills/loader').SkillsLoader
   registry?: import('../providers/registry').ProviderRegistry
+  artifactServer?: import('../artifacts/server').ArtifactServer
+}
+
+// ── Artifact Types ──
+export interface ArtifactEntry {
+  name: string
+  path: string
+  url: string
+  size: number
+  type: 'html' | 'svg'
+  createdAt: string
+  sessionId: string
+  versions?: string[] // version tags e.g. ['v1', 'v2']
+  versionCount?: number
+}
+
+export interface ArtifactManifest {
+  version: 1
+  artifacts: ArtifactEntry[]
+  port?: number
 }
 
 export interface ToolResult {

package/src/skills/loader.ts

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
-import { join, extname } from 'node:path'
+import { join } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { SkillDefinition } from '../shared/index.ts'
 
@@ -84,7 +84,7 @@ export class SkillsLoader {
   private tryLoad(path: string, type: 'standard' | 'mipham'): void {
     try {
       const raw = readFileSync(path, 'utf-8')
-      const { data, content } = parseFrontmatter(raw)
+      const { data } = parseFrontmatter(raw)
 
       const skill: SkillDefinition = {
         name: (data.name as string) || this.nameFromPath(path),

package/src/tools/artifact/artifact.ts

@@ -0,0 +1,144 @@
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolDefinition } from '../../shared/index.ts'
+import { ARTIFACTS_DIR, ARTIFACT_MAX_SIZE } from '../../shared/constants'
+import { addToManifest, readManifest, archiveVersion } from '../../artifacts/manifest'
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
+
+export const artifactTool: ToolDefinition = {
+  name: 'Artifact',
+  description:
+    'Create an interactive HTML or SVG artifact that opens in the browser. Use for dashboards, visualizations, reports, and interactive demos. Content must be self-contained — no external CDN references.',
+  category: 'artifact',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Short kebab-case name (e.g. "user-dashboard", "pipeline-diagram")',
+      },
+      type: {
+        type: 'string',
+        enum: ['html', 'svg'],
+        description: 'Artifact type',
+      },
+      content: {
+        type: 'string',
+        description: 'Full HTML or SVG content (self-contained, inline CSS/JS only)',
+      },
+    },
+    required: ['name', 'type', 'content'],
+  },
+  async execute(params, ctx) {
+    const name = params.name as string
+    const type = params.type as string
+    const content = params.content as string
+
+    // Validate name
+    if (!NAME_PATTERN.test(name) || name.length < 3) {
+      return {
+        success: false,
+        content: '',
+        error:
+          `Invalid artifact name "${name}". Use kebab-case (letters, numbers, hyphens), ` +
+          `at least 3 characters, e.g. "my-dashboard".`,
+      }
+    }
+
+    // Validate size
+    const size = Buffer.byteLength(content, 'utf-8')
+    if (size > ARTIFACT_MAX_SIZE) {
+      return {
+        success: false,
+        content: '',
+        error: `Content size ${(size / 1_048_576).toFixed(1)}MB exceeds ${ARTIFACT_MAX_SIZE / 1_048_576}MB limit.`,
+      }
+    }
+
+    // Determine output paths
+    const baseDir = join(ctx.cwd, ARTIFACTS_DIR)
+    const sessionDir = join(baseDir, ctx.sessionId)
+    mkdirSync(sessionDir, { recursive: true })
+
+    const ext = type === 'svg' ? '.svg' : '.html'
+    const filename = `${name}${ext}`
+    const filepath = join(sessionDir, filename)
+
+    // Start server if not running
+    let port: number | undefined
+    if (ctx.artifactServer && !ctx.artifactServer.isRunning()) {
+      port = await ctx.artifactServer.start()
+    } else if (ctx.artifactServer) {
+      port = ctx.artifactServer.getPort()
+    }
+
+    // Archive previous version if this artifact already exists
+    let archivedVersion: string | undefined
+    const isUpdate = existsSync(filepath)
+    if (isUpdate) {
+      const manifest = readManifest(baseDir)
+      const existing = manifest.artifacts.find(
+        (a) => a.name === name && a.sessionId === ctx.sessionId,
+      )
+      if (existing) {
+        archivedVersion = archiveVersion(baseDir, existing)
+      }
+    }
+
+    // Write artifact
+    writeFileSync(filepath, content, 'utf-8')
+
+    // Build URL and manifest entry
+    const url = port
+      ? `http://localhost:${port}/${ctx.sessionId}/${filename}`
+      : `file://${filepath}`
+
+    // Preserve existing version count
+    const manifestPre = readManifest(baseDir)
+    const prev = manifestPre.artifacts.find((a) => a.name === name && a.sessionId === ctx.sessionId)
+    const versionCount = prev?.versionCount || (isUpdate ? 1 : undefined)
+
+    addToManifest(
+      baseDir,
+      {
+        name,
+        path: filepath,
+        url,
+        size,
+        type: type as 'html' | 'svg',
+        createdAt: new Date().toISOString(),
+        sessionId: ctx.sessionId,
+        versions: prev?.versions,
+        versionCount,
+      },
+      port,
+    )
+
+    // Notify SSE clients to refresh Gallery
+    if (ctx.artifactServer) {
+      ctx.artifactServer.notifyReload()
+    }
+
+    const galleryUrl = port ? `http://localhost:${port}` : undefined
+    const versionLine = archivedVersion ? `   Prev archived as: ${archivedVersion}` : ''
+    const galleryLine = galleryUrl ? `Gallery: ${galleryUrl}` : ''
+
+    return {
+      success: true,
+      content: [
+        `✓ Artifact "${name}" saved${isUpdate ? ' (updated)' : ''}.`,
+        `   URL:  ${url}`,
+        `   Size: ${size.toLocaleString()} bytes`,
+        versionLine,
+        galleryLine,
+        '',
+        `Open in browser: /artifact open ${name}`,
+        `List all:         /artifact list`,
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    }
+  },
+}

package/src/tools/index.ts

@@ -15,6 +15,7 @@ import { webFetchTool } from './network/web-fetch'
 import { webSearchTool } from './network/web-search'
 import { configTool } from './system/config'
 import { mcpTool } from './system/mcp'
+import { artifactTool } from './artifact/artifact'
 
 /**
  * Validate tool parameters against the tool's JSON Schema definition.
@@ -116,6 +117,8 @@ export function createToolRegistry(): Map<string, ToolDefinition> {
     // System tools
     withValidation(configTool),
     withValidation(mcpTool),
+    // Artifact tools
+    withValidation(artifactTool),
   ]
 
   const map = new Map<string, ToolDefinition>()

package/src/ui/app.tsx

@@ -58,7 +58,7 @@ export function App({
   config,
   initialProvider,
   initialModel,
-  lang,
+  lang: _lang,
   skillsLoader,
 }: AppProps) {
   const [messages, setMessages] = useState<ChatMessage[]>([])
@@ -78,7 +78,10 @@ export function App({
 
   // Agent elapsed timer
   React.useEffect(() => {
-    if (!agentProgress) { setAgentElapsed(0); return }
+    if (!agentProgress) {
+      setAgentElapsed(0)
+      return
+    }
     const interval = setInterval(() => {
       setAgentElapsed(Math.floor((Date.now() - agentProgress.startTime) / 1000))
     }, 1000)
@@ -216,8 +219,10 @@ export function App({
             if (isAgent) {
               setAgentProgress({
                 name: (chunk.toolUse.input.subagent_type as string) || 'General-purpose',
-                description: (chunk.toolUse.input.description as string) ||
-                  (chunk.toolUse.input.prompt as string) || '',
+                description:
+                  (chunk.toolUse.input.description as string) ||
+                  (chunk.toolUse.input.prompt as string) ||
+                  '',
                 startTime: Date.now(),
               })
             }
@@ -379,8 +384,7 @@ export function App({
       {agentProgress && (
         <Box flexDirection="column" marginY={1}>
           <Text color="cyan" bold>
-            ⏺ {agentProgress.name}{' '}
-            <Text color="yellow">{agentElapsed}s</Text>
+            ⏺ {agentProgress.name} <Text color="yellow">{agentElapsed}s</Text>
           </Text>
           <Text dimColor>
             {agentProgress.description.length > 100

package/src/ui/chat.tsx

@@ -39,8 +39,8 @@ export function ChatPanel({ messages, focusMode }: ChatPanelProps) {
           </Box>
           <Box marginTop={1}>
             <Text dimColor>
-              Tip: Use <Text color="yellow">/clear</Text> to start fresh when switching topics
-              and free up context
+              Tip: Use <Text color="yellow">/clear</Text> to start fresh when switching topics and
+              free up context
             </Text>
           </Box>
         </Box>
@@ -50,8 +50,7 @@ export function ChatPanel({ messages, focusMode }: ChatPanelProps) {
           {msg.toolMeta ? (
             <Box flexDirection="column">
               <Text color="yellow">
-                {msg.toolMeta.collapsed ? '⏺' : '⏺ ▼'}{' '}
-                {msg.toolMeta.name}
+                {msg.toolMeta.collapsed ? '⏺' : '⏺ ▼'} {msg.toolMeta.name}
               </Text>
               <Text dimColor>{msg.content}</Text>
             </Box>
@@ -61,7 +60,12 @@ export function ChatPanel({ messages, focusMode }: ChatPanelProps) {
                 bold
                 color={msg.role === 'user' ? 'green' : msg.role === 'system' ? 'yellow' : 'blue'}
               >
-                {msg.role === 'user' ? '▸ You' : msg.role === 'assistant' ? 'Mipham Code' : '⚠ System'}:
+                {msg.role === 'user'
+                  ? '▸ You'
+                  : msg.role === 'assistant'
+                    ? 'Mipham Code'
+                    : '⚠ System'}
+                :
               </Text>
               <Text>{msg.content}</Text>
             </>

package/src/ui/commands.ts

@@ -8,14 +8,7 @@ import type { QueryEngine } from '../core/engine'
 import type { MiphamConfig } from '../shared/index.ts'
 import type { SkillsLoader } from '../skills/loader'
 import { McpClient } from '../mcp/client'
-import {
-  PACKAGE_NAME,
-  NPM_INSTALL_COMMAND,
-  NPM_UPDATE_COMMAND,
-  NPM_URL,
-  PRODUCT_URL_INTERNATIONAL,
-  PRODUCT_URL_CHINA,
-} from '@mipham/shared'
+import { NPM_INSTALL_COMMAND, NPM_UPDATE_COMMAND } from '@mipham/shared'
 
 export interface CommandContext {
   engine: QueryEngine
@@ -421,7 +414,6 @@ const renameCmd: CommandHandler = (ctx, args) => {
 const goalCmd: CommandHandler = (ctx, args) => {
   const goal = args.join(' ')
   if (!goal.trim()) {
-    const c = ctx.engine.getContext()
     return {
       content: `Usage: /goal <statement>\n\nSet a session-level completion condition. Mipham Code will track progress toward this goal.\n\nExample: /goal Fix all TypeScript errors and make tests pass`,
     }
@@ -867,7 +859,7 @@ const doctorCmd: CommandHandler = async (ctx) => {
 // ═══════════════════════════════════════════════════════════════
 
 const exportCmd: CommandHandler = async (ctx) => {
-  const { writeFileSync, existsSync } = await import('node:fs')
+  const { writeFileSync } = await import('node:fs')
   const { join } = await import('node:path')
 
   const cwd = process.cwd()
@@ -2128,6 +2120,87 @@ Mipham Code includes 4 agent-type tools for structured workflows:
   Use /tools to see all 16 tools, including the 4 agent tools.`,
 })
 
+// ═══════════════════════════════════════════════════════════════
+// Artifacts
+// ═══════════════════════════════════════════════════════════════
+
+async function openBrowser(url: string): Promise<void> {
+  const cmd =
+    process.platform === 'darwin'
+      ? `open "${url}"`
+      : process.platform === 'win32'
+        ? `start "" "${url}"`
+        : `xdg-open "${url}"`
+  const { exec } = await import('node:child_process')
+  exec(cmd, () => {
+    /* fire-and-forget */
+  })
+}
+
+const artifactOpenCmd: CommandHandler = async (ctx, args) => {
+  const name = args[0]
+  if (!name) {
+    return { content: 'Usage: /artifact open <name>\nExample: /artifact open dashboard' }
+  }
+
+  const sessionId = 'session-1' // default session
+  const port = 9876
+  const ext = name.endsWith('.svg') ? '' : '.html'
+  const url = `http://localhost:${port}/${sessionId}/${name}${ext}`
+
+  try {
+    await openBrowser(url)
+    return { content: `✓ Opening artifact "${name}" in browser...\n   ${url}` }
+  } catch (err) {
+    return { content: `✗ Failed to open browser: ${String(err)}\n   URL: ${url}` }
+  }
+}
+
+const artifactListCmd: CommandHandler = async (_ctx, _args) => {
+  const { getSessionArtifacts } = await import('../artifacts/manifest')
+  const { join } = await import('node:path')
+  const { ARTIFACTS_DIR } = await import('../shared/constants')
+
+  const dir = join(process.cwd(), ARTIFACTS_DIR)
+  const entries = getSessionArtifacts(dir, 'session-1')
+
+  if (entries.length === 0) {
+    return {
+      content: 'No artifacts created yet. Ask the AI to generate one with the Artifact tool.',
+    }
+  }
+
+  const lines = ['── Artifacts ──', '']
+  for (const e of entries) {
+    const ver = e.versions && e.versions.length > 1 ? ` v${e.versions.length}` : ''
+    lines.push(
+      `  ${e.name.padEnd(24)} ${(e.type + ver).padEnd(8)} ${(e.size / 1024).toFixed(1).padStart(8)}KB  ${e.createdAt.slice(0, 16).replace('T', ' ')}`,
+    )
+  }
+  lines.push('', `  ${entries.length} artifact(s) — /artifact open <name> to view`)
+  lines.push(`  Gallery: http://localhost:9876`)
+
+  return { content: lines.join('\n') }
+}
+
+const artifactServerCmd: CommandHandler = async (_ctx, _args) => {
+  const url = 'http://localhost:9876'
+  return {
+    content: `── Artifact Server ──\n\n  URL:  ${url}\n  Port: 9876\n\nArtifacts are served locally. No external network access.`,
+  }
+}
+
+const artifactBaseCmd: CommandHandler = (ctx, args) => {
+  const sub = args[0]
+  if (sub === 'open') return artifactOpenCmd(ctx, args.slice(1))
+  if (sub === 'list') return artifactListCmd(ctx, [])
+  if (sub === 'server') return artifactServerCmd(ctx, [])
+  return {
+    content:
+      'Usage: /artifact <open|list|server> [name]\n\n  /artifact open <name>  Open artifact in browser\n  /artifact list        List all artifacts\n  /artifact server      Show server status',
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════
 // Remaining low-priority stubs (backend not yet available)
 // ═══════════════════════════════════════════════════════════════
@@ -2214,6 +2287,9 @@ registry.set('/logout', logoutCmd)
 registry.set('/feedback', feedbackCmd)
 registry.set('/agents', agentsCmd)
 
+// Artifacts
+registry.set('/artifact', artifactBaseCmd)
+
 // Lower-priority semi-stubs (WIP, backend pending)
 registry.set('/branch', branchCmd)
 registry.set('/schedule', scheduleCmd)

package/src/ui/input.tsx

@@ -10,34 +10,95 @@ interface InputBarProps {
 // ── Status verbs — English (Claude Code-aligned) + Chinese (Mipham originals) ──
 
 const STATUS_EN = [
-  'Doodling', 'Forging', 'Germinating', 'Mosmosing', 'Cerebrating',
-  'Boogieing', 'Finagling', 'Misting', 'Recombobulating', 'Slithering',
-  'Effecting', 'Roosting', 'Crystallizing', 'Canoodling', 'Billowing',
-  'Warping', 'Improvising', 'Metamorphing', 'Gusting', 'Whiring',
-  'Topsy-turvying', 'Flibbertigibetting', 'Wibbling', 'Thundering',
-  'Moseying', 'Julienning', 'Evaporating', 'Ruminating', 'Whisking',
-  'Scampering', 'Meandering', 'Concoting', 'Gesticulating', 'Flamebeing',
-  'Quantumizing', 'Waddling', 'Fluttering', 'Sprouting', 'Elucidating',
-  'Embellishing', 'Razzmatizing', 'Pondering', 'Cogitating', 'Garnishing',
-  'Actualizing', 'Zigzagging', 'Mustering', 'Frolicking', 'Hullaballooing',
-  'Doing', 'Fermenting', 'Considering', 'Skedaddling', 'Actioning',
-  'Orbiting', 'Perambulating', 'Drizzling', 'Schlepping', 'Ionizing',
+  'Doodling',
+  'Forging',
+  'Germinating',
+  'Mosmosing',
+  'Cerebrating',
+  'Boogieing',
+  'Finagling',
+  'Misting',
+  'Recombobulating',
+  'Slithering',
+  'Effecting',
+  'Roosting',
+  'Crystallizing',
+  'Canoodling',
+  'Billowing',
+  'Warping',
+  'Improvising',
+  'Metamorphing',
+  'Gusting',
+  'Whiring',
+  'Topsy-turvying',
+  'Flibbertigibetting',
+  'Wibbling',
+  'Thundering',
+  'Moseying',
+  'Julienning',
+  'Evaporating',
+  'Ruminating',
+  'Whisking',
+  'Scampering',
+  'Meandering',
+  'Concoting',
+  'Gesticulating',
+  'Flamebeing',
+  'Quantumizing',
+  'Waddling',
+  'Fluttering',
+  'Sprouting',
+  'Elucidating',
+  'Embellishing',
+  'Razzmatizing',
+  'Pondering',
+  'Cogitating',
+  'Garnishing',
+  'Actualizing',
+  'Zigzagging',
+  'Mustering',
+  'Frolicking',
+  'Hullaballooing',
+  'Doing',
+  'Fermenting',
+  'Considering',
+  'Skedaddling',
+  'Actioning',
+  'Orbiting',
+  'Perambulating',
+  'Drizzling',
+  'Schlepping',
+  'Ionizing',
   'Scurrying',
 ]
 
 const STATUS_CN = [
-  '思忖中', '推演中', '凝炼中', '熬煮中', '锻造中',
-  '研磨中', '解构中', '冥思中', '编织中', '萃取中',
-  '烹制中', '淬火中', '雕琢中', '融汇中', '觉照中',
-  '运转中', '参详中', '化合中', '浸润中', '焙烤中',
+  '思忖中',
+  '推演中',
+  '凝炼中',
+  '熬煮中',
+  '锻造中',
+  '研磨中',
+  '解构中',
+  '冥思中',
+  '编织中',
+  '萃取中',
+  '烹制中',
+  '淬火中',
+  '雕琢中',
+  '融汇中',
+  '觉照中',
+  '运转中',
+  '参详中',
+  '化合中',
+  '浸润中',
+  '焙烤中',
 ]
 
 // Merge both — bilingual status verbs
 const STATUS_GERUNDS = [...STATUS_EN, ...STATUS_CN]
 
-const STATUS_PAST = [
-  'Brewed', 'Churned', 'Cooked', 'Sautéed', 'Cogitated', 'Crunched',
-]
+const STATUS_PAST = ['Brewed', 'Churned', 'Cooked', 'Sautéed', 'Cogitated', 'Crunched']
 
 function pick<T>(arr: T[]): T {
   return arr[Math.floor(Math.random() * arr.length)]!

package/src/ui/picker.tsx

@@ -1,6 +1,6 @@
-import React, { useState, useCallback, useEffect } from 'react'
+import React, { useState, useCallback } from 'react'
 import { Box, Text, useInput } from 'ink'
-import type { MiphamConfig, ProviderConfig, ModelInfo } from '../shared/index.ts'
+import type { MiphamConfig, ProviderConfig } from '../shared/index.ts'
 
 interface PickerProps {
   config: MiphamConfig
@@ -113,9 +113,6 @@ export function ModelPicker({
   // Provider labels
   const providerColor = (p: ProviderConfig) => (p.id === currentProvider ? 'green' : 'white')
 
-  const modelColor = (m: ModelInfo) =>
-    selectedProvider?.id === currentProvider && m.id === currentModel ? 'green' : 'white'
-
   return (
     <Box flexDirection="column" borderStyle="round" borderColor="cyan" padding={1}>
       {/* Title */}