@provartesting/provardx-cli 1.5.0-dev.1 → 1.5.0

package/lib/services/auth/loginFlow.d.ts

@@ -0,0 +1,68 @@
+/// <reference types="node" resolution-mode="require"/>
+export declare const CALLBACK_PORTS: number[];
+/**
+ * Generate a PKCE code_verifier / code_challenge pair (S256 method, as required by Cognito).
+ */
+export declare function generatePkce(): {
+    verifier: string;
+    challenge: string;
+};
+/**
+ * Generate a random nonce for OIDC replay-attack prevention.
+ * Required by the OpenID Connect spec when requesting an id_token.
+ */
+export declare function generateNonce(): string;
+/**
+ * Generate a random state value for CSRF protection.
+ * Required by Cognito Managed Login even though it is optional per the OAuth 2.0 spec.
+ */
+export declare function generateState(): string;
+/**
+ * Try each registered callback port in order; return the first that is free.
+ */
+export declare function findAvailablePort(): Promise<number>;
+/**
+ * Return the platform-specific command and argument list for opening a URL
+ * in the system browser. The URL is passed as an argument — never interpolated
+ * into a shell string — to avoid command injection. Exported so tests can
+ * assert the correct command is chosen without actually spawning a process.
+ */
+export declare function getBrowserCommand(url: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+export declare function openBrowser(url: string): void;
+/**
+ * Spin up a temporary localhost HTTP server that accepts exactly one callback
+ * from Cognito's Hosted UI, extracts the auth code, and shuts down.
+ */
+export declare function listenForCallback(port: number, expectedState?: string): Promise<string>;
+export interface CognitoTokens {
+    access_token: string;
+    id_token: string;
+    token_type: string;
+    expires_in: number;
+}
+/**
+ * Exchange a PKCE auth code for Cognito tokens via the standard token endpoint.
+ * Uses the Authorization Code + PKCE grant — no client secret required.
+ */
+export declare function exchangeCodeForTokens(opts: {
+    code: string;
+    redirectUri: string;
+    clientId: string;
+    verifier: string;
+    tokenEndpoint: string;
+}): Promise<CognitoTokens>;
+/**
+ * The login command calls loginFlowClient.X() so tests can replace properties with stubs.
+ */
+export declare const loginFlowClient: {
+    generatePkce: typeof generatePkce;
+    generateNonce: typeof generateNonce;
+    generateState: typeof generateState;
+    findAvailablePort: typeof findAvailablePort;
+    openBrowser: typeof openBrowser;
+    listenForCallback: (port: number, expectedState?: string) => Promise<string>;
+    exchangeCodeForTokens: typeof exchangeCodeForTokens;
+};

package/lib/services/auth/loginFlow.js

@@ -0,0 +1,216 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/* eslint-disable camelcase */
+import crypto from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+import { spawn } from 'node:child_process';
+import { URL } from 'node:url';
+// All three ports must be pre-registered in both the Cognito App Client and the Salesforce External Client Application (SF ECA).
+// Both providers require redirect_uri to exactly match a registered callback URL — no wildcards.
+export const CALLBACK_PORTS = [1717, 7890, 8080];
+// ── PKCE ─────────────────────────────────────────────────────────────────────
+/**
+ * Generate a PKCE code_verifier / code_challenge pair (S256 method, as required by Cognito).
+ */
+export function generatePkce() {
+    const verifier = crypto.randomBytes(32).toString('base64url');
+    const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+/**
+ * Generate a random nonce for OIDC replay-attack prevention.
+ * Required by the OpenID Connect spec when requesting an id_token.
+ */
+export function generateNonce() {
+    return crypto.randomBytes(16).toString('base64url');
+}
+/**
+ * Generate a random state value for CSRF protection.
+ * Required by Cognito Managed Login even though it is optional per the OAuth 2.0 spec.
+ */
+export function generateState() {
+    return crypto.randomBytes(16).toString('base64url');
+}
+// ── Port selection ────────────────────────────────────────────────────────────
+/**
+ * Try each registered callback port in order; return the first that is free.
+ */
+export async function findAvailablePort() {
+    for (const port of CALLBACK_PORTS) {
+        // Sequential by design — we need the first free registered port, not all of them.
+        // eslint-disable-next-line no-await-in-loop
+        if (await isPortFree(port))
+            return port;
+    }
+    throw new Error('Could not bind to any registered callback port (1717, 7890, 8080). ' +
+        'Check that no other process is using these ports and try again.');
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const probe = http.createServer();
+        probe.once('error', () => resolve(false));
+        probe.listen(port, '127.0.0.1', () => {
+            probe.close(() => resolve(true));
+        });
+    });
+}
+// ── Browser open ──────────────────────────────────────────────────────────────
+/**
+ * Return the platform-specific command and argument list for opening a URL
+ * in the system browser. The URL is passed as an argument — never interpolated
+ * into a shell string — to avoid command injection. Exported so tests can
+ * assert the correct command is chosen without actually spawning a process.
+ */
+export function getBrowserCommand(url, platform = process.platform) {
+    switch (platform) {
+        case 'darwin':
+            return { cmd: 'open', args: [url] };
+        case 'win32':
+            // Pass the URL via $args[0] so it is never interpolated into the -Command
+            // string — avoids quote-breaking and injection risk from special characters.
+            return { cmd: 'powershell.exe', args: ['-NoProfile', '-Command', 'Start-Process $args[0]', '-args', url] };
+        default:
+            return { cmd: 'xdg-open', args: [url] };
+    }
+}
+export function openBrowser(url) {
+    // detached:true + stdio:'ignore' + unref() is the standard Node.js pattern for
+    // fire-and-forget child processes — the event loop will not wait for them to exit.
+    const { cmd, args } = getBrowserCommand(url);
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    // Suppress unhandled-error crashes if the browser executable is not found.
+    // The login URL is already printed to the terminal so the user can open it manually.
+    child.on('error', () => {
+        /* intentional no-op */
+    });
+    child.unref();
+}
+// ── Localhost callback server ─────────────────────────────────────────────────
+/**
+ * Spin up a temporary localhost HTTP server that accepts exactly one callback
+ * from Cognito's Hosted UI, extracts the auth code, and shuts down.
+ */
+export function listenForCallback(port, expectedState) {
+    return new Promise((resolve, reject) => {
+        // Track open sockets so we can forcibly destroy them on shutdown.
+        // This is a Node 18.0/18.1 fallback for server.closeAllConnections(), which
+        // was added in Node 18.2. Without it a browser that ignores Connection:close
+        // could keep the event loop alive after server.close() returns.
+        const openSockets = new Set();
+        const closeServer = (srv) => {
+            srv.close();
+            if (typeof srv.closeAllConnections === 'function') {
+                srv.closeAllConnections();
+            }
+            else {
+                openSockets.forEach((s) => s.destroy());
+            }
+        };
+        const server = http.createServer((req, res) => {
+            const parsed = new URL(req.url ?? '/', `http://localhost:${port}`);
+            const code = parsed.searchParams.get('code');
+            const error = parsed.searchParams.get('error');
+            const description = parsed.searchParams.get('error_description');
+            const callbackState = parsed.searchParams.get('state');
+            if (expectedState && callbackState !== expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8', Connection: 'close' });
+                res.end('<html><body style="font-family:sans-serif;padding:2rem;max-width:480px">' +
+                    '<h2 style="color:#c23934">Authentication failed</h2>' +
+                    '<p>Invalid state parameter — possible CSRF attack. Please try again.</p>' +
+                    '</body></html>');
+                closeServer(server);
+                reject(new Error('OAuth callback state mismatch — possible CSRF. Try again.'));
+                return;
+            }
+            // 'Connection: close' tells the browser to close the TCP connection after
+            // this response so server.close() has no lingering keep-alive sockets to
+            // wait for, allowing the Node.js event loop to exit promptly.
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', Connection: 'close' });
+            res.end('<html><body style="font-family:sans-serif;padding:2rem;max-width:480px">' +
+                '<h2 style="color:#0070d2">Authentication complete</h2>' +
+                '<p>You can close this tab and return to the terminal.</p>' +
+                '</body></html>');
+            closeServer(server);
+            if (code) {
+                resolve(code);
+            }
+            else {
+                reject(new Error(description ?? error ?? 'No authorisation code received from identity provider'));
+            }
+        });
+        server.on('connection', (socket) => {
+            openSockets.add(socket);
+            socket.once('close', () => openSockets.delete(socket));
+        });
+        server.listen(port, '127.0.0.1');
+        server.on('error', (err) => reject(err));
+    });
+}
+/**
+ * Exchange a PKCE auth code for Cognito tokens via the standard token endpoint.
+ * Uses the Authorization Code + PKCE grant — no client secret required.
+ */
+export async function exchangeCodeForTokens(opts) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: opts.code,
+        redirect_uri: opts.redirectUri,
+        client_id: opts.clientId,
+        code_verifier: opts.verifier,
+    }).toString();
+    const { status, responseBody } = await httpsPost(opts.tokenEndpoint, body, {
+        'Content-Type': 'application/x-www-form-urlencoded',
+    });
+    if (status !== 200) {
+        throw new Error(`Token exchange failed (${status}): ${responseBody}`);
+    }
+    return JSON.parse(responseBody);
+}
+// ── Internal HTTPS helper ─────────────────────────────────────────────────────
+const REQUEST_TIMEOUT_MS = 30000;
+function httpsPost(url, body, headers) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const req = https.request({
+            hostname: parsed.hostname,
+            port: parsed.port || undefined,
+            path: parsed.pathname + parsed.search,
+            method: 'POST',
+            headers: {
+                ...headers,
+                'Content-Length': Buffer.byteLength(body).toString(),
+            },
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk.toString('utf-8');
+            });
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, responseBody: data }));
+        });
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error(`Token exchange timed out after ${REQUEST_TIMEOUT_MS / 1000}s`));
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+// ── Indirection object (sinon-stubbable) ──────────────────────────────────────
+/**
+ * The login command calls loginFlowClient.X() so tests can replace properties with stubs.
+ */
+export const loginFlowClient = {
+    generatePkce,
+    generateNonce,
+    generateState,
+    findAvailablePort,
+    openBrowser,
+    listenForCallback: listenForCallback,
+    exchangeCodeForTokens,
+};
+//# sourceMappingURL=loginFlow.js.map

