language-tools

Language-specific tooling and helpers.

Claude Code setup

This repo's .claude/settings.json enables plugins from the jr-claude-plugins marketplace. Register it once at the Claude user level — repo settings carry no machine-specific paths:

claude plugin marketplace add git@github.com:johnrichter/claude-marketplace.git
# or, with the psa-platform repos checked out as siblings:
claude plugin marketplace add ../marketplace-public

Knowledge bases are configured at the Claude user level, not per repo.

language-tools CLI

Cobra+koanf CLI composing the ai-shared-lib toolchain, clikit and sysops libraries: per-language build/test/lint/format/vet runs, and this binary's own per-OS/arch release-build orchestration. Every invocation writes one clikit result record to stdout and exits with clikit's exit-code taxonomy (0/10/20/.../90) — never a bare Go error to stderr.

Requires this repo checked out as a sibling of ai-shared-lib (go.mod's replace directives point at ../ai-shared-lib/go/*).

Build

go build -o language-tools .

Commands

language-tools build  --language <lang> --dir <path>   # cargo/etc. build, capped RunResult
language-tools test   --language <lang> --dir <path>   # same, for tests
language-tools lint   --language <lang> --dir <path>   # same, for lint
language-tools format --language <lang> --dir <path>   # same, for format
language-tools vet    --language <lang> --dir <path>   # same, for vet
language-tools release build --version <ver> --output-dir <dir>  # this binary's own archives+checksums

build/test/lint/format/vet share --log-dir (uncapped diagnostic log, default .language-tools/log), --cache-dir (content-hash impact-skip cache, disabled by default), --allow-warnings (default off — warnings fail the run), and --timeout. release build defaults --target to linux/amd64,linux/arm64,darwin/amd64,darwin/arm64 and --binary (repeatable, name:package) to language-tools:.; it writes a checksums.txt manifest (one row per archive) and a binary-checksums.txt manifest (one row per extracted binary, keyed <name>_<version>_<os>_<arch> with no leading v) alongside the archives.

Every setting is also a LANGUAGE_TOOLS_<NAME> environment variable and a YAML --config file key, layered flag > env > file > default (e.g. --allow-warnings / LANGUAGE_TOOLS_ALLOW_WARNINGS / allow_warnings: in the config file). An explicit --config <path> always wins over the file described next.

Repository config: language-tools.yaml (CONTRACT-LT-CONFIG)

Absent an explicit --config, the loader searches for a file named language-tools.yaml, walking up from the working directory to (and including) the enclosing git repository's root, and stopping there — it never reads a parent repository's file and never reads $HOME. A missing file is not an error; every setting then resolves exactly as it does with no config file at all. When found, it sits between the built-in defaults and the environment: default < file < env < flag.

The file declares the repository's release topology — its module layout and each module's tag shape — and carries exactly these keys:

Key	Type	Required	Default	Notes
version	integer	yes	none (required)	Currently must be 1.
modules	list of module entries	yes	none (required)	At least one entry.
modules[].path	string	yes	none (required)	Repository-root-relative; "." for a root module.
modules[].tag_form	string enum: bare | prefixed	yes	none (required)	bare prints the tag vX.Y.Z; prefixed prints <path>/vX.Y.Z (the monorepo shape).

Example, for a repository with one root module and one monorepo module:

version: 1
modules:
  - path: "."
    tag_form: bare
  - path: "go/toolchain"
    tag_form: prefixed

An unknown top-level or per-module key, a wrong-typed value, a malformed YAML document, or a duplicate modules[].path each fail the load closed with an error naming the file and the offending key — never a silent partial read. This file is load-only: no language-tools command ever writes it back.

Currently only the rust (cargo) toolchain adapter is registered upstream; build/test/lint/format/vet surface whatever languages ai-shared-lib/go/toolchain registers, with no per-language logic duplicated here. A check an adapter doesn't implement (e.g. vet on a language without one) exits 80 (unsupported), not an internal fault.

Example

language-tools build --language rust --dir ./crates/example
language-tools release build --version 1.2.3 --output-dir dist