create-codeverse 0.0.0-stage → 0.1.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.
Files changed (66) hide show
  1. package/LICENSE +21 -0
  2. package/ReadMe.MD +484 -0
  3. package/bin/cli.js +346 -0
  4. package/lib/apply/front.js +122 -0
  5. package/lib/apply/test.js +73 -0
  6. package/lib/copyTemplate.js +73 -0
  7. package/lib/desktop.js +65 -0
  8. package/lib/installDependencies.js +96 -0
  9. package/lib/openInEditor.js +14 -0
  10. package/lib/packageJson.js +33 -0
  11. package/lib/paths.js +4 -0
  12. package/lib/prompts.js +147 -0
  13. package/lib/runCommand.js +44 -0
  14. package/lib/secret.js +80 -0
  15. package/lib/templates.js +97 -0
  16. package/lib/validateProjectName.js +24 -0
  17. package/lib/versions.js +110 -0
  18. package/package.json +49 -6
  19. package/templates/codeskills.enc +0 -0
  20. package/templates/extras/test-componentes/ReadMe.MD +44 -0
  21. package/templates/extras/test-componentes/cypress/component/Login.cy.jsx +120 -0
  22. package/templates/extras/test-componentes/cypress/fixtures/example.json +5 -0
  23. package/templates/extras/test-componentes/cypress/support/commands.js +25 -0
  24. package/templates/extras/test-componentes/cypress/support/component-index.html +14 -0
  25. package/templates/extras/test-componentes/cypress/support/component.js +24 -0
  26. package/templates/extras/test-componentes/cypress.config.js +10 -0
  27. package/templates/extras/test-componentes/src/app/page.jsx +5 -0
  28. package/templates/extras/test-componentes/src/components/Login.jsx +47 -0
  29. package/templates/extras/test-dependencias/tests/nome-do-script.test.js +79 -0
  30. package/templates/front/.env.example +0 -0
  31. package/templates/front/ReadMe.MD +51 -0
  32. package/templates/front/_gitignore +42 -0
  33. package/templates/front/biome.json +42 -0
  34. package/templates/front/jsconfig.json +8 -0
  35. package/templates/front/next.config.mjs +11 -0
  36. package/templates/front/package.template.json +41 -0
  37. package/templates/front/public/fonts/gitkeep +0 -0
  38. package/templates/front/public/icons/gitkeep +0 -0
  39. package/templates/front/public/images/gitkeep +0 -0
  40. package/templates/front/public/media/gitkeep +0 -0
  41. package/templates/front/public/sounds/gitkeep +0 -0
  42. package/templates/front/src/app/favicon.ico +0 -0
  43. package/templates/front/src/app/globals.css +9 -0
  44. package/templates/front/src/app/layout.js +14 -0
  45. package/templates/front/src/app/nome-da-rota/nome-da-rota.module.css +0 -0
  46. package/templates/front/src/app/nome-da-rota/page.jsx +5 -0
  47. package/templates/front/src/app/page.jsx +39 -0
  48. package/templates/front/src/app/page.module.css +98 -0
  49. package/templates/front/src/components/Nome-do-componente.jsx +5 -0
  50. package/templates/front/src/components/Nome-do-componente.module.css +0 -0
  51. package/templates/integracao/ReadMe.MD +41 -0
  52. package/templates/integracao/cypress/e2e/meu-teste.cy.js +75 -0
  53. package/templates/integracao/cypress/fixtures/example.json +5 -0
  54. package/templates/integracao/cypress/support/commands.js +25 -0
  55. package/templates/integracao/cypress/support/e2e.js +17 -0
  56. package/templates/integracao/cypress.config.js +7 -0
  57. package/templates/integracao/package.template.json +38 -0
  58. package/templates/test/.env.example +0 -0
  59. package/templates/test/ReadMe.MD +49 -0
  60. package/templates/test/_gitignore +25 -0
  61. package/templates/test/jest.reporters.config.mjs +14 -0
  62. package/templates/test/package.template.json +42 -0
  63. package/templates/test/src/nome-do-seu-script.js +4 -0
  64. package/templates/test/tests/nome-do-script.test.js +40 -0
  65. package/templates/versions.json +84 -0
  66. package/README.md +0 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CodeVerse
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/ReadMe.MD ADDED
@@ -0,0 +1,484 @@
1
+ # create-codeverse
2
+
3
+ [![npm version](https://img.shields.io/npm/v/create-codeverse.svg)](https://www.npmjs.com/package/create-codeverse)
4
+ [![license](https://img.shields.io/npm/l/create-codeverse.svg)](https://www.npmjs.com/package/create-codeverse)
5
+ [![node](https://img.shields.io/node/v/create-codeverse.svg)](https://nodejs.org)
6
+
7
+ The official scaffolding CLI for **CodeVerse** students. Run one command, answer a few questions
8
+ and get a ready-to-code project: a Next.js front end or an automated-testing project with Jest or
9
+ Cypress. The CLI copies the template, installs the dependencies and opens the project in VS Code.
10
+
11
+ ```bash
12
+ npx create-codeverse@latest
13
+ ```
14
+
15
+ > [!NOTE]
16
+ > The interactive prompts are in **Brazilian Portuguese**, because the CLI is built for CodeVerse
17
+ > classes.
18
+
19
+ ---
20
+
21
+ ## Table of contents
22
+
23
+ - [Quick start](#quick-start)
24
+ - [Requirements](#requirements)
25
+ - [How it works](#how-it-works)
26
+ - [The wizard](#the-wizard)
27
+ - [Templates](#templates)
28
+ - [FrontEnd — Next.js App Router](#frontend--nextjs-app-router)
29
+ - [Test — Unit (Jest)](#test--unit-jest)
30
+ - [Test — Dependencies (Jest)](#test--dependencies-jest)
31
+ - [Test — Component Testing (Cypress)](#test--component-testing-cypress)
32
+ - [Test — E2E Integration (Cypress)](#test--e2e-integration-cypress)
33
+ - [Coming soon](#coming-soon)
34
+ - [Dependency versions](#dependency-versions)
35
+ - [Where the project is created](#where-the-project-is-created)
36
+ - [Opening in VS Code](#opening-in-vs-code)
37
+ - [Safety and guarantees](#safety-and-guarantees)
38
+ - [Exit codes](#exit-codes)
39
+ - [Troubleshooting](#troubleshooting)
40
+ - [License](#license)
41
+
42
+ ---
43
+
44
+ ## Quick start
45
+
46
+ ```bash
47
+ npx create-codeverse@latest
48
+ ```
49
+
50
+ You don't need a global install. `npm create codeverse@latest` also works.
51
+
52
+ The CLI is fully interactive and takes no command-line arguments or flags.
53
+
54
+ ## Requirements
55
+
56
+ | Requirement | Notes |
57
+ |---|---|
58
+ | **Node.js** `>= 20` | Check with `node -v` |
59
+ | **npm** | Comes with Node.js |
60
+ | **Windows** (PowerShell or cmd) | The generated npm scripts start with `cls` (clear screen), which only exists on Windows shells. See [Troubleshooting](#troubleshooting). |
61
+ | **VS Code** with `code` on your `PATH` | Optional. Without it, the CLI prints the project path so you can open it manually. |
62
+ | **Internet connection** | Needed for packages that aren't in the PC's npm cache yet (and to download the Cypress app the first time each version is used on the PC) |
63
+
64
+ ## How it works
65
+
66
+ 1. **Asks the template questions**: the template, then the extras (FrontEnd) or the test type (Test). See [The wizard](#the-wizard). As soon as each answer is given, the CLI resolves the package versions in the background.
67
+ 2. **Asks the project name.**
68
+ 3. **Creates the project folder** on your Windows Desktop (see [Where the project is created](#where-the-project-is-created)). It never overwrites an existing folder.
69
+ 4. **Copies the template** exactly as published:
70
+ - empty folders (marked with a `gitkeep` file) are created without the marker file
71
+ - `_gitignore` is renamed to `.gitignore`
72
+ - `node_modules`, `.next` and `package-lock.json` are never copied
73
+ 5. **Generates `package.json`** from the template's `package.template.json`, with `name` set to your project name and the dependencies.
74
+ 6. **Applies the code changes** for the extras or test type you chose (e.g. Tailwind setup, Ant Design registry, Cypress files).
75
+ 7. **Starts installing the dependencies in the background** with `npm install` (see [Dependency versions](#dependency-versions)) and, **while it installs**, asks for an optional description and your name. This works the same for every template.
76
+ 8. **Waits for whatever is left of the installation**, then saves in `package.json`:
77
+ - `description`: your description (if you typed one; otherwise the template's own)
78
+ - `author.name`: your name
79
+ 9. **Shows the next step** and counts down 5 seconds, so you have time to read the messages.
80
+ 10. **Opens the project in VS Code** (see [Opening in VS Code](#opening-in-vs-code)).
81
+
82
+ The CLI doesn't initialize a Git repository, run your project or run your tests. Its only job is
83
+ to create a ready-to-use starting point.
84
+
85
+ ## The wizard
86
+
87
+ | # | Prompt (pt-BR) | Meaning | Rules |
88
+ |---|---|---|---|
89
+ | 1 | `O que vamos construir hoje? ...` | Main menu: pick **one** template | `BackEnd`, `FrontEnd`, `Mobile`, `Test`. A "coming soon" template exits right away. |
90
+ | 2a | `Quais extras vão turbinar seu projeto? (opcional)` | FrontEnd extras (multi-select) | Optional. Select none, one or several. |
91
+ | 2b | `Que tipo de teste você vai fazer?` | Test type (single select) | `Unitário`, `Dependências`, `Component Testing`, `Integração E2E` |
92
+ | 3 | `Qual é o nome do seu projeto/app?` | Project name | Lowercase letters, digits and hyphens only. No spaces, can't start or end with a hyphen, max 214 characters. A folder with that name can't already exist on the Desktop. After this answer the project is created and the installation starts. |
93
+ | 4 | `Qual é a descrição do seu projeto/app? (opcional)` | Project description | Optional. Saved as `description` in `package.json`; left blank, the template's description is kept. |
94
+ | 5 | `Qual é o seu nome, DEV?` | Your name | Required. Saved as `author.name` in `package.json`. |
95
+
96
+ Before the main menu, the CLI pauses for a moment so you can read the welcome message. Keys
97
+ pressed during that pause are ignored.
98
+
99
+ **Keys:** `↑`/`↓` to move, `Space` to check or uncheck (multi-select), `Enter` to confirm,
100
+ `Ctrl+C` to cancel. Nothing is written to disk before the project name is answered. Cancelling
101
+ after that (during the description, your name or the dependency installation) stops npm and
102
+ deletes the project folder.
103
+
104
+ ---
105
+
106
+ ## Templates
107
+
108
+ ### FrontEnd — Next.js App Router
109
+
110
+ A Next.js project with the App Router, a `src/` folder, the React Compiler and Biome.
111
+
112
+ **Installed packages**
113
+
114
+ | Type | Packages |
115
+ |---|---|
116
+ | dependencies | `next`, `react`, `react-dom` |
117
+ | devDependencies | `@biomejs/biome`, `babel-plugin-react-compiler` |
118
+
119
+ **What's configured**
120
+
121
+ - `next.config.mjs`: `reactCompiler: true` and `turbopack.root` set to the project folder
122
+ - `jsconfig.json`: import aliases `@/*` → `src/*` and `@components/*` → `src/components/*`
123
+ - `biome.json`: 4-space indentation, single quotes, recommended rules plus the `next` and `react`
124
+ domains, organize imports on
125
+ - `layout.js`: `<html lang="pt-BR">` and imports `globals.css` (a minimal CSS reset)
126
+ - `page.jsx`: a CodeVerse landing page styled with CSS Modules
127
+ - Example route (`src/app/nome-da-rota/`) and example component (`src/components/`), ready to rename
128
+
129
+ **Project structure**
130
+
131
+ ```text
132
+ my-app/
133
+ ├── public/
134
+ │ ├── fonts/ (empty)
135
+ │ ├── icons/ (empty)
136
+ │ ├── images/ (empty)
137
+ │ ├── media/ (empty)
138
+ │ └── sounds/ (empty)
139
+ ├── src/
140
+ │ ├── app/
141
+ │ │ ├── nome-da-rota/
142
+ │ │ │ ├── nome-da-rota.module.css
143
+ │ │ │ └── page.jsx
144
+ │ │ ├── favicon.ico
145
+ │ │ ├── globals.css
146
+ │ │ ├── layout.js
147
+ │ │ ├── page.jsx
148
+ │ │ └── page.module.css
149
+ │ └── components/
150
+ │ ├── Nome-do-componente.jsx
151
+ │ └── Nome-do-componente.module.css
152
+ ├── .env.example
153
+ ├── .gitignore
154
+ ├── biome.json
155
+ ├── jsconfig.json
156
+ ├── next.config.mjs
157
+ ├── package.json
158
+ └── ReadMe.MD
159
+ ```
160
+
161
+ **Scripts**
162
+
163
+ | Script | Command | Purpose |
164
+ |---|---|---|
165
+ | `npm run dev` | `cls && next dev` | Starts the development server at `http://localhost:3000` |
166
+ | `npm run lint` | `biome check` | Lints the project and checks the formatting |
167
+ | `npm run format` | `biome format --write` | Formats all files |
168
+
169
+ **Extras**
170
+
171
+ Extras are optional and can be combined.
172
+
173
+ | Extra | Installs | Code changes |
174
+ |---|---|---|
175
+ | **Ant Design** | `antd`, `@ant-design/nextjs-registry` | Wraps `{children}` in `<AntdRegistry>` in `layout.js`, needed for correct SSR styles in the App Router |
176
+ | **Axios** | `axios` | None: import it where you need it |
177
+ | **Lucide Icons** | `lucide-react` | None: import the icons where you need them |
178
+ | **TailwindCss** | `tailwindcss`, `@tailwindcss/postcss` (dev) | Creates `postcss.config.mjs`, replaces `globals.css` with `@import "tailwindcss";`, rewrites `page.jsx` with Tailwind classes, removes the three `.module.css` files and adds `className="min-h-screen antialiased"` to `<body>` |
179
+ | **Toast-Hot** | `react-hot-toast` | Adds `<Toaster />` to `layout.js`, so `toast(...)` calls have somewhere to render |
180
+
181
+ With **Ant Design** and **Toast-Hot**, the `<body>` in `layout.js` becomes:
182
+
183
+ ```jsx
184
+ <body>
185
+ <AntdRegistry>{children}</AntdRegistry>
186
+ <Toaster />
187
+ </body>
188
+ ```
189
+
190
+ With no extras selected, you get the plain template: Next.js, React and CSS Modules.
191
+
192
+ ---
193
+
194
+ ### Test — Unit (Jest)
195
+
196
+ A JavaScript (ES Modules) project for unit tests with Jest: functions, classes, scenarios,
197
+ negative cases, boundary values and business rules.
198
+
199
+ | Type | Packages |
200
+ |---|---|
201
+ | devDependencies | `jest`, `jest-html-reporters` |
202
+
203
+ ```text
204
+ my-tests/
205
+ ├── src/
206
+ │ └── nome-do-seu-script.js sample function to replace
207
+ ├── tests/
208
+ │ └── nome-do-script.test.js teaching suite with the core matchers
209
+ ├── .env.example
210
+ ├── .gitignore
211
+ ├── jest.reporters.config.mjs Jest config with the HTML reporter
212
+ ├── package.json "type": "module"
213
+ └── ReadMe.MD how to run the tests (pt-BR)
214
+ ```
215
+
216
+ The test suite shows `describe`/`it`/`expect` and the matchers `toBe`, `toEqual`, `toContain`,
217
+ `toBeTruthy`, `toBeFalsy`, `toHaveLength` and `toBeCloseTo`.
218
+
219
+ **Scripts**
220
+
221
+ | Script | Command | Purpose |
222
+ |---|---|---|
223
+ | `npm test` | `cls && node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand --verbose` | Runs the whole suite, one test file at a time, with per-test output (ES Modules support) |
224
+ | `npm run report` | `npm test -- --coverage --json --outputFile=coverage/relatorio.json` | Runs with coverage and writes a JSON report to `coverage/relatorio.json` |
225
+ | `npm run dashboard` | `npm test -- --config jest.reporters.config.mjs` | Generates an HTML report at `_html-report/index.html` and opens it |
226
+
227
+ ---
228
+
229
+ ### Test — Dependencies (Jest)
230
+
231
+ Everything in [Unit](#test--unit-jest), plus examples of testing code that depends on external
232
+ resources (APIs, Promises) using mocks.
233
+
234
+ | Type | Packages |
235
+ |---|---|
236
+ | dependencies | `axios` |
237
+ | devDependencies | `jest`, `jest-html-reporters` |
238
+
239
+ The file `tests/nome-do-script.test.js` is replaced by a version that also contains a
240
+ `describe('Mocks com jest.fn()')` block, covering `mockReturnValue`, `mockResolvedValue`,
241
+ `mockRejectedValue`, `toHaveBeenCalled`, `toHaveBeenCalledTimes` and `toHaveBeenCalledWith`. Axios
242
+ is included as the HTTP client for real or mocked API scenarios.
243
+
244
+ It has the same scripts as Unit.
245
+
246
+ ---
247
+
248
+ ### Test — Component Testing (Cypress)
249
+
250
+ The [FrontEnd](#frontend--nextjs-app-router) template, without extras, plus Cypress Component
251
+ Testing for React components.
252
+
253
+ | Type | Packages |
254
+ |---|---|
255
+ | dependencies | `next`, `react`, `react-dom` |
256
+ | devDependencies | `@biomejs/biome`, `babel-plugin-react-compiler`, `cypress` |
257
+
258
+ **Changes on top of FrontEnd**
259
+
260
+ - Adds a `Login` component (`src/components/Login.jsx`), and `page.jsx` renders only it
261
+ - Adds `cypress.config.js` (component testing with the `next` framework and the `webpack` bundler)
262
+ - Adds a teaching spec, `cypress/component/Login.cy.jsx`, with assertions such as `exist`,
263
+ `be.visible`, `have.text`, `have.attr`, `have.value`, `have.focus` and `deep.equal`, plus typing,
264
+ clearing and submitting with `{enter}`
265
+ - Removes the files that don't belong to this exercise: `.env.example`, the example route, the
266
+ example component, the CSS Modules files and the `public/` subfolders
267
+ - Appends `cypress/screenshots/`, `cypress/videos/` and `cypress/downloads/` to `.gitignore`
268
+ - Adds the `test` script and sets a project-specific `description` and `keywords` in `package.json`
269
+
270
+ ```text
271
+ my-app/
272
+ ├── cypress/
273
+ │ ├── component/
274
+ │ │ └── Login.cy.jsx
275
+ │ ├── fixtures/
276
+ │ │ └── example.json
277
+ │ └── support/
278
+ │ ├── commands.js
279
+ │ ├── component-index.html
280
+ │ └── component.js
281
+ ├── public/
282
+ ├── src/
283
+ │ ├── app/
284
+ │ │ ├── favicon.ico
285
+ │ │ ├── globals.css
286
+ │ │ ├── layout.js
287
+ │ │ └── page.jsx
288
+ │ └── components/
289
+ │ └── Login.jsx
290
+ ├── .gitignore
291
+ ├── biome.json
292
+ ├── cypress.config.js
293
+ ├── jsconfig.json
294
+ ├── next.config.mjs
295
+ ├── package.json
296
+ └── ReadMe.MD
297
+ ```
298
+
299
+ **Scripts**
300
+
301
+ | Script | Command | Purpose |
302
+ |---|---|---|
303
+ | `npm run dev` | `cls && next dev` | Starts the development server |
304
+ | `npm test` | `cls && cypress open` | Opens Cypress; choose **Component Testing** |
305
+ | `npm run clean` | `cls && npx cypress cache prune` | Deletes old Cypress app versions from the PC (about 200 MB each), keeping only the one this project uses |
306
+ | `npm run lint` | `biome check` | Lints the project |
307
+ | `npm run format` | `biome format --write` | Formats all files |
308
+
309
+ ---
310
+
311
+ ### Test — E2E Integration (Cypress)
312
+
313
+ A standalone Cypress project for End-to-End tests: Cypress opens a real website in the browser and
314
+ interacts with it the way a user would.
315
+
316
+ | Type | Packages |
317
+ |---|---|
318
+ | devDependencies | `cypress` |
319
+
320
+ ```text
321
+ my-e2e/
322
+ ├── cypress/
323
+ │ ├── e2e/
324
+ │ │ └── meu-teste.cy.js teaching spec, one example of each assertion type
325
+ │ ├── fixtures/
326
+ │ │ └── example.json
327
+ │ └── support/
328
+ │ ├── commands.js
329
+ │ └── e2e.js
330
+ ├── cypress.config.js e2e.baseUrl = http://localhost:3000
331
+ ├── package.json
332
+ └── ReadMe.MD how to run the tests (pt-BR)
333
+ ```
334
+
335
+ The spec `meu-teste.cy.js` visits `/` before each test and covers URL and title, elements, attributes
336
+ and styles, forms and click navigation. Its selectors and texts are **placeholders**: adjust them
337
+ to the website you're testing. Change `baseUrl` in `cypress.config.js` to test another address.
338
+
339
+ | Script | Command | Purpose |
340
+ |---|---|---|
341
+ | `npm test` | `cls && cypress open` | Opens Cypress; choose **E2E Testing** |
342
+ | `npm run clean` | `cls && npx cypress cache prune` | Deletes old Cypress app versions from the PC (about 200 MB each), keeping only the one this project uses |
343
+
344
+ > [!NOTE]
345
+ > When you install `cypress`, it also downloads the Cypress app (about 200 MB) to
346
+ > `%LOCALAPPDATA%\Cypress\Cache\<version>`. The download happens only once per version on each PC:
347
+ > later projects with the same version reuse it. The CLI warns you that this step can take a few
348
+ > minutes only when that version isn't on the PC yet.
349
+
350
+ ---
351
+
352
+ ### Coming soon
353
+
354
+ | Template | Stack |
355
+ |---|---|
356
+ | **BackEnd** | NodeJS Express |
357
+ | **Mobile** | Expo + Native |
358
+
359
+ These entries already show up in the menu, marked as `em breve` ("coming soon"). Picking one shows a
360
+ notice and exits without creating anything.
361
+
362
+ ---
363
+
364
+ ## Dependency versions
365
+
366
+ The versions of every template's packages are kept in one file inside this package,
367
+ `templates/versions.json`, organized in reusable blocks (for example `front.base` or
368
+ `test.cypress.base`).
369
+
370
+ | Value in `versions.json` | What the CLI does |
371
+ |---|---|
372
+ | Exact version (e.g. `"6.19.3"`) | Writes it to `package.json` as is |
373
+ | `"latest"` | Looks up the current version in the npm registry and writes it to `package.json` as `^X.Y.Z` |
374
+
375
+ All the templates use exact versions, updated by CodeVerse when needed. Exact versions are faster
376
+ on a PC that already installed them, because npm reuses its local cache. `"latest"` is still
377
+ supported, and both kinds can be mixed.
378
+
379
+ Normally a single command installs everything:
380
+
381
+ ```bash
382
+ npm install --prefer-offline --no-audit --no-fund
383
+ ```
384
+
385
+ `--prefer-offline` takes packages from the npm cache of the PC and only downloads what isn't there.
386
+ If the command fails, it runs again without `--prefer-offline`, fetching everything from the
387
+ internet.
388
+
389
+ Only when the npm registry can't be reached to look up the `"latest"` versions does the CLI fall
390
+ back to these commands, in this order (only the ones that apply run):
391
+
392
+ ```bash
393
+ npm install # packages with an exact version
394
+ npm install <deps>@latest # dependencies marked "latest"
395
+ npm install -D <devDeps>@latest # devDependencies marked "latest"
396
+ ```
397
+
398
+ If one of these commands fails (no internet, npm registry down, etc.), the CLI:
399
+
400
+ - **keeps** the project folder and all the copied files
401
+ - shows the error and the exact commands left to run:
402
+
403
+ ```text
404
+ cd "C:\Users\you\Desktop\my-app"
405
+ npm install
406
+ ```
407
+
408
+ - still opens VS Code and exits with code `1`
409
+
410
+ ## Where the project is created
411
+
412
+ The project is always created on your **Windows Desktop**, as `<Desktop>\<project-name>`,
413
+ **wherever you ran the command from**. The CLI asks Windows where the Desktop really is, so it
414
+ also follows a redirected Desktop:
415
+
416
+ | Situation | Destination |
417
+ |---|---|
418
+ | Regular Desktop | `%USERPROFILE%\Desktop\<project-name>` |
419
+ | Desktop moved to OneDrive | e.g. `%USERPROFILE%\OneDrive\Área de Trabalho\<project-name>` (the folder you see on screen) |
420
+ | Windows can't tell where the Desktop is | `%USERPROFILE%\Desktop\<project-name>` (created if it doesn't exist) |
421
+
422
+ ## Opening in VS Code
423
+
424
+ After a 5-second countdown, the CLI runs:
425
+
426
+ | Where you ran the CLI | Command | Result |
427
+ |---|---|---|
428
+ | A regular terminal (PowerShell, cmd, Windows Terminal) | `code .` | Opens the project in a new VS Code window |
429
+ | The VS Code integrated terminal | `code -r .` | Opens the project in the **current** window. The terminal that ran the CLI closes. |
430
+
431
+ If the `code` command isn't found, the CLI prints the project path so you can open it manually. In
432
+ VS Code you can add it with **Command Palette → `Shell Command: Install 'code' command in PATH`**.
433
+
434
+ Then open the integrated terminal (`` Ctrl + ` ``) and run the template's scripts.
435
+
436
+ ## Safety and guarantees
437
+
438
+ - **Never overwrites anything.** The project name is rejected if the folder already exists, and
439
+ this is checked again right before writing.
440
+ - **Nothing is created before the project name is answered.** From then on, `Ctrl+C` (in a
441
+ question or during the installation) stops npm and deletes the project folder, so nothing is
442
+ left behind. If Windows doesn't release the folder in time, the CLI shows its path so you can
443
+ delete it yourself. After the installation ends, the project is kept.
444
+ - **Only writes inside the new project folder** (and creates the Desktop folder if it doesn't
445
+ exist). It never touches the folder you ran the command from or any global configuration.
446
+ - **No global installs, no telemetry, no Git operations.** The only external commands are
447
+ `npm install` inside the new folder and `code` to open VS Code.
448
+ - **Fixed commands only.** The arguments of every external command come from the CLI itself and
449
+ from `templates/versions.json`, never from what you type. Your project name is only used as a
450
+ validated folder name.
451
+ - **A single runtime dependency**, [`@clack/prompts`](https://www.npmjs.com/package/@clack/prompts),
452
+ pinned to an exact version and bundled inside the package (nothing extra to download).
453
+
454
+ ## Exit codes
455
+
456
+ | Code | Meaning |
457
+ |---|---|
458
+ | `0` | Project created and dependencies installed; or you picked a "coming soon" template |
459
+ | `1` | Something failed while creating the project, or the dependency installation is incomplete (the commands left to run are shown) |
460
+ | `130` | Cancelled with `Ctrl+C` (the project folder is deleted if the installation hadn't finished) |
461
+
462
+ ## Troubleshooting
463
+
464
+ | Problem | Solution |
465
+ |---|---|
466
+ | `'cls' is not recognized` / `cls: command not found` | The generated scripts are made for Windows. On macOS or Linux, remove `cls && ` from the scripts in `package.json`. |
467
+ | `Já existe uma pasta com esse nome...` | A folder with that name already exists on the Desktop. Pick another name, or remove the old folder yourself. |
468
+ | `Nome inválido...` | Use only lowercase letters, digits and hyphens, e.g. `my-first-app`. |
469
+ | `Falta instalar as dependências...` | The installation failed. Check your internet connection and run the commands shown, in the project folder. |
470
+ | `Não consegui apagar a pasta do projeto...` | You cancelled with `Ctrl+C` and Windows was still holding the files. Delete the folder shown. |
471
+ | `VS Code não encontrado...` | Install the `code` command in your `PATH` (see [Opening in VS Code](#opening-in-vs-code)), or open the printed folder manually. |
472
+ | Cypress takes a long time to install | Downloading the Cypress app (about 200 MB) is expected the first time each version is used on the PC; the CLI shows `Baixando o Cypress...` in that case. Wait for it to finish. |
473
+ | The disk is filling up with Cypress versions | In a Cypress project, run `npm run clean` to delete the old versions of the Cypress app. |
474
+ | You want the newest CLI version | Always run with `@latest`: `npx create-codeverse@latest` |
475
+
476
+ ## License
477
+
478
+ MIT © CodeVerse
479
+
480
+ ---
481
+
482
+ <p align="center">
483
+ <a href="https://codeverse.dev.br">codeverse.dev.br</a>
484
+ </p>