@foundrykit/cli 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/dist/cli.js +127 -4
- package/dist/cli.js.map +1 -1
- package/dist/index.js +127 -4
- package/dist/index.js.map +1 -1
- package/docs/DEPENDENCY_RESOLUTION.md +194 -0
- package/package.json +6 -3
- package/src/commands/add.ts +79 -5
- package/src/lib/registry.ts +71 -0
- package/tests/dependency-resolution.test.ts +289 -0
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
# Dependency Resolution in FoundryKit CLI
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The FoundryKit CLI handles two types of dependencies when adding components:
|
|
6
|
+
|
|
7
|
+
1. **Registry Dependencies** - Other components or utilities from the registry that a component depends on
|
|
8
|
+
2. **Package Dependencies** - NPM packages that need to be installed
|
|
9
|
+
|
|
10
|
+
## How It Works
|
|
11
|
+
|
|
12
|
+
### Registry Dependencies
|
|
13
|
+
|
|
14
|
+
When a component lists registry dependencies (e.g., `registryDependencies: ['utils']`), the CLI:
|
|
15
|
+
|
|
16
|
+
1. **Checks if the dependency already exists** in the project
|
|
17
|
+
2. **Handles special dependencies** (like `utils`) with custom logic
|
|
18
|
+
3. **Fetches regular dependencies** from the registry as components
|
|
19
|
+
4. **Gracefully handles failures** - warns but continues installation
|
|
20
|
+
|
|
21
|
+
### Special Dependencies
|
|
22
|
+
|
|
23
|
+
The following dependencies are handled specially:
|
|
24
|
+
|
|
25
|
+
- `utils` - Creates a `lib/utils.ts` file with the `cn()` function for className merging
|
|
26
|
+
- `lib` - Alias for `utils`
|
|
27
|
+
- `helpers` - Alias for `utils`
|
|
28
|
+
- `cn` - Alias for `utils`
|
|
29
|
+
|
|
30
|
+
#### Utils Dependency
|
|
31
|
+
|
|
32
|
+
When a component requires `utils`, the CLI:
|
|
33
|
+
|
|
34
|
+
1. Checks if `lib/utils.ts` already exists
|
|
35
|
+
2. If not, creates it with the standard `cn()` function:
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { type ClassValue, clsx } from 'clsx';
|
|
39
|
+
import { twMerge } from 'tailwind-merge';
|
|
40
|
+
|
|
41
|
+
export function cn(...inputs: ClassValue[]) {
|
|
42
|
+
return twMerge(clsx(inputs));
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
3. If it exists, preserves the existing file
|
|
47
|
+
4. Notifies about required NPM packages (`clsx`, `tailwind-merge`)
|
|
48
|
+
|
|
49
|
+
### Error Handling
|
|
50
|
+
|
|
51
|
+
The dependency resolution system is designed to be resilient:
|
|
52
|
+
|
|
53
|
+
- **Missing dependencies**: Logs a warning but continues installation
|
|
54
|
+
- **Network failures**: Falls back to local generation for special dependencies
|
|
55
|
+
- **Existing files**: Prompts user or skips based on `--overwrite` flag
|
|
56
|
+
|
|
57
|
+
## Examples
|
|
58
|
+
|
|
59
|
+
### Component with Utils Dependency
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"id": "button",
|
|
64
|
+
"name": "Button",
|
|
65
|
+
"registryDependencies": ["utils"],
|
|
66
|
+
"packageDependencies": ["clsx", "tailwind-merge"],
|
|
67
|
+
"files": [...]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
When installing this component:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
foundrykit add button
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The CLI will:
|
|
78
|
+
1. Check/create `lib/utils.ts`
|
|
79
|
+
2. Install the button component files
|
|
80
|
+
3. Notify about required NPM packages
|
|
81
|
+
|
|
82
|
+
### Component with Multiple Dependencies
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"id": "data-table",
|
|
87
|
+
"name": "DataTable",
|
|
88
|
+
"registryDependencies": ["utils", "table", "pagination"],
|
|
89
|
+
"packageDependencies": ["@tanstack/react-table"],
|
|
90
|
+
"files": [...]
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The CLI will:
|
|
95
|
+
1. Process each registry dependency in order
|
|
96
|
+
2. Skip already installed dependencies
|
|
97
|
+
3. Create special dependencies as needed
|
|
98
|
+
4. Fetch regular components from the registry
|
|
99
|
+
|
|
100
|
+
## Implementation Details
|
|
101
|
+
|
|
102
|
+
### Registry Service
|
|
103
|
+
|
|
104
|
+
The `RegistryService` class handles dependency resolution:
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
// Check if it's a special dependency
|
|
108
|
+
if (this.isSpecialDependency(id)) {
|
|
109
|
+
return this.createSpecialDependency(id);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// Otherwise, fetch from registry
|
|
113
|
+
const component = await registry.getComponent(id);
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Add Command
|
|
117
|
+
|
|
118
|
+
The `add` command processes dependencies before installing the main component:
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
// Install registry dependencies first
|
|
122
|
+
if (componentData.registryDependencies?.length) {
|
|
123
|
+
for (const dep of componentData.registryDependencies) {
|
|
124
|
+
try {
|
|
125
|
+
// Special handling for utils
|
|
126
|
+
if (dep === 'utils') {
|
|
127
|
+
// Create utils file if needed
|
|
128
|
+
} else {
|
|
129
|
+
// Fetch and install as component
|
|
130
|
+
}
|
|
131
|
+
} catch (error) {
|
|
132
|
+
// Log warning but continue
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Testing
|
|
139
|
+
|
|
140
|
+
Run the test script to verify dependency resolution:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
cd packages/cli
|
|
144
|
+
node test-add-command.js
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
This tests:
|
|
148
|
+
1. Utils file creation
|
|
149
|
+
2. Existing file preservation
|
|
150
|
+
3. Missing dependency handling
|
|
151
|
+
4. Error recovery
|
|
152
|
+
|
|
153
|
+
## Best Practices
|
|
154
|
+
|
|
155
|
+
### For Component Authors
|
|
156
|
+
|
|
157
|
+
1. **List all dependencies** in `registryDependencies`
|
|
158
|
+
2. **Use `utils` for className merging** instead of bundling your own
|
|
159
|
+
3. **Specify package dependencies** for NPM packages
|
|
160
|
+
|
|
161
|
+
### For CLI Users
|
|
162
|
+
|
|
163
|
+
1. **Install package dependencies** after adding components
|
|
164
|
+
2. **Use `--overwrite` carefully** to avoid losing customizations
|
|
165
|
+
3. **Check the output** for any warnings about failed dependencies
|
|
166
|
+
|
|
167
|
+
## Troubleshooting
|
|
168
|
+
|
|
169
|
+
### Component fails to install
|
|
170
|
+
|
|
171
|
+
1. Check network connection
|
|
172
|
+
2. Clear cache: `foundrykit cache clear`
|
|
173
|
+
3. Try with `--overwrite` flag if files exist
|
|
174
|
+
|
|
175
|
+
### Utils not found error
|
|
176
|
+
|
|
177
|
+
1. Ensure `lib/utils.ts` exists
|
|
178
|
+
2. Install required packages: `pnpm add clsx tailwind-merge`
|
|
179
|
+
3. Check import path matches: `@/lib/utils`
|
|
180
|
+
|
|
181
|
+
### Dependency not found in registry
|
|
182
|
+
|
|
183
|
+
This is usually fine - special dependencies are created locally. The CLI will:
|
|
184
|
+
1. Log a warning
|
|
185
|
+
2. Create the dependency if it's special (like `utils`)
|
|
186
|
+
3. Continue with the installation
|
|
187
|
+
|
|
188
|
+
## Future Improvements
|
|
189
|
+
|
|
190
|
+
- [ ] Dependency version management
|
|
191
|
+
- [ ] Circular dependency detection
|
|
192
|
+
- [ ] Batch dependency installation
|
|
193
|
+
- [ ] Dependency tree visualization
|
|
194
|
+
- [ ] Custom dependency handlers
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@foundrykit/cli",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"private": false,
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"glob": "^10.3.10",
|
|
26
26
|
"inquirer": "^9.2.15",
|
|
27
27
|
"node-fetch": "^3.3.0",
|
|
28
|
-
"@foundrykit/types": "1.0.
|
|
28
|
+
"@foundrykit/types": "1.0.1"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"@types/node": "^20.19.9",
|
|
@@ -34,6 +34,7 @@
|
|
|
34
34
|
"eslint": "^9.0.0",
|
|
35
35
|
"tsup": "^8.0.0",
|
|
36
36
|
"typescript": "^5.9.2",
|
|
37
|
+
"vitest": "^1.2.0",
|
|
37
38
|
"@foundrykit/eslint-config": "1.0.0",
|
|
38
39
|
"@foundrykit/typescript-config": "1.0.0"
|
|
39
40
|
},
|
|
@@ -41,6 +42,8 @@
|
|
|
41
42
|
"build": "tsup",
|
|
42
43
|
"dev": "tsup --watch",
|
|
43
44
|
"lint": "eslint . --max-warnings 0",
|
|
44
|
-
"type-check": "tsc --noEmit"
|
|
45
|
+
"type-check": "tsc --noEmit",
|
|
46
|
+
"test": "vitest",
|
|
47
|
+
"test:watch": "vitest --watch"
|
|
45
48
|
}
|
|
46
49
|
}
|
package/src/commands/add.ts
CHANGED
|
@@ -182,11 +182,76 @@ async function addSingleComponent(
|
|
|
182
182
|
if (componentData.registryDependencies?.length) {
|
|
183
183
|
console.log(chalk.blue('📦 Installing required dependencies...'));
|
|
184
184
|
for (const dep of componentData.registryDependencies) {
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
185
|
+
try {
|
|
186
|
+
// Special handling for utility dependencies
|
|
187
|
+
if (dep === 'utils') {
|
|
188
|
+
// Check if utils already exists
|
|
189
|
+
const utilsPath = path.join(
|
|
190
|
+
options.path || process.cwd(),
|
|
191
|
+
'lib/utils.ts'
|
|
192
|
+
);
|
|
193
|
+
if (!fs.existsSync(utilsPath)) {
|
|
194
|
+
// Create a basic utils file if it doesn't exist
|
|
195
|
+
await fs.ensureDir(path.dirname(utilsPath));
|
|
196
|
+
await fs.writeFile(
|
|
197
|
+
utilsPath,
|
|
198
|
+
`import { type ClassValue, clsx } from "clsx"
|
|
199
|
+
import { twMerge } from "tailwind-merge"
|
|
200
|
+
|
|
201
|
+
export function cn(...inputs: ClassValue[]) {
|
|
202
|
+
return twMerge(clsx(inputs))
|
|
203
|
+
}
|
|
204
|
+
`
|
|
205
|
+
);
|
|
206
|
+
console.log(chalk.green(` ✓ Created ${dep} file`));
|
|
207
|
+
} else {
|
|
208
|
+
console.log(chalk.gray(` ⏭ ${dep} already exists`));
|
|
209
|
+
}
|
|
210
|
+
} else {
|
|
211
|
+
// Try to fetch as a regular component
|
|
212
|
+
const depData = await registry.getComponent(dep);
|
|
213
|
+
if (!(await hasConflictingFiles(depData, options))) {
|
|
214
|
+
await installComponentFiles(depData, options);
|
|
215
|
+
console.log(chalk.green(` ✓ Installed ${dep}`));
|
|
216
|
+
} else {
|
|
217
|
+
console.log(chalk.gray(` ⏭ ${dep} already exists`));
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
} catch (error) {
|
|
221
|
+
// If dependency fetch fails, log warning but continue
|
|
222
|
+
console.log(
|
|
223
|
+
chalk.yellow(
|
|
224
|
+
` ⚠ Could not install dependency "${dep}": ${
|
|
225
|
+
error instanceof Error ? error.message : 'Unknown error'
|
|
226
|
+
}`
|
|
227
|
+
)
|
|
228
|
+
);
|
|
229
|
+
|
|
230
|
+
// For utils specifically, create it if missing
|
|
231
|
+
if (
|
|
232
|
+
dep === 'utils' &&
|
|
233
|
+
error instanceof Error &&
|
|
234
|
+
error.message.includes('not found')
|
|
235
|
+
) {
|
|
236
|
+
const utilsPath = path.join(
|
|
237
|
+
options.path || process.cwd(),
|
|
238
|
+
'lib/utils.ts'
|
|
239
|
+
);
|
|
240
|
+
if (!fs.existsSync(utilsPath)) {
|
|
241
|
+
await fs.ensureDir(path.dirname(utilsPath));
|
|
242
|
+
await fs.writeFile(
|
|
243
|
+
utilsPath,
|
|
244
|
+
`import { type ClassValue, clsx } from "clsx"
|
|
245
|
+
import { twMerge } from "tailwind-merge"
|
|
246
|
+
|
|
247
|
+
export function cn(...inputs: ClassValue[]) {
|
|
248
|
+
return twMerge(clsx(inputs))
|
|
249
|
+
}
|
|
250
|
+
`
|
|
251
|
+
);
|
|
252
|
+
console.log(chalk.green(` ✓ Created ${dep} file`));
|
|
253
|
+
}
|
|
254
|
+
}
|
|
190
255
|
}
|
|
191
256
|
}
|
|
192
257
|
}
|
|
@@ -210,6 +275,15 @@ async function addSingleComponent(
|
|
|
210
275
|
chalk.cyan(` pnpm add ${componentData.packageDependencies.join(' ')}`)
|
|
211
276
|
);
|
|
212
277
|
}
|
|
278
|
+
|
|
279
|
+
// Additional dependencies for utils
|
|
280
|
+
if (componentData.registryDependencies?.includes('utils')) {
|
|
281
|
+
const utilsDeps = ['clsx', 'tailwind-merge'];
|
|
282
|
+
console.log(chalk.yellow('\n📦 Required packages for utils:'));
|
|
283
|
+
console.log(chalk.gray(` ${utilsDeps.join(', ')}`));
|
|
284
|
+
console.log(chalk.gray(' Install them with:'));
|
|
285
|
+
console.log(chalk.cyan(` pnpm add ${utilsDeps.join(' ')}`));
|
|
286
|
+
}
|
|
213
287
|
} catch (error) {
|
|
214
288
|
console.error(chalk.red(`Failed to add ${id}:`));
|
|
215
289
|
throw error;
|
package/src/lib/registry.ts
CHANGED
|
@@ -93,6 +93,12 @@ export class RegistryService {
|
|
|
93
93
|
*/
|
|
94
94
|
async getComponent(id: string): Promise<ComponentData> {
|
|
95
95
|
try {
|
|
96
|
+
// Special handling for common utility dependencies
|
|
97
|
+
if (id === 'utils') {
|
|
98
|
+
console.log(chalk.gray(`Creating utils dependency...`));
|
|
99
|
+
return this.createUtilsComponent();
|
|
100
|
+
}
|
|
101
|
+
|
|
96
102
|
const url = `${this.config.registryUrl}/registry/${id}`;
|
|
97
103
|
console.log(chalk.gray(`Fetching component: ${url}`));
|
|
98
104
|
|
|
@@ -100,6 +106,15 @@ export class RegistryService {
|
|
|
100
106
|
|
|
101
107
|
if (!response.ok) {
|
|
102
108
|
if (response.status === 404) {
|
|
109
|
+
// Check if it's a known special dependency
|
|
110
|
+
if (this.isSpecialDependency(id)) {
|
|
111
|
+
console.log(
|
|
112
|
+
chalk.yellow(
|
|
113
|
+
`Special dependency "${id}" will be handled separately`
|
|
114
|
+
)
|
|
115
|
+
);
|
|
116
|
+
return this.createSpecialDependency(id);
|
|
117
|
+
}
|
|
103
118
|
throw new Error(`Component "${id}" not found in registry`);
|
|
104
119
|
}
|
|
105
120
|
throw new Error(
|
|
@@ -121,6 +136,12 @@ export class RegistryService {
|
|
|
121
136
|
return cache.componentData[id];
|
|
122
137
|
}
|
|
123
138
|
|
|
139
|
+
// Check if it's a special dependency that we can handle locally
|
|
140
|
+
if (this.isSpecialDependency(id)) {
|
|
141
|
+
console.log(chalk.yellow(`Creating local version of "${id}"`));
|
|
142
|
+
return this.createSpecialDependency(id);
|
|
143
|
+
}
|
|
144
|
+
|
|
124
145
|
// No cached data, throw error
|
|
125
146
|
throw new Error(
|
|
126
147
|
`Failed to fetch component "${id}": ${error instanceof Error ? error.message : 'Unknown error'}\n` +
|
|
@@ -130,6 +151,56 @@ export class RegistryService {
|
|
|
130
151
|
}
|
|
131
152
|
}
|
|
132
153
|
|
|
154
|
+
/**
|
|
155
|
+
* Check if a dependency is a special/utility dependency
|
|
156
|
+
*/
|
|
157
|
+
private isSpecialDependency(id: string): boolean {
|
|
158
|
+
const specialDeps = ['utils', 'lib', 'helpers', 'cn'];
|
|
159
|
+
return specialDeps.includes(id);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Create a special dependency component
|
|
164
|
+
*/
|
|
165
|
+
private createSpecialDependency(id: string): ComponentData {
|
|
166
|
+
switch (id) {
|
|
167
|
+
case 'utils':
|
|
168
|
+
case 'lib':
|
|
169
|
+
case 'helpers':
|
|
170
|
+
case 'cn':
|
|
171
|
+
return this.createUtilsComponent();
|
|
172
|
+
default:
|
|
173
|
+
throw new Error(`Unknown special dependency: ${id}`);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Create a utils component with the cn function
|
|
179
|
+
*/
|
|
180
|
+
private createUtilsComponent(): ComponentData {
|
|
181
|
+
return {
|
|
182
|
+
id: 'utils',
|
|
183
|
+
name: 'Utils',
|
|
184
|
+
category: 'primitives',
|
|
185
|
+
description: 'Utility functions for className merging',
|
|
186
|
+
tags: ['utility', 'helper'],
|
|
187
|
+
packageDependencies: ['clsx', 'tailwind-merge'],
|
|
188
|
+
files: [
|
|
189
|
+
{
|
|
190
|
+
path: 'lib/utils.ts',
|
|
191
|
+
type: 'util',
|
|
192
|
+
content: `import { type ClassValue, clsx } from 'clsx';
|
|
193
|
+
import { twMerge } from 'tailwind-merge';
|
|
194
|
+
|
|
195
|
+
export function cn(...inputs: ClassValue[]) {
|
|
196
|
+
return twMerge(clsx(inputs));
|
|
197
|
+
}
|
|
198
|
+
`,
|
|
199
|
+
},
|
|
200
|
+
],
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
|
|
133
204
|
/**
|
|
134
205
|
* Update the local cache with new component list
|
|
135
206
|
*/
|