semantic-js-mcp 0.10.0 → 0.10.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "author": {
     "name": "Jonathan Muñoz Lucas"

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-07-17
+
+### Added
+
+- Publish release tags to npm through a protected GitHub Actions environment using short-lived OIDC credentials and automatic provenance.
+
+### Fixed
+
+- Document and validate marketplace refresh before reinstalling an existing Codex plugin.
+- Install and verify ripgrep in the trusted-publishing runner before executing the release gate.
+
 ## [0.10.0] - 2026-07-17
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.10.0` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
+Version `0.10.1` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
 
 ## Installation
 
@@ -31,6 +31,18 @@ codex plugin add semantic-js-mcp@elnonathan
 
 Codex CLI 0.144.4 or newer is required for npm-backed marketplace installation. Start a new Codex session after installation. The plugin bundles both the MCP server configuration and the semantic-navigation skill.
 
+### Updating the Codex plugin
+
+Codex installs from a local snapshot of each configured marketplace. Refresh that snapshot before reinstalling so `plugin add` resolves the version currently declared by the marketplace:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+`plugin add` reinstalls the plugin; a separate removal is not required. Start a new Codex session after the command reports the expected version.
+
 ### MCP executable
 
 Install the package globally when using an MCP host that accepts a command-based stdio configuration:

package/docs/distribution.md

@@ -11,6 +11,16 @@ codex plugin add semantic-js-mcp@elnonathan
 
 The marketplace entry pins a concrete npm package version. Codex CLI 0.144.4 is the minimum verified client for npm-backed marketplace installation. A release updates the package version, plugin manifest, and marketplace entry together.
 
+For an existing marketplace installation, refresh its local snapshot before reinstalling the plugin:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+`plugin add` reinstalls the plugin selected by the refreshed marketplace. Start a new Codex session after the listed version matches the release being installed.
+
 ## Executable
 
 ```bash
@@ -47,6 +57,7 @@ npm run check
 npm run check:runtime
 npm run check:documentation
 npm run smoke:ci
+npm run smoke:publish
 npm run smoke:negative
 npm run smoke:doctor
 npm run smoke
@@ -68,6 +79,14 @@ The local release gate runs every configured source, runtime, semantic, evaluati
 
 Postpublication verification requires an explicit version and the matching `v<version>` repository tag. It queries that immutable registry version, installs it with a fresh temporary npm cache and consumer project, verifies the installed executable and manifest, then runs the installed doctor to cover MCP startup, tool discovery, TypeScript evidence, and Vue navigation. It also installs the plugin from the tag-pinned marketplace inside a temporary `CODEX_HOME` and verifies the enabled plugin version. Temporary state is removed afterward. An unavailable registry, marketplace, or network is reported as `blocked`.
 
+## npm Trusted Publishing
+
+The `publish.yml` workflow publishes tags matching `v*` from a GitHub-hosted Node.js 24 runner. It requires the protected `npm-publish` environment, verifies that the tag exactly matches the package version, runs the complete release gate, and publishes through npm Trusted Publishing with OIDC. No long-lived npm token is used. npm generates provenance automatically for the public package.
+
+Configure the npm trusted publisher for GitHub user `elnonathan`, repository `semantic-js-mcp`, workflow filename `publish.yml`, and environment `npm-publish`. Allow `npm publish` only. In package publishing access, require two-factor authentication and disallow tokens.
+
+Create and push the matching `v<version>` tag only after the release commit is on `main` and its CI matrix passes. Approve the protected environment deployment, verify the published package, and then create the matching GitHub release.
+
 ## Continuous Integration
 
 GitHub Actions runs the complete release gate on Node.js 22 and 24 across Ubuntu, macOS, and Windows. A second Linux matrix runs the same gate on Node.js 22 across Ubuntu, Fedora, Arch Linux, and openSUSE. The gate verifies ripgrep before running static checks, runtime resolution, documentation, CI policy, negative fixtures, doctor, TypeScript and Vue semantics, provider lifecycle, package installation, and the short benchmark.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -44,13 +44,14 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
+    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/publish-workflow-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
     "check:runtime": "node scripts/check-runtime.mjs",
     "check:documentation": "node scripts/documentation-gate.mjs",
     "doctor": "node cli.mjs doctor",
     "ci:evaluate": "node scripts/semantic-js-mcp-ci.mjs",
     "smoke": "node scripts/smoke.mjs",
     "smoke:ci": "node scripts/ci-smoke.mjs",
+    "smoke:publish": "node scripts/publish-workflow-smoke.mjs",
     "smoke:negative": "node scripts/negative-verification-smoke.mjs",
     "smoke:doctor": "node scripts/doctor-smoke.mjs",
     "smoke:vue": "node scripts/vue-smoke.mjs",

package/protocol.mjs

@@ -408,7 +408,7 @@ export const RESULT_SCHEMA = Object.freeze({
   VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.10.0";
+export const SERVER_VERSION = "0.10.1";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",

package/scripts/codex-plugin-verification.mjs

@@ -71,6 +71,25 @@ export async function verifyCodexPlugin({version, workspace, spawn, runCommand})
     ];
   }
 
+  const upgrade = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
+    CODEX_DISTRIBUTION.PLUGIN_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_COMMAND,
+    CODEX_DISTRIBUTION.UPGRADE_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_NAME,
+    CODEX_DISTRIBUTION.JSON_ARGUMENT,
+  ]);
+  if (upgrade.exitCode !== CI_EXIT_CODE.PASS) {
+    const unavailable = upgrade.exitCode === undefined || networkUnavailable(upgrade);
+    return [
+      check(
+        RELEASE_CHECK.CODEX_MARKETPLACE,
+        unavailable ? CI_STATUS.BLOCKED : CI_STATUS.FAIL,
+        unavailable ? RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE : RELEASE_REASON.CODEX_MARKETPLACE_FAILED,
+        {marketplaceRef, message: failureMessage(upgrade)},
+      ),
+    ];
+  }
+
   const checks = [check(RELEASE_CHECK.CODEX_MARKETPLACE, CI_STATUS.PASS, RELEASE_REASON.CHECK_COMPLETED, {marketplaceRef})];
   const installation = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
     CODEX_DISTRIBUTION.PLUGIN_COMMAND,

