Skip to content

Commit e92e28d

Browse files
chrisbbreuerchrisbbreuer
committed
feat: add global support
chore: lint
1 parent 03b9fbd commit e92e28d

File tree

12 files changed

+895
-16
lines changed

12 files changed

+895
-16
lines changed

‎docs/.vitepress/config.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ const nav = [
4141
},
4242
{
4343
text: 'Contributing',
44-
link: 'https://github.com/stacksjs/stacks/blob/main/https://github.com/stacksjs/contributing',
44+
link: 'https://github.com/stacksjs/contributing',
4545
},
4646
],
4747
},

‎docs/api/reference.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,65 @@ interface Installation {
379379
version: Version
380380
}
381381
}
382+
383+
interface PackageRequirement {
384+
project: string
385+
constraint: SemverRange
386+
global?: boolean
387+
}
388+
389+
interface DependencyConfiguration {
390+
/** Top-level global flag - applies to all dependencies unless overridden */
391+
global?: boolean
392+
/** Package dependencies with optional individual global flags */
393+
dependencies: DependencySpec[]
394+
/** Environment variables */
395+
env?: Record<string, string>
396+
}
397+
398+
type DependencySpec =
399+
| string // Simple format: "node@22" (defaults to global: false)
400+
| { // Object format with options
401+
version?: string
402+
global?: boolean // Individual package global flag (overrides top-level)
403+
}
404+
```
405+
406+
### Global Flag Types
407+
408+
```typescript
409+
interface GlobalDependencyOptions {
410+
/** Individual package global configuration */
411+
packageGlobal?: boolean
412+
/** Top-level global configuration (applies to all packages) */
413+
topLevelGlobal?: boolean
414+
/** Resolved global setting (considering precedence) */
415+
resolvedGlobal: boolean
416+
}
417+
418+
// Example dependency configurations
419+
interface DependencyExamples {
420+
// String format (defaults to local installation)
421+
simple: 'node@22'
422+
423+
// Object format with individual global flag
424+
individual: {
425+
version: '22.1.0'
426+
global: true
427+
}
428+
429+
// Top-level global with selective overrides
430+
topLevel: {
431+
global: true
432+
dependencies: {
433+
'node@22': string
434+
'[email protected]': {
435+
version: '5.0.4'
436+
global: false // Override top-level global
437+
}
438+
}
439+
}
440+
}
382441
```
383442

384443
## Usage Examples
@@ -454,6 +513,85 @@ await dump('/path/to/project', { dryrun: false, quiet: false })
454513
await integrate('/path/to/project')
455514
```
456515

516+
### Dependency Management with Global Flags
517+
518+
```typescript
519+
import { dump } from '@stacksjs/launchpad'
520+
521+
// Example: dependencies.yaml with global flag configurations
522+
const dependencyConfig = `
523+
# Top-level global flag (applies to all packages)
524+
global: true
525+
dependencies:
526+
# Uses top-level global: true
527+
- node@22
528+
- python@3.12
529+
530+
# Individual override to local installation
531+
typescript@5.0:
532+
version: 5.0.4
533+
global: false
534+
535+
# Individual global configuration
536+
git@2.42:
537+
version: 2.42.0
538+
global: true
539+
540+
env:
541+
NODE_ENV: development
542+
`
543+
544+
// Generate environment with global flag support
545+
await dump('/path/to/project', { dryrun: false, quiet: false })
546+
547+
// The dump function will:
548+
// - Install node@22 and [email protected] globally (to /usr/local)
549+
// - Install [email protected] locally (to project directory)
550+
// - Install [email protected] globally (individual flag)
551+
```
552+
553+
### Global Flag Resolution Examples
554+
555+
```typescript
556+
// Example dependency configurations and their resolved global settings
557+
558+
// 1. String format (defaults to local)
559+
const stringFormat = {
560+
dependencies: ['node@22', '[email protected]'],
561+
resolved: [
562+
{ package: 'node@22', global: false }, // default
563+
{ package: '[email protected]', global: false } // default
564+
]
565+
}
566+
567+
// 2. Individual global flags
568+
const individualFlags = {
569+
dependencies: {
570+
'node@22': { version: '22.1.0', global: true },
571+
'[email protected]': { version: '3.12.1', global: false }
572+
},
573+
resolved: [
574+
{ package: 'node@22', global: true }, // individual flag
575+
{ package: '[email protected]', global: false } // individual flag
576+
]
577+
}
578+
579+
// 3. Top-level global with overrides
580+
const topLevelWithOverrides = {
581+
global: true, // Top-level flag
582+
dependencies: {
583+
'node@22': '22.1.0', // string format
584+
'[email protected]': { version: '3.12.1' }, // object without global
585+
'[email protected]': { version: '5.0.4', global: false } // override to local
586+
},
587+
resolved: [
588+
{ package: 'node@22', global: true }, // uses top-level
589+
{ package: '[email protected]', global: true }, // uses top-level
590+
{ package: '[email protected]', global: false } // individual override
591+
]
592+
}
593+
```
594+
457595
### Creating Shims
458596

459597
```typescript

‎docs/config.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,84 @@ JavaScript format (`.launchpadrc`):
9696
}
9797
```
9898

