Skip to content

Available updates report

Terminal window
.repo-standards/runtime/node_modules/.bin/repo-standards outdated
.repo-standards/runtime/node_modules/.bin/repo-standards outdated --json

outdated reports whether an available update exists for each pin of the adopting project’s selection: a published CLI or standards version newer than the pinned one. It reads .repo-standards/selection.yaml, looks up the newest stable versions, and compares each to its pin. It runs no author code, needs no clean working tree, and changes nothing in the project except its own ignored cache, so it is safe to run at the start of any session. Without --json it renders a Markdown report; with --json it returns the JSON report and also makes invalid usage and the pinned CLI failure structured. --project <directory> selects another Git working tree.

The report states availability only. It updates nothing and does not recommend an update; whether to update is the maintainer’s decision. Adoption installs the model-invocable repository-standards system skill, which reports this result to an agent, also reads the repository-wide installed rules at the start of any work and looks up the rules covering a file before changing it, and starts no update; outdated remains the complete interface without an agent. Apply an update through inspection and start as described in Adoption. To have every available update proposed as a pull request instead, opt in to the update action.

There is no stability promise. Releases are frequent, and every release, including a breaking release, must be adoptable from the previous release in one adopt invocation without hand edits. Published acceptance proves the CLI update with the public learning source; it does not replace contextual agent assessment or establish that a deployment is healthy. A change that cannot update in one step is redesigned before its release is complete. Work outside adoption is an adopter action, which the update still completes around.

To stay current, run outdated with the project’s pinned CLI, then run adopt with the new CLI to update the selection. Review and commit the resulting run. The opt-in update action checks daily and proposes every available update as one rolling pull request, or reports the questions that need agent work. Release notes open with the same derived adopter-action line the update reports, followed by any author-written actions outside adoption.

Without --json, outdated prints a Markdown report. The same report renders the same bytes, and rendering makes no request and changes nothing beyond what the JSON form does. The report holds:

  • A Pins table with one row for the CLI package and one for the standards source: the pinned and newest versions, the update (available, none or unknown), the number of newer stable releases, when the answer was looked up and whether the lookup was fresh or cached. A value the report does not have reads unknown, and a pin or source the selection does not record reads not recorded.
  • An Adopter actions table, present when a newer stable release exists: each newer release with the one-line adopter action its author wrote, none when it sets none, or unreadable with the reason code and message when its standards.yaml could not be read. A line below it says the line derived from an update comes from adopt and inspect.
  • An Unknown results table, present only when a pin could not be answered: the pin, the reason’s code and its message. It covers a missing selection and a failed lookup of either pin while the other is still answered.

The values agree with the JSON report, which carries every field the Markdown does and stays the interface for scripts. Both formats state availability only; neither prescribes or starts an update. status keeps its own Markdown record and says nothing about available updates.

Before 8.0.0, outdated printed the JSON report with or without --json. It prints Markdown unless --json is given. Scripts that parse the report add --json; the flag has always been accepted. The repository-standards system skill already passes --json.

The JSON report is now repo-standards/outdated/v2, and its standards entry gains adopterActions when the lookup answers (see Adopter actions). Scripts that compare the format value accept v2; every other field is unchanged. An older ignored cache is not read, so the first invocation looks up again.

Run outdated with the CLI the selection pins. When the selection records a CLI pin and the running CLI is another version, outdated makes no lookup, writes no cache, and exits 1 with CLI_PIN_MISMATCH. The message names the pinned version and, when the committed runtime manifest and its npm lock both pin that version, the project root and the command, run there, that reinstalls the project runtime from them:

Terminal window
npm ci --ignore-scripts --prefix .repo-standards/runtime

When either file is missing, unreadable, or pins another version, the message names an exact CLI installed outside the project instead.

A stale project runtime therefore never reports availability. With --json the failure is valid: false with the diagnostic in errors; without it the diagnostic goes to stderr. Without a readable selection no pin is recorded, so every CLI reports both pins unknown as described under Degraded results. To change the CLI pin, inspect with the candidate exact CLI instead; see Update the selection.

