codex-plugin-doctor 1.46.1 → 1.48.0

package/dist/core/external-validation-corpus.js

@@ -0,0 +1,271 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { buildGenericMcpDoctor } from "../mcp/generic-mcp-doctor.js";
+import { packageVersion } from "../version.js";
+import { buildPackageFingerprint } from "./attestation.js";
+import { readJsonFile } from "./read-json-file.js";
+import { validatePlugin } from "./validate-plugin.js";
+export class ExternalCorpusManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExternalCorpusManifestError";
+    }
+}
+const topLevelKeys = new Set(["schemaVersion", "targets"]);
+const targetKeys = new Set([
+    "id",
+    "profile",
+    "sourceType",
+    "disclosure",
+    "path",
+    "mode",
+    "contentDigest",
+    "expectedStatus",
+    "reviews"
+]);
+const reviewKeys = new Set(["findingId", "fingerprint", "classification"]);
+const profiles = new Set(["healthy", "broken", "edge-case"]);
+const sourceTypes = new Set([
+    "public-package",
+    "local-snapshot",
+    "derived-fixture"
+]);
+const modes = new Set(["codex-plugin", "generic-mcp"]);
+const statuses = new Set(["pass", "warn", "fail"]);
+const classifications = new Set([
+    "true_positive",
+    "false_positive",
+    "unclear"
+]);
+const sha256Digest = /^sha256:[a-f0-9]{64}$/;
+const findingFingerprint = /^[a-f0-9]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+        throw new ExternalCorpusManifestError(`${label} contains unsupported field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`);
+    }
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ExternalCorpusManifestError(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+function parseReview(value, targetId, index) {
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} must be an object.`);
+    }
+    rejectUnknownKeys(value, reviewKeys, `Corpus target ${targetId} review ${index}`);
+    const findingId = requireString(value.findingId, `Corpus target ${targetId} review ${index} findingId`);
+    const fingerprint = requireString(value.fingerprint, `Corpus target ${targetId} review ${index} fingerprint`);
+    const classification = value.classification;
+    if (typeof classification !== "string" || !classifications.has(classification)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} has an unsupported classification.`);
+    }
+    if (!findingFingerprint.test(fingerprint)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} fingerprint must be a sha256 fingerprint.`);
+    }
+    return {
+        findingId,
+        fingerprint,
+        classification: classification
+    };
+}
+async function parseTarget(value, manifestDirectory, index) {
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${index} must be an object.`);
+    }
+    rejectUnknownKeys(value, targetKeys, `Corpus target ${index}`);
+    const id = requireString(value.id, `Corpus target ${index} id`);
+    const targetPath = requireString(value.path, `Corpus target ${id} path`);
+    if (path.posix.isAbsolute(targetPath) || path.win32.isAbsolute(targetPath)) {
+        throw new ExternalCorpusManifestError("Corpus target path must be relative to the manifest file.");
+    }
+    if (typeof value.profile !== "string" || !profiles.has(value.profile)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported profile.`);
+    }
+    if (typeof value.sourceType !== "string" || !sourceTypes.has(value.sourceType)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported sourceType.`);
+    }
+    if (value.disclosure !== "anonymized") {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} disclosure must be anonymized.`);
+    }
+    if (typeof value.mode !== "string" || !modes.has(value.mode)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported mode.`);
+    }
+    if (typeof value.expectedStatus !== "string" || !statuses.has(value.expectedStatus)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported expectedStatus.`);
+    }
+    if (typeof value.contentDigest !== "string" || !sha256Digest.test(value.contentDigest)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} contentDigest must be a sha256 digest.`);
+    }
+    if (!Array.isArray(value.reviews)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} reviews must be an array.`);
+    }
+    const reviews = value.reviews.map((review, reviewIndex) => parseReview(review, id, reviewIndex));
+    const reviewKeySet = new Set();
+    for (const review of reviews) {
+        const key = `${review.findingId}:${review.fingerprint}`;
+        if (reviewKeySet.has(key)) {
+            throw new ExternalCorpusManifestError(`Corpus target ${id} contains a duplicate finding review.`);
+        }
+        reviewKeySet.add(key);
+    }
+    const resolvedPath = path.resolve(manifestDirectory, targetPath);
+    try {
+        if (!(await stat(resolvedPath)).isDirectory()) {
+            throw new Error("not a directory");
+        }
+    }
+    catch {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} directory does not exist.`);
+    }
+    return {
+        id,
+        profile: value.profile,
+        sourceType: value.sourceType,
+        disclosure: "anonymized",
+        path: targetPath,
+        mode: value.mode,
+        contentDigest: value.contentDigest,
+        expectedStatus: value.expectedStatus,
+        reviews,
+        resolvedPath
+    };
+}
+export async function loadExternalCorpusManifest(manifestPath) {
+    let value;
+    try {
+        value = await readJsonFile(path.resolve(manifestPath));
+    }
+    catch {
+        throw new ExternalCorpusManifestError("Corpus manifest could not be read as JSON.");
+    }
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError("Corpus manifest must be an object.");
+    }
+    rejectUnknownKeys(value, topLevelKeys, "Corpus manifest");
+    if (value.schemaVersion !== "1.0.0") {
+        throw new ExternalCorpusManifestError("Unsupported corpus manifest schemaVersion.");
+    }
+    if (!Array.isArray(value.targets) || value.targets.length === 0) {
+        throw new ExternalCorpusManifestError("Corpus manifest targets must be a non-empty array.");
+    }
+    const manifestDirectory = path.dirname(path.resolve(manifestPath));
+    const targets = await Promise.all(value.targets.map((target, index) => parseTarget(target, manifestDirectory, index)));
+    const seenIds = new Set();
+    for (const target of targets) {
+        if (seenIds.has(target.id)) {
+            throw new ExternalCorpusManifestError(`Corpus target id ${target.id} is duplicated.`);
+        }
+        seenIds.add(target.id);
+    }
+    return { schemaVersion: "1.0.0", targets };
+}
+function findingKey(findingId, fingerprint) {
+    return `${findingId}:${fingerprint}`;
+}
+function emptyClassificationCounts() {
+    return {
+        truePositive: 0,
+        falsePositive: 0,
+        unclear: 0,
+        missingExpectedFinding: 0
+    };
+}
+function addClassificationCounts(total, value) {
+    return {
+        truePositive: total.truePositive + value.truePositive,
+        falsePositive: total.falsePositive + value.falsePositive,
+        unclear: total.unclear + value.unclear,
+        missingExpectedFinding: total.missingExpectedFinding + value.missingExpectedFinding
+    };
+}
+async function evaluateExternalCorpusTarget(target, options) {
+    const report = target.mode === "generic-mcp"
+        ? await buildGenericMcpDoctor(target.resolvedPath, options.environment)
+        : await validatePlugin(target.resolvedPath);
+    const packageFingerprint = await buildPackageFingerprint(target.resolvedPath);
+    const findings = report.findings.map((finding) => {
+        if (!finding.fingerprint) {
+            throw new ExternalCorpusManifestError(`Corpus target ${target.id} produced a finding without a fingerprint.`);
+        }
+        return {
+            findingId: finding.id,
+            fingerprint: finding.fingerprint
+        };
+    });
+    const reviewsByKey = new Map(target.reviews.map((review) => [
+        findingKey(review.findingId, review.fingerprint),
+        review
+    ]));
+    const actualKeys = new Set(findings.map((finding) => findingKey(finding.findingId, finding.fingerprint)));
+    const missingExpectedFinding = target.reviews.filter((review) => review.classification === "true_positive" &&
+        !actualKeys.has(findingKey(review.findingId, review.fingerprint))).length;
+    const classifiedFindings = findings
+        .map((finding) => ({
+        ...finding,
+        classification: reviewsByKey.get(findingKey(finding.findingId, finding.fingerprint))?.classification ?? "unreviewed"
+    }))
+        .sort((left, right) => findingKey(left.findingId, left.fingerprint)
+        .localeCompare(findingKey(right.findingId, right.fingerprint)));
+    const classificationCounts = {
+        truePositive: classifiedFindings.filter((finding) => finding.classification === "true_positive").length,
+        falsePositive: classifiedFindings.filter((finding) => finding.classification === "false_positive").length,
+        unclear: classifiedFindings.filter((finding) => finding.classification === "unclear").length,
+        missingExpectedFinding
+    };
+    const digestMatched = packageFingerprint.digest === target.contentDigest;
+    const expectationMatched = digestMatched &&
+        report.status === target.expectedStatus &&
+        classificationCounts.falsePositive === 0 &&
+        classificationCounts.unclear === 0 &&
+        classificationCounts.missingExpectedFinding === 0 &&
+        classifiedFindings.every((finding) => finding.classification !== "unreviewed");
+    return {
+        id: target.id,
+        profile: target.profile,
+        sourceType: target.sourceType,
+        disclosure: target.disclosure,
+        mode: target.mode,
+        expected: {
+            status: target.expectedStatus,
+            contentDigest: target.contentDigest,
+            findings: [...target.reviews].sort((left, right) => findingKey(left.findingId, left.fingerprint)
+                .localeCompare(findingKey(right.findingId, right.fingerprint)))
+        },
+        actual: {
+            status: report.status,
+            contentDigest: packageFingerprint.digest,
+            findings: classifiedFindings
+        },
+        digestMatched,
+        classificationCounts,
+        expectationMatched
+    };
+}
+export async function buildExternalValidationCorpusReport(manifestPath, options = {}) {
+    const manifest = await loadExternalCorpusManifest(manifestPath);
+    const cases = await Promise.all(manifest.targets.map((target) => evaluateExternalCorpusTarget(target, options)));
+    const failedExpectations = cases.filter((result) => !result.expectationMatched).length;
+    const classificationCounts = cases.reduce((total, result) => addClassificationCounts(total, result.classificationCounts), emptyClassificationCounts());
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.validation.corpus",
+        corpusType: "external",
+        generatedAt: new Date().toISOString(),
+        version: packageVersion,
+        summary: {
+            status: failedExpectations === 0 ? "pass" : "fail",
+            caseCount: cases.length,
+            passedExpectations: cases.length - failedExpectations,
+            failedExpectations,
+            runtimeCases: 0,
+            classificationCounts
+        },
+        cases
+    };
+}

