@plaited/development-skills 0.4.0 → 0.5.0

package/.claude/commands/lsp-find.md

@@ -1,43 +1,66 @@
 ---
-description: Search for TypeScript symbols across the workspace by name
+description: Search for TypeScript SYMBOLS (functions, types, classes) - NOT text
 allowed-tools: Bash
 ---
 
 # LSP Find
 
-Search for symbols (functions, types, classes, variables) across the TypeScript/JavaScript codebase.
+Search for TypeScript **symbols** (functions, types, classes, variables) across the codebase.
 
 **Arguments:** $ARGUMENTS
 
+## When to Use Each Tool
+
+| Tool | Purpose |
+|------|---------|
+| **Glob** | Find files by pattern |
+| **Grep** | Search text content |
+| **lsp-find** | Search TypeScript symbols |
+| **lsp-hover** | Get type info + TSDoc documentation |
+
 ## Usage
 
 ```
-/lsp-find <query> [context-file]
+/lsp-find <query> <context-file>
+```
+
+- `query`: TypeScript symbol name (function, type, class, variable)
+- `context-file`: Any `.ts` file in the project for LSP context
+
+## When NOT to Use
+
 ```
+# ❌ WRONG: Searching for text (use Grep instead)
+/lsp-find scaffold
+/lsp-find TODO
 
-- `query`: Symbol name or partial name to search for
-- `context-file`: Optional file to open for project context
+# ❌ WRONG: Missing context file
+/lsp-find createClient
+
+# ✅ CORRECT: Symbol search with context file
+/lsp-find createClient src/lsp-client.ts
+```
 
 ## Instructions
 
 ### Step 1: Parse Arguments
 
-Extract query and optional context file from `$ARGUMENTS`.
+Extract query and context file from `$ARGUMENTS`.
 
-If query is missing, show usage:
+If either is missing, show usage:
 ```
-Usage: /lsp-find <query> [context-file]
+Usage: /lsp-find <query> <context-file>
 
 Examples:
-  /lsp-find bElement
-  /lsp-find useTemplate src/main/use-template.ts
+  /lsp-find LspClient src/lsp-client.ts
+  /lsp-find createClient src/app.ts
 ```
 
 ### Step 2: Run LSP Find
 
 Execute the development-skills CLI command:
 ```bash
-bunx @plaited/development-skills lsp-find <query> [context-file]
+bunx @plaited/development-skills lsp-find <query> <context-file>
 ```
 
 ### Step 3: Format Output

package/.claude/commands/lsp-hover.md

@@ -1,14 +1,23 @@
 ---
-description: Get TypeScript type information at a specific position in a file
+description: Get TypeScript type signature + TSDoc documentation at a position
 allowed-tools: Bash
 ---
 
 # LSP Hover
 
-Get type information at a specific position in a TypeScript/JavaScript file.
+Get type signature and TSDoc documentation at a specific position in a TypeScript/JavaScript file.
 
 **Arguments:** $ARGUMENTS
 
+## When to Use Each Tool
+
+| Tool | Purpose |
+|------|---------|
+| **Glob** | Find files by pattern |
+| **Grep** | Search text content |
+| **lsp-find** | Search TypeScript symbols |
+| **lsp-hover** | Get type info + TSDoc documentation |
+
 ## Usage
 
 ```

package/.claude/commands/lsp-refs.md

@@ -9,6 +9,15 @@ Find all references to a symbol at a specific position. Use this before modifyin
 
 **Arguments:** $ARGUMENTS
 
+## When to Use Each Tool
+
+| Tool | Purpose |
+|------|---------|
+| **Glob** | Find files by pattern |
+| **Grep** | Search text content |
+| **lsp-find** | Search TypeScript symbols |
+| **lsp-refs** | Find all references to a symbol |
+
 ## Usage
 
 ```

package/.claude/rules/code-review.md

@@ -221,38 +221,6 @@ import config from './config.json'
 
 **Rationale:** Import attributes (ES2025) explicitly declare module types to the runtime. The `with { type: 'json' }` syntax is the standard (replacing the deprecated `assert` keyword). This provides runtime enforcement—if the file isn't valid JSON, the import fails.
 
