fix(plugins): post-merge remediation for #33 (validator hardening, packaging hygiene, ask-codex metadata)

.claude-plugin/marketplace.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "agentic-utilities",
   "description": "Curated Claude Code plugins from agentic-utilities — a harness-agnostic collection of skills, plugins, and extensions across pi, Claude Code, and Codex. This marketplace exposes the Claude Code plugins.",
   "owner": {
@@ -54,7 +54,7 @@
     },
     {
       "name": "ask-codex",
-      "description": "OpenAI Codex CLI integration for Claude Code. Wraps `codex exec` and `codex resume` with model selection (gpt-5.4 / gpt-5.3-codex / gpt-5.4-nano), reasoning effort control (high/medium/low), sandbox modes (read-only / workspace-write / danger-full-access), session resumption, and stderr suppression for thinking tokens.",
+      "description": "OpenAI Codex CLI integration for Claude Code. Wraps `codex exec` and `codex resume` with model selection (gpt-5.4 / gpt-5.3-codex / gpt-5.4-nano), reasoning effort control (high/medium/low), sandbox modes (read-only / workspace-write / danger-full-access), session resumption, and stderr suppression for thinking tokens. Requires the `codex` binary on PATH.",
       "version": "0.1.0",
       "author": {
         "name": "Ossie Irondi"

.gitignore

@@ -1,6 +1,8 @@
 node_modules/
 .pnpm-store/
 .DS_Store
+__pycache__/
+*.py[cod]
 .env
 .env.*
 !.env.example

claude-code/plugins/ask-codex/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ask-codex",
   "version": "0.1.0",
-  "description": "OpenAI Codex CLI integration for Claude Code. Wraps `codex exec` and `codex resume` with model selection (gpt-5.4 / gpt-5.3-codex / gpt-5.4-nano), reasoning effort control (high/medium/low), sandbox modes (read-only / workspace-write / danger-full-access), session resumption, and stderr suppression for thinking tokens.",
+  "description": "OpenAI Codex CLI integration for Claude Code. Wraps `codex exec` and `codex resume` with model selection (gpt-5.4 / gpt-5.3-codex / gpt-5.4-nano), reasoning effort control (high/medium/low), sandbox modes (read-only / workspace-write / danger-full-access), session resumption, and stderr suppression for thinking tokens. Requires the `codex` binary on PATH.",
   "author": {
     "name": "Ossie Irondi"
   },

claude-code/plugins/awesome-readme/skills/awesome-readme/SKILL.md

@@ -57,24 +57,16 @@ If neither (1) nor (2) is set up and the user picks "Yes, generate via gpt-image
 
 ### How to invoke
 
-When a workflow needs an image, invoke the **gpt-image-2** skill directly:
+When a workflow needs an image, invoke the installed **gpt-image-2** skill directly (do not try to locate or run its script yourself; the skill loader resolves that). Pass:
 
-```bash
-bash scripts/gen.sh \
-  --prompt "<descriptive prompt for the README element>" \
-  --out docs/<descriptive-name>.png
-```
+- `--prompt "<descriptive prompt for the README element>"`
+- `--out docs/<descriptive-name>.png`
 
-For reference-image conditioning (remix an existing logo, restyle a screenshot, etc.):
+For reference-image conditioning (remix an existing logo, restyle a screenshot, etc.), also pass:
 
-```bash
-bash scripts/gen.sh \
-  --prompt "<remix instruction>" \
-  --ref /absolute/path/to/reference.png \
-  --out docs/<descriptive-name>.png
-```
+- `--ref /absolute/path/to/reference.png`
 
-The script lives inside the gpt-image-2 skill's directory; the standard skill loader resolves it. Pass the user's prompt through raw — only polish wording when the user explicitly asks for it. After the image lands, display/attach it in the response; never stop at "saved to docs/x.png".
+Pass the user's prompt through raw. Only polish wording when the user explicitly asks for it. After the image lands, display/attach it in the response; never stop at "saved to docs/x.png".
 
 ### Prompt patterns for README elements
 

claude-code/plugins/awesome-readme/skills/awesome-readme/workflows/Create.md

@@ -99,34 +99,15 @@ Follow this 10-section order — story before installation:
 
 If the user said yes in Step 2, invoke the **gpt-image-2** skill — once per visual. Pass the user's intent through raw; only polish wording when the user explicitly asked for "fancy" or "make it look great".
 
-**Pattern:**
-
-```bash
-bash scripts/gen.sh \
-  --prompt "<README element prompt — see SKILL.md 'Prompt patterns' table>" \
-  --out docs/<descriptive-name>.png
-```
+**Pattern:** invoke the installed gpt-image-2 skill (do not try to locate or run its script yourself) with `--prompt "<README element prompt: see SKILL.md 'Prompt patterns' table>"` and `--out docs/<descriptive-name>.png`.
 
 **Example invocations for a typical Story-mode README:**
 
-```bash
-# Hero banner with embedded tagline
-bash scripts/gen.sh \
-  --prompt "<project> README hero banner. <subject in one phrase>. Embedded tagline reads: '<the tagline>'." \
-  --out docs/hero.png
-
-# Architecture diagram
-bash scripts/gen.sh \
-  --prompt "Architecture diagram for <project>. <ComponentA> connects to <ComponentB> via <ComponentC>. Excalidraw / hand-drawn style. Clear labels on each node." \
-  --out docs/architecture.png
-
-# Workflow illustration
-bash scripts/gen.sh \
-  --prompt "Workflow illustration: step 1 <X>, step 2 <Y>, step 3 <Z>. Numbered left-to-right flow with annotated arrows." \
-  --out docs/workflow.png
-```
+- Hero banner with embedded tagline: `--prompt "<project> README hero banner. <subject in one phrase>. Embedded tagline reads: '<the tagline>'." --out docs/hero.png`
+- Architecture diagram: `--prompt "Architecture diagram for <project>. <ComponentA> connects to <ComponentB> via <ComponentC>. Excalidraw / hand-drawn style. Clear labels on each node." --out docs/architecture.png`
+- Workflow illustration: `--prompt "Workflow illustration: step 1 <X>, step 2 <Y>, step 3 <Z>. Numbered left-to-right flow with annotated arrows." --out docs/workflow.png`
 
-For reference-conditioned remixes (e.g., "restyle this existing logo as ukiyo-e"), add `--ref /absolute/path/to/reference.png`.
+For reference-conditioned remixes (e.g., "restyle this existing logo as ukiyo-e"), also pass `--ref /absolute/path/to/reference.png`.
 
 After each call:
 1. Confirm the output file exists at the `--out` path.

claude-code/plugins/awesome-readme/skills/awesome-readme/workflows/Improve.md

@@ -130,24 +130,15 @@ For each section:
 
 If the user said yes in Step 3, invoke the **gpt-image-2** skill — once per visual. See SKILL.md "Image Generation" and Create.md Step 5 for the full pattern.
 
-```bash
-# Architecture diagram
-bash scripts/gen.sh \
-  --prompt "Architecture diagram for <project>. <ComponentA> connects to <ComponentB> via <ComponentC>. Excalidraw / hand-drawn style. Clear labels on each node." \
-  --out docs/architecture.png
-
-# Workflow illustration
-bash scripts/gen.sh \
-  --prompt "Workflow illustration: step 1 <X>, step 2 <Y>, step 3 <Z>. Numbered left-to-right flow with annotated arrows." \
-  --out docs/workflow.png
-
-# Comparison visual (if applicable)
-bash scripts/gen.sh \
-  --prompt "Side-by-side comparison: '<A>' vs '<B>'. Two columns, contrasting treatment, clear winner indicated." \
-  --out docs/comparison.png
-```
+Invoke the installed gpt-image-2 skill (do not try to locate or run its script yourself):
+
+- Architecture diagram: `--prompt "Architecture diagram for <project>. <ComponentA> connects to <ComponentB> via <ComponentC>. Excalidraw / hand-drawn style. Clear labels on each node." --out docs/architecture.png`
+- Workflow illustration: `--prompt "Workflow illustration: step 1 <X>, step 2 <Y>, step 3 <Z>. Numbered left-to-right flow with annotated arrows." --out docs/workflow.png`
+- Comparison visual (if applicable): `--prompt "Side-by-side comparison: '<A>' vs '<B>'. Two columns, contrasting treatment, clear winner indicated." --out docs/comparison.png`
+
+For reference-conditioned remixes (e.g., restyling an existing logo or diagram), also pass `--ref /absolute/path/to/reference.png`.
 
-Pass the user's prompt through raw — only polish wording when they explicitly asked for it. Reference each output in the README with descriptive alt text. If `gen.sh` fails, name the failing layer in one sentence and ask the user how to proceed; do not silently fall back to a weaker model.
+Pass the user's prompt through raw. Only polish wording when they explicitly asked for it. Reference each output in the README with descriptive alt text. If image generation fails, name the failing layer in one sentence and ask the user how to proceed; do not silently fall back to a weaker model.
 
 ## Step 8: Validate and Deliver
 

claude-code/plugins/harness-audit/skills/harness-audit/SKILL.md

@@ -64,7 +64,7 @@ For each artifact, score `✅ Present / ⚠️ Partial / ❌ Missing` with concr
 2. **Rules directory** — per-domain coding standards in `rules/`, `.cursor/rules/`, `docs/rules/`, `docs/solutions/`, etc. Imperative rules with reasoning. For repos with exported APIs, this includes an API documentation policy or ADR.
 3. **Lint config with rich error messages** — ESLint / Biome / SwiftLint / ruff / clippy with custom rules whose messages explain why and how to fix.
 4. **Pre-commit hooks** — Husky / lefthook / pre-commit / native git hooks running formatters, type checks, or targeted tests before push/commit.
-5. **Test suite agents can drive** — one-liner to run tests (`npm test`, `./scripts/test.sh`, `cargo test`, etc.). Fast enough and deterministic enough for agents.
+5. **Test suite agents can drive**: one-liner to run tests (`npm test`, `make test`, `cargo test`, etc.). Fast enough and deterministic enough for agents.
 6. **PR review automation** — CodeRabbit, AI reviewer workflows, persona reviewers, or at minimum CI that gates PRs.
 7. **Repo-scoped skills/prompts** — `.agents/skills/`, `.pi/skills/`, `.claude/skills/`, `.codex/`, `.pi/prompts/`, or package-scoped resources. Prefer 5-10 deep resources over many shallow ones.
 8. **Garbage-collection cadence** — documented recurring loop that converts agent/PR feedback into permanent rules, lints, docs, or skills.

package.json

@@ -42,7 +42,7 @@
     ]
   },
   "scripts": {
-    "check": "npm run lint && npm run typecheck && npm test && npm run validate:plugins && npm run validate:skills && node scripts/list-resources.mjs",
+    "check": "npm run lint && npm run typecheck && npm test && npm run validate:plugins && node scripts/validate-package-contents.mjs && npm run validate:skills && node scripts/list-resources.mjs",
     "list": "node scripts/list-resources.mjs",
     "validate:plugins": "node scripts/validate-plugin-ports.mjs && node scripts/validate-codex-plugins.mjs",
     "install:bash-guard:global": "node scripts/install-bash-guard-global.mjs",
@@ -53,7 +53,7 @@
     "lint": "biome lint .",
     "lint:fix": "biome check --write .",
     "prepare": "husky",
-    "test": "node extensions/autopilot/v2-smoke-test.mjs && node extensions/question/question-smoke-test.mjs && node extensions/conditional-hooks/smoke-test.mjs && python3 skills/diataxis-docs-site/tests/test_create_site.py && node scripts/validate-package-contents.mjs",
+    "test": "node extensions/autopilot/v2-smoke-test.mjs && node extensions/question/question-smoke-test.mjs && node extensions/conditional-hooks/smoke-test.mjs && node scripts/lib/frontmatter-test.mjs && node scripts/lib/bundle-refs-test.mjs && node scripts/cli-entrypoint-test.mjs && python3 skills/diataxis-docs-site/tests/test_create_site.py",
     "typecheck": "tsc --noEmit",
     "validate:skills": "node scripts/validate-agent-skills.mjs"
   },
