@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace-runtime/previews/runtime-preview.js

@@ -0,0 +1,251 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, readFile, realpath, rm } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import JSON5 from 'json5';
+import { z } from 'zod';
+import { embedWorkspaceRuntimeProfile, workspaceRelativePathSchema, workspaceRuntimePreviewProfileSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { readWorkspaceParameters } from '../workspaces/parameters.js';
+import { revisionScope } from '../workspaces/registry.js';
+import { PREVIEW_RUNTIME_DIRECTORY, previewRuntimeSdkArtifactSchema, readPreviewRuntimeDistribution, } from '../../preview-runtime/distribution.js';
+const manifestPath = '.playcraft/workspace.json';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const relativePath = z
+    .string()
+    .refine((path) => workspaceRelativePathSchema.safeParse(path).success);
+const configSchema = z
+    .object({
+    version: z.literal(1),
+    buildScript: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/),
+    outputPath: relativePath.refine((path) => path.startsWith('.playcraft-editor-preview/') && path.endsWith('.html')),
+    reportPath: relativePath.refine((path) => path.startsWith('.playcraft-editor-preview/') && path.endsWith('.json')),
+    configContractVersion: z.string().min(1).max(128),
+    entryPath: relativePath.optional(),
+    viteConfigPath: relativePath.optional(),
+    mountId: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/).optional(),
+    gameFilePaths: z.array(relativePath).max(256).default([]),
+})
+    .strict();
+const reportSchema = z
+    .object({
+    target: z.literal('editor-static'),
+    buildId: z.string(),
+    htmlDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    schemaDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    sourceFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    dataHash: z.string().regex(/^[a-f0-9]{64}$/),
+    dataRevision: z.number().int().nonnegative(),
+    schemaRevision: z.number().int().nonnegative(),
+    moduleIds: z.array(z.string()).min(1).max(10000),
+    sdkArtifact: previewRuntimeSdkArtifactSchema.optional(),
+    moduleInputs: z.array(z.object({
+        path: relativePath, sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    }).strict()).min(1).max(10000).optional(),
+})
+    .strict();
+export class RuntimePreviewBuildError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+async function insideFile(root, path) {
+    const base = await realpath(root);
+    const file = await isolatedPath(root, path);
+    const real = await realpath(file);
+    const rel = relative(base, real);
+    const stat = await lstat(file);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        rel === '..' ||
+        rel.startsWith(`..${sep}`) ||
+        stat.size > 50 * 1024 * 1024)
+        throw new RuntimePreviewBuildError('runtime_preview_path_invalid');
+    return readFile(file);
+}
+async function isolatedPath(root, path) {
+    const normalized = workspaceRelativePathSchema.parse(path);
+    const base = await realpath(root);
+    let parent = base;
+    for (const segment of normalized.split('/').slice(0, -1)) {
+        parent = resolve(parent, segment);
+        const stat = await lstat(parent).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            throw new RuntimePreviewBuildError('runtime_preview_path_invalid');
+    }
+    return resolve(base, normalized);
+}
+export async function prepareRuntimePreview(state, operation, root) {
+    let manifest;
+    try {
+        manifest = await insideFile(root, manifestPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let declared;
+    try {
+        declared = JSON5.parse(manifest.toString()).previewRuntime;
+    }
+    catch {
+        throw new RuntimePreviewBuildError('runtime_preview_manifest_invalid');
+    }
+    if (declared === undefined)
+        return undefined;
+    const parsed = configSchema.safeParse(declared);
+    if (!parsed.success)
+        throw new RuntimePreviewBuildError('runtime_preview_manifest_invalid');
+    const config = parsed.data;
+    const packageData = JSON.parse((await insideFile(root, 'package.json')).toString());
+    if (typeof packageData.scripts?.[config.buildScript] !== 'string')
+        throw new RuntimePreviewBuildError('runtime_preview_script_missing');
+    const scope = revisionScope(state, operation.workspaceId, operation.directoryName);
+    const read = () => readWorkspaceParameters(root, state.journal.fileRevisions(scope));
+    const before = await read();
+    if (before.status !== 'ready' ||
+        !before.schemaHash ||
+        !before.dataHash ||
+        !before.sourceFingerprint)
+        throw new RuntimePreviewBuildError('runtime_preview_parameters_missing');
+    const gameHashes = await Promise.all([...new Set(['package.json', ...config.gameFilePaths, ...(config.entryPath ? [config.entryPath] : []), ...(config.viteConfigPath ? [config.viteConfigPath] : [])])].map(async (path) => [path, digest(await insideFile(root, path))]));
+    // A copied development module must match the immutable artifact distributed with this command-line tool.
+    const copiedManifest = await insideFile(root, PREVIEW_RUNTIME_DIRECTORY + '/manifest.json').catch(error => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    let sdkArtifact;
+    let sdkModulePath;
+    let trustedHelperPath;
+    if (copiedManifest) {
+        if (!config.entryPath)
+            throw new RuntimePreviewBuildError('runtime_preview_entry_missing');
+        const trusted = await readPreviewRuntimeDistribution();
+        trustedHelperPath = resolve(trusted.source, 'build-preview.mjs');
+        if (digest(await readFile(trustedHelperPath)) !== trusted.manifest.files['build-preview.mjs'])
+            throw new RuntimePreviewBuildError('runtime_preview_sdk_modified');
+        if (!copiedManifest.equals(trusted.manifestBytes))
+            throw new RuntimePreviewBuildError('runtime_preview_sdk_modified');
+        for (const name of ['manifest.json', 'runtime.mjs', 'build-preview.mjs', 'release-guard.mjs']) {
+            const path = PREVIEW_RUNTIME_DIRECTORY + '/' + name;
+            const actual = await insideFile(root, path);
+            const expected = name === 'manifest.json' ? digest(trusted.manifestBytes) : trusted.manifest.files[name];
+            if (!expected || digest(actual) !== expected)
+                throw new RuntimePreviewBuildError('runtime_preview_sdk_modified');
+            gameHashes.push([path, expected]);
+        }
+        sdkModulePath = (await realpath(resolve(root, PREVIEW_RUNTIME_DIRECTORY, 'runtime.mjs'))).replaceAll('\\', '/');
+        sdkArtifact = {
+            path: '.playcraft/preview-runtime/runtime.mjs', sdkVersion: trusted.manifest.sdkVersion,
+            protocolVersion: 1, sha256: trusted.manifest.files['runtime.mjs'],
+        };
+    }
+    const buildId = randomUUID();
+    const profileBase = {
+        version: 1,
+        target: 'editor-static',
+        protocolVersion: 1,
+        binding: {
+            scope: {
+                projectId: operation.workspaceId,
+                branchName: operation.directoryName ?? 'basic',
+                themeId: before.themeId ?? 'default',
+            },
+            schemaVersion: before.schemaHash,
+            configContractVersion: config.configContractVersion,
+            locale: 'en',
+        },
+        sourceFingerprint: before.sourceFingerprint,
+        baseline: {
+            dataRevision: before.dataRevision ?? 0,
+            schemaRevision: before.schemaRevision ?? 0,
+            dataHash: before.dataHash,
+        },
+    };
+    const context = { buildId, ...profileBase };
+    // Remove stale outputs before the script runs; a stale report cannot satisfy this build's identity.
+    for (const path of [config.outputPath, config.reportPath]) {
+        await rm(await isolatedPath(root, path), { force: true });
+    }
+    return {
+        command: `PLAYCRAFT_RUNTIME_PREVIEW_CONTEXT=${shellQuote(JSON.stringify(context))} ${trustedHelperPath
+            ? [process.execPath, trustedHelperPath, '--entry', config.entryPath,
+                ...(config.viteConfigPath ? ['--config', config.viteConfigPath] : []),
+                ...(config.mountId ? ['--mount-id', config.mountId] : [])].map(shellQuote).join(' ')
+            : `pnpm run ${shellQuote(config.buildScript)}`}`,
+        async finish() {
+            const after = await read();
+            if (after.status !== 'ready' ||
+                after.sourceFingerprint !== before.sourceFingerprint ||
+                after.dataHash !== before.dataHash ||
+                after.schemaHash !== before.schemaHash ||
+                after.dataRevision !== before.dataRevision ||
+                after.schemaRevision !== before.schemaRevision ||
+                digest(await insideFile(root, manifestPath)) !== digest(manifest))
+                throw new RuntimePreviewBuildError('runtime_preview_source_changed');
+            for (const [path, hash] of gameHashes) {
+                if (digest(await insideFile(root, path)) !== hash)
+                    throw new RuntimePreviewBuildError('runtime_preview_source_changed');
+            }
+            const bytes = await insideFile(root, config.outputPath);
+            const report = reportSchema.safeParse(JSON.parse((await insideFile(root, config.reportPath)).toString()));
+            if (!report.success ||
+                report.data.buildId !== buildId ||
+                report.data.htmlDigest !== digest(bytes) ||
+                report.data.schemaDigest !== before.schemaHash ||
+                report.data.sourceFingerprint !== before.sourceFingerprint ||
+                report.data.dataHash !== before.dataHash ||
+                report.data.dataRevision !== before.dataRevision ||
+                report.data.schemaRevision !== before.schemaRevision ||
+                (sdkArtifact
+                    ? !report.data.sdkArtifact || JSON.stringify(report.data.sdkArtifact) !== JSON.stringify(sdkArtifact) ||
+                        !report.data.moduleIds.some(id => id.split('?')[0].replaceAll('\\', '/') ===
+                            sdkModulePath)
+                    : Boolean(report.data.sdkArtifact) || !report.data.moduleIds.some((id) => /(?:@playcraft\/preview-runtime|\/preview-runtime\/src\/(?:preview|runtime)\.ts)/.test(id))))
+                throw new RuntimePreviewBuildError('runtime_preview_report_invalid');
+            if (sdkArtifact) {
+                const inputs = report.data.moduleInputs;
+                if (!inputs || new Set(inputs.map(input => input.path)).size !== inputs.length)
+                    throw new RuntimePreviewBuildError('runtime_preview_report_invalid');
+                const hashes = new Map(inputs.map(input => [input.path, input.sha256]));
+                for (const input of inputs) {
+                    if (digest(await insideFile(root, input.path)) !== input.sha256)
+                        throw new RuntimePreviewBuildError('runtime_preview_source_changed');
+                }
+                const physicalRoot = (await realpath(root)).replaceAll('\\', '/') + '/';
+                for (const id of report.data.moduleIds) {
+                    const file = id.split('?')[0].replaceAll('\\', '/');
+                    if (!file.startsWith(physicalRoot) || file.includes('/node_modules/'))
+                        continue;
+                    const path = file.slice(physicalRoot.length);
+                    const stat = await lstat(file).catch(error => {
+                        if (error.code === 'ENOENT')
+                            return undefined;
+                        throw error;
+                    });
+                    if (stat?.isSymbolicLink())
+                        throw new RuntimePreviewBuildError('runtime_preview_path_invalid');
+                    if (stat?.isFile() && !hashes.has(path))
+                        throw new RuntimePreviewBuildError('runtime_preview_report_invalid');
+                }
+            }
+            const profile = workspaceRuntimePreviewProfileSchema.parse({
+                ...profileBase,
+                buildDigest: report.data.htmlDigest,
+            });
+            return {
+                bytes: Buffer.from(embedWorkspaceRuntimeProfile(bytes.toString(), profile)),
+                profile,
+            };
+        },
+    };
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/workspace-runtime/previews/single-file.js

@@ -0,0 +1,43 @@
+const LOCAL_ATTR = /<(?:script|img|link|source|video|audio|iframe)\b[^>]*?\b(?:src|href)\s*=\s*["']([^"']+)["']/gi;
+/** A CSS `url(`, not the tail of a name such as `createObjectURL(` or `getAudioURL(`. */
+const CSS_URL = /(?<![\w$.-])url\(\s*["']?([^"')]+)["']?\s*\)/gi;
+/** An inline script's body, kept apart from its tag so `<script src>` is still checked. */
+const SCRIPT_BODY = /(<script\b[^>]*>)[\s\S]*?(<\/script\s*>)/gi;
+/**
+ * A reference the sealed document would load from the local build, not from the network or inline
+ * data. Inline script code is not read: inlined libraries call functions named `…URL(` and build
+ * `"url(" + src + ")"` strings at run time, and neither is a file the document loads.
+ */
+export function findExternalLocalReferences(html) {
+    const markup = html.replace(SCRIPT_BODY, '$1$2');
+    const found = new Set();
+    for (const expression of [LOCAL_ATTR, CSS_URL]) {
+        expression.lastIndex = 0;
+        for (const match of markup.matchAll(expression)) {
+            const value = (match[1] ?? '').trim();
+            if (isLocalReference(value))
+                found.add(value);
+        }
+    }
+    return [...found];
+}
+export function classifyPreviewOutput(entries) {
+    if (entries.length !== 1)
+        return { ok: false };
+    const only = entries[0];
+    if (!only || only.kind !== 'file' || !only.name.toLowerCase().endsWith('.html'))
+        return { ok: false };
+    if (only.name.includes('/') || only.name.includes('\\') || only.name === '.' || only.name === '..') {
+        return { ok: false };
+    }
+    return { ok: true, entry: only.name };
+}
+function isLocalReference(value) {
+    if (!value || value.startsWith('#') || value.startsWith('data:') || value.startsWith('blob:'))
+        return false;
+    if (/^(https?:|mailto:|javascript:)/i.test(value))
+        return false;
+    if (value.startsWith('//'))
+        return false;
+    return true;
+}

package/dist/workspace-runtime/processes/managed-writes.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+export const MANAGED_WRITE_SOURCES = ['manual', 'agent', 'background'];
+const BACKGROUND_WRITER = `
+const fs = require('node:fs');
+const file = process.argv[1];
+if (!file) process.exit(1);
+fs.appendFileSync(file, 'background\\n');
+const timer = setInterval(() => {
+  try { fs.appendFileSync(file, 'x'); }
+  catch { clearInterval(timer); process.exit(0); }
+}, 200);
+`;
+/** `true` alive, `false` confirmed exited, `undefined` when the probe cannot tell. */
+export function probeProcess(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        return undefined;
+    }
+}
+export function spawnBackgroundWriter(absolutePath) {
+    const child = spawn(process.execPath, ['-e', BACKGROUND_WRITER, absolutePath], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    if (!child.pid)
+        throw new Error('background_write_failed');
+    return child.pid;
+}
+export async function stopBackgroundWriter(pid) {
+    signal(pid, 'SIGTERM');
+    if (await waitUntilStopped(pid, 2_000))
+        return true;
+    signal(pid, 'SIGKILL');
+    return waitUntilStopped(pid, 2_000);
+}
+function signal(pid, name) {
+    try {
+        process.kill(-pid, name);
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            return;
+        try {
+            process.kill(pid, name);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+async function waitUntilStopped(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const alive = probeProcess(pid);
+        if (alive === false)
+            return true;
+        if (alive === undefined)
+            return false;
+        await delay(50);
+    }
+    return probeProcess(pid) === false;
+}