99+
## Dependency File Configuration
100+
101+
Launchpad supports flexible dependency configuration with global installation options:
102+
103+
### Basic Dependency Format
104+
105+
```yaml
106+
# dependencies.yaml
107+
dependencies:
108+
- node@22
109+
- [email protected]
110+
111+
env:
112+
NODE_ENV: development
113+
```
114+
115+
### Global Installation Configuration
116+
117+
Control whether packages are installed globally or locally with the `global` flag:
118+
119+
#### Individual Package Global Flags
120+
121+
```yaml
122+
# dependencies.yaml
123+
dependencies:
124+
node@22:
125+
version: 22.1.0
126+
global: true # Install to /usr/local
127+
[email protected]:
128+
version: 3.12.1
129+
global: false # Install to project directory
130+
# String format defaults to local installation
131+
- [email protected]
132+
```
133+
134+
#### Top-Level Global Flag
135+
136+
Apply global installation to all dependencies:
137+
138+
```yaml
139+
# dependencies.yaml
140+
global: true # All packages install globally unless overridden
141+
dependencies:
142+
- node@22
143+
- [email protected]
144+
- [email protected]
145+
[email protected]:
146+
version: 5.0.4
147+
global: false # Override: install locally for this project
148+
```
149+
150+
#### Global Flag Precedence
151+
152+
The precedence order for global installation flags:
153+
154+
1. **Individual package `global` flag** (highest priority)
155+
2. **Top-level `global` flag**
156+
3. **Default behavior** (project-local installation)
157+
158+
```yaml
159+
# Example showing precedence
160+
global: true # Top-level: install globally
161+
dependencies:
162+
- node@22 # Uses top-level: global=true
163+
- [email protected] # Uses top-level: global=true
164+
[email protected]:
165+
version: 1.2.3
166+
global: false # Override: local installation
167+
[email protected]:
168+
version: 5.0.4 # Uses top-level: global=true
169+
```
170+
171+
### Installation Behavior
172+
173+
- **Global packages** (`global: true`): Installed to `/usr/local` (or user-configured global path)
174+
- **Local packages** (`global: false` or default): Installed to project-specific directories
175+
- **Mixed installations**: You can have both global and local packages in the same project
176+
99177
## Configuration Options
100178

101179
### General Options

‎docs/examples.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,81 @@ env:
8585
MODEL_DIR: ./models
8686
```
8787
88+
### Global Tool Installation
89+
90+
Use the `global` flag to install development tools system-wide:
91+
92+
```yaml
93+
# dependencies.yaml - Global development tools
94+
global: true
95+
dependencies:
96+
- node@22
97+
- [email protected]
98+
- [email protected]
99+
- [email protected]
100+
101+
env:
102+
# Global environment variables
103+
EDITOR: code
104+
PAGER: less
105+
```
106+
107+
### Mixed Global and Local Packages
108+
109+
Combine global tools with project-specific dependencies:
110+
111+
```yaml
112+
# dependencies.yaml - Mixed installation
113+
global: true # Default to global installation
114+
dependencies:
115+
# Global development tools
116+
- node@22
117+
- [email protected]
118+
- [email protected]
119+
120+
# Project-specific overrides
121+
[email protected]:
122+
version: 5.0.4
123+
global: false # Install locally for this project
124+
125+
[email protected]:
126+
version: 8.50.0
127+
global: false # Project-specific linting config
128+
129+
env:
130+
NODE_ENV: development
131+
PROJECT_NAME: my-mixed-project
132+
```
133+
134+
### Team Development Environment
135+
136+
Configure a standardized team environment with global shared tools:
137+
138+
```yaml
139+
# dependencies.yaml - Team standard
140+
dependencies:
141+
# Global shared tools (available system-wide)
142+
node@22:
143+
version: 22.1.0
144+
global: true
145+
[email protected]:
146+
version: 3.12.1
147+
global: true
148+
docker@24:
149+
version: 24.0.0
150+
global: true
151+
152+
# Project-specific tools (isolated per project)
153+
- [email protected]
154+
- [email protected]
155+
- [email protected]
156+
157+
env:
158+
NODE_ENV: development
159+
TEAM_CONFIG: standard-v2
160+
CI_ENVIRONMENT: local
161+
```
162+
88163
### Full-Stack Development
89164

90165
```yaml
@@ -248,6 +323,70 @@ env:
248323
DEBUG: ${{ env.NODE_ENV == 'development' && 'app:*' || '' }}
249324
```
250325

326+
### Individual Package Global Configuration
327+
328+
Fine-grained control over which packages are global vs local:
329+
330+
```yaml
331+
# dependencies.yaml
332+
dependencies:
333+
# Core development tools - install globally
334+
node@22:
335+
version: 22.1.0
336+
global: true
337+
[email protected]:
338+
version: 3.12.1
339+
global: true
340+
[email protected]:
341+
version: 2.42.0
342+
global: true
343+
344+
# Project-specific tools - install locally
345+
[email protected]:
346+
version: 5.0.4
347+
global: false
348+
[email protected]:
349+
version: 29.7.0
350+
global: false
351+
352+
# String format - defaults to local
353+
- [email protected]
354+
- [email protected]
355+
356+
env:
357+
NODE_ENV: development
358+
PROJECT_TYPE: mixed-environment
359+
```
360+
361+
### Global Tools for Development Machine Setup
362+
363+
Use global flag to set up a development machine with system-wide tools:
364+
365+
```yaml
366+
# dependencies.yaml - Development machine setup
367+
global: true
368+
dependencies:
369+
# Core runtimes
370+
- node@22
371+
- [email protected]
372+
- [email protected]
373+
- [email protected]
374+
375+
# Development tools
376+
- [email protected]
377+
- [email protected]
378+
- [email protected]
379+
380+
# Container tools
381+
- [email protected]
382+
- [email protected]
383+
384+
env:
385+
# Global development settings
386+
DOCKER_DEFAULT_PLATFORM: linux/amd64
387+
KUBECTL_EXTERNAL_DIFF: code --wait --diff
388+
```
389+
251390
## Scripting Examples
252391

253392
### Automated Project Setup Script

0 commit comments

Comments
 (0)