fyn 3.2.3 → 3.3.1

package/README.md

@@ -1,8 +1,14 @@
 # fyn
 
-[![NPM version][npm-image]][npm-url]
-[![Apache 2.0 License][apache-2.0-blue-image]][apache-2.0-url]
-[![Build Status][build-image]][build-url]
+[![License][license-image]][license-url]
+[![build][build-image]][build-url]
+
+[![Downloads][downloads-image]][downloads-url]
+
+[![npm badge][npm-badge-png]][package-url]
+
+- [Markdown reference](docs/reference.md) - the full CLI reference and runtime behavior in one file. Also ships in the package.
+- [GitHub](https://github.com/jchip/fynjs/tree/main/packages/fyn)
 
 **fyn** is a fast package manager for Node.js. It treats your disk as a registry, so you can develop and test packages using local copies. It uses hardlinks and a shared store to save disk space and speed up installs. It can link live source folders between packages, so changes show up right away. It reads your existing `.npmrc` and lockfiles, and it powers [fynpo], a zero-setup monorepo tool.
 
@@ -16,6 +22,12 @@ cd <your-project>
 fyn
 ```
 
+Once fyn is installed, it can manage its own global install:
+
+```sh
+fyn global add fyn
+```
+
 On an existing install, fyn checks file modification times before reinstalling. This scan
 prunes directories and files matched by repository and nested `.gitignore` rules, alongside
 its built-in exclusions. The rules apply even to tracked source files; manifests, lockfiles,
@@ -45,6 +57,16 @@ fyn outdated lodash --json
 and the registry's `latest` tag. Local, Git, and URL dependencies are not compared. Pass
 `--refresh-meta` to bypass fresh registry metadata caches.
 
+To move locked versions to the newest their declared ranges allow:
+
+```sh
+fyn update
+fyn update lodash
+```
+
+With no names, `update` ignores every lock pin. With names, it updates those packages and their
+dependencies and keeps the rest pinned. It never edits `package.json`.
+
 - It can read and use some settings from your `.npmrc`.
 - It can use `npm-shrinkwrap.json` or `package-lock.json` files.
 
@@ -56,29 +78,23 @@ fyn options can be listed in help:
 fyn --help
 ```
 
-fyn loads config from `CWD/.fynrc`, `CWD/.npmrc`, `~/.fynrc`, and `~/.npmrc` in this specified order, from highest to lowest priority.
+fyn loads config from up to 9 rc files. Later files override earlier ones, so this list goes from lowest to highest priority:
 
-From `.npmrc`, only fields `registry`, `@<scope>:registry`,`email`, and `_auth` are read.
+1. `$NPM_CONFIG_GLOBALCONFIG`
+2. `$PREFIX/etc/npmrc`
+3. `$NPM_CONFIG_USERCONFIG`
+4. `~/.npmrc`
+5. `~/.fynrc`
+6. `<fynpo dir>/.npmrc` (in a fynpo monorepo, when CWD is not the fynpo dir)
+7. `<fynpo dir>/.fynrc` (same as above)
+8. `CWD/.npmrc`
+9. `CWD/.fynrc`
 
-`.fynrc` file can be an [ini] or `YAML` format. For the `YAML` format, the first line must be `---`.
+fyn merges every key from every rc file into its options, including `.npmrc` files.
 
-Below is an `YAML` example, with all the options set to their default values:
+Every rc file is parsed as [ini]. YAML is not supported.
 
-```yml
----
-registry: https://registry.npmjs.org
-"@scope:registry": https://registry.custom.com
-offline: false
-forceCache: false
-lockOnly: false
-progress: normal
-logLevel: info
-production: false
-centralStore: false
-hardlink: true
-```
-
-Or as an ini:
+Below is an ini example, with the options set to their default values:
 
 ```ini
 registry=https://registry.npmjs.org
@@ -89,10 +105,29 @@ lockOnly=false
 progress=normal
 logLevel=info
 production=false
-centralStore=false
 hardlink=true
 ```
 
+`centralStore` has no fixed default. When it is unset in a non-fynpo project, fyn turns it on for macOS when @fynjs/reflink can clone dirs, and for Linux when it can hardlink or clone. It stays off on other platforms. A fynpo monorepo uses its own central store. Set `centralStore=false` to keep it off in a non-fynpo project.
+
+### `.fynrc` sections
+
+A `.fynrc` file can have sections that apply only in some environments. Top level keys are the defaults, and a matching section overrides them.
+
+- `[IS_CI]` matches when the `CI` or `BUILD_ENV` env var is set.
+- `[CI:value]` matches when `CI` equals `value`. If `CI` is unset, `BUILD_ENV` is checked instead.
+- `[VAR:value]` matches when env var `VAR` equals `value`.
+- `[A|B:value]` matches when `A` or `B` equals `value`.
+
+When several sections match, `[CI:value]` wins over `[IS_CI]`, and `[IS_CI]` wins over `[VAR:value]`.
+
+```ini
+progress=normal
+
+[IS_CI]
+progress=none
+```
+
 ### Local source exports (`fyn.localExports`)
 
 A package can expose local development directories by declaring them in its
@@ -464,8 +499,9 @@ or per-invocation on the command line:
 fyn install --no-enforce-registry-deps
 ```
 
-The CLI flag takes precedence over the `package.json` setting, which takes
-precedence over the default (on).
+Any explicitly set option takes precedence over the `package.json` setting. That
+covers the CLI flag, an `enforceRegistryDeps` key in an rc file, and fynpo's
+`fyn.options`. The `package.json` setting takes precedence over the default (on).
 
 This is independent of the lifecycle-script controls above: `allowScripts` /
 `allowTopLevelScripts` decide whether *scripts run*, while `enforceRegistryDeps`
@@ -498,12 +534,6 @@ Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses
 [ini]: https://www.npmjs.com/package/ini
 [node_preserve_symlinks]: https://nodejs.org/docs/latest-v8.x/api/cli.html#cli_node_preserve_symlinks_1
 [require-at]: https://www.npmjs.com/package/require-at
-[build-image]: https://github.com/jchip/fynjs/actions/workflows/ci.yml/badge.svg
-[build-url]: https://github.com/jchip/fynjs/actions/workflows/ci.yml
-[npm-image]: https://badge.fury.io/js/fyn.svg
-[npm-url]: https://npmjs.org/package/fyn
-[apache-2.0-blue-image]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
-[apache-2.0-url]: https://www.apache.org/licenses/LICENSE-2.0
 [npm scripts]: https://docs.npmjs.com/misc/scripts
 [node-tar]: https://www.npmjs.com/package/tar
 [semver]: https://www.npmjs.com/package/semver
@@ -517,3 +547,12 @@ Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses
 [npm link]: https://docs.npmjs.com/cli/link.html
 [@npmcli/run-script]: https://www.npmjs.com/package/@npmcli/run-script
 [npmlog]: https://www.npmjs.com/package/npmlog
+
+[license-image]: https://img.shields.io/npm/l/fyn.svg
+[license-url]: LICENSE
+[build-image]: https://github.com/jchip/fynjs/actions/workflows/ci.yml/badge.svg
+[build-url]: https://github.com/jchip/fynjs/actions/workflows/ci.yml
+[downloads-image]: https://img.shields.io/npm/dm/fyn.svg
+[downloads-url]: https://npm-stat.com/charts.html?package=fyn
+[npm-badge-png]: https://nodei.co/npm/fyn.png?downloads=true&stars=true
+[package-url]: https://npmjs.com/package/fyn