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 in-process via format_file. When patterns is provided, formats those specific files/globs. Otherwise formats dir (recursively, respecting filter) plus the root files when dir is paths.source.

Files the formatter rejects (e.g. a syntax error) are reported and fail the run in both modes rather than being silently skipped.

This is separated from ./format_file so modules that only need directory traversal don't pull in the formatter (which loads the tsv WASM module).

Formats a string of source code in-process. Passes the input through unchanged when the language is unsupported (an expected no-op), but throws when the formatter rejects the source — e.g. a syntax error — so callers can decide whether to log, skip, or fail rather than silently treating broken input as already-formatted.

The source languages Gro can format in-process, backed by @fuzdev/tsv_wasm (typescript/svelte/css) plus a builtin json formatter. Anything else passes through unchanged.

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 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.