Skip to content

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

Open
devantler wants to merge 4 commits into
mainfrom
claude/ksail-plugin-icon
Open

feat(ksail): add plugin directory listing assets for Claude and Codex#658
devantler wants to merge 4 commits into
mainfrom
claude/ksail-plugin-icon

Conversation

@devantler

@devantler devantler commented Nov 4, 2026 •
edited
Loading

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

@devantler @claude
feat(ksail): add the plugin directory icon
561fb16 
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
@devantler @claude
feat(ksail): add a Codex manifest with the plugin directory listing
7642deb 
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
@devantler devantler mentioned this pull request Nov 4, 2026
Open
@devantler @claude
fix(guard): skip signature-checked raster images in the gh JSON field…
4acfad9 
… 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

devantler commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •
edited
Loading

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 •
edited
Loading

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

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: f05c8c83-cdd6-4438-92e4-1516a93c4859
Commits

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

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

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

devantler commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 4, 2026 •
edited
Loading

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

devantler commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Generated by the Agentic Engineer

@devantler

devantler commented Nov 4, 2026

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 commented Nov 4, 2026
View reviewed changes

@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
@devantler @claude
fix(guard): state exactly what the image skip checks, and test its fa…
fbcb5aa 
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

🌊 Project Board
Status: 🫴 Ready

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@devantler