package/lib/services/auth/loginFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loginFlow.js","sourceRoot":"","sources":["../../../src/services/auth/loginFlow.ts"],"names":[],"mappings":"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"}

package/lib/services/projectValidation.d.ts

@@ -62,6 +62,8 @@ export interface ProjectValidationResult {
         uncovered_test_cases: string[];
     };
     saved_to: string | null;
+    /** Directories within plans/ that are missing a .planitem file and will be silently ignored by the Provar runner. */
+    plan_integrity_warnings?: string[];
     /** Set when save_results was requested but the write failed (disk full, permissions, etc.). */
     save_error?: string;
 }
@@ -88,11 +90,12 @@ export declare function readProjectContext(projectPath: string): {
     context: ProjectContext;
 };
 export declare function resolveTestInstance(instancePath: string, projectPath: string): TestCaseInput | null;
-export declare function readSuiteDirectory(dirPath: string, name: string, projectPath: string, depth?: number, coveredPaths?: Set<string>, idMap?: Map<string, string>): TestSuiteInput;
-export declare function readPlanDirectory(planPath: string, name: string, projectPath: string, coveredPaths?: Set<string>, idMap?: Map<string, string>): TestPlanInput;
+export declare function readSuiteDirectory(dirPath: string, name: string, projectPath: string, depth?: number, coveredPaths?: Set<string>, idMap?: Map<string, string>, planIntegrityWarnings?: string[]): TestSuiteInput;
+export declare function readPlanDirectory(planPath: string, name: string, projectPath: string, coveredPaths?: Set<string>, idMap?: Map<string, string>, planIntegrityWarnings?: string[]): TestPlanInput;
 export declare function readPlansDir(projectPath: string): {
     plans: TestPlanInput[];
     coveredPaths: Set<string>;
+    planIntegrityWarnings: string[];
 };
 /**
  * Collects all .testcase file basenames (without extension) found under tests/.

package/lib/services/projectValidation.js

@@ -70,7 +70,9 @@ export function resolveProjectRoot(givenPath) {
                 candidates.push(sub);
         }
     }
-    catch { /* skip */ }
+    catch {
+        /* skip */
+    }
     if (candidates.length === 1)
         return { root: candidates[0], candidates: [] };
     return { root: givenPath, candidates }; // caller handles 0 or multiple
