Skip to content

feat(ksail): add plugin directory listing assets for Claude and Codex - #658

Merged
devantler merged 4 commits into
mainfrom
claude/ksail-plugin-icon
Nov 7, 2026
Merged

devantler merged 4 commits into
mainfrom
claude/ksail-plugin-icon

Conversation

@devantler

@devantler devantler commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Gets the ksail plugin ready for both plugin directories.

  • Claude plugin directory, "No icon": adds the KSail app icon at plugins/ksail/.claude-plugin/icon.png, the path the directory reads by default. It is desktop/resources/icon.png from devantler-tech/ksail, a 1024 × 1024 RGBA PNG of 49 KB. The directory accepts square PNGs from 512 to 2048 px and under 2 MB.

  • OpenAI (Codex) plugin directory: adds plugins/ksail/.codex-plugin/plugin.json. Codex reads that file before .claude-plugin/plugin.json. It repeats the portable manifest, loads ./skills/ and ./.mcp.json, and holds the listing in interface:

    • display name KSail, short description Create Kubernetes clusters, and a long description
    • category Developer Tools, with capabilities Interactive, Read and Write
    • website https://ksail.devantler.tech/ and support https://github.com/devantler-tech/ksail/issues
    • three example prompts and the brand colours #143150 and #2EC4E6
    • logo and composerIcon both pointing at the same icon

    All fields are within the directory's final limits (short description 26 of 30 characters, prompts at most 88 of 128).

  • Version: ksail goes from 1.0.0 to 1.0.1 with scripts/bump-plugin-version.sh. The plugin's first CHANGELOG.md and the Codex note in docs/installation.md are added.

  • scripts/guard-gh-json-fields.sh: the icon is the first image packaged under plugins/, and the guard fails closed (UNKNOWN) on any file type it doesn't scan, which failed Test packaged resources. It now skips .png, .jpg, .jpeg and .webp files, but only when they are regular, unlinked files whose leading bytes match the format's signature. Text named icon.png, an empty file, a mismatched signature or a symlink stays UNKNOWN, and the self-test covers each case.

Directory findings this PR does not change

The local MCP server (ksail open mcp) stays. The maintainer decided to keep it.

  • Claude, policy hold "MCP server command wasn't read": a reviewer has to clear this. ksail is a Go CLI the user installs separately, so bundling a binary for every platform isn't practical.
  • Claude, "Local MCP servers accepted only from Verified organizations": this doesn't block the version under review. Before the next submission, devantler-tech needs Verified status or the plugin must drop its local MCP server.
  • Codex: a public listing takes only remote MCP servers, and local ones only from organizations OpenAI has allowlisted. The OpenAI submission therefore goes in as Skills only, from a ZIP of this package without .mcp.json. Installs from this marketplace keep the MCP server.

Validation

Run locally, all exit 0:

  • ./scripts/validate-manifests.sh, including a negative control: changing only the Codex manifest's version fails with differs from plugins/ksail/plugin.json beyond Codex's skills, mcpServers, apps and interface
  • ./scripts/check-plugin-version-bump.sh <merge-base> HEAD (ksail 1.0.0 → 1.0.1)
  • bash scripts/plugin-changelog.sh check <merge-base> HEAD
  • bash scripts/check-marketplace-version.sh <merge-base> <head>
  • bash scripts/package-discovery.test.sh
  • bash scripts/package-boundaries.test.sh
  • ./scripts/guard-gh-json-fields.sh (OK across 286 surfaces, icon included), and bash scripts/guard-gh-json-fields.test.sh passing 153 of 153 under both bash 5 and macOS bash 3.2
  • shellcheck -x on both guard files

🤖 Generated with Claude Code

