You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/07/03 16:09:03 UTC
(magpie) branch main updated: Document adapter README authoring fields (#699)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new b1e9da03 Document adapter README authoring fields (#699)
b1e9da03 is described below
commit b1e9da036436e3f057c7bc17a00ddf3345d628b3
Author: Justin Mclean <ju...@classsoftware.com>
AuthorDate: Sat Jul 4 02:08:58 2026 +1000
Document adapter README authoring fields (#699)
Generated-by: Claude (Opus 4.7)
---
tools/apache-projects/README.md | 9 +++++++++
tools/cve-org/README.md | 10 ++++++++++
tools/cve-tool-vulnogram/README.md | 17 +++++++++++++++++
tools/github-body-field/README.md | 9 +++++++++
tools/github-rollup/README.md | 9 +++++++++
tools/github/README.md | 11 +++++++++++
tools/mail-source/README.md | 8 ++++++++
tools/ponymail/README.md | 10 ++++++++++
tools/vcs/README.md | 10 ++++++++++
9 files changed, 93 insertions(+)
diff --git a/tools/apache-projects/README.md b/tools/apache-projects/README.md
index 4981d084..7b2a1fe0 100644
--- a/tools/apache-projects/README.md
+++ b/tools/apache-projects/README.md
@@ -4,6 +4,7 @@
- [`tools/apache-projects/`](#toolsapache-projects)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -37,3 +38,11 @@ operation catalogue, setup, and the track-`main` install contract.
- **CLIs:** `git` (clone the `apache/comdev` checkout), `npm` (install the server's deps), `node` (run it).
- **Credentials / auth:** None — the server is read-only and unauthenticated; every field it returns is already public.
- **Network:** `projects.apache.org` (the public JSON feeds the server fetches at run time); `github.com` to clone and track `apache/comdev` at `main`.
+
+## Configuration
+
+Adopters select this backend through `<project-config>/project.md` or
+their organization defaults under the `project_metadata` block. ASF
+projects inherit `project_metadata.kind: apache-projects-mcp` from
+`organizations/ASF/organization.md`; non-ASF projects normally set
+`project_metadata.kind: none` and supply roster evidence directly.
diff --git a/tools/cve-org/README.md b/tools/cve-org/README.md
index 34a1121c..8fb06a84 100644
--- a/tools/cve-org/README.md
+++ b/tools/cve-org/README.md
@@ -4,6 +4,7 @@
- [`tools/cve-org/`](#toolscve-org)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -26,3 +27,12 @@ CVE.org publication client. Submits CVE records via the CVE.org REST API; consum
- **CLIs:** `curl` and `jq`.
- **Credentials / auth:** None — cve.org is the public CVE registry and the CVE Services API has no auth.
- **Network:** `cveawg.mitre.org` (CVE Services API v2) and `www.cve.org` (the HTML record); optionally `nvd.nist.gov` for the alternative public registry.
+
+## Configuration
+
+Adopters select this backend with `<project-config>/project.md` →
+`cve_authority.tool: cve-org-direct` when they operate directly against
+CVE Services rather than an ASF Vulnogram tenant. The adopter-facing
+field vocabulary is documented in
+`projects/_template/cve-allocation-config.md` and
+`projects/_template/security-intake-config.md`.
diff --git a/tools/cve-tool-vulnogram/README.md b/tools/cve-tool-vulnogram/README.md
index 36f15457..a2c1722a 100644
--- a/tools/cve-tool-vulnogram/README.md
+++ b/tools/cve-tool-vulnogram/README.md
@@ -4,6 +4,8 @@
- [`tools/cve-tool-vulnogram/`](#toolscve-tool-vulnogram)
- [Prerequisites](#prerequisites)
+ - [Operations](#operations)
+ - [Configuration](#configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -28,3 +30,18 @@ ASF Vulnogram CVE-allocation client. OAuth-authenticated API that allocates a CV
- **CLIs:** `gh` (authenticated) — `generate-cve-json` shells out to it for tracker/GitHub access.
- **Credentials / auth:** `gh auth status` must pass; the Vulnogram API helpers read a session token at `~/.config/apache-magpie/vulnogram-session.json` (mode `0600`, created by `vulnogram-api-setup`).
- **Network:** `cveprocess.apache.org` (Vulnogram session API) and `api.github.com` (via `gh`).
+
+## Operations
+
+This adapter implements the `tools/cve-tool/` CVE-authority contract for
+ASF Vulnogram. The operation details live in [`allocation.md`](allocation.md)
+for CVE ID allocation, [`record.md`](record.md) for record state changes,
+and [`tool.md`](tool.md) for the shared protocol.
+
+## Configuration
+
+Adopters select this backend with `<project-config>/project.md` →
+`cve_authority.tool: vulnogram`. The same block supplies the tenant URLs,
+state names, reviewer channel, and publication signal fields documented in
+`projects/_template/cve-allocation-config.md` and
+`projects/_template/security-intake-config.md`.
diff --git a/tools/github-body-field/README.md b/tools/github-body-field/README.md
index ca4d0322..fc342233 100644
--- a/tools/github-body-field/README.md
+++ b/tools/github-body-field/README.md
@@ -4,6 +4,7 @@
- [github-body-field](#github-body-field)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
- [Why](#why)
- [Invocation](#invocation)
- [`get <issue> --field "<name>"`](#get-issue---field-name)
@@ -35,6 +36,14 @@ body **without bringing the body into agent context**.
- **Credentials / auth:** an authenticated `gh` session (`gh auth status` must pass) — the body read / parse / replace / push all go through `gh`.
- **Network:** `api.github.com` via `gh`.
+## Configuration
+
+This helper has no persistent config file of its own. Callers pass
+`--repo <tracker>` from `<project-config>/project.md` and the field names
+declared by the adopter's tracker configuration, such as
+`<project-config>/issue-tracker-config.md` or sibling
+`*-config.md` files that define tracker body fields.
+
## Why
Tracker issues in `<tracker>` carry a structured body — a list of
diff --git a/tools/github-rollup/README.md b/tools/github-rollup/README.md
index 8cdbde22..4f724190 100644
--- a/tools/github-rollup/README.md
+++ b/tools/github-rollup/README.md
@@ -4,6 +4,7 @@
- [github-rollup](#github-rollup)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
- [Why](#why)
- [Invocation](#invocation)
- [`append <issue> --action "<label>" ...`](#append-issue---action-label-)
@@ -34,6 +35,14 @@ issue **without bringing the rollup body into agent context**.
- **Credentials / auth:** an authenticated `gh` session (`gh auth status` must pass) — the comment read / append / PATCH all go through `gh`.
- **Network:** `api.github.com` via `gh`.
+## Configuration
+
+This helper has no persistent config file of its own. Callers pass the
+target issue from `<project-config>/project.md` → `tracker_repo`; the
+status-rollup comment format is the GitHub tracker convention documented
+in `tools/github/status-rollup.md` and reused by security lifecycle
+skills.
+
## Why
Every skill that updates a `<tracker>` issue (import receipt,
diff --git a/tools/github/README.md b/tools/github/README.md
index 809c6492..f6b9ce32 100644
--- a/tools/github/README.md
+++ b/tools/github/README.md
@@ -4,6 +4,7 @@
- [`tools/github/`](#toolsgithub)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -28,3 +29,13 @@ This tool implements three capability contracts: `contract:tracker` (issues / bo
- **CLIs:** `gh` (authenticated), `git` (source-control capability), `jq` (used via `gh api --jq`).
- **Credentials / auth:** `gh auth status` must show a logged-in user with the needed scopes — every skill's Step 0 runs it.
- **Network:** `api.github.com` (REST + GraphQL) and `github.com` (the `git` remote); source-control recipes are offline except explicit `fetch` / `push`.
+
+## Configuration
+
+Adopters select GitHub-backed tracker, source-control, and
+change-request behavior through `<project-config>/project.md` repository
+keys such as `tracker_repo`, `upstream_repo`, and the source-control /
+change-request entries in the *Tools enabled* table. GitHub issue body
+fields, labels, project-board IDs, and PR-management knobs live in the
+matching `<project-config>/*-config.md` files documented from
+`projects/_template/README.md`.
diff --git a/tools/mail-source/README.md b/tools/mail-source/README.md
index fdbbcdc7..70e37b63 100644
--- a/tools/mail-source/README.md
+++ b/tools/mail-source/README.md
@@ -5,6 +5,7 @@
- [`tools/mail-source/`](#toolsmail-source)
- [Prerequisites](#prerequisites)
- [Security and privacy](#security-and-privacy)
+ - [Operations](#operations)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -39,3 +40,10 @@ prompt-injection attempts in inbound mail are surfaced to the maintainer for
human review, not obeyed. Concrete backends must each apply the same
posture (see [`tools/gmail/`](../gmail/), [`tools/mail-source/imap/`](imap/),
[`tools/mail-source/mbox/`](mbox/)).
+
+## Operations
+
+The backend-neutral interface is documented in [`contract.md`](contract.md).
+Concrete backend operations live in the selected adapter directory, such as
+[`../gmail/`](../gmail/), [`../ponymail/`](../ponymail/),
+[`imap/`](imap/), or [`mbox/`](mbox/).
diff --git a/tools/ponymail/README.md b/tools/ponymail/README.md
index 692ceea3..e9be4425 100644
--- a/tools/ponymail/README.md
+++ b/tools/ponymail/README.md
@@ -5,6 +5,7 @@
- [`tools/ponymail/`](#toolsponymail)
- [Prerequisites](#prerequisites)
- [Security and privacy](#security-and-privacy)
+ - [Configuration](#configuration)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -38,3 +39,12 @@ by an untrusted sender. Skills route PonyMail content through structured
report fields; raw bodies are never passed to the model as framework
directives. Embedded prompt-injection attempts in archived threads are
surfaced to the maintainer for human review, not obeyed.
+
+## Configuration
+
+Adopters select PonyMail through `<project-config>/project.md` mail-source
+rows and the `archive_system` block, or inherit it from
+`organizations/ASF/organization.md`. The template documents PonyMail
+URL keys such as `ponymail_private_search_url_template`,
+`ponymail_public_search_url_template`, and `ponymail_thread_url_template`
+in the `project.md` *Mail sources* section.
diff --git a/tools/vcs/README.md b/tools/vcs/README.md
index 3e711806..0c854fa9 100644
--- a/tools/vcs/README.md
+++ b/tools/vcs/README.md
@@ -3,6 +3,7 @@
- [`magpie-vcs`](#magpie-vcs)
- [Prerequisites](#prerequisites)
+ - [Configuration](#configuration)
- [Why](#why)
- [The abstraction](#the-abstraction)
- [Backends](#backends)
@@ -52,6 +53,15 @@ VCS the project enables under *Tools enabled → Source control*.
- **Network:** Local for read and local-write operations; `fetch` / `push`
reach the project's remote (e.g. GitHub) over the network.
+## Configuration
+
+The active backend is detected from the working copy or forced with
+`--backend` / `$MAGPIE_VCS`. Skills get the checkout path from
+`<project-config>/user.md` (or the resolved user config) and the expected
+source-control backend from `<project-config>/project.md` *Tools enabled*
+entries. Backend-specific adopter knobs belong in the relevant
+`*-config.md` file rather than in this tool.
+
## Why
Before this tool the skills hard-coded `git …` inline. PR #609 added