diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 0000000..456d00a --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,103 @@ +// Add the Gitea webhook configured for this Jenkins installation. + +pipeline { + agent { label 'rust_nodocker' } + + options { + disableConcurrentBuilds() + skipDefaultCheckout(true) + } + + environment { + ASSET_SOURCE_DIR = 'tasks' + ASSET_PUBLISH_ROOT = '/mnt/assets/agent-tasks' + } + + stages { + stage('Checkout') { + steps { + deleteDir() + checkout scm + } + } + + stage('Validate publishable tasks') { + steps { + sh ''' + set -eu + + test -d "${ASSET_SOURCE_DIR}" || { + echo "ERROR: ${ASSET_SOURCE_DIR} is not a directory." >&2 + exit 1 + } + + invalid_type=$(find "${ASSET_SOURCE_DIR}" ! -type d ! -type f -print -quit) + test -z "${invalid_type}" || { + echo "ERROR: publishable assets must be regular files: ${invalid_type}" >&2 + exit 1 + } + + task_count=0 + for task in "${ASSET_SOURCE_DIR}"/*.task.md; do + test -e "${task}" || continue + test -f "${task}" && test ! -L "${task}" && test -s "${task}" || { + echo "ERROR: task must be a nonempty regular file: ${task}" >&2 + exit 1 + } + task_count=$((task_count + 1)) + done + + test "${task_count}" -gt 0 || { + echo "ERROR: no publishable *.task.md files were found." >&2 + exit 1 + } + + unexpected=$(find "${ASSET_SOURCE_DIR}" -mindepth 1 \ + \( ! -type f -o ! -name '*.task.md' \) -print -quit) + test -z "${unexpected}" || { + echo "ERROR: unexpected file in ${ASSET_SOURCE_DIR}: ${unexpected}" >&2 + exit 1 + } + + echo "Validated ${task_count} task files for publication." + ''' + } + } + + stage('Publish assets') { + when { + branch 'main' + } + steps { + sh ''' + set -eu + + case "${ASSET_PUBLISH_ROOT}" in + /*) ;; + *) + echo "ERROR: ASSET_PUBLISH_ROOT must be absolute." >&2 + exit 1 + ;; + esac + + mkdir -p "${ASSET_PUBLISH_ROOT}" + chmod 0755 "${ASSET_PUBLISH_ROOT}" + + for source in "${ASSET_SOURCE_DIR}"/*.task.md; do + name=${source##*/} + destination="${ASSET_PUBLISH_ROOT}/${name}" + temporary="${destination}.tmp-${BUILD_NUMBER}-$$" + + trap 'rm -f "${temporary}"' 0 1 2 3 15 + cp "${source}" "${temporary}" + chmod 0644 "${temporary}" + mv "${temporary}" "${destination}" + trap - 0 1 2 3 15 + done + + echo "Published task files below ${ASSET_PUBLISH_ROOT}." + ''' + } + } + } +} diff --git a/README.md b/README.md index fc5f9ed..7098779 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,37 @@ # agent-tasks -Repository adding agent tasks/prompts that I'm not keen on repeating over and over again \ No newline at end of file +Reusable task briefs for coding agents. Each brief captures a repeatable change, +its constraints, and the checks needed before handoff, so project-specific work +does not have to start from an improvised prompt. + +## Available tasks + +- [`ci-coverage-badges.task.md`](tasks/ci-coverage-badges.task.md) adds + project-native coverage and publishes current version, test, and coverage + badges without assuming a particular repository or build tool. +- [`semi-harden-ci.task.md`](tasks/semi-harden-ci.task.md) adds the focused + `cargo audit` and `cargo deny` gates to any Cargo-based Rust project. + +Copy the relevant brief into an agent session or reference it from a project +task. The receiving agent must still read that project's own instructions and +adapt the brief to its existing CI, tools, metadata, and commit conventions. + +## Publishing + +The `tasks/` directory is also the publication contract. Jenkins validates that +it contains only nonempty, regular `*.task.md` files. On `main`, it copies each +file atomically to: + +```text +/mnt/assets/agent-tasks/.task.md +``` + +The files are then available at: + +```text +https://assets.dandaedre.com/agent-tasks/.task.md +``` + +Other branches are validated but are not published. Publication intentionally +does not delete files from the shared asset mount, so removing or renaming a +task requires a separate, explicitly approved cleanup of its old public file. diff --git a/tasks/ci-coverage-badges.task.md b/tasks/ci-coverage-badges.task.md new file mode 100644 index 0000000..92dfce2 --- /dev/null +++ b/tasks/ci-coverage-badges.task.md @@ -0,0 +1,152 @@ +# Publish current CI badges through the assets mount + +Apply this task to one repository at a time. Read the repository's local agent +instructions, inspect its existing CI and coverage setup, preserve unrelated +work, and follow its commit policy. Do not push or publish outside CI unless the +user explicitly requests it. + +## Goal + +Make the default branch expose three small, current SVG badges: + +```text +/coverage////version.svg +/coverage////test.svg +/coverage////coverage.svg +/coverage////version.svg +/coverage////test.svg +/coverage////coverage.svg +``` + +Discover the canonical owner, project name, default branch, asset mount, and +public asset origin from repository or CI configuration. Do not infer them only +from the local checkout directory. Keep the default-branch component stable; +these URLs describe the latest default-branch build, not an immutable commit. + +Retain only the three badges as Jenkins artifacts. Do not publish or retain +commit-addressed coverage directories, HTML, JSON, LCOV, or other detailed +reports unless the repository already has a separate requirement for them. + +## CI behavior + +1. Use the project's established test and line-coverage tools. Pin tools that + CI installs itself, and keep tool configuration in the conventional tracked + project file. +2. Enforce an honest coverage floor supported by useful behavior tests. Do not + exclude ordinary production code or distort code or tests to increase the + percentage. +3. Produce a temporary machine-readable coverage summary, extract and validate + a numeric percentage from 0 through 100, render `coverage/coverage.svg`, and + remove the summary. +4. Read the version from authoritative package or build metadata and render + `coverage/version.svg`. Do not duplicate the version in CI configuration. +5. Write a build-specific marker only after the test stage succeeds. In an + always-run cleanup action, render `coverage/test.svg` as `passing` only when + that marker exists; otherwise render it as `failing`. Remove the marker + afterward so an old workspace cannot affect a later build. +6. If coverage did not complete, render a neutral `-%` badge during cleanup. + Cleanup must run for both successful and failed builds so published status + cannot silently remain stale. +7. Archive exactly the three nonempty SVG files with fingerprinting on every + branch. Publish them only from the default branch. A missing or unwritable + publication mount is a CI failure. +8. Keep rendering and filesystem publication in small tracked scripts rather + than large Jenkins shell blocks. Use the repository's existing scripting + language when suitable; otherwise use portable POSIX `sh`. + +Update the Jenkins success and failure summaries to mention tests, coverage, +badge generation, and any other gates that the pipeline actually runs. + +## Renderer contract + +Render badges locally and deterministically. Do not call an external badge +service. + +- The version renderer accepts only characters valid for the project's version + format, grows the value segment for long versions, and enforces a sensible + minimum width. +- The test renderer accepts only `passing` or `failing` and selects green or + red respectively. +- The coverage renderer accepts `-` or a number from 0 through 100, rounds + numeric values, and selects documented green, yellow, red, or neutral colors. +- Reject invalid input before creating or replacing output. +- Escape all text inserted into XML. +- Center labels and values horizontally with `text-anchor="middle"`. In a + 20-pixel badge, center text vertically at `y="10"` with + `dominant-baseline="middle"` instead of treating `y` as a font baseline. +- When POSIX `awk` prints a conditional expression, parenthesize it, for example + `print (width < 45 ? 45 : width)`, so the expression also works with FreeBSD + awk. + +## Publication contract + +The publication script receives the publication root and an explicit +allow-listed set of badge names. It must: + +- require an absolute publication root and validate all arguments before + changing published state; +- create only the required owner, project, and default-branch directories; +- publish only `coverage.svg`, `test.svg`, and `version.svg` below the resolved + default-branch directory; +- verify every selected source badge exists, is a regular nonempty file, and is + not a symlink; +- migrate an old default-branch symlink by unlinking the symlink itself without + deleting its target, and reject any other non-directory branch destination; +- make directories mode `0755` and badges mode `0644` so the web server can + traverse and read them even under a restrictive umask; +- copy each badge to a temporary file in its destination directory and rename + it atomically over the public file; +- clean temporary files on ordinary failures and signals; +- quote paths and remain portable to the Jenkins worker's operating system; +- never recursively synchronize, prune, or delete the shared asset mount. + +Do not automatically remove old commit-addressed directories. That is a +separate destructive migration requiring explicit authorization and exact path +verification. + +## Repository updates + +Place the live badges immediately below the README title, substituting the +resolved values: + +```markdown +![version](/coverage////version.svg) +![tests](/coverage////test.svg) +![test coverage](/coverage////coverage.svg) +``` + +Do not link them to a report that CI does not retain. Document the local +coverage command, enforced floor, version source, temporary summary, archived +files, publication path, and public URLs. Remove tracked generated badge files +and obsolete status snapshots. + +If this task also owns the web-server configuration, mount public assets +read-only, disable directory listing, serve SVG with a restrictive content +security policy, and revalidate or use a short cache lifetime for mutable badge +URLs. Otherwise record these as deployment requirements without expanding the +repository change into unrelated infrastructure work. + +## Verification + +Before committing: + +1. Run the repository's formatting, build/check, test, lint, and supported + toolchain gates relevant to the change. +2. Run the exact CI coverage command and confirm the enforced floor. +3. Confirm the temporary summary yields a valid percentage, is removed, and + exactly three nonempty SVGs are selected for archival. +4. Exercise normal and long versions, passing and failing test states, green, + yellow, red, and neutral coverage, and invalid input rejection. +5. Parse every rendered file as XML and rasterize representative badges to + inspect text placement. +6. Test publication with `umask 077` against a temporary absolute root. Verify + modes, atomic replacement, idempotence, and old-symlink migration without + deleting the old target. +7. Verify rejection of missing badges, relative roots, unwritable + destinations, and regular-file branch destinations. +8. Validate Jenkins syntax as far as local tooling permits, inspect the final + diff, commit the change, and confirm the worktree is clean. + +Report the measured coverage, enforced floor, checks run, commit ID, and any +checks unavailable locally. Do not claim the public badges are live until a +successful default-branch Jenkins build has published them. diff --git a/tasks/semi-harden-ci.task.md b/tasks/semi-harden-ci.task.md new file mode 100644 index 0000000..36161a0 --- /dev/null +++ b/tasks/semi-harden-ci.task.md @@ -0,0 +1,82 @@ +# Add Cargo audit and dependency-policy gates to CI + +Apply this task to one Cargo-based Rust repository at a time. Read its local +agent instructions, preserve unrelated work, follow its commit policy, and do +not push unless explicitly requested. Adapt names and documentation to the +repository; do not copy identifiers, paths, versions, or branch names from a +different project. + +## Scope + +Add exactly these two supply-chain gates: + +1. `cargo audit` for RustSec vulnerabilities, unmaintained or unsound + advisories, and yanked lockfile entries; +2. `cargo deny` for dependency licenses, sources, wildcard requirements, + duplicate-version visibility, and its advisory check. + +Do not add `cargo vet`, SBOM generation, vendoring, registry proxies, +provenance tools, or other security scanners as part of this task. + +## Implementation + +1. Confirm that `Cargo.lock` is tracked and that ordinary CI Cargo commands use + `--locked`. +2. Determine the current stable `cargo-audit` and `cargo-deny` releases from + their official upstream sources when applying the task. Pin both versions in + CI, and install them with `cargo install --locked --version ...` only when + the installed version does not exactly match the pin. +3. Add a dedicated CI stage for each command after checkout and tool setup but + before build, test, coverage, packaging, or publication: + + ```sh + cargo audit --deny warnings + cargo deny check + ``` + + Both stages require network access to refresh advisory and registry data and + must fail the build on findings or tool errors. Do not silently accept a + stale advisory database. +4. Add a tracked `deny.toml` using the schema supported by the pinned + `cargo-deny` version: + + - inspect the resolved dependency graph and allow only licenses it currently + needs; + - set license confidence to `0.8`; + - deny wildcard requirements; + - warn on duplicate versions so they remain visible without making every + duplicate a vulnerability; + - deny unknown registries and unknown Git sources; + - explicitly allow crates.io and allow no Git sources; + - enable all features for dependency-graph construction; + - begin with empty advisory ignores, crate bans, duplicate skips, license + exceptions, and license clarifications. +5. Do not add an exception merely to make CI green. If a real finding prevents + completion, report the advisory, crate, or license and its dependency path. + Every exception needs an explicit user decision, a reason, and a removal + condition. +6. Document the pinned versions, exact local commands, network requirement, + enforced policy, and limits of both tools in the repository's existing + development or security documentation. State that no other hardening tools + are in scope. +7. Update CI success and failure summaries so both gates are visible, while + preserving all unrelated existing checks. + +## Verification + +Run, in this order: + +```sh +cargo audit --deny warnings +cargo deny check +cargo fmt --all -- --check +cargo check --locked --all-targets --all-features +cargo test --locked --all-targets --all-features +cargo clippy --locked --all-targets --all-features -- -D warnings +``` + +Also run repository-specific MSRV, documentation, or packaging gates. Review +`cargo deny` warnings instead of hiding them; duplicate-version warnings are +expected only when unavoidable transitive constraints explain them. Commit the +completed repository change and report tool versions, findings, checks, and the +commit ID.