-## Module Organization
-
-Organize module exports into separate files by category:
-
-```
-module/
-├── module.types.ts      # Type definitions only
-├── module.schemas.ts    # Zod schemas and schema-inferred types
-├── module.constants.ts  # Constants and enum-like objects
-├── module-client.ts     # Implementation
-└── index.ts             # Public API exports (barrel file)
-```
-
-### Key Principles
-
-- **Types file**: Contains only type definitions, does NOT re-export from sibling files
-- **Schemas file**: Contains Zod schemas and their inferred types, does NOT export constants
-- **Constants file**: Contains all constant values (error codes, method names, defaults)
-- **Barrel file**: Uses wildcard exports; non-public files are simply not included
-
-```typescript
-// ✅ Good: Direct imports from specific files
-import type { Config } from './module.types.ts'
-import { ConfigSchema } from './module.schemas.ts'
-import { METHODS, ERROR_CODES } from './module.constants.ts'
-
-// ❌ Avoid: Expecting types file to re-export everything
-import { Config, ConfigSchema, METHODS } from './module.types.ts'
-```
-
-**Rationale:** Prevents circular dependencies, makes dependencies explicit, improves tree-shaking.
-
 ## Documentation Standards
 
 ### Mermaid Diagrams Only

package/.claude/rules/module-organization.md

