api #

Build operations for validating packages compile before publishing.

Semantic Versioning 2.0.0 utilities

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.

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

Collect all files from walk_repo_files into an array. Convenience function for when you need all paths upfront.

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 Prettier before writing for version control friendliness.

Default directories to exclude from file walking

Default binary/non-text extensions to exclude from content processing

Combined default operations for all gitops functionality.

Default repos directory relative to gitops config file. Resolves to the parent of the directory with the config (e.g., /dev/repo/gitops.config.ts resolves to /dev/).

Builder for creating and analyzing dependency graphs.

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.

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

Fetches sequentially with delay between requests to respect GitHub API rate limits. Uses await_in_loop intentionally to avoid parallel requests overwhelming the API.

Error handling: Logs fetch failures but continues processing remaining repos. Repos with failed fetches will have null for check_runs or pull_requests.

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 wildcard dependencies as styled strings. Returns array of lines for inclusion in output.

File system operations for reading and writing files.

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 all gitops tasks.

Initialization sequence: 1. Loads and normalizes config from gitops.config.ts 2. Resolves local repo paths (creates missing with --download) 3. Switches branches and pulls latest changes (in parallel by default) 4. Auto-installs deps if package.json changed during pull

Priority for path resolution: - dir argument (explicit override) - Config repos_dir setting - DEFAULT_REPOS_DIR constant

Fetches package metadata from NPM registry.

Returns name and latest version. Returns null if package doesn't exist or registry is unreachable.

Get repo paths from gitops config without full git sync. Lighter weight than get_gitops_ready() - just resolves paths.

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.

Adds files and commits in one operation and throws if anything goes wrong.

Wrapper for gro's git_check_clean_workspace that returns a boolean.

Commits staged changes with a message and throws if anything goes wrong.

Wrapper for gro's git_current_branch_name that throws if null.

Wrapper for gro's git_current_commit_hash that throws if null.

Returns list of changed files compared to HEAD.

Pushes a tag to origin and throws if anything goes wrong.

Stashes current changes and throws if anything goes wrong.

Applies stashed changes and throws if anything goes wrong.

Switches to a branch with safety checks and throws if workspace is not clean.

Creates a git tag and throws if anything goes wrong.

Minimal interface for GitHub API calls - works with both Pkg and Repo.

Git operations for branch management, commits, tags, and workspace state. All operations return Result instead of throwing errors.

Default number of repos to process concurrently during parallel operations.

Default path to the gitops configuration file.

Maximum number of iterations for fixed-point iteration during publishing. Used in both plan generation and actual publishing to resolve transitive dependency cascades.

In practice, most repos converge in 2-3 iterations. Deep dependency chains may require more iterations.

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.

Base directory for all gitops-generated files.

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

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.

Installs npm dependencies with cache healing on ETARGET errors.

Strategy: 1. First attempt: regular npm install 2. On ETARGET error (stale cache): npm cache clean --force then retry 3. On other errors: fail immediately

Why ETARGET errors occur: After publishing a package and waiting for NPM registry propagation, npm's local cache may still have stale "404" metadata. This healing strategy clears the cache to force fresh metadata fetch.

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 repo data with automatic syncing and dependency management.

Workflow: 1. Records current commit hash (for detecting changes) 2. Switches to target branch if needed (requires clean workspace) 3. Pulls latest changes from remote (skipped for local-only repos) 4. Validates workspace is clean after pull 5. Auto-installs dependencies if package.json changed 6. Imports library_json from src/routes/library.ts 7. Creates Library and extracts dependency maps

This ensures repos are always in sync with their configured branch before being used by gitops commands.

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 repo that is missing from the filesystem (needs cloning).

A repo that has been located on the filesystem (path exists). Used before loading - just filesystem/git concerns.

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 a simple bulleted list with a header. Common pattern for warnings, info messages, and other lists.

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 wildcard dependencies as warnings. Wildcard dependencies require attention and should be reviewed.

Transforms a RawGitopsConfig to the more strict GitopsConfig. This allows users to provide a more relaxed config.

Normalizes version string for comparison.

Strips prefixes (^, ~, >=) to get bare version number. Handles wildcards as-is. Used by needs_update to compare versions.

NPM registry operations for package availability checks and authentication. Includes exponential backoff for waiting on package propagation.