@fuzdev/gro 0.192.0

package/dist/upgrade.task.js

@@ -0,0 +1,111 @@
+import { args_serialize } from '@fuzdev/fuz_util/args.js';
+import { GitOrigin, git_pull } from '@fuzdev/fuz_util/git.js';
+import { spawn } from '@fuzdev/fuz_util/process.js';
+import { rm } from 'node:fs/promises';
+import { z } from 'zod';
+import { to_forwarded_args } from "./args.js";
+import { spawn_cli } from "./cli.js";
+import { NODE_MODULES_DIRNAME } from "./constants.js";
+import { package_json_extract_dependencies, package_json_load, } from "./package_json.js";
+import { TaskError } from "./task.js";
+/** @nodocs */
+export const Args = z.strictObject({
+    _: z
+        .array(z.string())
+        .meta({ description: 'names of deps to exclude from the upgrade' })
+        .default([]),
+    only: z
+        .union([z.string(), z.array(z.string())])
+        .meta({
+        description: 'names of deps to include in the upgrade',
+    })
+        .default([])
+        .transform((v) => (Array.isArray(v) ? v : [v])),
+    origin: GitOrigin.describe('git origin to deploy to').default('origin'),
+    force: z.boolean().meta({ description: 'if true, print out the planned upgrades' }).default(false),
+    pull: z.boolean().meta({ description: 'dual of no-pull' }).default(true),
+    'no-pull': z.boolean().meta({ description: 'opt out of git pull' }).default(false),
+    delete_node_modules: z
+        .boolean()
+        .meta({ description: 'if true, deletes node_modules before upgrading' })
+        .default(false),
+    node_modules_path: z // TODO maybe configured globally instead
+        .string()
+        .meta({ description: 'path to modules directory to delete' })
+        .default(NODE_MODULES_DIRNAME),
+    delete_lockfile: z
+        .boolean()
+        .meta({ description: 'if true, deletes the lockfile before upgrading' })
+        .default(false),
+    lockfile_path: z
+        .string()
+        .meta({ description: 'path to the lockfile to delete' })
+        .default('package-lock.json'),
+    dry: z.boolean().meta({ description: 'if true, print out the planned upgrades' }).default(false),
+});
+/** @nodocs */
+export const task = {
+    summary: 'upgrade deps',
+    Args,
+    run: async ({ args, log, config }) => {
+        const { _, only, origin, force, pull, delete_node_modules, node_modules_path, delete_lockfile, lockfile_path, dry, } = args;
+        if (_.length && only.length) {
+            throw new TaskError('Cannot call `gro upgrade` with both rest args and --only.');
+        }
+        // TODO maybe a different task that pulls and does other things, like `gro ready`
+        if (pull) {
+            await git_pull(origin);
+        }
+        if (delete_node_modules) {
+            log.info(`deleting node_modules at `, node_modules_path);
+            await rm(node_modules_path, { recursive: true, force: true });
+        }
+        if (delete_lockfile) {
+            log.info(`deleting lockfile at`, lockfile_path);
+            await rm(lockfile_path, { force: true });
+        }
+        const package_json = await package_json_load();
+        const all_deps = package_json_extract_dependencies(package_json);
+        const deps = only.length
+            ? all_deps.filter((d) => only.includes(d.name))
+            : all_deps.filter((d) => !_.includes(d.name));
+        if (only.length && only.length !== deps.length) {
+            throw new TaskError(`Some deps to upgrade were not found: ${only.filter((o) => !deps.find((d) => d.name === o)).join(', ')}`);
+        }
+        const upgrade_items = to_upgrade_items(deps);
+        log.info(`upgrading:`, upgrade_items.join(' '));
+        const install_args = ['install'].concat(upgrade_items);
+        if (dry) {
+            install_args.push('--dry-run');
+            log.info(`deps`, deps);
+        }
+        if (force) {
+            install_args.push('--force');
+        }
+        install_args.push(...args_serialize(to_forwarded_args(config.pm_cli)));
+        await spawn(config.pm_cli, install_args);
+        // TODO @many this relies on npm behavior that changed in v11
+        // If we deleted the lockfile or node modules, `npm install` again
+        // to fix a recurring npm bug getting the lockfile to its final state.
+        if (!dry && (delete_node_modules || delete_lockfile)) {
+            log.info(`installing again to fix npm lockfile bugs`);
+            await spawn(config.pm_cli, ['install']);
+        }
+        // Sync in a new process to pick up any changes after installing, avoiding some errors.
+        await spawn_cli('gro', ['sync']); // don't install because we do above
+    },
+};
+const EXACT_VERSION_MATCHER = /^..*@.+/;
+const CUSTOM_TAG_MATCHER = /^[\^~><=]*.+-(.+)/;
+// TODO hacky and limited
+// TODO probably want to pass through exact deps as well, e.g. @foo/bar@1
+const to_upgrade_items = (deps) => deps.map((dep) => {
+    if (EXACT_VERSION_MATCHER.test(dep.name)) {
+        return dep.name;
+    }
+    const custom_tag_matches = CUSTOM_TAG_MATCHER.exec(dep.version);
+    if (custom_tag_matches) {
+        return dep.name + '@' + custom_tag_matches[1].split('.')[0]; // I tried adding `\.?` to the end but doesn't work and I'm being lazy so I'm just splitting
+    }
+    return dep.name + '@latest';
+});