@@ -127,7 +129,9 @@ export function readProjectContext(projectPath) {
                     unencryptedSecretCount++;
             }
         }
-        catch { /* skip */ }
+        catch {
+            /* skip */
+        }
     }
     return {
         projectName,
@@ -158,16 +162,21 @@ function resolveTestInstanceFull(instancePath, projectPath) {
         // Bounds check: only read test case files within the project directory
         const tcInBounds = tcFullPath === projResolved || tcFullPath.startsWith(projResolved + path.sep);
         // Derive name from the bounds-checked resolved path to prevent injection via crafted testCasePath
-        const tcName = tcInBounds
-            ? path.basename(tcFullPath, '.testcase')
-            : path.basename(testCasePath, '.testcase');
+        const tcName = tcInBounds ? path.basename(tcFullPath, '.testcase') : path.basename(testCasePath, '.testcase');
         if (tcInBounds && fs.existsSync(tcFullPath)) {
             try {
                 xml_content = fs.readFileSync(tcFullPath, 'utf-8');
             }
-            catch { /* xml_content stays undefined */ }
+            catch {
+                /* xml_content stays undefined */
+            }
         }
-        return { testCase: { name: tcName, xml_content }, testCasePath, testCaseId };
+        // Only expose testCasePath/testCaseId when in-bounds — out-of-bounds paths must not affect coverage totals
+        return {
+            testCase: { name: tcName, xml_content },
+            testCasePath: tcInBounds ? testCasePath : null,
+            testCaseId: tcInBounds ? testCaseId : null,
+        };
     }
     catch {
         return { testCase: null, testCasePath: null, testCaseId: null };
@@ -188,7 +197,7 @@ function accumulateCoveredPath(testCasePath, testCaseId, coveredPaths, idMap) {
             coveredPaths.add(resolved);
     }
 }
-export function readSuiteDirectory(dirPath, name, projectPath, depth = 0, coveredPaths, idMap) {
+export function readSuiteDirectory(dirPath, name, projectPath, depth = 0, coveredPaths, idMap, planIntegrityWarnings) {
     const testCases = [];
     const testSuites = [];
     if (depth > MAX_SUITE_DEPTH)
@@ -200,7 +209,13 @@ export function readSuiteDirectory(dirPath, name, projectPath, depth = 0, covere
                 continue;
             const fullPath = path.join(dirPath, entry.name);
             if (entry.isDirectory() && !entry.name.startsWith('.')) {
-                testSuites.push(readSuiteDirectory(fullPath, entry.name, projectPath, depth + 1, coveredPaths, idMap));
+                const subHasPlanItem = fs.existsSync(path.join(fullPath, '.planitem'));
+                if (planIntegrityWarnings && !subHasPlanItem) {
+                    const rel = path.relative(projectPath, fullPath).replace(/\\/g, '/');
+                    planIntegrityWarnings.push(`${rel}/ is missing a .planitem file — test instances in this suite will be invisible to the runner.`);
+                    continue;
+                }
+                testSuites.push(readSuiteDirectory(fullPath, entry.name, projectPath, depth + 1, subHasPlanItem ? coveredPaths : undefined, subHasPlanItem ? idMap : undefined, planIntegrityWarnings));
             }
             else if (entry.name.endsWith('.testinstance')) {
                 const { testCase, testCasePath, testCaseId } = resolveTestInstanceFull(fullPath, projectPath);
@@ -211,10 +226,12 @@ export function readSuiteDirectory(dirPath, name, projectPath, depth = 0, covere
             }
         }
     }
-    catch { /* skip */ }
+    catch {
+        /* skip */
+    }
     return { name, test_cases: testCases, test_suites: testSuites };
 }
-export function readPlanDirectory(planPath, name, projectPath, coveredPaths, idMap) {
+export function readPlanDirectory(planPath, name, projectPath, coveredPaths, idMap, planIntegrityWarnings) {
     const testCases = [];
     const testSuites = [];
     try {
@@ -224,7 +241,13 @@ export function readPlanDirectory(planPath, name, projectPath, coveredPaths, idM
                 continue;
             const fullPath = path.join(planPath, entry.name);
             if (entry.isDirectory() && !entry.name.startsWith('.')) {
-                testSuites.push(readSuiteDirectory(fullPath, entry.name, projectPath, 0, coveredPaths, idMap));
+                const suiteHasPlanItem = fs.existsSync(path.join(fullPath, '.planitem'));
+                if (planIntegrityWarnings && !suiteHasPlanItem) {
+                    const rel = path.relative(projectPath, fullPath).replace(/\\/g, '/');
+                    planIntegrityWarnings.push(`${rel}/ is missing a .planitem file — test instances in this suite will be invisible to the runner.`);
+                    continue;
+                }
+                testSuites.push(readSuiteDirectory(fullPath, entry.name, projectPath, 0, suiteHasPlanItem ? coveredPaths : undefined, suiteHasPlanItem ? idMap : undefined, planIntegrityWarnings));
             }
             else if (entry.name.endsWith('.testinstance')) {
                 const { testCase, testCasePath, testCaseId } = resolveTestInstanceFull(fullPath, projectPath);
@@ -235,14 +258,17 @@ export function readPlanDirectory(planPath, name, projectPath, coveredPaths, idM
             }
         }
     }
-    catch { /* skip */ }
+    catch {
+        /* skip */
+    }
     return { name, test_cases: testCases, test_suites: testSuites };
 }
 export function readPlansDir(projectPath) {
     const plansDir = path.join(projectPath, 'plans');
     const coveredPaths = new Set();
+    const planIntegrityWarnings = [];
     if (!fs.existsSync(plansDir))
-        return { plans: [], coveredPaths };
+        return { plans: [], coveredPaths, planIntegrityWarnings };
     // Build UUID→path map once so the plan walk can resolve testCaseId fallbacks
     // without a separate pass over the tests/ directory later.
     const idMap = buildTestCaseIdMap(projectPath);
@@ -253,11 +279,17 @@ export function readPlansDir(projectPath) {
             if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules')
                 continue;
             const planPath = path.join(plansDir, entry.name);
-            plans.push(readPlanDirectory(planPath, entry.name, projectPath, coveredPaths, idMap));
+            const planHasPlanItem = fs.existsSync(path.join(planPath, '.planitem'));
+            if (!planHasPlanItem) {
+                planIntegrityWarnings.push(`plans/${entry.name}/ is missing a .planitem file — this plan will not be recognised by the Provar runner.`);
+            }
+            plans.push(readPlanDirectory(planPath, entry.name, projectPath, planHasPlanItem ? coveredPaths : undefined, planHasPlanItem ? idMap : undefined, planIntegrityWarnings));
         }
     }
-    catch { /* skip */ }
-    return { plans, coveredPaths };
+    catch {
+        /* skip */
+    }
+    return { plans, coveredPaths, planIntegrityWarnings };
 }
 /**
  * Builds a map of testcase UUID (registryId / id / guid) → project-relative path.
@@ -284,15 +316,20 @@ function buildTestCaseIdMap(projectPath) {
                         const rel = path.relative(projectPath, fullPath).replace(/\\/g, '/');
                         for (const attr of ['registryId', 'id', 'guid']) {
                             const m = content.match(new RegExp(`${attr}=["']([^"']+)["']`));
-                            if (m?.[1] && !idMap.has(m[1]))
+                            // Skip id="1" — new generator emits this literal and it is not UUID-unique
+                            if (m?.[1] && m[1] !== '1' && !idMap.has(m[1]))
                                 idMap.set(m[1], rel);
                         }
                     }
-                    catch { /* skip */ }
+                    catch {
+                        /* skip */
+                    }
                 }
             }
         }
