@fugood/bricks-project 2.23.3 → 2.23.5

package/tools/mcp-tools/icons.ts

@@ -0,0 +1,60 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import * as TOON from '@toon-format/toon'
+import Fuse from 'fuse.js'
+import glyphmap from '../icons/fa6pro-glyphmap.json'
+import glyphmapMeta from '../icons/fa6pro-meta.json'
+
+type IconStyle = 'brands' | 'duotone' | 'light' | 'regular' | 'solid' | 'thin'
+const iconMeta = glyphmapMeta as Record<IconStyle, string[]>
+
+const iconList = Object.entries(glyphmap as Record<string, number>).map(([name, code]) => {
+  const styles = (Object.keys(iconMeta) as IconStyle[]).filter((style) =>
+    iconMeta[style].includes(name),
+  )
+  return { name, code, styles }
+})
+
+const iconFuse = new Fuse(iconList, {
+  keys: ['name'],
+  threshold: 0.3,
+  includeScore: true,
+})
+
+export function register(server: McpServer) {
+  server.tool(
+    'icon_search',
+    {
+      query: z.string().describe('Search keywords for FontAwesome 6 Pro icons'),
+      limit: z.number().min(1).max(100).optional().default(10),
+      style: z
+        .enum(['brands', 'duotone', 'light', 'regular', 'solid', 'thin'])
+        .optional()
+        .describe('Filter by icon style'),
+    },
+    async ({ query, limit, style }) => {
+      let results = iconFuse.search(query, { limit: style ? limit * 3 : limit })
+
+      if (style) {
+        results = results.filter((r) => r.item.styles.includes(style)).slice(0, limit)
+      }
+
+      const icons = results.map((r) => ({
+        name: r.item.name,
+        code: r.item.code,
+        unicode: `U+${r.item.code.toString(16).toUpperCase()}`,
+        styles: r.item.styles,
+        score: r.score,
+      }))
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: TOON.encode({ count: icons.length, icons }),
+          },
+        ],
+      }
+    },
+  )
+}

package/tools/mcp-tools/lottie.ts

@@ -0,0 +1,102 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import * as TOON from '@toon-format/toon'
+
+const LOTTIEFILES_API_URL = 'https://lottiefiles.com/api'
+
+export function register(server: McpServer) {
+  server.tool(
+    'lottie_search',
+    {
+      query: z.string().describe('Search keywords for animations'),
+      page: z.number().min(1).optional().default(1),
+      limit: z.number().min(1).max(100).optional().default(10),
+    },
+    async ({ query, page, limit }) => {
+      try {
+        const url = new URL(`${LOTTIEFILES_API_URL}/search/get-animations`)
+        url.searchParams.set('query', query)
+        url.searchParams.set('page', String(page))
+        url.searchParams.set('limit', String(limit))
+        url.searchParams.set('format', 'json')
+
+        const response = await fetch(url.toString())
+        const data = await response.json()
+        const animations = data?.data?.data ?? []
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: TOON.encode({ count: animations.length, animations }),
+            },
+          ],
+        }
+      } catch (err: any) {
+        return {
+          content: [{ type: 'text', text: `Failed to search animations: ${err.message}` }],
+        }
+      }
+    },
+  )
+
+  server.tool(
+    'lottie_get_details',
+    {
+      id: z.string().describe('Animation file ID'),
+    },
+    async ({ id }) => {
+      try {
+        const url = new URL(`${LOTTIEFILES_API_URL}/animations/get-animation-data`)
+        url.searchParams.set('fileId', id)
+        url.searchParams.set('format', 'json')
+
+        const response = await fetch(url.toString())
+        const data = await response.json()
+
+        return {
+          content: [{ type: 'text', text: TOON.encode(data) }],
+        }
+      } catch (err: any) {
+        return {
+          content: [{ type: 'text', text: `Failed to get animation: ${err.message}` }],
+        }
+      }
+    },
+  )
+
+  server.tool(
+    'lottie_popular',
+    {
+      page: z.number().min(1).optional().default(1),
+      limit: z.number().min(1).max(100).optional().default(10),
+    },
+    async ({ page, limit }) => {
+      try {
+        const url = new URL(
+          `${LOTTIEFILES_API_URL}/iconscout/popular-animations-weekly?api=%26sort%3Dpopular`,
+        )
+        url.searchParams.set('page', String(page))
+        url.searchParams.set('limit', String(limit))
+        url.searchParams.set('format', 'json')
+
+        const response = await fetch(url.toString())
+        const data = await response.json()
+        const animations = data?.popularWeeklyData?.data ?? []
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: TOON.encode({ count: animations.length, animations }),
+            },
+          ],
+        }
+      } catch (err: any) {
+        return {
+          content: [{ type: 'text', text: `Failed to get popular animations: ${err.message}` }],
+        }
+      }
+    },
+  )
+}

