@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.
@@ -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.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.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
  }
@@ -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
- // Check if dependency is already installed
186
- const depData = await registry.getComponent(dep);
187
- if (!(await hasConflictingFiles(depData, options))) {
188
- await installComponentFiles(depData, options);
189
- console.log(chalk.green(` ✓ Installed ${dep}`));
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;
@@ -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
  */