diff options
| -rw-r--r-- | AGENTS.md | 110 |
1 files changed, 109 insertions, 1 deletions
@@ -43,12 +43,24 @@ Each package lives in its own top-level subfolder: --- +## Packages Maintained Elsewhere + +Several packages that used to live in this repo are now danix-official on +SlackBuilds.org and maintained in the separate +[sbo-slackbuilds](https://github.com/danixland/sbo-slackbuilds) repo: +`ffuf`, `gobuster`, `nuclei`, `feroxbuster`, `metasploit-framework-bin`, +`SecLists`, and `exploitdb`. Do not modify those packages here; changes +to them belong in `sbo-slackbuilds`. + +--- + ## Package Build Strategies Before updating or adding a package, identify which build strategy it uses: | Strategy | Examples | Key indicator | |----------|----------|---------------| +| Python source | netexec | `python3 -m build`, `python3.SlackBuild` | | Go source | ffuf, gobuster, nuclei | `go build`, `REQUIRES="google-go-lang"` | | Autotools/cmake source | hydra, cadaver | `./configure` or `cmake` | | Binary repack (.deb) | metasploit-framework-bin | `ar p … data.tar.gz \| tar xzv` | @@ -150,9 +162,79 @@ Then proceed: --- +## Version Sweep + +The `.extras/nvchecker.toml` file tracks upstream versions for all packages +in the suite (both in-repo and sbo-slackbuilds). A sweep compares upstream +against what this repo carries and identifies packages that need updating. + +### Procedure + +1. Generate a throwaway nvchecker config in the scratchpad (`/tmp/opencode/`) + that prepends a `[__config__]` section pointing at the personal keyfile + (`~/.config/nvchecker/keys.toml`, provides a GitHub token for 5000 req/h) + plus scratchpad `oldver`/`newver` paths, then appends the stanzas from + `.extras/nvchecker.toml`. + +2. Run `nvchecker -c <throwaway-config>` on the throwaway config. With a + fresh `oldver`, every stanza reports "updated to X" — that is the + *upstream* version, not a diff. + +3. For each **in-repo** package (cadaver, netexec, windows-binaries, + webshells), compare the reported upstream version against the `VERSION=` + in that package's `.info` file. Packages maintained in `sbo-slackbuilds` + are out of scope for this repo's sweep. + +4. Update `LAST_SWEEP` (gitignored) with the date and a table showing + carried version, upstream version, and status (current / needs bump) + for each in-repo package. + +5. For any package that needs a bump, follow the Mandatory Workflow: + Updating a Package Version above. + +### Important notes + +- Never run `nvchecker -c .extras/nvchecker.toml` directly — the tracked + config has no `[__config__]`, so GitHub stanzas hit the anonymous rate + limit (60 req/h) and 403. +- Probe a single package with `nvchecker -c <config> -e <name>` when + testing a specific stanza. +- Never audit GitHub repos with raw `curl` loops — a burst burns the + anonymous quota and later calls 403. + +--- + ## SlackBuild Scripting Rules -- Base all scripts on the SBo template: https://slackbuilds.org/templates/ +### Templates (source of truth) + +Local templates live in `~/Templates/SlackBuilds/`. Always start from the +matching template there rather than writing a SlackBuild or its accompanying +files from scratch. The directory holds per-build-type SlackBuild templates +(`autotools-template.SlackBuild`, `cmake-template.SlackBuild`, +`go-template.SlackBuild`, `python-template.SlackBuild`, etc.) and shared +support files (`slack-desc`, `template.info`, `doinst.sh`, `README`). + +When the local template and the upstream SBo template disagree, the local one +wins. Only fall back to the [SBo template](https://slackbuilds.org/templates/) +if no local template fits. + +The `sbo/` and `conraid/` subdirectories are git clones kept up to date by +`~/Templates/SlackBuilds/update-templates.sh`. Run that script (or let the +desktop autostart handle it) before starting work on a new package to ensure +templates reflect the latest upstream conventions. + +### Copyright line + +In every `.SlackBuild`, the maintainer copyright line is exactly: + +``` +# Copyright <year> danix <danix@danix.xyz> +``` + +### General rules + +- Base all scripts on the local templates above; fall back to the SBo template: https://slackbuilds.org/templates/ - Use `set -e` (abort on error). - Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT`; provide defaults if unset. - Detect `$ARCH` and set `SLKCFLAGS` and `LIBDIRSUFFIX` accordingly. @@ -269,6 +351,32 @@ Commit conventions: --- +## Git Hooks + +Versioned source lives in `.extras/hooks/`. After a fresh clone, install them: + +```bash +cp .extras/hooks/* .git/hooks/ && chmod 0755 .git/hooks/{pre,post}-commit +``` + +- `pre-commit` — runs `sbolint` on each changed package; aborts the commit on + any error. Also auto-removes staged source-archive symlinks and blocks + staged regular source archives (`*.tar.*`, `*.zip`, `*.deb`, etc.). Skip + with `SBOLINT=no git commit ...`. +- `post-commit` — for each added/updated `*.SlackBuild`, offers to build the + SBo submission tarball into `SBo/<package>.tar.gz`. + +### `SBO_ARCHIVE` (non-interactive archive answer) + +`post-commit` normally prompts on a TTY. To answer without one (agents, +scripts), set `SBO_ARCHIVE`: + +- `SBO_ARCHIVE=yes git commit ...` — build the tarball, no prompt +- `SBO_ARCHIVE=no git commit ...` — skip, no prompt +- unset + TTY → interactive prompt; unset + no TTY → skip + +--- + ## What Requires User Confirmation Stop and ask before doing any of the following: |