@ryanatkn/gro 0.170.0 → 0.172.0

package/dist/gro_config.d.ts

@@ -2,6 +2,11 @@ import type { Path_Filter, Path_Id } from '@ryanatkn/belt/path.js';
 import type { Create_Config_Plugins } from './plugin.ts';
 import type { Map_Package_Json } from './package_json.ts';
 import type { Parsed_Svelte_Config } from './svelte_config.ts';
+/**
+ * SHA-256 hash of empty string, used for configs without build_cache_config.
+ * This ensures consistent cache behavior when no custom config is provided.
+ */
+export declare const EMPTY_BUILD_CACHE_CONFIG_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 /**
  * The config that users can extend via `gro.config.ts`.
  * This is exposed to users in places like tasks and genfiles.
@@ -38,6 +43,13 @@ export interface Gro_Config extends Raw_Gro_Config {
     pm_cli: string;
     /** @default SVELTE_CONFIG_FILENAME */
     svelte_config_filename?: string;
+    /**
+     * SHA-256 hash of the user's `build_cache_config` from `gro.config.ts`.
+     * This is computed during config normalization and the raw value is immediately deleted.
+     * If no `build_cache_config` was provided, this is the hash of an empty string.
+     * @see Raw_Gro_Config.build_cache_config
+     */
+    build_cache_config_hash: string;
 }
 /**
  * The relaxed variant of `Gro_Config` that users can provide via `gro.config.ts`.
@@ -51,6 +63,22 @@ export interface Raw_Gro_Config {
     search_filters?: Path_Filter | Array<Path_Filter> | null;
     js_cli?: string;
     pm_cli?: string;
+    /**
+     * Optional object defining custom build inputs for cache invalidation.
+     * This value is hashed during config normalization and used to detect
+     * when builds need to be regenerated due to non-source changes.
+     *
+     * Use cases:
+     * - Environment variables baked into build: `{api_url: process.env.PUBLIC_API_URL}`
+     * - External data files: `{data: fs.readFileSync('data.json', 'utf-8')}`
+     * - Build feature flags: `{enable_analytics: true}`
+     *
+     * Can be a static object or an async function that returns an object.
+     *
+     * IMPORTANT: It's safe to include secrets here because they are hashed and `delete`d
+     * during config normalization. The raw value is never logged or persisted.
+     */
+    build_cache_config?: Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>);
 }
 export type Create_Gro_Config = (base_config: Gro_Config, svelte_config?: Parsed_Svelte_Config) => Raw_Gro_Config | Promise<Raw_Gro_Config>;
 export declare const create_empty_gro_config: () => Gro_Config;
@@ -65,8 +93,9 @@ export declare const EXPORTS_EXCLUDER_DEFAULT: RegExp;
 /**
  * Transforms a `Raw_Gro_Config` to the more strict `Gro_Config`.
  * This allows users to provide a more relaxed config.
+ * Hashes the `build_cache_config` and deletes the raw value for security.
  */
-export declare const cook_gro_config: (raw_config: Raw_Gro_Config) => Gro_Config;
+export declare const cook_gro_config: (raw_config: Raw_Gro_Config) => Promise<Gro_Config>;
 export interface Gro_Config_Module {
     readonly default: Raw_Gro_Config | Create_Gro_Config;
 }

