api #

Metadata stored in .gro/ directory to track build cache validity. Schema validates structure at load time to catch corrupted cache files.

Metadata about a single build output file. Includes cryptographic hash for validation plus filesystem stats for debugging and optimization.

Collects information about all files in build output directories. Returns an array of entries with path, hash, size, mtime, ctime, and mode.

Files are hashed in parallel for performance. For very large builds (10k+ files), this may take several seconds but ensures complete cache validation.

Computes the cache key components for a build. This determines whether a cached build can be reused.

Configures process output handling with path replacements while preserving ANSI colors.

Transforms a RawGroConfig to the more strict GroConfig. This allows users to provide a more relaxed config. Hashes the build_cache_config and deletes the raw value for security.

Creates build cache metadata after a successful build. Automatically discovers all build output directories (build/, dist/, dist_*).

The parsed SvelteKit config for the cwd, cached globally at the module level.

Discovers all build output directories in the current working directory. Returns an array of directory names that exist: build/, dist/, dist_*

BLAKE3 hash of empty string, used for configs without build_cache_config. This ensures consistent cache behavior when no custom config is provided.

Adds support for imports to both .ts and .js, as well as imports without extensions that resolve to .js or .ts. Prefers .ts over any .js, and falls back to .ts if no file is found.

Searches the filesystem for the CLI name, first local to the cwd and then globally.

Finds modules from input paths. (see input_path.ts for more)

Finds modules from input paths. (see input_path.ts for more)

Formats files on the filesystem. When patterns is provided, formats those specific files/patterns. Otherwise formats dir with default extensions, plus root files if dir is paths.source. This is separated from ./format_file to avoid importing all of the prettier code inside modules that import this one. (which has a nontrivial cost)

Formats a file with Prettier.

Gets a list of possible source ids for each input path with extensions, duplicating each under root_dirs, without checking the filesystem.

Length of git commit hash when displayed in logs (standard git convention).

Paths for the Gro package being used by the user repo.

Creates a gro plugin that compiles TypeScript to a binary using deno compile. Runs during the adapt phase (production build only).

Creates a gro plugin that runs a Deno server during development. The server is started during setup and stopped on teardown.

In dev mode, Vite should proxy API requests to this server.

The config that users can extend via gro.config.ts. This is exposed to users in places like tasks and genfiles.

Installs dependencies, self-healing the stale-cache (ETARGET) failure mode.

Strategy: 1. First attempt: ${pm_cli} install [...install_args]. 2. On an npm ETARGET-class failure (stale cache): npm cache clean --force then retry the same install once. 3. On any other failure — or any failure under a non-npm pm_cli — return immediately without healing.

Why ETARGET happens: right after a dependency is published and the registry has propagated, npm's local cache may still hold stale "404"/no-version metadata for it; clearing the cache forces a fresh metadata fetch. This makes installs safe to run immediately after publishing an upstream package — e.g. picking up a just-released dep in a dependency-ordered publish chain, or gro upgrade-ing to a fresh @latest.

npm only: the heal uses npm-specific syntax (cache clean --force), so it's gated on pm_cli === 'npm'. A non-npm pm_cli surfaces the failure unchanged rather than running a command it can't understand.

The env is always passed through sanitize_install_env so the build's devDependencies survive.

install_with_cache_healing that throws a TaskError on failure instead of returning the result — the shape every task callsite wants. The thrown message names the exact command (including install_args), an optional context clause, and the failure detail.

Options for install_with_cache_healing.

Invokes Gro tasks by name using the filesystem as the source.

When a task is invoked, Gro first searches for tasks in the current working directory. and falls back to searching Gro's directory, if the two are different. See input_path.ts for info about what "task_name" can refer to. If it matches a directory, all of the tasks within it are logged, both in the current working directory and Gro.

This code is particularly hairy because we're accepting a wide range of user input and trying to do the right thing. Precise error messages are especially difficult and there are some subtle differences in the complex logical branches. The comments describe each condition.

Main function to check if the build cache is valid. Returns true if the cached build can be used, false if a fresh build is needed.

Checks if an npm install failure is caused by stale cache (ETARGET).

Detects the several shapes npm uses for "the requested version isn't there": code ETARGET, ETARGET, notarget, and No matching version found.

Cache filename inside a repo's .gro directory for library_load_from_repo.

Computes the cache key for a repo at repo_dir: the git HEAD commit hash.

Returns null (uncacheable — analysis still runs, caching is skipped) when the dir is not a git repo OR when the working tree is dirty. A dirty tree is deliberately uncacheable: the commit hash doesn't capture uncommitted edits, so a single -dirty key would serve a stale analysis across successive edits. Skipping the cache while dirty guarantees fresh metadata; clean commits cache.

Reads and validates the .gro/library.json cache at cache_path.

Returns the cached {library_json, package_json} only when the file exists and its stored hash matches key. Returns null on every miss - absent, stale (different hash), or unreadable/corrupt - signalling the caller to re-analyze.

Format version for the .gro/library.json cache. The cache key is the git commit hash, which does NOT change when the cached *shape* changes — so bump this whenever LibraryCache's shape changes (e.g. the LibraryJson / PkgJson split, then slimming LibraryJson to the raw pkg_json/source_json pair) to self-invalidate stale caches across the ecosystem rather than serve old-shaped data at an unchanged commit.

Writes result to the .gro/library.json cache at cache_path, keyed by key and stamped with the current LIBRARY_CACHE_VERSION, creating the parent directory as needed.

Best effort: caching is optional, so write failures are logged as a warning and swallowed rather than thrown.

Loads a repo's library metadata via svelte-docinfo, with a .gro cache keyed by git hash.

Analyzes repo_dir with analyzeFromFiles and combines the result with the repo's package.json into a LibraryJson, returned alongside the full package.json. Results are cached at <repo_dir>/.gro/library.json keyed by the current git HEAD, so repeated loads at the same commit skip the (potentially slow) analysis. A dirty working tree (or a non-git dir) is uncacheable, so analysis re-runs on every load until the changes are committed - see library_cache_key.

On-disk shape of the .gro/library.json cache file. The hash is the git-based cache key the result was computed at; version is the LIBRARY_CACHE_VERSION it was written under.

Result of loading a repo's library metadata: the curated LibraryJson (carrying the publish-safe pkg_json) plus the repo's full package.json.

The full package_json is kept alongside — not folded into LibraryJson — because tooling like fuz_gitops needs dependencies/devDependencies, which the curated LibraryJson.pkg_json deliberately omits.

Loads build cache metadata from .gro/ directory. Invalid or corrupted cache files are automatically deleted.

Loads a single env value without merging it into process.env. By default searches process.env, then a local .env if one exists, then ../.env if it exists. Empty strings are semantically the same as undefined for more ergonomic fallbacks.