@@ -0,0 +1,92 @@
+<!--
+RULE TEMPLATE - Distributed via /scaffold-rules
+Variables: {{#if bun}}
+-->
+
+# Module Organization
+
+## No Index Files
+
+**Never use `index.ts` or `index.js` files.** These create implicit magic and complicate debugging.
+
+### Re-export Pattern
+
+Use named re-export files at the parent level, matching the folder name:
+
+```
+src/
+├── acp/                 # Feature module
+│   ├── acp.types.ts
+│   ├── acp.schemas.ts
+│   └── acp.ts           # Main implementation
+├── acp.ts               # Re-exports public API from acp/
+├── utils/
+│   └── format.ts
+└── utils.ts             # Re-exports public API from utils/
+```
+
+### Single Feature Packages
+
+When a package has one primary feature, expose that re-export file directly as main:
+
+```json
+{
+  "main": "src/acp.ts",
+  "exports": {
+    ".": "./src/acp.ts",
+    "./utils": "./src/utils.ts"
+  }
+}
+```
+
+Only use `main.ts` if the package truly has multiple co-equal entry points that need a unified export.
+
+## Explicit Import Extensions
+
+{{#if bun}}
+Always include `.ts` extensions in imports. Bun runs TypeScript natively—no compilation required:
+{{/if}}
+
+```typescript
+// ✅ Good
+import { Config } from './module.types.ts'
+import { createClient } from '../acp/acp.ts'
+
+// ❌ Avoid
+import { Config } from './module.types'
+```
+
+**Rationale:** Explicit extensions enable direct execution, clearer module graphs, and align with ES module standards. With `allowImportingTsExtensions: true`, TypeScript supports this pattern.
+
+## File Organization Within Modules
+
+```
+feature/
+├── feature.types.ts      # Type definitions only
+├── feature.schemas.ts    # Zod schemas + inferred types
+├── feature.constants.ts  # Constants, error codes
+└── feature.ts            # Main implementation
+```
+
+- **Types file**: Type definitions only, no re-exports from siblings
+- **Schemas file**: Zod schemas and `z.infer<>` types
+- **Constants file**: All constant values
+- **Main file**: Primary implementation, named after the feature
+
+### Key Principles
+
+- **Direct imports**: Import from specific files, not through re-exports within a module
+- **Re-exports at boundaries**: Only use re-export files to expose public API at module boundaries
+- **No circular re-exports**: Types file does NOT re-export from siblings
+
+```typescript
+// ✅ Good: Direct imports from specific files
+import type { Config } from './feature.types.ts'
+import { ConfigSchema } from './feature.schemas.ts'
+import { ERROR_CODES } from './feature.constants.ts'
+
+// ❌ Avoid: Expecting one file to re-export everything
+import { Config, ConfigSchema, ERROR_CODES } from './feature.types.ts'
+```
+
+**Rationale:** Prevents circular dependencies, makes dependencies explicit, improves tree-shaking.

package/.claude/rules/testing.md

@@ -75,6 +75,86 @@ If a value might not exist, the test should either:
 2. Assert that it doesn't exist (if that's the expected behavior)
 3. Restructure the test to ensure the value is always present
 
+## Test Coverage Principles
+
+### Expansion Checklist
+
+When writing tests, ensure coverage of:
+
+- [ ] **Happy path** - Expected normal usage
+- [ ] **Edge cases** - Empty strings, special characters, boundary values
+- [ ] **Fallback paths** - What happens when try/catch catches?
+- [ ] **Real dependencies** - Use installed packages (e.g., `@modelcontextprotocol/sdk`) not fake paths
+- [ ] **Category organization** - Group related tests in `describe` blocks
+
+### Meaningful Test Coverage
+
+Tests should verify behavior, not just exercise code. Each test should answer: "What breaks if this test fails?"
+
+**Coverage priorities:**
+1. **Happy path** - Normal expected usage
+2. **Edge cases** - Boundary conditions, empty inputs, unusual formats
+3. **Error paths** - Invalid inputs, missing dependencies, fallback behavior
+4. **Real integrations** - Use actual installed packages when testing module resolution
+
+### Use Real Dependencies
+
+When testing features that interact with packages or the file system, prefer real installed packages over mocked/fake paths:
+
+```typescript
+// ✅ Good: Real scoped package with subpath exports
+test('resolves scoped package subpath', () => {
+  const result = resolveFilePath('@modelcontextprotocol/sdk/client')
+  expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
+})
+
+// ✅ Good: Real package deep subpath
+test('resolves deep subpath with extension', () => {
+  const result = resolveFilePath('@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js')
+  expect(result).toContain('bearerAuth')
+})
+```
+
+### Test Both Branches
+
+When code has conditional logic, try/catch, or fallbacks, test both paths:
+
+```typescript
+describe('package resolution', () => {
+  test('success: resolves existing package', () => {
+    const result = resolveFilePath('typescript')
+    expect(result).toContain('node_modules/typescript')
+  })
+
+  test('fallback: returns cwd path for non-existent package', () => {
+    const result = resolveFilePath('nonexistent-package')
+    expect(result).toBe(join(cwd, 'nonexistent-package'))
+  })
+})
+```
+
+### Organize with Describe Blocks
+
+Group tests by category for better readability and failure diagnosis:
+
+```typescript
+describe('resolveFilePath', () => {
+  describe('absolute paths', () => {
+    test('returns as-is', () => { /* ... */ })
+  })
+
+  describe('relative paths with extension', () => {
+    test('resolves ./ paths', () => { /* ... */ })
+    test('resolves ../ paths', () => { /* ... */ })
+  })
+
+  describe('scoped package specifiers', () => {
+    test('resolves subpath exports', () => { /* ... */ })
+    test('falls back for non-existent', () => { /* ... */ })
+  })
+})
+```
+
 ## Docker Integration Tests
 
 Tests that require external services or API keys can run in Docker containers for consistent, isolated execution.

package/.claude/skills/scaffold-rules/SKILL.md

@@ -66,6 +66,13 @@ Bun test runner conventions:
 - No conditionals around assertions
 - Assert existence before checking values
 
+### Module Organization
+Import/export patterns for Bun/TypeScript projects:
+- No `index.ts` files—use named re-export files matching folder names
+- Single feature packages expose the feature file directly as main
+- Explicit `.ts` extensions in all imports
+- Flat re-export structure: `src/acp.ts` re-exports from `src/acp/`
+
 ## Merge Behavior
 
 **Always scans existing rules first.** When existing rules are found:

package/.claude/skills/typescript-lsp/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: typescript-lsp
-description: REQUIRED for searching code in *.ts, *.tsx, *.js, *.jsx files. Use INSTEAD of Grep for TypeScript/JavaScript - provides type-aware symbol search that understands imports, exports, and relationships. Activate before reading, editing, or searching TypeScript code to verify signatures and find references.
+description: Search TypeScript SYMBOLS (functions, types, classes) - NOT text. Use Glob to find files, Grep for text search, LSP for symbol search. Provides type-aware results that understand imports, exports, and relationships.
 license: ISC
 compatibility: Requires bun
 allowed-tools: Bash
 metadata:
   file-triggers: "*.ts,*.tsx,*.js,*.jsx"
-  replaces-tools: Grep
 ---
 
 # TypeScript LSP Skill
@@ -24,14 +23,25 @@ Use these tools to:
 - **Verify before editing** - Check all usages before modifying or deleting exports
 - **Navigate code** - Jump to definitions, find implementations
 
-## When to Use LSP vs Grep/Glob
+## When to Use Each Tool
+
+| Tool | Purpose |
+|------|---------|
+| **Glob** | Find files by pattern |
+| **Grep** | Search text content |
+| **lsp-find** | Search TypeScript symbols |
+| **lsp-hover** | Get type info + TSDoc documentation |
+| **lsp-refs** | Find all references to a symbol |
+| **lsp-analyze** | Batch analysis of file structure |
+
+### LSP vs Grep/Glob
 
 | Task | Use LSP | Use Grep/Glob |
 |------|---------|---------------|
-| Find all usages of a function/type | ✅ `lsp-references` | ❌ Misses re-exports, aliases |
+| Find all usages of a function/type | ✅ `lsp-refs` | ❌ Misses re-exports, aliases |
 | Search for a symbol by name | ✅ `lsp-find` | ❌ Matches strings, comments |
+| Get type signature + TSDoc | ✅ `lsp-hover` | ❌ Not possible |
 | Understand file exports | ✅ `lsp-analyze --exports` | ❌ Doesn't resolve re-exports |
-| Get type signature | ✅ `lsp-hover` | ❌ Not possible |
 | Find files by pattern | ❌ | ✅ `Glob` |
 | Search non-TS files (md, json) | ❌ | ✅ `Grep` |
 | Search for text in comments/strings | ❌ | ✅ `Grep` |

package/LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2025 Plaited
+Copyright (c) 2026 Plaited Labs
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

package/README.md

@@ -1,5 +1,10 @@
 # development-skills
 
+[![npm version](https://img.shields.io/npm/v/@plaited/development-skills.svg)](https://www.npmjs.com/package/@plaited/development-skills)
+[![CI](https://github.com/plaited/acp-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/plaited/development-skills/actions/workflows/ci.yml)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+
 TypeScript LSP, code documentation, and validation tools. Available as both a CLI tool and as installable skills for AI coding agents.
 
 ## CLI Tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/development-skills",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
   "license": "ISC",
   "engines": {
@@ -48,6 +48,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
+    "@modelcontextprotocol/sdk": "1.22.0",
     "@types/bun": "1.3.6",
     "format-package": "7.0.0",
     "lint-staged": "16.2.7",

package/src/lsp-analyze.ts

@@ -125,7 +125,7 @@ Examples:
     console.error('Error: File path required')
     process.exit(1)
   }
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 

package/src/lsp-find.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 /**
- * Search for symbols across the workspace by name
+ * Search for TypeScript symbols across the workspace by name
  *
- * Usage: bun lsp-find.ts <query> [file]
+ * Usage: bun lsp-find.ts <query> <context-file>
  */
 
 import { parseArgs } from 'node:util'
@@ -10,25 +10,9 @@ import { LspClient } from './lsp-client.ts'
 import { resolveFilePath } from './resolve-file-path.ts'
 
 /**
- * Find a default context file when none is provided
+ * Search for TypeScript symbols across the workspace by name
  *
- * @remarks
- * Checks common TypeScript entry points in order of preference
- */
-const findDefaultContextFile = async (): Promise<string | null> => {
-  const candidates = [`${process.cwd()}/src/index.ts`, `${process.cwd()}/src/main.ts`, `${process.cwd()}/index.ts`]
-  for (const candidate of candidates) {
-    if (await Bun.file(candidate).exists()) {
-      return candidate
-    }
-  }
-  return null
-}
-
-/**
- * Search for symbols across the workspace by name
- *
- * @param args - Command line arguments [query, file?]
+ * @param args - Command line arguments [query, context-file]
  */
 export const lspFind = async (args: string[]) => {
   const { positionals } = parseArgs({
@@ -38,10 +22,15 @@ export const lspFind = async (args: string[]) => {
 
   const [query, filePath] = positionals
 
-  if (!query) {
-    console.error('Usage: lsp-find <query> [file]')
-    console.error('  query: Symbol name or partial name to search')
-    console.error('  file: Optional file to open for project context')
+  if (!query || !filePath) {
+    console.error('Error: context-file required')
+    console.error('')
+    console.error('lsp-find searches TypeScript SYMBOLS (functions, types, classes).')
+    console.error('  - Use Glob to find files by pattern')
+    console.error('  - Use Grep to search text content')
+    console.error('  - Use lsp-find <query> <context-file> for symbol search')
+    console.error('')
+    console.error('Provide any .ts file as context-file (e.g., src/app.ts)')
     process.exit(1)
   }
 
@@ -51,15 +40,7 @@ export const lspFind = async (args: string[]) => {
   try {
     await client.start()
 
-    // Open a file to establish project context if provided, otherwise find a default
-    const contextFile = filePath ? await resolveFilePath(filePath) : await findDefaultContextFile()
-
-    if (!contextFile) {
-      console.error('Error: No context file found.')
-      console.error('Provide a file path or ensure src/index.ts, src/main.ts, or index.ts exists.')
-      await client.stop()
-      process.exit(1)
-    }
+    const contextFile = resolveFilePath(filePath)
 
     const file = Bun.file(contextFile)
     if (!(await file.exists())) {

package/src/lsp-hover.ts

@@ -38,7 +38,7 @@ export const lspHover = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 

package/src/lsp-references.ts

@@ -38,7 +38,7 @@ export const lspRefs = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 

package/src/lsp-symbols.ts

@@ -28,7 +28,7 @@ export const lspSymbols = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 

package/src/resolve-file-path.ts

@@ -1,28 +1,42 @@
+import { join } from 'node:path'
+
+/**
+ * Check if a path has a source file extension
+ */
+const hasSourceExtension = (path: string): boolean => /\.(tsx?|jsx?|mjs|cjs|json)$/.test(path)
+
 /**
  * Resolve a file path to an absolute path
  *
  * @remarks
- * Handles three types of paths:
- * - Absolute paths (starting with `/`) - returned as-is
- * - Relative paths (starting with `.`) - resolved from cwd
- * - Package export paths (e.g., `plaited/workshop/get-paths.ts`) - resolved via Bun.resolve()
+ * Resolution order:
+ * 1. Absolute paths (starting with `/`) - returned as-is
+ * 2. Explicit relative with extension (`./foo.ts`, `../bar.ts`) - resolved from cwd
+ * 3. Everything else - try Bun.resolveSync(), fallback to cwd
+ *
+ * The "everything else" category includes:
+ * - Package specifiers: `@org/pkg`, `lodash`, `typescript/lib/typescript.js`
+ * - Relative without extension: `./testing` (for package.json exports)
+ * - Implicit relative: `src/foo.ts` (fails Bun.resolveSync, falls back to cwd)
  */
-export const resolveFilePath = async (filePath: string): Promise<string> => {
-  // Absolute path
+export const resolveFilePath = (filePath: string): string => {
+  const cwd = process.cwd()
+
+  // Absolute path - return as-is
   if (filePath.startsWith('/')) {
     return filePath
   }
 
-  // Relative path from cwd
-  if (filePath.startsWith('.')) {
-    return `${process.cwd()}/${filePath}`
+  // Explicit relative with extension - resolve directly from cwd
+  if (filePath.startsWith('.') && hasSourceExtension(filePath)) {
+    return join(cwd, filePath)
   }
 
-  // Try package export path resolution
+  // Everything else: try Bun.resolveSync
+  // Handles packages, exports field resolution, and implicit relative paths (via fallback)
   try {
-    return await Bun.resolve(filePath, process.cwd())
+    return Bun.resolveSync(filePath, cwd)
   } catch {
-    // Fall back to relative path from cwd
-    return `${process.cwd()}/${filePath}`
+    return join(cwd, filePath)
   }
 }

package/src/tests/resolve-file-path.spec.ts

@@ -1,33 +1,114 @@
 import { describe, expect, test } from 'bun:test'
+import { join } from 'node:path'
 import { resolveFilePath } from '../resolve-file-path.ts'
 
 describe('resolveFilePath', () => {
-  test('returns absolute path as-is', async () => {
-    const absolutePath = '/Users/test/file.ts'
-    const result = await resolveFilePath(absolutePath)
-    expect(result).toBe(absolutePath)
+  describe('absolute paths', () => {
+    test('returns absolute path as-is', () => {
+      const absolutePath = '/Users/test/file.ts'
+      const result = resolveFilePath(absolutePath)
+      expect(result).toBe(absolutePath)
+    })
   })
 
-  test('resolves relative path from cwd', async () => {
-    const relativePath = './plugin/skills/typescript-lsp/scripts/tests/fixtures/sample.ts'
-    const result = await resolveFilePath(relativePath)
-    expect(result).toBe(`${process.cwd()}/${relativePath}`)
+  describe('relative paths with extension', () => {
+    test('resolves ./path from cwd', () => {
+      const relativePath = './src/resolve-file-path.ts'
+      const result = resolveFilePath(relativePath)
+      expect(result).toBe(join(process.cwd(), relativePath))
+    })
+
+    test('resolves ../path from cwd', () => {
+      const relativePath = '../other/file.ts'
+      const result = resolveFilePath(relativePath)
+      expect(result).toBe(join(process.cwd(), relativePath))
+    })
+
+    test('resolves various file extensions', () => {
+      const extensions = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'json']
+
+      for (const ext of extensions) {
+        const path = `./src/file.${ext}`
+        const result = resolveFilePath(path)
+        expect(result).toBe(join(process.cwd(), path))
+      }
+    })
+  })
+
+  describe('relative paths without extension', () => {
+    test('falls back to cwd when no exports match', () => {
+      // ./testing has no extension, tries Bun.resolveSync first
+      // Falls back to cwd since this project has no exports field
+      const path = './testing'
+      const result = resolveFilePath(path)
+      expect(result).toBe(join(process.cwd(), path))
+    })
+  })
+
+  describe('implicit relative paths', () => {
+    test('resolves src/foo.ts via fallback to cwd', () => {
+      // No ./ prefix, has extension - tries Bun.resolveSync (fails), falls back to cwd
+      const path = 'src/resolve-file-path.ts'
+      const result = resolveFilePath(path)
+      expect(result).toBe(join(process.cwd(), path))
+    })
+
+    test('resolves nested implicit path via fallback', () => {
+      const path = 'src/tests/fixtures/sample.ts'
+      const result = resolveFilePath(path)
+      expect(result).toBe(join(process.cwd(), path))
+    })
   })
 
-  test('resolves package export path via Bun.resolve', async () => {
-    // Use typescript package which is installed as devDependency
-    const packagePath = 'typescript'
-    const result = await resolveFilePath(packagePath)
+  describe('bare package specifiers', () => {
+    test('resolves bare package name', () => {
+      const result = resolveFilePath('typescript')
+      expect(result).toContain('node_modules/typescript')
+      expect(result.startsWith('/')).toBe(true)
+    })
 
-    // Should resolve to node_modules/typescript/...
-    expect(result).toContain('node_modules/typescript')
-    expect(result.startsWith('/')).toBe(true)
+    test('falls back to cwd for non-existent package', () => {
+      const invalidPath = 'nonexistent-package'
+      const result = resolveFilePath(invalidPath)
+      expect(result).toBe(join(process.cwd(), invalidPath))
+    })
   })
 
-  test('falls back to cwd for non-existent package', async () => {
-    const invalidPath = 'nonexistent-package/file.ts'
-    const result = await resolveFilePath(invalidPath)
+  describe('scoped package specifiers', () => {
+    test('resolves scoped package subpath export', () => {
+      // @modelcontextprotocol/sdk/client is a defined export
+      const result = resolveFilePath('@modelcontextprotocol/sdk/client')
+      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
+      expect(result).toContain('client')
+    })
+
+    test('resolves scoped package server subpath', () => {
+      const result = resolveFilePath('@modelcontextprotocol/sdk/server')
+      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
+      expect(result).toContain('server')
+    })
+
+    test('resolves scoped package deep subpath with extension', () => {
+      // Deep subpath with .js extension via wildcard export "./*"
+      const path = '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js'
+      const result = resolveFilePath(path)
+      expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
+      expect(result).toContain('bearerAuth')
+    })
+
+    test('falls back to cwd for non-existent scoped package', () => {
+      const scopedPkg = '@nonexistent/pkg/src/file.ts'
+      const result = resolveFilePath(scopedPkg)
+      expect(result).toBe(join(process.cwd(), scopedPkg))
+    })
+  })
 
-    expect(result).toBe(`${process.cwd()}/${invalidPath}`)
+  describe('package subpaths', () => {
+    test('resolves package subpath with extension', () => {
+      // typescript/lib/typescript.js is a real subpath
+      const result = resolveFilePath('typescript/lib/typescript.js')
+      expect(result).toContain('node_modules/typescript')
+      expect(result).toContain('typescript.js')
+    })
   })
 })