package/scripts/distribution-policy.mjs

@@ -30,6 +30,7 @@ export const CODEX_DISTRIBUTION = Object.freeze({
   PLUGIN_COMMAND: "plugin",
   MARKETPLACE_COMMAND: "marketplace",
   ADD_COMMAND: "add",
+  UPGRADE_COMMAND: "upgrade",
   LIST_COMMAND: "list",
   REF_ARGUMENT: "--ref",
   JSON_ARGUMENT: "--json",

package/scripts/documentation-contract.mjs

@@ -12,7 +12,15 @@ export const PUBLIC_ROOT_DOCUMENT = Object.freeze(["CHANGELOG.md", "CONTRIBUTING
 export const PUBLIC_DOCUMENT_DIRECTORY = Object.freeze(["docs", "skills"]);
 
 export const DOCUMENTATION_REQUIREMENT = Object.freeze({
-  README_HEADINGS: Object.freeze(["Installation", "Runtime", "Verification", "Current Limitations", "Reporting Problems"]),
+  README_HEADINGS: Object.freeze([
+    "Installation",
+    "Updating the Codex plugin",
+    "Runtime",
+    "Verification",
+    "Current Limitations",
+    "Reporting Problems",
+  ]),
+  README_LITERALS: Object.freeze(["codex plugin marketplace upgrade elnonathan", "codex plugin add semantic-js-mcp@elnonathan"]),
   GETTING_STARTED_HEADINGS: Object.freeze([
     "Trace A Symbol",
     "Review A Security-Sensitive Change",

package/scripts/documentation-gate-smoke.mjs

@@ -6,7 +6,7 @@ import {evaluateDocumentation} from "./documentation-gate.mjs";
 
 const headingText = (headings) => headings.map((heading) => `## ${heading}`).join("\n");
 const valid = {
-  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}`,
+  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.GETTING_STARTED]: `${headingText(DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.CONTRIBUTING]: "# Contributing",
   [DOCUMENTATION_FILE.SECURITY]: "# Security",
@@ -46,9 +46,28 @@ strictEqual(
   "Missing canonical example literal was accepted",
 );
 
+const missingMarketplaceUpgrade = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_LITERALS[0], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingMarketplaceUpgrade).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.README_LITERALS[0],
+  ),
+  true,
+  "Missing marketplace upgrade guidance was accepted",
+);
+
 process.stdout.write(
   `${JSON.stringify(
-    {validDocumentation: "pass", missingHeading: "rejected", missingLiteral: "rejected", privateCoordination: "rejected"},
+    {
+      validDocumentation: "pass",
+      missingHeading: "rejected",
+      missingLiteral: "rejected",
+      missingMarketplaceUpgrade: "rejected",
+      privateCoordination: "rejected",
+    },
     null,
     2,
   )}\n`,

package/scripts/documentation-gate.mjs

@@ -52,6 +52,10 @@ export function evaluateDocumentation(documents) {
       if (readme.includes(`](${link})`)) continue;
       findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LINK_MISSING, link});
     }
+    for (const literal of DOCUMENTATION_REQUIREMENT.README_LITERALS) {
+      if (readme.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
   }
 
   const gettingStarted = documents[DOCUMENTATION_FILE.GETTING_STARTED];

package/scripts/publish-workflow-smoke.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import {deepStrictEqual, strictEqual} from "node:assert";
+import {readFile} from "node:fs/promises";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {parse} from "yaml";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workflowFile = path.join(root, ".github", "workflows", "publish.yml");
+const workflowText = await readFile(workflowFile, "utf8");
+const workflow = parse(workflowText);
+const publish = workflow.jobs?.publish;
+const steps = publish?.steps || [];
+const setupNode = steps.find((step) => step.uses === "actions/setup-node@v6");
+const commands = steps.flatMap((step) => (typeof step.run === "string" ? [step.run] : []));
+
+deepStrictEqual(Object.keys(workflow.on || {}), ["push"], "Publish workflow must only run from tag pushes");
+deepStrictEqual(workflow.on?.push?.tags, ["v*"], "Publish workflow must run only for release tags");
+deepStrictEqual(
+  workflow.permissions,
+  {contents: "read", "id-token": "write"},
+  "Publish workflow must grant only repository read and OIDC permissions",
+);
+strictEqual(publish?.if, "github.repository == 'elnonathan/semantic-js-mcp'", "Publishing must be restricted to the canonical repository");
+strictEqual(publish?.["runs-on"], "ubuntu-latest", "Publishing must use a GitHub-hosted runner");
+strictEqual(publish?.environment, "npm-publish", "Publishing must use the protected npm environment");
+strictEqual(workflow.concurrency?.["cancel-in-progress"], false, "An active publication must never be cancelled by another tag");
+strictEqual(setupNode?.with?.["node-version"], 24, "Publishing must use Node.js 24");
+strictEqual(setupNode?.with?.["registry-url"], "https://registry.npmjs.org", "Publishing must target npmjs.org");
+strictEqual(setupNode?.with?.["package-manager-cache"], false, "Release builds must not use a package-manager cache");
+strictEqual(
+  commands.includes("sudo apt-get update && sudo apt-get install --yes ripgrep"),
+  true,
+  "Publishing must install the required ripgrep executable",
+);
+strictEqual(commands.includes("rg --version"), true, "Publishing must verify ripgrep before the release gate");
+strictEqual(commands.includes("npm install --global npm@11.17.0"), true, "Publishing must install the verified npm CLI");
+strictEqual(commands.includes("npm ci"), true, "Publishing must install the locked dependency tree");
+strictEqual(commands.includes("npm run release:verify"), true, "Publishing must run the complete release gate");
+strictEqual(commands.includes("npm publish --access public"), true, "Publishing must use the public OIDC publish path");
+strictEqual(
+  commands.some((command) => command.includes("GITHUB_REF_NAME") && command.includes("package.json")),
+  true,
+  "Publishing must reject a tag that differs from the package version",
+);
+strictEqual(workflowText.includes("NODE_AUTH_TOKEN"), false, "OIDC publishing must not use an npm token");
+strictEqual(workflowText.includes("secrets."), false, "OIDC publishing must not read repository secrets");
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      workflow: "publish.yml",
+      trigger: "release-tags",
+      authentication: "oidc",
+      environment: publish.environment,
+      tokenSecret: "absent",
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/release-contract.mjs

@@ -10,6 +10,7 @@ export const RELEASE_CHECK = Object.freeze({
   RUNTIME: "runtime",
   DOCUMENTATION: "documentation",
   CI_POLICY: "ci-policy",
+  PUBLISH_WORKFLOW: "publish-workflow",
   NEGATIVE_VERIFICATION: "negative-verification",
   DOCTOR: "doctor",
   TYPESCRIPT_SMOKE: "typescript-smoke",
@@ -57,6 +58,7 @@ export const RELEASE_LOCAL_CHECKS = Object.freeze([
   Object.freeze({name: RELEASE_CHECK.RUNTIME, npmScript: "check:runtime"}),
   Object.freeze({name: RELEASE_CHECK.DOCUMENTATION, npmScript: "check:documentation"}),
   Object.freeze({name: RELEASE_CHECK.CI_POLICY, npmScript: "smoke:ci"}),
+  Object.freeze({name: RELEASE_CHECK.PUBLISH_WORKFLOW, npmScript: "smoke:publish"}),
   Object.freeze({name: RELEASE_CHECK.NEGATIVE_VERIFICATION, npmScript: "smoke:negative"}),
   Object.freeze({name: RELEASE_CHECK.DOCTOR, npmScript: "smoke:doctor"}),
   Object.freeze({name: RELEASE_CHECK.TYPESCRIPT_SMOKE, npmScript: "smoke"}),

package/scripts/release-smoke.mjs

@@ -81,7 +81,11 @@ try {
     calls[0].args.includes(`${CODEX_DISTRIBUTION.VERSION_REF_PREFIX}${version}`),
     "Codex marketplace verification did not use an immutable version ref",
   );
-  assert(calls[1].args.includes(CODEX_DISTRIBUTION.PLUGIN_SELECTOR), "Codex verification used the wrong plugin selector");
+  assert(
+    calls[1].args.includes(CODEX_DISTRIBUTION.UPGRADE_COMMAND) && calls[1].args.includes(CODEX_DISTRIBUTION.MARKETPLACE_NAME),
+    "Codex marketplace verification omitted the configured snapshot refresh",
+  );
+  assert(calls[2].args.includes(CODEX_DISTRIBUTION.PLUGIN_SELECTOR), "Codex verification used the wrong plugin selector");
   assert(
     calls.every((call) => call.options.env[CODEX_DISTRIBUTION.HOME_ENVIRONMENT_VARIABLE].startsWith(codexWorkspace)),
     "Codex verification did not isolate its state under the temporary workspace",
@@ -105,6 +109,22 @@ try {
     networkChecks[0].reason === RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE,
     "Unavailable Codex marketplace network used the wrong reason",
   );
+
+  let upgradeCall = 0;
+  const upgradeNetworkChecks = await verifyCodexPlugin({
+    version,
+    workspace: codexWorkspace,
+    runCommand: async () => {
+      upgradeCall++;
+      if (upgradeCall === 1) return {exitCode: CI_EXIT_CODE.PASS, stdout: "{}", stderr: ""};
+      return {exitCode: CI_EXIT_CODE.FAIL, stdout: "", stderr: "network is unreachable"};
+    },
+  });
+  assert(upgradeNetworkChecks[0].status === CI_STATUS.BLOCKED, "Unavailable marketplace upgrade was not blocked");
+  assert(
+    upgradeNetworkChecks[0].reason === RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE,
+    "Unavailable marketplace upgrade used the wrong reason",
+  );
 } finally {
   await rm(codexWorkspace, {recursive: true, force: true});
 }
@@ -116,6 +136,7 @@ process.stdout.write(
       missingPublishedVersion: "blocked",
       isolatedCodexPluginInstallation: "ok",
       unavailableCodexMarketplace: "blocked",
+      unavailableCodexMarketplaceUpgrade: "blocked",
     },
     null,
     2,

package/skills/semantic-navigation/references/protocol-literals.md

@@ -2,7 +2,7 @@
 
 Generated from `protocol.mjs`. Do not edit this file directly.
 
-Producer: `semantic-js-mcp` version `0.10.0`
+Producer: `semantic-js-mcp` version `0.10.1`
 Display name: `Semantic JS MCP`
 Result schema version: `7`