This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Tools

Tools tree

This tree contains tools used inside the repository. All tracked content follows the repository’s public-source policy.

  • Bazel targets MUST use repository-internal visibility except for toolchain types whose owner explicitly exposes a public build API.
  • Tool artifacts MUST NOT be published as first-party product artifacts.
  • Tool targets MUST NOT be used as dependencies of production build targets.
  • Tool targets intended for repository-wide use MUST use visibility = ["//:__subpackages__"].
  • Tool targets MAY be used in tests and explicit source-generation/update targets.

An explicit source-generation/update target is a developer workflow, not part of the production build graph. It may depend on a tool from this tree and use write_source_file to update a checked-in source artifact. Normal production and documentation targets must consume that checked-in artifact directly; they must not depend on the generator, its tool, or an action-generated copy.

1 -

Bazel session cleanup

The repository’s .codex/config.toml queues asynchronous Bazel expunge when a Codex session ends. Review and trust the hook with /hooks in Codex; project hooks do not run until trusted. A completed assistant turn does not trigger cleanup.

If /hooks is empty in a linked Git worktree, check the primary checkout’s .codex/config.toml. In Codex CLI 0.153.4, observed on 2026-09-06, config/read returned the primary checkout’s configuration even though its project-layer metadata named the linked worktree. That primary configuration had no hooks, so hooks/list returned an empty list. The exact worktree TOML listed both hooks in an isolated normal checkout; separate user-config probes also accepted both TOML and JSON. Changing formats is therefore not an established fix. Merge the hook configuration and update the primary checkout, then start a new CLI session and check /hooks to trust it. Recheck configuration resolution after upgrading Codex; this is an observed version-specific behavior, not a guarantee for every release.

The shell hook launches a transient user systemd service, which runs bazel --noblock_for_lock clean --config=agent --expunge_async in each built, tracked Bazel workspace in the linked Git worktree. It skips the primary checkout, submodules, workspaces without a bazel-out symlink, and busy Bazel instances. Source files, Git worktrees, and shared disk caches are preserved. Nested workspaces are discovered from tracked MODULE.bazel, WORKSPACE, and WORKSPACE.bazel files. Custom convenience-symlink prefixes are not supported.

This Linux hook requires Bash, Git, Bazelisk’s bazel on PATH, and a running user systemd manager. The service inherits PATH, not the session’s full environment. KillMode=process allows Bazel’s asynchronous deletion child to finish after the service exits. Failures appear in the user journal; failure to enqueue is reported by Codex as a hook failure. There is no automatic retry or orphan-cache sweep. Concurrent sessions sharing a worktree may lose warm build state when one ends; the Bazel lock protects running builds, not idle sessions. Resuming a cleaned session rebuilds its outputs normally.

The hook uses shell because it must run from a fresh checkout without first building a helper. It invokes Bazel directly to supply the startup lock flag, which bazel_agent does not currently accept. Tests replace Git, systemd, and Bazel with fixtures and never clean real caches.

Codex’s SessionEnd hook is synchronous even with async: true and permits at most three seconds. Systemd owns the longer-running cleanup; the hook does not wait for it. See the Codex hook documentation.

2 - Agent control contracts

Repository-internal shared contracts for agent-system composition

Agent control contracts

This project owns the repository-internal shared vocabulary used to compose agent-system declarations and derived catalogs. It does not own component payload schemas, user authority, runtime observations, or generated catalogs.

The initial api/v1alpha1 package defines stable references, atomic effects, authority and budget envelopes, independent path-policy axes, information and retention classes, availability reasons, evidence applicability, and the common operation and artifact envelopes. Validation fails closed for unknown effects and malformed identities. JSON decoding is strict and canonical encoding is deterministic.

The Phase 1 registry names the closed registration authorities, declares skill metadata and supported direct binaries, links owner-local operation files, and records generated-artifact ownership. Run the report-only completeness check with:

bazel_agent bazel run //tools/agents/cmd/phase1_check -- \
  --workspace-root "$PWD" \
  --report out/<task>/phase1-report.json

The adjacent criteria-revision-bound resource baseline records numeric ceilings separately from observations. Unavailable observations carry a reason instead of an estimate.

Project roots use exactly one lifecycle value from active, in_progress, maintenance, experimental, finished, or abandoned. These values describe project maintenance state; they do not imply publication or information policy.

