Document npm package, bundled plugin, and runtime version mapping

Open Beginner friendly
#234 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
nodejs, typescript
Domain
documentation, release

Research direction

Start with the npm-v0.1.5 tag and the commands in the reproduction section, then inspect sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json. Done means the release documentation or metadata explicitly maps the npm version, commit SHA, bundled tree hash, plugin version, and runtime/catalog version, or clearly records the intended alignment for future releases.

Written by the indexing model from the issue text.

Description

area:cli documentation priority:p3

Summary

The following identifiers refer to the same Codex Security plugin release/content, but they use different version numbers:

  • npm release tag: npm-v0.1.5
  • bundled plugin manifest: 0.1.14
  • Codex runtime distribution: 0.1.15

The vendor snapshot is therefore correct when copied byte-for-byte from npm-v0.1.5; the confusing part is the undocumented mapping between these three identifiers.

Observed source identity

  • Tag npm-v0.1.5 resolves to commit 66778d0d85f478d7832854b81d0a6ddb93a3ce4c.
  • The bundled plugin tree is 09b14c17694b5f568dd61860f2bc63771e5e4280.
  • sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json reports 0.1.14.
  • The corresponding Codex runtime plugin reports 0.1.15.

Request

Could the release documentation or metadata explicitly describe the relationship between:

  1. the npm release tag/version,
  2. the bundled .codex-plugin/plugin.json version, and
  3. the Codex runtime/catalog version?

An immutable mapping such as npm tag → commit SHA → bundled tree hash → runtime version would make byte-for-byte vendoring and provenance checks unambiguous.

Alternatively, aligning these version fields for future releases would avoid downstream tools interpreting the same release as a version mismatch.

Reproduction

git clone https://github.com/openai/codex-security.git
cd codex-security
git checkout npm-v0.1.5

git rev-parse HEAD
git rev-parse HEAD:sdk/typescript/_bundled_plugin
jq -r .version sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json

Observed:

66778d0d85f478d7832854b81d0a6ddb93a3ce4c
09b14c17694b5f568dd61860f2bc63771e5e4280
0.1.14
Dominant language
TypeScript
Stars
10.8k
Forks
802
Avg merge
1d 8h
Merged PRs (30d)
257

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/codex-security

All issues in openai/codex-security

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.