An update can ask adopters for something outside adoption. A source author writes that as the optional adopter-action field of the root standards.yaml (author format). For each newer stable standards release, outdated reads that release’s standards.yaml at its tag once, through the GitHub request helper, and reports the line: an Adopter actions table in Markdown and adopterActions in JSON, oldest release first. Each entry has the release version and its action, which is null when the release sets none. A release whose file cannot be read, such as an unreachable file or an invalid line, reports a reason with a code and message for that release alone, and the report still answers.

outdated runs no inspection, so it cannot derive the rest of the line, which depends on the update class, the project’s declarations and remote setup. That line comes from adopt and inspect. The adopter actions are present when the standards pin was answered, an empty list when no release is newer, and absent when it is unknown.

Each invocation looks up the npm registry and GitHub releases in parallel, then reads the standards.yaml of each newer stable release, so a pin behind by n releases costs one registry request, the pages of the release list, and n file requests. Each file request is bounded to ten seconds too. The registry request and each request in the paginated release lookup are bounded to ten seconds:

  • The CLI pin is compared with the versions of @lutzseverino/repo-standards published by the registry named in npm_config_registry, or by https://registry.npmjs.org/ when it is unset. npm configuration files are not read.
  • The standards pin is compared with the source repository’s published GitHub releases across all pages. A token in GH_TOKEN, or otherwise GITHUB_TOKEN, is sent to GitHub as bearer authorization when present; without one the request is anonymous and uses the anonymous API quota. Values are trimmed; empty or whitespace-only values count as absent. Release reads and exact-tag resolution use Postern’s ReleaseSource; other source-verification reads keep their GitHub boundary. A token uses the authenticated quota and is never recorded in reports or caches, or sent to the npm registry or on Git object downloads. A rejected token (HTTP 401) reports SOURCE_UNAVAILABLE with no anonymous retry. Quota retry guidance prefers a usable retry-after over x-ratelimit-reset when both arrive.

A stable version is a SemVer version without a prerelease component. For the standards pin it must also be the tag of a published GitHub release that is not marked as a prerelease. Drafts, prereleases, and tags that are not SemVer versions are ignored. Tags published without a GitHub release are not counted.

With --json, the report has format repo-standards/outdated/v2 and one entry per pin: cli, which also names the package, and standards, which also names the source repository.

FieldMeaning
pinnedThe version recorded in the selection, or null without a readable selection.
updateavailable when a newer stable version exists, none when it does not, or unknown when the pin could not be answered.
newestThe highest stable version published.
newerStableReleasesHow many stable versions newer than the pin are published, up to and including newest.
checkedAtWhen the answer was looked up.
cachedWhether the answer came from the cache instead of a request.
reasonFor unknown only: a stable code and a message.
adopterActionsStandards pin only, when answered: each newer release’s version, author-written action or null, and reason if unreadable.

outdated never blocks and exits 0 whether or not each pin could be answered; only a CLI other than the pin exits 1, and invalid usage exits 2. A pin that cannot be answered reports update: unknown with a reason, and the other pin is still answered:

CodePinsCause
NO_SELECTIONBothThe directory is not a Git working tree or has no .repo-standards/selection.yaml.
INVALID_SELECTIONBothThe selection cannot be read or does not name a CLI and GitHub source pin.
REGISTRY_UNAVAILABLECLIThe registry is unreachable, timed out, or returned an error or no version list.
SOURCE_UNAVAILABLEStandardsGitHub is unreachable, timed out, or returned an error or no release list.
QUOTA_EXHAUSTEDStandardsGitHub reports its API quota exhausted. The message names the usable reset time or retry delay and GH_TOKEN and GITHUB_TOKEN.
NO_STABLE_RELEASEEitherThe lookup found no stable version.
LOOKUP_FAILEDEitherThe lookup failed unexpectedly.

Answers are cached in .repo-standards/cache/outdated.json, inside the product cache directory that .repo-standards/.gitignore ignores. Each lookup’s answer stays valid for 24 hours for the same registry, or for the same source repository, and each release’s adopter action stays valid for 24 hours for the same release; a second invocation within that time answers from the cache without a request. unknown answers and unreadable releases are not cached, so the next invocation looks up again. The cache is written only when Git confirms that its path is ignored and its directory is a safe product-state boundary; otherwise the answer stands without a cache. Nothing else is written, the cache never binds an inspection identity, and deleting the file forces fresh lookups.

status remains offline: it reports pins and evidence without any network request and says nothing about available updates.