sloff

README

sloff 🦥

A fingerprint-aware codegen orchestrator for polyglot monorepos. Skips work when inputs haven't changed — and never lies about it.

sloff runs your code generators (proto / SQL / mock / GraphQL / etc.) and fingerprints their outputs in git so devs and CI skip re-generation when nothing has changed. Fingerprint hits are validated by comparing both inputs and the actual output files against the recorded state — so even when the fingerprint looks valid, a drifted output triggers re-generation rather than a stale skip.

Features

• Output-comparison fingerprint hits. A hit requires the recorded input_hash and the on-disk output files to match. Drifted outputs (manual edits, formatter runs, partial checkouts) are re-generated, never silently skipped.
• OS-portable fingerprints. Fingerprints are deterministic YAML committed to git. A record built on macOS works on Linux CI without rebuilds — tool versions are captured as logical strings, never as OS-specific binary hashes.
• Reads your existing toolchain. No replacement for aqua / mise / nix / pnpm / go.mod. Tool versions come from the runtime binary's --version, lockfiles, or repo source — whichever is the actual source of truth.
• Auto-derived dependencies. Task ordering is computed from inputs / outputs glob intersections. There is no manual depends: field to keep in sync.
• Single Go binary. No runtime dependencies, no daemon, no language ecosystem to install.
• Codegen-only by design. Build / test / lint stay in your existing tooling (Make, npm scripts, etc.) — sloff does one thing.

Install

go install github.com/izumin5210/sloff/cmd/sloff@latest

Quick start

Place a sloff.yml in any directory containing your codegen inputs:

tools:
  buf:
    exec: ["buf", "--version"]
  protoc-gen-go:
    exec: ["protoc-gen-go", "--version"]
    extract: 'v[0-9]+\.[0-9]+\.[0-9]+'

commands:
  - name: protoc-gen-go
    cmd: buf generate
    inputs: ["**/*.proto", "buf.gen.yaml", "buf.yaml", "buf.lock"]
    outputs: ["**/*.pb.go", "**/*.connect.go"]
    tools: [buf, protoc-gen-go]

Then from anywhere in the repo:

sloff run

sloff run discovers every sloff.yml, builds a DAG from inputs / outputs overlap, and either skips or re-runs each task based on fingerprint lookup.

Tool resolvers

tools: entries dispatch to one of three resolvers based on shape:

script — for prebuilt binaries

For anything with a --version command: aqua / mise / nix-distributed CLIs, go tool-managed bins, npm bins via pnpm exec, etc. The runtime binary's stdout is the version source of truth.

tools:
  buf:
    exec: ["buf", "--version"]
  protoc-gen-go:
    exec: ["protoc-gen-go", "--version"]
    extract: 'v[0-9]+\.[0-9]+\.[0-9]+'

go-local — for repo-internal Go CLIs

For codegen tools you maintain in this repo as Go cmd/... packages, run via go run:

tools:
  protoc-gen-foo:
    go-local: ./cmd/protoc-gen-foo

Internal .go source files contribute to the task's effective inputs (so source edits invalidate); external Go module versions come from go.sum.

pnpm-local — for pnpm workspace internal packages

For codegen tools you maintain as pnpm workspace packages:

tools:
  codegen:
    pnpm-local: "@org/codegen"

commands:
  - name: gen
    cmd: ["sh", "-c", "pnpm --filter @org/codegen build && pnpm exec my-codegen"]
    inputs: ["**/*.proto"]
    outputs: ["**/*.pb.ts"]
    tools: [codegen]

git-tracked files in the workspace package (and transitive workspace deps) contribute to inputs; external npm dep versions come from pnpm-lock.yaml. Build steps stay in the task cmd.

Fingerprint storage

By default sloff persists records to .sloff/fingerprints/ under the repo root and commits them to git (ADR-0003). For monorepos where git-noise / clone-size pressure starts mattering, switch to the DynamoDB backend via .sloff/config.yml:

# .sloff/config.yml
fingerprint:
  backend: dynamodb
  dynamodb:
    table: sloff-fingerprints # required
    region: us-east-1         # optional; falls back to AWS_REGION / shared config
    # endpoint: ""            # optional; emulator URL
    # expires_after_days: 0   # optional; >0 enables DynamoDB TTL-based GC

Credentials are resolved through the aws-sdk-go-v2 default chain (env vars / ~/.aws/credentials / IRSA / IMDS), so the config file carries no secrets and is safe to commit. The DynamoDB backend is fronted by a transparent $XDG_CACHE_HOME-rooted disk cache so warm lookups stay local; see Storage: DynamoDB for the full design (schema, caching, consistency, cost).

sloff does not auto-create the DynamoDB table — provision it once with your IaC of choice.

Table provisioning (AWS CLI / Terraform)

aws dynamodb create-table \
  --table-name sloff-fingerprints \
  --attribute-definitions \
      AttributeName=pk,AttributeType=S \
      AttributeName=sk,AttributeType=S \
  --key-schema \
      AttributeName=pk,KeyType=HASH \
      AttributeName=sk,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

resource "aws_dynamodb_table" "sloff_fingerprints" {
  name         = "sloff-fingerprints"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "pk"
  range_key    = "sk"

  attribute { name = "pk"; type = "S" }
  attribute { name = "sk"; type = "S" }

  # Required only when expires_after_days > 0 in .sloff/config.yml.
  ttl {
    attribute_name = "expires_at"
    enabled        = true
  }
}

Required IAM actions

{
  "Effect": "Allow",
  "Action": [
    "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:DeleteItem",
    "dynamodb:Query", "dynamodb:Scan",
    "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
    "dynamodb:DescribeTable"
  ],
  "Resource": "arn:aws:dynamodb:<region>:<account>:table/sloff-fingerprints"
}

When to use sloff (vs alternatives)

sloff is well-suited when:

• You have a polyglot codegen pipeline (Go + JS/TS + external prebuilt binaries) and want shared fingerprint store across devs and CI.
• You want to keep your existing toolchain (aqua / mise / nix / pnpm / go.mod) instead of migrating to a new build system.
• You're OK with outputs being committed to git (no separate artifact cache infrastructure).

You probably want a different tool when:

Need	Better fit
Cache compile artifacts and binaries (not just codegen outputs)	Bazel / Buck2
Hermetic build with full toolchain isolation	Bazel / Buck2
General task runner (build / test / lint / dev server / formatter)	moonrepo / Nx
JS/TS-only monorepo	Turborepo / Nx
File-grained dependency inference	Pants
Battle-tested at massive scale	Any of the above

sloff is intentionally narrow — codegen orchestration with honest fingerprints, nothing else.

Documentation

• Architecture — overall design
• Resolver: script
• Resolver: go-local
• Resolver: pnpm-local
• Storage: DynamoDB
• ADRs — design decision records (in Japanese)

License

MIT