package/dist/gro_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gro_config.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/gro_config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,WAAW,EAAE,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAajE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IACjD;;OAEG;IACH,OAAO,EAAE,qBAAqB,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,cAAc,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC/B,WAAW,EAAE,UAAU,EACvB,aAAa,CAAC,EAAE,oBAAoB,KAChC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,eAAO,MAAM,uBAAuB,QAAO,UAYzC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAUnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAwD,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,cAAc,KAAG,UA0B5D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAAC;CACrD;AAED,eAAO,MAAM,eAAe,GAAU,YAAgB,KAAG,OAAO,CAAC,UAAU,CAmB1E,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,CACxC,aAAa,EAAE,GAAG,EAClB,WAAW,EAAE,MAAM,KACf,OAAO,CAAC,aAAa,IAAI,iBAS7B,CAAC"}
+{"version":3,"file":"gro_config.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/gro_config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,WAAW,EAAE,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAcjE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAG7D;;;GAGG;AACH,eAAO,MAAM,6BAA6B,qEACyB,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IACjD;;OAEG;IACH,OAAO,EAAE,qBAAqB,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,cAAc,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,uBAAuB,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,EAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC/B,WAAW,EAAE,UAAU,EACvB,aAAa,CAAC,EAAE,oBAAoB,KAChC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,eAAO,MAAM,uBAAuB,QAAO,UAazC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAUnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAA+C,CAAC;AAErF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAU,YAAY,cAAc,KAAG,OAAO,CAAC,UAAU,CA+CpF,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAAC;CACrD;AAED,eAAO,MAAM,eAAe,GAAU,YAAgB,KAAG,OAAO,CAAC,UAAU,CAqB1E,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,CACxC,aAAa,EAAE,GAAG,EAClB,WAAW,EAAE,MAAM,KACf,OAAO,CAAC,aAAa,IAAI,iBAS7B,CAAC"}

package/dist/gro_config.js