The Claude plugin directory check reported "No icon" for the ksail plugin.
Add the KSail app icon (1024x1024 PNG from devantler-tech/ksail
desktop/resources/icon.png) at .claude-plugin/icon.png, the path the
directory reads by convention, so no manifest field is needed and the
portable and strict manifests stay identical. Bump ksail to 1.0.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-project-automation github-project-automation Bot moved this to 🫴 Ready in 🌊 Project Board Nov 4, 2026
@devantler
devantler marked this pull request as ready for review November 4, 2026 22:42
The OpenAI plugin directory reads its listing from .codex-plugin/plugin.json:
display name, short and long descriptions, category, links, example
prompts, brand colours, logo and composer icon. Add one for ksail that
repeats the portable manifest (validate-manifests.sh enforces parity), loads
the skill and the ksail MCP server, and points both icons at the existing
.claude-plugin/icon.png.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devantler
devantler force-pushed the claude/ksail-plugin-icon branch from a674cde to 7642deb Compare November 4, 2026 22:50
@devantler devantler changed the title feat(ksail): add the plugin directory icon feat(ksail): add plugin directory listing assets for Claude and Codex Nov 4, 2026
… guard

The ksail plugin's listing icon (.claude-plugin/icon.png) is the first image
packaged under plugins/, and the guard reported UNKNOWN for it because every
file type it does not scan fails closed. That is the intended design: extend
the list rather than skip a new kind of file.

A raster image is pixels, not prose an agent reads, so it cannot prescribe a
gh field. But its name proves nothing, so .png, .jpg, .jpeg and .webp files
are skipped only when they are regular, unlinked files whose leading bytes
match their format's signature. Text named icon.png, an empty file, a
mismatched signature or a symlink stays UNKNOWN. Tests cover each case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devantler

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 5b8d2d72-6459-40b5-ac71-813e5fb07ca1
Commits

Reviewing files that changed from the base of the PR and between 52b1d97 and fbcb5aa.

