codex-plugin-doctor 0.15.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/core/inspector-bridge.d.ts +23 -0
- package/dist/core/inspector-bridge.js +100 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/run-cli.js +32 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -178,6 +178,8 @@ codex-plugin-doctor self-test
|
|
|
178
178
|
codex-plugin-doctor doctor
|
|
179
179
|
codex-plugin-doctor doctor npm codex-plugin-doctor
|
|
180
180
|
codex-plugin-doctor doctor npm codex-plugin-doctor --json --output npm-preinstall.json
|
|
181
|
+
codex-plugin-doctor doctor inspector .
|
|
182
|
+
codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
|
|
181
183
|
codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
|
|
182
184
|
codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
|
|
183
185
|
codex-plugin-doctor doctor recommend .
|
|
@@ -254,7 +256,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
|
|
|
254
256
|
|
|
255
257
|
`self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
|
|
256
258
|
|
|
257
|
-
`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
|
|
259
|
+
`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
|
|
258
260
|
|
|
259
261
|
`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
|
|
260
262
|
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export interface DoctorInspectorReport {
|
|
2
|
+
schemaVersion: "1.0.0";
|
|
3
|
+
generatedAt: string;
|
|
4
|
+
kind: "doctor.inspector";
|
|
5
|
+
targetPath: string;
|
|
6
|
+
status: "pass" | "fail";
|
|
7
|
+
exitCode: 0 | 1;
|
|
8
|
+
mcpConfigPath: string | null;
|
|
9
|
+
serverName: string | null;
|
|
10
|
+
command: {
|
|
11
|
+
executable: string;
|
|
12
|
+
args: string[];
|
|
13
|
+
} | null;
|
|
14
|
+
message: string;
|
|
15
|
+
}
|
|
16
|
+
export interface BuildDoctorInspectorReportOptions {
|
|
17
|
+
serverName?: string | null;
|
|
18
|
+
}
|
|
19
|
+
export declare function buildDoctorInspectorReport(targetPath: string, options?: BuildDoctorInspectorReportOptions): Promise<DoctorInspectorReport>;
|
|
20
|
+
export declare function renderDoctorInspectorReportJson(report: DoctorInspectorReport): string;
|
|
21
|
+
export declare function renderDoctorInspectorReport(report: DoctorInspectorReport, options?: {
|
|
22
|
+
outputPath?: string | null;
|
|
23
|
+
}): string;
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { readJsonFile } from "./read-json-file.js";
|
|
3
|
+
import { discoverPackage } from "./discover-package.js";
|
|
4
|
+
function isPlainObject(value) {
|
|
5
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
6
|
+
}
|
|
7
|
+
function isPathWithinRoot(rootPath, candidatePath) {
|
|
8
|
+
const relativePath = path.relative(rootPath, candidatePath);
|
|
9
|
+
return (relativePath === "" ||
|
|
10
|
+
(!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
|
|
11
|
+
}
|
|
12
|
+
function buildFailure(targetPath, message, mcpConfigPath = null) {
|
|
13
|
+
return {
|
|
14
|
+
schemaVersion: "1.0.0",
|
|
15
|
+
generatedAt: new Date().toISOString(),
|
|
16
|
+
kind: "doctor.inspector",
|
|
17
|
+
targetPath: path.resolve(targetPath),
|
|
18
|
+
status: "fail",
|
|
19
|
+
exitCode: 1,
|
|
20
|
+
mcpConfigPath,
|
|
21
|
+
serverName: null,
|
|
22
|
+
command: null,
|
|
23
|
+
message
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
export async function buildDoctorInspectorReport(targetPath, options = {}) {
|
|
27
|
+
const discoveredPackage = await discoverPackage(targetPath);
|
|
28
|
+
if (!discoveredPackage?.manifest.mcpServers) {
|
|
29
|
+
return buildFailure(targetPath, "The target package does not declare an MCP server config in `.codex-plugin/plugin.json`.");
|
|
30
|
+
}
|
|
31
|
+
const mcpConfigPath = path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers);
|
|
32
|
+
if (!isPathWithinRoot(discoveredPackage.rootPath, mcpConfigPath)) {
|
|
33
|
+
return buildFailure(discoveredPackage.rootPath, "The target package points the MCP server config outside the package root.", mcpConfigPath);
|
|
34
|
+
}
|
|
35
|
+
let parsedConfig;
|
|
36
|
+
try {
|
|
37
|
+
parsedConfig = await readJsonFile(mcpConfigPath);
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return buildFailure(discoveredPackage.rootPath, "The MCP server config could not be parsed as JSON.", mcpConfigPath);
|
|
41
|
+
}
|
|
42
|
+
if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
|
|
43
|
+
return buildFailure(discoveredPackage.rootPath, "The MCP server config does not contain a valid `mcpServers` object.", mcpConfigPath);
|
|
44
|
+
}
|
|
45
|
+
const serverNames = Object.keys(parsedConfig.mcpServers).sort();
|
|
46
|
+
const selectedServerName = options.serverName ?? serverNames[0] ?? null;
|
|
47
|
+
if (!selectedServerName || !serverNames.includes(selectedServerName)) {
|
|
48
|
+
return buildFailure(discoveredPackage.rootPath, options.serverName
|
|
49
|
+
? `The MCP server config does not contain server \`${options.serverName}\`.`
|
|
50
|
+
: "The MCP server config does not contain any server entries.", mcpConfigPath);
|
|
51
|
+
}
|
|
52
|
+
return {
|
|
53
|
+
schemaVersion: "1.0.0",
|
|
54
|
+
generatedAt: new Date().toISOString(),
|
|
55
|
+
kind: "doctor.inspector",
|
|
56
|
+
targetPath: discoveredPackage.rootPath,
|
|
57
|
+
status: "pass",
|
|
58
|
+
exitCode: 0,
|
|
59
|
+
mcpConfigPath,
|
|
60
|
+
serverName: selectedServerName,
|
|
61
|
+
command: {
|
|
62
|
+
executable: "npx",
|
|
63
|
+
args: [
|
|
64
|
+
"-y",
|
|
65
|
+
"@modelcontextprotocol/inspector",
|
|
66
|
+
"--config",
|
|
67
|
+
mcpConfigPath,
|
|
68
|
+
"--server",
|
|
69
|
+
selectedServerName
|
|
70
|
+
]
|
|
71
|
+
},
|
|
72
|
+
message: "Run this command to open the MCP Inspector for the selected packaged server."
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
export function renderDoctorInspectorReportJson(report) {
|
|
76
|
+
return JSON.stringify(report, null, 2);
|
|
77
|
+
}
|
|
78
|
+
export function renderDoctorInspectorReport(report, options = {}) {
|
|
79
|
+
const lines = [
|
|
80
|
+
"Doctor MCP Inspector",
|
|
81
|
+
"====================",
|
|
82
|
+
`Target: ${report.targetPath}`,
|
|
83
|
+
`Status: ${report.status.toUpperCase()}`,
|
|
84
|
+
`Message: ${report.message}`
|
|
85
|
+
];
|
|
86
|
+
if (report.mcpConfigPath) {
|
|
87
|
+
lines.push(`Config: ${report.mcpConfigPath}`);
|
|
88
|
+
}
|
|
89
|
+
if (report.serverName) {
|
|
90
|
+
lines.push(`Server: ${report.serverName}`);
|
|
91
|
+
}
|
|
92
|
+
if (options.outputPath) {
|
|
93
|
+
lines.push(`Output: ${options.outputPath}`);
|
|
94
|
+
}
|
|
95
|
+
if (report.command) {
|
|
96
|
+
lines.push("", "Command", "-------");
|
|
97
|
+
lines.push([report.command.executable, ...report.command.args].join(" "));
|
|
98
|
+
}
|
|
99
|
+
return lines.join("\n");
|
|
100
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -8,6 +8,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
|
|
|
8
8
|
export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
|
|
9
9
|
export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";
|
|
10
10
|
export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson, type BuildDoctorRiskDiffReportOptions, type DoctorRiskDiffReport, type RiskDiffFinding, type RiskFindingCategory } from "./core/risk-diff.js";
|
|
11
|
+
export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson, type BuildDoctorInspectorReportOptions, type DoctorInspectorReport } from "./core/inspector-bridge.js";
|
|
11
12
|
export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, type EcosystemAuditReport } from "./audit/ecosystem-audit.js";
|
|
12
13
|
export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
|
|
13
14
|
export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";
|
package/dist/index.js
CHANGED
|
@@ -8,6 +8,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
|
|
|
8
8
|
export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
|
|
9
9
|
export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
|
|
10
10
|
export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
|
|
11
|
+
export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson } from "./core/inspector-bridge.js";
|
|
11
12
|
export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
|
|
12
13
|
export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
|
|
13
14
|
export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
|
package/dist/run-cli.js
CHANGED
|
@@ -19,6 +19,7 @@ import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBu
|
|
|
19
19
|
import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
|
|
20
20
|
import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
|
|
21
21
|
import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
|
|
22
|
+
import { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson } from "./core/inspector-bridge.js";
|
|
22
23
|
import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
|
|
23
24
|
import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
|
|
24
25
|
import { initCiWorkflow } from "./core/init-ci.js";
|
|
@@ -64,7 +65,7 @@ const defaultIo = {
|
|
|
64
65
|
}
|
|
65
66
|
};
|
|
66
67
|
function printUsage(io) {
|
|
67
|
-
io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n codex-plugin-doctor mcp <path> [--json] [--output <path>]\n codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n codex-plugin-doctor doctor [npm <package>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|export --bundle <path>|snapshot|clients|--json|--update-check]\n codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n codex-plugin-doctor init-ci [path]\n codex-plugin-doctor self-test\n codex-plugin-doctor list --installed\n codex-plugin-doctor explain <finding-id>\n codex-plugin-doctor --version\n\nFirst run:\n codex-plugin-doctor doctor\n codex-plugin-doctor self-test\n codex-plugin-doctor init my-plugin\n codex-plugin-doctor check . --runtime --explain");
|
|
68
|
+
io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n codex-plugin-doctor mcp <path> [--json] [--output <path>]\n codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n codex-plugin-doctor doctor [npm <package>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|export --bundle <path>|snapshot|clients|--json|--update-check]\n codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n codex-plugin-doctor init-ci [path]\n codex-plugin-doctor self-test\n codex-plugin-doctor list --installed\n codex-plugin-doctor explain <finding-id>\n codex-plugin-doctor --version\n\nFirst run:\n codex-plugin-doctor doctor\n codex-plugin-doctor self-test\n codex-plugin-doctor init my-plugin\n codex-plugin-doctor check . --runtime --explain");
|
|
68
69
|
}
|
|
69
70
|
function renderInstalledPlugins(plugins) {
|
|
70
71
|
const lines = [
|
|
@@ -291,6 +292,36 @@ export async function runCli(args, io = defaultIo, options = {}) {
|
|
|
291
292
|
io.writeStdout(renderedReport);
|
|
292
293
|
return report.exitCode;
|
|
293
294
|
}
|
|
295
|
+
if (maybePath === "inspector") {
|
|
296
|
+
const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
|
|
297
|
+
? remainingArgs[0]
|
|
298
|
+
: ".";
|
|
299
|
+
const inspectorFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
|
|
300
|
+
? remainingArgs.slice(1)
|
|
301
|
+
: remainingArgs;
|
|
302
|
+
const jsonOutput = inspectorFlags.includes("--json");
|
|
303
|
+
const outputIndex = inspectorFlags.indexOf("--output");
|
|
304
|
+
const outputPath = outputIndex === -1 ? null : inspectorFlags[outputIndex + 1];
|
|
305
|
+
const serverIndex = inspectorFlags.indexOf("--server");
|
|
306
|
+
const serverName = serverIndex === -1 ? null : inspectorFlags[serverIndex + 1];
|
|
307
|
+
if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
|
|
308
|
+
io.writeStderr("Missing path after --output.");
|
|
309
|
+
return 2;
|
|
310
|
+
}
|
|
311
|
+
if (serverIndex !== -1 && (!serverName || serverName.startsWith("--"))) {
|
|
312
|
+
io.writeStderr("Missing server name after --server.");
|
|
313
|
+
return 2;
|
|
314
|
+
}
|
|
315
|
+
const report = await buildDoctorInspectorReport(targetPath, { serverName });
|
|
316
|
+
const renderedReport = jsonOutput
|
|
317
|
+
? renderDoctorInspectorReportJson(report)
|
|
318
|
+
: renderDoctorInspectorReport(report, { outputPath });
|
|
319
|
+
if (outputPath) {
|
|
320
|
+
await writeFile(outputPath, renderedReport, "utf8");
|
|
321
|
+
}
|
|
322
|
+
io.writeStdout(renderedReport);
|
|
323
|
+
return report.exitCode;
|
|
324
|
+
}
|
|
294
325
|
if (maybePath === "trust") {
|
|
295
326
|
const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
|
|
296
327
|
? remainingArgs[0]
|
package/package.json
CHANGED