fix(kyberforge): bridge apm content to Claude Code's flat plugin discovery
Claude Code's (and Copilot's) native plugin installer has zero awareness of .apm/ nesting -- it convention-scans only flat skills/, agents/, commands/, hooks.json at each plugin's root. Confirmed via strings on the installed claude binary and live installs of git@holocron/gitea@holocron/kyberforge@ holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json compiler deliberately strips skills/agents/commands keys, assuming the host already auto-discovers those convention directories -- it has no model of .apm/ being host-visible at all. Separately, apm's own bundle exporter (apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`) implements the correct .apm/ -> flat mapping, but only ever targeted build/<name>-<version>/, a path nothing in marketplace.json's source: points at. scripts/sync-plugin-content.sh wraps that bundle exporter and copies its agents/, skills/, commands/, instructions/, extensions/, and merged hooks.json back into each plugin's own root as a second tracked compiled-output category -- same governance status as .claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/ subdirectories are excluded from the mirror (dev fixtures, not host-visible runtime content; several hardcode a relative repo-root walk-up sized for the .apm/-nested depth, which breaks when duplicated one level shallower). Applied for real across all 6 plugins and verified two ways: `claude plugin validate --strict` passes on every real plugin directory, and a live `claude --plugin-dir <path> -p "list skills/agents"` behavioral test confirms content is now actually discovered. Also, from the same issue #90 review round: - scripts/check-manifests.sh pointed at each plugin's root-level plugin.json (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a stale near-duplicate of .claude-plugin/plugin.json nothing else read or wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to validate .claude-plugin/plugin.json instead, and drops the pointer-field checks entirely (nothing to check -- those fields are correctly absent by design). Content-presence drift is now check-plugin-content-sync's job, a new pre-push hook wired in .pre-commit-config.yaml. docs/adr/0017 records the root cause and decision in full, including two rejected alternatives (patching plugin.json's path fields directly -- apm's compiler strips them on every run; pointing marketplace.json at apm pack's build/ output -- a version-suffixed non-source directory nothing can install from without an extra build step). ADR-0015 and CONTEXT.md are updated to point at it. Refs: #90
This commit is contained in:
120
plugins/git/skills/pc-author/references/hooks-by-language.md
Normal file
120
plugins/git/skills/pc-author/references/hooks-by-language.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
source_keys:
|
||||
- context7-pre-commit-com
|
||||
- pre-commit-com
|
||||
- context7-pre-commit-hooks
|
||||
- pre-commit-hooks-github
|
||||
---
|
||||
|
||||
# Hook Recommendations by Language / Context
|
||||
|
||||
Use this table when creating a config from scratch or recommending hooks to add.
|
||||
Always check the existing config for duplicates before proposing.
|
||||
|
||||
## Universal (recommend for every repo)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `end-of-file-fixer` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Ensures files end with a newline — prevents spurious diffs |
|
||||
| `trailing-whitespace` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Strips trailing whitespace — prevents invisible diff noise |
|
||||
| `check-merge-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches unresolved merge markers before commit |
|
||||
| `detect-private-key` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks PEM private key material |
|
||||
| `check-added-large-files` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks accidentally committing large binary files |
|
||||
| `check-case-conflict` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Catches filenames that would collide on case-insensitive filesystems |
|
||||
| `mixed-line-ending` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Normalizes line endings |
|
||||
| `no-commit-to-branch` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Blocks direct commits to protected branches — defaults to blocking `main`+`master` with no args; add `args: [--branch, <name>]` only to protect additional branch names |
|
||||
|
||||
## Shell (`.sh`)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `shellcheck` | `https://github.com/jumanjihouse/pre-commit-hooks` | `3.0.0` | **Unverified — not in research corpus, verify upstream before use.** Static analysis for shell scripts; catches common errors |
|
||||
|
||||
Recommended args: `args: [--severity=warning]`
|
||||
|
||||
## Python (`.py`)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `check-ast` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates Python files parse as valid AST |
|
||||
| `check-builtin-literals` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Enforces literal syntax for `dict()`, `list()` |
|
||||
|
||||
For formatting: check if `black`, `ruff`, or `isort` is already configured in `pyproject.toml` before recommending them.
|
||||
|
||||
## JSON (`.json`)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `check-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates JSON parses correctly |
|
||||
| `pretty-format-json` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Auto-formats JSON (fixer — warns user to re-stage after commit) |
|
||||
|
||||
## YAML (`.yaml`, `.yml`)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `check-yaml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates YAML parses correctly |
|
||||
|
||||
For Kubernetes/Helm YAML with custom tags, add `args: ['--unsafe']` and `exclude: ^helm/templates/`.
|
||||
|
||||
## TOML (`.toml`)
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `check-toml` | `https://github.com/pre-commit/pre-commit-hooks` | `v6.0.0` | Validates TOML parses correctly |
|
||||
|
||||
## Secrets / security
|
||||
|
||||
| Hook ID | Repo | Rev | Rationale |
|
||||
|---------|------|-----|-----------|
|
||||
| `gitleaks` | `https://github.com/gitleaks/gitleaks` | `v8.30.1` | **Unverified — not in research corpus, verify upstream before use.** Scans for secrets and high-entropy strings |
|
||||
|
||||
## Commit message
|
||||
|
||||
| Hook ID | Repo | Rev | Stage | Rationale |
|
||||
|---------|------|-----|-------|-----------|
|
||||
| `conventional-pre-commit` | `https://github.com/compilerla/conventional-pre-commit` | `v2.4.0` | `commit-msg` | Enforces Conventional Commits format |
|
||||
|
||||
When adding commit-msg hooks, also add `default_install_hook_types: [pre-commit, commit-msg]` to the top-level config if not already present.
|
||||
|
||||
## Meta-validation (add last, after all other repos)
|
||||
|
||||
```yaml
|
||||
- repo: meta
|
||||
hooks:
|
||||
- id: check-hooks-apply # catches hooks that match no files
|
||||
- id: check-useless-excludes # catches exclude patterns that match no files
|
||||
```
|
||||
|
||||
## Local hooks (repo: local)
|
||||
|
||||
Use for repo-specific scripts that don't belong in an external hook repo.
|
||||
|
||||
```yaml
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: run-tests
|
||||
name: Run test suite
|
||||
entry: bash tests/run-tests.sh
|
||||
language: unsupported_script
|
||||
pass_filenames: false
|
||||
always_run: true
|
||||
stages: [pre-push]
|
||||
```
|
||||
|
||||
Language choices for local hooks:
|
||||
- `unsupported` — system PATH tool (pre-commit does not manage env)
|
||||
- `unsupported_script` — script at a repo-relative path
|
||||
- `fail` — always-fail guard; `entry` text becomes the error message
|
||||
- `python` — isolated venv; use `additional_dependencies` for pip packages
|
||||
- `node` — isolated node env; `additional_dependencies` are npm packages
|
||||
- `ruby` — isolated gem env; `additional_dependencies` are gems
|
||||
- `golang` — builds from source; `additional_dependencies` are Go module paths
|
||||
- `rust` — Cargo build
|
||||
- `docker` — Docker image built from `entry`; use when no other language fits
|
||||
- `docker_image` — pulls a pre-built Docker image by `entry`
|
||||
- `conda` — Conda environment; conda-native hooks
|
||||
- `coursier` — Coursier (Scala/JVM) environment; JVM hooks
|
||||
|
||||
## Rev pin freshness
|
||||
|
||||
The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since `pc-author`'s "Rev staleness" check treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
|
||||
Reference in New Issue
Block a user