Files ignored due to path filters: 1

  • plugins/ksail/.claude-plugin/icon.png is excluded by !**/*.png
Files selected for processing: 9

  • .claude-plugin/marketplace.json
  • .github/plugin/marketplace.json
  • docs/installation.md
  • plugins/ksail/.claude-plugin/plugin.json
  • plugins/ksail/.codex-plugin/plugin.json
  • plugins/ksail/CHANGELOG.md
  • plugins/ksail/plugin.json
  • scripts/guard-gh-json-fields.sh
  • scripts/guard-gh-json-fields.test.sh

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Recent review details

Additional context used

Code guidelines: 3

AGENTS.md — auto-discovered
docs/adr/0001-bundling-mcp-servers-and-custom-agents.md — auto-discovered
docs/installation.md — auto-discovered
Path-based instructions: 3

Source excerpt: The repo ships **two marketplace manifests that must stay byte-for-byte in sync** (modulo key order): [`.github/plugin/marketplace.json`](.github/plugin/marketplace.json) for Copilot / VS Code and [`.claude-plugin/marketplac...

CodeRabbit inference engine (AGENTS.md)

Files:

  • .claude-plugin/marketplace.json
  • .github/plugin/marketplace.json
Applicability reference: AGENTS.md: # devantler-tech/agent-plugins By design the marketplace is **not scoped to skills-only** — a plugin may bundle any agent resource (agent skills today; [MCP](https://modelcontextprotocol.io) servers and c...

CodeRabbit inference engine (docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)

Files:

  • plugins/ksail/plugin.json
  • .claude-plugin/marketplace.json
  • .github/plugin/marketplace.json
  • plugins/ksail/CHANGELOG.md
  • plugins/ksail/.claude-plugin/plugin.json
  • plugins/ksail/.codex-plugin/plugin.json
Applicability reference: AGENTS.md: # devantler-tech/agent-plugins See the [plugin catalogue](docs/plugins.md) and the per-tool [installation instructions](docs/installation.md).

CodeRabbit inference engine (docs/installation.md)

Files:

  • plugins/ksail/.codex-plugin/plugin.json
Additional comments: 5

scripts/guard-gh-json-fields.sh: 2

17-19: LGTM!

Also applies to: 63-68, 73-80, 221-223

71-72: Stability & Availability

The claimed concurrent replacement is not established for the supported workflow. The separate pathname checks alone do not establish a material failure.

scripts/guard-gh-json-fields.test.sh: 1

370-411: LGTM!

plugins/ksail/.codex-plugin/plugin.json: 2

26-26: Functional Correctness

The repository manifest is not the reported skills-only submission package. The planned ZIP may use a modified manifest, so the evidence does not establish that its required flag is missing.

27-27: Data Integrity & Integration

The marketplace declaration has a matching file. The planned ZIP’s manifest contents are not established, so the reported upload failure is unsupported.

Walkthrough

The KSail plugin adds a Codex manifest with plugin metadata, skill and MCP paths, and listing details. Its version changes to 1.0.1 in the plugin metadata and marketplace files. The changelog and installation documentation describe the Codex listing. The plugin discovery guard now checks that supported image extensions are regular files with matching PNG, JPEG, or WebP signatures. Tests cover matching signatures and invalid or unreadable image files.

Possibly related PRs

Merge Risk: Minimal · up to fbcb5

This PR adds listing assets and a Codex manifest for the ksail plugin, bumps its version to 1.0.1, and tightens the guard so image files are skipped only when they are regular files with matching signatures. No concrete defect was found in the supplied changes, so it is ready to merge after the normal checks. The Codex submission ZIP is built outside this repository, so its manifest contents could not be checked here.

Pre-merge checks: Passed 5

Check name Status Explanation
Title check Passed The title identifies the KSail directory-listing assets for Claude and Codex.
Description check Passed The description covers the listing assets, version bump, documentation, and image guard changes.
Docstring Coverage Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 1 functions across 2 files. (7 skipped: 7 unsupported.)

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@devantler

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@devantler

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@devantler

Copy link
Copy Markdown
Contributor Author

@cursor review

@cursor

cursor Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: cbba0178-2273-4bbb-9185-582f5f971801)

@devantler devantler left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Generated by the Agentic Engineer

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 4acfad9c939d050e3776ee755c5e64887adc1351

  • CodeRabbit: free OSS review limit reached for the organization ("Review limit reached", next included review in 59 minutes, this PR, 2026-11-04T23:33:57Z), after an earlier refusal at 23:19Z.
  • Codex: usage limit for code reviews reached (#656, 2026-11-04T21:33:52Z); only the maintainer can lift it.
  • Cursor Bugbot: "usage limit reached" (this PR, check-run neutral/Error, 2026-11-04T23:36:17Z); only a Cursor admin can lift it.

Independent review of 5e3cd8e..4acfad9c939d050e3776ee755c5e64887adc1351. I ran adversarial fixtures against the guard under bash 5 and macOS bash 3.2 with BSD od: unreadable, FIFO, dangling and directory symlinks, truncated or wrong-magic WebP, uppercase .PNG, and text named .png. Each one stayed UNKNOWN. I also checked every listing field against the OpenAI limits (lengths, category, unique prompts, HTTPS URLs, contrast 13.25:1 and 7.79:1), the icon (1024×1024 RGBA, 49,695 bytes, no text chunks, byte-identical to ksail's desktop/resources/icon.png), validate-manifests, the version-bump and changelog gates, the guard self-test (153/153) and shellcheck -x.

Verdict: no P0/P1 findings

Comment thread scripts/guard-gh-json-fields.sh Resolved
Comment thread scripts/guard-gh-json-fields.test.sh Resolved
Comment thread plugins/ksail/.codex-plugin/plugin.json Resolved
…ilure paths

Local review round nits:
- The comment claimed more than the check does. Only the leading
  signature is read; text after it, or in a PNG text chunk, is not
  inspected, because agents open image files as images. Say so, and say
  that the skip applies to images anywhere under plugins/.
- Cover the untested fail-closed paths: a FIFO named .png, an uppercase
  .PNG, and an unreadable .png (skipped when running as root, which reads
  it anyway).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@devantler

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@devantler
devantler merged commit 0e76cf9 into main Nov 7, 2026
24 checks passed
@devantler
devantler deleted the claude/ksail-plugin-icon branch November 7, 2026 11:08
@github-project-automation github-project-automation Bot moved this from 🫴 Ready to ✅ Done in 🌊 Project Board Nov 7, 2026
devantler added a commit that referenced this pull request Nov 7, 2026
#658 landed a broader, reviewed fix to the gh JSON-field guard: it skips
signature-checked raster images anywhere under plugins/. That supersedes
this branch's narrower listing-icon exception, so both guard files take
main's version; this PR no longer changes the guard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

1 participant