@mpgd/cli 0.6.0 → 0.8.0

package/dist/game-acceptance.d.ts

@@ -0,0 +1,65 @@
+export declare const defaultGameAcceptanceCommandTimeoutMs: number;
+export declare function resolveGameAcceptanceReleaseManifestFile(gameRoot: string, env?: NodeJS.ProcessEnv): string;
+export type GameAcceptanceStatus = 'failed' | 'passed';
+export type GameAcceptanceStepStatus = 'failed' | 'passed' | 'skipped';
+export interface GameAcceptanceStep {
+  readonly id: string;
+  readonly label: string;
+  readonly command?: string;
+  readonly args?: readonly string[];
+  readonly cwd?: string;
+  readonly skipReason?: string;
+}
+export interface GameAcceptanceStepResult {
+  readonly id: string;
+  readonly label: string;
+  readonly command: string | null;
+  readonly args: readonly string[];
+  readonly cwd: string | null;
+  readonly status: GameAcceptanceStepStatus;
+  readonly exitCode: number | null;
+  readonly startedAt: string;
+  readonly durationMs: number;
+  readonly detail: string | null;
+}
+export interface GameAcceptanceReport {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly status: GameAcceptanceStatus;
+  readonly gameRoot: string;
+  readonly durationMs: number;
+  readonly options: Readonly<Record<string, string | boolean | null>>;
+  readonly steps: readonly GameAcceptanceStepResult[];
+  readonly evidence: {
+    readonly releaseManifest: {
+      readonly file: string;
+      readonly found: boolean;
+      readonly parseError: string | null;
+      readonly value: unknown;
+    } | null;
+  };
+}
+export interface GameAcceptanceCommandResult {
+  readonly exitCode: number;
+  readonly detail?: string;
+}
+export type GameAcceptanceCommandRunner = (step: Required<Pick<GameAcceptanceStep, 'command' | 'args' | 'cwd'>>) => GameAcceptanceCommandResult;
+export interface RunGameAcceptanceInput {
+  readonly gameRoot: string;
+  readonly reportDir: string;
+  readonly releaseManifestFile?: string;
+  readonly options: Readonly<Record<string, string | boolean | null>>;
+  readonly steps: readonly GameAcceptanceStep[];
+  readonly env?: NodeJS.ProcessEnv;
+  readonly commandTimeoutMs?: number;
+  readonly commandRunner?: GameAcceptanceCommandRunner;
+  readonly now?: () => number;
+  readonly log?: (message: string) => void;
+}
+export interface RunGameAcceptanceResult {
+  readonly report: GameAcceptanceReport;
+  readonly jsonFile: string;
+  readonly markdownFile: string;
+}
+export declare function runGameAcceptance(input: RunGameAcceptanceInput): RunGameAcceptanceResult;
+export declare function renderGameAcceptanceMarkdown(report: GameAcceptanceReport): string;

package/dist/game-acceptance.js