package/dist/watch_dir.d.ts

@@ -0,0 +1,36 @@
+import { type ChokidarOptions, type Matcher } from 'chokidar';
+import type { PathFilter } from '@fuzdev/fuz_util/path.js';
+export interface WatchNodeFs {
+    init: () => Promise<void>;
+    close: () => Promise<void>;
+}
+export interface WatcherChange {
+    type: WatcherChangeType;
+    path: string;
+    is_directory: boolean;
+}
+export type WatcherChangeType = 'add' | 'update' | 'delete';
+export type WatcherChangeCallback = (change: WatcherChange) => void;
+export interface WatchDirOptions {
+    dir: string;
+    on_change: WatcherChangeCallback;
+    filter?: PathFilter | null | undefined;
+    chokidar?: ChokidarOptions;
+    /**
+     * When `false`, returns the `path` relative to `dir`.
+     * @default true
+     */
+    absolute?: boolean;
+    /**
+     * Pattern to ignore files, merged into `chokidar.ignored` if also provided.
+     * - `undefined` (default) ignores files matching `.tmp.` pattern
+     * - `null` sets no default ignore pattern
+     * - or some custom pattern
+     */
+    ignored?: Matcher | null;
+}
+/**
+ * Watch for changes on the filesystem using chokidar.
+ */
+export declare const watch_dir: ({ dir, on_change, filter, absolute, chokidar, ignored, }: WatchDirOptions) => WatchNodeFs;
+//# sourceMappingURL=watch_dir.d.ts.map

package/dist/watch_dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch_dir.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/watch_dir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,eAAe,EAAkB,KAAK,OAAO,EAAC,MAAM,UAAU,CAAC;AAInF,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAOzD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;CACtB;AACD,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,qBAAqB,CAAC;IACjC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,0DAOvB,eAAe,KAAG,WA+CpB,CAAC"}

package/dist/watch_dir.js

