lean-dist

name	lean-dist
description	Keep the published Composer archive lean by excluding dev/test/AI dirs via .gitattributes.

Lean dist

When to apply

• Adding a new top-level directory (tests/, docs/, .ai/, etc.)
• Reviewing a PR that touches .gitattributes
• Package's dist size feels too large

The contract

Every path NOT needed at runtime should be export-ignored so Composer's dist installer skips it. Two layers produce that — and neither is a list to hand-maintain in this skill:

• The managed block — vendor/bin/package-boost-php gitattributes writes package-boost-php's canonical AI/agent entries into the # >>> package-boost (managed) >>> block: the per-agent directories (.ai/, .claude/, .cursor/, …) and the root agent files (AGENTS.md, CLAUDE.md, GEMINI.md, plus the .cursorrules / .windsurfrules dotfiles). The exact set is generated by the command — read the live block, not a copy in this skill.
• The full lean set — .lpv is the single source of truth for the complete export-ignore set the validator checks: the managed AI/agent entries above plus dev tooling, tests, and lock files (tests/, composer.lock, phpstan.neon.dist, pint.json, …). Edit .lpv, not a list here.

Verifying

Run vendor/bin/package-boost-php lean (this package) or directly via vendor/bin/lean-package-validator validate. Both check the .gitattributes against .lpv rules.

Add to CI:

- name: Validate lean dist
  run: vendor/bin/package-boost-php lean

Validation is opt-in; the managed block is the baseline

Two distinct tools, two roles — don't conflate them:

• vendor/bin/package-boost-php gitattributes writes and refreshes the managed block. This is what actually makes the archive lean; you run it during setup and whenever a new top-level path needs excluding. Baseline, not optional.
• vendor/bin/package-boost-php lean (the stolt/lean-package-validator wrapper) only checks that the block stays complete. It is opt-in: wire it into CI if you want enforcement, but a package whose managed block is correct ships lean whether or not the validator ever runs. There is no default .lpv / composer-script wiring — add it only if you want the stricter gate.

If your .gitattributes export-ignore is already covered by the managed block (e.g. confirmed by a repo-init audit), the validator is redundant-but-harmless, not a missing requirement.

Anti-patterns

• Editing .gitattributes outside the managed block to add boost-managed entries — package-boost will rewrite the block on next sync
• Forgetting export-ignore on a new top-level dir → users get bloat
• Mixing export-ignore with diff/merge attributes on the same line (works, but visually noisy; separate the concerns)

See also

• .lpv file in this package's root for the canonical exclusion list
• references/gitattributes-managed-block.md in sandermuller/repo-init for the multi-tool managed-block contract