Claude Code 플러그인 시스템

// schemas.ts, 사칭 시도를 막는 차단 패턴
export const BLOCKED_OFFICIAL_NAME_PATTERN =
  /(?:official[^a-z0-9]*(anthropic|claude)|(?:anthropic|claude)[^a-z0-9]*official|^(?:anthropic|claude)[^a-z0-9]*(marketplace|plugins|official))/i

// Non-ASCII는 동형이의 공격을 막는다. 키릴 문자 'а'는 라틴 문자 'a'와 다르다.
const NON_ASCII_PATTERN = /[^\u0020-\u007E]/

export function validateOfficialNameSource(name, source): string | null {
  // 예약된 이름인가? 반드시 github.com/anthropics/ 에서 와야 한다.
  if (source.source === 'github') {
    const repo = source.repo || ''
    if (!repo.toLowerCase().startsWith(`anthropics/`)) {
      return `이 이름 '${name}'은 공식 Anthropic 마켓플레이스용으로 예약되어 있습니다.`
    }
  }
  return null
}

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "모든 기능 유형을 보여주는 예제 플러그인",
  "author": { "name": "Acme Corp", "url": "https://acme.example" },
  "license": "MIT",

  // 의존성 선언, bare name은 이 플러그인의 마켓플레이스를 상속한다
  "dependencies": ["shared-utils"],

  // 명령, 디렉터리 자동 스캔 + 추가 파일 + inline content
  "commands": {
    "hello": { "content": "${CLAUDE_PLUGIN_ROOT}에 인사하기" },
    "deploy": { "source": "./docs/deploy.md", "argumentHint": "[env]" }
  },

  // 훅, inline 또는 path
  "hooks": "./hooks/extra.json",

  // .mcpb 번들을 통한 MCP 서버, 미리 패키징된 바이너리
  "mcpServers": "./server.mcpb",

  // TypeScript용 LSP 서버
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact" }
    }
  },

  // 사용자 설정 값, 활성화 시점에 입력받는다
  "userConfig": {
    "API_KEY": {
      "type": "string",
      "title": "API Key",
      "description": "서비스 API 키",
      "sensitive": true,   // → settings.json이 아니라 keychain에 저장된다
      "required": true
    }
  }
}

// pluginLoader.ts
export function getVersionedCachePathIn(
  baseDir: string,
  pluginId: string,
  version: string,
): string {
  const { name: pluginName, marketplace } = parsePluginIdentifier(pluginId)
  // path traversal을 막기 위해 각 세그먼트를 정리한다
  const sanitizedMarketplace = (marketplace || 'unknown').replace(/[^a-zA-Z0-9\-_]/g, '-')
  const sanitizedPlugin    = (pluginName    || pluginId).replace(/[^a-zA-Z0-9\-_]/g, '-')
  const sanitizedVersion   = version.replace(/[^a-zA-Z0-9\-_.]/g, '-')
  return join(baseDir, 'cache', sanitizedMarketplace, sanitizedPlugin, sanitizedVersion)
}

// pluginVersioning.ts, git-subdir path hash
const normPath = source.path
  .replace(/\\/g, '/')    // backslash를 forward slash로 바꾼다
  .replace(/^\.\//, '')    // 앞의 ./ 제거
  .replace(/\/+$/, '')     // 뒤의 / 제거
const pathHash = createHash('sha256').update(normPath).digest('hex').substring(0, 8)
const v = `${shortSha}-${pathHash}`

export async function resolveDependencyClosure(
  rootId: PluginId,
  lookup: (id: PluginId) => Promise<DependencyLookupResult | null>,
  alreadyEnabled: ReadonlySet<PluginId>,
  allowedCrossMarketplaces: ReadonlySet<string> = new Set(),
): Promise<ResolutionResult> {
  const closure: PluginId[] = []
  const visited = new Set<PluginId>()
  const stack: PluginId[] = []  // 사이클 감지를 위한 DFS 스택

  async function walk(id, requiredBy) {
    // 이미 활성화된 DEP는 건너뛴다. root 제외. version pin 덮어쓰기를 막기 위함이다.
    if (id !== rootId && alreadyEnabled.has(id)) return null

    // 교차 마켓플레이스 보안 게이트
    const idMkt = parsePluginIdentifier(id).marketplace
    if (idMkt !== rootMarketplace && !allowedCrossMarketplaces.has(idMkt)) {
      return { ok: false, reason: 'cross-marketplace', dependency: id, requiredBy }
    }

    if (stack.includes(id)) return { ok: false, reason: 'cycle', chain: [...stack, id] }
    if (visited.has(id)) return null
    visited.add(id)

    const entry = await lookup(id)
    if (!entry) return { ok: false, reason: 'not-found', missing: id, requiredBy }

    stack.push(id)
    for (const rawDep of entry.dependencies ?? []) {
      const dep = qualifyDependency(rawDep, id)  // bare name이면 marketplace를 상속한다
      const err = await walk(dep, id)
      if (err) return err
    }
    stack.pop()
    closure.push(id)   // post-order, dep가 dependent보다 먼저 온다
    return null
  }

  const err = await walk(rootId, rootId)
  if (err) return err
  return { ok: true, closure }
}

런타임에는 명령과 스킬 내용에서 다음 변수가 치환됩니다.

// dependencyResolver.ts
export function findReverseDependents(
  pluginId: PluginId,
  plugins: readonly LoadedPlugin[],
): string[] {
  const { name: targetName } = parsePluginIdentifier(pluginId)
  return plugins
    .filter(p =>
      p.enabled &&
      p.source !== pluginId &&
      (p.manifest.dependencies ?? []).some(d => {
        const qualified = qualifyDependency(d, p.source)
        // @inline 플러그인의 bare dep는 이름만으로 매칭한다
        return parsePluginIdentifier(qualified).marketplace
          ? qualified === pluginId
          : qualified === targetName
      }),
    )
    .map(p => p.name)
}
// 결과 예시, "warning: plugin-a, plugin-b가 필요로 함"