api #

Builds the dependency graph and runs cycle/wildcard analysis, tolerating cycles (reports rather than throws). The shared core of gitops_analyze and gitops_validate, which format the result themselves.

Build operations for validating packages compile before publishing.

A semver bump kind: major, minor, or patch.

Calculates all dependency updates between packages based on predicted versions.

Iterates through all repos, checking prod, peer, and dev dependencies to find which packages will need dependency version bumps after publishing.

Also tracks "breaking cascades" - when a breaking change propagates to dependents.

Collects events in memory. Used to build the run report and in tests.

A capture_handler also exposes the events it has collected.

Best-effort read of a repo's root Cargo.toml for the identity fields the dashboard renders. Returns null when there's no Cargo.toml.

Extracts name/version/description/repository from the [package] and [workspace.package] tables of a Cargo.toml.

Deliberately not a full TOML parser: it scans for simple key = "value" string entries in those two tables, which covers both a single-crate manifest and a workspace root. Inline-table values like version = { workspace = true } (and the equivalent version.workspace = true) are ignored — a member crate inheriting from the workspace has no literal here, and fuz_repos only ever reads a repo's root manifest, where these are concrete. The first non-empty value for a key wins, so a top-level [package] takes precedence over [workspace.package] when both appear.

The handful of identity fields fuz_repos reads from a Rust repo's Cargo.toml to render it on the dashboard. Everything is optional — a workspace root has no name, and any field may be absent or inherited.

