Skip to content

docs: add acli-axi to community catalog - #119

Open
mathieu-neron wants to merge 1 commit into
kunchenguid:mainfrom
mathieu-neron:acli-axi-contribution
Open

docs: add acli-axi to community catalog#119
mathieu-neron wants to merge 1 commit into
kunchenguid:mainfrom
mathieu-neron:acli-axi-contribution

Conversation

@mathieu-neron

Copy link
Copy Markdown

Intent

The developer asked for a security review of a small, already-prepared change that adds their own tool, acli-axi, to the AXI community catalog. The change consists of one new entry in catalog.yaml (name, GitHub URL, author, domain Jira, description) plus the matching generated table row in docs/index.html. Their intent was to have the addition checked for security vulnerabilities before committing it, treating the catalog data and rendered HTML as the review scope. No other requirements or constraints were stated; the review found the entry to be inert data flowing through the repo's existing URL-validation and HTML-escaping pipeline, with no issues.

What Changed

  • Added an acli-axi entry (author mathieu-neron, domain Jira, repo github.com/mathieu-neron/acli-axi) to the community list in catalog.yaml.
  • Regenerated the matching rows in the generated:catalog-community regions of README.md and docs/index.html; pnpm run docs:check confirms no drift between the source and the generated output.
  • Data-only change — no code paths touched. The entry flows through the existing URL-protocol validation and HTML-escaping in scripts/generate-docs.mjs. Review left one informational note: the pinned-revision source-admission verdict required by VISION.md is a maintainer gate outside this branch's files.

Risk Assessment

✅ Low: Purely additive inert catalog data plus its machine-generated README/HTML rows, flowing through the existing safeUrl/HTML-escaping generator with no drift and no executable surface.

Testing

Exercised the catalog-to-docs pipeline for the new acli-axi entry rather than just the diff text: docs:check proved the committed README/index.html generated regions are exactly what the generator emits from catalog.yaml, the generator's own escaping and protocol-allowlist tests passed, and a purpose-written check ran the real entry plus hostile mutations of it through the same render functions — the real entry produces only an https github.com anchor and escaped text, while a javascript: URL is rejected and injected script/img/event-handler payloads come out escaped. A headless-Chrome screenshot of docs/index.html shows the row as an end user sees it (acli-axi / mathieu-neron / Jira, with acli rendered as a code span). No failures; worktree left clean.

  • Evidence: Rendered docs/index.html — Community catalog table with the new acli-axi row (last row) (local file: /var/folders/1c/ldynyg5j3xb96xmd8w3c6h300000gn/T/no-mistakes-evidence/01KYVB7DESXDG2E5XW3HJD29NM/community-table.png)
Evidence: Catalog entry render + hostile-input check output

== rendered HTML row == <tr> <td><a href="https://github.com/mathieu-neron/acli-axi&#34;&gt;&lt;code&gt;acli-axi&lt;/code&gt;&lt;/a&gt;&lt;/td&gt;&#10;&lt;td&gt;mathieu-neron&lt;/td&gt;&#10;&lt;td&gt;Jira&lt;/td&gt;&#10;&lt;td&gt;Search, view, create, and edit Jira work items and inspect board sprints. Wraps the Atlassian CLI (<code>acli</code>) with token-efficient TOON output and true totals.</td> </tr> shipped docs/index.html + README.md contain the entry with an https github.com href rendered row carries no script tag, javascript: URL, or event handler attribute hostile url "javascript:alert(document.domain)" -> rejected: Unsupported link URL protocol hostile text fields -> escaped: <td>&lt;script&gt;alert(1)&lt;/script&gt;</td> <td>Jira&ldquo; onmouseover=&rdquo;alert(1)</td> <td>Wraps &lt;img src=x onerror=alert(1)&gt;.</td> all assertions passed

== catalog.yaml entry ==
{
  "name": "acli-axi",
  "url": "https://github.com/mathieu-neron/acli-axi",
  "author": "mathieu-neron",
  "domain": "Jira",
  "description": "Search, view, create, and edit Jira work items and inspect board sprints. Wraps the Atlassian CLI (`acli`) with token-efficient TOON output and true totals."
}

== rendered HTML row ==
<tr>
<td><a href="https://github.com/mathieu-neron/acli-axi"><code>acli-axi</code></a></td>
<td>mathieu-neron</td>
<td>Jira</td>
<td>Search, view, create, and edit Jira work items and inspect board sprints. Wraps the Atlassian CLI (<code>acli</code>) with token-efficient TOON output and true totals.</td>
</tr>

