Add package manager selection and --dry-run option #92

outslept · 2024-12-27T12:58:18Z

This PR introduces a significant overhaul to the npm init stylelint command, focusing on providing users with greater control and transparency during the initial setup process. I've implemented two key features:

Interactive package manager selection and
A --dry-run option.

Motivation

The existing npm init stylelint command, while functional, makes implicit assumptions that can lead to friction and confusion for users:

Implicit npm Assumption: The tool automatically uses npm for dependency installation, disregarding the user's potential preference or existing project setup with pnpm, yarn, or bun. This forces manual intervention and can lead to inconsistencies in dependency management.
Lack of Transparency and Safety: The tool directly modifies the file system without providing a way to preview the intended actions. This can be problematic for users who want to understand the changes before they are applied or for debugging potential issues.

This PR directly addresses these shortcomings, resulting in a more observable initialization experience.

Breakdown of the changes Made:

1. src/actions/context.ts:

Purpose: This file is responsible for establishing the execution context for the npm init stylelint command. It parses command-line arguments, detects the package manager, and creates a Context object that holds information, which we need throughout the initialization process.

2. src/actions/create-config.ts:

Purpose: This file handles the creation of the .stylelintrc.json configuration file.

3. src/actions/ensure-package-json.ts:

Purpose: This file ensures that a package.json file exists in the project directory. If it doesn't, it attempts to create one.

4. src/actions/help.ts:

Purpose: This file contains the logic for displaying the help information when the --help flag is used.

5. src/actions/install.ts:

Purpose: This file handles the installation of the necessary Stylelint dependencies.

6. src/actions/post-install.ts:

Purpose: This file is responsible for displaying the post-installation message to the user, providing guidance on how to use Stylelint.

7. src/prompts/install-now.ts:

Purpose: This file handles the prompt asking the user if they want to install the dependencies now.

8. src/prompts/package-manager.ts:

Purpose: This file implements the interactive prompt for selecting the preferred package manager.

9. src/prompts/usage-preference.ts:

Purpose: This file handles the prompt asking the user about their preferred Stylelint usage (catching errors only or enforcing style).

10. src/shell.ts:

Purpose: This file provides a lightweight abstraction over the child_process.spawn function for executing shell commands.

Note

This was created to replace execa, reducing the project's dependency footprint. Comes from astro - https://github.com/withastro/astro/blob/main/packages/upgrade/src/shell.ts

11. index.ts:

Purpose: This is the main entry point of the npm init stylelint command. It orchestrates the entire initialization process.

Related Issues

#16
#91

This commit introduces a new, self-contained module located at `src/actions/create-config.ts`. This module is designed to handle creating and managing the Stylelint configuration file. **Functionality:** - **Configuration Existence Check:** The module begins by implementing a mechanism for detecting existing Stylelint configurations. This is crucial to prevent accidental overwriting of user-defined settings. The `findExistingConfig` function leverages the `cosmiconfigSync` utility. This search ensures that all common configuration locations are considered. This prevents accidental overwrites. - **Conditional Configuration Creation:** Based on the user's initial preference (selected in a prior step), the module determines the appropriate base configuration to extend. If the user opted for a basic setup focused on error detection, `stylelint-config-recommended` is chosen. For users desiring a more opinionated and comprehensive setup, `stylelint-config-standard` is selected.

This commit introduces the `src/actions/ensure-package-json.ts` module to ensure a `package.json` file exists in the project directory. Key changes: - Implements `hasPackageJson` which uses `fs.readdirSync` to check if `package.json` exists in the directory. - Implements `initializePackageJson` which creates a default `package.json` if one is missing. It uses `execa` to run the `npm init -y` command. - Implements `ensureProjectPackageJson` as the main function to check for and potentially create the `package.json`.

This commit introduces the `installProjectDependencies` action to handle the installation of necessary project dependencies. Key changes: - Implements `installProjectDependencies` which uses `execa` to execute the package manager's install command. - Installs `stylelint` and either `stylelint-config-recommended` or `stylelint-config-standard` based on the user's usage preference. - Uses `getInstallCommand` to determine the correct install command (`install` for npm, `add` for others).

