0
# @js-lib/cli
1

2
@js-lib/cli is a comprehensive command-line interface tool for scaffolding JavaScript and TypeScript third-party libraries. It provides developers with a complete framework for quickly creating new library projects with modern development practices including linting, testing, build systems, and CI/CD integration.
3

4
## Package Information
5

6
- **Package Name**: @js-lib/cli
7
- **Package Type**: npm
8
- **Language**: JavaScript  
9
- **Installation**: `npx @js-lib/cli new mylib`
10
- **Node.js Requirement**: >= 18.0.0
11

12
## Core Imports
13

14
This package is a CLI tool and is not intended for programmatic import. It is executed via npx:
15

16
```bash
17
# Execute the CLI tool
18
npx @js-lib/cli [command] [options]
19
```
20

21
For programmatic access to internal utilities (advanced usage):
22

23
```javascript
24
// Not recommended - internal APIs may change
25
const { checkProjectExists } = require('@js-lib/cli/util/file');
26
const { init } = require('@js-lib/cli/util/log');
27
```
28

29
## Basic Usage
30

31
```bash
32
# Interactive project creation
33
npx @js-lib/cli new my-awesome-lib
34
# Follow the interactive prompts to configure:
35
# - Project name
36
# - NPM package name
37
# - UMD name
38
# - GitHub username  
39
# - Template type (JavaScript or TypeScript)
40
# - Package manager preference
41

42
cd my-awesome-lib
43
npm install
44
npm run build
45
npm test
46
```
47

48
## Architecture
49

50
@js-lib/cli is built around several key components:
51

52
- **CLI Interface**: Command-line argument parsing and interactive prompts using yargs and inquirer
53
- **Template System**: Separate JavaScript and TypeScript project templates with complete scaffolding
54
- **File Operations**: Comprehensive file copying, template processing, and JSON manipulation utilities
55
- **Project Management**: Initialize new projects and update existing ones with version migrations
56
- **Build Integration**: Modern build toolchain with Rollup, ESLint, Prettier, Mocha, and GitHub Actions
57

58
## Capabilities
59

60
### File Utilities
61

62
Internal utilities for file operations, template processing, and JSON manipulation used by the CLI.
63

64
```javascript { .api }
65
// File existence checking
66
function checkProjectExists(cmdPath: string, name: string): boolean;
67

68
// Template processing and file operations
69
function copyDir(from: string, to: string, options?: object): void;
70
function copyFile(from: string, to: string, opt?: {cover: boolean}): void;
71
function copyTmpl(from: string, to: string, data?: object, opt?: {cover: boolean}): void;
72
function readTmpl(from: string, data?: object): string;
73
function readJSON(from: string): object;
74

75
// JSON manipulation
76
function mergeObj2JSON(object: object, to: string): void;
77
function mergeJSON2JSON(from: string, to: string): void;
78
function mergeTmpl2JSON(from: string, to: string, data?: object): void;
79
function deleteJSONKeys(keysObj: object, to: string): void;
80

81
// File content manipulation
82
function replaceFileLine(filepath: string, match: RegExp, to: string): void;
83
function deleteFileLine(filepath: string, match: RegExp): void;
84
function replaceFileText(filepath: string, replacerList: Array<{from: RegExp|string, to: string|Function}>): void;
85
function insertText2File(text: string, filepath: string, line?: number): void;
86

87
// Directory operations
88
function deleteFile(filePath: string): void;
89
function deleteDir(dirPath: string): void;
90
```
91

92
[File Utilities](./file-utilities.md)
93

94
### Project Creation
95

96
Create new JavaScript or TypeScript library projects with complete scaffolding including build systems, testing, linting, and CI/CD.
97

98
```bash { .api }
99
jslib new [projectname] [options]
100
jslib n [projectname] [options]
101

102
Options:
103
  --force, -f              Force create (overwrite existing)
104
  --config, -c             Initialize only configuration file  
105
  --npmname, -n <name>     NPM package name
106
  --umdname, --umd <name>  UMD name for package
107
  --username, -u <name>    GitHub username
108
  --type, -t <type>        Template type (js/ts)
109
  --manager, -m <manager>  Package manager (npm/no install)
110
```
111

