@hegemonart/get-design-done 1.28.7 → 1.28.8

package/scripts/lib/install/converters/cursor-marketplace.cjs

@@ -0,0 +1,309 @@
+'use strict';
+
+/**
+ * scripts/lib/install/converters/cursor-marketplace.cjs — Phase 28.8 (Plan B1).
+ *
+ * Cursor Marketplace Tier-2 distribution-channel converter. SEPARATE from
+ * Phase 28.7's `cursor.cjs` SKILL.md file-drop converter — that one rewrites
+ * per-skill content for the runtime install path. THIS one builds the
+ * `.cursor-plugin/plugin.json` manifest and emits the marketplace bundle
+ * layout consumed by `build-distribution-bundles.cjs` (Plan 28-8-X1).
+ *
+ * Architecture note: per CONTEXT D-05 (additive), Tier-1 file-drop and
+ * Tier-2 marketplace coexist — `cursor.cjs` is UNCHANGED. Per CONTEXT D-06,
+ * `skills/` is the SHARED source; this converter passes skill content
+ * through verbatim (Cursor accepts Claude-compatible SKILL.md per Wave A
+ * research, so no per-skill content transform is required at the Tier-2
+ * bundle layer).
+ *
+ * Source mapping: see `.planning/research/cursor-marketplace-2026-05-19.md`
+ * § Schema Mapping (lines 234-256) for the authoritative field-by-field spec.
+ *
+ * GDD-original pattern (no gsd-build/get-shit-done counterpart): Tier-2
+ * distribution channels do not exist in the upstream multi-runtime install
+ * reference (CONTEXT line 34). No port attribution required.
+ *
+ * Exports:
+ *   - `buildManifest(sources, opts)` — pure function, returns the manifest
+ *     object ready to `JSON.stringify(obj, null, 2)`.
+ *   - `convert({ skillsDir, outDir, manifest }, opts)` — file-emission
+ *     function for `build-distribution-bundles.cjs`. The only side-effect
+ *     surface; touches only paths under `outDir`.
+ *   - `CURATED_KEYWORDS` — frozen 8-tag default keyword subset.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Curated keyword subset for Cursor's marketplace card display.
+// Per Wave A research § Schema Mapping `keywords` row: marketplace card
+// surfaces ~5-8 tags — picking the most Cursor-user-relevant subset out
+// of the 60+ tags in package.json.keywords.
+const CURATED_KEYWORDS = Object.freeze([
+  'design',
+  'ui',
+  'ux',
+  'frontend',
+  'design-system',
+  'accessibility',
+  'figma',
+  'skill',
+]);
+
+/**
+ * Build the .cursor-plugin/plugin.json manifest object from GDD source
+ * artifacts. Pure function — no fs, env, or path access.
+ *
+ * Field-by-field source mapping per Wave A research § Schema Mapping:
+ *
+ *   name        ← claudePluginJson.name (canonical, kebab-case)
+ *   description ← packageJson.description (verbatim)
+ *   version     ← packageJson.version (verbatim, lockstep per D-08)
+ *   author      ← {name: claudePluginJson.author.name} (transform)
+ *   homepage    ← packageJson.homepage (verbatim, omit if absent)
+ *   repository  ← packageJson.repository.url with trailing .git stripped
+ *   license     ← packageJson.license (verbatim, omit if absent)
+ *   keywords    ← opts.keywords || CURATED_KEYWORDS
+ *
+ * OMITTED (per research § Schema Mapping rationale):
+ *   logo, rules, agents, skills, commands, hooks, mcpServers
+ *
+ * @param {Object} sources                            Source metadata.
+ * @param {Object} sources.packageJson                Parsed package.json.
+ * @param {Object} [sources.claudePluginJson]         Parsed .claude-plugin/plugin.json.
+ * @param {Object} [opts]
+ * @param {string[]} [opts.keywords]                  Override keyword subset
+ *   (defaults to CURATED_KEYWORDS).
+ * @returns {Object}                                  Manifest object,
+ *   keys in documented order, ready to JSON.stringify with 2-space indent.
+ */
+function buildManifest(sources, opts) {
+  const opts2 = opts || {};
+  const pkg = sources && sources.packageJson;
+  const claudePlugin = sources && sources.claudePluginJson;
+
+  if (!pkg || typeof pkg !== 'object') {
+    throw new Error('cursor-marketplace: sources.packageJson is required');
+  }
+
+  // name — prefer .claude-plugin/plugin.json.name (canonical, already
+  // kebab-case as "get-design-done"); fall back to stripping npm scope
+  // prefix from package.json.name.
+  let name;
+  if (claudePlugin && typeof claudePlugin.name === 'string') {
+    name = claudePlugin.name;
+  } else if (typeof pkg.name === 'string') {
+    name = pkg.name.replace(/^@[^/]+\//, '');
+  } else {
+    throw new Error('cursor-marketplace: name is required (no source)');
+  }
+
+  // description — required (we want predictable failure if package.json
+  // is malformed).
+  if (typeof pkg.description !== 'string' || pkg.description.length === 0) {
+    throw new Error('cursor-marketplace: packageJson.description is required');
+  }
+  const description = pkg.description;
+
+  // version — required, semver-shaped.
+  if (typeof pkg.version !== 'string' || !/^\d+\.\d+\.\d+/.test(pkg.version)) {
+    throw new Error(
+      'cursor-marketplace: packageJson.version is required and must be semver-shaped'
+    );
+  }
+  const version = pkg.version;
+
+  // author — resolve in order: claudePluginJson.author.name → pkg.author
+  // (string form) → pkg.author.name. Email only if claudePluginJson source
+  // carries one (GDD does not today).
+  let authorName;
+  let authorEmail;
+  if (
+    claudePlugin
+    && claudePlugin.author
+    && typeof claudePlugin.author === 'object'
+    && typeof claudePlugin.author.name === 'string'
+  ) {
+    authorName = claudePlugin.author.name;
+    if (typeof claudePlugin.author.email === 'string') {
+      authorEmail = claudePlugin.author.email;
+    }
+  } else if (typeof pkg.author === 'string' && pkg.author.length > 0) {
+    authorName = pkg.author;
+  } else if (
+    pkg.author
+    && typeof pkg.author === 'object'
+    && typeof pkg.author.name === 'string'
+  ) {
+    authorName = pkg.author.name;
+    if (typeof pkg.author.email === 'string') {
+      authorEmail = pkg.author.email;
+    }
+  } else {
+    throw new Error('cursor-marketplace: author.name is required (no source)');
+  }
+  const author = authorEmail
+    ? { name: authorName, email: authorEmail }
+    : { name: authorName };
+
+  // homepage — verbatim, omit if absent.
+  const homepage =
+    typeof pkg.homepage === 'string' && pkg.homepage.length > 0
+      ? pkg.homepage
+      : undefined;
+
+  // repository — package.json may store as object {type, url} or string.
+  // Strip trailing .git for cleaner display.
+  let repository;
+  if (pkg.repository) {
+    let rawUrl;
+    if (typeof pkg.repository === 'string') {
+      rawUrl = pkg.repository;
+    } else if (typeof pkg.repository === 'object'
+      && typeof pkg.repository.url === 'string') {
+      rawUrl = pkg.repository.url;
+    }
+    if (rawUrl) {
+      repository = rawUrl.replace(/\.git$/, '');
+    }
+  }
+
+  // license — verbatim, omit if absent.
+  const license =
+    typeof pkg.license === 'string' && pkg.license.length > 0
+      ? pkg.license
+      : undefined;
+
+  // keywords — opts override → CURATED_KEYWORDS default. Always materialize
+  // a fresh array (don't expose the frozen module-level constant directly
+  // in user-mutable output).
+  const keywords =
+    Array.isArray(opts2.keywords) && opts2.keywords.length > 0
+      ? opts2.keywords.slice()
+      : CURATED_KEYWORDS.slice();
+
+  // Assemble in documented order: name, description, version, author,
+  // homepage, repository, license, keywords. Omit undefined fields so
+  // JSON.stringify produces a clean diff.
+  const manifest = {};
+  manifest.name = name;
+  manifest.description = description;
+  manifest.version = version;
+  manifest.author = author;
+  if (homepage !== undefined) manifest.homepage = homepage;
+  if (repository !== undefined) manifest.repository = repository;
+  if (license !== undefined) manifest.license = license;
+  manifest.keywords = keywords;
+
+  return manifest;
+}
+
+/**
+ * Copy a directory tree recursively. Vanilla fs only — no deps.
+ * Returns the list of relative paths written (relative to `dest`).
+ */
+function copyDirRecursive(src, dest, relPrefix) {
+  const written = [];
+  const stack = [{ s: src, d: dest, rel: relPrefix || '' }];
+  while (stack.length > 0) {
+    const { s, d, rel } = stack.pop();
+    fs.mkdirSync(d, { recursive: true });
+    const entries = fs.readdirSync(s);
+    for (const entry of entries) {
+      const sp = path.join(s, entry);
+      const dp = path.join(d, entry);
+      const relPath = rel ? `${rel}/${entry}` : entry;
+      const stat = fs.statSync(sp);
+      if (stat.isDirectory()) {
+        stack.push({ s: sp, d: dp, rel: relPath });
+      } else if (stat.isFile()) {
+        fs.copyFileSync(sp, dp);
+        written.push(relPath);
+      }
+      // symlinks + other: ignored (skills tree is regular files only)
+    }
+  }
+  return written;
+}
+
+/**
+ * Convert/emit the cursor-marketplace bundle into a destination directory.
+ * Called by build-distribution-bundles.cjs (Plan 28-8-X1).
+ *
+ * Per CONTEXT D-06, `skills/` is the shared source — this converter emits
+ * the marketplace bundle as:
+ *
+ *   <outDir>/
+ *     .cursor-plugin/
+ *       plugin.json          ← the manifest object, JSON.stringified
+ *     skills/
+ *       <each skill copied verbatim from input.skillsDir>
+ *
+ * Cursor accepts Claude-compatible SKILL.md so no per-skill content
+ * transform is required at this layer. The Tier-1 cursor.cjs converter
+ * remains responsible for the per-runtime SKILL.md rewrites needed by the
+ * file-drop install path; those rewrites are irrelevant to a marketplace
+ * bundle (Cursor's marketplace reads the SKILL.md content directly).
+ *
+ * Idempotent: rerunning with the same inputs produces identical files
+ * (no partial-state corruption, no append-only emissions).
+ *
+ * Touches only paths under `outDir`. The source `skillsDir` is read-only.
+ *
+ * @param {Object} input
+ * @param {string} input.skillsDir                    Path to source skills/ tree.
+ * @param {string} input.outDir                       Path to destination bundle directory.
+ * @param {Object} input.manifest                     Manifest object from buildManifest().
+ * @param {Object} [opts]
+ * @returns {{ filesWritten: string[] }}              Sorted relative paths under outDir.
+ */
+function convert(input, opts) {
+  if (!input || typeof input !== 'object') {
+    throw new Error('cursor-marketplace.convert: input is required');
+  }
+  const { skillsDir, outDir, manifest } = input;
+  if (typeof skillsDir !== 'string' || skillsDir.length === 0) {
+    throw new Error('cursor-marketplace.convert: input.skillsDir is required');
+  }
+  if (typeof outDir !== 'string' || outDir.length === 0) {
+    throw new Error('cursor-marketplace.convert: input.outDir is required');
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error('cursor-marketplace.convert: input.manifest is required');
+  }
+
+  const skillsStat = fs.statSync(skillsDir);
+  if (!skillsStat.isDirectory()) {
+    throw new Error(
+      `cursor-marketplace.convert: skillsDir is not a directory: ${skillsDir}`
+    );
+  }
+
+  const written = [];
+
+  // Create outDir if absent.
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // Write manifest at <outDir>/.cursor-plugin/plugin.json.
+  const manifestDir = path.join(outDir, '.cursor-plugin');
+  fs.mkdirSync(manifestDir, { recursive: true });
+  const manifestPath = path.join(manifestDir, 'plugin.json');
+  fs.writeFileSync(
+    manifestPath,
+    JSON.stringify(manifest, null, 2) + '\n',
+    'utf8'
+  );
+  written.push('.cursor-plugin/plugin.json');
+
+  // Copy skills/ tree verbatim under <outDir>/skills.
+  const skillsDest = path.join(outDir, 'skills');
+  const copied = copyDirRecursive(skillsDir, skillsDest, 'skills');
+  for (const rel of copied) {
+    written.push(rel);
+  }
+
+  written.sort();
+  return { filesWritten: written };
+}
+
+module.exports = { buildManifest, convert, CURATED_KEYWORDS };

package/scripts/lib/install/doctor-codex-plugin.cjs

@@ -0,0 +1,388 @@
+'use strict';
+
+/**
+ * scripts/lib/install/doctor-codex-plugin.cjs — Phase 28.8 (Plan 28-8-C2).
+ *
+ * Codex Plugin doctor-mode reporter. Pure, read-only function that
+ * surfaces the maintainer's local Codex Plugin readiness state to
+ * `scripts/install.cjs --doctor`.
+ *
+ * Phase 28.8 D-03: Codex install-by-URL works today — `codex plugin
+ * marketplace add hegemonart/get-design-done` is a single command per
+ * developers.openai.com/codex/plugins/build. This reporter inspects the
+ * local repo for the artifacts that the Codex CLI consumes during that
+ * single step:
+ *   - `.codex-plugin/plugin.json` (manifest, built by Plan 28-8-C1)
+ *   - `.claude-plugin/marketplace.json` (catalog reused per D-14)
+ *
+ * Phase 28.8 D-10: tmpdir-safe. Read-only fs access; no writes anywhere;
+ * no `codex` CLI invocation; no access to `~/.codex/`. The cache install
+ * path is COMPUTED (pure string composition via `os.homedir()`), NOT
+ * verified. The maintainer verifies the cache after running the field-
+ * test command on a Codex-installed machine (see
+ * docs/codex-plugin-field-test.md).
+ *
+ * Phase 28.8 D-14: the `.claude-plugin/marketplace.json` catalog file is
+ * reused from Claude Code's marketplace per Codex's legacy-compatible
+ * catalog path. Whenever the catalog is present, `reusedFromClaude` is
+ * true — there is no separate Codex-specific catalog artifact.
+ *
+ * Phase 28.8 D-16: Codex is single-step (D-03). The multi-step pattern
+ * is Cursor Marketplace's domain (see doctor-cursor-marketplace.cjs).
+ * No review-window state machine here — verdict is binary:
+ * `ready-to-install` or `manifest-only-not-ready`.
+ *
+ * Design pattern (mirrors doctor-cursor-marketplace.cjs from Plan B2):
+ *   - `checkCodexPlugin(projectRoot)` returns a structured result object.
+ *   - `renderCodexPluginSection(result)` formats it as text.
+ *   - `computeCacheSimulationPath(...)` is pure string composition.
+ *
+ * Exports:
+ *   - `checkCodexPlugin(projectRoot)` — structured readiness status.
+ *   - `computeCacheSimulationPath(marketplaceName, pluginName, version)` —
+ *     pure path composition; no fs access.
+ *   - `renderCodexPluginSection(result)` — text formatter for the doctor
+ *     section.
+ *   - `MARKETPLACE_NAME` / `PLUGIN_NAME` / `MANIFEST_REL_PATH` /
+ *     `CATALOG_REL_PATH` — exposed for test cross-checks.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const MARKETPLACE_NAME = 'get-design-done';
+const PLUGIN_NAME = 'get-design-done';
+const MANIFEST_REL_PATH = '.codex-plugin/plugin.json';
+const CATALOG_REL_PATH = '.claude-plugin/marketplace.json';
+
+// Sentinel rendered when neither manifest nor package.json yields a version.
+const VERSION_PLACEHOLDER = '<version-from-package.json>';
+
+// Reuse C1's required-fields tuple. Lazy-require keeps the doctor module
+// independent of the converter's runtime cost when only the formatter is
+// imported (e.g., for a unit test of `computeCacheSimulationPath`).
+function loadConverterRequiredFields() {
+  // eslint-disable-next-line global-require
+  const c1 = require('./converters/codex-plugin.cjs');
+  return c1.MANIFEST_REQUIRED_FIELDS;
+}
+
+/**
+ * Validate a parsed `.codex-plugin/plugin.json` object against the C1
+ * spec (required fields + kebab-case name + semver version). Returns
+ * `{valid, errors}` — never throws. Mirrors the validateManifest helper
+ * in doctor-cursor-marketplace.cjs but uses Codex schema rules.
+ *
+ * @param {*} parsed                                  Parsed JSON value.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateCodexManifest(parsed) {
+  const errors = [];
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { valid: false, errors: ['manifest is not a JSON object'] };
+  }
+
+  const required = loadConverterRequiredFields();
+  for (const field of required) {
+    if (parsed[field] === undefined || parsed[field] === null) {
+      errors.push(`missing required field "${field}"`);
+    }
+  }
+
+  if (parsed.name !== undefined && parsed.name !== null) {
+    if (typeof parsed.name !== 'string' || parsed.name.length === 0) {
+      errors.push('name must be a non-empty string');
+    } else if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(parsed.name)) {
+      errors.push('name must be kebab-case (lowercase letters, digits, single hyphens)');
+    }
+  }
+
+  if (parsed.version !== undefined && parsed.version !== null) {
+    if (typeof parsed.version !== 'string' || !/^\d+\.\d+\.\d+/.test(parsed.version)) {
+      errors.push('version must be semver-shaped (x.y.z)');
+    }
+  }
+
+  if (parsed.description !== undefined && parsed.description !== null) {
+    if (typeof parsed.description !== 'string' || parsed.description.length === 0) {
+      errors.push('description must be a non-empty string');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Safely read + parse a JSON file. Returns `{exists, parsed, error}`.
+ * @param {string} filePath
+ * @returns {{ exists: boolean, parsed: *, error: string|null }}
+ */
+function readJsonFileSafe(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      return { exists: false, parsed: null, error: null };
+    }
+    return { exists: false, parsed: null, error: 'read failed: ' + e.message };
+  }
+  try {
+    return { exists: true, parsed: JSON.parse(raw), error: null };
+  } catch (e) {
+    return { exists: true, parsed: null, error: 'JSON parse error: ' + e.message };
+  }
+}
+
+/**
+ * Compute the install cache path WITHOUT touching the filesystem outside
+ * `projectRoot` (or anywhere, actually — this is pure string composition).
+ * The path schema is documented in research § Plugin cache layout:
+ *
+ *   ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/
+ *
+ * Per D-10 we do NOT verify this path exists — `codex` CLI may not be
+ * installed locally. The maintainer field-test (post-merge, on a Codex-
+ * installed machine) is the only place this path is actually checked.
+ *
+ * @param {string} marketplaceName  Catalog `.name` field (default
+ *                                  'get-design-done' for GDD).
+ * @param {string} pluginName       Manifest `.name` field (same as
+ *                                  marketplaceName for GDD).
+ * @param {string|null|undefined} version  Manifest `.version` field, or
+ *                                          null/undefined to render the
+ *                                          `<version-from-package.json>`
+ *                                          placeholder.
+ * @returns {string}                Absolute path with `~` expanded to
+ *                                  `os.homedir()`. Forward slashes per
+ *                                  Codex docs convention.
+ */
+function computeCacheSimulationPath(marketplaceName, pluginName, version) {
+  const home = os.homedir().replace(/\\/g, '/');
+  const ver = (typeof version === 'string' && version.length > 0)
+    ? version
+    : VERSION_PLACEHOLDER;
+  return home + '/.codex/plugins/cache/' + marketplaceName + '/' + pluginName + '/' + ver + '/';
+}
+
+/**
+ * Read-only Codex Plugin readiness reporter. Inspects `projectRoot` for
+ * the manifest + catalog artifacts and returns a structured verdict.
+ *
+ * No writes, no network, no `codex` CLI invocation. Tmpdir-safe per D-10.
+ *
+ * @param {string} projectRoot                       Path to inspect.
+ * @returns {{
+ *   manifest: {
+ *     present: boolean,
+ *     path: string,
+ *     valid: boolean | null,
+ *     version: string | null,
+ *     errors: string[],
+ *   },
+ *   catalog: {
+ *     present: boolean,
+ *     path: string,
+ *     referencesCodexPlugin: boolean,
+ *     reusedFromClaude: boolean,
+ *   },
+ *   cacheSimulation: {
+ *     path: string,
+ *     verified: false,
+ *     note: string,
+ *   },
+ *   verdict: 'ready-to-install' | 'manifest-only-not-ready',
+ *   verdictReasons: string[],
+ * }}
+ */
+function checkCodexPlugin(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new Error('checkCodexPlugin: projectRoot is required');
+  }
+
+  const manifestPath = path.join(projectRoot, MANIFEST_REL_PATH);
+  const catalogPath = path.join(projectRoot, CATALOG_REL_PATH);
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  const manifestRead = readJsonFileSafe(manifestPath);
+  const catalogRead = readJsonFileSafe(catalogPath);
+  const pkgRead = readJsonFileSafe(pkgPath);
+
+  // ── Manifest ────────────────────────────────────────────────────────
+  const manifest = {
+    present: false,
+    path: manifestPath,
+    valid: null,
+    version: null,
+    errors: [],
+  };
+
+  if (manifestRead.exists) {
+    manifest.present = true;
+    if (manifestRead.error) {
+      manifest.valid = false;
+      manifest.errors = [manifestRead.error];
+    } else {
+      const validation = validateCodexManifest(manifestRead.parsed);
+      manifest.valid = validation.valid;
+      manifest.errors = validation.errors;
+      if (manifestRead.parsed && typeof manifestRead.parsed.version === 'string') {
+        manifest.version = manifestRead.parsed.version;
+      }
+    }
+  }
+
+  // ── Catalog ─────────────────────────────────────────────────────────
+  const catalog = {
+    present: false,
+    path: catalogPath,
+    referencesCodexPlugin: false,
+    reusedFromClaude: false,
+  };
+
+  if (catalogRead.exists && !catalogRead.error
+      && catalogRead.parsed && typeof catalogRead.parsed === 'object') {
+    catalog.present = true;
+    catalog.reusedFromClaude = true;
+    // Reference check: any entry in `plugins[]` with name === manifest.name
+    // (or PLUGIN_NAME if manifest absent / unparsed) signals an explicit
+    // reference. Per D-14 the catalog is reused regardless.
+    const refName = (manifestRead.exists
+      && manifestRead.parsed
+      && typeof manifestRead.parsed.name === 'string'
+      && manifestRead.parsed.name.length > 0)
+      ? manifestRead.parsed.name
+      : PLUGIN_NAME;
+    if (Array.isArray(catalogRead.parsed.plugins)) {
+      catalog.referencesCodexPlugin = catalogRead.parsed.plugins.some(
+        (entry) => entry && typeof entry === 'object' && entry.name === refName
+      );
+    }
+  } else if (catalogRead.exists && catalogRead.error) {
+    // Malformed catalog — mark present but unreusable. Keep
+    // referencesCodexPlugin false. reusedFromClaude stays false since
+    // we couldn't actually parse it. This is a Rule 1 safety: the
+    // doctor should not lie about reusable catalogs.
+    catalog.present = true;
+    catalog.reusedFromClaude = false;
+  }
+
+  // ── Version (prefer manifest, fall back to package.json) ───────────
+  let resolvedVersion = manifest.version;
+  if (!resolvedVersion
+      && pkgRead.exists && !pkgRead.error
+      && pkgRead.parsed && typeof pkgRead.parsed.version === 'string') {
+    resolvedVersion = pkgRead.parsed.version;
+  }
+
+  // ── Cache simulation (computed, never verified) ─────────────────────
+  const cacheSimulation = {
+    path: computeCacheSimulationPath(MARKETPLACE_NAME, PLUGIN_NAME, resolvedVersion),
+    verified: false,
+    note: 'codex CLI may not be installed locally — path computed not verified',
+  };
+
+  // ── Verdict ─────────────────────────────────────────────────────────
+  const verdictReasons = [];
+  if (!manifest.present) {
+    verdictReasons.push('manifest absent');
+  } else if (manifest.valid === false) {
+    if (manifest.errors.length > 0 && /JSON parse error/.test(manifest.errors[0])) {
+      verdictReasons.push('manifest JSON parse error: ' + manifest.errors[0].replace(/^JSON parse error:\s*/, ''));
+    } else {
+      verdictReasons.push('manifest schema invalid: ' + (manifest.errors[0] || 'unknown reason'));
+    }
+  }
+  if (!catalog.present) {
+    verdictReasons.push('catalog absent');
+  }
+
+  const verdict = (manifest.present && manifest.valid === true && catalog.present)
+    ? 'ready-to-install'
+    : 'manifest-only-not-ready';
+
+  return {
+    manifest,
+    catalog,
+    cacheSimulation,
+    verdict,
+    verdictReasons,
+  };
+}
+
+/**
+ * Render the inspection result as the doctor section text. Pure — no IO.
+ *
+ * Output shape (per plan <interfaces>):
+ *
+ *   Codex Plugin status
+ *     manifest .codex-plugin/plugin.json: present (version 1.28.8) — schema valid
+ *     catalog .claude-plugin/marketplace.json: present — referenced by codex-plugin per D-14 (legacy-compatible catalog reuse)
+ *     install path (computed, not verified): ~/.codex/plugins/cache/get-design-done/get-design-done/1.28.8/
+ *     verdict: ready-to-install
+ *
+ * @param {ReturnType<checkCodexPlugin>} result
+ * @returns {string} Multi-line text ending with a trailing newline.
+ */
+function renderCodexPluginSection(result) {
+  if (!result || typeof result !== 'object') {
+    throw new Error('renderCodexPluginSection: result is required');
+  }
+
+  const lines = ['Codex Plugin status'];
+
+  // Manifest line
+  let manifestState;
+  if (!result.manifest.present) {
+    manifestState = 'absent';
+  } else if (result.manifest.errors.length > 0
+      && /^JSON parse error/.test(result.manifest.errors[0])) {
+    manifestState = 'present — ' + result.manifest.errors[0];
+  } else {
+    const ver = result.manifest.version
+      ? '(version ' + result.manifest.version + ')'
+      : '(version unknown)';
+    if (result.manifest.valid === true) {
+      manifestState = 'present ' + ver + ' — schema valid';
+    } else {
+      const firstErr = result.manifest.errors[0] || 'unknown error';
+      manifestState = 'present ' + ver + ' — schema invalid: ' + firstErr;
+    }
+  }
+  lines.push('  manifest .codex-plugin/plugin.json: ' + manifestState);
+
+  // Catalog line
+  let catalogState;
+  if (!result.catalog.present) {
+    catalogState = 'absent';
+  } else if (result.catalog.referencesCodexPlugin) {
+    catalogState = 'present — referenced by codex-plugin per D-14 (legacy-compatible catalog reuse)';
+  } else {
+    catalogState = 'present — would be reused per D-14 (legacy-compatible catalog reuse)';
+  }
+  lines.push('  catalog .claude-plugin/marketplace.json: ' + catalogState);
+
+  // Install path line — always shows the "computed, not verified" guarantee
+  lines.push('  install path (computed, not verified): ' + result.cacheSimulation.path);
+
+  // Verdict line — parenthetical reasons only when non-ready
+  let verdictLine = '  verdict: ' + result.verdict;
+  if (result.verdict !== 'ready-to-install' && result.verdictReasons.length > 0) {
+    verdictLine += ' (' + result.verdictReasons.join('; ') + ')';
+  }
+  lines.push(verdictLine);
+
+  return lines.join('\n') + '\n';
+}
+
+module.exports = {
+  checkCodexPlugin,
+  computeCacheSimulationPath,
+  renderCodexPluginSection,
+  validateCodexManifest,
+  MARKETPLACE_NAME,
+  PLUGIN_NAME,
+  MANIFEST_REL_PATH,
+  CATALOG_REL_PATH,
+};