package/dist/core/init-git-hooks.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 const isWindows = process.platform === "win32";
 const preCommitHook = isWindows
@@ -81,6 +81,45 @@ async function fileExists(filePath) {
         return false;
     }
 }
+async function resolveHooksDirectory(rootPath) {
+    const dotGitPath = path.join(rootPath, ".git");
+    let dotGitStat;
+    try {
+        dotGitStat = await stat(dotGitPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return path.join(dotGitPath, "hooks");
+        }
+        throw error;
+    }
+    if (dotGitStat.isDirectory()) {
+        return path.join(dotGitPath, "hooks");
+    }
+    let gitFile;
+    try {
+        gitFile = (await readFile(dotGitPath, "utf8")).trim();
+    }
+    catch {
+        throw new Error("Invalid linked-worktree .git file.");
+    }
+    const match = /^gitdir:\s*(.+)$/i.exec(gitFile);
+    if (!match) {
+        throw new Error("Invalid linked-worktree .git file.");
+    }
+    const worktreeGitDir = path.resolve(rootPath, match[1]);
+    let commonDirValue;
+    try {
+        commonDirValue = (await readFile(path.join(worktreeGitDir, "commondir"), "utf8")).trim();
+    }
+    catch {
+        throw new Error("Invalid linked-worktree commondir file.");
+    }
+    if (!commonDirValue) {
+        throw new Error("Invalid linked-worktree commondir file.");
+    }
+    return path.join(path.resolve(worktreeGitDir, commonDirValue), "hooks");
+}
 async function writeHook(hookPath, content, force) {
     const exists = await fileExists(hookPath);
     if (exists && !force) {
@@ -94,14 +133,14 @@ async function writeHook(hookPath, content, force) {
 }
 export async function removeGitHooks(targetPath) {
     const rootPath = path.resolve(targetPath);
-    const hooksDir = path.join(rootPath, ".git", "hooks");
+    const hooksDir = await resolveHooksDirectory(rootPath);
     const hookNames = Array.from(new Set([`pre-commit${hookExtension}`, `pre-push${hookExtension}`, "pre-commit", "pre-push"]));
     const removed = [];
     const skipped = [];
     for (const name of hookNames) {
         const hookPath = path.join(hooksDir, name);
         if (await fileExists(hookPath)) {
-            const content = await import("node:fs/promises").then((m) => m.readFile(hookPath, "utf8"));
+            const content = await readFile(hookPath, "utf8");
             if (content.includes("Generated by codex-plugin-doctor init git-hooks")) {
                 await import("node:fs/promises").then((m) => m.rm(hookPath));
                 removed.push(hookPath);
@@ -115,7 +154,7 @@ export async function removeGitHooks(targetPath) {
 }
 export async function initGitHooks(targetPath, options = {}) {
     const rootPath = path.resolve(targetPath);
-    const hooksDir = path.join(rootPath, ".git", "hooks");
+    const hooksDir = await resolveHooksDirectory(rootPath);
     const force = options.force ?? false;
     await mkdir(hooksDir, { recursive: true });
     const hookPaths = [];

package/dist/core/output-contract.js

@@ -95,6 +95,29 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.validation.corpus",
         required: ["schemaVersion", "kind", "generatedAt", "version", "summary", "cases"]
     },
+    {
+        id: "doctor.validation.corpus.external.json",
+        command: "codex-plugin-doctor doctor corpus --manifest <corpus.json> --json",
+        outputKind: "doctor.validation.corpus",
+        required: ["schemaVersion", "kind", "corpusType", "generatedAt", "version", "summary", "cases"]
+    },
+    {
+        id: "doctor.validation.corpus.metrics.json",
+        command: "codex-plugin-doctor doctor corpus metrics --manifest <corpus.json> --json",
+        outputKind: "doctor.validation.corpus.metrics",
+        required: [
+            "schemaVersion",
+            "kind",
+            "generatedAt",
+            "version",
+            "status",
+            "exitCode",
+            "summary",
+            "thresholds",
+            "thresholdChecks",
+            "targets"
+        ]
+    },
     {
         id: "doctor.recommendations.json",
         command: "codex-plugin-doctor doctor recommend <path> --json",
@@ -115,13 +138,13 @@ const publicSchemaDefinitions = [
         id: "doctor.runtime.plan.json",
         command: "codex-plugin-doctor doctor runtime-plan <path> --json",
         outputKind: "doctor.runtime.plan",
-        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "digest", "summary", "servers", "findings"]
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "execution", "digest", "summary", "servers", "findings"]
     },
     {
         id: "doctor.runtime.policy.json",
         command: "codex-plugin-doctor doctor runtime-policy <path> --json",
         outputKind: "doctor.runtime.policy",
-        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "planDigest", "recommendation", "summary", "servers"]
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "execution", "planDigest", "recommendation", "summary", "servers"]
     },
     {
         id: "doctor.review.bundle.json",

package/dist/core/release-check.d.ts

@@ -1,4 +1,4 @@
-import type { CheckOptions, CheckResult } from "../domain/types.js";
+import type { CheckOptions, CheckResult, RuntimeSandboxMode } from "../domain/types.js";
 export interface ReleaseCheckReport {
     targetPath: string;
     status: "pass" | "fail";
@@ -41,6 +41,7 @@ export interface BuildReleaseCheckOptions {
     env?: Record<string, string | undefined>;
     platform?: NodeJS.Platform;
     runtime?: boolean;
+    runtimeSandbox?: RuntimeSandboxMode;
     runCheck?: (targetPath: string, options: CheckOptions) => Promise<CheckResult>;
 }
 export declare function buildReleaseMetadataCheck(targetPath: string): Promise<ReleaseMetadataCheck>;

package/dist/core/release-check.js

@@ -105,7 +105,8 @@ export async function buildReleaseCheck(targetPath, options = {}) {
     const platform = options.platform ?? process.platform;
     const runtimeProbeEnabled = options.runtime ?? false;
     const validationResult = await (options.runCheck ?? validatePlugin)(resolvedPath, {
-        runtime: runtimeProbeEnabled
+        runtime: runtimeProbeEnabled,
+        ...(options.runtimeSandbox ? { runtimeSandbox: options.runtimeSandbox } : {})
     });
     const securityResult = await buildSecurityAudit(resolvedPath);
     const depResult = await buildDepAudit(resolvedPath);

package/dist/core/release-evidence.d.ts

@@ -5,7 +5,7 @@ import { type SecurityAudit } from "../security/security-audit.js";
 import { type TrustScoreReport } from "../security/trust-score.js";
 import { type RuntimeApprovalReport } from "./runtime-plan.js";
 import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
-import type { CheckResult } from "../domain/types.js";
+import type { CheckOptions, CheckResult, RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 type EvidenceStatus = "pass" | "warn" | "fail";
 export interface DoctorReleaseEvidenceSignature {
     status: "signed";
@@ -52,6 +52,7 @@ export interface DoctorReleaseEvidenceReport {
         }>;
     };
     runtimeApproval: RuntimeApprovalReport;
+    execution?: RuntimeExecutionEvidence;
     package: DoctorReleaseEvidencePackageMetadata;
     git: DoctorReleaseEvidenceGitMetadata;
     attestation: DoctorAttestation;
@@ -109,8 +110,10 @@ export interface BuildDoctorReleaseEvidenceOptions {
     allowUntagged?: boolean;
     requireRuntimeApproval?: boolean;
     runtimeApprovalDigest?: string | null;
+    runtime?: boolean;
+    sandbox?: RuntimeSandboxMode;
     environment?: CompatibilityEnvironment;
-    runCheck?: (targetPath: string) => Promise<CheckResult>;
+    runCheck?: (targetPath: string, options?: CheckOptions) => Promise<CheckResult>;
     performanceThresholds?: DoctorPerformanceThresholdOptions;
 }
 export declare function buildDoctorReleaseEvidenceReport(targetPath: string, options: BuildDoctorReleaseEvidenceOptions): Promise<DoctorReleaseEvidenceReport>;

package/dist/core/release-evidence.js

@@ -10,6 +10,7 @@ import { readJsonFile } from "./read-json-file.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
 import { buildTrustScore } from "../security/trust-score.js";
 import { buildDoctorRuntimePlan, evaluateRuntimeApproval, runtimeApprovalPassed } from "./runtime-plan.js";
+import { validatePlugin } from "./validate-plugin.js";
 import { packageVersion } from "../version.js";
 const execFileAsync = promisify(execFile);
 function isPlainObject(value) {
@@ -152,6 +153,7 @@ function buildReleaseEvidenceSigningPayload(report) {
         git: report.git,
         releaseGates: report.releaseGates,
         runtimeApproval: report.runtimeApproval,
+        ...(report.execution ? { execution: report.execution } : {}),
         attestation: {
             version: report.attestation.version,
             subject: report.attestation.subject,
@@ -193,6 +195,13 @@ function signReleaseEvidence(report, signingKey, keyHint) {
 export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
     const rootPath = path.resolve(targetPath);
     const security = await buildSecurityAudit(rootPath);
+    const runCheck = options.runCheck ?? validatePlugin;
+    const checkOptions = options.runtime
+        ? {
+            runtime: true,
+            ...(options.sandbox ? { runtimeSandbox: options.sandbox } : {})
+        }
+        : {};
     const [attestation, corpus, performance, trust, packageMetadata, git, runtimePlan] = await Promise.all([
         buildDoctorAttestation(rootPath, {
             signingKey: options.signingKey,
@@ -202,13 +211,13 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         buildDoctorValidationCorpusReport({ environment: options.environment }),
         buildDoctorPerformanceReport(rootPath, {
             environment: options.environment,
-            runCheck: options.runCheck,
+            runCheck: (pathToCheck) => runCheck(pathToCheck, checkOptions),
             thresholds: options.performanceThresholds
         }),
         buildTrustScore(rootPath, { securityAudit: security }),
         readPackageMetadata(rootPath),
         readGitMetadata(rootPath),
-        buildDoctorRuntimePlan(rootPath)
+        buildDoctorRuntimePlan(rootPath, new Date().toISOString(), options.sandbox ? { sandbox: options.sandbox } : {})
     ]);
     const normalizedPackageMetadata = {
         name: packageMetadata.name ?? attestation.subject.name,
@@ -244,6 +253,7 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         git,
         releaseGates,
         runtimeApproval,
+        ...(options.runtime ? { execution: runtimePlan.execution } : {}),
         attestation,
         attestationVerification,
         corpus,

package/dist/core/runtime-plan.d.ts

@@ -1,5 +1,6 @@
 import { type SecurityAudit } from "../security/security-audit.js";
 import type { Finding } from "../domain/types.js";
+import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 type RuntimePlanStatus = "pass" | "warn" | "fail";
 type RuntimePlanRiskLevel = "low" | "medium" | "high";
 type RuntimePlanTransport = "stdio" | "http";
@@ -23,6 +24,7 @@ export interface DoctorRuntimePlan {
     status: RuntimePlanStatus;
     exitCode: 0 | 1;
     runtimeExecution: "not_started";
+    execution: RuntimeExecutionEvidence;
     digest: string;
     summary: {
         serverCount: number;
@@ -40,7 +42,9 @@ export interface RuntimeApprovalReport {
     approvedDigest: string | null;
     message: string;
 }
-export declare function buildDoctorRuntimePlan(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePlan>;
+export declare function buildDoctorRuntimePlan(targetPath: string, generatedAt?: string, options?: {
+    sandbox?: RuntimeSandboxMode;
+}): Promise<DoctorRuntimePlan>;
 export declare function evaluateRuntimeApproval(plan: DoctorRuntimePlan, options: {
     required: boolean;
     approvedDigest?: string | null;

package/dist/core/runtime-plan.js

@@ -4,6 +4,7 @@ import { packageVersion } from "../version.js";
 import { discoverPackage } from "./discover-package.js";
 import { readJsonFile } from "./read-json-file.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
+import { DOCKER_RUNTIME_IMAGE } from "./runtime-sandbox.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -51,6 +52,7 @@ function planDigestPayload(plan) {
         schemaVersion: plan.schemaVersion,
         kind: "doctor.runtime.plan.digest.v1",
         version: plan.version,
+        execution: plan.execution,
         status: plan.status,
         summary: plan.summary,
         servers: plan.servers,
@@ -64,10 +66,18 @@ function planDigestPayload(plan) {
 function buildRuntimePlanDigest(plan) {
     return sha256(stableStringify(planDigestPayload(plan)));
 }
-export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString()) {
+export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString(), options = {}) {
     const rootPath = path.resolve(targetPath);
     const discoveredPackage = await discoverPackage(rootPath);
     const security = await buildSecurityAudit(rootPath);
+    const execution = options.sandbox === "docker"
+        ? {
+            backend: "docker",
+            image: DOCKER_RUNTIME_IMAGE,
+            network: "none",
+            packageMount: "read_only"
+        }
+        : { backend: "native", image: null, network: "host", packageMount: "host" };
     if (!discoveredPackage?.manifest.mcpServers) {
         const partialPlan = {
             schemaVersion: "1.0.0",
@@ -77,6 +87,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             status: security.status,
             exitCode: (security.status === "fail" ? 1 : 0),
             runtimeExecution: "not_started",
+            execution,
             summary: {
                 serverCount: 0,
                 executableServerCount: 0,
@@ -146,6 +157,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
                 : "pass",
         exitCode: (highRiskServerCount > 0 ? 1 : 0),
         runtimeExecution: "not_started",
+        execution,
         summary: {
             serverCount: servers.length,
             executableServerCount: servers.filter((server) => server.command).length,

package/dist/core/runtime-policy.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 import { type DoctorRuntimePlan, type RuntimePlanServer } from "./runtime-plan.js";
 export type RuntimePolicyDecision = "allow" | "review" | "sandbox_recommended" | "deny";
 export interface RuntimePolicyRecommendation {
@@ -14,6 +15,7 @@ export interface DoctorRuntimePolicyReport {
     status: "pass" | "warn" | "fail";
     exitCode: 0 | 1;
     runtimeExecution: "not_started";
+    execution: RuntimeExecutionEvidence;
     planDigest: string;
     recommendation: RuntimePolicyRecommendation;
     summary: {
@@ -29,6 +31,8 @@ export interface DoctorRuntimePolicyReport {
         reasons: string[];
     }>;
 }
-export declare function buildDoctorRuntimePolicyReport(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePolicyReport>;
+export declare function buildDoctorRuntimePolicyReport(targetPath: string, generatedAt?: string, options?: {
+    sandbox?: RuntimeSandboxMode;
+}): Promise<DoctorRuntimePolicyReport>;
 export declare function renderDoctorRuntimePolicyJson(report: DoctorRuntimePolicyReport): string;
 export declare function renderDoctorRuntimePolicy(report: DoctorRuntimePolicyReport): string;

package/dist/core/runtime-policy.js

@@ -91,8 +91,8 @@ function buildRecommendation(plan, decision, reasons) {
         ]
     };
 }
-export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = new Date().toISOString()) {
-    const plan = await buildDoctorRuntimePlan(targetPath, generatedAt);
+export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = new Date().toISOString(), options = {}) {
+    const plan = await buildDoctorRuntimePlan(targetPath, generatedAt, options);
     const servers = plan.servers.map((server) => ({
         name: server.name,
         decision: serverDecision(server),
@@ -118,6 +118,7 @@ export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = n
         status,
         exitCode: status === "fail" ? 1 : 0,
         runtimeExecution: "not_started",
+        execution: plan.execution,
         planDigest: plan.digest,
         recommendation,
         summary: {

package/dist/core/runtime-probe.d.ts

@@ -1,5 +1,6 @@
-import type { DiscoveredPackage, RuntimeProbeResult } from "../domain/types.js";
+import type { DiscoveredPackage, RuntimeProbeResult, RuntimeSandboxMode } from "../domain/types.js";
 export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: {
     startupTimeoutMs?: number;
+    sandbox?: RuntimeSandboxMode;
     transcript?: (line: string) => void;
 }): Promise<RuntimeProbeResult>;