This commit introduces the `promptInstallDependencies` function to ask the user whether to install specified dependencies. Key changes: - Uses the `prompts` library to present a confirmation prompt to the user. - The prompt message includes the package manager and the list of dependencies to be installed. - Returns a boolean indicating the user's choice.

This commit introduces the `promptPackageManager` function to allow the user to select their preferred package manager (npm, pnpm, or yarn). Key changes: - Uses the `prompts` library to present a selection prompt. - Uses `which-pm-runs` to pre-select the package manager if it's already being used in the project. - Returns the selected package manager.

This commit introduces the `promptUsagePreference` function to let the user choose their preferred Stylelint usage level (error detection only or error detection and style enforcement).

This commit introduces a `messages` module to centralize all user-facing messages within the application.

This commit introduces a signal handler to gracefully handle the SIGINT signal (typically triggered by Ctrl+C). Key changes: - Implements `setupProcessHandlers` to attach a listener to the `SIGINT` signal. - When the signal is received, the handler logs a message indicating cancellation and then exits the process.

This commit introduces the main application logic within the `main` function. Key changes: - Sets up process handlers for graceful cancellation. - Checks for existing Stylelint configurations and exits if one is found. - Ensures the existence of a `package.json` file. - Prompts the user for their preferred Stylelint usage (errors only or errors and style). - Prompts the user to select their preferred package manager. - Prompts the user to confirm the installation of necessary dependencies. - Conditionally installs dependencies and creates the Stylelint configuration file based on user input. - Displays next steps and customization information upon successful setup.

…roject deps

…e manager support Updates the package description to be more generic ("The initialization script for Stylelint.") instead of being specific to npm init. Also updates the keywords to better reflect the functionality and improve discoverability, including terms like "configuration", "initializer", "cli", and "setup".

…DME.md

…ed dependencies, added context, minor fixes to improve readability

package.json

outslept · 2024-12-27T13:28:04Z

I have some questions to discuss before we ship this.

Currently, when a user presses Ctrl + C while an interactive prompt (e.g., package manager selection, install dependencies confirmation) is active, the initialization process doesn't terminate immediately. Instead, it seems to proceed to the next prompt in the sequence. What do we think is the expectable behavior here?
How do we approach testing with this changes?

If you have any questions or suggestions for improvements, please @mention me in here. I'm currently having some health issues, so being directly mentioned will help me track notifications better. I will check this draft from time to time, when we're ready with the suggestions I'll begin implementing new tests and an entry point in the root folder (index.mjs).

Co-authored-by: Gary Gozlan <[email protected]>

…lint into idkgene/pkg

outslept · 2024-12-27T13:43:10Z

Example workflow with package.json already existing (no audio):

2024-12-27.16-36-53.mp4

outslept · 2024-12-27T13:45:30Z

Example workflow with no package.json existing (no audio):

2024-12-27.16-42-11.mp4

src/actions/install.ts

src/actions/post-install.ts

jeddy3 · 2024-12-28T01:28:23Z

@idkgene Thank you for working on this; it looks great! I also appreciate the clarity of the PR description.

I've two preliminary comments related to some decisions we took with Stylelint that may not be obvious:

The recommended/standard config split dates back to when Stylelint bundled many stylistic rules. Nowadays, we only promote the Standard configuration and have scrubbed the Recommended one from our docs. To reflect this, let's remove the usage preference step.
As we may be moving to a flat config and ESM-only, we've been updating our docs to point users in this direction. Let's generate a stylelint.config.mjs file (and not add the choice of other formats) to minimise potential disruption.

With these suggestions in mind, we can summarise the tool's scope as an initialisation script that installs Stylelint and the Standard config using a person's preferred package manager and then creates an ESM configuration file to extend that config. It also provides a dry-run option for transparency and safety.

I have some questions to discuss before we ship this... when a user presses Ctrl + C... approach testing

I'd expect Ctrl + C to exit the tool completely, but it would be interesting to know what Astro's and ESLint's init tools do and how they approach testing.

Thanks again for broadening our support of package managers. It'll help more new users quickly get up and running with Stylelint. It's great to see bun support included, too!

…t post-install command

outslept · 2024-12-28T11:40:55Z

Latest Update Summary:

