0
# Liftoff
1

2
Liftoff is a Node.js library that simplifies the creation and management of command-line tools by automatically handling common tasks like finding and loading configuration files, resolving local module paths, managing v8 flags, and supporting various file extensions through custom loaders.
3

4
## Package Information
5

6
- **Package Name**: liftoff
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install liftoff`
10

11
## Core Imports
12

13
```javascript
14
const Liftoff = require('liftoff');
15
```
16

17
For ES modules:
18

19
```javascript
20
import Liftoff from 'liftoff';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Liftoff = require('liftoff');
27

28
// Create a new CLI launcher
29
const MyApp = new Liftoff({
30
  name: 'myapp',
31
  extensions: {
32
    '.js': null,
33
    '.json': null,
34
    '.coffee': 'coffee-script/register',
35
  },
36
  v8flags: ['--harmony']
37
});
38

39
// Launch the application
40
MyApp.prepare({}, function(env) {
41
  MyApp.execute(env, function(env, argv) {
42
    // Your CLI application logic here
43
    console.log('Current working directory:', env.cwd);
44
    console.log('Config file found at:', env.configPath);
45
    console.log('Local module path:', env.modulePath);
46
  });
47
});
48
```
49

50
## Architecture
51

52
Liftoff is built around several key components:
53

54
- **Environment Builder**: Discovers configuration files, local modules, and sets up the execution environment
55
- **Event System**: EventEmitter-based architecture for lifecycle hooks and status updates
56
- **Process Management**: Handles v8 flag detection and automatic process respawning when needed
57
- **Configuration System**: Supports multiple config file formats with extension loading and inheritance
58
- **Module Resolution**: Locates and loads local versions of CLI tools and their dependencies
59

60
## Capabilities
61

62
### Core Lifecycle Management
63

64
Manages the complete lifecycle of CLI tool execution from environment preparation to final execution with automatic configuration discovery and process management.
65

66
```javascript { .api }
67
/**
68
 * Creates a new Liftoff instance for launching CLI applications
69
 * @param opts - Configuration options for the CLI launcher
70
 * @throws {Error} If name is not provided and any of processTitle, moduleName, or configName are missing
71
 */
72
function Liftoff(opts: LiftoffOptions): Liftoff;
73

74
interface LiftoffOptions {
75
  /** Name of the CLI tool (sets processTitle, moduleName, configName if not specified) */
76
  name?: string;
77
  /** Title to set for the process (required if name not provided) */
78
  processTitle?: string;
79
  /** Name of the local module to find and require (required if name not provided) */
80
  moduleName?: string;
81
  /** Base name of configuration files to search for (required if name not provided) */
82
  configName?: string;
83
  /** File extensions and their loaders */
84
  extensions?: { [ext: string]: string | null };
85
  /** V8 flags to apply during respawn */
86
  v8flags?: string[] | ((callback: (err: Error | null, flags?: string[]) => void) => void);
87
  /** Function to handle shell completions */
88
  completions?: (type: string) => void;
89
  /** Array of configuration file search specifications */
90
  configFiles?: ConfigFileSpec[];
91
  /** Additional search paths for configuration discovery */
92
  searchPaths?: string[];
93
}
94

95
interface ConfigFileSpec {
96
  /** Base name of the config file */
97
  name?: string;
98
  /** Path to search in */
99
  path: string;
100
  /** File extensions to try */
101
  extensions?: string[] | { [ext: string]: string | null };
102
  /** Base directory for relative paths */
103
  cwd?: string;
104
  /** Whether to search up the directory tree */
105
  findUp?: boolean;
106
}
107
```
108

109
[Core Lifecycle](./core-lifecycle.md)
110

111
### Environment Building
112

113
Builds execution environment by discovering configuration files, resolving module paths, and preparing the runtime context with all necessary metadata.
114

115
```javascript { .api }
116
/**
117
 * Builds the execution environment with configuration and module resolution
118
 * @param opts - Options for environment building
119
 * @returns Environment object with discovered paths and configuration
120
 */
