@foundrykit/cli 0.1.1 → 1.0.0

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 CHANGED
@@ -1,5 +1,27 @@
1
1
  # @foundrykit/cli
2
2
 
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - Version alignment push
8
+
9
+ ### Patch Changes
10
+
11
+ - Updated dependencies
12
+ - @foundrykit/types@1.0.0
13
+
14
+ ## 0.1.2
15
+
16
+ ### Patch Changes
17
+
18
+ - 015ff5f: Updating the way the cli works and how it grabs data from the
19
+ registry
20
+ - Updating versions to ensure they are inline
21
+ - Updated dependencies [015ff5f]
22
+ - Updated dependencies
23
+ - @foundrykit/types@0.1.2
24
+
3
25
  ## 0.1.1
4
26
 
5
27
  ### Patch Changes
package/README.md CHANGED
@@ -1,328 +1,296 @@
1
1
  # @foundrykit/cli
2
2
 
3
- A command-line interface for managing FoundryKit components, blocks, and projects. Provides tools for adding, updating, and managing UI components across your applications.
3
+ The official CLI for FoundryKit - a modern component library for Next.js applications with Tailwind CSS v4 support.
4
4
 
5
5
  ## Features
6
6
 
7
- - **Component management** - Add, update, and list components
8
- - **Block management** - Manage page blocks and sections
9
- - **Project initialization** - Set up new FoundryKit projects
10
- - **Registry integration** - Connect to component registries
11
- - **Interactive mode** - User-friendly interactive prompts
12
- - **Colorized output** - Beautiful terminal output with colors
7
+ - 🌐 **Live Registry** - Fetches components from the hosted registry at [foundry.umiflow.com](https://foundry.umiflow.com)
8
+ - 🎨 **Interactive Selection** - Multi-select components with keyboard navigation
9
+ - 📦 **Smart Dependencies** - Automatically installs required component dependencies
10
+ - 🎯 **Tailwind CSS v4** - Full support for the latest Tailwind CSS version
11
+ - 🔄 **Auto-updates** - Registry automatically updates when new components are released
13
12
 
14
13
  ## Installation
15
14
 
16
- ### Global Installation
15
+ ### Global Installation (Recommended)
17
16
 
18
17
  ```bash
18
+ # Using pnpm (recommended)
19
19
  pnpm add -g @foundrykit/cli
20
+
21
+ # Using npm
22
+ npm install -g @foundrykit/cli
23
+
24
+ # Using yarn
25
+ yarn global add @foundrykit/cli
20
26
  ```
21
27
 
22
28
  ### Local Installation
23
29
 
30
+ You can also use the CLI without installing it globally:
31
+
24
32
  ```bash
25
- pnpm add -D @foundrykit/cli
33
+ npx @foundrykit/cli [command]
26
34
  ```
27
35
 
28
- ## Available Commands
36
+ ## Quick Start
29
37
 
30
- ### Core Commands
38
+ Initialize FoundryKit in your Next.js project:
31
39
 
32
- - **`foundrykit init`** - Initialize a new FoundryKit project
33
- - **`foundrykit add`** - Add components or blocks to your project
34
- - **`foundrykit list`** - List available components and blocks
35
- - **`foundrykit update`** - Update existing components
36
- - **`foundrykit doctor`** - Check project health and configuration
40
+ ```bash
41
+ foundrykit init
42
+ ```
37
43
 
38
- ## Usage
44
+ This will:
45
+ - ✅ Detect your Next.js project
46
+ - ✅ Install required FoundryKit dependencies
47
+ - ✅ Set up Tailwind CSS v4 configuration
48
+ - ✅ Create necessary directories and files
49
+ - ✅ Add helper scripts to your package.json
39
50
 
40
- ### Initializing a Project
51
+ ## Commands
41
52
 
42
- ```bash
43
- # Initialize a new FoundryKit project
44
- foundrykit init
53
+ ### `init`
45
54
 
46
- # Initialize with specific options
47
- foundrykit init --template nextjs --typescript --tailwind
55
+ Initialize FoundryKit in your Next.js project.
56
+
57
+ ```bash
58
+ foundrykit init [options]
48
59
  ```
49
60
 
50
61
  **Options:**
51
- - `--template` - Project template (nextjs, react, vue)
52
- - `--typescript` - Enable TypeScript
53
- - `--tailwind` - Include Tailwind CSS
54
- - `--yes` - Skip interactive prompts
62
+ - `-f, --force` - Overwrite existing files
63
+ - `--skip-install` - Skip installing dependencies
55
64
 
56
- ### Adding Components
57
-
58
- ```bash
59
- # Add a specific component
60
- foundrykit add button
65
+ **What it does:**
66
+ 1. Validates that you're in a Next.js project
67
+ 2. Installs FoundryKit packages (if not in a workspace)
68
+ 3. Sets up Tailwind CSS v4 with FoundryKit styles
69
+ 4. Creates component directories (`components/ui`, `components/blocks`, `lib`, `hooks`)
70
+ 5. Creates utility files (`lib/utils.ts`)
71
+ 6. Updates your layout file to import FoundryKit styles
72
+ 7. Adds convenient scripts to package.json
61
73
 
62
- # Add multiple components
63
- foundrykit add button input card
74
+ ### `list`
64
75
 
65
- # Add from specific category
66
- foundrykit add --category primitives button
76
+ List all available FoundryKit components and blocks from the live registry.
67
77
 
68
- # Add with specific variant
69
- foundrykit add button --variant outlined
78
+ ```bash
79
+ foundrykit list [options]
70
80
  ```
71
81
 
72
82
  **Options:**
73
- - `--category` - Component category (primitives, components, blocks)
74
- - `--variant` - Component variant
75
- - `--path` - Custom installation path
76
- - `--registry` - Custom registry URL
77
-
78
- ### Listing Available Items
83
+ - `-c, --category <category>` - Filter by category (primitives, components, blocks)
84
+ - `-s, --search <term>` - Search components by name or description
79
85
 
86
+ **Examples:**
80
87
  ```bash
81
- # List all available components
88
+ # List all components
82
89
  foundrykit list
83
90
 
84
- # List components by category
85
- foundrykit list --category primitives
91
+ # List only blocks
92
+ foundrykit list -c blocks
86
93
 
87
- # List with details
88
- foundrykit list --detailed
94
+ # Search for button components
95
+ foundrykit list -s button
89
96
 
90
- # Search for specific components
91
- foundrykit list --search button
97
+ # Components are fetched from https://foundry.umiflow.com/registry
92
98
  ```
93
99
 
94
- **Options:**
95
- - `--category` - Filter by category
96
- - `--detailed` - Show detailed information
97
- - `--search` - Search by name or description
98
- - `--json` - Output in JSON format
100
+ ### `add`
99
101
 
100
- ### Updating Components
102
+ Add a component or block to your project. Components are fetched from the live registry at [foundry.umiflow.com](https://foundry.umiflow.com).
101
103
 
102
104
  ```bash
103
- # Update all components
104
- foundrykit update
105
-
106
- # Update specific component
107
- foundrykit update button
108
-
109
- # Update with specific version
110
- foundrykit update button --version 2.0.0
111
-
112
- # Check for updates without applying
113
- foundrykit update --check
105
+ foundrykit add <component-id> [options]
114
106
  ```
115
107
 
116
108
  **Options:**
117
- - `--version` - Specific version to update to
118
- - `--check` - Check for updates without applying
119
- - `--force` - Force update even if conflicts exist
120
-
121
- ### Project Health Check
109
+ - `-o, --overwrite` - Overwrite existing files
110
+ - `-p, --path <path>` - Custom installation path
122
111
 
112
+ **Examples:**
123
113
  ```bash
124
- # Check project health
125
- foundrykit doctor
114
+ # Interactive mode - select from a list of all components
115
+ foundrykit add
126
116
 
127
- # Fix common issues
128
- foundrykit doctor --fix
117
+ # Add a specific component from the registry
118
+ foundrykit add hero-minimal
129
119
 
130
- # Generate health report
131
- foundrykit doctor --report
132
- ```
120
+ # Add a button component to a custom path
121
+ foundrykit add button -p components/custom
133
122
 
134
- **Options:**
135
- - `--fix` - Automatically fix common issues
136
- - `--report` - Generate detailed health report
137
- - `--verbose` - Show detailed output
123
+ # Overwrite existing component
124
+ foundrykit add card -o
125
+ ```
138
126
 
139
- ## Interactive Mode
127
+ ### `update`
140
128
 
141
- When run without arguments, the CLI enters interactive mode:
129
+ Update an existing component or block to the latest version.
142
130
 
143
131
  ```bash
144
- foundrykit
132
+ foundrykit update <component-id>
145
133
  ```
146
134
 
147
- This provides a guided experience for:
148
- - Project initialization
149
- - Component selection
150
- - Configuration options
151
- - Installation preferences
152
-
153
- ## Configuration
154
-
155
- ### Project Configuration
156
-
157
- Create a `foundrykit.config.js` file in your project root:
158
-
159
- ```javascript
160
- module.exports = {
161
- // Registry configuration
162
- registry: {
163
- url: 'https://registry.foundrykit.com',
164
- token: process.env.FOUNDRYKIT_TOKEN
165
- },
166
-
167
- // Installation preferences
168
- install: {
169
- path: './components',
170
- format: 'tsx',
171
- style: 'tailwind'
172
- },
173
-
174
- // Component preferences
175
- components: {
176
- defaultCategory: 'primitives',
177
- includeTypes: true,
178
- includeTests: false
179
- }
180
- }
135
+ **Example:**
136
+ ```bash
137
+ foundrykit update hero-minimal
181
138
  ```
182
139
 
183
- ### Environment Variables
184
-
185
- - `FOUNDRYKIT_TOKEN` - Registry authentication token
186
- - `FOUNDRYKIT_REGISTRY_URL` - Custom registry URL
187
- - `FOUNDRYKIT_DEBUG` - Enable debug mode
188
-
189
- ## Registry Integration
140
+ ### `doctor`
190
141
 
191
- ### Connecting to Registries
142
+ Check your project's health and configuration.
192
143
 
193
144
  ```bash
194
- # Connect to default registry
195
- foundrykit registry connect
196
-
197
- # Connect to custom registry
198
- foundrykit registry connect --url https://custom-registry.com
199
-
200
- # Authenticate with token
201
- foundrykit registry auth --token YOUR_TOKEN
145
+ foundrykit doctor
202
146
  ```
203
147
 
204
- ### Publishing Components
148
+ This command checks:
149
+ - Next.js installation
150
+ - FoundryKit dependencies
151
+ - Tailwind CSS v4 configuration
152
+ - Project structure
153
+ - Common issues and fixes
205
154
 
206
- ```bash
207
- # Publish component to registry
208
- foundrykit registry publish button
155
+ ## Tailwind CSS v4 Support
209
156
 
210
- # Publish with metadata
211
- foundrykit registry publish button --description "Accessible button component"
157
+ FoundryKit CLI is built for Tailwind CSS v4, which uses CSS-based configuration instead of JavaScript config files. The CLI will:
212
158
 
213
- # Publish with tags
214
- foundrykit registry publish button --tags react,accessible,ui
215
- ```
159
+ 1. Import FoundryKit's pre-configured Tailwind CSS v4 styles
160
+ 2. Set up proper CSS variables for theming
161
+ 3. Configure dark mode support
162
+ 4. Include all necessary Tailwind directives
216
163
 
217
- ## Advanced Usage
164
+ Your `globals.css` will be updated to include:
165
+ ```css
166
+ @import "@foundrykit/tailwind/globals.css";
167
+ ```
218
168
 
219
- ### Custom Templates
169
+ This provides:
170
+ - Complete Tailwind CSS v4 setup
171
+ - CSS variables for colors and theming
172
+ - Dark mode configuration
173
+ - Component-specific styles
174
+ - Proper content scanning for all FoundryKit packages
220
175
 
221
- Create custom component templates:
176
+ ## Working in a Monorepo
222
177
 
223
- ```bash
224
- # Create template from existing component
225
- foundrykit template create button --from ./my-button
178
+ If you're using FoundryKit in a monorepo with workspace packages (like pnpm workspaces), the CLI will:
226
179
 
227
- # Use custom template
228
- foundrykit add button --template ./custom-templates/button
229
- ```
180
+ 1. Detect the workspace configuration
181
+ 2. Skip installing dependencies (they're already linked via workspace)
182
+ 3. Use the local workspace packages instead of npm registry
230
183
 
231
- ### Scripts Integration
184
+ ## Package.json Scripts
232
185
 
233
- Add to your `package.json` scripts:
186
+ After initialization, you'll have these convenient scripts:
234
187
 
235
188
  ```json
236
189
  {
237
190
  "scripts": {
238
- "add:component": "foundrykit add",
239
- "update:components": "foundrykit update",
240
- "check:health": "foundrykit doctor"
191
+ "foundrykit": "foundrykit",
192
+ "fk": "foundrykit"
241
193
  }
242
194
  }
243
195
  ```
244
196
 
245
- ### CI/CD Integration
197
+ Use them like:
198
+ ```bash
199
+ npm run fk list
200
+ pnpm fk add hero-minimal
201
+ yarn fk doctor
202
+ ```
203
+
204
+ ## Project Structure
205
+
206
+ After initialization, your project will have:
246
207
 
247
- ```yaml
248
- # GitHub Actions example
249
- - name: Update components
250
- run: |
251
- foundrykit update --check
252
- foundrykit update --yes
253
208
  ```
209
+ your-nextjs-app/
210
+ ├── app/
211
+ │ ├── layout.tsx # Updated with FoundryKit imports
212
+ │ └── globals.css # Tailwind CSS v4 with FoundryKit styles
213
+ ├── components/
214
+ │ ├── ui/ # UI components
215
+ │ ├── blocks/ # Page blocks
216
+ │ └── providers.tsx # Theme provider setup
217
+ ├── lib/
218
+ │ └── utils.ts # Utility functions (cn, etc.)
219
+ └── hooks/ # Custom React hooks
220
+ ```
221
+
222
+ ## Requirements
223
+
224
+ - Node.js 18.0.0 or higher
225
+ - Next.js 14.0.0 or higher
226
+ - Tailwind CSS v4
227
+ - React 18 or 19
254
228
 
255
229
  ## Troubleshooting
256
230
 
257
- ### Common Issues
231
+ ### Command not found
258
232
 
259
- **Component not found:**
260
- ```bash
261
- # Check available components
262
- foundrykit list --search component-name
233
+ If you get `command not found: foundrykit` after global installation with pnpm:
263
234
 
264
- # Update registry cache
265
- foundrykit registry refresh
266
- ```
235
+ 1. Ensure your pnpm global bin directory is in your PATH:
236
+ ```bash
237
+ export PATH="$PNPM_HOME:$PATH"
238
+ ```
267
239
 
268
- **Installation fails:**
269
- ```bash
270
- # Check project health
271
- foundrykit doctor
240
+ 2. Or use the local installation method:
241
+ ```bash
242
+ npx @foundrykit/cli [command]
243
+ ```
272
244
 
273
- # Clear cache and retry
274
- foundrykit cache clear
275
- foundrykit add component-name
276
- ```
245
+ ### Workspace Detection
277
246
 
278
- **Version conflicts:**
279
- ```bash
280
- # Check for conflicts
281
- foundrykit update --check
247
+ If you're in a monorepo and the CLI tries to install packages from npm:
282
248
 
283
- # Force update
284
- foundrykit update --force
285
- ```
249
+ 1. Ensure your `pnpm-workspace.yaml` is properly configured
250
+ 2. Check that workspace packages use `workspace:*` protocol
251
+ 3. Use `--skip-install` flag and link packages manually if needed
286
252
 
287
- ### Debug Mode
253
+ ### Tailwind CSS v4
288
254
 
289
- Enable debug mode for detailed logging:
255
+ If you're migrating from Tailwind CSS v3:
290
256
 
291
- ```bash
292
- FOUNDRYKIT_DEBUG=1 foundrykit add button
293
- ```
257
+ 1. Remove `tailwind.config.js` or `tailwind.config.ts`
258
+ 2. Update your CSS imports to use `@import` directives
259
+ 3. Run `foundrykit init --force` to set up v4 configuration
294
260
 
295
- ## API Reference
261
+ ## Contributing
296
262
 
297
- ### Command Options
263
+ Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
298
264
 
299
- All commands support these common options:
265
+ ## License
300
266
 
301
- - `--help` - Show command help
302
- - `--version` - Show CLI version
303
- - `--verbose` - Enable verbose output
304
- - `--quiet` - Suppress output
305
- - `--json` - Output in JSON format
267
+ MIT © FoundryKit
306
268
 
307
- ### Exit Codes
269
+ ## Registry
308
270
 
309
- - `0` - Success
310
- - `1` - General error
311
- - `2` - Configuration error
312
- - `3` - Network error
313
- - `4` - Permission error
271
+ FoundryKit components are served from a live registry hosted at [foundry.umiflow.com](https://foundry.umiflow.com). The registry automatically updates when new components are released on GitHub.
314
272
 
315
- ## Contributing
273
+ ### Registry Endpoints
316
274
 
317
- When contributing to the CLI:
275
+ - **Component List**: `https://foundry.umiflow.com/registry` - Returns all component metadata
276
+ - **Individual Component**: `https://foundry.umiflow.com/registry/[id]` - Returns full component data including files
277
+ - **Filtered List**: `https://foundry.umiflow.com/registry?category=primitives&search=button` - Supports filtering
318
278
 
319
- 1. Follow the existing command structure
320
- 2. Add comprehensive help text
321
- 3. Include TypeScript definitions
322
- 4. Add unit tests
323
- 5. Update this README
324
- 6. Ensure cross-platform compatibility
279
+ ### Custom Registry
325
280
 
326
- ## License
281
+ To use a custom registry, set the environment variable:
282
+
283
+ ```bash
284
+ export FOUNDRYKIT_REGISTRY_URL=https://your-registry.com
285
+ foundrykit list
286
+ ```
287
+
288
+ ### Offline Mode
289
+
290
+ If the registry is unavailable, the CLI will automatically fall back to a local component cache, ensuring you can always work offline.
291
+
292
+ ## Support
327
293
 
328
- MIT
294
+ - 📧 Email: support@foundrykit.dev
295
+ - 🐛 Issues: [GitHub Issues](https://github.com/foundrykit/foundrykit/issues)
296
+ - 📖 Docs: [https://foundrykit.dev](https://foundrykit.dev)