# Build Tools

## Overview

This article is maintainer-facing.

`shiny.webawesome` uses a small set of top-level build tools under
`tools/` to implement the documented package workflow.

These tools are the operational entry points for the repository’s
generator, runtime-pruning, reporting, finalize, and website-build
steps.

This article is a practical companion to the authoritative workflow
documentation in `projectdocs/`. It describes the tool entry points and
how they fit together, but it does not replace the project workflow
docs.

All top-level tool entry points support `--help` (and `-h`) to print a
summary of their command-line options.

## Core Build Stages

The core reproducible package-build stages map closely to the documented
pipeline through `report`:

- `clean_webawesome()`
- `fetch_webawesome()`
- `prune_webawesome()`
- `generate_components()`
- `report_components()`
- `check_integrity()`

### `clean_webawesome()`

Removes generated artifacts and build outputs.

Use `clean_webawesome()` for the ordinary clean stage and `distclean`
when you also want to remove fetched upstream inputs. The clean stage
also removes the generated site output under `website/`.

### `fetch_webawesome()`

Fetches the pinned upstream Web Awesome npm package, extracts the
browser-ready `dist-cdn/` tree, and stores it under
`vendor/webawesome/<version>/`.

This tool uses `npm` by default. If the desired executable is not
already on `PATH`, set `SHINY_WEBAWESOME_NPM` to the executable that
should be run.

By default, the version comes from `dev/webawesome-version.txt`.

### `prune_webawesome()`

Builds the pruned runtime bundle under `inst/www/wa/` and copies the
metadata inputs needed for generation into `inst/extdata/webawesome/`.

This stage is also responsible for prune-stage diagnostics and its
integrity record.

### `generate_components()`

Builds the component schema from `custom-elements.json` and emits:

- generated wrappers under `R/`
- generated bindings under `inst/bindings/`
- generated update helpers where supported

This stage now also records generate-stage integrity output.

### `report_components()`

Builds deterministic manifests and human-readable reports describing:

- generated-file integrity
- component coverage
- API conformance
- handwritten package API inventory

This stage is the structural diagnostics and reporting boundary. It is
not the late-stage release-preparation step.

### `check_integrity()`

Runs the final integrity gate over the recorded build surfaces.

This tool remains the hard integrity gate for the current generated
surfaces, and it is also invoked by the later `finalize_package.R`
workflow.

## Late-Stage Release Preparation

### `finalize_package.R`

Runs the recurring late-stage local release-preparation workflow.

This tool performs the documented finalize sequence, including:

- stale handoff cleanup
- integrity checking via `check_integrity()`
- dry-run style and lint checks
- dependency auditing
- package tests
- advisory package test coverage reporting
- package documentation regeneration
- site building plus local website link auditing with `lychee`
- package URL auditing without auto-updating links, with package-owned
  website URLs validated against the built local site artifact
- package checking
- tarball creation
- finalize handoff reporting under `manifests/finalize/` and
  `reports/finalize/`

The finalize workflow supports iterative default mode and a stricter
`--strict` release-preparation mode.

Strict clean-start enforcement belongs to the full `build_package.R`
orchestrator, not to `finalize_package.R` itself. Strict finalize is the
late-stage gate that runs after the earlier build stages have already
recreated the package-owned generated surfaces.

The finalize workflow also checks handwritten JavaScript with ESLint.
That means the developer environment should have ESLint, which in turn
requires Node.js and npm, available before finalize is treated as
ready-to-run. Use the manual setup command:

`npm install --save-dev eslint@latest @eslint/js@latest`

Strict finalize also expects the website link checker `lychee` to be
available so the built local `website/` tree can be audited before
release. Do not use the snap package for this repository. Its filesystem
confinement prevents `lychee` from auditing the repo’s built site
reliably. Instead, download a pre-built `lychee` binary from:

<https://github.com/lycheeverse/lychee/releases>

and, if it is not already on `PATH`, point the workflow at it
explicitly:

`export SHINY_WEBAWESOME_LYCHEE=/path/to/lychee`

External pre-release checks such as `rhub` and the final manual visual
review remain outside the automatic finalize execution path. In strict
mode, `finalize_package.R` requires explicit confirmation flags for
those checks. The repository’s representative manual visual review app
is launched with:

`./tools/check_interactive.R`

The repository’s helper for launching external R-hub checks from the
current git branch is:

`./tools/check_rhub.R`

## Orchestration Tools

The top-level orchestrators are intentionally explicit rather than
collapsing multiple responsibilities into one opaque release command.

### `build_tools.R`

Runs the source-level tool workflow by orchestrating:

- tool tests
- tool documentation generation

This is the prerequisite workflow for the tooling surface itself.

### `build_package.R`

Runs `build_tools.R` first by default, then executes the currently
available package build-stage scripts in sequence.

At the current stage of the repository, that sequence includes the
package build stages through `finalize`, including fetch, prune,
generate, binding-candidate review, report, integrity checking, and
finalize.

`build_package.R` does not own publish. The release publication step
remains separate so git tagging, pushing, and website deployment happen
only when the maintainer explicitly decides the repository is ready to
put out.

When invoked with `--finalize-strict`, `build_package.R` is the entry
point that should enforce a clean release-build starting state. It also
passes the external strict-finalize confirmation flags through to
`finalize_package.R`: `--confirmed-rhub-pass` and
`--confirmed-visual-review`.

## Website Tool

### `build_site.R`

Builds the pkgdown documentation site using the checked-in
`_pkgdown.yml` configuration and writes output to the configured
destination, currently `website/`.

