Skip to content
SLCR

Reference

Project manifest

The normative definition of SLCR.toml, the file that marks a project's root and declares its specifications and tools.

This page defines SLCR.toml. The key words MUST, MUST NOT, SHOULD, and MAY are used as defined in RFC 2119⁠ (external site).

Location⁠Link to this section

  • The manifest MUST be named exactly SLCR.toml. The name is case-sensitive: a file named slcr.toml is reported as an error.
  • The directory that holds the manifest is the project root.
  • slcr finds the project by searching the working directory and then each parent directory for SLCR.toml.

Fields⁠Link to this section

FieldRequiredValue
formatVersionYesThe string "1".
specsYesA non-empty array of glob patterns naming the project's specification files, with no duplicates.
toolsNoA table of tool declarations, keyed by tool name. If present, it MUST NOT be empty.

Unknown fields MUST NOT appear.

TOML
formatVersion = "1"
specs = ["SPEC.slcr.toml", "services/**/*.slcr.yaml"]

[tools.cargo-nextest]
version = "1.0.0"
source = { url = "https://example.com/descriptors/cargo-nextest/1.0.0.toml" }
pin = "blake3:9f2c…"

[tools.ast-grep]
version = "1.2.0"
source = { path = "tools/ast-grep.toml" }
pin = "blake3:5938…"

specs⁠Link to this section

Each entry is a glob relative to the project root:

  • * and ? match within one path segment. They match a leading dot, but never a /.
  • ** matches any number of directories.
  • Matching skips the .git directory and anything git ignores.

slcr vet reports each of these as an error:

CodeMeaning
invalid-patternA pattern isn't a valid glob.
no-matchA pattern matches no file.
matches-validator-fileA pattern matches a validator file.
unsupported-formatA match has no specification file extension.
duplicate-spec-nameTwo matched specifications share a spec.name.

tools⁠Link to this section

Each key under [tools] is a tool name: lowercase letters and digits in dash-separated words, such as cargo-nextest. Validators refer to tools by this key. The key defaults to the descriptor's own name, but the key is authoritative and can differ from it.

Each entry has these fields:

FieldRequiredValue
versionYesThe descriptor's version, copied from it. A SemVer 2.0.0 version.
sourceYesWhere the descriptor is fetched from.
pinYesThe BLAKE3 hash of the descriptor's bytes.

source⁠Link to this section

A source is a table with exactly one of these fields:

FieldValue
urlAn https:// URL.
pathA path relative to the project root. It MUST NOT be absolute, contain a .. segment, or use backslashes.

pin⁠Link to this section

A pin is blake3: followed by 64 lowercase hexadecimal characters. slcr MUST NOT run a descriptor whose bytes don't hash to its pin.

Tool entries are written by slcr tools add, slcr tools update, and slcr tools remove. A pin SHOULD NOT be written or edited by hand.

slcr vet reports each of these as an error:

CodeMeaning
descriptor-not-installedA pinned descriptor isn't in the descriptor store. Run slcr tools install.
descriptor-corruptedThe stored descriptor doesn't hash to its pin.
descriptor-unreadableThe stored descriptor can't be read.
invalid-descriptorThe stored descriptor isn't a valid descriptor.
descriptor-version-mismatchThe descriptor's version differs from the entry's version.

Format version⁠Link to this section

formatVersion MUST be "1". A file with an unsupported format version is an error.