Skip to content

Commit 5b6860a

Browse files
wangdicoderwangdicoder
authored
feat: add CLI package and shared extraction layer (#79)
* feat: add CLI package and shared extraction layer - Add @tiny-design/cli with 8 commands: list, info, doc, demo, token, icon, doctor, usage - Extract shared extraction logic into @tiny-design/extract (internal package) - Refactor @tiny-design/mcp to use shared extraction package - Add CLI documentation page (en + zh) to docs site - Reorganize Guide sidebar menu into 4 groups: Overview, Getting Started, AI, Resources * chore: update change log * fix: update MCP tests to use shared extract package - Update extract test imports from deleted local scripts to @tiny-design/extract - Use import.meta.url for __dirname in ESM test files - Remove rootDir from MCP tsconfig to allow cross-package type imports - Add --passWithNoTests to CLI test script
1 parent 810fc86 commit 5b6860a

47 files changed

Lines changed: 2056 additions & 532 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/add-cli-package.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@tiny-design/cli": minor
3+
"@tiny-design/mcp": patch
4+
---
5+
6+
Add @tiny-design/cli package for querying component metadata, docs, demos, tokens, and icons from the terminal. Extract shared extraction logic into internal @tiny-design/extract package. Add CLI docs page and reorganize Guide menu into grouped sections.

‎.changeset/config.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,5 @@
1313
"access": "public",
1414
"baseBranch": "master",
1515
"updateInternalDependencies": "patch",
16-
"ignore": ["@tiny-design/docs"]
16+
"ignore": ["@tiny-design/docs", "@tiny-design/extract"]
1717
}

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ apps/docs/build
2424
.claude/*
2525
!.claude/skills/
2626

27+
# Generated data
28+
packages/mcp/src/data
29+
packages/cli/src/data
30+
2731
# Misc
2832
*.tgz
2933
*.log

‎apps/docs/guides/cli.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# CLI
2+
3+
`@tiny-design/cli` is an official command-line tool that brings Tiny Design component knowledge to your terminal. It ships all metadata locally — every prop, demo, token, and icon — queryable in milliseconds, fully offline.
4+
5+
## Highlights
6+
7+
- **Fully offline** — All metadata ships with the package. No network calls, no latency, no API keys.
8+
- **Agent-optimized** — `--format json` on every command. Structured output ready for AI tools.
9+
- **Bilingual** — Every component name and description has both English and Chinese. Switch with `--lang zh`.
10+
- **Smart matching** — Typo `Buttn`? The CLI suggests `Button` using fuzzy matching.
11+
12+
## Install
13+
14+
```bash
15+
npm install -g @tiny-design/cli
16+
```
17+
18+
## Quick Start
19+
20+
```bash
21+
tiny-design list # List all 80+ components by category
22+
tiny-design info Button # Component props, types, defaults
23+
tiny-design doc Select # Full markdown documentation
24+
tiny-design demo Button Type # Runnable demo source code
25+
tiny-design token colors # Design token values
26+
tiny-design icon arrow # Search icons by name
27+
tiny-design doctor # Diagnose project issues
28+
tiny-design usage ./src # Scan project for import stats
29+
```
30+
31+
## Commands
32+
33+
### Knowledge Query
34+
35+
| Command | Description |
36+
|---------|-------------|
37+
| `tiny-design list [category]` | List all components grouped by category. Filter by: Foundation, Layout, Navigation, Data Display, Form, Feedback, Miscellany. |
38+
| `tiny-design info <component>` | Props table with types, required flags, default values, and descriptions. |
39+
| `tiny-design doc <component>` | Full markdown documentation for a component. |
40+
| `tiny-design demo <component> [name]` | Demo source code (TSX). Lists available demos if no name is given. |
41+
| `tiny-design token [category]` | Design token values. Categories: colors, typography, spacing, breakpoints, shadows. |
42+
| `tiny-design icon [search]` | List all 240+ icons or search by name. |
43+
44+
### Project Analysis
45+
46+
| Command | Description |
47+
|---------|-------------|
48+
| `tiny-design doctor` | Diagnostic checks: package.json, React version, peer deps, TypeScript, duplicate React detection. |
49+
| `tiny-design usage [dir]` | Scan source files for `@tiny-design/react` imports. Shows component usage counts and file locations. |
50+
51+
### Global Flags
52+
53+
| Flag | Description | Default |
54+
|------|-------------|---------|
55+
| `--format json\|text\|markdown` | Output format | `text` |
56+
| `--lang en\|zh` | Output language | `en` |
57+
| `--detail` | Include extended information | `false` |
58+
59+
## Examples
60+
61+
### List components in a category
62+
63+
```bash
64+
$ tiny-design list Foundation
65+
66+
Foundation
67+
68+
Component | Description
69+
------------+----------------------------------------------
70+
Button | To trigger an operation.
71+
Image | The Image component is used to display images.
72+
Link | Displays a hyperlink.
73+
Typography | Basic text writing, including headings, ...
74+
75+
4 components total
76+
```
77+
78+
### Get component props (JSON for AI tools)
79+
80+
```bash
81+
$ tiny-design info Modal --format json
82+
{
83+
"name": "Modal",
84+
"category": "Feedback",
85+
"description": "Modal dialogs.",
86+
"props": [
87+
{
88+
"name": "visible",
89+
"type": "boolean",
90+
"required": false,
91+
"description": "Whether the modal is visible"
92+
},
93+
...
94+
]
95+
}
96+
```
97+
98+
### Search icons
99+
100+
```bash
101+
$ tiny-design icon arrow
102+
103+
Icons matching "arrow" (16 found)
104+
105+
• IconArrowRight
106+
• IconArrowUp
107+
• IconArrowLeft
108+
• IconArrowDown
109+
...
110+
```
111+
112+
### View a demo
113+
114+
```bash
115+
$ tiny-design demo Button Type
116+
117+
Button / Type
118+
119+
import React from 'react';
120+
import { Button, Flex } from '@tiny-design/react';
121+
122+
export default function TypeDemo() {
123+
return (
124+
<Flex gap="sm">
125+
<Button>Default</Button>
126+
<Button btnType="primary">Primary</Button>
127+
<Button btnType="outline">Outline</Button>
128+
</Flex>
129+
);
130+
}
131+
```
132+
133+
### Diagnose project setup
134+
135+
```bash
136+
$ tiny-design doctor
137+
138+
Tiny Design Doctor
139+
140+
✓ package.json: Found
141+
✓ @tiny-design/react: v1.6.1 installed
142+
✓ React version: v18.3.1
143+
✓ TypeScript: v5.4.5
144+
✓ Peer dependencies: react-dom found
145+
✓ Duplicate React: No duplicates found
146+
147+
All checks passed!
148+
```
149+
150+
## Usage with AI Tools
151+
152+
The CLI is designed to work seamlessly with AI coding assistants. Use `--format json` for structured output:
153+
154+
```bash
155+
# Get component info as JSON for an AI agent
156+
tiny-design info DatePicker --format json
157+
158+
# List all icons as JSON
159+
tiny-design icon --format json
160+
161+
# Get design tokens as JSON
162+
tiny-design token colors --format json
163+
```
164+
165+
For a richer AI integration that works inside your editor, check out the [MCP Server](/guide/mcp-server) which provides the same data through the Model Context Protocol.

‎apps/docs/guides/cli.zh_CN.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# CLI
2+
3+
`@tiny-design/cli` 是官方命令行工具，将 Tiny Design 组件知识带到你的终端。所有元数据随包附带——每个属性、演示、令牌和图标——毫秒级查询，完全离线。
4+
5+
## 特性
6+
7+
- **完全离线** — 所有元数据随包附带，无需网络请求、无延迟、无需 API 密钥。
8+
- **AI 友好** — 所有命令支持 `--format json` 输出，结构化数据适配 AI 工具。
9+
- **双语支持** — 所有组件名称和描述同时提供中英文，使用 `--lang zh` 切换。
10+
- **智能匹配** — 输错 `Buttn`？CLI 会通过模糊匹配建议 `Button`。
11+
12+
## 安装
13+
14+
```bash
15+
npm install -g @tiny-design/cli
16+
```
17+
18+
## 快速开始
19+
20+
```bash
21+
tiny-design list # 列出所有 80+ 个组件（按分类）
22+
tiny-design info Button # 组件属性、类型、默认值
23+
tiny-design doc Select # 完整的 Markdown 文档
24+
tiny-design demo Button Type # 可运行的演示源代码
25+
tiny-design token colors # 设计令牌值
26+
tiny-design icon arrow # 按名称搜索图标
27+
tiny-design doctor # 诊断项目问题
28+
tiny-design usage ./src # 扫描项目中的导入统计
29+
```
30+
31+
## 命令
32+
33+
### 知识查询
34+
35+
| 命令 | 描述 |
36+
|------|------|
37+
| `tiny-design list [category]` | 按分类列出所有组件。可筛选：基础、布局、导航、数据展示、表单、反馈、其他。 |
38+
| `tiny-design info <component>` | 属性表，包含类型、是否必填、默认值和描述。 |
39+
| `tiny-design doc <component>` | 组件的完整 Markdown 文档。 |
40+
| `tiny-design demo <component> [name]` | 演示源代码（TSX）。未指定名称时列出可用演示。 |
41+
| `tiny-design token [category]` | 设计令牌值。分类：colors、typography、spacing、breakpoints、shadows。 |
42+
| `tiny-design icon [search]` | 列出所有 240+ 个图标或按名称搜索。 |
43+
44+
### 项目分析
45+
46+
| 命令 | 描述 |
47+
|------|------|
48+
| `tiny-design doctor` | 诊断检查：package.json、React 版本、对等依赖、TypeScript、重复 React 检测。 |
49+
| `tiny-design usage [dir]` | 扫描源文件中的 `@tiny-design/react` 导入，显示组件使用次数和文件位置。 |
50+
51+
### 全局参数
52+
53+
| 参数 | 描述 | 默认值 |
54+
|------|------|--------|
55+
| `--format json\|text\|markdown` | 输出格式 | `text` |
56+
| `--lang en\|zh` | 输出语言 | `en` |
57+
| `--detail` | 显示扩展信息 | `false` |
58+
59+
## 示例
60+
61+
### 按分类列出组件
62+
63+
```bash
64+
$ tiny-design list Foundation --lang zh
65+
66+
Foundation
67+
68+
Component | Description
69+
------------+----------------------------------------------
70+
Button | 用于触发一个操作。
71+
Image | Image 组件用于显示图片。
72+
Link | 显示超链接。
73+
Typography | 基本的文字排版，包括标题、正文、列表等。
74+
75+
4 components total
76+
```
77+
78+
### 获取组件属性（JSON 格式，适合 AI 工具）
79+
80+
```bash
81+
$ tiny-design info Modal --format json
82+
{
83+
"name": "Modal",
84+
"category": "Feedback",
85+
"description": "Modal dialogs.",
86+
"props": [
87+
{
88+
"name": "visible",
89+
"type": "boolean",
90+
"required": false,
91+
"description": "Whether the modal is visible"
92+
},
93+
...
94+
]
95+
}
96+
```
97+
98+
### 搜索图标
99+
100+
```bash
101+
$ tiny-design icon arrow
102+
103+
Icons matching "arrow" (16 found)
104+
105+
• IconArrowRight
106+
• IconArrowUp
107+
• IconArrowLeft
108+
• IconArrowDown
109+
...
110+
```
111+
112+
### 查看演示
113+
114+
```bash
115+
$ tiny-design demo Button Type
116+
117+
Button / Type
118+
119+
import React from 'react';
120+
import { Button, Flex } from '@tiny-design/react';
121+
122+
export default function TypeDemo() {
123+
return (
124+
<Flex gap="sm">
125+
<Button>Default</Button>
126+
<Button btnType="primary">Primary</Button>
127+
<Button btnType="outline">Outline</Button>
128+
</Flex>
129+
);
130+
}
131+
```
132+
133+
### 诊断项目配置
134+
135+
```bash
136+
$ tiny-design doctor
137+
138+
Tiny Design Doctor
139+
140+
✓ package.json: Found
141+
✓ @tiny-design/react: v1.6.1 installed
142+
✓ React version: v18.3.1
143+
✓ TypeScript: v5.4.5
144+
✓ Peer dependencies: react-dom found
145+
✓ Duplicate React: No duplicates found
146+
147+
All checks passed!
148+
```
149+
150+
## 与 AI 工具配合使用
151+
152+
CLI 专为 AI 编程助手设计。使用 `--format json` 获取结构化输出：
153+
154+
```bash
155+
# 以 JSON 格式获取组件信息
156+
tiny-design info DatePicker --format json
157+
158+
# 以 JSON 列出所有图标
159+
tiny-design icon --format json
160+
161+
# 以 JSON 获取设计令牌
162+
tiny-design token colors --format json
163+
```
164+
165+
如需在编辑器内更丰富的 AI 集成体验，请查看 [MCP Server](/guide/mcp-server)，它通过 Model Context Protocol 提供相同的数据。

0 commit comments

Comments
 (0)