gro

tooling · experimental · TypeScript, Rust

gro as this site sees it: what its repo's own files declare, and every record on the coherence and values pages that names it or links it. This page is computed and adds nothing of its own. For what the project is, see the Fuz stack page.

What uses it

The stack repos that declare a dependency on it. A breaking change has to be carried through each of them, and through any consumer that no manifest declares. Only the stack's own projects are listed, so a consumer outside the stack is not here.

Used byKindDeclared inThrough
fuz_blog peerpackage.json@fuzdev/gro
fuz_repos peerpackage.json@fuzdev/gro
fuz_ui optional peerpackage.json@fuzdev/gro
blake3 devpackage.json@fuzdev/gro
corpora devpackage.json@fuzdev/gro
fuz-stack (docs.fuz.dev)devpackage.json@fuzdev/gro
fuz_app devpackage.json@fuzdev/gro
fuz_code devpackage.json@fuzdev/gro
fuz_css devpackage.json@fuzdev/gro
fuz_forge devpackage.json@fuzdev/gro
fuz_schema devpackage.json@fuzdev/gro
fuz_template devpackage.json@fuzdev/gro
fuz_util devpackage.json@fuzdev/gro
mdz devpackage.json@fuzdev/gro
pglet devpackage.json@fuzdev/gro
svelte-docinfo devpackage.json@fuzdev/gro
tsv devpackage.json@fuzdev/gro
tsv (tsv.fuz.dev)devpackage.json@fuzdev/gro
zap devpackage.json@fuzdev/gro
zzz devpackage.json@fuzdev/gro

What it uses

UsesKindDeclared inThrough
tsv runtimeCargo.toml(registry)tsv_ts
tsv runtimepackage.json@fuzdev/tsv
blake3 peerpackage.json@fuzdev/blake3-wasm
fuz_schema peerpackage.json@fuzdev/fuz_schema
fuz_util peerpackage.json@fuzdev/fuz_util
svelte-docinfo optional peerpackage.jsonsvelte-docinfo
fuz_code devpackage.json@fuzdev/fuz_code
fuz_css devpackage.json@fuzdev/fuz_css
fuz_ui devpackage.json@fuzdev/fuz_ui
mdz devpackage.json@fuzdev/mdz

Read from the repos' manifests on . Only each repo's root manifests are read. A manifest shows what a repo declares, which is not always what its code imports, and a dependency that no manifest states, such as a sibling checkout a test reads, is not here. The kind is the manifest table a dependency is declared in, not how much it matters: an app that bundles what it builds declares everything as dev. See every dependency in the stack.

What it declares from outside the stack

runtime
Cargo.toml: argh, blake3, deno_core, deno_web, deno_webidl, getrandom, landlock, libc, seccompiler, serde, serde_json, thiserror, tokio, url, v8
package.json: chokidar, dotenv
peer
package.json: svelte, typescript
optional peer
package.json: @sveltejs/kit, vite, vitest

Read from the repo on . What a repo's manifests declare from outside the stack, by name and without versions. The dev tables are left out, so what an app bundles from its dev table is not here. For a Cargo workspace the list is every crate's together, and it is what is declared, not what a release build links. A crate is left out as tooling only when it is named xtask or testing_*, or the release audit marks it dev-only, so what a bench, debug or test-support crate under another name uses is listed with the rest. See everything the stack declares.

Its check script and CI

The check script of its package.json:

gro check

Its CLAUDE.md has no line in a code block that gives gro check or npm run check with a # comment, and none whose comment says to run it before committing. It may describe its checks another way.

It is among the repos whose check script runs gro check; with a CI step, on a push or a pull request, that runs gro check with --workspace; with an exports map in package.json, and a CI step, on a push or a pull request, that runs gro check with --workspace; with a CI step, on a push or a pull request, that runs gro check with --build; with a Cargo workspace at the root.

.github/workflows/check.yml runs on push (branches main), pull_request (branches **), workflow_dispatch

build on ubuntu-latest

  1. uses actions/checkout, pinned to a commit
  2. Use Node.js ${{ matrix.node-version }}
    uses actions/setup-node, pinned to a commit
  3. npm ci
  4. npm run bootstrap
  5. npx @fuzdev/gro check --workspace --build
  6. Install Rust
    rustup toolchain install --no-self-update
    rustup show active-toolchain
    cargo --version
  7. uses Swatinem/rust-cache, pinned to a commit
  8. Check the JS/TS under crates/
    cargo xtask check-js

