docs: nicer quotes

[IsaacLeeWebDev]

It's generally a good practice to prefer single-quotes in shell script strings unless you plan on interpolating variables.

It's purely stylistic here (even if you disregard that these are just markdown files 😅), but there's something about shell code that looks safer at first-glance. It's sorta like how a SQL query string can be safe when concatenating another string directly onto it, but it doesn't look as safe as one that escapes inputs.

Plus, given that the NPM scripts are already inside JSON strings, getting rid of escaped characters makes it look neater! :3

[IsaacLeeWebDev]

PS: I love this tool SO much, and use it all the time! Thanks for all the hard work!

[IsaacLeeWebDev]

Also, I made an exception in docs/cli/configuration.md

Just 'cause an escaped a shell single-quote is a bit tricky to read, and at the end of the day, docs are meant to be read!

[gustavohenke]

Fair change, I think - but looks the quotes thing has bitten some people before: #509.
What are your thoughts?

I don't mind it either way.

[IsaacLeeWebDev]

Man, after giving it a long think, it's a really tough choice.

Because concurrently is a lot like unix's eval in that it intentionally executes string arguments as code, and because there are widely used alternatives to Command Prompt on Windows that don't have the problem in #509 such as PowerShell, I think I personally lean more towards single-quotes.

From my point of view, it seems like the odds are pretty remote with respect to someone potentially passing unsanitized user input to concurrently before they know how quotes work, and doing so specifically because they copy-pasted from this repo's docs. However, if and when that happens, boy would that be a harsh lesson. Shell injection is one of the most severe vulnerabilities that a system can have.

That said, as you can see in #509, single quotes may unintentionally cause annoyingly harsh (and potentially untimely and costly) lessons about portability. I also think preserving the "copy-pasteability" of your docs is a very worthwhile goal, and command portability seems like a wide-spread accessibility issue that the world of software is wrought with, and would bring me no joy to contribute to.

However— and know that I absolutely despise this fact— I do believe that every developer will inevitably be forced to learn how to make commands they need to run portable across multiple environments— and I'd speculate that Windows Command Prompt users who run NPM scripts are forced to learn that lesson a lot more often (and usually a lot earlier in their careers).

Ultimately, though, I think I still lean more towards single-quotes. I wanna be clear that I don't think it's cut and dry to me, and if nothing changed, I'd get it. I think it just sorta comes down to the values of the maintainers, and no matter what, I definitely empathize with anyone who gets hung up on portability issues wherever they crop up.

Maybe it's worth listing two versions of the command in the README for Command Prompt users? I could see that maybe getting out of hand, though.

Or maybe the note in the README should say something like this:

Escape double-quotes in package.json if you need them.

I could update my PR, if so.

I wonder what other CLI tools do about this in their docs!

---

Another thought:

it seems like we may be heading into a world where a lot of the CLI commands we run are generated by AI models based on a developer's local files, or even a list of webpages which may all contain malicious/injected prompt instructions, for all we know... and like... it's not like it's any one open-source package's responsibility to say "hey guys, please don't go full YOLO-mode with AI" or even to protect the security of those that do (if we assume we even can) but I guess there's some marginal amount of value in adopting a style in documentation that errs a bit more on the secure/paranoid side.

[gustavohenke]

Thanks for sharing your thoughts!

comes down to the values of the maintainers

I guess there's some marginal amount of value in adopting a style in documentation that errs a bit more on the secure/paranoid side

These have echoed with me because I've been writing the examples somewhat mindlessly based on what I do myself.
However, being intentional on what to use means adopting a style, which helps reducing messy examples each using their own style going forward.

And as you pointed out AI, these days being intentional might even influence these tools to write examples in using the safer default of single quotes.

I also came across #497 that I didn't remember about, and being intentional about the use of single quotes might help a few users.
Besides, probably not a lot of people use cmd these days, and powershell seems to support single quotes.

Maybe it's worth listing two versions of the command in the README for Command Prompt users?

Maybe, if there was a documentation website that could hide the duplicated examples.
GitHub can't do that yet, though, so it becomes noise.