121
buildEnvironment(opts?: EnvironmentOptions): Environment;
122

123
interface EnvironmentOptions {
124
  /** Current working directory override */
125
  cwd?: string;
126
  /** Explicit path to configuration file */
127
  configPath?: string;
128
  /** Modules to preload before execution */
129
  preload?: string | string[];
130
  /** Completion data for shell completions */
131
  completion?: any;
132
}
133

134
interface Environment {
135
  /** Current working directory */
136
  cwd: string;
137
  /** Array of modules that will be preloaded */
138
  preload: string[];
139
  /** Regex or array of config file names searched */
140
  configNameSearch: RegExp | string[];
141
  /** Full path to found configuration file */
142
  configPath: string | null;
143
  /** Directory containing the configuration file */
144
  configBase: string | null;
145
  /** Full path to the local module */
146
  modulePath: string | null;
147
  /** Contents of the local module's package.json */
148
  modulePackage: object;
149
  /** Array of found configuration file paths */
150
  configFiles: (string | null)[];
151
  /** Array of loaded configuration objects */
152
  config: object[];
153
}
154
```
155

156
[Environment Building](./environment-building.md)
157

158
### Configuration Management
159

160
Handles discovery and loading of configuration files with support for multiple formats, inheritance through extends, and flexible search patterns.
161

162
```javascript { .api }
163
/**
164
 * Configuration file inheritance and loading system
165
 * Supports extends property for config inheritance
166
 * Handles circular reference detection
167
 * Loads custom extensions through registered loaders
168
 */
169
interface ConfigurationSystem {
170
  /** Extend configurations support circular detection */
171
  extends?: string | ConfigFileSpec;
172
  /** Override config path discovery */
173
  [configName: string]?: string;
174
  /** Additional modules to preload */
175
  preload?: string | string[];
176
}
177
```
178

179
[Configuration Management](./configuration.md)
180

181
### Event System
182

183
EventEmitter-based system providing lifecycle hooks for module preloading, loader registration, and process respawning with detailed status information.
184

185
```javascript { .api }
186
/**
187
 * Liftoff extends EventEmitter and emits lifecycle events
188
 */
189
interface LiftoffEvents {
190
  /** Emitted before attempting to preload a module */
191
  'preload:before': (moduleName: string) => void;
192
  /** Emitted when a module is successfully preloaded */
193
  'preload:success': (moduleName: string, module: any) => void;
194
  /** Emitted when module preloading fails */
195
  'preload:failure': (moduleName: string, error: Error) => void;
196
  /** Emitted when a file extension loader is successfully registered */
197
  'loader:success': (loaderName: string, module: any) => void;
198
  /** Emitted when a file extension loader fails to load */
199
  'loader:failure': (loaderName: string, error: Error) => void;
200
  /** Emitted when process is respawned for v8 flags */
201
  'respawn': (flags: string[], childProcess: object) => void;
202
}
203
```
204

205
[Event System](./events.md)
206

207
## Types
208

209
```javascript { .api }
210
/**
211
 * Main Liftoff class extending EventEmitter
212
 */
213
class Liftoff extends EventEmitter {
214
  constructor(opts: LiftoffOptions);
215
  
216
  /** Build execution environment */
217
  buildEnvironment(opts?: EnvironmentOptions): Environment;
218
  
219
  /** Prepare environment and invoke callback */
220
  prepare(opts: EnvironmentOptions, callback: (env: Environment) => void): void;
221
  
222
  /** Execute application with environment */
223
  execute(env: Environment, callback: (env: Environment, argv: string[]) => void): void;
224
  execute(env: Environment, forcedFlags: string[], callback: (env: Environment, argv: string[]) => void): void;
225
  
226
  /** Require a module from local working directory */
227
  requireLocal(moduleName: string, basedir: string): any;
228
  
229
  /** Handle v8flags resolution */
230
  handleFlags(callback: (err: Error | null, flags?: string[]) => void): void;
231
}
232
```