The topology compiler derives a deterministic, offline TopologyCatalog from the registered projects/* universe, top-level boundary READMEs, and tracked MODULE.bazel roots. The portable JSON at tools/agents/catalogs/topology.json is authoritative; the adjacent Markdown renders the same data and states the JSON digest.

Regenerate with:

bazel_agent bazel run //tools/agents/cmd/topology_check:topology_update

Verify the checked artifacts are current with:

bazel_agent bazel test //tools/agents/cmd/topology_check:topology_check_check

The catalog contains no timestamps, absolute checkout paths, or nested authority; every input is bound by a content digest and the catalog digest covers the canonical bytes. Completeness is complete only when every eligible registered project, workspace, and boundary tree is emitted without conflicts or limitations.

The agent_system command emits a bounded offline context capsule for a workspace-relative path or local Bazel label. It joins checked catalogs with the applicable AGENTS.md chain, nearest owner README, and policy source paths. Its digest-bound document links include the nearest package BUILD.bazel or BUILD, include.MODULE.bazel, and workspace MODULE.bazel when present. These locate the source to inspect; they do not select targets. JSON is the default; --markdown or --json=false renders Markdown. Existing symlinks resolve to their canonical workspace paths before ownership and policy selection. Escaping, dangling, or cyclic symlinks are refused; new paths may extend a verified existing parent.

bazel_agent bazel run //tools/agents/cmd/agent_system -- \
  --workspace-root "$PWD" --path projects/agents --markdown

The legacy agent_system_update wrapper also forwards these query flags and does not update tracked files. --task records a caller-supplied task ID; it does not select a goal. Input digests bind accepted catalog and document inputs.

Relative --workspace-root values resolve against BUILD_WORKSPACE_DIRECTORY under bazel run, so --workspace-root . means the source workspace. Outside Bazel they resolve against the current directory. normalize, coverage, and aggregate apply the same rule to relative input, catalog, and output file flags, with optional --workspace-root selecting another base. Absolute file paths retain their meaning; output parent directories must already exist. For example:

bazel_agent bazel run //tools/agents/cmd/agent_system -- aggregate \
  --catalog tools/agents/catalogs/capability.json \
  --input tools/agents/catalogs/skill-cases.json \
  --output out/<task>/coverage.json

The context command observes local Git HEAD and dirty state under the selected workspace, including untracked files and excluding ignored files. The identity.git object separates these observations from optional caller --revision and --dirty-inputs declarations. Without overrides, successful observations populate the existing identity fields; revisionSource and dirtyInputsSource name their basis. Failed Git reads leave git.dirty: null or the revision absent with explicit reasons. Legacy identity fields then retain an input digest and a conservative dirty default, clearly labelled.

Git commands have a combined three-second deadline and a 65,536-byte output limit each, disable optional index writes and fsmonitor hooks, and ignore ambient GIT_* variables. The report contains no changed-path list or Git stderr. Git and catalog reads are separate observations, not an atomic snapshot or proof that generated catalogs match HEAD.

The capsule reports the actual read time, unknown catalog freshness, and partial completeness. It does not observe runtime health, infer authority, resolve effective CODEOWNERS, or associate an unrelated active goal. Its capability list is an inventory of root-workspace and selected-workspace candidates, not task-intent routing or a complete cross-workspace dependency closure. Workspace check phases are references, not instructions to run a broad check.

identity.byteSize measures the complete canonical JSON, including its final newline. --max-bytes caps the selected JSON or Markdown output at 65,536 bytes by default; oversized output fails before writing a partial document. The limit may be set explicitly between 1,024 and 1,048,576 bytes. Verification:

bazel_agent bazel test //tools/agents/cmd/agent_system:agent_system_check

The tools/agents/control package owns the fixed runtime control kernel: per-package states and deadlines, account/lock acquisition, expires-checked leases, and expected-revision asset publication with namespace isolation. It persists an offline-readable packages.json snapshot.

Package registration preserves the caller’s scope, desired revision, and contract hash. Activation deadlines are fixed at registration time; KernelOptions.Deadlines are fixed at kernel creation for packages introduced through Mark. Reading status does not extend those deadlines. Lifecycle transitions do not establish revision identity, so observedRevision remains empty: the current API has no observed revision input.

The control_status command renders the snapshot/asset status for a control root without creating directories or starting a kernel (Markdown with --markdown):

bazel_agent bazel run //tools/agents/cmd/control_status:control_status -- \
  --workspace-root "$PWD" [--markdown]

The JSON healthy field describes the persisted package observations, with healthBasis: persisted-package-snapshot. Ready, degraded, and disabled packages count as healthy, matching the kernel. Missing, empty, malformed, or rejected observations produce healthy: null; consumers must support this unavailable value rather than assuming a boolean is always present. snapshotPath identifies the source. The report’s observedAt is its read time; each package retains the writer’s observationTime.

Freshness is unknown unless the caller supplies a positive duration such as --max-snapshot-age 5m. That bound yields within-age-bound or stale; stale observations make snapshot health unavailable. This is an explicit caller policy, not a heartbeat or runtime liveness guarantee. Live runtime health remains unavailable even when every observation is within the bound. The snapshot format does not identify its writer, so report runtimeId is empty with an unavailable reason. An asset’s runtimeId identifies its publisher only.

Verification:

bazel_agent bazel test //tools/agents/control:all //tools/agents/cmd/control_status:all

3 - Android

Android

4 - Android cmdtools

Android Command Line Tools

5 - Ansible

Bazel rules for ansible

ansible_lint runs ansible-lint from Bazel-managed Python dependencies. A Go test runner exposes the CLI binaries under their hyphenated names, configures writable Ansible paths, and invokes the linter against workspace-relative sources.

Molecule is not integrated yet. The likely path is to add Molecule to these Python requirements and invoke it through a Bazel-native Go runner, but practical scenarios require choosing and provisioning a Molecule driver before any scenarios can run.

6 - Ast-grep

Ast-grep

7 - Bazel configs

Bazel config targets

Targets that pull from the private Harbor registry are disabled by default so repository-wide builds work while Harbor is unavailable. Enable them with --config=harbor when the registry is reachable.

8 - Bazel shell worker

Bazel worker that runs shell commands

8.1 - Bzl

Bazel code

8.1.1 - al_genrule

al_genrule

load("@com_alwaldend_src//tools/shell_worker/main/bzl:al_genrule.bzl", "al_genrule")

al_genrule(test, executable, **kwargs)

Generate al_genrule target

PARAMETERS

Name Description Default Value
test If set, use al_genrule_test False
executable if set, use al_genrule_executable False
kwargs kwargs for the rule none

8.1.2 - al_genrule_rule

al_genrule_executable

load("@com_alwaldend_src//tools/shell_worker/main/bzl:al_genrule_rule.bzl", "al_genrule_executable")

al_genrule_executable(name, srcs, data, outs, cmd, set_flags, shell, tools, worker)

Build executable using shell worker

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Sources, will not be added to runfiles List of labels optional []
data Data, will be added to runfiles List of labels optional []
outs Outputs List of labels; nonconfigurable required
cmd Script to execute String required
set_flags set flags List of strings optional ["-eux"]
shell shell to use String optional "/bin/sh"
tools Tools, will be added to runfiles List of labels optional []
worker Worker binary Label optional "@com_alwaldend_src//tools/shell_worker"

al_genrule_regular

load("@com_alwaldend_src//tools/shell_worker/main/bzl:al_genrule_rule.bzl", "al_genrule_regular")

al_genrule_regular(name, srcs, data, outs, cmd, set_flags, shell, tools, worker)

Build shell worker rule

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Sources, will not be added to runfiles List of labels optional []
data Data, will be added to runfiles List of labels optional []
outs Outputs List of labels; nonconfigurable required
cmd Script to execute String required
set_flags set flags List of strings optional ["-eux"]
shell shell to use String optional "/bin/sh"
tools Tools, will be added to runfiles List of labels optional []
worker Worker binary Label optional "@com_alwaldend_src//tools/shell_worker"

al_genrule_test

load("@com_alwaldend_src//tools/shell_worker/main/bzl:al_genrule_rule.bzl", "al_genrule_test")

al_genrule_test(name, srcs, data, outs, cmd, set_flags, shell, tools, worker)

Test using shell worker

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Sources, will not be added to runfiles List of labels optional []
data Data, will be added to runfiles List of labels optional []
outs Outputs List of labels; nonconfigurable required
cmd Script to execute String required
set_flags set flags List of strings optional ["-eux"]
shell shell to use String optional "/bin/sh"
tools Tools, will be added to runfiles List of labels optional []
worker Worker binary Label optional "@com_alwaldend_src//tools/shell_worker"

9 - Bazelrc

Bazelrc files
bazel run //tools/bazelrc:preset.update

The agent profile must not propagate ambient TEMP, TMP, or TMPDIR values into repository rules, actions, host actions, or tests. Those execution contexts use Bazel-managed temporary storage; host tools own any explicit task/run scratch they require.

Agent tests use Bazel’s normal result cache. Tests that inspect undeclared workspace files must opt out with the no-cache tag.

Agent commands use Bazel’s default lockfile update mode. Review and commit generated lockfile changes with dependency changes. CI retains strict lockfile checking; use --lockfile_mode=error for an explicit reproducibility check.

In the root workspace, lint actions fail on violations. Their failure setting is identical across normal and lint configurations to preserve the analysis cache when switching modes. --config=lint enables the linter aspects and requests only lint reports and skill validation, not ordinary target outputs.

10 - Black

Black

11 - Blender

Blender

12 - Buf

Buf

13 - Buildifier

Buildifier

14 - Bzl

Bazel rules related to Bazel itself

14.1 - Bzl

Bazel code

14.1.1 - al_alias_map

al_alias_map

load("@com_alwaldend_src//tools/bzl/main/bzl:al_alias_map.bzl", "al_alias_map")

al_alias_map(aliases, visibility)

Generate aliases from an alias map

PARAMETERS

Name Description Default Value
aliases alias map, keys are names, values are alias arguments none
visibility default visibility ["//:__subpackages__"]

14.1.2 - al_bzl_generate_repository

al_bzl_generate_repository

load("@com_alwaldend_src//tools/bzl/main/bzl:al_bzl_generate_repository.bzl", "al_bzl_generate_repository")

al_bzl_generate_repository(name, files, repo_mapping)

Generate a repository

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
files Files to generate, keys are paths, values are file contents Dictionary: String -> String optional {}
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).		 Dictionary: String -> String optional

14.1.3 - al_bzl_library_map

al_bzl_library_map

load("@com_alwaldend_src//tools/bzl/main/bzl:al_bzl_library_map.bzl", "al_bzl_library_map")

al_bzl_library_map(name, visibility, libs, deps, **kwargs)

Create bzl_library targets from a map

PARAMETERS

Name Description Default Value
name combined bzl_library target name none
visibility

-

None
libs bzl_library names {}
deps other al_bzl_library_map targets []
kwargs bzl_library kwargs none

14.1.4 - al_bzl_target_doc

al_bzl_target_doc

load("@com_alwaldend_src//tools/bzl/main/bzl:al_bzl_target_doc.bzl", "al_bzl_target_doc")

al_bzl_target_doc(name, visibility, subpackages)

Document bazel targets

PARAMETERS

Name Description Default Value
name target name none
visibility

-

none
subpackages list of subpackages []

14.1.5 - al_genquery_write_to_source_file

al_genquery_write_to_source_file

load("@com_alwaldend_src//tools/bzl/main/bzl:al_genquery_write_to_source_file.bzl", "al_genquery_write_to_source_file")

al_genquery_write_to_source_file(name, expression, scope, var_name, out_file)

Write genquery result to a bzl file

Example:

    al_genquery_write_to_source_file(
        name = "al_bzl_libs",
        expression = """
            filter(
                "^//",
                attr(
                    "srcs",
                    ".{3,}",
                    kind(
                        "bzl_library",
                        deps("//bzl")
                    )
                )
            )
        """,
        out_file = "al_bzl_libs.bzl",
        scope = ["//bzl"],
        var_name = "AL_BZL_LIBS",
    )

PARAMETERS

Name Description Default Value
name name prefix none
expression genquery expression none
scope genquery scope none
var_name variable name in the generated .bzl file none
out_file output bzl file none

15 - Bzlenv

Setup bazel environment

Rules to create a bazel environment which functions similar to venv

  • Adds bazel-built tools to ${PATH}
  • Exports .env

Create env and activate:

. "$(bazel run //tools/bzlenv)"

Activate existing env:

. .bzlenv/bin/activate

Deactivate env:

bzlenv_deactivate

15.1 - Bzl

Bazel code

15.1.1 - al_bzlenv_binary

al_bzlenv_binary

load("@com_alwaldend_src//tools/bzlenv/main/bzl:al_bzlenv_binary.bzl", "al_bzlenv_binary")

al_bzlenv_binary(name, activate, tools)

Dev shell binary

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
activate Activation script Label optional "@com_alwaldend_src//tools/bzlenv/main/sh:activate"
tools Tools, keys are tool names, values are tool labels Dictionary: String -> Label optional {}

16 - Cc

Cc

//:refresh_compile_commands uses the pinned Hedron extractor. Its archive is declared through use_repo_rule and fetched when the extractor’s package is loaded, rather than during module resolution. LLVM toolchain registration remains automatic.

17 - Cloc

Cloc

18 - Cmctl

Cert Manager cmctl

19 - Consul

Consul

19.1 - Gen gossip key

Generate a gossip key and write it to a kv secret

20 - Dart Sass

Dart Sass toolchain

Dart Sass binary toolchain, used by Hugo for toCSS "dartsass" builds.

21 - Dnscontrol

Dnscontrol tool

22 - Drawio

Bazel rules for drawio

drawio_svg in defs.bzl renders named pages from a .drawio file with the pinned Drawio web exporter and the existing pinned Chrome-for-Testing browser. The extraction action unpacks the web application from the Drawio AppImage; rendering uses a small Puppeteer bridge for its export messages. Neither action uses a host display server or accesses the network. JavaScript keeps this adapter close to Drawio’s browser API and the existing Puppeteer dependency.

Use the rule from an explicit source-update target with write_source_files, as in //infra/arch:update. Normal documentation consumes the maintained SVGs, not the rendering tool. The generated freshness tests catch stale output.

Exports use a light theme with an opaque white canvas, keeping labels and connectors readable in both light and dark documentation themes and standalone image viewers. The renderer adds this canvas on every export.

Chrome’s inner sandbox is disabled because it cannot nest within the Bazel Linux sandbox used for these actions. The Bazel sandbox remains enabled; requests outside local files and embedded data are rejected. The renderer is intended for checked-in, reviewed diagram sources and propagates export failures.

The repeat-render test checks byte equality, including stable SVG identifiers. Rendering uses only the declared Liberation Fonts 2.1.5 through an isolated Fontconfig configuration. Helvetica/Arial map to Liberation Sans, Times to Liberation Serif, and Courier to Liberation Mono. The fonts are licensed under the SIL Open Font License 1.1; their archive retains LICENSE.

22.1 - Bzl

Bazel code

22.1.1 - al_drawio_run_binary

al_drawio_run_binary

load("@com_alwaldend_src//tools/drawio/main/bzl:al_drawio_run_binary.bzl", "al_drawio_run_binary")

al_drawio_run_binary(name, srcs, out, arguments, cmd_timeout)

Run drawio a a build action

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Sources List of labels optional []
out Output Label; nonconfigurable required
arguments Arguments, location statements are expanded List of strings required
cmd_timeout Drawio command timeout String optional "1m"

22.1.2 - al_drawio_toolchain

al_drawio_toolchain

load("@com_alwaldend_src//tools/drawio/main/bzl:al_drawio_toolchain.bzl", "al_drawio_toolchain")

al_drawio_toolchain(name, drawio)

Drawio toolchain

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
drawio Drawio binary Label required

23 - File installer

CLI tool to install files

24 - fj

Forgejo CLI

25 - Flake8

Flake8

26 - flux

flux

27 - Flux operator

Flux operator

28 - Forgejo

Forgejo

29 - Gazelle

Repository BUILD file generation

//tools/gazelle:gazelle runs the repository’s Gazelle language plugins. Repository-wide directives remain in root BUILD.bazel, where Gazelle discovers them for all packages. Root //:gazelle and //:gazelle_bin remain compatibility entry points.

//tools/gazelle:gazelle_python_manifest.update refreshes root gazelle_python.yaml; //tools/gazelle:gazelle_python_manifest.test validates its integrity against root requirements.txt. Keeping the manifest at the repository root preserves Python dependency discovery in every package.

30 - Git

Git rules

30.1 - Bzl

Bazel rules

30.1.1 - al_git_binary

al_git_binary

load("@com_alwaldend_src//tools/git/main/bzl:al_git_binary.bzl", "al_git_binary")

al_git_binary(name, arguments)

Run git binary

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
arguments Git arguments (templated) List of strings optional []

30.1.2 - al_git_changelog

al_git_changelog

load("@com_alwaldend_src//tools/git/main/bzl:al_git_changelog.bzl", "al_git_changelog")

al_git_changelog(name, visibility, git_binary, subpackages)

Create changelog target

PARAMETERS

Name Description Default Value
name target name prefix none
visibility visibility none
git_binary

-

"@git//:git"
subpackages subpackages []

30.1.3 - al_git_current_state

30.1.4 - al_git_extension

al_git_extension

al_git_extension = use_extension("@com_alwaldend_src//tools/git/main/bzl:al_git_extension.bzl", "al_git_extension")
al_git_extension.local_git(name)

Create git repos

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Name Name required

30.1.5 - al_git_info_file

al_git_info_file

load("@com_alwaldend_src//tools/git/main/bzl:al_git_info_file.bzl", "al_git_info_file")

al_git_info_file(name, git_state, git_tool, timeout)

Generate git info file

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
git_state Files that should invalidate the cache on new commit List of labels optional []
git_tool Git tool to use Label optional "@com_alwaldend_src//tools/git/main/go"
timeout Timeout in seconds Integer optional 60

30.1.6 - al_git_repo

al_git_repo

load("@com_alwaldend_src//tools/git/main/bzl:al_git_repo.bzl", "al_git_repo")

al_git_repo(name, repo_mapping)

Git repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).		 Dictionary: String -> String optional

30.1.7 - al_git_resolved_toolchain

al_git_resolved_toolchain

load("@com_alwaldend_src//tools/git/main/bzl:al_git_resolved_toolchain.bzl", "al_git_resolved_toolchain")

al_git_resolved_toolchain(name)

Resolved git toolchain

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

30.1.8 - al_git_run_binary

al_git_run_binary

load("@com_alwaldend_src//tools/git/main/bzl:al_git_run_binary.bzl", "al_git_run_binary")

al_git_run_binary(name, srcs, outs, arguments, git)

Run a git binary as a build action

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Files to be made available List of labels optional []
outs Outputs List of labels; nonconfigurable required
arguments Arguments (Location is expanded) List of strings optional []
git Git binary Label required

30.1.9 - al_git_toolchain

al_git_toolchain

load("@com_alwaldend_src//tools/git/main/bzl:al_git_toolchain.bzl", "al_git_toolchain")

al_git_toolchain(name, git_dir, git_path, git_root, invalidation)

Local git toolchain

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
git_dir Git directory path String required
git_path Git binary path String required
git_root Git workspace path String required
invalidation Files that should invalidate git actions List of labels optional []

30.2 - Proto

Protobuf contracts

30.2.1 - contracts

Proto docs for contracts.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/git/main/proto/contracts:contracts_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/git/main/proto/contracts:contracts",
    ],
)

syntax = "proto3";

package git;

option go_package = "git.alwaldend.com/alwaldend/src/tools/git/main/proto/contracts";

message GitSignature {
  string name = 1;
  string email = 2;
  int64 when = 3;
}

message GitCommit {
  string hash = 1;
  GitSignature author = 2;
  GitSignature committer = 3;
  string merge_tag = 4;
  string pgp_signature = 5;
  string message = 6;
  repeated string tags = 7;
  map<string, bool> changed_files = 8;
}

message GitTagAnnotated {
  GitSignature tagger = 1;
  string hash = 2;
  string message = 3;
  string pgp_signature = 4;
}

message GitTag {
  string name = 1;
  string target = 2;
  GitTagAnnotated annotated = 3;
}

message GitRemote {
  string name = 1;
  repeated string urls = 2;
}

message GitInfo {
  map<string, GitCommit> commits = 1;
  repeated string commits_order = 2;
  map<string, GitTag> tags = 3;
  repeated GitRemote remotes = 4;
}

31 - Git filter repo

Git filter repo

32 - Gitea

Gitea

33 - Go

Go rules

33.1 - Bzl

Bazel code

33.1.1 - al_go_repository

al_go_repository

al_go_repository = use_extension("@com_alwaldend_src//tools/go/main/bzl:al_go_repository.bzl", "al_go_repository")
al_go_repository.go_repository(name, importpath, sum, version)

Extension wrapper around go_repository (useless because you can just call use_repo_rule)

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Name Name required
importpath importpath String required
sum checksum String optional ""
version - String required

34 - Gzip

Gzip rules

34.1 - Bzl

Bazel code

34.1.1 - al_gzip_extension

al_gzip_extension

al_gzip_extension = use_extension("@com_alwaldend_src//tools/gzip/main/bzl:al_gzip_extension.bzl", "al_gzip_extension")
al_gzip_extension.download(name, integrity, url)

Extension for gzip repos

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Name Name required
integrity Integrity String optional ""
url Url String required

34.1.2 - al_gzip_repo

al_gzip_repo

load("@com_alwaldend_src//tools/gzip/main/bzl:al_gzip_repo.bzl", "al_gzip_repo")

al_gzip_repo(name, integrity, repo_mapping, url)

Gzip repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
integrity Integrity String optional ""
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).		 Dictionary: String -> String optional
url Url String required

35 - Harbor

Harbor CLI

36 - Helm

Bazel rules for helm

36.1 - Bzl

Bazel code

36.1.1 - al_helm_binary

al_helm_binary

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_binary.bzl", "al_helm_binary")

al_helm_binary(name, data, arguments, cd)

Helm binary

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
data Helm chart List of labels optional []
arguments Helm arguments List of strings optional []
cd Cd to a directory before running bazel String optional "."

36.1.2 - al_helm_chart

al_helm_chart

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_chart.bzl", "al_helm_chart")

al_helm_chart(name, deps, package, source)

Helm chart

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Helm chart deps List of labels optional []
package Helm chart package Label optional None
source Helm chart source Label optional None

36.1.3 - al_helm_chart_info

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_chart_info.bzl", "AlHelmChartInfo")

AlHelmChartInfo(source, package, deps, files_info)

Information about a helm chart

FIELDS

Name Description
source Chart sources (PackageFilegroupInfo, optional)
package Chart package (tgz file)
deps Chart deps (depset of AlHelmChartInfo)
files_info Chart file structure (PackageFilesInfo)

36.1.4 - al_helm_chart_lock

al_helm_chart_lock

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_chart_lock.bzl", "al_helm_chart_lock")

al_helm_chart_lock(name, lock, lock_out)

Generate targets for a chart lock

PARAMETERS

Name Description Default Value
name name none
lock lock label none
lock_out parsed lock filename none

36.1.5 - al_helm_cmds

36.1.6 - al_helm_deps

al_helm_deps

al_helm_deps = use_extension("@com_alwaldend_src//tools/helm/main/bzl:al_helm_deps.bzl", "al_helm_deps")
al_helm_deps.from_locks(name, integrity, locks)

Extension to download helm dependencies

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Repo name Name required
integrity Intergrity for locks, keys are packages, values are integrity Dictionary: String -> String optional {}
locks Helm lock labels List of labels optional []

36.1.7 - al_helm_deps_repo

al_helm_deps_repo

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_deps_repo.bzl", "al_helm_deps_repo")

al_helm_deps_repo(name, integrity, locks, repo_mapping)

Helm deps repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
integrity Intergrity for locks, keys are packages, values are integrity Dictionary: String -> String optional {}
locks Lock labels to parse List of labels optional []
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).		 Dictionary: String -> String optional

36.1.8 - al_helm_toolchain

al_helm_toolchain

load("@com_alwaldend_src//tools/helm/main/bzl:al_helm_toolchain.bzl", "al_helm_toolchain")

al_helm_toolchain(name, helm)

Helm toolchain

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
helm Helm binary Label required

37 - Hermes install

Run the Hermes Agent install script

Run the pinned Hermes Agent install script:

bazel run //tools/hermes_install

38 - Hooks

Git hooks

The hook installer resolves the repository’s effective hooks directory through Git. This supports linked worktrees and repositories that configure core.hooksPath.

The installed pre-commit hook requires bazel_agent. Bootstrap it before installing the hook:

bazel run --config=agent //projects/bazel_agent:install

Install or update the checked-in hooks:

bazel_agent bazel run //:write_git_hooks

Verify that every hook is current and executable without changing it:

bazel_agent bazel run //:write_git_hooks -- test

39 - Http server

Bazel rules for running http.server

39.1 - Bzl

Bazel code

39.1.1 - al_http_server_binary

al_http_server_binary

load("@com_alwaldend_src//tools/http_server/main/bzl:al_http_server_binary.bzl", "al_http_server_binary")

al_http_server_binary(name, srcs, arguments)

Run a http server

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Files to symlink List of labels optional []
arguments Arguments List of strings optional []

40 - Hugo

Hugo toolchain

Hugo binary toolchain for the repository. Build rules live in rules_hugo.

41 - Install file

Bazel rules to install files

41.1 - Bzl

Bazel code

41.1.1 - al_install_file

al_install_file

load("@com_alwaldend_src//tools/install_file/main/bzl:al_install_file.bzl", "al_install_file")

al_install_file(name, args, install_file_label, visibility, **py_binary_kwargs)

Create py_binary target to install file

PARAMETERS

Name Description Default Value
name target name none
args install-file args []
install_file_label

-

"//tools/install_file/main/py:install_file_lib"
visibility

-

["//:__subpackages__"]
py_binary_kwargs

-

none

42 - Isort

Isort

43 - Js

Js

Repository JavaScript tooling dependencies belong to the pnpm workspace in tools/. Its package.json and pnpm-lock.yaml own their requested and resolved versions. //tools:node_modules owns the Bazel package store and links; loading the repository root package does not load the npm extension’s generated rules.

Run pnpm with //tools/pnpm, passing --dir with the absolute path to tools/ for dependency updates. Keep lifecycle scripts disabled (--ignore-scripts) when updating the lockfile.

44 - Kt

Kotlin

45 - kubectl

Kubectl

46 - Lua

Lua rules

46.1 - Bzl

Bazel code

46.1.1 - al_lua_library

al_lua_library

load("@com_alwaldend_src//tools/lua/main/bzl:al_lua_library.bzl", "al_lua_library")

al_lua_library(name, srcs, check, stylua_config_label, stylua_label, pkg_kwargs, visibility)

Generate targets for a lua library

PARAMETERS

Name Description Default Value
name library name none
srcs library sources none
check if set, only these files will be checked []
stylua_config_label

-

"//tools/stylua:stylua_config"
stylua_label

-

"//tools/stylua"
pkg_kwargs

-

{}
visibility visibility ["//:__subpackages__"]

47 - Make install

Rules to create tar archives that can be installed with make

47.1 - Bzl

Bazel code

47.1.1 - al_make_install

al_make_install

load("@com_alwaldend_src//tools/make_install/main/bzl:al_make_install.bzl", "al_make_install")

al_make_install(name, srcs)

Create the make install executable and a filegroup

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Make install filegroups List of labels optional []

47.1.2 - al_make_install_binary

al_make_install_binary

load("@com_alwaldend_src//tools/make_install/main/bzl:al_make_install_binary.bzl", "al_make_install_binary")

al_make_install_binary(name, src, arguments)

Create a binary target for a make install

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src Make install target Label required
arguments Arugments for the executable List of strings optional []

47.1.3 - al_make_install_filegroup

al_make_install_filegroup

load("@com_alwaldend_src//tools/make_install/main/bzl:al_make_install_filegroup.bzl", "al_make_install_filegroup")

al_make_install_filegroup(name, deps, srcs, diff_args, install_args, install_dir, pkg_prefix)

Create a make install filegroup

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Deps List of labels optional []
srcs Sources to install List of labels optional []
diff_args Diff args List of strings optional []
install_args Install args List of strings optional ["--compare", "-D"]
install_dir Install directory String optional "${HOME}"
pkg_prefix Ignore that prefix for srcs String required

47.1.4 - al_make_install_filegroup_info

load("@com_alwaldend_src//tools/make_install/main/bzl:al_make_install_filegroup_info.bzl", "AlMakeInstallFilegroupInfo")

AlMakeInstallFilegroupInfo(srcs, deps, install_dir, origin, install_args, diff_args, pkg_prefix)

Describe install info for a single filegrop

FIELDS

Name Description
srcs depset of PackageFilegroupInfo
deps depset of AlMakeInstallFilegroupInfo
install_dir Install directory
origin Rule label
install_args Args for the install command
diff_args Args for the diff command
pkg_prefix Ignore that prefix for srcs

48 - Md

Md rules

48.1 - Bzl

Bazel code

48.1.1 - al_md_data

al_md_data

load("@com_alwaldend_src//tools/md/main/bzl:al_md_data.bzl", "al_md_data")

al_md_data(name, srcs, deps, **kwargs)

Markdown data backed by a filegroup

Targets:

  • ${name}: filegroup

PARAMETERS

Name Description Default Value
name filegroup name none
srcs markdown files none
deps deps []
kwargs filegroup kwargs none

49 - Mermaid

Bazel-managed Mermaid diagram renderer

This package exposes the Mermaid CLI as a repository-wide Bazel tool. Bazel provisions the pinned Node toolchain, JavaScript dependency graph, Mermaid CLI, and Chrome-for-Testing browser used by Puppeteer. Rendering runs as a Bazel target or action; it does not use a host browser or download one during an npm lifecycle hook.

The JavaScript launcher runs from Bazel’s output tree. Pass absolute paths when rendering source-tree files directly:

repo_root="$PWD"
bazel_agent bazel run //tools/mermaid:mmdc -- \
  -i "${repo_root}/path/to/diagram.mmd" \
  -o "${repo_root}/path/to/diagram.svg"

Prefer a mermaid_svg action plus write_source_file for maintained diagrams; those targets use declared Bazel paths and need no absolute-path handling.

50 - Minisign

Minisign

51 - Mypy

Mypy

52 - Nc

Netcat

53 - Nmap

Nmap

54 - Nogo

Golang static analyser

55 - Nping

Nping - Network packet generation tool & ping utility

56 - Oci

Oci

57 - openbao

Openbao

58 - Opencode

Opencode - The open source AI coding agent

59 - Ops

Ops CLI binary

60 - Oras

Oras rules

61 - Patch

Patch rules

61.1 - Bzl

Bazel code

61.1.1 - al_apply_patches

al_apply_patches

load("@com_alwaldend_src//tools/patch/main/bzl:al_apply_patches.bzl", "al_apply_patches")

al_apply_patches(name, src, patches, visibility, **kwargs)

Create a genrule applying patches

PARAMETERS

Name Description Default Value
name genrule name none
src source archive label none
patches patches label none
visibility visibility ["//:__subpackages__"]
kwargs other genrule kwargs none

62 - Pkg

Package rules

62.1 - Bzl

Bazel code

62.1.1 - al_genrule_src

al_genrule_src

load("@com_alwaldend_src//tools/pkg/main/bzl:al_genrule_src.bzl", "al_genrule_src")

al_genrule_src(name, srcs, visibility)

Create a filegroup and a genrule generating a tar archive

PARAMETERS

Name Description Default Value
name genrule name none
srcs source labels []
visibility

-

["//:__subpackages"]

62.1.2 - al_pkg_basic_naming

al_pkg_basic_naming

load("@com_alwaldend_src//tools/pkg/main/bzl:al_pkg_basic_naming.bzl", "al_pkg_basic_naming")

al_pkg_basic_naming(name, deps)

Variables for @rules_pkg

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Deps to merge List of labels optional []

62.1.3 - al_pkg_extract_dir

al_pkg_extract_dir

load("@com_alwaldend_src//tools/pkg/main/bzl:al_pkg_extract_dir.bzl", "al_pkg_extract_dir")

al_pkg_extract_dir(name, src, out, arguments)

Extract an archive into a TreeArtifact

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src Archive to unpack Label required
out Output directory name String optional ""
arguments Additional arguments List of strings optional []

62.1.4 - al_pkg_tar_combined

al_pkg_tar_combined

load("@com_alwaldend_src//tools/pkg/main/bzl:al_pkg_tar_combined.bzl", "al_pkg_tar_combined")

al_pkg_tar_combined(name, srcs, strip_components, **kwargs)

Create a genrule combining several tars into one

PARAMETERS

Name Description Default Value
name genrule name none
srcs dicts tar archives ({“label”: “tar label”, “dir”: “target dir”}) []
strip_components value of –stip-components 2
kwargs other genrule kwargs none

62.1.5 - al_unpack_archives

al_unpack_archives

load("@com_alwaldend_src//tools/pkg/main/bzl:al_unpack_archives.bzl", "al_unpack_archives")

al_unpack_archives(name, srcs, out)

Unpack several archives using tar into a directory

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs - List of labels required
out - String optional ""

63 - Pkgsite

Pkgsite

64 - Pnpm

Pnpm

65 - Postcss

Postcss

66 - Prettier

Prettier

67 - Print deps

Aspect to print deps

67.1 - Bzl

Bazel code

67.1.1 - al_print_deps

al_print_deps

load("@com_alwaldend_src//tools/print_deps/main/bzl:al_print_deps.bzl", "al_print_deps")

al_print_deps()

ASPECT ATTRIBUTES

Name Type
deps String

ATTRIBUTES

68 - Proto

Protobuf rules

68.1 - Bzl

Bazel code

68.1.1 - al_proto_docs

al_proto_docs

load("@com_alwaldend_src//tools/proto/main/bzl:al_proto_docs.bzl", "al_proto_docs")

al_proto_docs(name, src, prefix, visibility, renames)

Generate protobuf documentation

PARAMETERS

Name Description Default Value
name name none
src protobuf source file none
prefix

-

None
visibility visibility None
renames

-

None

69 - Py

Python rules

The repository Python dependency lock remains in root requirements.txt, next to pyproject.toml. Update it with //tools/py:requirements.update and validate it with //tools/py:requirements.test; the root labels remain compatibility entry points. These upstream pip-tools workflows require network access to resolve and validate package versions and run outside the action sandbox.

69.1 - Bzl

Bazel code

69.1.1 - al_compile_pip_requirements_combined

al_compile_pip_requirements_combined

load("@com_alwaldend_src//tools/py/main/bzl:al_compile_pip_requirements_combined.bzl", "al_compile_pip_requirements_combined")

al_compile_pip_requirements_combined(name, srcs, **kwargs)

Create compile_pip_requirements target for several requirement files

PARAMETERS

Name Description Default Value
name compile_pip_requirements name none
srcs list of labels of requirement files to combine none
kwargs kwargs for compile_pip_requirements none

69.1.2 - al_genrule_with_wheels

al_genrule_with_wheels

load("@com_alwaldend_src//tools/py/main/bzl:al_genrule_with_wheels.bzl", "al_genrule_with_wheels")

al_genrule_with_wheels(name, wheels, srcs, cmd, **kwargs)

Regular genrule with wheels added to ${PYTHONPATH}

PARAMETERS

Name Description Default Value
name genrule name none
wheels list of wheel labels none
srcs srcs for the genrule []
cmd genrule cmd []
kwargs other genrule kwargs none

69.1.3 - al_py_binary_shell

al_py_binary_shell

load("@com_alwaldend_src//tools/py/main/bzl:al_py_binary_shell.bzl", "al_py_binary_shell")

al_py_binary_shell(name, deps, srcs, shell_type, shell_label, **kwargs)

Create a py_binary target that allows you to run commands in proper python environment

PARAMETERS

Name Description Default Value
name target name none
deps py_binary deps []
srcs py_binary srcs []
shell_type ${BAZEL_PYTHON_SHELL_TYPE} "python"
shell_label

-

"//tools/py/main/py:bazel_python_shell_lib"
kwargs other py_binary kwargs none

69.1.4 - al_py_checker

al_py_checker

load("@com_alwaldend_src//tools/py/main/bzl:al_py_checker.bzl", "al_py_checker")

al_py_checker(name, tool, args_bin, args_test, test_size, disable_fix, **kwargs)

Create -fix and -test targets for a python checker

PARAMETERS

Name Description Default Value
name Name prefix None
tool Tool label None
args_bin Args for the binary target None
args_test Args for the test None
test_size

-

"small"
disable_fix If set, do not create fix target False
kwargs Kwargs for both targets none

69.1.5 - al_py_checkers

al_py_checkers

load("@com_alwaldend_src//tools/py/main/bzl:al_py_checkers.bzl", "al_py_checkers")

al_py_checkers(name, srcs, isort_label, black_label, mypy_label, flake8_label, pyproject_label)

Generate -fix and -test targets for python checkers

PARAMETERS

Name Description Default Value
name

-

none
srcs list of source file labels none
isort_label

-

"//tools/isort"
black_label

-

"//tools/black"
mypy_label

-

"//tools/mypy"
flake8_label

-

"//tools/flake8"
pyproject_label

-

"//tools/py:pyproject"

70 - Qt

Qt rules

The module configuration downloads SHA-256-pinned Qt 6.8.3 distributions via rules_qt and registers its build tools. Bazel builds do not require Qt under /opt or another host installation.

70.1 - Bzl

Bazel code

71 - Rclone

Rclone

72 - Readme tree

Tool to parse README.md files
bazel run tools/readme_tree -- parse -g -C "${PWD}" .

73 - Release

Release rules

73.1 - Bzl

Bazel bindings for the release tool

73.1.1 - al_release

al_release

load("@com_alwaldend_src//tools/release/main/bzl:al_release.bzl", "al_release")

al_release(name, srcs, git_bundle, git_state, manifest, project, release_name, release_tool,
           root_prefix)

Rule describing a release

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Sources List of labels optional []
git_bundle Deterministic Git bundle used to generate release metadata Label optional "@com_alwaldend_src_tools_git//:release_git_state"
git_state Additional declared Git state used to generate release metadata List of labels optional []
manifest Load manifest from a file instead of generating it from srcs Label optional None
project Project package_name String required
release_name Release name String required
release_tool Release tool Label optional "@com_alwaldend_src//tools/release/main/go"
root_prefix Root prefix String optional "content/docs"

73.1.2 - al_release_binary

al_release_binary

load("@com_alwaldend_src//tools/release/main/bzl:al_release_binary.bzl", "al_release_binary")

al_release_binary(name, srcs, arguments, cmd, oras, release_tool)

Release binary

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
srcs Releases List of labels optional []
arguments Arguments List of strings optional []
cmd Cmd String optional "deploy"
oras Oras binary Label optional "@com_alwaldend_src//tools/oras"
release_tool Release tool Label optional "@com_alwaldend_src//tools/release/main/go"

73.1.3 - al_release_deployment

al_release_deployment

load("@com_alwaldend_src//tools/release/main/bzl:al_release_deployment.bzl", "al_release_deployment")

al_release_deployment(name, oci_repository)

Deployment info

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
oci_repository OCI repository url String optional ""

73.1.4 - al_release_deployment_info

load("@com_alwaldend_src//tools/release/main/bzl:al_release_deployment_info.bzl", "AlReleaseDeploymentInfo")

AlReleaseDeploymentInfo(info, info_file)

Deployment info

FIELDS

Name Description
info Deployment info struct
info_file Deployment info file

73.1.5 - al_release_deps

al_release_deps

load("@com_alwaldend_src//tools/release/main/bzl:al_release_deps.bzl", "al_release_deps")

al_release_deps(name, srcs, visibility, **kwargs)

Generate a dependency diagram using genquery

PARAMETERS

Name Description Default Value
name name none
srcs list of labels to generate deps for (should be full labels) none
visibility visibility None
kwargs kwargs for al_release_files none

73.1.6 - al_release_files

al_release_files

load("@com_alwaldend_src//tools/release/main/bzl:al_release_files.bzl", "al_release_files")

al_release_files(name, deps, srcs, deployments, ignore_suffixes, release_tool)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Deps List of labels optional []
srcs Sources List of labels optional []
deployments Deployment info List of labels optional []
ignore_suffixes Ignore src files ending with these suffixes List of strings optional []
release_tool Release tool Label optional "@com_alwaldend_src//tools/release/main/go"

73.1.7 - al_release_files_info

load("@com_alwaldend_src//tools/release/main/bzl:al_release_files_info.bzl", "AlReleaseFilesInfo")

AlReleaseFilesInfo(files, manifest)

Release files

FIELDS

Name Description
files File dict, keys are filenames, values are Files
manifest Release manifest for srcs

73.1.8 - al_release_info

load("@com_alwaldend_src//tools/release/main/bzl:al_release_info.bzl", "AlReleaseInfo")

AlReleaseInfo(release_name, project, files, manifest)

Release information

FIELDS

Name Description
release_name Release name (string)
project Project subdir (string)
files File dict, keys are filenames, values are Files
manifest Release manifest (File)

73.2 - Proto

Protobuf contracts

73.2.1 - contracts

Proto docs for contracts.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/release/main/proto/contracts:contracts_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/release/main/proto/contracts:contracts",
    ],
)

syntax = "proto3";

package release;

import "tools/git/main/proto/contracts/contracts.proto";

option go_package = "git.alwaldend.com/alwaldend/src/tools/release/main/proto/contracts";

message ReleaseHash {
  string algo = 1;
  string content = 2;
}

message ReleaseFile {
  repeated ReleaseHash hashes = 1;
  string name = 2;
  string safe_name = 6;
  string url = 3;
  int64 size = 4;
  string local_path = 5;
}

message ReleaseItem {
  ReleaseFile file = 1;
  repeated ReleaseDeployment deployments = 2;
}

message Project {
  string subdir = 1;
  string safe_subdir = 2;
}

message Git {
  git.GitCommit revision = 1;
  repeated git.GitCommit commits = 2;
}

message ReleasePageSectionItemAttr {
  string name = 1;
  string content = 2;
}

message ReleasePageSectionItem {
  string content = 1;
  string content_url = 2;
  repeated ReleasePageSectionItemAttr attrs = 3;
}

message ReleasePageSection {
  string title = 1;
  repeated ReleasePageSectionItem items = 2;
}

message ReleasePage {
  repeated ReleasePageSection sections = 1;
}

message ReleaseDeploymentOci {
  string repository = 1;
  repeated string tags = 2;
}

message ReleaseDeployment {
  ReleaseDeploymentOci oci = 1;
}

message Release {
  repeated ReleaseItem items = 1;
  string name = 2;
  Project project = 3;
  Git git = 4;
}

74 - Replace section

Replace sections of files

75 - Repo map

Extension to download several versions of a repository depending on a platform

75.1 - Bzl

Bazel code

75.1.1 - al_repo_map

al_repo_map

al_repo_map = use_extension("@com_alwaldend_src//tools/repo_map/main/bzl:al_repo_map.bzl", "al_repo_map")
al_repo_map.download(name, build_file_content, build_file_native_binary, download_type, executable,
                     repos, strip_prefix)

Extension to create several repos from a map

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Name Name required
build_file_content Build file content String optional ""
build_file_native_binary Args for a native binary build file Dictionary: String -> String optional {}
download_type Download type String optional "http_archive"
executable Field executable for http_file Boolean optional False
repos Map of repos Dictionary: String -> List of strings required
strip_prefix Strip prefix String optional ""

76 - Repository AL configuration

Shared configuration for repository command wrappers

//tools/al:config packages the repository’s shared AL configuration. The root //:al label remains a compatibility alias. The Lua source files stay at the repository root so existing CLI configuration discovery and require("al_lib") imports retain their paths.

77 - Repository delivery

Guarded Git and pull-request delivery

repo_delivery implements the deterministic part of repository delivery. It invokes native Git and a selected forge CLI; it does not infer task ownership, choose validation commands, resolve conflicts, or judge review feedback.

Run delivery commands from this Git worktree’s repository root, which owns the root MODULE.bazel and tools/repo_delivery. This also applies when changed files belong to a nested Bazel module: its workspace does not own the delivery target. Use the same feature worktree, not another checkout. The baseline works with older installed runners. Detect the provider without printing a credential-bearing remote URL:

bazel_agent bazel run //tools/repo_delivery -- provider

The optional cached form is bazel_agent tool run repo_delivery -- .... Follow the bazel-agent skill’s one-time capability check before using it: reuse the known result for this runner binary, or inspect bazel_agent tool --help once. Unsupported tool means use the baseline without updating the host; an execution failure or delivery refusal still requires diagnosis. All examples below use the baseline.

The sanitized report distinguishes forge support from Git transport support. adapter_available reports whether the forge has an adapter; git_transport reports ssh, https, or mixed_or_unsupported; and delivery_transport_available is true only when both captured endpoints are canonical SSH endpoints. It never reports either endpoint.

For validation that invokes Bazel, use the cached entry point or generate a task-local launcher once from the repository root. Ordinary bazel run can retain the Bazel lock while its target runs; --script_path releases it before the generated launcher is executed. Refresh the launcher after changing the delivery tool. This requires no installed runner update:

bazel_agent bazel run --script_path=out/task/repo_delivery \
  //tools/repo_delivery

For the supported GitHub adapter, the normal workflow is:

bazel_agent bazel run //tools/repo_delivery -- inspect --base master
bazel_agent bazel run //tools/repo_delivery -- prepare \
  --base master \
  --message-file out/task/commit.md \
  --receipt-file out/task/prepare.json \
  --path path/to/task/file \
  --rewrite <inspect.local_head_oid> # omit when the range has no commit
# For an explicitly reviewed task-owned multi-commit range, use
# --consolidate <inspect.local_head_oid> instead of --rewrite.
out/task/repo_delivery validate \
  --receipt-file out/task/prepare.json --plan-file out/task/checks.json
out/task/repo_delivery continue \
  --receipt-file out/task/prepare.json --publish
out/task/repo_delivery continue \
  --receipt-file out/task/prepare.json

checks.json is an explicitly selected validation plan. Keep it mode 0600 in the same ignored out/<task>/ directory as the preparation receipt. For example, a change confined to the delivery Go package can use:

{
  "schema": "repo_delivery/validation_plan/v1",
  "checks": [
    {
      "workspace": ".",
      "kind": "test",
      "targets": [
        "//tools/repo_delivery/cmd/repo_delivery:go_test",
        "//:repo_quality_test"
      ],
      "timeout_seconds": 3600
    },
    {
      "workspace": ".",
      "kind": "lint",
      "targets": ["//tools/repo_delivery/cmd/repo_delivery:all"],
      "timeout_seconds": 3600
    }
  ],
  "gap_decisions": []
}

Allowed kinds are test, build, and lint (build with --config=lint). The plan accepts 1–32 sequential checks, 1–128 explicit local labels per check, and a 1–3600 second deadline per check. Package :all is supported outside the root package; recursive target patterns, arbitrary run targets, shell commands, and free-form flags are not. Workspace paths are relative to the Git worktree root and must name real Bazel workspace roots. Nested checks execute there; the required //:repo_quality_test check executes in .. The plan must lint every suggested non-root affected package and resolve each validation gap with exactly one { "path": "...", "reason": "..." } decision. The caller still selects sufficient consumer checks and verifies representative output.

validate runs aggregate git diff --check first, then the selected checks. It requires a fully clean worktree and ordinary index flags before and after checks. It records exact head/tree, preparation revision, plan bytes, inherited environment digest, check outcomes, and log digests beside the receipt, using mode 0600 files. Each output stream is capped at 96 KiB; truncation fails the check. The same receipt lock protects validation and continuation. Keep all these files trusted and unedited; they are consistency evidence, not security tokens. Tool binaries, ignored configuration, external services, and other inputs outside the recorded Git tree/environment still require the caller’s input-stability judgment before publication. No passing checks are reused automatically by a new validation run.

continue reports readiness without publishing. Only continue --publish uses the captured passing result to call the existing guarded publication and verification path; it never substitutes the current mutable HEAD as evidence. Changed candidate, receipt, plan, environment, incomplete results, altered logs, and dirty inputs refuse publication. A base rebase records revalidation_required and stops before pushing: rerun validate against the updated receipt, then explicitly continue. An interrupted or failed publication remains publication_attempted; further continuation only verifies its remote postcondition and never blindly repeats a push or metadata mutation. Diagnose an incomplete result before using the existing manual recovery API. A new validation run cannot reset an uncertain attempt for the same candidate.

prepare derives affected_bazel_labels from the prepared aggregate changed paths, selecting each nearest non-root Bazel package. It never infers //:all from a root-owned file. The reported bazel_selection_basis is nearest_non_root_package_without_dependency_analysis: this bounds discovery but does not establish downstream impact. Shared build inputs may need explicit consumer checks.

bazel_validation_gaps lists paths requiring a separate decision, with reasons root_package_requires_explicit_targets, ignored_by_root_workspace, nested_workspace, or no_bazel_package. For each gap, select appropriate targets or record why no target check applies. Validate nested or ignored workspaces through their owner, then return to the repository root for delivery. The suggested commands always include the root-workspace gate bazel_agent bazel test //:repo_quality_test; that gate does not establish semantic correctness for BUILD, MODULE, or configuration changes. Run semantic lint for the selected affected targets in addition to that mandatory gate.

To synchronize a prepared, task-owned, single-commit feature branch with an advanced base before prepare, use the guarded adapter workflow:

bazel_agent bazel run //tools/repo_delivery -- rebase --base master

The command refuses dirty trees, divergent remote feature tips, multi-commit or merge-containing ranges, and pull-request metadata changes. It fetches fresh refs, replays the commit in an isolated worktree, preserves signature requirements, pushes only with the captured remote feature lease, verifies base advancement, and reports the literal resulting head. Run required validations against that head before prepare and publish.

Remote rewrites use rewrite-authorize to write a typed, non-authorizing authorization receipt (old remote OID, new head OID, owner root, task paths, provider ownership), then prepare --rewrite-authorization <file> instead of raw --replace-remote handoff. Review replies accept --goal-ref, --delivery-ref, and --defect-id durable join references.

prepare refuses a divergent remote feature tip by default. Use --replace-remote <literal-inspect.remote_head_oid> only after the git-rebase-remote workflow has preserved that exact old tip and established that it is task-owned history the user authorized rewriting. Never infer the OID or use this escape hatch for shared, stacked, human-owned, unrelated, or ambiguous history. A mismatched, malformed, absent, or unnecessary authorization is refused. The final fresh snapshot and preparation receipt bind the same old remote OID for the later exact force-with-lease push.

prepare --consolidate <literal-inspect.local_head_oid> is the explicit ownership authorization for replacing a multi-commit feature range with one aggregate commit. It is not inferred from author names. The adapter still requires a merge-free linear chain, one author and committer identity across the range, the ownership disclaimer on its oldest commit, pull-request metadata matching the requested aggregate message, and the exact inspected head. It preserves any signature requirement found in the range and keeps the fetched remote feature tip as the publication lease. --consolidate and --rewrite are mutually exclusive.

When a clean replay onto an advanced base makes an expected aggregate path disappear from the resulting diff, the adapter accepts that shrink only when the prior candidate and the new base have byte-identical Git tree entries at that path. A new path, a non-identical disappearance, or an entirely empty aggregate remains a refusal. The derived receipt records the reduced exact aggregate path set.

The manual publish --receipt-file <path> --validated-head <literal-head_oid> API remains available for validations outside the structured plan and diagnosed recovery. Never populate that flag by resolving current HEAD: carry the literal candidate that the checks covered. A preparation receipt alone does not establish validation. The structured continuation path supplies that literal value from its recorded passing results instead.

For message-only amendments, deliver --message-file <path> --receipt-file <path> --owner-root <root> --task-path <path> combines inspection, any needed rewrite authorization, and preparation. It stops before publication with a nonzero exit and a revalidation_required report containing the exact head, tree, receipt, affected labels, and suggested checks. Establish validation for that candidate using validate, then use continue --publish, or use the manual publish API and verify. Do not repeat deliver to continue, because that prepares another candidate.

Version 1 delivery accepts only SCP-style or ssh:// Git fetch and push endpoints. The gh CLI is still used for the GitHub forge API, but the tool does not import mutable global credential-helper configuration installed by gh auth setup-git. An HTTPS Git remote is therefore rejected before inspect, preparation, or publication performs network access. Configure an SSH remote explicitly before using delivery; the tool will not rewrite the repository’s remote configuration for you.

prepare writes a strict versioned receipt under an ignored out/<task>/ directory. The receipt binds the prepared head and tree to the exact worktree and Git directories, fetch and push endpoint digests, sanitized repository identity, forge adapter, base and head refs, fetched base, expected remote feature ref, expected pull-request identity or absence, and immutable aggregate path scope. The file contains no remote URL, must remain untracked, and is installed with mode 0600 by atomic rename. It is a consistency record, not an unforgeable authorization token.

The adjacent receipt lock serializes receipt transitions and reads performed by cooperating repo_delivery processes. Keep the ignored receipt path trusted and do not edit, replace, copy over, or otherwise write it while prepare, publish, or receipt-bound verify is running. Stable byte and revision checks detect changes visible before their checks, but operating systems do not provide a portable atomic pathname-content compare-and-swap. A same-user process that ignores the lock can race the final comparison and rename; the tool does not claim to exclude that writer. A persistent exclusive revision-claim sidecar would have the same trust boundary, while a crash before installation could strand the receipt without a safe automatic cleanup decision, so it is not used.

Use repeated --path flags for fully task-owned paths, or pre-stage only task-owned hunks and use --use-index. Both modes bind the complete existing feature diff, not merely the paths newly staged by that invocation. --message-only --rewrite <exact-oid> preserves the tree but changes the commit OID. Consolidation also changes the commit OID and parent structure. Every prepare, consolidation, or message-only amendment therefore requires a validation decision bound to its returned exact head. Run required checks after preparation by default. For a tree-preserving amendment, prior passing evidence may be reused only after recording its exact prior candidate, the matching tree OID, the new OID, and unchanged inputs relevant to each check. Those inputs include commands, tools, configuration, and environment. Rerun checks affected by commit identity, history, or stamping, and any check whose input stability is unknown. The caller owns and records this applicability judgment; the receipt neither proves validation nor authorizes reuse. When an authorized remote replacement is pending, rewrite evidence accepts an existing pull request only if its metadata matches the exact projectable local or fetched-remote commit projection. A legacy remote tail that lacks an aggregate disclaimer cannot block a matching local aggregate, and unrelated pull-request text remains a refusal.

Publish and receipt-bound verify require a clean index and reject staged, unstaged, or untracked changes in the prepared task scope. They preserve unrelated unstaged and untracked files when no rebase is needed. A required rebase demands a fully clean worktree and index. Run validation from a clean checkout at the literal head_oid whenever unrelated dirty files could affect the check; the tool cannot infer a check’s input set.

If the base advances after preparation, publish rebases the exact captured commit in an isolated ignored worktree. It then exits nonzero before pushing and emits a revalidation_required JSON report containing the new exact head, tree, and derived receipt. Validate that returned head directly, then retry publish with the same receipt file and the new literal OID. Do not run prepare again unless content or the commit message must change. A receipt also supports a guarded retry when the remote already equals its prepared head but pull-request creation or metadata synchronization stopped partway through. Replacement pull-request identities and any state other than the exact prior or desired projection are refused. Multi-commit consolidation likewise requires an existing pull request to equal the requested aggregate message’s projection, so consolidation cannot silently replace independently edited pull-request text.

The tool creates commits with Git plumbing and pushes one exact ref with hooks disabled. It rejects shallow, promisor, or grafted history and ignores replacement objects. Each network operation runs in a fresh private, config-free bare Git directory bound to the captured SSH endpoint and the repository’s canonical object database. It does not load mutable main-repo local/worktree URL rewriting, proxy, TLS, SSH-command, or remote configuration. Normal DNS resolution and SSH host-key verification still apply; the tool does not claim to pin an IP address or server key. Ordinary local Git operations still intentionally use repository identity and signing configuration. Fetches use isolated temporary refs without pruning, then install exact private refs locally; pushes use an exact force-with-lease. Repository-required hook checks remain the caller’s responsibility and must complete before recording the validated OID.

The feature-ref lease and base-ref checks are separate because Git forges do not offer a cross-ref compare-and-swap. If the base advances in the narrow push window, the feature ref may be visible briefly before the tool detects the race and attempts an exact guarded rollback. Coordinate consumers that react immediately to branch-update webhooks.

Start with a bounded structured inventory:

bazel_agent bazel run //tools/repo_delivery -- review inspect

Carry values from the latest inspection literally. All mutations require the pull-request node ID, expected head, and pull-request expectation digest. A top-level reply also requires the reported last-comment sentinel and top-level inventory digest:

bazel_agent bazel run //tools/repo_delivery -- review comment \
  --pull-request-id <pull_request.id> \
  --expected-head <pull_request.head_ref_oid> \
  --expected-pull-request-digest <pull_request_expectation_digest> \
  --expected-last-top-level-comment \
    <expected_last_top_level_comment> \
  --expected-top-level-comments-digest \
    <expected_top_level_comments_digest> \
  --body-file out/task/comment.md

Thread replies and resolutions additionally bind the thread, its last comment, and its complete expectation digest:

bazel_agent bazel run //tools/repo_delivery -- review reply \
  --pull-request-id <pull_request.id> \
  --expected-head <pull_request.head_ref_oid> \
  --expected-pull-request-digest <pull_request_expectation_digest> \
  --thread-id <review_threads[index].id> \
  --expected-last-comment-id <review_threads[index].comments[-1].id> \
  --expected-thread-digest <review_threads[index].expectation_digest> \
  --body-file out/task/reply.md \
  --reply-receipt-file out/task/reply.json

bazel_agent bazel run //tools/repo_delivery -- review resolve \
  --pull-request-id <pull_request.id> \
  --expected-head <pull_request.head_ref_oid> \
  --expected-pull-request-digest <pull_request_expectation_digest> \
  --thread-id <review_threads[index].id> \
  --expected-last-comment-id <review_threads[index].comments[-1].id> \
  --expected-thread-digest <review_threads[index].expectation_digest> \
  --reply-receipt-file out/task/reply.json

bazel_agent bazel run //tools/repo_delivery -- review request \
  --pull-request-id <pull_request.id> \
  --expected-head <pull_request.head_ref_oid> \
  --expected-pull-request-digest <pull_request_expectation_digest> \
  --reviewer <login>

Comment and reply bodies must be ignored files under out/<task>/; the tool adds the exact comment disclaimer. Resolution requires the strict reply receipt written by review reply, and the receipt must still match the exact pull request, head, thread, reply, body, and complete bounded review inventory projection. The parent pull-request UpdatedAt is a nondecreasing floor, rather than an exact value, because reply side effects can advance it asynchronously; every review, top-level comment, thread and thread comment, and review request remains bound. Reinspect after every mutation and use the newly reported IDs and digests for the next one. The one-use reply authority expires no more than five minutes after issuance. Resolution verifies the authority window and atomically consumes the receipt before contacting the provider. If a provider read fails before any resolution mutation is attempted, the tool can restore the original unexpired receipt without replacing another file or extending its authority window. Only an explicit restoration report permits retry with that receipt; no additional public reply is needed for that read failure. Expiration, semantic or full-inventory mismatch, mutation failure, and an unknown mutation outcome still consume authority. Never recreate the receipt yourself. Reinspect the remote state and, if resolution remains appropriate, leave a fresh reasoned reply to obtain new one-use authority.

GitHub provides neither compare-and-swap resolution nor a documented monotonic review-thread epoch. A human resolve followed by unresolve can therefore be unobservable if it restores identical thread and pull-request state inside the five-minute authority window. The exact-state checks, short expiration, and one-use consumption narrow that risk; they do not prove that such an ABA or a change to provider metadata omitted from the bounded projection did not occur. Do not resolve a thread that may be concurrently moderated.

GitHub does not expose atomic compare-and-swap mutations for pull-request metadata, comments, replies, resolutions, or review requests. The adapter checks exact expectations before each mutation and verifies the complete result afterward, but a concurrent human change can still occur inside that narrow provider-side window. Do not mutate an actively coedited pull request. Post-mutation inspection failures are reported as outcome unknown; reinspect instead of retrying blindly.

GitHub is supported through the gh CLI. Forge behavior is selected behind a Go interface and uses argument-vector subprocess calls, so another structured CLI adapter can be added without changing delivery policy. --forge auto selects GitHub for github.com; use --forge github --forge-cli <gh-path> to select an explicit executable. Unknown or unsupported forges fail before any commit rewrite or push.

Version 1 is limited to same-repository pull requests. It cannot reliably discover or map an upstream pull request whose head lives in a fork. Treat same-repository topology as a caller-enforced precondition: do not use the delivery or review commands for a fork-based or otherwise cross-repository pull request, and stop when remote or pull-request ownership is uncertain. The adapter fails closed when it observes an unsupported or inconsistent topology, but that refusal is not a substitute for this caller check.

The read-only provider command recognizes known Forgejo hosts, but there is currently no Forgejo delivery adapter. Use the repository’s documented Forgejo compatibility workflow instead of pretending GitHub operations are portable.

78 - Repository quality

Whole-index formatting, linting and validation coordinator

This package uses upstream aspect_rules_lint formatting and linting rules to discover Git-tracked files and inspect declared source targets with established tools acquired by Bazel. It does not implement a formatter or linter and does not download tools at runtime. Thin workspace adapters extend the upstream language list with the official Go SDK for module and workspace manifests, StyLua and Selene for Lua, and the existing Prettier XML plugin for Qt .ui and .qrc files.

Format all safe, hand-maintained files:

bazel_agent bazel run //:format

Run the non-mutating repository check:

bazel_agent bazel test //:repo_quality_test

The suite also parses root BUILD.bazel and rejects load() statements to keep unrelated tool dependencies out of root package loading. Run this check alone with bazel_agent bazel test //tools/repo_quality/test/root_build:root_build_test.

Run semantic source linters over declared targets:

bazel_agent bazel build --config=lint //...

The CSS formatter bucket includes CSS, Less and SCSS. The JavaScript bucket includes JavaScript, JSON, JSON-with-comments, JSON5, TypeScript, TSX and Vue. Go source uses gofumpt; go.mod and go.work use the official Go SDK. Lua checks cover every tracked file not excluded by Git attributes, using StyLua for canonical formatting and Selene for correctness diagnostics.

Explicit templates (.j2, .tmpl, .tpl, and the Hugo layout tree), generic application configuration, and non-Terraform HCL are deliberately excluded from general formatting. Ordinary Markdown, YAML, HTML and other files remain covered even when their contents include template expressions. Generated, vendored, lock, binary, diagram and exact-content files likewise retain their owning regeneration, validation or integrity workflow.

The integration test intentionally uses the upstream rule’s no_sandbox mode so it can inspect files that are tracked by Git but not declared in BUILD files. This is a local-checkout guarantee, like the root Buildifier test; tool acquisition remains hermetic and pinned through Bazel.

79 - Resolved toolchain

Helper rule to create a resolved toolchain

79.1 - Bzl

Bazel code

79.1.1 - al_resolved_toolchain

al_resolved_toolchain

load("@com_alwaldend_src//tools/resolved_toolchain/main/bzl:al_resolved_toolchain.bzl", "al_resolved_toolchain")

al_resolved_toolchain(toolchain_label, **kwargs)

Create a resolved toolchain

PARAMETERS

Name Description Default Value
toolchain_label

-

none
kwargs rule kwargs none

RETURNS

Resolved toolchain rule

80 - Rfc

Rfc tools

80.1 - Bzl

Bazel code

80.1.1 - al_rfc_extension

al_rfc_extension

al_rfc_extension = use_extension("@com_alwaldend_src//tools/rfc/main/bzl:al_rfc_extension.bzl", "al_rfc_extension")
al_rfc_extension.download(name, integrity, rfcs)

Rfc extension

TAG CLASSES

Attributes

Name Description Type Mandatory Default
name Name Name required
integrity Rfc integrity Dictionary: String -> String optional {}
rfcs Rfcs List of strings optional []

80.1.2 - al_rfc_repo

al_rfc_repo

load("@com_alwaldend_src//tools/rfc/main/bzl:al_rfc_repo.bzl", "al_rfc_repo")

al_rfc_repo(name, integrity, repo_mapping, rfcs, url)

Rfc repository

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
integrity Rfc integrity Dictionary: String -> String optional {}
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension’s implementation function).		 Dictionary: String -> String optional
rfcs Rfcs List of strings optional []
url Url format String optional "https://www.rfc-editor.org/rfc/{postfix}"

81 - Root Bazel module

Generate the root module’s owning include list

MODULE.bazel is generated directly from include.MODULE.bazel files:

bazel run //tools/bazel_module:update

Dependency declarations and pins stay in their owning include files. The small root module(...) header lives in the Go generator. Discovery uses the existing //tools/git host Git wrapper to include tracked and untracked files while respecting Git ignore rules. Deleted files, symlinks, .bazelignore directories, and standalone workspaces beneath MODULE.bazel, WORKSPACE, or WORKSPACE.bazel boundaries are excluded.

Includes are ordered by owning directory, with third_party, tools, then projects before other trees. This keeps the existing precedence between those trees, including toolchain registrations. A parent directory precedes its children. Keep any order-sensitive declarations together in one owning include.

//tools/bazel_module/cmd/update:freshness_test checks the current checkout and is included in //:repo_quality_test. It intentionally disables sandboxing and result caching to detect new or removed files outside declared Bazel inputs. The generator’s unit tests remain sandboxed and cacheable.

Before deleting or moving an existing include, retain a launcher so regeneration does not need to load the old module after its include disappears:

mkdir -p out/bazel_module
bazel run --script_path=out/bazel_module/update //tools/bazel_module:update
# Delete or move the include, then regenerate:
out/bazel_module/update

82 - Run tool

Run tool rules

82.1 - Bzl

Bazel code

82.1.1 - al_run_tool

al_run_tool

load("@com_alwaldend_src//tools/run_tool/main/bzl:al_run_tool.bzl", "al_run_tool")

al_run_tool(name, tool, executable, test, **kwargs)

Generate either native_test, native_binary, or run_binary target

PARAMETERS

Name Description Default Value
name Target name (required) none
tool Tool label to run (required) none
executable If True, generate native_binary False
test If True, generate native_test False
kwargs kwargs for rules none

83 - Selene

Hermetic Selene Lua linter

Selene provides correctness-oriented linting for the repository’s hand-maintained Lua files. The repository standard-library description permits the intentional al configuration DSL and Neovim’s vim global while keeping Selene’s ordinary Lua diagnostics enabled.

84 - Sh

Shell rules

84.1 - Bzl

Bazel code

84.1.1 - al_sh_library

al_sh_library

load("@com_alwaldend_src//tools/sh/main/bzl:al_sh_library.bzl", "al_sh_library")

al_sh_library(name, shfmt_src, editorconfig_src, shellcheck_src, run_args_src, visibility,
              test_data, **sh_kwargs)

Create targets for a shell library

Targets:

  • ${name}.shfmt_fix: executable to run shfmt
  • ${name}.shfmt_test: test whether the script is formatted
  • ${name}.shellcheck_test: shellcheck test

PARAMETERS

Name Description Default Value
name target name none
shfmt_src

-

"//tools/shfmt"
editorconfig_src

-

"//tools/shfmt:editorconfig"
shellcheck_src

-

"//tools/shellcheck"
run_args_src

-

"//tools/sh/main/sh:run_args_lib"
visibility

-

["//:__subpackages__"]
test_data

-

[]
sh_kwargs kwargs for sh targets none

84.1.2 - al_write_script

al_write_script

load("@com_alwaldend_src//tools/sh/main/bzl:al_write_script.bzl", "al_write_script")

al_write_script(name, out, content, make_vars, set_flags, shebang)

Write a script and make it executable

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
out Output file Label; nonconfigurable required
content Script content String required
make_vars Additional make vars Dictionary: String -> String optional {}
set_flags Flags to pass to set List of strings optional ["-eu"]
shebang Sheband to use String optional "#!/usr/bin/env sh"

85 - Shellcheck

Shellcheck wrapper

86 - Shfmt

Shfmt

87 - Sops

Sops

88 - Stylua

Stylua wrapper

89 - Taplo

Taplo

90 - Terraform

Terraform
  • Terraform binaries use explicit operation suffixes. In particular, apply is <name>.apply; the unnamed <name> mutating alias is intentionally absent.
  • Root //:tf.* commands delegate to //tools/terraform/cmd/workspace:tf.*. They retain the repository root as Terraform’s working directory. Other packages default to their own directory; terraform_binary accepts an explicit chdir for relocated command wrappers.

90.1 - Runner

Golang code for the terraform runner

91 - Toml

Toml rules

91.1 - Bzl

Bazel code

91.1.1 - al_toml_data

al_toml_data

load("@com_alwaldend_src//tools/toml/main/bzl:al_toml_data.bzl", "al_toml_data")

al_toml_data(name, deps, srcs, tomlv)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Toml data targets List of labels optional []
srcs Toml files List of labels optional []
tomlv Tomlv target to use for validation Label optional "@com_alwaldend_src//tools/tomlv"

91.1.2 - al_toml_info

load("@com_alwaldend_src//tools/toml/main/bzl:al_toml_info.bzl", "AlTomlInfo")

AlTomlInfo(srcs, deps)

Provide toml data info

FIELDS

Name Description
srcs Toml files
deps Toml data targets

91.1.3 - al_toml_validate

al_toml_validate

load("@com_alwaldend_src//tools/toml/main/bzl:al_toml_validate.bzl", "al_toml_validate")

al_toml_validate()

Aspect adding linters for toml files

ASPECT ATTRIBUTES

Name Type
deps String

ATTRIBUTES

92 - Tomlv

Tomlv

93 - Traefik

Traefik

94 - Transitive sources

Provider and a rule to extract transitive sources

94.1 - Bzl

Bazel code

94.1.1 - al_transitive_sources

load("@com_alwaldend_src//tools/transitive_sources/main/bzl:al_transitive_sources.bzl", "AlTransitiveSources")

AlTransitiveSources(transitive_sources)

Provide transitive sources

FIELDS

Name Description
transitive_sources -

al_transitive_sources

load("@com_alwaldend_src//tools/transitive_sources/main/bzl:al_transitive_sources.bzl", "al_transitive_sources")

al_transitive_sources(srcs, deps)

Obtain the source files for a target and its transitive dependencies.

PARAMETERS

Name Description Default Value
srcs a list of source files none
deps a list of targets that are direct dependencies none

RETURNS

a collection of the transitive sources

95 - Trufflehog

Trufflehog

The normal //tools/trufflehog:repo_test scans the history reachable from the checked-out HEAD and skips unrelated local refs. Run the manual //tools/trufflehog:repo_all_refs_test target explicitly when an audit must include every local Git ref, such as T3 checkpoint refs from other worktrees.

96 - Twine

Twine

97 - Txt

Text rules

97.1 - Bzl

Bazel code

97.1.1 - al_combine_files

al_combine_files

load("@com_alwaldend_src//tools/txt/main/bzl:al_combine_files.bzl", "al_combine_files")

al_combine_files(name, srcs, **kwargs)

Create a genrule combining several files into one

PARAMETERS

Name Description Default Value
name genrule target none
srcs list of labels to combine none
kwargs other genrule kwargs none

97.1.2 - al_txt_data

al_txt_data

load("@com_alwaldend_src//tools/txt/main/bzl:al_txt_data.bzl", "al_txt_data")

al_txt_data(name, srcs, **kwargs)

Text data

PARAMETERS

Name Description Default Value
name target name none
srcs sources none
kwargs filegroup kwargs none

98 - Vault

Vault

The root //:vault and //:vault.* labels delegate to wrappers in //tools/vault/cmd/workspace, using //tools/al:config. //tools/vault:vault is the standalone CLI; the wrappers add the existing AL environment injection.

98.1 - Backup

Run backup for Vault

98.2 - Forgejo login

Get a short-lived Forgejo token using OIDC

The plugin registers token removal before issuance, using a unique token name. Startup failure and normal shutdown attempt removal through the authenticated Forgejo browser session, including when creation did not return a usable token. Cleanup parses the complete applications settings page and verifies token absence after deletion. It then logs out the invocation’s browser session and verifies that the retained original cookie no longer accesses authenticated settings. Cleanup failures are reported.

The parser follows the Forgejo 15.0.3 applications template: all tokens appear on one page, each in a flex-item row with a title and a matching delete button. It requires the applications page marker and new-token link before accepting an empty list. Login pages, invalid token IDs, duplicates, and responses larger than 4 MiB fail closed. A changed upstream template may require a parser update. Network requests have a ten-second timeout and honor cancellation. Forced process termination or an unavailable Forgejo server can prevent cleanup; Forgejo tokens do not acquire an expiry merely because this plugin created them.

98.2.1 - api

Proto docs for api.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/forgejo_login:api_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/forgejo_login:forgejo_login",
    ],
)

syntax = "proto3";

package com.alwaldend.src.tools.vault.forgejo_login.forgejo_login_proto;

option go_package = "git.alwaldend.com/alwaldend/src/tools/vault/forgejo_login/forgejo_login_proto";

message Config {
  string forgejo_url = 1;
  string forgejo_oauth_name = 2;
  string vault_conn = 3;
  string vault_auth = 4;
}

98.3 - Gen client cert

Generate a client certificate

98.4 - Gen root token

Generate a root token for Vault

98.5 - Harbor login

Create a harbor session using OIDC

The plugin destroys its Harbor session on normal shutdown and checks that the original session ID is rejected by the current-user API. Cleanup uses Harbor’s /c/oidc/logout endpoint (available in newer Harbor releases) and does not follow the optional identity-provider logout redirect. Unsupported endpoints, network failures, or sessions that remain valid are reported as cleanup errors. Session expiry remains server-controlled; forced termination cannot guarantee logout.

The session destruction behavior is defined by Harbor’s OIDC controller. Vault tokens created by the invocation are revoked after session cleanup.

98.5.1 - api

Proto docs for api.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/harbor_login:api_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/harbor_login:harbor_login",
    ],
)

syntax = "proto3";

package com.alwaldend.src.tools.vault.harbor_login.harbor_login_proto;

option go_package = "git.alwaldend.com/alwaldend/src/tools/vault/harbor_login/harbor_login_proto";

message Config {
  string harbor_url = 1;
  string vault_conn = 2;
  string vault_auth = 3;
}

98.6 - Injector

Secret injector

Shutdown first drains plugin requests, then stops and waits for resource processes, revokes invocation-owned Vault credentials, and deletes temporary files and SSH key directories. Failed cleanup is reported. Registration after shutdown is rejected; a fetcher removes any unregistered temporary material. Temporary files use mode 0600 and directories use 0700. Deletion is filesystem unlinking, not secure erasure, and cannot run after SIGKILL or host failure.

no_auth explicitly sets the injected VAULT_TOKEN to an empty value so an inherited token is overridden. This does not remove the user’s token-helper file; commands that independently consult that helper may still authenticate. Template errors and OIDC status errors omit input and response contents. OIDC requests honor cancellation and do not follow redirects.

98.6.1 - api

Proto docs for api.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/injector:api_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/injector:injector",
    ],
)

syntax = "proto3";

package com.alwaldend.src.tools.vault.injector.injector_proto;

option go_package = "git.alwaldend.com/alwaldend/src/tools/vault/injector/injector_proto";

message File {
  string value = 1;
  string from_file = 2;
  map<string, string> extra = 3;
}

message Env {
  string value = 1;
}

message Kv {
  // Secret path
  string path = 1;
  // Secret mount
  string mount = 2;
}

message Op {
  string method = 1;
  string path = 4;
  map<string, string> data = 5;
}

message VaultSsh {
  string backend = 1;
  int64 ttl = 2;
}

message Process {
  string name = 1;
  repeated string args = 2;
}

message Oidc {
  string name = 1;
  string scope = 2;
  string client_id = 3;
  string redirect_uri = 4;
}

message VaultEnv {
  // Vault connection
  string conn = 1;
  // Vault auth
  string auth = 2;
}

message Resource {
  // Resource name
  string name = 1;
  // Vault connection for the resource
  string vault_conn = 2;
  // Vault auth for the resource
  string vault_auth = 3;
  // Dependencies
  repeated string deps = 8;

  oneof res {
    // Vault operation
    Op op = 4;
    // Vault KV secret
    Kv kv = 5;
    // Environment variable
    Env env = 6;
    // File
    File file = 7;
    // Vault environment variables
    VaultEnv vault_env = 9;
    // Ssh key signed by Vautl
    VaultSsh vault_ssh = 10;
    // Run a cmd
    Process process = 11;
    // Create an OIDC token
    Oidc oidc = 12;
  }
}

message Config {
  // Resources
  repeated Resource res = 1;
}

98.7 - Login

Login to vault using the yubikey
bazel run //tools/vault/login

98.8 - PVE login

Get a login ticket using OIDC

The plugin requests an API token with a one-hour expiry and deletes that token on shutdown using the retained login ticket and CSRF token. The token name is registered for cleanup before creation, so cleanup is attempted even when a creation response is lost or malformed. Failures to delete are reported; expiry is the fallback when shutdown cannot complete. Pre-existing credentials are not revoked. Vault tokens created by the invocation are revoked after token cleanup.

Token deletion uses the Proxmox user token API.

98.8.1 - api

Proto docs for api.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/pve_login:api_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/pve_login:pve_login",
    ],
)

syntax = "proto3";

package com.alwaldend.src.tools.vault.pve_login.pve_login_proto;

option go_package = "git.alwaldend.com/alwaldend/src/tools/vault/pve_login/pve_login_proto";

message Config {
  string pve_base_url = 1;
  string pve_redirect_url = 2;
  string pve_realm = 3;
  string vault_conn = 4;
  string vault_auth = 5;
}

98.9 - Tf backend

Http terraform backend backed by Vault

The plugin tracks each running backend for shutdown, including backends created before a later call fails. Shutdown drains HTTP requests before revoking the backend’s invocation-owned Vault credentials. If the shutdown deadline expires, connections are forcibly closed and the timeout is reported. Normal HTTP server closure is not an error. Vault requests use their incoming request context.

98.9.1 - api

Proto docs for api.proto
load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/tf_backend:api_java_library",
    ],
)

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "name",
    deps = [
        "@com_alwaldend_src//tools/vault/tf_backend:tf_backend",
    ],
)

syntax = "proto3";

package com.alwaldend.src.tools.vault.tf_backend.tf_backend_proto;

option go_package = "git.alwaldend.com/alwaldend/src/tools/vault/tf_backend/tf_backend_proto";

message Config {
  string vault_conn = 1;
  string vault_auth = 2;
  string vault_secret = 3;
  string vault_secret_mount = 4;
}

98.10 - Unseal

Unseal the vault

99 - Versioning

Global repository and project versioning

versioning owns versions for this repository and its first-party projects. It deliberately does not manage versions of third-party dependencies.

The repository uses SemVer-compatible calendar versions:

  • ordinary development: 0.0.0-dev;
  • nightly trunk tag: vYYYY.W.0-nightly.YYYYMMDD;
  • weekly release branch: releases/YYYY.W;
  • release tag: vYYYY.W.PATCH.

YYYY and W are the ISO week-year and week. The week is not zero-padded, because SemVer forbids leading zeroes in numeric identifiers. Patch zero is the release branch point. Every first-parent commit after that point advances the calculated patch number by one.

Calculated versions and Bazel status omit the Git tag’s leading v.

A commit may carry one nightly tag and one release tag when a nightly is promoted. Branch context selects the channel automatically. On detached HEAD, pass --channel release or --channel nightly for that exact co-tagged commit. For an untagged detached commit from a release branch, pass --release YYYY.W so the tool can calculate its patch from the correct branch-point tag.

Build and inspect the tool with:

bazel_agent bazel run //tools/versioning/cmd/versioning -- show

For a stamped build, use the bootstrap entry point. It generates a source-current Bazel launcher under out/versioning/, then the Go tool runs Bazel with itself as workspace status:

tools/versioning/cmd/versioning/versioning.sh bazel -- \
  build --config=release //path/to:artifact

Read $versioning for the guarded nightly, release, and Bazel stamping workflows.

versioning also owns a typed, reviewed release-ref plan and a provider-neutral guarded publisher for the generated nightly and release tags. It never merges versioning, delivery, or goal authority; the tool retains its own release-refs authority.

Generate a deterministic plan from the resolved version state:

bazel_agent bazel run //tools/versioning/cmd/versioning -- release-plan \
  --plan out/delivery/release-plan.json

The plan records the exact version, channel, commit, tree state, target refs (tag-only for nightly, branch-plus-tag for release), the expected remote preconditions, and whether atomic multi-ref publication is required. It is reviewed before consumption and is not an authorization.

Publish the reviewed plan only after explicit release scope:

bazel_agent bazel run //tools/versioning/cmd/versioning -- release-publish \
  --plan out/delivery/release-plan.json \
  --receipt out/delivery/release-ref-receipt.json

The guarded publisher fetches expected remote state, acquires a distinct release-refs lease, publishes the refs (atomically when required and supported), and verifies the remote before emitting a ReleaseRefReceipt. An existing immutable release tag never moves; a remote that cannot guarantee atomic multi-ref publication is an explicit refusal, never a generic success.

100 - Vial

Bazel rules for Vial

100.1 - Bzl

Bazel code

100.1.1 - al_vial_configs

al_vial_configs

load("@com_alwaldend_src//tools/vial/main/bzl:al_vial_configs.bzl", "al_vial_configs")

al_vial_configs(name, srcs, visibility, **kwargs)

Generate vial config targets

PARAMETERS

Name Description Default Value
name generated docs archive name none
srcs vial config none
visibility visibility None
kwargs kwargs for template_files none

101 - Word lists

Word lists

102 - Workspace status

Workspace status script

103 - Ykman

Ykman (Yubikey Manager)