When generated tool docs are present, this step also copies them into
`website/tool-docs/`. When source apps are present under
`vignettes/shinylive-examples/`, it can also publish matching standalone
live-demo targets under `website/live-examples/` when invoked with
`--with-live-examples`. If `shinylive` export emits warnings, the site
build writes a placeholder page instead of publishing a likely-broken
demo shell. It also audits the built local site links with `lychee`;
missing `lychee` produces a warning in ordinary runs and a hard failure
when `--strict-link-audit` is requested. Do not use the snap package
here; use a pre-built release binary instead, and set
`SHINY_WEBAWESOME_LYCHEE` to the executable that should be run if that
binary is not already on `PATH`.

This tool is intentionally separate from `build_package.R`. The
docs-site workflow is maintainership-facing and may evolve on a
different cadence from the core package-build stages.

## Publish Tool

### `publish.R`

Runs the explicit maintainer-invoked `publish` stage after `finalize`.

This tool is intentionally separate from `build_package.R`. That
separation is deliberate: `build_package.R` is the recurring local
package-build orchestrator, while publish is the explicit maintainer
release action. Keeping publish outside the package-build orchestrator
ensures that git tagging, pushing, and website deployment happen only
when the maintainer decides the repository is ready to put out.

The publish tool verifies the recorded finalize handoff against the
current repo state and then performs only the action groups explicitly
requested at the CLI. Its core checks include:

- release version consistency against `DESCRIPTION` and `NEWS.md`
- finalize handoff presence and status
- clean git working tree
- current `HEAD` and tracked-tree checksum matching the handoff
- tarball and built `website/` artifact checksum matching the handoff
- branch and tag readiness checks
- website deployment readiness checks when site deployment is requested

The publish tool currently supports:

- `--dry-run` for verification-only readiness checks
- `--do-tag` to create and push the release tag and current branch
- `--deploy-site` to deploy the already-built `website/` artifact

`--dry-run` is verification-only even when `--do-tag` or `--deploy-site`
are also supplied. In that mode, publish records the requested actions
as planned but does not execute them.

The publish tool writes machine-readable and human-readable outputs
under:

- `manifests/publish/`
- `reports/publish/`

### `deploy_site_netlify.R`

The publish tool delegates site deployment to the dedicated Netlify
wrapper:

`./tools/deploy_site_netlify.R`

This wrapper keeps site deployment explicit and narrow. In `--dry-run`
mode, it verifies local website output, checks Netlify authentication,
and confirms that the configured site id is visible to the authenticated
account. In a real run, it then deploys the already-built `website/`
artifact with the Netlify CLI.

This tool requires the Netlify CLI. Install it manually with:

`sudo npm install -g netlify-cli`

The Netlify wrapper currently expects these environment variables:

- `NETLIFY_AUTH_TOKEN`
- `NETLIFY_SITE_ID`

Place those exports somewhere your shell session loads before you run
publish or the deploy helper. A login-shell startup file such as
`~/.profile` is usually a better fit than placing them late in an
interactive `~/.bashrc`.

Typical setup:

``` bash
export NETLIFY_AUTH_TOKEN=...
export NETLIFY_SITE_ID=...
```

Typical dry-run checks:

``` bash
./tools/deploy_site_netlify.R --dry-run
./tools/publish.R --release-version 1.0.0 --dry-run --deploy-site
```

## Tool Documentation

Generated tool documentation lives under `tools/man/`.

In the website build, the generated HTML tool docs are copied into
`tool-docs/`.

Useful entry points include:

- [`build_package`](https://www.shiny-webawesome.org/tool-docs/build_package.md)
- [`build_site`](https://www.shiny-webawesome.org/tool-docs/build_site.md)
- [`build_tools`](https://www.shiny-webawesome.org/tool-docs/build_tools.md)
- [`check_integrity`](https://www.shiny-webawesome.org/tool-docs/check_integrity.md)
- [`check_interactive`](https://www.shiny-webawesome.org/tool-docs/check_interactive.md)
- [`check_rhub`](https://www.shiny-webawesome.org/tool-docs/check_rhub.md)
- [`clean_webawesome`](https://www.shiny-webawesome.org/tool-docs/clean_webawesome.md)
- [`document_tools`](https://www.shiny-webawesome.org/tool-docs/document_tools.md)
- [`deploy_site_netlify`](https://www.shiny-webawesome.org/tool-docs/deploy_site_netlify.md)
- [`fetch_webawesome`](https://www.shiny-webawesome.org/tool-docs/fetch_webawesome.md)
- [`finalize_package`](https://www.shiny-webawesome.org/tool-docs/finalize_package.md)
- [`publish`](https://www.shiny-webawesome.org/tool-docs/publish.md)
- [`prune_webawesome`](https://www.shiny-webawesome.org/tool-docs/prune_webawesome.md)
- [`report_components`](https://www.shiny-webawesome.org/tool-docs/report_components.md)
- [`review_binding_candidates`](https://www.shiny-webawesome.org/tool-docs/review_binding_candidates.md)
- [`test_tools`](https://www.shiny-webawesome.org/tool-docs/test_tools.md)

These generated docs are useful when you need the CLI and function-level
details for a specific tool.

## Notes for Maintainers

This article complements the authoritative project docs under
`projectdocs/`, especially:

- `projectdocs/workflow/build-pipeline.md`
- `projectdocs/workflow/agent-development-playbook.md`

If the implemented tool entry points, stage boundaries, or orchestrators
change, update both:

- the relevant tool documentation
- the authoritative workflow docs in `projectdocs/`
- this maintainer-facing article so it remains consistent with the
  actual orchestrators and entry points