rust on ubuntu-24.04

  1. uses actions/checkout, pinned to a commit
  2. Install Rust
    rustup toolchain install --no-self-update
    rustup show active-toolchain
    cargo --version
  3. uses Swatinem/rust-cache, pinned to a commit
  4. Check
    sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
    cargo xtask check-rust

reproducible on ubuntu-24.04

  1. uses actions/checkout, pinned to a commit
  2. Install Rust
    rustup toolchain install --no-self-update
    rustup show active-toolchain
    cargo --version
  3. uses Swatinem/rust-cache, pinned to a commit
  4. Check that fgro builds reproducibly
    env -u CARGO_INCREMENTAL cargo xtask check-reproducible
.github/workflows/release.yml runs on push (tags fgro-v*), workflow_dispatch

build on ubuntu-24.04

  1. uses actions/checkout, pinned to a commit
  2. Install Rust
    rustup toolchain install --no-self-update
    rustup show active-toolchain
    cargo --version
  3. Move to the neutral paths
    if [ -e "$BUILD_ROOT" ]; then
      echo "::error::$BUILD_ROOT already exists on this runner"
      exit 1
    fi
    sudo install -d -o "$(id -u)" -g "$(id -g)" -m 755 "$BUILD_ROOT"
    cp -a "$GITHUB_WORKSPACE" "$BUILD_ROOT/gro"
    mkdir "$BUILD_ROOT/cargo"
    echo "CARGO_HOME=$BUILD_ROOT/cargo" >> "$GITHUB_ENV"
  4. Refuse a tag that isn't the workspace version
    version=$(cargo metadata --locked --no-deps --format-version 1 \
      | jq -r '.packages[] | select(.name == "gro_cli") | .version')
    if [ -z "$version" ]; then
      echo "::error::no gro_cli version in Cargo.toml"
      exit 1
    fi
    if [ "$GITHUB_EVENT_NAME" != push ]; then
      echo "::notice::a $GITHUB_EVENT_NAME run on $GITHUB_REF has no tag: the tag check is skipped, not passed (workspace version $version)"
    elif [ "$GITHUB_REF_NAME" != "fgro-v$version" ]; then
      echo "::error::the tag '$GITHUB_REF_NAME' isn't 'fgro-v' + the workspace version '$version' in Cargo.toml"
      exit 1
    fi
    echo "VERSION=$version" >> "$GITHUB_ENV"
  5. Fetch V8
    cargo xtask fetch-v8
  6. Build and verify
    sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
    cargo xtask build --release --verify
  7. Check the version line
    line=$(target/gro_snapshot/release/fgro --version)
    echo "$line"
    case "$line" in
      "fgro $VERSION (commit $GITHUB_SHA, "*", snapshot)") ;;
      *)
        echo "::error::expected 'fgro $VERSION (commit $GITHUB_SHA, …, snapshot)'"
        exit 1
        ;;
    esac
  8. Check for builder paths
    export LC_ALL=C
    binary=target/gro_snapshot/release/fgro
    prefix="$BUILD_ROOT/"
    roots=(/home/ /Users/ /root/ /.cargo/ /.rustup/)
    for dir in "$HOME" "$GITHUB_WORKSPACE" "$RUNNER_TEMP" "$RUNNER_TOOL_CACHE"; do
      dir=${dir%/}
      if [ -n "$dir" ]; then roots+=("$dir/"); fi
    done
    # the prefix must be there, so a scan that read nothing fails
    if ! grep -qaF -- "$prefix" "$binary"; then
      echo "::error::the binary holds no path under $prefix: the build didn't run from it, or the scan failed"
      exit 1
    fi
    leaks=$(
      {
        { grep -aobF -- "$prefix" "$binary" || true; } | awk -F: '{ print "P\t" $1 }'
        for root in "${roots[@]}"; do
          { grep -aobF -- "$root" "$binary" || true; } | awk -F: -v root="$root" '{ print "R\t" $1 "\t" root }'
        done
      } | awk -F '\t' -v prefix="$prefix" '
        $1 == "P" { in_prefix[$2] = 1; next }
        {
          offset = $2; root = $3; excused = 0
          for (k = 1; k + length(root) - 1 <= length(prefix); k++) {
            if (substr(prefix, k, length(root)) == root && (offset - k + 1) in in_prefix) {
              excused = 1
              break
            }
          }
          if (!excused) print offset "\t" root
        }
      ' | sort -n -u
    )
    escaped=$(printf '%s' "$prefix" | sed 's/[][\\.*^$+?(){}|]/\\&/g')
    echo "paths under $prefix in the binary, by their first two components:"
    grep -aoE -- "$escaped[A-Za-z0-9._-]+/[A-Za-z0-9._-]+" "$binary" | sort | uniq -c || true
    if [ -n "$leaks" ]; then
      echo "::error::the binary contains builder paths outside $prefix"
      head -n 10 <<<"$leaks" | while IFS=$'\t' read -r offset root; do
        printf '%s at byte %s: ' "$root" "$offset"
        { tail -c "+$((offset + 1))" "$binary" || true; } | head -c 160 | tr -c '[:print:]' '?'
        echo
      done
      exit 1
    fi
  9. Stage the asset
    mkdir -p "$RUNNER_TEMP/asset"
    cp target/gro_snapshot/release/fgro "$RUNNER_TEMP/asset/fgro-linux-x64-gnu"
    sha512=$(sha512sum "$RUNNER_TEMP/asset/fgro-linux-x64-gnu" | cut -d ' ' -f 1)
    echo "sha512=$sha512" >> "$GITHUB_OUTPUT"
    echo "$sha512  fgro-linux-x64-gnu"
  10. uses actions/upload-artifact, pinned to a commit