@@ -0,0 +1,245 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const defaultGameAcceptanceCommandTimeoutMs = 30 * 60 * 1000;
+const defaultGameAcceptanceReleaseManifestFile = 'artifacts/release-manifest.json';
+export function resolveGameAcceptanceReleaseManifestFile(gameRoot, env = process.env) {
+    const configuredFile = env.MPGD_RELEASE_MANIFEST_FILE;
+    return path.resolve(gameRoot, configuredFile === undefined || configuredFile.length === 0
+        ? defaultGameAcceptanceReleaseManifestFile
+        : configuredFile);
+}
+export function runGameAcceptance(input) {
+    const now = input.now ?? Date.now;
+    const log = input.log ?? console.log;
+    const commandTimeoutMs = input.commandTimeoutMs ?? defaultGameAcceptanceCommandTimeoutMs;
+    if (!Number.isInteger(commandTimeoutMs) || commandTimeoutMs <= 0) {
+        throw new Error(`Acceptance command timeout must be a positive integer: ${commandTimeoutMs}`);
+    }
+    const commandRunner = input.commandRunner
+        ?? ((step) => runAcceptanceCommand(step, input.env ?? process.env, commandTimeoutMs));
+    const gameRoot = path.resolve(input.gameRoot);
+    const startedAtMs = now();
+    const results = [];
+    let failed = false;
+    for (const step of input.steps) {
+        if (failed) {
+            results.push(skippedStepResult(step, now(), 'A previous acceptance step failed.'));
+            continue;
+        }
+        if (step.skipReason !== undefined) {
+            log(`[mpgd:accept] skipped ${step.label}: ${step.skipReason}`);
+            results.push(skippedStepResult(step, now(), step.skipReason));
+            continue;
+        }
+        const runnableStep = resolveRunnableStep(step);
+        if (!runnableStep.ok) {
+            results.push(failedStepResult(step, now(), runnableStep.detail));
+            failed = true;
+            continue;
+        }
+        const command = runnableStep.command;
+        const args = step.args ?? [];
+        const cwd = path.resolve(runnableStep.cwd);
+        const stepStartedAtMs = now();
+        const startedAt = new Date(stepStartedAtMs).toISOString();
+        log(`[mpgd:accept] ${step.label}`);
+        let commandResult;
+        try {
+            commandResult = commandRunner({ command, args, cwd });
+        }
+        catch (error) {
+            commandResult = {
+                exitCode: 1,
+                detail: formatError(error),
+            };
+        }
+        const status = commandResult.exitCode === 0 ? 'passed' : 'failed';
+        results.push({
+            id: step.id,
+            label: step.label,
+            command,
+            args,
+            cwd,
+            status,
+            exitCode: commandResult.exitCode,
+            startedAt,
+            durationMs: Math.max(0, now() - stepStartedAtMs),
+            detail: commandResult.detail ?? null,
+        });
+        failed = status === 'failed';
+    }
+    const finishedAtMs = now();
+    const releaseManifest = readOptionalJsonEvidence(input.releaseManifestFile, gameRoot);
+    const report = {
+        schemaVersion: 1,
+        generatedAt: new Date(finishedAtMs).toISOString(),
+        status: failed ? 'failed' : 'passed',
+        gameRoot,
+        durationMs: Math.max(0, finishedAtMs - startedAtMs),
+        options: input.options,
+        steps: results,
+        evidence: {
+            releaseManifest,
+        },
+    };
+    const reportDir = path.resolve(input.reportDir);
+    const jsonFile = path.join(reportDir, 'acceptance-report.json');
+    const markdownFile = path.join(reportDir, 'acceptance-report.md');
+    mkdirSync(reportDir, { recursive: true });
+    writeFileSync(jsonFile, `${JSON.stringify(report, null, 2)}\n`);
+    writeFileSync(markdownFile, renderGameAcceptanceMarkdown(report));
+    return { report, jsonFile, markdownFile };
+}
+export function renderGameAcceptanceMarkdown(report) {
+    const lines = [
+        '# Game Acceptance Report',
+        '',
+        `Status: ${report.status}`,
+        `Generated: ${report.generatedAt}`,
+        `Game root: ${escapeMarkdownInline(report.gameRoot)}`,
+        `Duration: ${formatDuration(report.durationMs)}`,
+        '',
+        '## Steps',
+        '',
+        '| Step | Status | Duration | Detail |',
+        '| --- | --- | ---: | --- |',
+        ...report.steps.map((step) => [
+            escapeMarkdownTable(step.label),
+            step.status,
+            formatDuration(step.durationMs),
+            escapeMarkdownTable(step.detail ?? ''),
+        ].join(' | ')).map((row) => `| ${row} |`),
+        '',
+        '## Release Evidence',
+        '',
+    ];
+    if (report.evidence.releaseManifest === null) {
+        lines.push('- Release manifest collection disabled.');
+    }
+    else if (!report.evidence.releaseManifest.found) {
+        lines.push(`- Release manifest not found: ${escapeMarkdownInline(report.evidence.releaseManifest.file)}`);
+    }
+    else if (report.evidence.releaseManifest.parseError !== null) {
+        lines.push(`- Release manifest is invalid: ${escapeMarkdownInline(report.evidence.releaseManifest.file)}`, `  - ${escapeMarkdownInline(report.evidence.releaseManifest.parseError)}`);
+    }
+    else {
+        lines.push(`- Release manifest: ${escapeMarkdownInline(report.evidence.releaseManifest.file)}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function runAcceptanceCommand(step, env, timeoutMs) {
+    const result = spawnSync(step.command, [...step.args], {
+        cwd: step.cwd,
+        env,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+        timeout: timeoutMs,
+        killSignal: 'SIGTERM',
+    });
+    if (result.error !== undefined) {
+        return {
+            exitCode: 1,
+            detail: isTimeoutError(result.error)
+                ? `Command timed out after ${timeoutMs}ms.`
+                : result.error.message,
+        };
+    }
+    return {
+        exitCode: result.status ?? 1,
+        ...(result.signal === null ? {} : { detail: `Terminated by ${result.signal}.` }),
+    };
+}
+function failedStepResult(step, nowMs, detail) {
+    return {
+        id: step.id,
+        label: step.label,
+        command: normalizeStepCommand(step.command),
+        args: step.args ?? [],
+        cwd: normalizeStepCwd(step.cwd),
+        status: 'failed',
+        exitCode: 1,
+        startedAt: new Date(nowMs).toISOString(),
+        durationMs: 0,
+        detail,
+    };
+}
+function skippedStepResult(step, nowMs, detail) {
+    return {
+        id: step.id,
+        label: step.label,
+        command: normalizeStepCommand(step.command),
+        args: step.args ?? [],
+        cwd: normalizeStepCwd(step.cwd),
+        status: 'skipped',
+        exitCode: null,
+        startedAt: new Date(nowMs).toISOString(),
+        durationMs: 0,
+        detail,
+    };
+}
+function normalizeStepCommand(command) {
+    return command === undefined || command.length === 0 ? null : command;
+}
+function normalizeStepCwd(cwd) {
+    return cwd === undefined || cwd.length === 0 ? null : path.resolve(cwd);
+}
+function readOptionalJsonEvidence(file, gameRoot) {
+    if (file === undefined) {
+        return null;
+    }
+    const resolved = path.resolve(gameRoot, file);
+    const displayFile = relativeOrAbsolute(gameRoot, resolved);
+    if (!existsSync(resolved)) {
+        return { file: displayFile, found: false, parseError: null, value: null };
+    }
+    try {
+        return {
+            file: displayFile,
+            found: true,
+            parseError: null,
+            value: JSON.parse(readFileSync(resolved, 'utf8')),
+        };
+    }
+    catch (error) {
+        return {
+            file: displayFile,
+            found: true,
+            parseError: formatError(error),
+            value: null,
+        };
+    }
+}
+function relativeOrAbsolute(root, file) {
+    const relative = path.relative(root, file);
+    return relative.startsWith('..') || path.isAbsolute(relative) ? file : relative || '.';
+}
+function resolveRunnableStep(step) {
+    if (step.command === undefined || step.command.length === 0) {
+        return { ok: false, detail: `Acceptance step ${step.id} is missing command.` };
+    }
+    if (step.cwd === undefined || step.cwd.length === 0) {
+        return { ok: false, detail: `Acceptance step ${step.id} is missing cwd.` };
+    }
+    return { ok: true, command: step.command, cwd: step.cwd };
+}
+function escapeMarkdownTable(value) {
+    return escapeMarkdownInline(value).replaceAll('|', '\\|');
+}
+function escapeMarkdownInline(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replace(/([\\`*_[\]])/gu, '\\$1')
+        .replaceAll('\n', ' ');
+}
+function formatDuration(durationMs) {
+    return durationMs < 1000 ? `${durationMs}ms` : `${(durationMs / 1000).toFixed(1)}s`;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isTimeoutError(error) {
+    return 'code' in error && error.code === 'ETIMEDOUT';
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, type GameAcceptanceCommandResult, type GameAcceptanceCommandRunner, type GameAcceptanceReport, type GameAcceptanceStatus, type GameAcceptanceStep, type GameAcceptanceStepResult, type GameAcceptanceStepStatus, type RunGameAcceptanceInput, type RunGameAcceptanceResult, } from './game-acceptance.js';
+export { assertProductionTargetReadiness, type ProductionTargetReadinessInput, } from './production-target-readiness.js';
 export declare function runMpgdCli(args: readonly string[]): Promise<void>;
 export declare function runCreateGameCli(args: readonly string[]): Promise<void>;
 export declare function readCliArgs(): readonly string[];