== rendered Markdown row ==
| [`acli-axi`](https://github.com/mathieu-neron/acli-axi) | mathieu-neron | Jira | Search, view, create, and edit Jira work items and inspect board sprints. Wraps the Atlassian CLI (`acli`) with token-efficient TOON output and true totals. |

shipped docs/index.html + README.md contain the entry with an https github.com href
rendered row carries no script tag, javascript: URL, or event handler attribute

hostile url "javascript:alert(document.domain)" -> rejected: Unsupported link URL protocol

hostile text fields -> escaped:
<tr>
<td><a href="https://github.com/mathieu-neron/acli-axi"><code>acli-axi</code></a></td>
<td>&lt;script&gt;alert(1)&lt;/script&gt;</td>
<td>Jira&ldquo; onmouseover=&rdquo;alert(1)</td>
<td>Wraps &lt;img src=x onerror=alert(1)&gt;.</td>
</tr>

all assertions passed
Evidence: Focused check script (evidence-only, not added to the repo)
// Exercises the real acli-axi catalog entry through the doc pipeline, then
// re-runs the same entry with hostile field values to show the pipeline's
// URL validation and HTML escaping actually fire on this code path.
import { readFileSync } from "node:fs";
import assert from "node:assert/strict";
import { parse } from "yaml";
import { htmlCatalogRows, mdCatalogTable } from "./scripts/generate-docs.mjs";

const root = process.cwd();
const catalog = parse(readFileSync(`${root}/catalog.yaml`, "utf8"));
const entry = catalog.community.find((e) => e.name === "acli-axi");

console.log("== catalog.yaml entry ==");
console.log(JSON.stringify(entry, null, 2));

const html = htmlCatalogRows([entry], true);
const md = mdCatalogTable([entry], true).split("\n").at(-1);
console.log("\n== rendered HTML row ==\n" + html);
console.log("\n== rendered Markdown row ==\n" + md);

// The rendered row must appear verbatim (modulo prettier wrapping) in the shipped files.
const site = readFileSync(`${root}/docs/index.html`, "utf8");
const readme = readFileSync(`${root}/README.md`, "utf8");
assert.match(site, /<a href="https:\/\/github\.com\/mathieu-neron\/acli-axi"\s*><code>acli-axi<\/code><\/a\s*>/);
assert.ok(readme.includes("[`acli-axi`](https://github.com/mathieu-neron/acli-axi)"));
console.log("\nshipped docs/index.html + README.md contain the entry with an https github.com href");

// No executable surface introduced by the entry.
assert.doesNotMatch(html, /<script|javascript:|on[a-z]+=/i);
console.log("rendered row carries no script tag, javascript: URL, or event handler attribute");

// Same code path, hostile inputs.
assert.throws(
  () => htmlCatalogRows([{ ...entry, url: "javascript:alert(document.domain)" }], true),
  /Unsupported link URL protocol: javascript:/,
);
console.log('\nhostile url "javascript:alert(document.domain)" -> rejected: Unsupported link URL protocol');

const injected = htmlCatalogRows(
  [
    {
      ...entry,
      author: '<script>alert(1)</script>',
      domain: 'Jira" onmouseover="alert(1)',
      description: "Wraps <img src=x onerror=alert(1)>.",
    },
  ],
  true,
);
console.log("\nhostile text fields -> escaped:\n" + injected);
assert.doesNotMatch(injected, /<script|<img/);
assert.match(injected, /&lt;script&gt;alert\(1\)&lt;\/script&gt;/);
console.log("\nall assertions passed");

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info
  • ℹ️ catalog.yaml:154 - VISION.md:17-24 requires an independent source review of the proposed package at an exact pinned revision before a positive community-catalog admission verdict. This PR carries the correct 3-file shape (matching prior additions such as glab-axi, e5f198e) and the target repo github.com/mathieu-neron/acli-axi is public, non-fork, MIT-licensed, with a command surface matching the catalog description — but the pinned-revision admission verdict itself is a maintainer-owned gate outside this change's files. No action required in this branch.
✅ **Test** - passed

✅ No issues found.

  • pnpm run docs:check — verified the committed README.md and docs/index.html generated regions match catalog.yaml (no drift, no hand-edited HTML)
  • pnpm run docs:test — 4/4 node:test cases in scripts/generate-docs.test.mjs, including "catalog HTML escapes text and attribute values" and "catalog HTML rejects unsafe link protocols"
  • node --input-type=module -e &#34;$(cat catalog-entry-check.mjs)&#34; — focused check that loads the real acli-axi entry from catalog.yaml, renders it via htmlCatalogRows/mdCatalogTable, asserts the shipped docs contain the https github.com href, asserts no <script>/javascript:/on*= in the rendered row, then asserts a javascript: URL throws "Unsupported link URL protocol" and hostile author/domain/description values come out HTML-escaped
  • Manual visual verification: headless Chrome (CDP) screenshot of docs/index.html Community catalog card showing the rendered acli-axi row
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Add acli-axi to the community list in catalog.yaml and regenerate
README.md and docs/index.html with pnpm run docs:gen.

acli-axi is a Jira AXI over the official Atlassian CLI (acli),
published on npm as acli-axi with source at
https://github.com/mathieu-neron/acli-axi.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant