webanvil 0.0.6 → 0.0.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Mateusz Pietrzak
-
-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.
+MIT License
+
+Copyright (c) 2026 Mateusz Pietrzak
+
+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

@@ -1,38 +1,490 @@
-<div align="center">
-
-[![license](https://img.shields.io/npm/l/webanvil.svg)](https://github.com/mzpkdev/webanvil/blob/master/LICENSE)
-[![npm version](https://img.shields.io/npm/v/webanvil.svg)](https://www.npmjs.com/package/webanvil)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![bundle size](https://img.shields.io/bundlephobia/min/webanvil)](https://bundlephobia.com/result?p=webanvil)
-
-</div>
-<br>
-<br>
-
-<p align="center">
-  <strong>WebAnvil</strong>
-  <p align="center">
-    A zero configuration static site generator that just works.
-    <br />
-    <br />
-    <a href="https://github.com/mzpkdev/webanvil/issues">Report a bug</a>
-    &nbsp;&nbsp;·&nbsp;&nbsp;
-    <a href="https://github.com/mzpkdev/webanvil/issues">Request a feature</a>
-  </p>
-<br />
-<br />
-
-Table of Contents
-------------------
-
-* [Getting started](#getting-started)
-    * [How to install](#how-to-install)
-
-Getting started
-----------------
-
-### How to install
-
-```shell
-npm install webanvil
-```
+<div align="center">
+  <img src=".github/assets/banner.svg" width="1012" alt="WebAnvil: build the web, forge the backend" />
+
+  <p>
+    <strong>WebAnvil</strong> · one CLI for building, testing, linting, formatting, and type-checking JavaScript and TypeScript projects
+    <br />
+    <br />
+    <a href="#getting-started"><strong>Get started »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/mzpkdev/webanvil/issues">Report a bug</a>
+    &nbsp;&nbsp;·&nbsp;&nbsp;
+    <a href="https://github.com/mzpkdev/webanvil/issues">Request a feature</a>
+  </p>
+</div>
+
+Table of contents
+-----------------
+
+- [Why WebAnvil?](#why-webanvil)
+- [What it includes](#what-it-includes)
+- [Getting started](#getting-started)
+    - [Install](#install)
+    - [Everyday commands](#everyday-commands)
+    - [A web app](#a-web-app)
+    - [A Node project](#a-node-project)
+- [Configuration](#configuration)
+    - [Tool selection](#tool-selection)
+    - [Native tool configuration](#native-tool-configuration)
+    - [Node declarations](#node-declarations)
+    - [Command-line options](#command-line-options)
+- [Migration](#migration)
+- [Command reference](#command-reference)
+
+Why WebAnvil?
+-------------
+
+JavaScript projects usually need a builder, a development server, a test runner, a linter, a formatter, and a type checker. Each tool has its own command and configuration. That is workable, but it makes the project setup longer than it needs to be.
+
+WebAnvil puts the common jobs behind `wa`. It uses Vite for web projects, Rolldown for Node builds, Vitest for tests, and Oxc for linting and formatting. You keep those tools, but package scripts and the first layer of configuration stay in one place.
+
+```sh
+wa dev        # develop a web app or watch a Node build
+wa build      # build the project
+wa preview    # serve the production web build
+wa clean      # remove tracked build output
+wa check      # check formatting, linting, and types
+wa check --fix # format files and apply safe lint fixes before type checking
+wa test       # run tests, watch them, collect coverage, or open the UI
+wa lint       # lint files
+wa format      # format files
+wa typecheck   # type-check the project
+```
+
+What it includes
+----------------
+
+| Project job                | WebAnvil command                   | Tool                             |
+| -------------------------- | ---------------------------------- | -------------------------------- |
+| Web builds and development | `wa build`, `wa dev`, `wa preview` | Vite                             |
+| Node builds and watch mode | `wa build`, `wa dev`               | Rolldown                         |
+| Tracked output cleanup     | `wa clean`                         | WebAnvil                         |
+| Static checks              | `wa check`                         | Oxfmt, Oxlint, TypeScript Native |
+| Tests                      | `wa test`                          | Vitest                           |
+| Linting                    | `wa lint`                          | Oxlint                           |
+| Formatting                 | `wa format`                        | Oxfmt                            |
+| Type checking              | `wa typecheck`                     | TypeScript Native                |
+
+Getting started
+---------------
+
+### Install
+
+Install WebAnvil as a development dependency:
+
+```sh
+npm install --save-dev webanvil
+```
+
+Your package manager remains responsible for dependencies, the lockfile, and
+the installed tree. WebAnvil never installs or updates tools. When a supported
+tool is declared directly by the active project, or by a workspace that contains
+it, WebAnvil uses that installed version. Otherwise it uses the exact version
+shipped with WebAnvil.
+
+Add the scripts you want to `package.json`:
+
+```json
+{
+    "scripts": {
+        "dev": "wa dev",
+        "build": "wa build",
+        "clean": "wa clean",
+        "check": "wa check",
+        "test": "wa test",
+        "lint": "wa lint",
+        "format": "wa format",
+        "typecheck": "wa typecheck"
+    }
+}
+```
+
+You can start without a config file. WebAnvil defaults to a Node project with `src/index.ts` as its entry and `dist` as its output directory.
+
+### Everyday commands
+
+Run the commands through npm or directly with `wa`:
+
+```sh
+npm run dev
+npm run build
+npm run clean
+npm run check
+npm run test
+npm run lint
+npm run format
+npm run typecheck
+```
+
+`wa check` checks formatting, linting, and types sequentially, stopping on the
+first failure. It is read-only by default. Use `wa check --fix` to format files
+and apply safe lint fixes before type checking. Tests stay separate under
+`wa test`.
+
+### A web app
+
+Set the build mode to `"web"` and point it at an HTML entry point. `wa dev` starts Vite's development server, `wa build` produces a production bundle, and `wa preview` serves that bundle locally.
+
+```ts
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: {
+        mode: "web",
+        entry: "index.html",
+        outDir: "dist",
+        copy: [{ from: "assets/**", to: "assets" }]
+    }
+})
+```
+
+Pass framework plugins through your WebAnvil configuration:
+
+```ts
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: { mode: "web", entry: "index.html" },
+    plugins: [react()]
+})
+```
+
+### A Node project
+
+Node mode is the default. Declare the package's public roots with `entry` or
+`entries`, then choose whether Rolldown should preserve or bundle the reachable
+module graph:
+
+```ts
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: {
+        mode: "node",
+        entries: {
+            ".": "src/index.ts",
+            "./feature": "src/internal/implementation.ts"
+        },
+        outDir: "dist",
+        bundle: true,
+        formats: ["esm", "cjs"],
+        declaration: true,
+        sourcemap: true,
+        platform: "node",
+        target: "es2022"
+    }
+})
+```
+
+Without `bundle`, Rolldown uses `preserveModules` and emits only modules
+reachable from the public roots. It does not mirror the source tree, so tests,
+examples, setup files, and other unreachable modules are omitted. With
+`bundle`, those same roots become bundle entries. An explicit positional entry
+overrides configured `entries`.
+
+TypeScript paths, native Rolldown aliases and resolver plugins, and package
+export conditions resolve before WebAnvil decides whether an import is a
+dependency. Project-local results stay in the graph. Node built-ins and
+installed packages remain external with their original portable specifiers,
+while unresolved imports fail the build.
+
+`platform` (`node`, `browser`, or `neutral`) is Node-only. `target` is one
+syntax target or an array; CLI lists are comma-separated. Node defaults are
+`platform: "node"` and `target: "node20"`. Web production forwards only an
+explicit target; Vite config wins, and web dev does not apply it.
+
+For Node builds, WebAnvil fills omitted output settings from the nearest
+`package.json`: `import` and `require` export conditions enable ESM and CommonJS
+respectively, while a top-level `types` field or `types` export condition enables
+declarations. Explicit CLI options override `webanvil.config.*`, which overrides
+package metadata, which overrides built-in defaults. Package metadata does not
+affect web builds.
+
+`wa dev` watches and rebuilds Node output with the same `build` configuration as
+`wa build`: bundle mode, entries, formats, declarations, source maps,
+minification, platform, target, plugins, static copies, stale-output cleanup, and
+build metadata all stay in sync. It does not run or restart the server process.
+
+Node output is transactional. WebAnvil generates every requested format before
+writing, rejects filename or copy collisions, and replaces the previous output
+only after the complete build succeeds. A failed one-shot build or watch cycle
+rolls back to the last successful files and build metadata.
+
+### Node build plugins
+
+Node builds use Rolldown. To use a plugin in both web and Node builds, wrap an
+unplugin implementation with `definePlugin()`:
+
+```ts
+import { defineConfig, definePlugin } from "webanvil"
+import { createUnplugin } from "unplugin"
+
+const replace = createUnplugin<{ from: string; to: string }>((options) => ({
+    name: "replace",
+    transform: (code) => code.replace(options.from, options.to)
+}))
+
+export default defineConfig({
+    plugins: [definePlugin(replace, { from: "development", to: "production" })]
+})
+```
+
+Plain Vite plugins work in effective web mode. Effective Node builds require
+plugins created with `definePlugin()`; raw Vite and Rolldown plugins are rejected
+during config validation after explicit CLI overrides are applied.
+
+Configuration
+-------------
+
+Use `webanvil.config.ts` to keep WebAnvil orchestration and native tool settings
+together:
+
+```ts
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: {
+        mode: "web",
+        entry: "index.html",
+        outDir: "dist"
+    },
+    vite: {
+        base: "/app/"
+    },
+    test: {
+        globals: true,
+        environment: "jsdom",
+        include: ["test/**/*.test.ts"]
+    },
+    lint: {
+        rules: { "no-console": "deny" }
+    },
+    format: {
+        printWidth: 100,
+        semi: false
+    }
+})
+```
+
+### Tool selection
+
+WebAnvil selects compatible project and workspace declarations before its own
+fallbacks. A transitive or merely hoisted package is not selected. Each command
+preflights the engines it can dispatch before `webanvil.config.*` is loaded or
+its plugins are evaluated, so a declared command engine that is missing, has
+invalid package identity, or is outside the supported range fails first.
+
+| Tool                       | Supported project/workspace versions | Exact WebAnvil fallback |
+| -------------------------- | ------------------------------------ | ----------------------- |
+| Vite                       | `>=8.1.5 <9`                         | `8.1.5`                 |
+| Vitest                     | `>=4.1.10 <5`                        | `4.1.10`                |
+| Rolldown                   | `>=1.2.0 <2`                         | `1.2.0`                 |
+| Oxlint                     | `>=1.75.0 <2`                        | `1.75.0`                |
+| Oxfmt                      | `>=0.60.0 <0.61`                     | `0.60.0`                |
+| TypeScript (declarations)  | `>=5 <7`                             | `6.0.3`                 |
+| TypeScript Native (`tsgo`) | `>=7.0.0-dev.20260707.2 <7.0.0`      | `7.0.0-dev.20260707.2`  |
+
+When a tool is first used, the CLI reports its package, version, and source, for
+example `Using rolldown 1.2.0 (project)` or
+`Using rolldown 1.2.0 (webanvil)`.
+
+The TypeScript compiler is selected only after configuration enables a
+declaration build, but before Rolldown starts that build. It follows the same
+direct project/workspace declaration and exact-fallback rules.
+
+### Native tool configuration
+
+The `vite`, `test`, `rolldown`, `lint`, and `format` blocks use the owning
+tool's exported TypeScript types. WebAnvil validates them as opaque native
+objects and passes compatible upstream options through without duplicating
+their schemas.
+
+Precedence is:
+
+1. explicit CLI values for the current run;
+2. an existing native `vite.config.*`, `vitest.config.*`, `.oxlintrc.json`, or
+   `.oxfmtrc.json`;
+3. the matching native block in `webanvil.config.*`;
+4. WebAnvil defaults.
+
+WebAnvil-owned `build`, `copy`, cross-engine `plugins`, and CLI behavior remain
+orchestration settings. `rolldown.input` and per-format `rolldown.output`
+options extend Node builds; WebAnvil still owns the input roots, output
+directory, format, cleanup, and `preserveModules` strategy.
+
+```ts
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: {
+        mode: "node",
+        entries: { ".": "src/index.ts", "./feature": "src/feature.ts" },
+        formats: ["esm", "cjs"]
+    },
+    rolldown: {
+        input: {
+            resolve: { conditionNames: ["source", "node", "import"] }
+        },
+        output: {
+            esm: {
+                entryFileNames: "[name].mjs",
+                chunkFileNames: "chunks/[name]-[hash].mjs"
+            },
+            cjs: {
+                entryFileNames: "[name].js",
+                chunkFileNames: "chunks/[name]-[hash].js"
+            }
+        }
+    }
+})
+```
+
+Native `entryFileNames`, `chunkFileNames`, and `assetFileNames` accept the same
+strings or callbacks as Rolldown. WebAnvil records the actual emitted paths, so
+stale-output removal, rollback, build metadata, and `wa clean` follow customized
+names and source maps.
+
+### Node declarations
+
+`build.declaration: true` uses `rolldown-plugin-dts` with its TypeScript
+generator. Pass a native declaration options object to select the `"oxc"` or
+`"tsgo"` generator and other plugin settings:
+
+```ts
+import { defineConfig } from "webanvil"
+
+export default defineConfig({
+    build: {
+        declaration: {
+            generator: "tsc",
+            sourcemap: true
+        }
+    }
+})
+```
+
+The TypeScript generator selects a compatible project/workspace TypeScript
+declaration when present, otherwise WebAnvil's exact TypeScript fallback.
+Project-local `ts-patch` and TypeScript emit transforms are honored when they
+are directly declared and resolve to that same compiler. Emit transforms
+require the `tsc` generator; Oxc and `tsgo` are explicit alternatives.
+
+`rolldown-plugin-dts` owns declaration paths and imports. ESM-only builds attach
+one declaration graph; CommonJS-only and dual-format builds use one
+declaration-only ESM pass. Because the plugin initializes TypeScript in process,
+one process cannot switch to a different compiler path or version after its
+first TypeScript declaration build—run builds needing different compilers in
+separate processes.
+
+### Command-line options
+
+Command-line options override the config file. For example, this writes a build to `preview` without changing `webanvil.config.ts`:
+
+```sh
+wa build --out-dir preview
+```
+
+For Node builds and watchers, `--bundle` and `--no-bundle` are explicit
+opposites. `--no-bundle` overrides `build.bundle: true` for that run and emits
+the reachable module graph with Rolldown `preserveModules`.
+
+Use `build.copy` for static files that should be copied unchanged after either a
+web or Node build. Each mapping preserves the path beneath the source glob's
+static base. For example, `assets/**` mapped to `assets` copies
+`assets/images/logo.svg` to `dist/assets/images/logo.svg`. `--copy` accepts one
+or more `source=destination` mappings and replaces configured mappings for that
+run:
+
+```sh
+wa build --copy "assets/**=assets" "src/templates/**=templates"
+```
+
+Both paths are relative to the project root: `from` is a file path or glob and
+`to` is an output directory. This is useful for Node runtime files such as Fastify email
+or response templates: `{ from: "src/templates/**", to: "templates" }` makes
+`src/templates/welcome.txt` available as `dist/templates/welcome.txt`.
+
+Copy destinations must not resolve to the same file as generated output, another
+mapping, or an untracked file already in the output directory. WebAnvil fails
+instead of overwriting in each case.
+
+Node watch mode re-expands copy globs on every rebuild. Changes and deletions to
+currently matched files trigger rebuilds; newly matching files are included on
+the next rebuild.
+
+Web builds keep Vite's `publicDir` behavior unchanged. Do not use `copy` for
+assets imported by application code; Vite continues to manage those assets.
+
+### Test modes
+
+`wa test` runs once by default. Use `--watch` to rerun affected tests after a
+change, `--coverage` to write V8 coverage reports, or `--ui` to start the
+Vitest UI:
+
+```sh
+wa test --watch
+wa test --coverage
+wa test --ui
+wa test --ui --ui-port 51204
+```
+
+These are run-specific modes; keep persistent Vitest configuration in
+`vitest.config.*`. `--ui-port` selects a strict loopback port and requires
+`--ui`.
+
+### Cleaning build output
+
+`wa build` records the actual emitted and copied files in
+`.webanvil/buildinfo.json`. Run `wa clean` to remove only those files across
+every build target; source files and other untracked files stay in place. The
+command leaves `.webanvil/` behind with an empty output list.
+
+Migration
+---------
+
+Start with WebAnvil without rewriting your project configuration. You do not need `webanvil.config.ts` before you can use the unified CLI, and you do not need to translate existing Vite, Vitest, or Oxc settings first.
+
+Install WebAnvil, then replace the project scripts with the WebAnvil commands:
+
+```json
+{
+    "scripts": {
+        "dev": "wa dev",
+        "build": "wa build",
+        "clean": "wa clean",
+        "check": "wa check",
+        "test": "wa test",
+        "lint": "wa lint",
+        "format": "wa format",
+        "typecheck": "wa typecheck"
+    }
+}
+```
+
+For a Node project that follows the defaults, this is enough. WebAnvil reads `src/index.ts`, writes to `dist`, and uses the project's TypeScript configuration when you run `wa typecheck`.
+
+Your existing configuration stays in charge. A `vite.config.*` or
+`vitest.config.*` takes precedence over the matching WebAnvil native block.
+`.oxfmtrc.json` and `.oxlintrc.json` do the same for Oxc. Explicit CLI values
+remain the final run-specific override.
+
+That lets a project standardize on `wa` now and move settings into `webanvil.config.ts` later, one part at a time. Start with a build entry when it makes sense, then bring over test, lint, or format settings as you touch them.
+
+Command reference
+-----------------
+
+| Command                   | Description                                                           | Options                                                                                                                                                           |
+| ------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wa build [entry]`        | Builds with Vite in web mode or Rolldown in Node mode.                | `--mode`, `--out-dir`, `--copy`, `--bundle`, `--no-bundle`, `--formats`, `--declaration`, `--sourcemap`, `--minify`, `--platform`, `--target`                     |
+| `wa clean`                | Removes files emitted by prior WebAnvil builds.                       | No options                                                                                                                                                        |
+| `wa check`                | Checks formatting, linting, and types, stopping on the first failure. | `--fix`                                                                                                                                                           |
+| `wa dev [entry]`          | Starts a Vite server or a full Node build watcher.                    | `--mode`, `--out-dir`, `--host`, `--port`, `--copy`, `--bundle`, `--no-bundle`, `--formats`, `--declaration`, `--sourcemap`, `--minify`, `--platform`, `--target` |
+| `wa preview`              | Serves a Vite production build.                                       | `--out-dir`, `--host`, `--port`, `--open`                                                                                                                         |
+| `wa test [filters...]`    | Runs Vitest once, in watch mode, with coverage, or UI.                | `--environment`, `--watch`, `--coverage`, `--ui`, `--ui-port`                                                                                                     |
+| `wa lint [paths...]`      | Runs Oxlint and treats warnings as failures.                          | `--fix`                                                                                                                                                           |
+| `wa format [paths...]`    | Formats with Oxfmt.                                                   | `--check`                                                                                                                                                         |
+| `wa typecheck [paths...]` | Type-checks with TypeScript Native.                                   | No options                                                                                                                                                        |
+
+Run `wa <command> --help` for the complete reference for a command.

package/bin/webanvil

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import("../dist/cli.mjs").catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/bin/webanvil.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0\..\dist\cli.mjs" %*