@mpgd/cli 0.9.0 → 0.10.1

package/dist/game-acceptance.d.ts

@@ -1,4 +1,5 @@
 export declare const defaultGameAcceptanceCommandTimeoutMs: number;
+export declare const maximumGameplayE2EReportBytes: number;
 export declare function resolveGameAcceptanceReleaseManifestFile(gameRoot: string, env?: NodeJS.ProcessEnv): string;
 export type GameAcceptanceStatus = 'failed' | 'passed';
 export type GameAcceptanceStepStatus = 'failed' | 'passed' | 'skipped';
@@ -37,6 +38,13 @@ export interface GameAcceptanceReport {
       readonly parseError: string | null;
       readonly value: unknown;
     } | null;
+    readonly gameplayE2E: {
+      readonly file: string;
+      readonly found: boolean;
+      readonly parseError: string | null;
+      readonly validationError: string | null;
+      readonly value: unknown;
+    } | null;
   };
 }
 export interface GameAcceptanceCommandResult {
@@ -48,6 +56,12 @@ export interface RunGameAcceptanceInput {
   readonly gameRoot: string;
   readonly reportDir: string;
   readonly releaseManifestFile?: string;
+  readonly gameplayE2EReportFile?: string;
+  readonly requireGameplayE2EReport?: boolean;
+  /** Step that must replace any previous gameplay report before evidence is accepted. */
+  readonly gameplayE2EStepId?: string;
+  /** Resolved acceptance targets that gameplay evidence is allowed to represent. */
+  readonly gameplayE2ETargets?: readonly string[];
   readonly options: Readonly<Record<string, string | boolean | null>>;
   readonly steps: readonly GameAcceptanceStep[];
   readonly env?: NodeJS.ProcessEnv;

package/dist/game-acceptance.js

@@ -1,8 +1,10 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
+import { collectGameplayE2EPathEvidence, maximumGameplayE2EStates, readGameplayE2EPlan, resolveGameplayE2EPathInsideGameRoot, } from './gameplay-e2e.js';
 export const defaultGameAcceptanceCommandTimeoutMs = 30 * 60 * 1000;
 const defaultGameAcceptanceReleaseManifestFile = 'artifacts/release-manifest.json';
+export const maximumGameplayE2EReportBytes = 1024 * 1024;
 export function resolveGameAcceptanceReleaseManifestFile(gameRoot, env = process.env) {
     const configuredFile = env.MPGD_RELEASE_MANIFEST_FILE;
     return path.resolve(gameRoot, configuredFile === undefined || configuredFile.length === 0
@@ -22,7 +24,31 @@ export function runGameAcceptance(input) {
     const startedAtMs = now();
     const results = [];
     let failed = false;
+    let gameplayE2EReportFileToReplace;
+    if (input.gameplayE2EStepId !== undefined) {
+        if (input.gameplayE2EReportFile === undefined) {
+            throw new Error('A gameplay E2E evidence step needs a report file.');
+        }
+        if (input.steps.filter((step) => step.id === input.gameplayE2EStepId).length !== 1) {
+            throw new Error(`Gameplay E2E evidence step must occur exactly once: ${input.gameplayE2EStepId}`);
+        }
+        gameplayE2EReportFileToReplace = resolveGameplayE2EPathInsideGameRoot(gameRoot, input.gameplayE2EReportFile, 'Gameplay E2E report');
+    }
     for (const step of input.steps) {
+        if (!failed
+            && step.id === input.gameplayE2EStepId
+            && gameplayE2EReportFileToReplace !== undefined) {
+            try {
+                // Earlier acceptance commands are untrusted and may have changed the path hierarchy.
+                const verifiedGameplayE2EReportFile = resolveGameplayE2EPathInsideGameRoot(gameRoot, gameplayE2EReportFileToReplace, 'Gameplay E2E report');
+                rmSync(verifiedGameplayE2EReportFile, { force: true });
+            }
+            catch (error) {
+                results.push(failedStepResult(step, now(), formatError(error)));
+                failed = true;
+                continue;
+            }
+        }
         if (failed) {
             results.push(skippedStepResult(step, now(), 'A previous acceptance step failed.'));
             continue;
@@ -69,18 +95,25 @@ export function runGameAcceptance(input) {
         });
         failed = status === 'failed';
     }
-    const finishedAtMs = now();
     const releaseManifest = readOptionalJsonEvidence(input.releaseManifestFile, gameRoot);
+    const gameplayE2E = readGameplayE2EEvidence(input.gameplayE2EReportFile, gameRoot, input.releaseManifestFile, typeof input.options.profile === 'string' ? input.options.profile : undefined, input.gameplayE2ETargets);
+    const evidenceFailed = input.requireGameplayE2EReport === true
+        && (gameplayE2E === null
+            || !gameplayE2E.found
+            || gameplayE2E.parseError !== null
+            || gameplayE2E.validationError !== null);
+    const finishedAtMs = now();
     const report = {
         schemaVersion: 1,
         generatedAt: new Date(finishedAtMs).toISOString(),
-        status: failed ? 'failed' : 'passed',
+        status: failed || evidenceFailed ? 'failed' : 'passed',
         gameRoot,
         durationMs: Math.max(0, finishedAtMs - startedAtMs),
         options: input.options,
         steps: results,
         evidence: {
             releaseManifest,
+            gameplayE2E,
         },
     };
     const reportDir = path.resolve(input.reportDir);
@@ -126,6 +159,22 @@ export function renderGameAcceptanceMarkdown(report) {
     else {
         lines.push(`- Release manifest: ${escapeMarkdownInline(report.evidence.releaseManifest.file)}`);
     }
+    lines.push('', '## Gameplay E2E Evidence', '');
+    if (report.evidence.gameplayE2E === null) {
+        lines.push('- Gameplay E2E evidence collection disabled.');
+    }
+    else if (!report.evidence.gameplayE2E.found) {
+        lines.push(`- Gameplay E2E report not found: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`);
+    }
+    else if (report.evidence.gameplayE2E.parseError !== null) {
+        lines.push(`- Gameplay E2E report is invalid JSON: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`, `  - ${escapeMarkdownInline(report.evidence.gameplayE2E.parseError)}`);
+    }
+    else if (report.evidence.gameplayE2E.validationError !== null) {
+        lines.push(`- Gameplay E2E report failed validation: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`, `  - ${escapeMarkdownInline(report.evidence.gameplayE2E.validationError)}`);
+    }
+    else {
+        lines.push(`- Gameplay E2E report: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`);
+    }
     return `${lines.join('\n')}\n`;
 }
 function runAcceptanceCommand(step, env, timeoutMs) {
@@ -188,32 +237,296 @@ function readOptionalJsonEvidence(file, gameRoot) {
     if (file === undefined) {
         return null;
     }
-    const resolved = path.resolve(gameRoot, file);
+    let resolved;
+    try {
+        resolved = resolveGameplayE2EPathInsideGameRoot(gameRoot, file, 'Release manifest');
+    }
+    catch (error) {
+        return {
+            file: '<outside-game-root>',
+            found: false,
+            parseError: formatError(error),
+            value: null,
+        };
+    }
     const displayFile = relativeOrAbsolute(gameRoot, resolved);
     if (!existsSync(resolved)) {
         return { file: displayFile, found: false, parseError: null, value: null };
     }
     try {
+        const releaseManifestContent = readBoundedUtf8File(resolved, maximumGameplayE2EReportBytes);
+        if (releaseManifestContent === null) {
+            return {
+                file: displayFile,
+                found: true,
+                parseError: `Release manifest cannot exceed ${maximumGameplayE2EReportBytes} bytes.`,
+                value: null,
+            };
+        }
+        return {
+            file: displayFile,
+            found: true,
+            parseError: null,
+            value: JSON.parse(releaseManifestContent),
+        };
+    }
+    catch (error) {
         return {
             file: displayFile,
             found: true,
+            parseError: formatError(error),
+            value: null,
+        };
+    }
+}
+function readGameplayE2EEvidence(file, gameRoot, releaseManifestFile, expectedProfile, expectedTargets) {
+    if (file === undefined) {
+        return null;
+    }
+    let resolved;
+    try {
+        resolved = resolveGameplayE2EPathInsideGameRoot(gameRoot, file, 'Gameplay E2E report');
+    }
+    catch (error) {
+        return {
+            file: '<outside-game-root>',
+            found: false,
+            parseError: null,
+            validationError: formatError(error),
+            value: null,
+        };
+    }
+    const displayFile = relativeOrAbsolute(gameRoot, resolved);
+    if (!existsSync(resolved)) {
+        return {
+            file: displayFile,
+            found: false,
             parseError: null,
-            value: JSON.parse(readFileSync(resolved, 'utf8')),
+            validationError: null,
+            value: null,
         };
     }
+    let value;
+    try {
+        const reportContent = readBoundedUtf8File(resolved, maximumGameplayE2EReportBytes);
+        if (reportContent === null) {
+            return {
+                file: displayFile,
+                found: true,
+                parseError: null,
+                validationError: `Gameplay E2E report cannot exceed ${maximumGameplayE2EReportBytes} bytes.`,
+                value: null,
+            };
+        }
+        value = JSON.parse(reportContent);
+    }
     catch (error) {
         return {
             file: displayFile,
             found: true,
             parseError: formatError(error),
+            validationError: null,
             value: null,
         };
     }
+    return {
+        file: displayFile,
+        found: true,
+        parseError: null,
+        validationError: validateGameplayE2EEvidence(value, gameRoot, releaseManifestFile, expectedProfile, expectedTargets),
+        value,
+    };
+}
+function validateGameplayE2EEvidence(value, gameRoot, releaseManifestFile, expectedProfile, expectedTargets) {
+    if (!isRecord(value)) {
+        return 'Gameplay E2E report must be an object.';
+    }
+    if (value.schemaVersion !== 1) {
+        return 'Gameplay E2E report schemaVersion must be 1.';
+    }
+    if (value.status !== 'passed') {
+        return 'Gameplay E2E report status must be passed.';
+    }
+    const generatedAtMs = typeof value.generatedAt === 'string'
+        ? Date.parse(value.generatedAt)
+        : Number.NaN;
+    if (typeof value.generatedAt !== 'string'
+        || !Number.isFinite(generatedAtMs)
+        || new Date(generatedAtMs).toISOString() !== value.generatedAt) {
+        return 'Gameplay E2E report generatedAt must be an ISO timestamp.';
+    }
+    if (typeof value.target !== 'string' || value.target.length === 0) {
+        return 'Gameplay E2E report target must be a non-empty string.';
+    }
+    if (expectedTargets !== undefined && !expectedTargets.includes(value.target)) {
+        return `Gameplay E2E report target must match an acceptance target: ${expectedTargets.join(', ')}.`;
+    }
+    if (typeof value.profile !== 'string' || value.profile.length === 0) {
+        return 'Gameplay E2E report profile must be a non-empty string.';
+    }
+    if (expectedProfile !== undefined && value.profile !== expectedProfile) {
+        return `Gameplay E2E report profile must match acceptance profile ${expectedProfile}.`;
+    }
+    if (!isPathEvidence(value.artifact) || value.artifact.kind === 'symbolic-link') {
+        return 'Gameplay E2E report must link a hashed file or directory target artifact.';
+    }
+    const artifactError = validateCurrentPathEvidence(value.artifact, gameRoot, 'target artifact');
+    if (artifactError !== null) {
+        return artifactError;
+    }
+    if (!isPathEvidence(value.plan) || value.plan.kind !== 'file') {
+        return 'Gameplay E2E report must link its hashed manifest plan.';
+    }
+    const planError = validateCurrentPathEvidence(value.plan, gameRoot, 'manifest plan');
+    if (planError !== null) {
+        return planError;
+    }
+    let configuredPlan;
+    try {
+        configuredPlan = readGameplayE2EPlan(gameRoot);
+    }
+    catch (error) {
+        return `Gameplay E2E manifest plan is invalid: ${formatError(error)}`;
+    }
+    if (configuredPlan === null) {
+        return 'Gameplay E2E manifest plan must define acceptance.gameplay.';
+    }
+    if (path.resolve(gameRoot, value.plan.file) !== configuredPlan.file) {
+        return 'Gameplay E2E report must link the game manifest plan path.';
+    }
+    if (releaseManifestFile !== undefined) {
+        if (!isPathEvidence(value.releaseManifest) || value.releaseManifest.kind !== 'file') {
+            return 'Gameplay E2E report must link the current release manifest.';
+        }
+        let resolvedReleaseManifest;
+        try {
+            resolvedReleaseManifest = resolveGameplayE2EPathInsideGameRoot(gameRoot, releaseManifestFile, 'Gameplay E2E release manifest');
+        }
+        catch (error) {
+            return formatError(error);
+        }
+        if (path.resolve(gameRoot, value.releaseManifest.file) !== resolvedReleaseManifest) {
+            return 'Gameplay E2E report must link the acceptance release manifest path.';
+        }
+        const releaseManifestError = validateCurrentPathEvidence(value.releaseManifest, gameRoot, 'release manifest');
+        if (releaseManifestError !== null) {
+            return releaseManifestError;
+        }
+        let releaseManifest;
+        try {
+            const releaseManifestContent = readBoundedUtf8File(resolvedReleaseManifest, maximumGameplayE2EReportBytes);
+            if (releaseManifestContent === null) {
+                return `Gameplay E2E release manifest cannot exceed ${maximumGameplayE2EReportBytes} bytes.`;
+            }
+            releaseManifest = JSON.parse(releaseManifestContent);
+        }
+        catch (error) {
+            return `Gameplay E2E report release manifest is unreadable: ${formatError(error)}`;
+        }
+        const releaseTargetError = validateReleaseTargetEvidence(releaseManifest, value.target, value.profile, value.artifact.file, gameRoot);
+        if (releaseTargetError !== null) {
+            return releaseTargetError;
+        }
+    }
+    if (!Array.isArray(value.states) || value.states.length === 0) {
+        return 'Gameplay E2E report must contain at least one state.';
+    }
+    if (value.states.length > maximumGameplayE2EStates) {
+        return `Gameplay E2E report cannot contain more than ${maximumGameplayE2EStates} states.`;
+    }
+    const stateIds = [];
+    for (const state of value.states) {
+        if (!isRecord(state)
+            || typeof state.id !== 'string'
+            || state.id.length === 0
+            || state.status !== 'passed'
+            || !isPathEvidence(state.screenshot)
+            || state.screenshot.kind !== 'file') {
+            return 'Every gameplay E2E state must have passed with a hashed screenshot.';
+        }
+        const screenshotError = validateCurrentPathEvidence(state.screenshot, gameRoot, 'state screenshot');
+        if (screenshotError !== null) {
+            return screenshotError;
+        }
+        stateIds.push(state.id);
+    }
+    const configuredStateIds = configuredPlan.plan.states.map((state) => state.id);
+    if (stateIds.length !== configuredStateIds.length
+        || stateIds.some((stateId, index) => stateId !== configuredStateIds[index])) {
+        return 'Gameplay E2E report must cover every manifest plan state in order.';
+    }
+    return null;
+}
+function validateReleaseTargetEvidence(value, target, profile, artifactFile, gameRoot) {
+    if (!isRecord(value) || !isRecord(value.targets)) {
+        return 'Gameplay E2E release manifest must define target evidence.';
+    }
+    const targetEvidence = value.targets[target];
+    if (!isRecord(targetEvidence) || typeof targetEvidence.artifact !== 'string') {
+        return `Gameplay E2E release manifest does not contain target ${target}.`;
+    }
+    if (targetEvidence.profile !== undefined
+        && targetEvidence.profile !== profile) {
+        return `Gameplay E2E release manifest target ${target} does not match profile ${profile}.`;
+    }
+    if (path.resolve(gameRoot, targetEvidence.artifact)
+        !== path.resolve(gameRoot, artifactFile)) {
+        return `Gameplay E2E release manifest target ${target} does not match the tested artifact.`;
+    }
+    return null;
+}
+function isPathEvidence(value) {
+    return isRecord(value)
+        && typeof value.file === 'string'
+        && value.file.length > 0
+        && (value.kind === 'file' || value.kind === 'directory' || value.kind === 'symbolic-link')
+        && typeof value.sha256 === 'string'
+        && /^[a-f0-9]{64}$/u.test(value.sha256);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateCurrentPathEvidence(evidence, gameRoot, label) {
+    const resolved = path.resolve(gameRoot, evidence.file);
+    const relative = path.relative(gameRoot, resolved);
+    if (relative === '..'
+        || relative.startsWith(`..${path.sep}`)
+        || path.isAbsolute(relative)) {
+        return `Gameplay E2E ${label} path escapes the game root.`;
+    }
+    let current;
+    try {
+        current = collectGameplayE2EPathEvidence(gameRoot, evidence.file, label);
+    }
+    catch (error) {
+        return `Gameplay E2E ${label} is unavailable: ${formatError(error)}`;
+    }
+    return current.kind === evidence.kind && current.sha256 === evidence.sha256
+        ? null
+        : `Gameplay E2E ${label} hash does not match its current contents.`;
 }
 function relativeOrAbsolute(root, file) {
     const relative = path.relative(root, file);
     return relative.startsWith('..') || path.isAbsolute(relative) ? file : relative || '.';
 }
+function readBoundedUtf8File(file, maximumBytes) {
+    const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+    const fileDescriptor = openSync(file, 'r');
+    let offset = 0;
+    try {
+        while (offset < buffer.length) {
+            const bytesRead = readSync(fileDescriptor, buffer, offset, buffer.length - offset, null);
+            if (bytesRead === 0) {
+                break;
+            }
+            offset += bytesRead;
+        }
+    }
+    finally {
+        closeSync(fileDescriptor);
+    }
+    return offset > maximumBytes ? null : buffer.subarray(0, offset).toString('utf8');
+}
 function resolveRunnableStep(step) {
     if (step.command === undefined || step.command.length === 0) {
         return { ok: false, detail: `Acceptance step ${step.id} is missing command.` };

package/dist/gameplay-e2e.d.ts

@@ -0,0 +1,121 @@
+export declare const defaultGameplayE2EReportFile = "artifacts/gameplay-e2e/gameplay-e2e-report.json";
+export declare const maximumGameplayE2EStates = 50;
+export interface GameplayE2EHashLimits {
+  readonly maximumDepth: number;
+  readonly maximumEntries: number;
+  readonly maximumTotalFileBytes: number;
+}
+export interface GameplayE2EPlan {
+  readonly schemaVersion: 1;
+  readonly states: readonly GameplayE2EState[];
+}
+export interface GameplayE2EState {
+  readonly id: string;
+  readonly label: string;
+  readonly expectation?: string;
+  readonly actions: readonly GameplayE2EAction[];
+}
+export type GameplayE2EAction = GameplayE2EInputAction | GameplayE2EPauseResumeAction;
+export type GameplayE2EInputAction = {
+  readonly type: 'tap';
+  readonly x: number;
+  readonly y: number;
+} | {
+  readonly type: 'key';
+  readonly key: string;
+} | {
+  readonly type: 'wait';
+  readonly durationMs: number;
+};
+export interface GameplayE2EPauseResumeAction {
+  readonly type: 'pause-resume';
+  readonly backgroundMs: number;
+  readonly expectSameSession?: boolean;
+}
+export interface GameplayE2EObservation {
+  readonly passed: boolean;
+  readonly sessionId: string | null;
+  readonly detail?: string;
+  readonly metadata?: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface GameplayE2EDriver {
+  readonly perform: (action: GameplayE2EInputAction) => Promise<void>;
+  readonly pause: () => Promise<void>;
+  readonly resume: () => Promise<void>;
+  readonly inspect: (input: {
+    readonly state: GameplayE2EState;
+    readonly phase: 'after' | 'before' | 'resumed';
+  }) => Promise<GameplayE2EObservation>;
+  readonly captureScreenshot: (input: {
+    readonly state: GameplayE2EState;
+    readonly file: string;
+  }) => Promise<void>;
+}
+export type GameplayE2EStatus = 'failed' | 'passed';
+export type GameplayE2EResultStatus = GameplayE2EStatus | 'skipped';
+export interface GameplayE2EActionResult {
+  readonly action: GameplayE2EAction;
+  readonly status: GameplayE2EResultStatus;
+  readonly startedAt: string;
+  readonly durationMs: number;
+  readonly detail: string | null;
+}
+export interface GameplayE2EPathEvidence {
+  readonly file: string;
+  readonly kind: 'directory' | 'file' | 'symbolic-link';
+  readonly sha256: string;
+}
+export interface GameplayE2EStateResult {
+  readonly id: string;
+  readonly label: string;
+  readonly expectation: string | null;
+  readonly status: GameplayE2EResultStatus;
+  readonly startedAt: string;
+  readonly durationMs: number;
+  readonly detail: string | null;
+  readonly actions: readonly GameplayE2EActionResult[];
+  readonly observation: GameplayE2EObservation | null;
+  readonly screenshot: GameplayE2EPathEvidence | null;
+}
+export interface GameplayE2EReport {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly status: GameplayE2EStatus;
+  readonly gameRoot: string;
+  readonly target: string;
+  readonly profile: string;
+  readonly durationMs: number;
+  readonly plan: GameplayE2EPathEvidence;
+  readonly artifact: GameplayE2EPathEvidence;
+  readonly releaseManifest: GameplayE2EPathEvidence | null;
+  readonly states: readonly GameplayE2EStateResult[];
+}
+export interface RunGameplayE2EInput {
+  readonly gameRoot: string;
+  readonly reportDir: string;
+  readonly reportFile?: string;
+  readonly plan: GameplayE2EPlan;
+  readonly planFile: string;
+  readonly target: string;
+  readonly profile: string;
+  readonly artifactFile: string;
+  readonly releaseManifestFile?: string;
+  readonly driver: GameplayE2EDriver;
+  readonly now?: () => number;
+  readonly log?: (message: string) => void;
+}
+export interface RunGameplayE2EResult {
+  readonly report: GameplayE2EReport;
+  readonly jsonFile: string;
+  readonly markdownFile: string;
+}
+export declare function resolveGameplayE2EReportFile(gameRoot: string, env?: NodeJS.ProcessEnv): string;
+export declare function readGameplayE2EPlan(gameRoot: string, configFile?: string): {
+  readonly file: string;
+  readonly plan: GameplayE2EPlan;
+} | null;
+export declare function parseGameplayE2EPlan(value: unknown, source?: string): GameplayE2EPlan;
+export declare function runGameplayE2E(input: RunGameplayE2EInput): Promise<RunGameplayE2EResult>;
+export declare function renderGameplayE2EMarkdown(report: GameplayE2EReport): string;
+export declare function collectGameplayE2EPathEvidence(gameRoot: string, file: string, label: string, limits?: GameplayE2EHashLimits): GameplayE2EPathEvidence;
+export declare function resolveGameplayE2EPathInsideGameRoot(gameRoot: string, file: string, label: string, allowSymbolicLinkLeaf?: boolean): string;