@cnpx/cnpx 0.0.5-dev.20260405125711 → 0.0.5-dev.20260405131159

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.
Files changed (2) hide show
  1. package/README.md +45 -14
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -10,6 +10,7 @@ An interactive CLI tool for creating new projects from curated templates hosted
10
10
  - [Quick Start](#quick-start)
11
11
  - [CLI Flags](#cli-flags)
12
12
  - [Interactive Flow](#interactive-flow)
13
+ - [Offline Mode](#offline-mode)
13
14
  - [Templates](#templates)
14
15
  - [Package Manager Detection](#package-manager-detection)
15
16
  - [Auto-Update Check](#auto-update-check)
@@ -74,13 +75,14 @@ cnpx --name my-app --template backend/fastify
74
75
 
75
76
  All flags are optional. Any omitted value is collected interactively.
76
77
 
77
- | Flag | Type | Description |
78
- | ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | `-n`, `--name` | `string` | Output directory / project name. Validated against filesystem rules — see [Validation](#validation). |
80
- | `-c`, `--category` | `string` | Template category (top-level directory in the template repo). Skips the category selection prompt. |
81
- | `-t`, `--template` | `string` | Template name. Accepts bare name (`starter`) or `category/template` slash syntax. Slash syntax also sets `--category`. |
82
- | `-f`, `--force` | `boolean` | Overwrite a non-empty target directory without prompting. Skips both the overwrite confirmation and the final "create project?" confirmation. |
83
- | `-h`, `--help` | `boolean` | Print the help message and exit. Also triggered by passing `help` as a bare argument. |
78
+ | Flag | Short | Type | Description |
79
+ | ------------ | ----- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `--name` | `-n` | `string` | Output directory / project name. Validated against filesystem rules — see [Validation](#validation). |
81
+ | `--category` | `-c` | `string` | Template category (top-level directory in the template repo). Skips the category selection prompt. |
82
+ | `--template` | `-t` | `string` | Template name. Accepts bare name (`fastify`) or `category/template` slash syntax. Slash syntax also sets `--category`. |
83
+ | `--force` | `-f` | `boolean` | Overwrite a non-empty target directory without prompting. Skips both the overwrite confirmation and the final "create project?" confirmation. |
84
+ | `--offline` | `-o` | `boolean` | Run in offline mode using locally cached templates. Requires `--template` in `category/template` format. |
85
+ | `--help` | `-h` | `boolean` | Print the help message and exit. Also triggered by passing `help` as a bare argument. |
84
86
 
85
87
  ### Examples
86
88
 
@@ -100,6 +102,9 @@ cnpx --category backend --template fastify
100
102
  # All flags — no prompts at all
101
103
  cnpx -n my-app -t backend/fastify -f
102
104
 
105
+ # Offline mode — uses cached templates, no network required
106
+ cnpx --offline -n my-app -t backend/fastify
107
+
103
108
  # Print help
104
109
  cnpx --help
105
110
  ```
@@ -134,6 +139,29 @@ update check → project name → overwrite? → category → template → confi
134
139
 
135
140
  ---
136
141
 
142
+ ## Offline Mode
143
+
144
+ Pass `--offline` (or `-o`) to skip all network requests and clone directly from degit's local cache. This is useful in environments without internet access or when you want faster re-scaffolding of a template you've cloned before.
145
+
146
+ ```bash
147
+ cnpx --offline --name my-app --template backend/fastify
148
+ ```
149
+
150
+ **Requirements for offline mode:**
151
+
152
+ - `--template` must be provided in `category/template` slash format — bare template names are not accepted.
153
+ - The template must have been previously cloned at least once so degit has a local cache entry.
154
+
155
+ If either condition is not met, the CLI exits with an error:
156
+
157
+ ```
158
+ ✖ Offline mode requires a specific template.
159
+ ```
160
+
161
+ > Templates are cached by degit automatically on first clone. No manual setup is needed.
162
+
163
+ ---
164
+
137
165
  ## Templates
138
166
 
139
167
  All templates live in the [xcfio/template](https://github.com/xcfio/template) GitHub repository. The directory structure is:
@@ -155,7 +183,7 @@ The following top-level directories are always excluded from the category list:
155
183
 
156
184
  Templates are cloned using **degit** with `cache: true`, so repeated clones of the same template are served from a local cache instead of re-downloading from GitHub.
157
185
 
158
- > **API rate limits:** Template lists are fetched live from the GitHub Contents API. If you encounter `API rate limit exceeded`, wait a few minutes and try again. Authenticated requests are not currently supported.
186
+ > **API rate limits:** Template lists are fetched live from the GitHub Contents API. If you encounter `API rate limit exceeded`, wait a few minutes and try again. Use `--offline` mode to bypass this entirely when you already have the template cached.
159
187
 
160
188
  ---
161
189
 
@@ -195,7 +223,7 @@ Versions are compared with a custom semver parser that handles pre-release ident
195
223
  └──────────────────────────────────╯
196
224
  ```
197
225
 
198
- The check is non-blocking — any error (network failure, rate limit) is silently swallowed so it never interrupts the main flow.
226
+ The check is non-blocking — any error (network failure, rate limit) is silently swallowed so it never interrupts the main flow. In offline mode the update check is skipped entirely.
199
227
 
200
228
  ---
201
229
 
@@ -226,10 +254,10 @@ After name validation, the resolved path is checked:
226
254
 
227
255
  ### Exit codes
228
256
 
229
- | Code | Meaning |
230
- | ---- | ----------------------------------------------------------------------------- |
231
- | `0` | Success or user-cancelled |
232
- | `1` | Validation error, target-is-file error, API rate limit, or uncaught exception |
257
+ | Code | Meaning |
258
+ | ---- | ------------------------------------------------------------------------------------------------------- |
259
+ | `0` | Success or user-cancelled |
260
+ | `1` | Validation error, target-is-file error, missing offline template, API rate limit, or uncaught exception |
233
261
 
234
262
  ---
235
263
 
@@ -263,7 +291,11 @@ All runtime dependencies are pure-JS and work without native addons.
263
291
  src/
264
292
  ├── bin.ts # Entry point — wires showHelp + main
265
293
  ├── main.ts # Orchestrates the full interactive flow
294
+ ├── offlineRunner.ts # Offline mode flow (--offline flag)
266
295
  ├── clone.ts # Wraps degit clone with a spinner
296
+ ├── confirmProject.ts # Extracted final confirmation prompt logic
297
+ ├── getProjectName.ts # Extracted project name prompt + validation
298
+ ├── parseTemplate.ts # Parses --category / --template flags into [cat, tpl]
267
299
  ├── checkForUpdate.ts # npm registry version check + semver comparison
268
300
  ├── getCategories.ts # GitHub API → category list
269
301
  ├── getTemplates.ts # GitHub API → template list for a category
@@ -318,7 +350,6 @@ The package is published publicly to npm under the `latest` tag:
318
350
  | npm package | https://www.npmjs.com/package/@cnpx/cnpx |
319
351
  | Homepage | https://github.com/xcfio/template/tree/main/cnpx/cnpx#readme |
320
352
  | Bug reports | https://github.com/xcfio/template/issues |
321
- | Bug report email | omarfaruksxp@gmail.com |
322
353
 
323
354
  ### Discord
324
355
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cnpx/cnpx",
3
- "version": "0.0.5-dev.20260405125711",
3
+ "version": "0.0.5-dev.20260405131159",
4
4
  "description": "An interactive CLI tool for creating new projects from curated templates hosted on GitHub. Pick a category, pick a template, and get coding.",
5
5
  "author": "xcfio",
6
6
  "homepage": "https://github.com/xcfio/template/tree/main/cnpx/cnpx#readme",