-        catch { /* skip */ }
+        catch {
+            /* skip */
+        }
     }
     walk(testsDir);
     return idMap;
@@ -320,7 +357,9 @@ export function collectAllTestCaseNames(projectPath) {
                     names.push(path.basename(entry.name, '.testcase'));
             }
         }
-        catch { /* skip */ }
+        catch {
+            /* skip */
+        }
     }
     walk(testsDir);
     return names;
@@ -360,11 +399,15 @@ export function collectCoveredPathsFromDisk(projectPath) {
                                 covered.add(resolvedPath);
                         }
                     }
-                    catch { /* skip */ }
+                    catch {
+                        /* skip */
+                    }
                 }
             }
         }
-        catch { /* skip */ }
+        catch {
+            /* skip */
+        }
     }
     walk(plansDir);
     return covered;
@@ -390,7 +433,9 @@ export function findUncoveredTestCases(projectPath, coveredPaths) {
                 }
             }
         }
-        catch { /* skip */ }
+        catch {
+            /* skip */
+        }
     }
     walk(testsDir);
     return uncovered.sort();
@@ -426,7 +471,7 @@ function tcIssuesToQhViolations(tc) {
             appliesTo: issue.applies_to,
         });
     }
-    for (const bp of (tc.best_practices_violations ?? [])) {
+    for (const bp of tc.best_practices_violations ?? []) {
         violations.push({
             number: num++,
             ruleId: bp.rule_id,
@@ -530,7 +575,13 @@ export function buildQhReport(result, projectName) {
     return {
         reportInfo: {
             name: `VR-LOCAL-${now.toISOString().replace(/[:.]/g, '-').slice(0, 19)}`,
-            generatedAt: now.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }),
+            generatedAt: now.toLocaleDateString('en-US', {
+                year: 'numeric',
+                month: 'short',
+                day: 'numeric',
+                hour: '2-digit',
+                minute: '2-digit',
+            }),
             exportedAt: now.toISOString(),
             source: 'provar-mcp-local',
         },
@@ -551,9 +602,7 @@ export function buildQhReport(result, projectName) {
     };
 }
 export function saveResults(projectPath, resultsDir, report, projectName) {
-    const targetDir = resultsDir
-        ? path.resolve(resultsDir)
-        : path.join(projectPath, 'provardx', 'validation');
+    const targetDir = resultsDir ? path.resolve(resultsDir) : path.join(projectPath, 'provardx', 'validation');
     fs.mkdirSync(targetDir, { recursive: true });
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
     const safeName = projectName.replace(/[^a-zA-Z0-9_-]/g, '-').toLowerCase();
@@ -582,7 +631,9 @@ export function validateProjectFromPath(options) {
     }
     const { root: projectRoot, candidates } = resolveProjectRoot(resolved);
     if (candidates.length > 1) {
-        throw new ProjectValidationError('AMBIGUOUS_PROJECT', `Multiple Provar projects found under "${resolved}". Specify the exact project directory: ${candidates.map((c) => path.basename(c)).join(', ')}`);
+        throw new ProjectValidationError('AMBIGUOUS_PROJECT', `Multiple Provar projects found under "${resolved}". Specify the exact project directory: ${candidates
+            .map((c) => path.basename(c))
+            .join(', ')}`);
     }
     if (!fs.existsSync(path.join(projectRoot, '.testproject'))) {
         throw new ProjectValidationError('NOT_A_PROJECT', `No Provar project found at "${projectRoot}". Ensure the path points to a directory containing a .testproject file.`);
@@ -592,7 +643,7 @@ export function validateProjectFromPath(options) {
     const { projectName, context } = readProjectContext(projectRoot);
     // 2. Read plan hierarchy from plans/ directory; covered paths are computed
     //    as a byproduct of the walk — no second traversal needed.
-    const { plans: testPlans, coveredPaths } = readPlansDir(projectRoot);
+    const { plans: testPlans, coveredPaths, planIntegrityWarnings } = readPlansDir(projectRoot);
     // 3. Validate
     const input = {
         name: projectName,
@@ -672,6 +723,7 @@ export function validateProjectFromPath(options) {
             uncovered_test_cases: uncoveredTestCases,
         },
         saved_to: savedTo,
+        ...(planIntegrityWarnings.length > 0 ? { plan_integrity_warnings: planIntegrityWarnings } : {}),
         save_error: saveError,
     };
 }