Changeset operations for reading and predicting versions from .changeset/*.md files.

Checks a repos status --json report on the repos gitops_sync generates the site data from (repo_readiness_for_gen).

Checks whether pkg@version is on the npm registry, by npm view.

Checks a repos status --fetch --json report on the repos a real publish reads and writes: every key's entry ready (repo_readiness_for_publish), the report fetched, and busy detection available, since a live session it can't vouch for may be working in any checkout.

How a repo's declared ci diverges from its workflow files on disk.

Compares bump types. Returns positive if a > b, negative if a < b, 0 if equal.

Creates a changeset file for dependency updates. Returns the path to the created changeset file.

Creates file-system backed cache for fuz_util's fetch.js API responses.

Cache invalidation strategy: If cache file can't be read or parsed, entire cache is cleared (delete file) and starts fresh. This handles format changes.

Uses structuredClone to track changes - only writes to disk if data modified. Formatted with gro's format_file before writing for version control friendliness.

A config module's default export in function form.

Decides whether a publish run must block, prompt for confirmation, or proceed without prompting, from the pre-execution inputs.

• blocked: a real publish whose plan has errors — fail loud before prompting. The executor enforces this too, so --no-plan can't bypass the gate; this branch only avoids prompting for (and printing the "this will publish" banner of) a plan that can't run.
• confirm: a real publish that shows its plan — the user must confirm interactively.
• proceed: a dry run, or a --no-plan real publish — no prompt.

Combined default operations for all gitops functionality.

Cycles and wildcard dependencies found by DependencyGraph.analyze.

Derives the ordered side-effects a wetrun would perform from a frozen plan.

Reads only publishing_order, version_changes, and dependency_updates — the same data execute_publishing_plan consumes, in the same order — so the preview reflects the real pass. A dependency is only propagated to its dependents if it actually publishes this run.

Determines the bump type for a package from its changesets.

When multiple changesets exist for the same package, returns the highest bump type (major > minor > patch) to ensure the most significant change is reflected in the version bump.

Executes a frozen publishing plan in a single linear pass — the "dumb executor" half of the zap model. The plan is the single source of truth; this re-derives nothing.

Fails loud when the plan couldn't be fully computed (plan.errors): a wetrun aborts before any side effect, a dry run still reports the partial cascade but returns ok: false. This is the single error gate — --no-plan can't bypass it.

Fetches the check runs on ref and reduces them to one overall status and conclusion.

Fetches GitHub metadata (CI status, PRs) for all repos.

Fetches sequentially with a delay before each request to respect GitHub API rate limits. Uses await_in_loop intentionally to avoid parallel requests overwhelming the API. CI status is read for the branch each repo's registry entry follows (main when it names none), and that branch is written to RepoJson.branch.

A repo whose registry entry declares no CI (ci: false) isn't asked for check runs, and one with none on its branch isn't a failure: both leave check_runs null without logging. A failed fetch is logged as an error and leaves null for that repo's check_runs or pull_requests, and the remaining repos still fetch — except a 401 response or a repo URL without a GitHub owner, which throw.

Options for fetch_repo_data.

Formats data and outputs to file or stdout based on options.

Supports three formats:

• stdout: Uses logger for colored/styled output (cannot use with --outfile)
• json: Stringified JSON
• markdown: Formatted markdown text

Formats dev circular dependencies as styled strings. Returns array of lines for inclusion in output.

Formats production/peer circular dependencies as styled strings. Returns array of lines for inclusion in output.

Formats steps as human-readable lines (one per step) for stdout and markdown output. Returns a single placeholder line when there are no side effects.

Says what happens to a ready repo's commits ahead of origin: its release push carries them when it publishes, else they stay unpushed.

Formats the diagnostics' readiness block: a header and a line per problem, saying what each repo not at rest is doing instead — or no lines when every repo is at rest. Not a failure: the diagnostics read repos as they sit.

What a readiness problem says is wrong with the repo keyed key, and the fix, when there is one to name.

Formats wildcard dependencies as styled strings. Returns array of lines for inclusion in output.

File system operations for reading and writing files.

Errors are typed via FsError (`not_found | permission_denied | already_exists | io_error) so callers can branch on kind` instead of regex-matching message. See @fuzdev/fuz_util/fs.ts.

The readiness gate gitops_publish --wetrun runs before its confirmation prompt: fetches every npm repo from origin (`repos status <keys…> --fetch --json`, which writes remote-tracking refs and nothing else) and refuses unless each is ready (check_publish_readiness) — on its registry branch, clean, idle, in sync with origin or ahead of it, fetched without error, no other live session in its checkout, and nothing left to a person. Each ready repo ahead of origin is logged, saying whether its release push carries those commits or they stay unpushed.

Every npm repo, not just those the plan publishes or rewrites: the plan reads each one's working tree (changesets, versions, dependency ranges), so a repo off its branch or behind origin can hide a changeset and leave the plan wrong about what to publish. Changes nothing.

Generates markdown changeset content for dependency updates.

Creates properly formatted changeset with YAML frontmatter, summary, and categorized list of breaking vs regular updates. Output format matches changesets CLI for consistency.

Generates a publishing plan showing what would happen during publishing. Shows version changes, dependency updates, and breaking change cascades. Uses fixed-point iteration to resolve transitive cascades.

Central initialization function for the gitops tasks that load libraries: resolves the config's repos through repos status (resolve_gitops_repos), then loads each repo's library as its working tree sits (local_repos_load). Moves no ref; gro caches each library at .gro/library.json in its repo, at a clean commit.

Determines the required bump type for a package based on its dependency updates.

Returns null if no prod/peer dependency updates, otherwise returns the minimum required bump type (major for breaking deps, patch otherwise).

Respects pre-1.0 semver conventions (minor for breaking in 0.x).

Determines version prefix to use when updating dependencies.

Strategy:

• Wildcard (*): Use caret (^) as default
• Has existing prefix: Preserve it (^, ~, >=, <=, etc)
• No prefix: Use default_strategy

This preserves user intent while handling wildcard replacements sensibly.

Gets the version prefix (^, ~, >=, <=, or empty string).

Adds files to git staging area and throws if anything goes wrong.

Commits files alone with a message, leaving anything else staged out of the commit, and throws if anything goes wrong. files must be non-empty: an empty list would commit the whole index.

Wrapper for gro's git_current_commit_hash that reads HEAD and throws if null.

Minimal interface for GitHub API calls, satisfied structurally by fuz_ui's Library.

Git operations the publishing executor authors with: staging and committing dependency updates and auto-changesets, and reading the commit it published. All operations return Result instead of throwing errors. Where each repo sits (branch, dirt, relation to origin) is ReposOperations's to report.

Default number of repos to process concurrently during parallel operations.

The private repos a public host package must not publish. gitops_sync writes every configured repo's GitHub metadata into the host project's generated repos.json — a public site's data when the host package is public — so a private repo in that config would leak. Empty when the host is private.

Default path to the gitops configuration file.

Maximum number of fixed-point iterations plan generation runs to resolve transitive dependency cascades. Publishing executes the frozen plan in a single pass and doesn't iterate.

Each iteration reaches at least one more level of dependents, so a deep dependency chain needs more; a plan that hits the limit still changing warns, naming the packages left.

Default timeout in milliseconds for waiting on NPM package propagation (10 minutes). NPM's CDN uses eventual consistency, so published packages may not be immediately available.

A project's gitops config.

Combined operations interface grouping all gitops functionality. This is the main interface injected into publishing and validation workflows.

Groups dependency updates by dependent package — `dependent → (dependency → new version), the shape update_package_json consumes. Restricted by predicate` (e.g. prod/peer for a given package, or all dev deps) and to dependencies that actually published this run, so a failed/aborted publish never propagates to its dependents.

Checks if a repo has any changeset files (excluding README.md).

Used by preflight checks and publishing workflow to determine which packages need to be published. Returns false if .changeset directory doesn't exist or contains only README.md.

Determines if a bump is a breaking change based on semver rules. Pre-1.0: minor bumps are breaking 1.0+: major bumps are breaking

Loads a gitops config module and validates it.

Runs repos status <keys…> --json and parses its report.

Loads a resolved repo as its working tree sits (the tasks read where each repo sits from repos status, and repos sync moves them). Moves no ref; gro caches the library at .gro/library.json in the repo, at a clean commit.

1. Loads library_json via library_load_from_repo (svelte-docinfo analysis)
2. Creates Library and extracts dependency maps

A repo with no package.json but a Rust Cargo.toml loads as a dashboard-only cargo repo instead.

Resolves a gitops config's registry keys against a repos status report, in config order. Every key must name an owned repo that's present and was probed; each that doesn't is a problem, and any problem fails the whole resolve, naming them all.

Fully loaded local repo with Library and extracted dependency data. Does not extend LocalRepoPath - Library is source of truth for name/repo_url/etc.

A configured repo resolved through repos status: present on disk, before its library is loaded. See local_repos_resolve.

Logs all dependency analysis results (wildcards, production cycles, dev cycles). Convenience function that calls all three logging functions in order.

Logs dev circular dependencies as info. Dev cycles are normal and non-blocking, so they're informational, not warnings.

Logs production/peer circular dependencies as errors. Production cycles block publishing and must be resolved.

Logs a complete publishing plan to the console.

Displays errors, publishing order, version changes grouped by scenario, dependency-only updates, warnings, and a summary.

Logs the diagnostics' readiness block as warnings (stderr, so a `--format json or markdown` document on stdout stays clean): each npm repo not at rest, and how. Logs nothing when every one is at rest. Reads the entries repos status already reported, from local refs.

Logs wildcard dependencies as warnings. Wildcard dependencies require attention and should be reviewed.

Returns a copy of the event with secrets redacted from its string-valued fields.

Wraps a handler, masking secrets in each event's string fields (mask_secrets) before forwarding.

Fans an event out to every handler in order.