package-lock.json

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+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.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

LICENSE.md

@@ -0,0 +1,20 @@
+<!-- This file is automatically added by @npmcli/template-oss. Do not edit. -->
+
+ISC License
+
+Copyright npm, Inc.
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted, provided that the above copyright notice and this
+permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND NPM DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL NPM BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
+USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -1,38 +1,109 @@
-# GitHub Docs <!-- omit in toc -->
-
-Welcome to GitHub Docs! GitHub’s documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our [contributing guide](https://docs.github.com/en/contributing).
-
-
-## Quick links by contributor type
-
-* **Hubbers (GitHub employees):** See [CONTRIBUTING.md](https://github.com/github/docs-content/blob/main/CONTRIBUTING.md) in the `docs-content` repository for GitHub-specific processes.
-
-* **Open source contributors:** See [CONTRIBUTING.md](https://github.com/github/docs/blob/main/.github/CONTRIBUTING.md) in the `docs` repository for a quick-start summary.
-
-## How we sync changes across Docs repositories
-
-There are two GitHub Docs repositories: 
-
-- **`github/docs`** (public): Open to external contributions
-
-- **`github/docs-internal`** (private): For GitHub employee contributions. 
-
-The two repositories sync frequently. Content changes in one are reflected in the other.  Hubbers might prefer to post in `docs` when working with a customer, but `docs` has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to `docs-internal`.
-
-**Important:** The `docs` repository accepts contributions to content files (`.md` files in `/content` and select `/data` sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification.
-
-## New to contributing
-
-Here are some resources to help you get started with open source contributions:
-
-* [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)
-* [Set up Git](https://docs.github.com/en/get-started/git-basics/set-up-git)
-* [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow)
-* [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests)
-
-## License
-
-This project is dual-licensed under:
-
-* **Creative Commons Attribution 4.0** - for documentation and content in the assets, content, and data folders (see [LICENSE](LICENSE))
-* **MIT License** - for code (see [LICENSE-CODE](LICENSE-CODE))
+# @npmcli/installed-package-contents
+
+Get the list of files installed in a package in node_modules, including
+bundled dependencies.
+
+This is useful if you want to remove a package node from the tree _without_
+removing its child nodes, for example to extract a new version of the
+dependency into place safely.
+
+It's sort of the reflection of [npm-packlist](http://npm.im/npm-packlist),
+but for listing out the _installed_ files rather than the files that _will_
+be installed.  This is of course a much simpler operation, because we don't
+have to handle ignore files or package.json `files` lists.
+
+## USAGE
+
+```js
+// programmatic usage
+const pkgContents = require('@npmcli/installed-package-contents')
+
+pkgContents({ path: 'node_modules/foo', depth: 1 }).then(files => {
+  // files is an array of items that need to be passed to
+  // rimraf or moved out of the way to make the folder empty
+  // if foo bundled dependencies, those will be included.
+  // It will not traverse into child directories, because we set
+  // depth:1 in the options.
+  // If the folder doesn't exist, this returns an empty array.
+})
+
+pkgContents({ path: 'node_modules/foo', depth: Infinity }).then(files => {
+  // setting depth:Infinity tells it to keep walking forever
+  // until it hits something that isn't a directory, so we'll
+  // just get the list of all files, but not their containing
+  // directories.
+})
+```
+
+As a CLI:
+
+```bash
+$ installed-package-contents node_modules/bundle-some -d1
+node_modules/.bin/some
+node_modules/bundle-some/package.json
+node_modules/bundle-some/node_modules/@scope/baz
+node_modules/bundle-some/node_modules/.bin/foo
+node_modules/bundle-some/node_modules/foo
+```
+
+CLI options:
+
+```
+Usage:
+  installed-package-contents <path> [-d<n> --depth=<n>]
+
+Lists the files installed for a package specified by <path>.
+
+Options:
+  -d<n> --depth=<n>   Provide a numeric value ("Infinity" is allowed)
+                      to specify how deep in the file tree to traverse.
+                      Default=1
+  -h --help           Show this usage information
+```
+
+## OPTIONS
+
+* `depth` Number, default `1`.  How deep to traverse through folders to get
+    contents.  Typically you'd want to set this to either `1` (to get the
+    surface files and folders) or `Infinity` (to get all files), but any
+    other positive number is supported as well.  If set to `0` or a
+    negative number, returns the path provided and (if it is a package) its
+    set of linked bins.
+* `path` Required.  Path to the package in `node_modules` where traversal
+    should begin.
+
+## RETURN VALUE
+
+A Promise that resolves to an array of fully-resolved files and folders
+matching the criteria.  This includes all bundled dependencies in
+`node_modules`, and any linked executables in `node_modules/.bin` that the
+package caused to be installed.
+
+An empty or missing package folder will return an empty array.  Empty
+directories _within_ package contents are listed, even if the `depth`
+argument would cause them to be traversed into.
+
+## CAVEAT
+
+If using this module to generate a list of files that should be recursively
+removed to clear away the package, note that this will leave empty
+directories behind in certain cases:
+
+- If all child packages are bundled dependencies, then the
+    `node_modules` folder will remain.
+- If all child packages within a given scope were bundled dependencies,
+    then the `node_modules/@scope` folder will remain.
+- If all linked bin scripts were removed, then an empty `node_modules/.bin`
+    folder will remain.
+
+In the interest of speed and algorithmic complexity, this module does _not_
+do a subsequent readdir to see if it would remove all directory entries,
+though it would be easier to look at if it returned `node_modules` or
+`.bin` in that case rather than the contents.  However, if the intent is to
+pass these arguments to `rimraf`, it hardly makes sense to do _two_
+`readdir` calls just so that we can have the luxury of having to make a
+third.
+
+Since the primary use case is to delete a package's contents so that they
+can be re-filled with a new version of that package, this caveat does not
+pose a problem.  Empty directories are already ignored by both npm and git.