@jakobm/groundskeeper
v0.1.1
Published
Operations and checks across local Git repositories
Readme
Groundskeeper
Operations and checks across local Git repositories. Requires Linux with /proc and flock, Git, Node.js 22.14+ in the 22.x line, npm, Volta for pinned toolchains, and access to the relevant GitHub and npm registries. Groundskeeper pins Node.js 22.14.0 and npm 11.21.0.
Install the public npm package globally:
npm install -g @jakobm/groundskeeper
groundskeeper --help
groundskeeper versionThe global command is groundskeeper and can be run from any directory. To install a development checkout instead, use npm link:
volta run npm ci
volta run npm link
groundskeeper --help
groundskeeper versionUse groundskeeper --help to list command groups or groundskeeper dependencies update --help for command-specific arguments and options. Invalid commands or arguments exit with code 2.
groundskeeper version prints the full Git SHA embedded when Groundskeeper was built, so it does not require access to the source checkout at runtime.
Shell completion
Cmdabra provides tab completion for commands, options and enum values. After installing or rebuilding Groundskeeper, add this adapter to ~/.bashrc for Bash:
_groundskeeper_completion() {
COMPREPLY=()
mapfile -t COMPREPLY < <(
command "${COMP_WORDS[0]}" --cmdabra-complete "$COMP_CWORD" "${COMP_WORDS[@]}" 2>/dev/null
)
}
complete -F _groundskeeper_completion groundskeeperFor zsh, add this to ~/.zshrc after initializing completion with autoload -Uz compinit; compinit:
_groundskeeper_completion() {
local -a candidates
candidates=("${(@f)$("$words[1]" --cmdabra-complete "$((CURRENT - 1))" "${words[@]}" 2>/dev/null)}")
compadd -- "${candidates[@]}"
}
compdef _groundskeeper_completion groundskeeperReload the shell configuration or open a new shell, then try groundskeeper dependencies <TAB> or groundskeeper projects create --publish-to-npm <TAB>. Candidates come from the installed CLI's current cmdabra.yaml; completion does not load Groundskeeper configuration or execute a command handler.
Configuration
Pass the shared YAML configuration with --config-file <path>, or set GROUNDSKEEPER_CONFIG_FILE as a fallback. An explicit command-line value takes precedence. With neither value, Groundskeeper tries groundskeeper.config.yaml in the current directory and uses empty configuration if that default file does not exist. Relative paths in the configuration resolve against the file's directory. Missing explicitly selected files, unreadable files, empty environment values, invalid YAML and unknown keys are errors. Shared values have no individual CLI overrides: positional inventory roots, --repos-directory, --npm-user and --owner are rejected. The former projectsDirectory key is replaced by reposDirectory.
reposDirectory: /home/you/code
user:
github: your-reviewer
npm: your-npm-account
projectAuthor:
name: Your Name
email: [email protected]
automationCommitIdentity:
name: Your Automation
email: [email protected]
ignoredGithubRepositories:
- example/old-projectInventory commands require reposDirectory. Dependency audit also requires user.npm and an authenticated GitHub CLI; secret sync requires user.github. GitHub and dependency audits use every repository visible to the authenticated GitHub CLI identity and do not require a configured GitHub user. Project creation requires reposDirectory, both user.* account values and both projectAuthor.* values. First update requires current shared configuration, including user.github as human reviewer and both automationCommitIdentity.* values for commits made by dependency and release automation. It also requires an authenticated GitHub CLI identity that differs from the configured reviewer and can write to every selected repository. The two identity objects are deliberately separate: project authorship is human-facing package metadata, while automation commit identity identifies machine-made Git history. Groundskeeper passes the automation identity explicitly and does not fall back to the ambient Git configuration. Ignored GitHub repositories are excluded from GitHub and dependency audits and automatic secret discovery; explicit --new-repo still includes them for secret synchronization.
Configurations using the former user.name and user.email fields must move those values to projectAuthor and add an explicit automationCommitIdentity. Dependency executions frozen with the former combined identity contract must be recreated from a fresh audit.
Create a project
Create the GitHub repository first and leave it completely empty, then run:
groundskeeper projects create --name my-library --publish-to-npm trueBoth options are required. Pass only the lowercase repository and package basename to --name, for example my-library, without a GitHub owner or URL. --publish-to-npm accepts only true or false. Groundskeeper derives the repository URL as https://github.com/<user.github>/<name>.git, creates the destination at <reposDirectory>/<name>, and forwards projectAuthor.name and projectAuthor.email as the package author and initial commit author. Publishing projects use @<user.npm>/<name> as their package name; private projects use the unscoped <name>.
Groundskeeper invokes its exactly pinned @jakobm/peacekeeper runtime dependency, which owns the generated files, validation, installation, tests, commit and push. It does not use a global peacekeeper, npx, or a latest-version lookup. The destination must not already exist, even when empty, and the GitHub repository must contain no refs. Preflight failures create nothing. Failures after generation starts leave the local directory for inspection; Groundskeeper does not delete it or retry Git operations.
On success, enter the new project, run its committed setup-github-config.sh, and complete the manual GitHub—and, for publishing projects, npm trusted-publishing—steps listed by that script. Groundskeeper does not run the script or publish the package.
Update dependencies across repositories
groundskeeper dependencies audit
# Select one or more audited dependencies on the first update:
groundskeeper dependencies update --working-directory /tmp/groundskeeper-dependencies-update/update-XXXXXX --dependency @jakobm/peacekeeper --dependency @jakobm/portico
# Optionally limit that campaign to audited repositories (paths relative to reposDirectory):
groundskeeper dependencies update --working-directory /tmp/groundskeeper-dependencies-update/update-XXXXXX --dependency @jakobm/peacekeeper --repository producer --repository consumer
# Start with every outdated dependency, or resume the frozen selection:
groundskeeper dependencies update --working-directory /tmp/groundskeeper-dependencies-update/update-XXXXXX
groundskeeper dependencies list
groundskeeper dependencies remove --working-directory /tmp/groundskeeper-dependencies-update/update-XXXXXXAudit starts from every nonignored repository visible to the authenticated GitHub CLI identity. It reads each default-branch root manifest at an exact GitHub commit and includes every repository with a root package.json; dependency and repository campaign selection happens later, when update starts.
Selected repositories are matched to existing clones below reposDirectory by canonical GitHub origin, regardless of their local directory name. Missing clones are created persistently at <reposDirectory>/<repo> when that basename is unique. When multiple selected repositories share a basename, new clones use <reposDirectory>/<owner>/<repo>. Existing clones are never moved; a later colliding clone uses the owner-qualified path. Multiple existing clones of the same GitHub repository, or an occupied destination that is not the intended repository, are reported as errors rather than resolved destructively. Cloning uses a hidden staging directory and only exposes the destination after the clone completes.
The deep audit then inspects fetched default branches and creates a unique execution directory under the system temp parent groundskeeper-dependencies-update. Every directly declared dependency, whether owned or third-party, resolves against the npm latest tag during audit. The observed exact versions are persisted so one execution never changes a selected target when a tag moves. npm access list packages <user.npm> --json separately identifies public packages that the configured npm user can write and is used only for producer and publication decisions. These public registry reads do not require npm login, npm whoami or a local npm token. Private registry packages are outside that unauthenticated guarantee.
The audit saves audit.json, the full inventory plan, GitHub inventory and clone evidence, versioned ownership metadata and logs. stdout always contains a readable report, absolute directory and an unquoted continuation command. The saved audit has artifact.workingDirectory, artifact.executable and artifact.args for safe structured continuation. Audit has no --json, --output, --keep-worktrees or dependency-selection option. Successful inventory worktrees are cleaned; useful failed-operation logs remain. Apart from materializing missing persistent clones, audit does not update project files, commit, push, create PRs or publish packages.
Update starts or resumes that exact directory; there is no implicit latest execution or separate run ID. On first start, omitting --dependency selects every audited dependency with an outdated installed version or requirement, including dependencies whose fixes still need publication. Repeat --dependency to limit the update to specific packages. If no dependencies need updates, the execution completes without starting workers. Without --repository, it selects every candidate affected by those dependencies. Invalid dependencies, invalid repositories and excluded required producers fail before workers start. The first valid start atomically saves both selections, audited npm packages, reviewer and relevant non-secret configuration in contract.json. Missing required configuration can be corrected before this point. Resume may omit both selections and uses the frozen contract regardless of later local configuration; supplied selections must match it. GitHub credentials are loaded at runtime and never journaled. Groundskeeper requires no npm login, npm identity or local publication credential for public packages; repository GitHub Actions own npm publication and Groundskeeper verifies the resulting public registry state.
The deterministic coordinator schedules all independent repositories concurrently, without a worker limit or batch barriers. Runtime consumers start only after their producers' completion is independently verified, including npm fetchability and the relevant dist-tag. dependencies, optionalDependencies and peerDependencies form the release-order graph; cycles that remain in that graph require an explicit bootstrap decision. A devDependencies back-edge is instead scheduled as a later development-sync phase, after the runtime releases it observes. The sync still updates the lockfile, runs the complete repository checks and uses the normal reviewed PR flow, but a mechanically classified development-only change in an otherwise publishable repository is merged without creating another npm release. If repairing that sync changes package source, the normal release process still applies. This prevents release ping-pong while retaining verification of repository tooling. Workers use separate owned codex/ worktrees and branches for each phase, project toolchains, exact persisted npm targets and npm test. Every created pull request waits for approval by the configured human reviewer, including mechanically classified dependency-only changes. Simple exact/caret/tilde requirements retain their style; ranges already accepting a target can retain their declaration. Complex ranges, peers, API migrations, test failures and conflicts use up to three bounded Codex repairs per task. Repairs use the CLI's default model/reasoning, low verbosity, full VM access and independent verification afterward. They cannot expand the selected dependency scope or weaken checks. Publishing workers bind the current source and previous-release baseline to the persisted assessment, invoke peacekeeper release <major|minor|patch>, and independently verify the resulting release range, npm version, dist-tag, Git tag and package fetchability.
Supported projects have a root npm package with npm lockfile v2/v3 and Peacekeeper conventions, including explicit publishesToNpm. Private nonpublishing consumers and private npm workspaces sharing the root lockfile are supported. Dependency updates cover the root and every workspace manifest, preserve declaration styles, and verify each package's resolved lockfile version, whether npm hoists the dependency or installs it inside a workspace. Installation and npm test run from the repository root using its toolchain. Manifest intents are saved together so interrupted updates resume with the same targets for every package. Workspace membership and package identities are checked against the audit on resume; changes require a fresh audit. Only the root package can be published; separately published workspace packages, independent nested lockfiles, unlinked nested packages, and aliased audited dependencies block the affected chain explicitly. A publishing project without a verified previous npm release blocks the entire execution before mutating workers start. Project-specific access/toolchain failures block that project and its consumers; independent chains continue. Shared configuration/authentication failures block the entire execution.
GitHub review and authentication
Automation uses the sandbox's authenticated GitHub CLI identity for API requests, branch pushes, pull requests, merges after approval and release orchestration. Groundskeeper reads its token only at runtime and never persists it in the execution contract or journal. The authenticated automation identity must differ from user.github, which names the human reviewer, and must have write access to every selected repository. Missing authentication or access is reported as a blocker. Release workflows retain their own configured publication credentials or trusted-publishing setup.
GitHub network failures, HTTP 5xx responses, and rate limits receive up to four attempts with exponential backoff. PR creation, review requests, and merges reconcile remote state before replaying a write after an ambiguous failure. Retry-After and rate-limit reset headers are honored; delays longer than one minute stop with a retry time instead of sending requests early. Authentication, permission, and validation failures stop with the HTTP status, endpoint, and GitHub error details. Failed API calls save a diagnostic under logs/github-*.json containing the method, endpoint, status, error message, and request ID, without tokens, request bodies, or successful authentication responses.
The complete manifest/lockfile diff is classified conservatively so development-only package changes and repairs retain their release semantics. Every pull request requires approval from the configured human reviewer as well as enforced green required checks before merge. Approval, tests, classification and merge are bound to the current PR head; a changed head invalidates previous acceptance. GitHub branch protections remain in force. Request changes triggers a bounded repair; ordinary comments do not. Fresh review is needed after repairs. Every new review request prints its project and PR link; resume prints outstanding review links again. Polling an unchanged tested PR head does not reinstall dependencies, rerun checks, or push the same branch. Waiting for review does not consume an active worker or repair attempt.
Release contract
All version-controlled changes since the verified prior release count when detecting release need, including docs and tests. Peacekeeper assess-release supplies recommendation, source SHA, previous-release SHA, model metadata and motivation. noop cannot override deterministic evidence of changes; undetermined also blocks publication.
Current upstream limitation: Peacekeeper 0.18.0 provides assess-release but its release command cannot yet enforce both assessed SHAs through release preparation and partial-release recovery. The production worker therefore blocks at guarded publication rather than releasing unassessed code. The internal guarded-release adapter is exercised with controlled integrations; it must be connected to Peacekeeper's actual guarded contract once available. Do not replace it with a pre-command SHA check or reproduce release steps manually. The GitHub CLI/API update flow also requires final production validation against the actual repository protections.
Recovery, cleanup and exit codes
state.json stores phases, intents, pinned targets, repair attempts, processed review IDs, test evidence, assessments and outcomes. On resume, workers reconcile remote branches, PRs, merges and publication before repeating side effects. Blocked conditions are rechecked; restarting never resets repair budgets. Ctrl+C stops scheduling and terminates owned process groups, preserving resumable state. Commands have five-minute timeouts; tests/repair/assessment allow twenty minutes. Registry verification retries three times with one- and two-second backoff; review/check polling is every fifteen seconds without a review timeout. Temporary repair-service capacity or connection failures retry three times within the same semantic repair attempt. If the service remains unavailable, resume can retry without consuming the semantic repair budget or triggering the no-progress guard.
Repository reservations live outside individual execution directories and use canonical GitHub host/owner/repo identity, so separate clones compete. Reservations persist through review and interruption and report the owning directory. Process locks use flock, boot identity and process start time to distinguish actual activity from stale saved status and reused PIDs. Orphan process records live outside execution directories so lost temp data does not permit duplicate active work. Stale reservations can be reclaimed once their execution has disappeared and its owned activity is gone; surviving worktrees with uncertain ownership are preserved.
list uses local metadata only, shows malformed entries as errors, and reports path, timestamps, status, progress and actual process activity. It has no JSON mode. remove excludes concurrent resume, refuses active or unowned resources, discards dirty owned worktrees without confirmation/--force, and retains cleanup evidence until cleanup succeeds. Retry the same removal after a partial failure. Remote branches, PRs, tags and publications remain; known references are printed. There is no automatic age-based deletion.
Execution directories are temporary working storage: OS temp cleanup can remove resumability. Keep needed evidence elsewhere if long-term retention is required.
Dependency audit exits 0 when current, 1 when updates exist, 2 on incomplete/error results. Update exits 0 when every selected task completes, 2 when blocked/invalid, 130 on interruption. Interactive updates maintain a live progress display showing completed projects, active projects and their work stages, review waits, GitHub/CI waits, queued projects, and blockers. The display uses green for completed work, cyan for activity, yellow for review/GitHub waits and interruptions, dim text for queued work, and red for blockers; NO_COLOR disables colors. An Elapsed: HH:MM:SS clock refreshes every second, including while waiting for review, and starts over for each invocation or resume. Counts are per repository, including repositories with multiple runtime/development phases. Every persistent update output line starts with an ISO 8601 UTC timestamp, such as [2026-10-30T14:05:06.000Z] Review required: .... Redirected output and TERM=dumb contain plain timestamped progress messages without terminal escapes or clock refreshes. Unchanged polling does not repeat review notices or progress snapshots. Each new blocker gets one concise notice; when execution stops, a complete summary lists reasons, affected repository chains, known PRs, and a single resume command.
Audit local repository state
groundskeeper repos audit
groundskeeper repos audit --json --output repos-audit.jsonUses the shared reposDirectory configuration. Discovers repositories
recursively using the same rules as dependency discovery: skip hidden directories,
node_modules, and symlinks, and stop at repository boundaries.
Reports three independent checks: a clean index and working tree (including untracked files and submodule changes, excluding gitignored files), whether the checkout is on origin's default branch, and whether HEAD exactly matches the latest fetched default-branch commit. Ahead, behind, and diverged commits fail the last check. Detached HEAD fails the branch check even if its commit matches.
Queries origin's remote HEAD and explicitly fetches that branch, including for
single-branch clones. Fetch updates remote-tracking refs and fetch metadata.
Working files, the index, local branches, and checked-out commits remain unchanged.
No checkout, pull, reset, commit, or push takes place. Missing origins, unborn
repositories, and fetch failures are errors; other repositories are still checked.
Text output contains only a table: green yes means the check passed; red no
means it failed or could not be determined. Colors are disabled for redirected
output, TERM=dumb, or when NO_COLOR is set. Use --json for error details and
to distinguish failed checks from unknown results. No progress text is printed.
Unknown checks never count as passing. --output FILE saves the JSON report.
Exit codes: 0 all checks pass (including an empty result), 1 at least one
check fails, 2 inspection or discovery errors.
Audit GitHub repository policy
groundskeeper repos audit-githubRequires an authenticated GitHub CLI. The command audits every repository the
authenticated identity can access as an owner, collaborator, or organization
member, including private repositories allowed by its token. The inventory can
span multiple users and organizations, and its scope changes when that identity's
access changes. The authenticated login is printed in the inventory heading.
Repositories in ignoredGithubRepositories are excluded.
The command first lists every selected repository in deterministic groups:
repositories without Peacekeeper, repositories using an older version than
Groundskeeper, repositories using Groundskeeper's exact pinned version,
unsupported declarations, and inspection errors. An exact version equal to
Groundskeeper's installed @jakobm/peacekeeper version is eligible directly.
For a repository without Peacekeeper or with an older exact version,
Groundskeeper searches same-repository open pull requests into the default
branch and selects the most recently updated head whose root manifest uses the
expected exact version. Ranges, newer versions and conflicting declarations are
unsupported. Archived repositories and repositories without a default branch
are inspection errors.
Manifest inspection is bound to the exact observed commit. For repositories at
the expected version this is the default-branch commit; for repositories that
need Peacekeeper introduced or upgraded it is the selected pull request's head
commit. Groundskeeper confirms that the default branch and any selected branch
have not moved, checks
that the authenticated identity can read the relevant GitHub policy APIs,
creates a temporary checkout at the verification commit and invokes its pinned
Peacekeeper binary with verify-release-protection. Groundskeeper does not
interpret or duplicate Peacekeeper's policy. Temporary checkouts are removed
after the audit.
Correct, incorrect and unverifiable repositories are then listed separately. If
any repository is verifiably incorrect, Groundskeeper invokes
peacekeeper generate-github-setup once with exactly those repositories. When
an introduction or upgrade branch was selected, GitHub configuration reads made
by that command are pinned to the same branch-head SHA instead of the default
branch. The output is written to an owner-executable setup-github-config.sh in
a unique directory under the operating system's temporary directory. The
absolute path is the final output line. Review and run or copy that script
manually if desired; Groundskeeper never executes it. No script is created when
no known policy drift exists. Like other system-temporary artifacts, the script
is not permanent and may be removed by operating-system cleanup.
Exit codes: 0 every eligible repository is correctly configured, 1 the complete audit found known policy drift and created a setup script, 2 the audit was incomplete or script generation failed. Repositories without Peacekeeper or with an older version need a suitable open pull request; otherwise the audit is incomplete. A selected introduction or upgrade branch is checked and included in the setup script when its policy has drifted.
Audit local test scripts
groundskeeper tests audit
groundskeeper tests audit --json --output tests-audit.jsonRecursively discover local Git repositories using the same directory rules as
dependency discovery (skip hidden directories, node_modules, and symlinks;
stop at repository boundaries). Inspect only each repository's root
package.json in the current working tree, including uncommitted changes.
Repositories without that file are listed under Ignored (JSON status
ignored) and do not affect the exit code. No fetching, installation, or test
execution takes place.
The report lists correct and incorrect repositories separately. scripts.test
must be exactly "peacekeeper run-tests"; missing scripts, extra arguments, and
leading or trailing whitespace are incorrect. Invalid or unreadable manifests
are listed as errors, and inspection continues with other repositories.
--json prints the report as JSON; --output FILE saves the same JSON report.
Exit codes: 0 all inspected repositories correct (including an empty result),
1 incorrect configuration, 2 read, parse, or discovery errors.
Rotate a GitHub Actions secret across repositories
Requires an authenticated GitHub CLI (gh) with permission to list repositories,
read their Actions secret names, and write secrets in every target repository.
The command works with any single-line token or secret value:
node dist/bin/groundskeeper.js secrets sync --name RELEASE_POLICY_TOKEN --new-repo groundskeeper --dry-run
node dist/bin/groundskeeper.js secrets sync --name RELEASE_POLICY_TOKEN --new-repo groundskeeperSupply the secret name and optionally repeat --new-repo for each new
repository, as repo or owner/repo (for example,
--new-repo groundskeeper --new-repo another-repo). user.github in configuration scopes discovery and all targets to one
user or organization. Missing configuration is an error. For a personal owner, authenticate as that user so private
repositories are included. Discovery paginates the owner's repository inventory
and secret lists, then combines repositories already containing that secret name
(case-insensitively) with your additions. Each target is updated once. Omitting
new repositories rotates only existing occurrences. Organization and environment
secrets are outside this command's scope.
The command prints the targets and asks for the new value once, with terminal
echo disabled. It passes the value to gh secret set over stdin, never as a
command argument or temporary file. For automation, pipe a single line on stdin;
avoid putting literal secrets in shell commands or history. --dry-run previews
targets without reading a value or writing secrets. --json emits a report
containing target, updated, failed, and inaccessible repository names; progress
is written to stderr. Secret values and subprocess error output are not logged.
Unreadable repositories are always reported and skipped. Explicit new targets still require successful writes, even when their existing secrets could not be listed. Exit code 2 means a write failure or another error; runs that only skip unreadable repositories exit 0. Writes are not atomic: if a repository update fails, earlier updates remain and the command continues with the remaining targets. Retry with the same value after fixing permissions.
This command updates stored values. Regenerate the token and configure its repository access separately on GitHub. It cannot tell whether existing secrets with the same name hold the same value, nor recover an old value.
What is inspected
- Recursively discover Git repositories under the configured directory, stopping at repository boundaries. Hidden directories and
node_modulesare skipped. Symlink directories are not followed; submodules are not separate projects. - Fetch origin and discover its default branch using the remote HEAD. Explicitly fetch that branch, including for single-branch clones. Inspect its captured commit in a detached temporary worktree. Local branches, index, and working files remain unchanged; remote-tracking refs are refreshed.
- Inspect tracked
package.jsonfiles at any depth, excludingnode_modules,vendor,dist, andbuild. Find the nearest ancestor npm lockfile for each manifest and deduplicate installation roots, including shared workspace roots. Projects without npm lockfiles are reported as unchecked. Non-npm projects are not installed with another package manager. - Fresh worktrees have no installed packages, so run
npm ci --include=dev --include=optional --include=peerper installation root. Install scripts run normally. This executes project code and can have effects outside the temporary worktree; use trusted repositories. Network, credentials, and platform-specific optional dependencies affect what can be inspected. - Before fetching or installing repositories, run
npm access list packages USER --jsononce. Package names withread-writeaccess define packages this user can publish, not which dependencies may be audited.read-onlyentries do not establish publication ownership. The public lookup works without npm authentication and describes current permissions, not historical authorship. A failed or malformed list stops repository analysis; the CLI saves the error in its conclusions file and exits 2. An empty directory needs no registry lookup. - Each repository supplies its manifests, installed versions, and direct and transitive dependency declarations. Every direct dependency is retained as an audited update target; account-listed writable packages are additionally retained so local producers and publication chains remain known. No
authormetadata is collected or reconciled; missing or different authors never affect selection. Missing required direct dependencies are errors; absent optional packages cannot be classified from installed metadata. - Fetch
npm view PACKAGE@latest --jsononce per direct dependency and account-listed producer, including producers without consumers. This public lookup needs no npm authentication. One release record supplies the latest version and published requirements for all repositories. Both installed versions and declared semver requirements are compared. A range whose minimum is older than latest is flagged for updating even if it already permits latest. Non-semver declarations (aliases, Git URLs, local files, workspace protocols) retain their raw values; their requirement comparison is unknown, while installed versions can still be compared. - Associate package names with non-private manifests in local repositories, report consumer-to-producer edges, runtime cycles, ambiguous producers, and a producer-first runtime order. Development-only edges remain in the JSON graph with their manifest field but do not create release cycles. Transitive occurrences include their declaring installed parent so later updates can target the producer rather than introduce overrides. Missing local producers have an empty
producerslist.
The report describes fetched origin commits, not uncommitted or unpushed local work. npm versions are sampled during the run, not an atomic registry snapshot. Failures remain unknown, never silently current. Independent repositories continue after failures. No local repositories means an empty report.
In an interactive terminal, dependency reports show current packages in green, packages with outdated versions or requirements in red, and unknown results in yellow. Repository status labels use the same colors. Set NO_COLOR to disable colors. Redirected output, TERM=dumb, and JSON output have no color codes.
A package whose installed version and requirements are current is shown in yellow if its producer or upstream producer repositories need updates or publication. A white (needs updates: repo, ...) note lists upstream repositories relative to the audit directory, excluding the consuming repository and the package's own producers. If only the package's own producer needs work, the row is yellow without a note. This does not change the installed-version comparison. Directly outdated packages remain red.
The text report lists every repository in a central latest-published-version overview, including publishable packages that no other repository currently uses. Private packages and repositories without publishable npm packages are identified separately. All repositories also appear in the results, including current ones. Detailed dependency declarations and published/source requirement comparisons are omitted from text results and retained in JSON. Publication-needed details are also retained only in JSON. The dependency update plan includes outdated repositories and current consumers affected by future releases, with producers before consumers. JSON retains the complete inventory and dependency graph.
Only local producers present in the writable account list receive publication lookups. Others are labeled not listed for npm account ...; this does not claim the package name is unavailable on npm. A registry E404 for a queried package is labeled not found in npm registry; authentication, network, and malformed-response failures remain unknown with an error explanation. A package not found on a registry is not proof that it has never been published or that a private package does not exist.
Repository labels in the text overview, results, update graph, and cycles are relative to the audit directory printed in the header (. for that directory itself). JSON paths remain absolute.
The legacy JSON update blocker list includes only outdated repositories; use the new plan for execution planning. Each repository lists the runtime producers blocking it, or ready when it has no blockers. An updater can start all ready repositories in parallel, then start each consumer as soon as all of its own blockers have been published and are available. It does not need to wait for unrelated work to finish. Paths through current repositories retain their ordering constraints without listing those repositories as update work. Runtime cycles or ambiguous producers suppress the blocker plan and remain explicit errors; development-only back-edges are handled by the plan's later sync phases. These legacy constraints do not include future-release work; the new plan below supersedes them. No updates are executed.
For each account-listed, named, non-private package with a valid version in the fetched source, the audit compares its latest published npm metadata with the source manifest. If that release has an old requirement on an audited dependency that is already current (or removed) in source, the repository is marked outdated, with publication details in JSON. This identifies dependency fixes waiting for a release, even when the source package version still equals the published version. It does not compare all source code with the published tarball or detect every possible unpublished change. Registry lookup failures remain unknown.
Development
volta run node --version
volta run npm --version
volta run npm run typecheck
volta run npm testcmdabra.yaml is the source of truth for the CLI hierarchy, help text, and option types. Run volta run npm run generate:cli-types after changing it; build and typecheck verify that the committed src/cmdabra.generated.ts is current. The cli module assembles handlers directly from the dependencies, projects, repositories, and secrets facades, and checks the complete object with the generated Cmdabra implementation type. Portico discovers contracts and policies under src/modules/interfaces/ and the full runtime hierarchy under src/modules/implementations/. Leaf contracts are files named after their modules; only interface modules with children retain directories, with their child contracts under a reserved modules/ directory. Each facade explicitly selects what it exposes. The six public Portico modules are cli, configuration, dependencies, projects, repositories, and secrets; child modules and local implementations stay private behind their explicit facades. src/container.ts creates the asynchronous ESM container, the CLI module runs Cmdabra with the assembled typed implementation, and the executable files handle startup. See the module architecture for boundaries and lifecycle. Run volta run npm run architecture to regenerate the committed SVG dependency graph and YAML views in architecture/.
npm ci and npm link compile TypeScript automatically through prepare. After editing source files, run volta run npm run build before using the linked command. Generated JavaScript and the copied Portico policy live in the ignored dist/ directory. npm run typecheck checks source and tests without emitting files; npm test performs a clean build and runs the compiled tests. Production code uses strict TypeScript settings; test fixtures use a separate relaxed configuration.
Peacekeeper is pinned to 0.25.2. npm test checks project conventions and runs the Node test suite. Test receipts can be reused for sixty minutes; use volta run npm test -- --force to force a new run. Tests use disposable repositories and controlled GitHub/npm/Codex dependencies, including crashes immediately after PR creation, merge and publication. No personal configuration or live registry data is required.
After npm ci or a build, run volta run npm run test:package to build and pack the actual npm tarball, install it globally under a temporary prefix, and verify help, the embedded Git SHA and shell completion from a separate directory. This smoke test downloads runtime dependencies from npm using a temporary cache and empty npm configuration files; it does not use personal npm or Groundskeeper configuration. It also rejects source, test and development-script directories in the tarball. The required test CI job runs this check after npm test.
peacekeeper.config.yaml sets origin/main, codex/ branches, required checks and checkpoint pushes to origin. The committed Codex hooks and environment install dependencies using Volta. npm run cleanup:branches and npm run cleanup:empty-directories preview repository cleanup; add -- --execute after reviewing the preview.
npm releases
peacekeeper.config.yaml declares publishesToNpm: true. The package includes compiled CLI and runtime modules, Portico dependency policies, cmdabra.yaml and the embedded build SHA. npm also includes the package metadata, README and license. Consumers install the compiled package without a TypeScript build or access to the source Git repository.
Before the first release, confirm publish access to the @jakobm scope. Peacekeeper's setup instructions use an initial manual publication with npm login and npm publish to create the npm package. Run the full tests and npm run test:package before that publication. Then configure an npm GitHub Actions trusted publisher for package @jakobm/groundskeeper, owner jakobmattsson, repository groundskeeper, and workflow filename publish.yml. Enable direct publishing. If an npm environment name is configured, add the same environment to the workflow's publish job.
GitHub needs the RELEASE_POLICY_TOKEN secret and the branch protections required by peacekeeper verify-release-protection, including the strict required test check and owner approval. The test check includes the package smoke test, so no additional required check name is needed.
For subsequent releases, run from a clean repository root:
volta run npm run release -- patchUse minor or major for the corresponding version increment. The prerelease script installs the locked dependencies with npm ci; Peacekeeper then manages the release PR, version and lockfile updates, tag, publication monitoring and retries. .github/workflows/publish.yml runs on v* tags, verifies the release, and publishes through npm OIDC without an npm publishing token. Retry the same release command after resolving an interrupted release instead of manually recreating its steps.