@@ -0,0 +1,69 @@
+import { watch } from 'chokidar';
+import { relative } from 'node:path';
+import { statSync } from 'node:fs';
+import { create_deferred } from '@fuzdev/fuz_util/async.js';
+import { EMPTY_OBJECT } from '@fuzdev/fuz_util/object.js';
+const TMP_FILE_PATTERN = /\.tmp\./;
+/**
+ * Watch for changes on the filesystem using chokidar.
+ */
+export const watch_dir = ({ dir, on_change, filter, absolute = true, chokidar, ignored = TMP_FILE_PATTERN, }) => {
+    let watcher;
+    let initing;
+    return {
+        init: async () => {
+            if (initing)
+                return initing.promise;
+            initing = create_deferred();
+            watcher = watch(dir, resolve_chokidar_options(chokidar, ignored));
+            watcher.on('add', (path) => {
+                const final_path = absolute ? path : relative(dir, path);
+                if (filter && !filter(final_path, false))
+                    return;
+                on_change({ type: 'add', path: final_path, is_directory: false });
+            });
+            watcher.on('addDir', (path) => {
+                const final_path = absolute ? path : relative(dir, path);
+                if (filter && !filter(final_path, true))
+                    return;
+                on_change({ type: 'add', path: final_path, is_directory: true });
+            });
+            watcher.on('change', (path, s) => {
+                const stats = s ?? statSync(path);
+                const final_path = absolute ? path : relative(dir, path);
+                if (filter && !filter(final_path, stats.isDirectory())) {
+                    return;
+                }
+                on_change({ type: 'update', path: final_path, is_directory: stats.isDirectory() });
+            });
+            watcher.on('unlink', (path) => {
+                const final_path = absolute ? path : relative(dir, path);
+                if (filter && !filter(final_path, false))
+                    return;
+                on_change({ type: 'delete', path: final_path, is_directory: false });
+            });
+            watcher.on('unlinkDir', (path) => {
+                const final_path = absolute ? path : relative(dir, path);
+                if (filter && !filter(final_path, true))
+                    return;
+                on_change({ type: 'delete', path: final_path, is_directory: true });
+            });
+            // wait until ready
+            watcher.once('ready', () => initing?.resolve());
+            await initing.promise;
+        },
+        close: async () => {
+            initing = undefined;
+            if (!watcher)
+                return;
+            await watcher.close();
+        },
+    };
+};
+const resolve_chokidar_options = (options, ignored) => {
+    if (ignored === null)
+        return options;
+    const { ignored: i, ...rest } = options ?? EMPTY_OBJECT;
+    const resolved_ignored = i === undefined ? ignored : Array.isArray(i) ? [...i, ignored] : [i, ignored];
+    return { ...rest, ignored: resolved_ignored };
+};

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@fuzdev/gro",
+  "version": "0.192.0",
+  "description": "task runner and toolkit extending SvelteKit",
+  "motto": "generate, run, optimize",
+  "glyph": "🌰",
+  "logo": "logo.svg",
+  "logo_alt": "a pixelated green oak acorn with a glint of sun",
+  "license": "MIT",
+  "homepage": "https://gro.fuzdev.com/",
+  "author": {
+    "name": "Ryan Atkinson",
+    "email": "mail@ryanatkn.com",
+    "url": "https://www.ryanatkn.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fuzdev/gro.git"
+  },
+  "bugs": "https://github.com/fuzdev/gro/issues",
+  "funding": "https://www.ryanatkn.com/funding",
+  "scripts": {
+    "bootstrap": "rm -rf .gro dist && svelte-kit sync && svelte-package && chmod +x ./dist/gro.js && npm link -f",
+    "start": "gro dev",
+    "dev": "gro dev",
+    "build": "gro build",
+    "check": "gro check",
+    "test": "gro test",
+    "preview": "vite preview",
+    "deploy": "gro deploy"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.15"
+  },
+  "bin": {
+    "gro": "dist/gro.js"
+  },
+  "keywords": [
+    "web",
+    "tools",
+    "task runner",
+    "tasks",
+    "codegen",
+    "svelte",
+    "sveltekit",
+    "vite",
+    "typescript"
+  ],
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "dotenv": "^17.2.3",
+    "esm-env": "^1.2.2",
+    "oxc-parser": "^0.99.0",
+    "prettier": "^3.7.4",
+    "prettier-plugin-svelte": "^3.4.1",
+    "ts-blank-space": "^0.6.2",
+    "tslib": "^2.8.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@fuzdev/fuz_util": ">=0.49.2",
+    "@sveltejs/kit": "^2",
+    "esbuild": "^0.27.0",
+    "svelte": "^5",
+    "typescript": "^5",
+    "vitest": "^3 || ^4"
+  },
+  "peerDependenciesMeta": {
+    "@sveltejs/kit": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "vitest": "^3 || ^4"
+  },
+  "devDependencies": {
+    "@changesets/changelog-git": "^0.2.1",
+    "@changesets/types": "^6.1.0",
+    "@fuzdev/fuz_code": "^0.44.1",
+    "@fuzdev/fuz_css": "^0.47.0",
+    "@fuzdev/fuz_ui": "^0.182.0",
+    "@fuzdev/fuz_util": "^0.50.1",
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "@ryanatkn/eslint-config": "^0.9.0",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
+    "@types/node": "^24.10.1",
+    "@webref/css": "^8.2.0",
+    "esbuild": "^0.27.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-svelte": "^3.13.1",
+    "magic-string": "^0.30.21",
+    "svelte": "^5.49.1",
+    "svelte-check": "^4.3.6",
+    "svelte2tsx": "^0.7.47",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1",
+    "vitest": "^4.0.15",
+    "zimmerframe": "^1.1.4"
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-svelte"
+    ],
+    "useTabs": true,
+    "printWidth": 100,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "overrides": [
+      {
+        "files": "package.json",
+        "options": {
+          "useTabs": false
+        }
+      }
+    ]
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src/lib/**/*.ts",
+    "!src/lib/**/*.test.*",
+    "!dist/**/*.test.*"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  }
+}

