@libyears/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Selvakumar Arumugam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @libyears/cli
+
+How far behind are your dependencies?
+
+```bash
+npx @libyears/cli
+```
+
+```
+/Users/you/project  pnpm lockfile v9.0
+
+PACKAGE       INSTALLED  LATEST  BEHIND     LIBYEARS
+typescript    5.9.3      7.0.2   2 major        0.77
+@types/node   20.19.43   26.2.0  6 major        0.16
+eslint        9.39.5     10.9.0  1 major        0.11  deprecated
+
+1.0 libyears behind · 34 direct, 683 transitive · 3 a major behind · 14 current
+  7 private packages counted but never sent to the registry
+```
+
+No account, no sign-up, no configuration. Reads your lockfile, asks the npm
+registry when each version was published, and tells you how much release time
+you are behind.
+
+## What a libyear is
+
+One libyear is one year of release time between what you have installed and
+the latest stable version. A package you upgraded last week contributes almost
+nothing; one you pinned in 2019 contributes six. Summed across a project it is
+a single number for "how far behind are we", and unlike a count of outdated
+packages it does not treat a patch release the same as five years of drift.
+
+The idea is [Jared Beck's](https://libyear.com). This adds versions behind,
+deprecation and removed-from-registry detection, and every lockfile format.
+
+## Privacy
+
+Private package names never leave your machine. Anything published to a
+private registry, resolved from a scope with its own registry, or defined
+inside your own workspace is counted and never named to anyone. Credentials in
+`.npmrc`, `.yarnrc.yml` and `bunfig.toml` are discarded before parsing and are
+never stored or logged.
+
+Nothing is uploaded at all unless you pass `--push`.
+
+## Supported lockfiles
+
+`pnpm-lock.yaml` (5.4, 6.0, 9.0 and pnpm 11 multi-document), `package-lock.json`
+(v1, v2, v3), `yarn.lock` (classic and Berry), and `bun.lock` (v0 to v3).
+Handles `npm:` aliases, catalogs, overrides, peer suffixes and workspace
+protocols. With no lockfile it falls back to declared ranges and says so.
+
+## In continuous integration
+
+```bash
+npx @libyears/cli --max-libyears 10 --max-majors 2
+```
+
+Exit codes are the contract:
+
+| Code | Meaning |
+|---|---|
+| 0 | scanned, and within any thresholds given |
+| 1 | a threshold was exceeded, or a `--push` was rejected |
+| 2 | the command could not run: bad arguments, no `package.json` |
+
+`1` and `2` are kept apart deliberately. A pipeline that treats them the same
+passes silently the day the scan itself breaks.
+
+## Options
+
+```
+  --json                 machine-readable output
+  --offline              skip the registry: inventory only, no freshness
+  --limit <n>            rows to print before summarising (default 25)
+  --concurrency <n>      parallel registry requests (default 8)
+
+  --max-libyears <n>     exit 1 if the total exceeds n
+  --max-majors <n>       exit 1 if any direct dependency is more than n majors behind
+
+  --push                 upload this snapshot to a hosted ledger
+  --token <t>            project token (or set LIBYEARS_TOKEN)
+  --api <url>            override the endpoint (or set LIBYEARS_API)
+```
+
+`NO_COLOR` and `FORCE_COLOR` are honoured. Output piped to a file carries no
+escape sequences.
+
+## Why "latest" can differ from `npm outdated`
+
+A release published in the last fourteen days does not count as lag yet. You
+have not fallen behind because someone published this morning. The genuinely
+newest version is still reported in the summary line, so the difference is
+visible rather than mysterious.
+
+## Pushing to a hosted ledger
+
+`--push` sends the inventory — package names, versions and dependency types —
+to [libyears.com](https://libyears.com), where it joins the same ledger a
+GitHub App installation would produce. No source code, no file contents, no
+lockfile, and no private package names. It is the ingestion path for GitLab,
+Bitbucket and self-hosted repositories.
+
+The hosted product is a separate, proprietary application. This CLI, the
+lockfile parsers and the freshness metrics are MIT and work entirely without
+it.
+
+## Licence
+
+MIT.