The pkgManager add command is now used to install dependencies directly.
Once the dependencies are installed, the process adds the linting script to package.json and adapts to the selected package manager when printing a command to an output.
If the package.json file is missing, the program throws an error. This prevents situations where dependencies are installed in the wrong directory (e.g. the nearest parent package.json).
Removed usage-preference prompt as were suggested above.
Added support for program termination by pressing Ctrl + C in all interactive prompts.
Switching to stylelint.config.mjs

On My List (Personal Notes):

Further Research on how folks implement tests for this type of projects

Links for later:

src/actions/post-install.ts

jeddy3 · 2024-12-31T13:46:12Z

@idkgene Thank you for your recent commits. The latest summary looks great!

It would be interesting to see what is uncovered about testing. However, I think we can start with a light touch. Once the testing is in place, I think we can undraft the PR for others to review.

And once we've merged and released this PR, we can update our docs as part of stylelint/stylelint#8210 to inform people that the init script supports other package managers.

outslept · 2024-12-31T17:18:44Z

@jeddy3 Thank you for your feedback! It's currently 8 PM my time, and I'm just about to join my family to celebrate New Year's.

As for your question, in short, I noticed they test individual 'modules' using fixtures and that's the play. I also have some tests already that haven't been submitted yet.

I'll be back with more detailed comments and information tomorrow afternoon, after the holiday celebration.

Wishing you and your family a very Happy New Year filled with joy, success, and good health! 🎉✨

jeddy3 · 2024-12-31T18:11:25Z

It's great that you're willing to post some more details tomorrow. Please don't feel rushed, though. As open-source contributors, we do what we can when we can.

Thank you for your kind words about the new year. I wish you and yours all the best in 2025! 🎉

outslept · 2025-01-01T13:58:21Z

Latest Updates TLDR (mostly UX)