package/src/lib/args.ts

@@ -0,0 +1,115 @@
+import {styleText as st} from 'node:util';
+import {argv_parse, type Args} from '@fuzdev/fuz_util/args.js';
+
+/**
+ * Parses `task_name` and `args` from `process.argv`,
+ * ignoring anything after any `--`.
+ */
+export const to_task_args = (argv = process.argv): {task_name: string; args: Args} => {
+	const forwarded_index = argv.indexOf('--');
+	const args = argv_parse(forwarded_index === -1 ? argv.slice(2) : argv.slice(2, forwarded_index));
+	const task_name = args._.shift() ?? '';
+	if (!args._.length) delete (args as Args)._; // enable schema defaults
+	return {task_name, args};
+};
+
+/**
+ * Gets the array of raw string args starting with the first `--`, if any.
+ */
+export const to_raw_rest_args = (argv = process.argv): Array<string> => {
+	const forwarded_index = argv.indexOf('--');
+	return forwarded_index === -1 ? [] : argv.slice(forwarded_index);
+};
+
+/**
+ * Parses `process.argv` for the specified `command`, so given
+ * `gro taskname arg1 --arg2 -- eslint eslintarg1 --eslintarg2 -- tsc --tscarg1 --tscarg2`
+ * the `command` `'eslint'` returns `eslintarg1 --eslintarg2`
+ * and `'tsc'` returns `--tscarg1` and `--tscarg2`.
+ */
+export const to_forwarded_args = (
+	command: string,
+	raw_rest_args?: Array<string>,
+	cache = to_forwarded_args_by_command(raw_rest_args),
+): Args => cache[command] ?? {};
+
+export const to_forwarded_args_by_command = (
+	raw_rest_args = to_raw_rest_args(),
+): Record<string, Args | undefined> => {
+	// Parse each segment of `argv` separated by `--`.
+	const argvs: Array<Array<string>> = [];
+	let arr: Array<string> | undefined;
+	for (const arg of raw_rest_args) {
+		if (arg === '--') {
+			if (arr?.length) argvs.push(arr);
+			arr = [];
+		} else if (!arr) {
+			continue;
+		} else if (arg) {
+			arr.push(arg);
+		}
+	}
+	if (arr?.length) argvs.push(arr);
+	// Add each segment of parsed `argv` keyed by the first rest arg,
+	// which is assumed to be the CLI command that gets forwarded the args.
+	const forwarded_args_by_command: Record<string, Args> = {};
+	for (const argv of argvs) {
+		const args = argv_parse(argv);
+		let command = args._.shift();
+		if (!command) {
+			// Skip sections without a command name - these are handled by `to_implicit_forwarded_args`.
+			// This allows `gro run script.ts -- --help` to pass `--help` to the script.
+			continue;
+		}
+		// Gro commands get combined with their task name.
+		if (command === 'gro') {
+			if (!args._.length) {
+				throw Error(
+					`Malformed args following a \`--\`. Expected gro taskname: \`${argv.join(' ')}\``,
+				);
+			}
+			command += ' ' + args._.shift();
+		}
+		if (!args._.length) delete (args as Args)._;
+		forwarded_args_by_command[command] = args;
+	}
+	return forwarded_args_by_command;
+};
+
+/**
+ * Gets all args after the first `--` without assuming a command name.
+ * This is useful for tasks that want to forward args directly to a tool
+ * without requiring users to specify the tool name explicitly.
+ * Optionally strips a specific command name if present for backward compatibility.
+ * @example
+ * ```ts
+ * // `gro test -- --watch` → {watch: true}
+ * // `gro test -- foo.test.ts` → {_: ['foo.test.ts']}
+ * // `gro test -- vitest --watch` with command_to_strip='vitest' → {watch: true}
+ * to_implicit_forwarded_args('vitest')
+ * ```
+ */
+export const to_implicit_forwarded_args = (
+	command_to_strip?: string,
+	raw_rest_args = to_raw_rest_args(),
+): Args => {
+	const start = raw_rest_args.indexOf('--');
+	if (start === -1) return {};
+
+	let argv = raw_rest_args.slice(start + 1);
+
+	if (command_to_strip && argv[0] === command_to_strip) {
+		argv = argv.slice(1);
+	}
+
+	const args = argv_parse(argv);
+	if (!args._.length) delete (args as Args)._;
+	return args;
+};
+
+export const print_command_args = (serialized_args: Array<string>): string =>
+	st('gray', '[') +
+	st('magenta', 'running command') +
+	st('gray', ']') +
+	' ' +
+	serialized_args.join(' ');

