v0.7 (#9)

Author: jaandrle

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+**Describe the bug:**
+
+Here is place for your 😉 clear and concise description of what the bug is.
+
+**To Reproduce/Example:**
+
+Yes, it is nice to have for example code snippet of 🐛 behaviour.
+
+**Technical background (following information can be really helpful 👍):**
+
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context:**
+
+Add any other context about the problem here.
+
+---
+
+Thanks for your help 🎉!

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe:**
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like:**
+
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered:**
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+---
+
+Thanks for your help 🎉!

.github/ISSUE_TEMPLATE/idea.md

@@ -0,0 +1,13 @@
+---
+name: Idea
+about: Suggest an idea improving library usage but needs discussion if schould be part of library
+title: ''
+labels: 'idea'
+assignees: ''
+
+---
+
+
+---
+
+Thanks for your help 🎉!

.github/workflows/npm-publish.yml

@@ -0,0 +1,18 @@
+name: Publish Package to npmjs
+on:
+  release:
+    types: [created]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '16.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.npmrc

@@ -0,0 +1,3 @@
+//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+registry=https://registry.npmjs.org/
+always-auth=true

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# How to contribute
+Contributions to the project generally take one of three forms:
+
+1. Issues reports
+    1. Bug reports
+    1. Feature requests
+1. Patches
+1. Documentation/examples improvements
+
+## Issues reports
+The proper way to report Bug/Feature is to use corresponding issue template.
+
+The maintenance team will read all created issues and …:
+
+<!--1. … assign them to proper [projects](../../projects/)
+based on targerted library version. Also, each issue schould have chooosed
+priority (__low__/__high__) by using specific column i project
+(__To Do – Low priority__/__To Do – High priority__).-->
+1. … assign them to targerted milestone (with specific deadline, if it is known).
+
+## Patches
+__We're super grateful for your patch__
+
+The best way to make sure your issue is addressed is to submit a patch.
+We accept patches through all mediums: pull requests, email, issue
+comment, tweet with a link to a snippet, etc.
+
+However, before sending a patch, please take try to:
+
+- make your commit message describtive and use issue links for better
+understandig commit purpose.
+- make your coding style similar to ours (TBD).
+
+### Development Environment
+The library is developed using [Node.js](http://nodejs.org/) and has
+a number of dependencies specified in its package.json file.
+To install them just run the following command from within your
+repo directory:
+```bash
+$ npm ci
+```
+
+## Documentation/examples improvements
+You can use issue for reporting errors and suggesting improvements
+similary to [Issues reports](#issues-reports). It is also acceptable
+to open issue with question if it wasn’t currently adressed anywhere
+and you think it schould.
+
+For updating documentation and examples follow [Patches](#Patches).
+The documentation is created by [typedoc](https://github.com/TypeStrong/typedoc).
+Examples are in [examples/](./docs/examples/).
+
+---
+This text was inspired by
+[jshint’s one](https://github.com/jshint/jshint/blob/master/CONTRIBUTING.md).

README.md

@@ -8,14 +8,13 @@ This is primarily achieved by using [shelljs/shelljs](https://github.com/shelljs
 You can compare the final script code to `zx` example:
 ```javascript
 #!/usr/bin/env nodejsscript
-import { s, echo } from "nodejsscript";
 echo(s.grep("name", "package.json"));
 
-s.exec("git branch --show-current").xargs(s.exec, "dep deploy --branch={}");
+s.run("git branch --show-current").xargs(s.run, "dep deploy --branch={}");
 
-s.exec("sleep 1; echo 1");
-s.exec("sleep 2; echo 2");
-s.exec("sleep 3; echo 3");
+s.run("sleep 1; echo 1");
+s.run("sleep 2; echo 2");
+s.run("sleep 3; echo 3");
 
 import { join } from "node:path";
 const name= "foo bar";
@@ -27,10 +26,11 @@ s.mkdir(join(s.tempdir(), name));
 
 1. tested/used on *NodeJS*: `[email protected]` and `[email protected]` ⇒ for installation follow [nvm-sh/nvm: Node Version Manager](https://github.com/nvm-sh/nvm)[^OR]
 1. `npm install https://github.com/jaandrle/nodejsscript --global` (**will be registered also in npm repository**)
+1. alternatively install locally
 
 ## Goods
 [s #shelljs](./docs/modules/s.md)
- · [cli](./docs/modules/cli.md) ([cli.api() #sade](./docs/modules/cli.md#api), [cli.read()](./docs/modules/cli.md#read), …)
+ · [cli](./docs/modules/cli.md) ([cli.api() #sade](./docs/modules/cli.md#api), [cli.read()](./docs/modules/cli.md#read), [cli.xdg](./docs/modules/xdg_.xdg.md), …)
  · [echo()](./docs/README.md#echo)
  · [fetch() #node-fetch](./docs/README.md#fetch)
  · [style #ansi-colors](./docs/modules/style.md)
@@ -59,17 +59,65 @@ Or via the `nodejsscript` executable:
 nodejsscript ./script.mjs
 ```
 
-All function (`shelljs`, `fetch`, …) are exported by library, so use:
-```javascript
-import { … } from "nodejsscript";
+<details>
+<summary>Alternatively when installed locally</summary>
+
+```bash
+#!/usr/bin/env -S npx nodejsscript
+```
+```bash
+npx nodejsscript ./script.mjs
 ```
-… *The entry point for documentation of all exported (**Public**) items is in the* [**docs/**](./docs/README.md).
+
+</details>
+
+All function (`shelljs`, `fetch`, …) are registered as global namespaces/functions:
+… *The entry point for documentation of all **Public** items is in the* [**docs/**](./docs/README.md).
 
 Note that there are also built-in `'node:*'` modules:
 ```js
 import { setTimeout } from "node:timers/promises";
 import { join, resolve } from "node:path";
+
+//current file url
+import.meta.url;
+//url to path
+import { fileURLToPath } from "node:url";
+const file_path= fileURLToPath(import.meta.url);
 ```
 …and more, see [Node.js v17.9.1 Documentation](https://nodejs.org/docs/latest-v17.x/api/documentation.html#stability-overview).
 
+## Security guidelines
+**`run()` command injection**: this advice applies to `child_process.exec()` just as
+much as it applies to `s.run()`. It is potentially risky to run commands passed
+for example by user input:
+```js
+function curlUnsafe(urlToDownload){ return s.run('curl ' + urlToDownload); }
+curlUnsafe('https://some/url ; rm -rf $HOME'); //=> curl https://some/url ; rm -rf $HOME
+```
+Therefore, `nodejsscript`s `s.run()` provide way to escapes untrusted parameters:
+```js
+function curl(url){ return s.run("run ::url::", { url }); }
+curl('https://some/url ; rm -rf $HOME'); //=> curl 'https://some/url ; rm -rf $HOME'
+```
+…*Note: The ['xargs()'](../interfaces/s.XargsFunction.md) by default also escapes piped strings.*
+
+*…Note 2: `s.run(…cmd, …vars)` is also helpul for escaping parameters passed as variables (e.g. arrays).*
+
+*…Note 3: ShellJS also provides `s.exec`, but `s.run` should be prefered way to execute commands.*
+
+**Glob injection (all commands)**: Most ShellJS commands support [glob](https://github.com/isaacs/node-glob) expansion,
+expanding wildcards such as `*` to match files. While this is very powerful,
+dependent modules should exercise caution. Unsanitized user input may contain
+wildcard characters. Consider for example that the `*.txt` is valid file name,
+however the `s.rm("*.txt")` by default (using the globbing) delete all `txt` files.
+Keep in mind that you can always turn off this for next command by using:
+```js
+s.$("-g").rm("*.txt");
+```
+
+## Contribute
+- [Contributor Covenant Code of Conduc](./CODE_OF_CONDUCT.md)
+- [How to contribute](./CONTRIBUTING.md)
+
 [^OR]: Alternatively `curl -sL install-node.vercel.app/16.13.0 | bash`