@@ -9,9 +9,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { join, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 import { identity } from '@ryanatkn/belt/function.js';
+import { json_stringify_deterministic } from '@ryanatkn/belt/json.js';
 import { GRO_DIST_DIR, IS_THIS_GRO, paths } from "./paths.js";
 import { GRO_CONFIG_FILENAME, JS_CLI_DEFAULT, NODE_MODULES_DIRNAME, PM_CLI_DEFAULT, SERVER_DIST_PATH, SVELTEKIT_BUILD_DIRNAME, SVELTEKIT_DIST_DIRNAME, } from "./constants.js";
 import create_default_config from "./gro.config.default.js";
+import { to_hash } from "./hash.js";
+/**
+ * SHA-256 hash of empty string, used for configs without build_cache_config.
+ * This ensures consistent cache behavior when no custom config is provided.
+ */
+export const EMPTY_BUILD_CACHE_CONFIG_HASH = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
 export const create_empty_gro_config = () => ({
     plugins: () => [],
     map_package_json: identity,
@@ -24,6 +31,7 @@ export const create_empty_gro_config = () => ({
     search_filters: [(id) => !SEARCH_EXCLUDER_DEFAULT.test(id)],
     js_cli: JS_CLI_DEFAULT,
     pm_cli: PM_CLI_DEFAULT,
+    build_cache_config_hash: EMPTY_BUILD_CACHE_CONFIG_HASH,
 });
 /**
  * The regexp used by default to exclude directories and files
@@ -38,16 +46,31 @@ export const SEARCH_EXCLUDER_DEFAULT = new RegExp(`(${'(^|/)\\.[^/]+' + // exclu
     `|(^|/)(?<!(^|/)gro/)${SVELTEKIT_DIST_DIRNAME}` + // exclude the SvelteKit dist directory unless it's in the Gro directory
     `|(^|/)${SERVER_DIST_PATH}` // exclude the Gro server plugin dist directory
 })($|/)`, 'u');
-export const EXPORTS_EXCLUDER_DEFAULT = /(\.md|\.(test|ignore)\.|\/(test|fixtures|ignore)\/)/;
+export const EXPORTS_EXCLUDER_DEFAULT = /(\.md|\.(test|ignore)\.|\/(test|ignore)\/)/;
 /**
  * Transforms a `Raw_Gro_Config` to the more strict `Gro_Config`.
  * This allows users to provide a more relaxed config.
+ * Hashes the `build_cache_config` and deletes the raw value for security.
  */
-export const cook_gro_config = (raw_config) => {
+export const cook_gro_config = async (raw_config) => {
     const empty_config = create_empty_gro_config();
     // All of the raw config properties are optional,
     // so fall back to the empty values when `undefined`.
-    const { plugins = empty_config.plugins, map_package_json = empty_config.map_package_json, task_root_dirs = empty_config.task_root_dirs, search_filters = empty_config.search_filters, js_cli = empty_config.js_cli, pm_cli = empty_config.pm_cli, } = raw_config;
+    const { plugins = empty_config.plugins, map_package_json = empty_config.map_package_json, task_root_dirs = empty_config.task_root_dirs, search_filters = empty_config.search_filters, js_cli = empty_config.js_cli, pm_cli = empty_config.pm_cli, build_cache_config, } = raw_config;
+    // Hash build_cache_config and delete the raw value
+    // IMPORTANT: Raw value may contain secrets - hash it and delete immediately
+    let build_cache_config_hash;
+    if (!build_cache_config) {
+        build_cache_config_hash = EMPTY_BUILD_CACHE_CONFIG_HASH;
+    }
+    else {
+        // Resolve if it's a function
+        const resolved = typeof build_cache_config === 'function' ? await build_cache_config() : build_cache_config;
+        // Hash the JSON representation with deterministic key ordering
+        build_cache_config_hash = await to_hash(new TextEncoder().encode(json_stringify_deterministic(resolved)));
+    }
+    // Delete the raw value to ensure it doesn't persist in memory
+    delete raw_config.build_cache_config;
     return {
         plugins,
         map_package_json,
@@ -59,10 +82,11 @@ export const cook_gro_config = (raw_config) => {
                 : [],
         js_cli,
         pm_cli,
+        build_cache_config_hash,
     };
 };
 export const load_gro_config = async (dir = paths.root) => {
-    const default_config = cook_gro_config(await create_default_config(create_empty_gro_config()));
+    const default_config = await cook_gro_config(await create_default_config(create_empty_gro_config()));
     const config_path = join(dir, GRO_CONFIG_FILENAME);
     if (!existsSync(config_path)) {
         // No user config file found, so return the default.
@@ -71,7 +95,7 @@ export const load_gro_config = async (dir = paths.root) => {
     // Import the user's `gro.config.ts`.
     const config_module = await import(__rewriteRelativeImportExtension(config_path, true));
     validate_gro_config_module(config_module, config_path);
-    return cook_gro_config(typeof config_module.default === 'function'
+    return await cook_gro_config(typeof config_module.default === 'function'
         ? await config_module.default(default_config)
         : config_module.default);
 };

package/dist/hash.d.ts

@@ -1,5 +1,5 @@
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
  */
-export declare const to_hash: (data: Buffer, algorithm?: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512") => Promise<string>;
+export declare const to_hash: (data: BufferSource, algorithm?: "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512") => Promise<string>;
 //# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hash.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,OAAO,GACnB,MAAM,MAAM,EACZ,YAAW,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAqB,KAChE,OAAO,CAAC,MAAM,CAQhB,CAAC"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hash.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,OAAO,GACnB,MAAM,YAAY,EAClB,YAAW,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,SAAqB,KAChE,OAAO,CAAC,MAAM,CAQhB,CAAC"}

package/dist/hash.js

@@ -1,5 +1,4 @@
-import { webcrypto } from 'node:crypto';
-const { subtle } = webcrypto;
+const { subtle } = globalThis.crypto;
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
  */

package/dist/invoke_task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoke_task.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/invoke_task.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,OAAO,EAAC,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EAAoB,KAAK,IAAI,EAAC,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAgB,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAI9D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAC,KAAK,EAAC,MAAM,YAAY,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,GACvB,WAAW,cAAc,EACzB,MAAM,IAAI,GAAG,SAAS,EACtB,QAAQ,UAAU,EAClB,gBAAgB,KAAK,EACrB,kBAAkB,OAAO,GAAG,IAAI,KAC9B,OAAO,CAAC,IAAI,CAwFd,CAAC"}
+{"version":3,"file":"invoke_task.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/invoke_task.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,OAAO,EAAC,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EAAoB,KAAK,IAAI,EAAC,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAgB,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAI9D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAC,KAAK,EAAC,MAAM,YAAY,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,GACvB,WAAW,cAAc,EACzB,MAAM,IAAI,GAAG,SAAS,EACtB,QAAQ,UAAU,EAClB,gBAAgB,KAAK,EACrB,kBAAkB,OAAO,GAAG,IAAI,KAC9B,OAAO,CAAC,IAAI,CA2Fd,CAAC"}

package/dist/invoke_task.js

@@ -77,7 +77,8 @@ export const invoke_task = async (task_name, args, config, initial_filer, initia
         throw new Silent_Error();
     }
     const loaded_tasks = loaded.value;
-    if (resolved_input_files.length > 1 || resolved_input_files[0].resolved_input_path.is_directory) {
+    if (resolved_input_files.length > 1 ||
+        resolved_input_files[0].resolved_input_path.is_directory) {
         // The input path matches a directory. Log the tasks but don't run them.
         log_tasks(log, loaded_tasks);
         await finish();

package/dist/package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/package.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,4BAA4B,CAAC;AAEzD,eAAO,MAAM,YAAY,EAAE,YAkGnB,CAAC;AAET,eAAO,MAAM,QAAQ,EAAE,QA8vBf,CAAC"}
+{"version":3,"file":"package.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/package.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,4BAA4B,CAAC;AAEzD,eAAO,MAAM,YAAY,EAAE,YAkGnB,CAAC;AAET,eAAO,MAAM,QAAQ,EAAE,QAuwBf,CAAC"}

package/dist/package.js

@@ -1,7 +1,7 @@
 // generated by src/lib/package.gen.ts
 export const package_json = {
     name: '@ryanatkn/gro',
-    version: '0.170.0',
+    version: '0.172.0',
     description: 'task runner and toolkit extending SvelteKit',
     motto: 'generate, run, optimize',
     glyph: '🌰',
@@ -51,7 +51,7 @@ export const package_json = {
         zod: '^4.1.12',
     },
     peerDependencies: {
-        '@ryanatkn/belt': '^0.35.1',
+        '@ryanatkn/belt': '^0.36.0',
         '@sveltejs/kit': '^2',
         esbuild: '^0.25',
         svelte: '^5',
@@ -63,7 +63,7 @@ export const package_json = {
     devDependencies: {
         '@changesets/changelog-git': '^0.2.1',
         '@changesets/types': '^6.1.0',
-        '@ryanatkn/eslint-config': '^0.8.0',
+        '@ryanatkn/eslint-config': '^0.8.1',
         '@ryanatkn/fuz': '^0.147.0',
         '@ryanatkn/moss': '^0.36.0',
         '@sveltejs/adapter-static': '^3.0.10',
@@ -78,7 +78,7 @@ export const package_json = {
         'svelte-check': '^4.3.3',
         typescript: '^5.9.3',
         'typescript-eslint': '^8.42.0',
-        vitest: '^4.0.0',
+        vitest: '^4.0.3',
     },
     prettier: {
         plugins: ['prettier-plugin-svelte'],
@@ -99,7 +99,7 @@ export const package_json = {
 };
 export const src_json = {
     name: '@ryanatkn/gro',
-    version: '0.170.0',
+    version: '0.172.0',
     modules: {
         '.': {
             path: 'index.ts',
@@ -132,10 +132,28 @@ export const src_json = {
                 { name: 'print_command_args', kind: 'function' },
             ],
         },
+        './build_cache.js': {
+            path: 'build_cache.ts',
+            declarations: [
+                { name: 'BUILD_CACHE_METADATA_FILENAME', kind: 'variable' },
+                { name: 'BUILD_CACHE_VERSION', kind: 'variable' },
+                { name: 'Build_Output_Entry', kind: 'variable' },
+                { name: 'Build_Cache_Metadata', kind: 'variable' },
+                { name: 'compute_build_cache_key', kind: 'function' },
+                { name: 'load_build_cache_metadata', kind: 'function' },
+                { name: 'save_build_cache_metadata', kind: 'function' },
+                { name: 'validate_build_cache', kind: 'function' },
+                { name: 'is_build_cache_valid', kind: 'function' },
+                { name: 'collect_build_outputs', kind: 'function' },
+                { name: 'discover_build_output_dirs', kind: 'function' },
+                { name: 'create_build_cache_metadata', kind: 'function' },
+            ],
+        },
         './build.task.js': {
             path: 'build.task.ts',
             declarations: [
                 { name: 'Args', kind: 'variable' },
+                { name: 'GIT_SHORT_HASH_LENGTH', kind: 'variable' },
                 { name: 'task', kind: 'variable' },
             ],
         },
@@ -408,6 +426,7 @@ export const src_json = {
         './gro_config.js': {
             path: 'gro_config.ts',
             declarations: [
+                { name: 'EMPTY_BUILD_CACHE_CONFIG_HASH', kind: 'variable' },
                 { name: 'Gro_Config', kind: 'type' },
                 { name: 'Raw_Gro_Config', kind: 'type' },
                 { name: 'Create_Gro_Config', kind: 'type' },
@@ -820,16 +839,6 @@ export const src_json = {
                 { name: 'validate_task_module', kind: 'function' },
             ],
         },
-        './test_helpers.js': {
-            path: 'test_helpers.ts',
-            declarations: [
-                { name: 'TEST_TIMEOUT_MD', kind: 'variable' },
-                { name: 'SOME_PUBLIC_ENV_VAR_NAME', kind: 'variable' },
-                { name: 'SOME_PUBLIC_ENV_VAR_VALUE', kind: 'variable' },
-                { name: 'init_test_env', kind: 'function' },
-                { name: 'create_ts_test_env', kind: 'function' },
-            ],
-        },
         './test.task.js': {
             path: 'test.task.ts',
             declarations: [

package/dist/package_json.js

@@ -136,7 +136,7 @@ export const parse_repo_url = (package_json) => {
         return;
     }
     const [, owner, repo] = parsed_repo_url;
-    return { owner, repo };
+    return { owner: owner, repo: repo };
 };
 /**
  * Parses a `Package_Json` object but preserves the order of the original keys.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanatkn/gro",
-  "version": "0.170.0",
+  "version": "0.172.0",
   "description": "task runner and toolkit extending SvelteKit",
   "motto": "generate, run, optimize",
   "glyph": "🌰",
@@ -61,7 +61,7 @@
     "zod": "^4.1.12"
   },
   "peerDependencies": {
-    "@ryanatkn/belt": "^0.35.1",
+    "@ryanatkn/belt": "^0.36.0",
     "@sveltejs/kit": "^2",
     "esbuild": "^0.25",
     "svelte": "^5",
@@ -82,7 +82,7 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@changesets/types": "^6.1.0",
-    "@ryanatkn/eslint-config": "^0.8.0",
+    "@ryanatkn/eslint-config": "^0.8.1",
     "@ryanatkn/fuz": "^0.147.0",
     "@ryanatkn/moss": "^0.36.0",
     "@sveltejs/adapter-static": "^3.0.10",
@@ -97,7 +97,7 @@
     "svelte-check": "^4.3.3",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.42.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.3"
   },
   "prettier": {
     "plugins": [

package/src/lib/build.task.ts

@@ -1,8 +1,19 @@
 import {z} from 'zod';
+import {styleText as st} from 'node:util';
+import {git_check_clean_workspace, git_current_commit_hash} from '@ryanatkn/belt/git.js';
+import {rmSync, existsSync} from 'node:fs';
+import {join} from 'node:path';
 
-import type {Task} from './task.ts';
+import {Task_Error, type Task} from './task.ts';
 import {Plugins} from './plugin.ts';
 import {clean_fs} from './clean_fs.ts';
+import {
+	is_build_cache_valid,
+	create_build_cache_metadata,
+	save_build_cache_metadata,
+	discover_build_output_dirs,
+} from './build_cache.ts';
+import {paths} from './paths.ts';
 
 export const Args = z.strictObject({
 	sync: z.boolean().meta({description: 'dual of no-sync'}).default(true),
@@ -12,29 +23,122 @@ export const Args = z.strictObject({
 		.boolean()
 		.meta({description: 'opt out of installing packages before building'})
 		.default(false),
+	force_build: z
+		.boolean()
+		.meta({description: 'force a fresh build, ignoring the cache'})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
+/**
+ * Length of git commit hash when displayed in logs (standard git convention).
+ */
+export const GIT_SHORT_HASH_LENGTH = 7;
+
+/**
+ * Formats a git commit hash for display in logs.
+ * Returns '[none]' if hash is null (e.g., not in a git repo).
+ */
+const format_commit_hash = (hash: string | null): string =>
+	hash?.slice(0, GIT_SHORT_HASH_LENGTH) ?? '[none]';
+
 export const task: Task<Args> = {
 	summary: 'build the project',
 	Args,
 	run: async (ctx): Promise<void> => {
-		const {args, invoke_task, log} = ctx;
-		const {sync, install} = args;
+		const {args, invoke_task, log, config} = ctx;
+		const {sync, install, force_build} = args;
 
 		if (sync || install) {
 			if (!sync) log.warn('sync is false but install is true, so ignoring the sync option');
 			await invoke_task('sync', {install});
 		}
 
-		// TODO possibly detect if the git workspace is clean, and ask for confirmation if not,
-		// because we're not doing things like `gro gen` here because that's a dev/CI concern
+		// Batch git calls upfront for performance (spawning processes is expensive)
+		const [workspace_status, initial_commit] = await Promise.all([
+			git_check_clean_workspace(),
+			git_current_commit_hash(),
+		]);
+		const workspace_dirty = !!workspace_status;
 
-		await clean_fs({build_dist: true});
+		// Discover build output directories once to avoid redundant filesystem scans
+		let build_dirs: Array<string> | undefined;
+
+		// Check build cache unless force_build is set or workspace is dirty
+		if (!workspace_dirty && !force_build) {
+			const cache_valid = await is_build_cache_valid(config, log, initial_commit);
+			if (cache_valid) {
+				log.info(
+					st('cyan', 'skipping build, cache is valid'),
+					st('dim', '(use --force_build to rebuild)'),
+				);
+				return;
+			}
+		} else if (workspace_dirty) {
+			// IMPORTANT: When workspace is dirty, we delete cache AND all outputs to prevent stale state.
+			// Rationale: Uncommitted changes could be reverted, leaving cached outputs from reverted code.
+			// This conservative approach prioritizes safety over convenience during development.
+			const cache_path = join(paths.build, 'build.json');
+			if (existsSync(cache_path)) {
+				rmSync(cache_path, {force: true});
+			}
+
+			// Delete all build output directories
+			build_dirs = discover_build_output_dirs();
+			for (const dir of build_dirs) {
+				rmSync(dir, {recursive: true, force: true});
+			}
+
+			log.info(st('yellow', 'workspace has uncommitted changes - skipping build cache'));
+			// Skip clean_fs - already manually cleaned cache and all build outputs above
+		} else {
+			log.info(st('yellow', 'forcing fresh build, ignoring cache'));
+		}
+
+		// Clean build outputs (skip if workspace was dirty - already cleaned manually above)
+		if (!workspace_dirty) {
+			await clean_fs({build_dist: true});
+		}
 
 		const plugins = await Plugins.create({...ctx, dev: false, watch: false});
 		await plugins.setup();
 		await plugins.adapt();
 		await plugins.teardown();
+
+		// Verify workspace didn't become dirty during build
+		const final_workspace_status = await git_check_clean_workspace();
+		if (final_workspace_status !== workspace_status) {
+			// Workspace state changed during build - this indicates a problem
+			throw new Task_Error(
+				'Build process modified tracked files or created untracked files.\n\n' +
+					'Git status after build:\n' +
+					final_workspace_status +
+					'\n\n' +
+					'Builds should only write to output directories (build/, dist/, etc.).\n' +
+					'This usually indicates a plugin or build step is incorrectly modifying source files.',
+			);
+		}
+
+		// Save build cache metadata after successful build (only if workspace is clean)
+		if (!workspace_dirty) {
+			// Race condition protection: verify git commit didn't change during build
+			const current_commit = await git_current_commit_hash();
+
+			if (current_commit !== initial_commit) {
+				log.warn(
+					st('yellow', 'git commit changed during build'),
+					st(
+						'dim',
+						`(${format_commit_hash(initial_commit)} → ${format_commit_hash(current_commit)})`,
+					),
+					'- cache not saved',
+				);
+			} else {
+				// Commit is stable - safe to save cache
+				const metadata = await create_build_cache_metadata(config, log, initial_commit, build_dirs);
+				save_build_cache_metadata(metadata, log);
+				log.debug('Build cache metadata saved');
+			}
+		}
 	},
 };