package/src/lib/build.task.ts

@@ -0,0 +1,151 @@
+import {z} from 'zod';
+import {styleText as st} from 'node:util';
+import {git_check_clean_workspace, git_current_commit_hash} from '@fuzdev/fuz_util/git.js';
+import {rm} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+
+import {TaskError, 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';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	sync: z.boolean().meta({description: 'dual of no-sync'}).default(true),
+	'no-sync': z.boolean().meta({description: 'opt out of gro sync'}).default(false),
+	gen: z.boolean().meta({description: 'dual of no-gen'}).default(true),
+	'no-gen': z.boolean().meta({description: 'opt out of gro gen'}).default(false),
+	install: z.boolean().meta({description: 'dual of no-install'}).default(true),
+	'no-install': z // convenience, same as `gro build -- gro sync --no-install` but the latter takes precedence
+		.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]';
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'build the project',
+	Args,
+	run: async (ctx): Promise<void> => {
+		const {args, invoke_task, log, config} = ctx;
+		const {sync, gen, 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, gen: false});
+		}
+
+		if (gen) {
+			await invoke_task('gen');
+		}
+
+		// 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;
+
+		// 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 (await fs_exists(cache_path)) {
+				await rm(cache_path, {force: true});
+			}
+
+			// Delete all build output directories
+			build_dirs = await discover_build_output_dirs();
+			await Promise.all(build_dirs.map((dir) => rm(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 TaskError(
+				'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);
+				await save_build_cache_metadata(metadata, log);
+				log.debug('Build cache metadata saved');
+			}
+		}
+	},
+};