@fuzdev/gro 0.192.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ryan Atkinson <mail@ryanatkn.com> <https://ryanatkn.com/>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# gro <img src="static/logo.svg" alt="a pixelated green oak acorn with a glint of sun" width="32" height="32">
+
+[<img src="static/logo.svg" alt="a pixelated green oak acorn with a glint of sun" align="right" width="192" height="192">](https://gro.fuzdev.com/)
+
+> task runner and toolkit extending SvelteKit 🌰 generate, run, optimize
+
+[`npm i -D @fuzdev/gro`](https://www.npmjs.com/package/@fuzdev/gro)
+
+> ⚠️ I still use Gro heavily but I'm transitioning to Rust-based tooling
+> with [Fuz](https://github.com/fuzdev) using [Deno](https://github.com/denoland) as a sidecar.
+> I consider Gro deprecated but there should be a migration path.
+> Please open issues if you need help.
+
+> ⚠️[Windows won't be supported](https://github.com/fuzdev/gro/issues/319), I chose Bash instead.
+
+Docs at [gro.fuzdev.com/docs](https://gro.fuzdev.com/docs) and [src/docs](./src/docs).
+
+Need help or want to share thoughts? See the
+[issues](https://github.com/fuzdev/gro/issues) and
+[discussions](https://github.com/fuzdev/gro/discussions).
+
+## about
+
+Gro is a task runner and toolkit
+extending [SvelteKit](https://github.com/sveltejs/kit),
+[Vite](https://github.com/vitejs/vite),
+and [esbuild](https://github.com/evanw/esbuild)
+for making web frontends, servers, and libraries with TypeScript.
+It's a dev tool, not for production use.
+It includes:
+
+- [task runner](/src/docs/task.md) that uses the filesystem convention `*.task.ts`
+  - lots of [common builtin tasks](/src/docs/tasks.md) that users can easily override and compose
+- tools and patterns for
+  [developing](/src/docs/dev.md),
+  [building](/src/docs/build.md),
+  [testing](/src/docs/test.md),
+  [deploying](/src/docs/deploy.md),
+  and [publishing](/src/docs/publish.md)
+  [SvelteKit](https://github.com/sveltejs/kit) apps, library packages, and Node servers
+  - integrated [TypeScript](https://github.com/microsoft/typescript),
+    [Svelte](https://github.com/sveltejs/svelte),
+    and [SvelteKit](https://github.com/sveltejs/kit)
+  - defers to SvelteKit and Vite for the frontend and
+    [`@sveltejs/package`](https://kit.svelte.dev/docs/packaging) for the library
+  - exposes all of its internals in `$lib`
+  - uses [Changesets](https://github.com/changesets/changesets) for versioning and changelogs
+  - provides a [Node loader](/src/lib/loader.ts) with a [register hook](/src/lib/register.ts)
+    - uses Node's type stripping and supports importing JSON, SvelteKit shims,
+      and SSR'd Svelte files in tests/tasks/scripts
+    - supports [SvelteKit module imports](https://kit.svelte.dev/docs/modules) for
+      `$lib`, `$env`, and `$app` in tasks, tests, Node servers,
+      and other code outside of the SvelteKit frontend,
+      so you can use SvelteKit patterns everywhere
+      (these are best-effort shims, not perfect)
+    - supports running TypeScript files directly without a task via `gro run a.ts`
+      or `node --import @fuzdev/gro/register.js a.ts`
+  - [configurable plugins](/src/docs/plugin.md) to support SvelteKit,
+    [auto-restarting Node servers](/src/lib/gro_plugin_server.ts),
+    and other external build processes
+    - see the [Gro config docs](/src/docs/config.md) and
+      [the default config](https://github.com/fuzdev/gro/blob/main/src/lib/gro.config.default.ts)
+    - see [`fuz_template`](https://github.com/fuz-dev/fuz_template)
+      for a simple starter project example, and
+      [`@feltjs/felt`](https://github.com/feltjs/felt) for a more complex example with custom tasks
+- [testing](/src/docs/test.md) with [`vitest`](https://github.com/vitest-dev/vitest)
+- codegen by convention with [`gen`](/src/docs/gen.md)
+- linting with [ESLint](https://github.com/eslint/eslint)
+  (I also maintain [`@feltjs/eslint-config`](https://github.com/feltjs/eslint-config))
+- formatting with [Prettier](https://github.com/prettier/prettier)
+
+## docs
+
+- early API docs at [/docs/api](https://gro.fuzdev.com/docs/api)
+- developing web frontends, servers, and libraries
+  - [config](/src/docs/config.md)
+  - [dev](/src/docs/dev.md)
+  - [build](/src/docs/build.md) for production
+  - [deploy](/src/docs/deploy.md) to a branch, like for GitHub pages
+  - [publish](/src/docs/publish.md) to npm
+- [`Task`](/src/docs/task.md) runner
+  - builtin [tasks](/src/docs/tasks.md) list
+- [testing](/src/docs/test.md) with [`vitest`](https://github.com/vitest-dev/vitest)
+- [`gen`](/src/docs/gen.md) code generation
+- [`public` package](/src/docs/package_json.md#public-packages) features (nonstandard)
+- full [docs index](/src/docs#readme)
+
+## install
+
+> depends on node >=20.12
+
+Typical usage installs [@fuzdev/gro](https://www.npmjs.com/package/@fuzdev/gro)
+as a dev dependency:
+
+```bash
+npm i -D @fuzdev/gro
+npx @fuzdev/gro # note the package is namespaced, don't install `gro`
+```
+
+It's handy to install globally too:
+
+```bash
+npm i -g @fuzdev/gro
+gro
+```
+
+## usage
+
+Gro has a task runner that discovers and runs TypeScript modules with the `.task.` subextension.
+Running `gro` with no args prints the tasks
+it finds in the current directory along with its builtin tasks:
+
+```bash
+gro # prints available tasks - defers to any local gro installation
+```
+
+```
+Run a task: gro [name]
+View help:  gro [name] --help
+
+19 tasks in gro:
+
+build      build the project
+changeset  call changeset with gro patterns
+check      check that everything is ready to commit
+clean      remove temporary dev and build files, and optionally prune git branches
+commit     commit and push to a new branch
+deploy     deploy to a branch
+dev        start SvelteKit and other dev plugins
+format     format source files
+gen        run code generation scripts
+lint       run eslint
+publish    bump version, publish to the configured registry, and git push
+reinstall  refreshes package-lock.json with the latest and cleanest deps
+release    publish and deploy
+resolve    diagnostic that logs resolved filesystem info for the given input paths
+run        execute a file with the loader, like `node` but works for TypeScript
+sync       run `gro gen`, update `package.json`, and optionally install packages to sync up
+test       run tests with vitest
+typecheck  run svelte-check or tsc on the project without emitting any files
+upgrade    upgrade deps
+```
+
+To run tasks, Gro matches your CLI input against its filesystem conventions.
+It tries to do the right thing, where right is helpful but not surprising,
+with some magic but not too much:
+
+```bash
+gro # displays all available tasks matching `src/lib/**/*.task.ts` and Gro's builtins
+gro a # tries to run `src/lib/a.task.ts`, then `./a.task.ts`, then Gro's builtin if one exists
+gro a --help # displays docs for the "a" task and its args, works for every task
+gro some/dir # lists all tasks inside `src/lib/some/dir`
+gro some/file # runs `src/lib/some/file.task.ts`
+gro some/file.task.ts # same as above
+```
+
+Gro can also run non-task TypeScript files directly
+with [the `gro run` task](/src/lib/run.task.ts) or [register hook](/src/lib/register.ts):
+
+```bash
+gro run foo.ts
+node --import @fuzdev/gro/register.js foo.ts
+```
+
+Or programmatically:
+
+```js
+// myfile.js
+import {register} from 'node:module';
+register('@fuzdev/gro/loader.js', import.meta.url);
+await import('./foo.ts');
+```
+
+Gro has a number of builtin tasks that you can run with the CLI.
+To learn more [see the task docs](/src/docs/task.md)
+and [the generated task index](/src/docs/tasks.md).
+
+```bash
+gro dev # start developing in watch mode
+gro dev -- vite --port 3003 # forward args by separating sections with --
+```
+
+```bash
+gro build # build everything for production
+```
+
+[Testing](/src/docs/test.md) with [`vitest`](https://github.com/vitest-dev/vitest),
+including shims for [SvelteKit modules](https://kit.svelte.dev/docs/modules):
+
+```bash
+gro test # run all tests for `*.test.ts` files with `vitest`
+gro test filepattern1 some.test another.test
+gro test optional_pattern -t "optional search string for test name"
+gro test -- vitest --forwarded_args 'to vitest'
+```
+
+Check all the things:
+
+```bash
+gro check # does all of the following:
+gro typecheck # svelte-check with tsc fallback
+gro test # run tests
+gro gen --check # ensure generated files are current
+gro format --check # ensure everything is formatted
+gro lint # eslint
+```
+
+For a usage example see [the `check.yml` CI config](.github/workflows/check.yml).
+
+Formatting with [`prettier`](https://github.com/prettier/prettier):
+
+```bash
+gro format # format all of the source files using Prettier
+gro format --check # check that all source files are formatted
+```
+
+Codegen with [`gen`](/src/docs/gen.md):
+
+```bash
+gro gen # run codegen for all `*.gen.*` files
+gro gen --check # error if any generated files are new or different
+```
+
+To deploy: (also see [`src/docs/deploy.md`](/src/docs/deploy.md))
+
+```bash
+gro deploy # build and push to the `deploy` branch
+```
+
+To publish: (also see [`src/docs/publish.md`](/src/docs/publish.md))
+
+```bash
+gro publish # flush changeset to changelog, bump version, publish to npm, and git push
+```
+
+More:
+
+```bash
+gro clean # delete all build artifacts from the filesystem
+gro clean --sveltekit --nodemodules --git # also deletes dirs and prunes git branches
+gro upgrade excluded-dep-1 excluded-dep-2 # npm updates to the latest everything
+gro --version # print the Gro version
+```
+
+For more see [the tasks index](/src/docs/tasks.md),
+[the task feature docs](/src/docs/task.md), and [the docs index](/src/docs/README.md).
+
+## develop
+
+```bash
+npm i
+npm run bootstrap # build and link `gro` without itself - needed only once
+gro build # same as `npm run bootstrap` when the `gro` CLI is available
+gro test # make sure everything looks good - same as `npm test`
+gro test some.test another.test
+
+# use your development version of `gro` locally in another project:
+gro build # updates the `gro` CLI, same as `npm run bootstrap`
+cd ../otherproject
+npm link ../gro # from `otherproject/`
+gro build # from `../gro` on changes
+```
+
+## credits 🐢<sub>🐢</sub><sub><sub>🐢</sub></sub>
+
+Gro builds on
+[TypeScript](https://github.com/microsoft/TypeScript) ∙
+[Svelte](https://github.com/sveltejs/svelte) ∙
+[SvelteKit](https://github.com/sveltejs/kit) ∙
+[Vite](https://github.com/vitejs/vite) ∙
+[esbuild](https://github.com/evanw/esbuild) ∙
+[Vitest](https://github.com/vitest-dev/vitest) ∙
+[chokidar](https://github.com/paulmillr/chokidar) ∙
+[zod](https://github.com/colinhacks/zod) ∙
+[@fuzdev/fuz_util](https://github.com/fuzdev/fuz_util) ∙
+[ESLint](https://github.com/eslint/eslint) ∙
+[Prettier](https://github.com/prettier/prettier) ∙
+[svelte-check](https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check) &
+[more](package.json)
+
+## license [🐦](https://wikipedia.org/wiki/Free_and_open-source_software)
+
+[MIT](LICENSE)

package/dist/args.d.ts

@@ -0,0 +1,37 @@
+import { type Args } from '@fuzdev/fuz_util/args.js';
+/**
+ * Parses `task_name` and `args` from `process.argv`,
+ * ignoring anything after any `--`.
+ */
+export declare const to_task_args: (argv?: string[]) => {
+    task_name: string;
+    args: Args;
+};
+/**
+ * Gets the array of raw string args starting with the first `--`, if any.
+ */
+export declare const to_raw_rest_args: (argv?: string[]) => Array<string>;
+/**
+ * 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 declare const to_forwarded_args: (command: string, raw_rest_args?: Array<string>, cache?: Record<string, Args | undefined>) => Args;
+export declare const to_forwarded_args_by_command: (raw_rest_args?: string[]) => Record<string, Args | undefined>;
+/**
+ * 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 declare const to_implicit_forwarded_args: (command_to_strip?: string, raw_rest_args?: string[]) => Args;
+export declare const print_command_args: (serialized_args: Array<string>) => string;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/args.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,IAAI,EAAC,MAAM,0BAA0B,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,eAAmB,KAAG;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAMhF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,eAAmB,KAAG,KAAK,CAAC,MAAM,CAGlE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,MAAM,EACf,gBAAgB,KAAK,CAAC,MAAM,CAAC,EAC7B,wCAAmD,KACjD,IAA4B,CAAC;AAEhC,eAAO,MAAM,4BAA4B,GACxC,wBAAkC,KAChC,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,CAuCjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,GACtC,mBAAmB,MAAM,EACzB,wBAAkC,KAChC,IAaF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAAG,MAK1C,CAAC"}

package/dist/args.js

@@ -0,0 +1,102 @@
+import { styleText as st } from 'node:util';
+import { argv_parse } 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) => {
+    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._; // 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) => {
+    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, raw_rest_args, cache = to_forwarded_args_by_command(raw_rest_args)) => cache[command] ?? {};
+export const to_forwarded_args_by_command = (raw_rest_args = to_raw_rest_args()) => {
+    // Parse each segment of `argv` separated by `--`.
+    const argvs = [];
+    let arr;
+    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 = {};
+    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._;
+        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, raw_rest_args = to_raw_rest_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._;
+    return args;
+};
+export const print_command_args = (serialized_args) => st('gray', '[') +
+    st('magenta', 'running command') +
+    st('gray', ']') +
+    ' ' +
+    serialized_args.join(' ');

package/dist/build.task.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { type Task } from './task.ts';
+/** @nodocs */
+export declare const Args: z.ZodObject<{
+    sync: z.ZodDefault<z.ZodBoolean>;
+    'no-sync': z.ZodDefault<z.ZodBoolean>;
+    gen: z.ZodDefault<z.ZodBoolean>;
+    'no-gen': z.ZodDefault<z.ZodBoolean>;
+    install: z.ZodDefault<z.ZodBoolean>;
+    'no-install': z.ZodDefault<z.ZodBoolean>;
+    force_build: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type Args = z.infer<typeof Args>;
+/**
+ * Length of git commit hash when displayed in logs (standard git convention).
+ */
+export declare const GIT_SHORT_HASH_LENGTH = 7;
+/** @nodocs */
+export declare const task: Task<Args>;
+//# sourceMappingURL=build.task.d.ts.map

package/dist/build.task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.task.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/build.task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAOtB,OAAO,EAAY,KAAK,IAAI,EAAC,MAAM,WAAW,CAAC;AAW/C,cAAc;AACd,eAAO,MAAM,IAAI;;;;;;;;kBAcf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AASvC,cAAc;AACd,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,IAAI,CAqG3B,CAAC"}

package/dist/build.task.js

@@ -0,0 +1,119 @@
+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 } from "./task.js";
+import { Plugins } from "./plugin.js";
+import { clean_fs } from "./clean_fs.js";
+import { is_build_cache_valid, create_build_cache_metadata, save_build_cache_metadata, discover_build_output_dirs, } from "./build_cache.js";
+import { paths } from "./paths.js";
+/** @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),
+});
+/**
+ * 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) => hash?.slice(0, GIT_SHORT_HASH_LENGTH) ?? '[none]';
+/** @nodocs */
+export const task = {
+    summary: 'build the project',
+    Args,
+    run: async (ctx) => {
+        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;
+        // 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');
+            }
+        }
+    },
+};