@@ -74,7 +74,8 @@
     "husky": "9.1.7",
     "lint-staged": "16.4.0",
     "typebox": "latest",
-    "typescript": "latest"
+    "typescript": "latest",
+    "yaml": "^2.8.2"
   },
   "engines": {
     "node": ">=20"

scripts/cli-entrypoint-test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Regression for a URL-unsafe direct-execution guard: a naive
+// `import.meta.url === \`file://${process.argv[1]}\`` comparison fails
+// silently for any checkout path containing a space (import.meta.url
+// percent-encodes it, the raw argv string does not), so `node
+// validate-plugin-ports.mjs` would exit 0 having never called main().
+//
+// This copies the real script and its lib dependencies into a temp
+// directory whose path contains a space, symlinks node_modules alongside
+// it so "yaml" still resolves, and runs it as a real subprocess. There is
+// no claude-code/plugins directory in the copy, so a correctly-invoked
+// main() must fail loudly with "plugins directory not found" — proof that
+// main() actually ran, not just that the subprocess exited.
+
+const scriptsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const repoRoot = path.resolve(scriptsDir, "..");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "cli-entrypoint-"));
+const spacedDir = path.join(tmp, "path with a space");
+fs.mkdirSync(path.join(spacedDir, "scripts", "lib"), { recursive: true });
+
+for (const file of ["validate-plugin-ports.mjs"]) {
+  fs.copyFileSync(path.join(scriptsDir, file), path.join(spacedDir, "scripts", file));
+}
+for (const file of ["bundle-refs.mjs", "frontmatter.mjs"]) {
+  fs.copyFileSync(path.join(scriptsDir, "lib", file), path.join(spacedDir, "scripts", "lib", file));
+}
+fs.symlinkSync(path.join(repoRoot, "node_modules"), path.join(spacedDir, "node_modules"));
+
+const targetScript = path.join(spacedDir, "scripts", "validate-plugin-ports.mjs");
+const result = spawnSync(process.execPath, [targetScript], { encoding: "utf8" });
+
+fs.rmSync(tmp, { recursive: true, force: true });
+
+assert.notEqual(result.status, 0, "main() must run and fail against the fixture's absent claude-code/plugins dir");
+assert.match(
+  result.stderr,
+  /plugins directory not found/,
+  "stderr must show main() actually executed listPlugins(), proving the space-containing path was recognized as direct execution",
+);
+
+console.log("CLI entrypoint direct-execution fixtures passed");