112
[Project Creation](./project-creation.md)
113

114
### Project Updates
115

116
Update existing jslib projects to the latest template version and tooling configuration.
117

118
```bash { .api }
119
jslib update
120
jslib u
121

122
Requirements:
123
- Must be run in directory containing jslib.json
124
- Project must have been created with @js-lib/cli
125
```
126

127
[Project Updates](./project-updates.md)
128

129
### Interactive Configuration
130

131
Prompt-based configuration system for collecting project metadata and preferences when creating new projects.
132

133
```bash { .api }
134
# Interactive prompts are automatically triggered when:
135
# - Required information is not provided via command line options
136
# - Creating a new project without all necessary parameters
137

138
# The CLI will prompt for:
139
# - Project name (if not provided as argument)
140
# - NPM package name (with validation)  
141
# - UMD global variable name
142
# - GitHub username
143
# - Template type (JavaScript or TypeScript)
144
# - Package manager preference (npm or no install)
145
```
146

147
[Interactive Configuration](./interactive-configuration.md)
148

149
### Template System
150

151
Template processing engine for generating project files with variable substitution using EJS-style syntax.
152

153
```javascript { .api }
154
// Template variables available during project creation
155
interface TemplateVariables {
156
  name: string;        // Project display name
157
  npmname: string;     // NPM package name  
158
  umdname: string;     // UMD global variable name
159
  username: string;    // GitHub username
160
  type: 'js' | 'ts';  // Template type (JavaScript or TypeScript)
161
  manager: 'npm' | null; // Package manager
162
  version: string;     // CLI version
163
  pathname: string;    // Directory name
164
}
165

166
// Template files use EJS-style syntax:
167
// <%=variable%>     - Output variable value
168
// <% if (condition) { %> - Conditional blocks  
169
// <% for (var i=0; i<items.length; i++) { %> - Loop constructs
170
```
171

172
[Template System](./template-system.md)
173

174
### Module System
175

176
Internal module structure for organizing template generation and project scaffolding functionality.
177

178
```javascript { .api }
179
// Module initialization and update functions
180
interface ProjectModule {
181
  init(cmdPath: string, name: string, option: ProjectOptions): void | Promise<void>;
182
  update?(cmdPath: string, option: ProjectOptions): void;
183
}
184

185
// Available modules:
186
// - config: Project configuration (jslib.json)
187
// - root: Root files (README, LICENSE, etc.)
188
// - lint: ESLint and Prettier configuration
189
// - packagejson: package.json generation and updates
190
// - demo: Demo files and usage examples
191
// - build: Rollup build configuration
192
// - test: Mocha testing setup
193
// - manager: Package manager integration (npm install)
194
```
195

196
### Package Manager Integration
197

198
Automated dependency installation and git repository initialization during project creation.
199

200
```javascript { .api }
201
/**
202
 * Initialize git repository and install dependencies
203
 * @param cmdPath - Base directory path
204
 * @param name - Project directory name
205
 * @param option - Project configuration including manager preference
206
 * @returns Promise that resolves when installation completes
207
 */
208
function managerInit(
209
  cmdPath: string, 
210
  name: string, 
211
  option: ProjectOptions
212
): Promise<void>;
213

214
// Manager options:
215
// - 'npm': Run npm install after project creation
216
// - null: Skip dependency installation
217
```
218

219
## Types
220

221
```javascript { .api }
222
// Project initialization options
223
interface ProjectOptions {
224
  pathname: string;    // Directory name to create
225
  name: string;        // Project display name
226
  npmname: string;     // NPM package name
227
  umdname: string;     // UMD global variable name  
228
  username: string;    // GitHub username
229
  type: 'js' | 'ts';  // Template type
230
  manager: 'npm' | null; // Package manager
231
  version: string;     // CLI version
232
}
233

234
// Command line arguments structure
235
interface CLIArguments {
236
  _: string[];         // Positional arguments
237
  force?: boolean;     // Force overwrite flag
238
  config?: boolean;    // Config-only flag
239
  npmname?: string;    // NPM name option
240
  umdname?: string;    // UMD name option  
241
  username?: string;   // Username option
242
  type?: string;       // Type option
243
  manager?: string;    // Manager option
244
}
245
```