package/tools/mcp-tools/media.ts

@@ -0,0 +1,110 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { $ } from 'bun'
+
+const runBricks = async (projectDir: string, ...args: string[]) => {
+  try {
+    return await $`bunx bricks ${args}`.cwd(projectDir).text()
+  } catch (err: any) {
+    throw new Error(err.stderr?.toString() || err.message)
+  }
+}
+
+export function register(server: McpServer, projectDir: string) {
+  server.tool('media_boxes', {}, async () => {
+    try {
+      const output = await runBricks(projectDir, 'media', 'boxes')
+      return { content: [{ type: 'text', text: output }] }
+    } catch (err: any) {
+      return { content: [{ type: 'text', text: `Failed to list media boxes: ${err.message}` }] }
+    }
+  })
+
+  server.tool('media_get_box', { id: z.string().describe('Media box ID') }, async ({ id }) => {
+    try {
+      const output = await runBricks(projectDir, 'media', 'box', id)
+      return { content: [{ type: 'text', text: output }] }
+    } catch (err: any) {
+      return { content: [{ type: 'text', text: `Failed to get media box: ${err.message}` }] }
+    }
+  })
+
+  server.tool(
+    'media_files',
+    {
+      boxId: z.string().describe('Media box ID'),
+      types: z.string().describe('Comma-separated file types to include').optional(),
+      userTag: z.array(z.string()).describe('Filter by user tags').optional(),
+      limit: z.number().describe('Limit results').optional(),
+      offset: z.number().describe('Offset results').optional(),
+    },
+    async ({ boxId, types, userTag, limit, offset }) => {
+      try {
+        const args = ['media', 'files', boxId]
+        if (types) args.push('-t', types)
+        if (userTag) userTag.forEach((tag) => args.push('-u', tag))
+        if (limit != null) args.push('-l', String(limit))
+        if (offset != null) args.push('-o', String(offset))
+        const output = await runBricks(projectDir, ...args)
+        return { content: [{ type: 'text', text: output }] }
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Failed to list media files: ${err.message}` }] }
+      }
+    },
+  )
+
+  server.tool('media_file', { id: z.string().describe('Media file ID') }, async ({ id }) => {
+    try {
+      const output = await runBricks(projectDir, 'media', 'file', id)
+      return { content: [{ type: 'text', text: output }] }
+    } catch (err: any) {
+      return { content: [{ type: 'text', text: `Failed to get media file: ${err.message}` }] }
+    }
+  })
+
+  server.tool(
+    'media_upload_files',
+    {
+      boxId: z.string().describe('Target media box ID'),
+      files: z.array(z.string()).min(1).describe('File paths to upload'),
+      description: z.string().describe('File description').optional(),
+      userTags: z.array(z.string()).max(15).describe('User tags (max 15)').optional(),
+      imageVersion: z
+        .array(z.string())
+        .describe('Image resize specs as WxH or WxH:STRATEGY')
+        .optional(),
+      imageVersionType: z.enum(['jpg', 'png']).describe('Image output format').optional(),
+      enableAiAnalysis: z.boolean().describe('Enable AI analysis').optional(),
+      aiInstruction: z.string().describe('Custom AI analysis instruction').optional(),
+      concurrency: z.number().min(1).describe('Max concurrent uploads').optional(),
+    },
+    async ({
+      boxId,
+      files,
+      description,
+      userTags,
+      imageVersion,
+      imageVersionType,
+      enableAiAnalysis,
+      aiInstruction,
+      concurrency,
+    }) => {
+      try {
+        const args = ['media', 'upload', boxId, ...files]
+        if (description) args.push('-d', description)
+        if (userTags) userTags.forEach((tag) => args.push('-t', tag))
+        if (imageVersion) imageVersion.forEach((spec) => args.push('--image-version', spec))
+        if (imageVersionType) args.push('--image-version-type', imageVersionType)
+        if (enableAiAnalysis) args.push('--enable-ai-analysis')
+        if (aiInstruction) args.push('--ai-instruction', aiInstruction)
+        if (concurrency != null) args.push('--concurrency', String(concurrency))
+        const output = await runBricks(projectDir, ...args)
+        return { content: [{ type: 'text', text: output }] }
+      } catch (err: any) {
+        return {
+          content: [{ type: 'text', text: `Failed to upload media files: ${err.message}` }],
+        }
+      }
+    },
+  )
+}

package/tools/postinstall.ts

@@ -1,8 +1,25 @@
 import { $ } from 'bun'
-import { stat, readFile, writeFile, readdir } from 'fs/promises'
+import {
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  readlink,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from 'fs/promises'
+import * as path from 'path'
 import TOML from '@iarna/toml'
 
 const cwd = process.cwd()
+const projectSkillsDir = path.join(cwd, '.bricks', 'skills')
+const compatibilitySkillLinks = [
+  path.join(cwd, '.claude', 'skills'),
+  path.join(cwd, '.codex', 'skills'),
+]
 
 async function exists(f: string) {
   try {
@@ -13,6 +30,15 @@ async function exists(f: string) {
   }
 }
 
+async function pathExists(f: string) {
+  try {
+    await lstat(f)
+    return true
+  } catch {
+    return false
+  }
+}
+
 // handle flag --skip-copy
 const skipCopyProject = process.argv.includes('--skip-copy-project')
 if (skipCopyProject) {
@@ -34,6 +60,7 @@ type CodexMcpConfig = {
   mcp_servers: Record<string, typeof projectMcpServer>
 }
 
+// Claude Code and AGENTS.md projects both use the shared project .mcp.json file.
 const defaultMcpConfig = {
   mcpServers: {
     'bricks-project': projectMcpServer,
@@ -64,43 +91,101 @@ const hasClaudeCode = await exists(`${cwd}/CLAUDE.md`)
 const hasAgentsMd = await exists(`${cwd}/AGENTS.md`)
 
 if (hasClaudeCode || hasAgentsMd) {
+  // Keep the workspace-level JSON MCP config aligned for tools that read .mcp.json.
   const mcpConfigPath = `${cwd}/.mcp.json`
   await handleMcpConfigOverride(mcpConfigPath)
 }
 
-const setupSkills = async (skillsDir) => {
-  const packageSkillsDir = `${__dirname}/../skills`
+const copyMissingSkills = async (sourceDir: string, targetDir: string) => {
+  if (!(await exists(sourceDir))) return
+
+  const packageSkills = await readdir(sourceDir, { withFileTypes: true })
+  const skillsToInstall = packageSkills.filter(
+    (entry) => entry.isDirectory() && !entry.name.startsWith('.'),
+  )
+
+  await mkdir(targetDir, { recursive: true })
+
+  await Promise.all(
+    skillsToInstall.map(async (entry) => {
+      const targetSkillDir = path.join(targetDir, entry.name)
+      if (await exists(targetSkillDir)) {
+        console.log(`Skill '${entry.name}' already exists, skipping`)
+      } else {
+        await cp(path.join(sourceDir, entry.name), targetSkillDir, { recursive: true })
+        console.log(`Installed skill '${entry.name}' to ${targetDir}/`)
+      }
+    }),
+  )
+}
+
+const migrateSkillsDir = async (legacySkillsDir: string, canonicalSkillsDir: string) => {
+  if (!(await pathExists(legacySkillsDir))) return
+
+  const legacyStats = await lstat(legacySkillsDir)
+
+  if (legacyStats.isSymbolicLink()) {
+    const linkTarget = await readlink(legacySkillsDir)
+    const resolvedTarget = path.resolve(path.dirname(legacySkillsDir), linkTarget)
+    if (resolvedTarget === canonicalSkillsDir) return
 
-  if (await exists(packageSkillsDir)) {
-    const packageSkills = await readdir(packageSkillsDir)
-    const skillsToInstall = packageSkills.filter((skill) => !skill.startsWith('.'))
-
-    await $`mkdir -p ${skillsDir}`
-
-    await Promise.all(
-      skillsToInstall.map(async (skill) => {
-        const targetSkillDir = `${skillsDir}/${skill}`
-        if (await exists(targetSkillDir)) {
-          console.log(`Skill '${skill}' already exists, skipping`)
-        } else {
-          await $`cp -r ${packageSkillsDir}/${skill} ${targetSkillDir}`
-          console.log(`Installed skill '${skill}' to ${skillsDir}/`)
-        }
-      }),
-    )
+    await copyMissingSkills(resolvedTarget, canonicalSkillsDir)
+    await rm(legacySkillsDir, { force: true, recursive: true })
+    return
   }
+
+  if (legacyStats.isDirectory()) {
+    await copyMissingSkills(legacySkillsDir, canonicalSkillsDir)
+    await rm(legacySkillsDir, { force: true, recursive: true })
+    return
+  }
+
+  console.warn(`Skipping skills migration for ${legacySkillsDir}; expected a directory or symlink`)
 }
 
-if (hasClaudeCode) {
-  // Install skills that don't already exist in the project
-  await setupSkills(`${cwd}/.claude/skills`)
+const ensureCompatibilitySkillLink = async (linkPath: string, targetDir: string) => {
+  await mkdir(path.dirname(linkPath), { recursive: true })
+
+  if (await pathExists(linkPath)) {
+    const linkStats = await lstat(linkPath)
+    if (linkStats.isSymbolicLink()) {
+      const linkTarget = await readlink(linkPath)
+      const resolvedTarget = path.resolve(path.dirname(linkPath), linkTarget)
+      if (resolvedTarget === targetDir) return
+    } else {
+      console.warn(
+        `Skipping skills symlink at ${linkPath}; path already exists and is not a symlink`,
+      )
+      return
+    }
+  }
+
+  const relativeTarget = path.relative(path.dirname(linkPath), targetDir)
+  const symlinkType = process.platform === 'win32' ? 'junction' : 'dir'
+  await symlink(relativeTarget, linkPath, symlinkType)
+  console.log(`Linked ${linkPath} -> ${relativeTarget}`)
 }
 
-if (hasAgentsMd) {
-  // Handle codex skills
-  // Currently no signal file for codex skills, so we just check if AGENTS.md exists
-  await setupSkills(`${cwd}/.codex/skills`)
+const setupSkills = async () => {
+  const packageSkillsDir = `${__dirname}/../skills`
+  await mkdir(projectSkillsDir, { recursive: true })
+  await copyMissingSkills(packageSkillsDir, projectSkillsDir)
+
+  await Promise.all(
+    compatibilitySkillLinks.map(async (linkPath) => {
+      await migrateSkillsDir(linkPath, projectSkillsDir)
+      await ensureCompatibilitySkillLink(linkPath, projectSkillsDir)
+    }),
+  )
+}
 
+if (hasClaudeCode || hasAgentsMd) {
+  // Install project skills once and expose them through compatibility symlinks.
+  await setupSkills()
+}
+
+if (hasAgentsMd) {
+  // Codex stores its project-local MCP config in .codex/config.toml.
   const defaultCodexMcpConfig = {
     mcp_servers: {
       'bricks-project': projectMcpServer,
@@ -128,7 +213,7 @@ if (hasAgentsMd) {
     console.log(`Updated ${mcpConfigPath}`)
   }
 
-  // Setup MCP config (.codex/config.toml)
+  // Keep the Codex TOML MCP config aligned with the same bricks-project server entry.
   const codexConfigPath = `${cwd}/.codex/config.toml`
   await handleCodexMcpConfigOverride(codexConfigPath)
 }

package/tools/pull.ts

@@ -2,6 +2,8 @@ import { $ } from 'bun'
 import { format } from 'prettier'
 
 const cwd = process.cwd()
+const args = process.argv.slice(2)
+const force = args.includes('--force') || args.includes('-f')
 
 // Check git status
 const { exitCode } = await $`cd ${cwd} && git status`.nothrow()
@@ -9,8 +11,15 @@ const isGitRepo = exitCode === 0
 
 if (isGitRepo) {
   const unstagedChanges = await $`cd ${cwd} && git diff --name-only --diff-filter=ACMR`.text()
-  if (unstagedChanges)
-    throw new Error('Unstaged changes found, please commit or stash your changes before pulling')
+  if (unstagedChanges) {
+    if (force) {
+      console.log('Force mode: committing unstaged changes before pull...')
+      await $`cd ${cwd} && git add .`
+      await $`cd ${cwd} && git commit -m ${'chore(force-pull): saved unstaged changes before pull'}`
+    } else {
+      throw new Error('Unstaged changes found, please commit or stash your changes before pulling')
+    }
+  }
 } else {
   const confirmContinue = prompt(
     'No git repository found, so it will not be safe to pull, continue? (y/n)',
@@ -25,6 +34,7 @@ const isModule = app.type === 'module'
 const command = isModule ? 'module' : 'app'
 
 // Fetch project files using CLI
+console.log(`Pulling ${command} project (${app.id})...`)
 const result = await $`bricks ${command} project-pull ${app.id} --json`.quiet().nothrow()
 
 if (result.exitCode !== 0) {
@@ -40,7 +50,8 @@ if (result.exitCode !== 0) {
 const { files, lastCommitId } = JSON.parse(result.stdout.toString())
 
 let useMain = false
-if (isGitRepo) {
+if (isGitRepo && !force) {
+  console.log(`Checking commit ${lastCommitId}...`)
   const found = (await $`cd ${cwd} && git rev-list -1 ${lastCommitId}`.nothrow().text())
     .trim()
     .match(/^[\da-f]{40}$/)
@@ -86,13 +97,18 @@ await Promise.all(
 
 if (isGitRepo) {
   await $`cd ${cwd} && git add .`
-  const commitMsg = isModule
-    ? 'chore(project): apply file changes from BRICKS module'
-    : 'chore(project): apply file changes from BRICKS application'
-  await $`cd ${cwd} && git commit -m ${commitMsg}`
-  if (!useMain) {
+  const hasChanges = !!(await $`cd ${cwd} && git diff --cached --name-only`.text()).trim()
+  if (hasChanges) {
+    let commitMsg = 'chore(project): apply file changes from BRICKS application'
+    if (force) commitMsg = `chore(force-pull): apply force pull-${command}`
+    else if (isModule) commitMsg = 'chore(project): apply file changes from BRICKS module'
+    await $`cd ${cwd} && git commit -m ${commitMsg}`
+  }
+  if (!force && !useMain) {
     await $`cd ${cwd} && git merge main`
   }
 }
 
-console.log(`${isModule ? 'Module' : 'App'} project pulled: ${files.length} files`)
+console.log(
+  `${isModule ? 'Module' : 'App'} project pulled: ${files.length} files${force ? ' (force)' : ''}`,
+)

package/types/animation.ts

@@ -61,8 +61,10 @@ export interface AnimationDecayConfig {
 export interface AnimationDef {
   __typename: 'Animation'
   id: string
+  alias?: string
   title: string
   description?: string
+  hideShortRef?: boolean
   runType?: 'once' | 'loop'
   property:
     | 'transform.translateX'
@@ -80,8 +82,10 @@ export interface AnimationDef {
 export interface AnimationComposeDef {
   __typename: 'AnimationCompose'
   id: string
+  alias?: string
   title: string
   description?: string
+  hideShortRef?: boolean
   runType?: 'once' | 'loop'
   composeType: 'parallel' | 'sequence'
   items: Array<() => Animation>

package/types/automation.ts

@@ -182,6 +182,7 @@ export interface TestCase {
   __typename: 'TestCase'
   id: string
   name: string
+  hideShortRef?: boolean
   run: TestMethodRun
   exit_on_failed: boolean
   commented: boolean
@@ -203,6 +204,7 @@ export interface AutomationTest {
   __typename: 'AutomationTest'
   id: string
   title: string
+  hideShortRef?: boolean
   timeout: number
   trigger_type?: TestTriggerType
   cron?: string // Cron expression when trigger_type is 'cron'
@@ -220,6 +222,7 @@ export interface AutomationTestMap {
   __typename: 'AutomationTestMap'
   id: string
   title: string
+  hideShortRef?: boolean
   createdAt: number
   tests: AutomationTest[]
 }

package/types/bricks/Camera.ts

@@ -167,15 +167,42 @@ Default property:
   }
   outlets?: {
     /* Camera device and format information */
-    info?: () => Data
+    info?: () => Data<{ [key: string]: any }>
     /* Picture taken result */
-    pictureTaken?: () => Data
+    pictureTaken?: () => Data<{
+      width?: number
+      height?: number
+      uri?: string
+      base64?: string
+      [key: string]: any
+    }>
     /* Record video result */
-    recordVideo?: () => Data
+    recordVideo?: () => Data<{
+      uri?: string
+      [key: string]: any
+    }>
     /* Barcode read result */
-    barcodeRead?: () => Data
+    barcodeRead?: () => Data<{
+      type?: string
+      data?: string
+      rawData?: string
+      bounds?: {
+        origin?: {
+          x?: number
+          y?: number
+          [key: string]: any
+        }
+        size?: {
+          width?: number
+          height?: number
+          [key: string]: any
+        }
+        [key: string]: any
+      }
+      [key: string]: any
+    }>
     /* Faces detected result */
-    faceDetected?: () => Data
+    faceDetected?: () => Data<Array<{ [key: string]: any }>>
   }
   animation?: AnimationBasicEvents & {
     stateChange?: Animation
@@ -188,7 +215,7 @@ Default property:
   }
 }
 
-/* Camera view brick ([Tutorial](https://intercom.help/bricks-dag-inc/articles/5378589-camera)) */
+/* Camera view brick */
 export type BrickCamera = Brick &
   BrickCameraDef & {
     templateKey: 'BRICK_CAMERA'

package/types/bricks/GenerativeMedia.ts

@@ -209,15 +209,15 @@ Default property:
   }
   outlets?: {
     /* Brick is pressing */
-    brickPressing?: () => Data
+    brickPressing?: () => Data<boolean>
     /* Brick is focusing (Use TV Device with controller) */
-    brickFocusing?: () => Data
+    brickFocusing?: () => Data<boolean>
     /* Generated media URL */
-    url?: () => Data
+    url?: () => Data<string>
     /* Generated media error */
-    error?: () => Data
+    error?: () => Data<string>
     /* Loading state */
-    loading?: () => Data
+    loading?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
     generativeMediaOnPress?: Animation

package/types/bricks/Icon.ts

@@ -57,9 +57,9 @@ Default property:
   }
   outlets?: {
     /* Brick is pressing */
-    brickPressing?: () => Data
+    brickPressing?: () => Data<boolean>
     /* Brick is focusing (Use TV Device with controller) */
-    brickFocusing?: () => Data
+    brickFocusing?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
     onPress?: Animation

package/types/bricks/Image.ts

@@ -71,9 +71,9 @@ Default property:
   }
   outlets?: {
     /* Brick is pressing */
-    brickPressing?: () => Data
+    brickPressing?: () => Data<boolean>
     /* Brick is focusing (Use TV Device with controller) */
-    brickFocusing?: () => Data
+    brickFocusing?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
     onPress?: Animation
@@ -87,7 +87,7 @@ Default property:
   }
 }
 
-/* Image brick ([Tutorial](https://intercom.help/bricks-dag-inc/articles/5378576-image)) */
+/* Image brick */
 export type BrickImage = Brick &
   BrickImageDef & {
     templateKey: 'BRICK_IMAGE'