release on ubuntu-24.04, if github.event_name == 'push' && github.ref_type == 'tag'

  1. uses actions/checkout, pinned to a commit
  2. uses actions/download-artifact, pinned to a commit
  3. Check the digest and write SHA512SUMS
    downloaded=$(sha512sum fgro-linux-x64-gnu | cut -d ' ' -f 1)
    if [ -z "$BUILT_SHA512" ] || [ "$downloaded" != "$BUILT_SHA512" ]; then
      echo "::error::the downloaded binary's SHA-512 '$downloaded' isn't the build job's '$BUILT_SHA512'"
      exit 1
    fi
    sha512sum fgro-linux-x64-gnu > SHA512SUMS
    cat SHA512SUMS
  4. Release notes
    version=${GITHUB_REF_NAME#fgro-v}
    notes="$RUNNER_TEMP/release_notes.md"
    awk -v heading="## $version" '
      $0 == heading { found = 1; next }
      found && /^## / { exit }
      found { print }
    ' crates/CHANGELOG.md | sed -e '/./,$!d' > "$notes"
    if ! grep -q '[^[:space:]]' "$notes"; then
      echo "::error::crates/CHANGELOG.md has no '## $version' section, or it's empty"
      exit 1
    fi
    {
      echo
      echo "Linux x86_64 only, built on Ubuntu 24.04, so it needs glibc 2.39 or later (not Debian 12 or Ubuntu 22.04)."
      echo "To verify and install it, see [install](https://github.com/$GITHUB_REPOSITORY/blob/$GITHUB_REF_NAME/src/docs/runtime.md#install)."
    } >> "$notes"
    cat "$notes"
  5. Attest build provenance
    uses actions/attest-build-provenance, pinned to a commit
  6. Create the GitHub Release
    version=${GITHUB_REF_NAME#fgro-v}
    prerelease=()
    case "$version" in *-*) prerelease=(--prerelease) ;; esac
    gh release create "$GITHUB_REF_NAME" \
      "$RUNNER_TEMP/assets/fgro-linux-x64-gnu" "$RUNNER_TEMP/assets/SHA512SUMS" \
      --verify-tag --title "fgro $version" \
      --notes-file "$RUNNER_TEMP/release_notes.md" \
      "${prerelease[@]}"

Read from the repo on . A workflow's jobs and steps are as the file writes them: a step's command, or the action it uses without its version. An action's inputs, a matrix's values, permissions, environment and working directories are left out, and nothing here says which command is the gate. A line is quoted when it sits in a code block of the repo's CLAUDE.md, has a # comment after the command, and either is the command gro check or npm run check, or has a comment that says to run it before committing. A repo that describes its check command in a sentence or a list, or in another file, has no line here. Every file is read at the repo's main branch as the checkout last fetched it, so nothing uncommitted or unpushed is here. See every repo's checks.

Holds that name it

Comparisons that name it

ComparedAgainstKindRunsSource
gro's Rust runtime, built-in modulesgro's Node implementationsTwin
Every change
Rust workspace
gro's module resolverNode's resolutionReference
Every change
departures from Node
gro's release binaryThe same commit built at another pathBuild
CI
Rust workspace

From Oracles in use.

Gates

  • Types, tests, lints and format (every change): Type errors, regressions, lint errors and style drift. Where: The repos whose check script runs gro's check, with lints where the repo has a lint config. pglet's check script reaches it through a script of its own, for its TypeScript.
  • Drift in generated files (every change): A generated file that no longer matches its source. Where: The repos whose check script runs gro's check, and pglet's TypeScript the same way.
  • A budget for the startup snapshot (every change): A startup snapshot that has grown past its committed budget. Where: gro.
  • Drift in the package exports map (ci): An exports map that no longer matches the source, which the local gate rewrites instead of failing on. Where: The repos with an exports map whose CI runs gro's check with its workspace flag.
  • Build (ci): A broken build. Where: The repos whose CI runs gro's check with its build flag.
  • A clean tree after the run, and no TODO docs at the root (ci): Uncommitted output and a TODO Markdown file at the repo root. Where: The repos whose CI runs gro's check with its workspace flag.
  • Wall time and instruction counts against a base (on demand): A performance regression: tsv fails a row past a committed percentage, and gro asks for a written reason. Where: gro and tsv.
  • zap's CI has no build of gro's runtime, so the tests that evaluate config through it are skipped there, by an explicit allowance

From Gates. A gate is listed here when its row names the project or links its repo, or speaks of a class of repos that the snapshot puts this one in.

Actions kept with a person

  • Push a tag, which starts a release in CI for tsv and gro (tool refuses, permission rule, dry run by default): The push tool never sends a tag, and raw pushes are denied. The release script of tsv pushes its own tag, and changes nothing without an explicit flag.
  • Publish a package (permission rule, dry run by default, written rule): The harness denies the publish commands, in settings that are not public. The release scripts of tsv, pglet and blake3 change nothing without an explicit flag, which a session could pass. The publish task of gro and the release task of fuz_forge have no such default.
  • Deploy a site or a server (permission rule, dry run by default, written rule): The harness denies the site deploy command, in settings that are not public, and the deploy task of gro has no dry default. A server deploy through zap changes nothing without an explicit flag and runs only a plan it has already previewed, which a session can do itself, so there the written rule is what holds.

From Actions kept with a person.

Values

The order gro states its priorities in, highest first (gro's runtime design):

  1. security
  2. web standards
  3. developer control and ergonomics
  4. speed, startup first
  5. binary size, memory

Over every choice: simple and small.

  • A decision: speed over security. One realm, mutable intrinsics and the JIT on by default. Cost: Some hardening, which an opt-in tier listed as future work would give back. runtime design
  • Passes the question of security: gro's authority model, where the network is an import and no global carries authority
  • Passes the question of controllability: At the boundary: gro's host modules, where a root imports authority, narrows it and hands it down
  • Passes the question of simplicity: gro's design, where staying simple and small is what keeps the surface small enough to audit
  • Where the stack falls short of security: gro's runtime says its security is not finished, and fuz_forge says its security is not ready to be trusted.
  • Where the stack falls short of controllability: That library code takes its effects as parameters is a written rule, tested only over a named list of gro's own modules, and gro's policy file, the reviewable record of what a project may reach, is designed and not built.
  • A context: A short command, called in a loop. Short-lived runs dominate a loop an agent drives, so the start counts before the steady state. gro's runtime design
  • Cited for how claims are made: gro's design, where the wins are startup, loading, caching and work avoided
  • What a reader can verify, reproducible builds: gro's snapshot build of fgro is reproducible from any path, given the same toolchain and cargo home
  • What a reader can verify, reproducible builds: The comparison that holds gro's build in CI is a row of the oracle table

From the values page.