Introduced explicit package manager selection flags:
- --use-npm,
- --use-pnpm,
- --use-yarn,
- --use-bun (from - https://nextjs.org/docs/app/api-reference/cli/create-next-app).
Added --skip-install flag for flexible dependency management (link above)
Enhanced pre-installation transparency by fetching and displaying latest dependency versions.
Implemented critical pre-installation checks:
- Write permissions verification in current directory (from - https://github.com/vercel/next.js/blob/canary/packages/create-next-app/helpers/is-writeable.ts).
- Internet connectivity validation (from https://github.com/vercel/next.js/blob/canary/packages/create-next-app/helpers/is-online.ts ).
- Registry availability assessment (https://github.com/withastro/astro/blob/main/packages/upgrade/src/messages.ts#L14C1-L27C2)
Improved constant naming for better code readability
Formatting systematization

Preview of the latest changes (audio muted, video is speeded up)

2025-01-01.15-26-28.mp4

Questions UX related

I've been critically examining our CLI's user experience, comparing it with Astro's approach. While our current implementation provides functionality, there are opportunities for improvement in user guidance and interaction clarity.

Add package command

Create a file command

File Contents

So the questions are:

Should we introduce more verbose, guided installation steps? Like prompt to create stylelint config file, show file contents of the stylelint config file, prompt to save it and so on?
Can or should we provide more contextual information during configuration? About the commands to be ran like on 1st screenshot and etc.

This looks nice, isn't hard to implement, yet I'm overwhelmed so that the tool should save the balance between being informative, but not overly verbose. I want the implemented functionality to be good and intuitive for the dev either if he is super skilled or not at all.

Testing

I assume that our approach is as follows:

└── 📁test
    └── 📁fixtures
        └── 📁configs
            └── stylelint.config.js
            └── stylelint.config.mjs
            └── stylelint.config.cjs
            └── .stylelintrc.js
            └── .stylelintrc.mjs
            └── .stylelintrc.cjs
            └── .stylelintrc.json
            └── .stylelintrc.yml
            └── .stylelintrc.yaml
            └── .stylelintrc
            └── package.json
        └── 📁package-json
            └── no-package.json
            └── valid-package.json
    └── 📁actions
         └── context.test.ts
         └── create-config.test.ts
         └── help.test.ts
         └── install.test.ts
         └── post-install.test.ts
    └── 📁prompts
         └── install-now.test.ts
         └── package-manager.test.ts
    └── 📁utils
         └── helpers.test.ts
         └── isOnline.test.ts
         └── isWriteable.test.ts
         └── registry.test.ts
    └── integration.test.ts

I think it would be appropriate to fixtures like this:

const configs = {
  js: './fixtures/configs/stylelint.config.js',
  mjs: './fixtures/configs/stylelint.config.mjs',
  // and so one
};

As long as all this formats are in docs I think they need to be tested.

Modules as I wrote above should be tested in isolation and itntegration test will check the full flow of CLI operation.

Currently actions tests are finished. Prompts, utils and main flow to be done. Planning on getting PR out of the draft when I'm done with the tests.

Addition described in the PR's TLDR comment.

jeddy3 · 2025-01-02T15:44:22Z

Thank you for your latest additions. It's shaping up to be a useful and robust tool!

Should we introduce more verbose, guided installation steps? Can or should we provide more contextual information during configuration

Yes, I believe both improve the user experience as people can:

see exactly what the script will do
interactively step through each part

What do you think about the following?:

jeddy3@mac create-stylelint % npm start         

> [email protected] start
> node create-stylelint.mjs

✔ Which package manager do you want to use? › npm
✔ This tool will install dependencies using the following command:

  npm install stylelint@~16.12.0 stylelint-config-standard@~36.0.1

Continue? … yes
✔ Installed dependencies.
✔ This tool will create a `stylelint.config.mjs` file with the following content:

  export default {
    extends: ["stylelint-config-standard"]
  };

Continue? … yes
✔ Created config file.

Success! You can now lint your CSS files by running the command:

  npx stylelint "**/*.css"

Please refer to the official Stylelint documentation for more customization options:
https://stylelint.io/user-guide/configure/

For --dry-run, it'd be great if we had the same behaviour as Astro, i.e. being able to step through the process:

> [email protected] start --dry-run
> node create-stylelint.mjs

Dry run mode.

✔ Which package manager do you want to use? › npm
✔ This tool will install dependencies using the following command:

  npm install stylelint@~16.12.0 stylelint-config-standard@~36.0.1

Continue? … yes
i --dry-run Skipping installation
✔ This tool will create a `stylelint.config.mjs` file with the following content:

  export default {
    extends: ["stylelint-config-standard"]
  };

Continue? … yes
i --dry-run Skipping file creation

Dry run complete!

Do you think that'd be possible? (Adding details to each step makes the --dry-run flag much more useful.)

… improvements

outslept · 2025-01-13T11:09:14Z

Hey. I wanted to apologize for the delay in getting this PR finalized. I’ve been working on it in my spare time, and I’ve run into a couple of issues with memfs for mocking the fs. These issues slowed things down a bit for me. I’ll provide an update as soon as I’ve resolved the remaining problems. Thanks for your patience, and I appreciate your understanding while I wrap this up!

jeddy3 · 2025-01-13T12:38:36Z

@gnify No need to apologise. As open-source contributors, we do what we can when we can. Many thanks for working on this in your spare time. Take as long as you need. We appreciate your efforts. The PR is looking great and significantly improves user experience, especially for people encountering Stylelint for the first time. So, thank you!

outslept added 20 commits December 27, 2024 09:14

feat(prompts): introduce prompt for usage preference

e0a6fea

This commit introduces the `promptUsagePreference` function to let the user choose their preferred Stylelint usage level (error detection only or error detection and style enforcement).

feat: introduce messages module for user feedback

12b04f7

This commit introduces a `messages` module to centralize all user-facing messages within the application.

chore(deps): added prompts, @types/prompts and @types/semver to the p…

4b55675

…roject deps

chore: removing the old implementation

0d175b2

style: removed extra space from package description + changed the REA…

d5b43b6

…DME.md

style: typo in readme

8fc8f4c

chore(rename): rename install-dependencies to install

7399d35

chore: removing process-handlers

3ea00a9

chore: removing messages file

1ded092

feat(shell): created a mini-execa version

bc4c36b

feat: took messages from a separate file directly into functions, add…

13449ff

…ed dependencies, added context, minor fixes to improve readability

chore: removing is cancelled from index.ts

b8372e4

outslept changed the title ~~CLI Rework~~ PM Selection and --dry-run option for stylelint init (BREAKING) Dec 27, 2024

Mouvedia reviewed Dec 27, 2024

View reviewed changes

package.json Outdated Show resolved Hide resolved

outslept and others added 3 commits December 27, 2024 16:31

chore(meta): making keywords more concise

d7fbace

Co-authored-by: Gary Gozlan <[email protected]>

chore: removing extra [

df390ff

Merge branch 'idkgene/pkg' of https://github.com/idkgene/create-style…

60af269

…lint into idkgene/pkg

Mouvedia reviewed Dec 27, 2024

View reviewed changes

src/actions/install.ts Outdated Show resolved Hide resolved

Mouvedia reviewed Dec 27, 2024

View reviewed changes

src/actions/post-install.ts Outdated Show resolved Hide resolved

jeddy3 mentioned this pull request Dec 28, 2024

Document preferred config file format stylelint/stylelint#8237

Merged

jeddy3 changed the title ~~PM Selection and --dry-run option for stylelint init (BREAKING)~~ Add package manager selection and --dry-run option Dec 28, 2024

outslept added 7 commits December 28, 2024 11:31

refactor: simplify install command by using 'add' directly

b9893d2

refactor: creating package.json with an add command, not the init

93eed34

refactor: removing usage-preference + adding package manager dependan…

7154888

…t post-install command

feat: throwing an error with not package.json existing

283d24a

feat: more flexible post-install

e0a9bdd

feat: more tweaks to the project

3ad07e0

feat: cancel support for prompts

d12d28b

Mouvedia reviewed Dec 28, 2024

View reviewed changes

src/actions/post-install.ts Outdated Show resolved Hide resolved

jeddy3 mentioned this pull request Dec 31, 2024

Document instructions for other package managers stylelint/stylelint#8210

Open

outslept added 6 commits January 1, 2025 17:02

feat: major updates

239b62b

Addition described in the PR's TLDR comment.

tests: isWriteable

a8c1f11

tests: helpers

d1b5bde

tests: shell

0f6184e

tests: post-install

8ce881a

tests: help

96f0269

outslept added 4 commits January 5, 2025 16:02

feat: partial fixes

43dbf9a

more fixes

ff7e27b

more tests, vitest configuration, esbuild setup, some pedantic naming…

2e148ea

… improvements

npm-run-all is no longer maintained. migrated to concurrently

37dd272

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add package manager selection and --dry-run option #92

Add package manager selection and --dry-run option #92

outslept commented Dec 27, 2024 •

edited

Loading

outslept commented Dec 27, 2024 •

edited

Loading

outslept commented Dec 27, 2024

outslept commented Dec 27, 2024

jeddy3 commented Dec 28, 2024

outslept commented Dec 28, 2024 •

edited

Loading

jeddy3 commented Dec 31, 2024

outslept commented Dec 31, 2024

jeddy3 commented Dec 31, 2024

outslept commented Jan 1, 2025 •

edited

Loading

jeddy3 commented Jan 2, 2025 •

edited

Loading

outslept commented Jan 13, 2025

jeddy3 commented Jan 13, 2025 •

edited

Loading

Add package manager selection and --dry-run option #92

Are you sure you want to change the base?

Add package manager selection and --dry-run option #92

Conversation

outslept commented Dec 27, 2024 • edited Loading

Motivation

Breakdown of the changes Made:

Related Issues

outslept commented Dec 27, 2024 • edited Loading

outslept commented Dec 27, 2024

outslept commented Dec 27, 2024

jeddy3 commented Dec 28, 2024

outslept commented Dec 28, 2024 • edited Loading

jeddy3 commented Dec 31, 2024

outslept commented Dec 31, 2024

jeddy3 commented Dec 31, 2024

outslept commented Jan 1, 2025 • edited Loading

Latest Updates TLDR (mostly UX)

Preview of the latest changes (audio muted, video is speeded up)

Questions UX related

So the questions are:

Testing

jeddy3 commented Jan 2, 2025 • edited Loading

outslept commented Jan 13, 2025

jeddy3 commented Jan 13, 2025 • edited Loading

outslept commented Dec 27, 2024 •

edited

Loading

outslept commented Dec 27, 2024 •

edited

Loading

outslept commented Dec 28, 2024 •

edited

Loading

outslept commented Jan 1, 2025 •

edited

Loading

jeddy3 commented Jan 2, 2025 •

edited

Loading

jeddy3 commented Jan 13, 2025 •

edited

Loading