@playcraft/cli 0.1.52 → 0.1.53-beta

package/dist/workspace-runtime/workspaces/parameter-assets.js

@@ -0,0 +1,189 @@
+import { constants } from 'node:fs';
+import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join, posix } from 'node:path';
+import sharp from 'sharp';
+import { AssetGenerationVideoValidator, parameterAssetFilePath, parameterAssetMimeType, parameterAssetValueError, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from './artifact-files.js';
+import { registerThemeAsset } from './theme-asset-index.js';
+export class ParameterAssetError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function imageType(bytes) {
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+        return 'image/jpeg';
+    if (/^GIF8[79]a$/.test(bytes.subarray(0, 6).toString('ascii')))
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP')
+        return 'image/webp';
+    return undefined;
+}
+/** Inspect the actual no-link file, rather than trusting browser MIME (Multipurpose Internet Mail Extensions, 媒体类型) metadata. */
+export async function validateParameterAssetFile(root, dataPath, value, asset) {
+    const valueError = parameterAssetValueError(asset, value);
+    if (valueError)
+        throw new ParameterAssetError(valueError);
+    const relative = parameterAssetFilePath(dataPath, value);
+    if (!relative)
+        throw new ParameterAssetError('parameter_asset_theme_unsupported');
+    let target;
+    try {
+        target = await artifactPath(root, relative);
+    }
+    catch {
+        throw new ParameterAssetError('parameter_asset_file_unavailable');
+    }
+    let file;
+    try {
+        file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        throw new ParameterAssetError('parameter_asset_file_unavailable');
+    }
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size <= 0 || before.size > asset.maxBytes)
+            throw new ParameterAssetError('parameter_asset_file_invalid');
+        const mime = parameterAssetMimeType(value);
+        if (asset.kind === 'image') {
+            const bytes = await file.readFile();
+            if (imageType(bytes) !== mime)
+                throw new ParameterAssetError('parameter_asset_type_mismatch');
+            try {
+                const metadata = await sharp(bytes, { limitInputPixels: 32 * 1024 * 1024 }).metadata();
+                if (!metadata.width || !metadata.height)
+                    throw new Error('invalid_dimensions');
+            }
+            catch {
+                throw new ParameterAssetError('parameter_asset_file_invalid');
+            }
+        }
+        else {
+            const validator = new AssetGenerationVideoValidator(), chunk = Buffer.allocUnsafe(64 * 1024);
+            let offset = 0;
+            try {
+                for (;;) {
+                    const { bytesRead } = await file.read(chunk, 0, chunk.length, offset);
+                    if (!bytesRead)
+                        break;
+                    offset += bytesRead;
+                    validator.update(chunk.subarray(0, bytesRead));
+                }
+                validator.finish();
+            }
+            catch {
+                throw new ParameterAssetError('parameter_asset_file_invalid');
+            }
+        }
+        const after = await file.stat(), pathStat = await lstat(await artifactPath(root, relative));
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+            || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+            || after.dev !== pathStat.dev || after.ino !== pathStat.ino)
+            throw new ParameterAssetError('parameter_asset_file_changed');
+    }
+    catch (error) {
+        if (error instanceof ParameterAssetError)
+            throw error;
+        throw new ParameterAssetError('parameter_asset_file_changed');
+    }
+    finally {
+        await file.close();
+    }
+    return relative;
+}
+/** Prepare all registry edits before changing any project file. Unknown registries stay untouched. */
+export async function prepareParameterAssetRegistration(root, dataPath, bindings) {
+    if (!bindings.length)
+        return undefined;
+    if (!/^src\/theme\/[A-Za-z0-9_-]+\/theme\.data\.json5$/.test(dataPath))
+        throw new ParameterAssetError('parameter_asset_theme_unsupported');
+    const index = posix.dirname(dataPath) + '/index.ts';
+    let source;
+    try {
+        const target = await artifactPath(root, index), stat = await lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('unsupported');
+        source = await readFile(target, 'utf8');
+    }
+    catch {
+        throw new ParameterAssetError('parameter_asset_index_unsupported');
+    }
+    let next = source;
+    for (const { value, asset } of bindings) {
+        const file = await validateParameterAssetFile(root, dataPath, value, asset);
+        let importPath = posix.relative(posix.dirname(index), file);
+        if (!importPath.startsWith('.'))
+            importPath = './' + importPath;
+        next = registerThemeAsset(next, value, importPath);
+    }
+    return next === source ? undefined : { path: index, previousHash: digest(source), content: next };
+}
+/** Stage complete bytes and original metadata before atomically replacing the unchanged registry. */
+export async function writeParameterAssetRegistration(root, plan) {
+    let target;
+    let file;
+    try {
+        target = await artifactPath(root, plan.path);
+        file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        throw new ParameterAssetError('parameter_asset_index_conflict');
+    }
+    const temporary = join(dirname(target), '.playcraft-parameter-' + randomUUID() + '.tmp');
+    let staged;
+    let published = false;
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > 1024 * 1024 || digest(await file.readFile()) !== plan.previousHash)
+            throw new ParameterAssetError('parameter_asset_index_conflict');
+        const parent = await lstat(dirname(target));
+        const bytes = Buffer.from(plan.content);
+        staged = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        // Metadata restoration must succeed before publication; never downgrade to a partial text write.
+        await staged.chown(before.uid, before.gid);
+        await staged.chmod(before.mode & 0o777);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesWritten } = await staged.write(bytes, offset, bytes.length - offset, offset);
+            if (!bytesWritten)
+                throw new ParameterAssetError('parameter_asset_index_conflict');
+            offset += bytesWritten;
+        }
+        await staged.sync();
+        const stagedStat = await staged.stat();
+        await staged.close();
+        staged = undefined;
+        const current = await lstat(await artifactPath(root, plan.path)), currentParent = await lstat(dirname(target));
+        if (before.dev !== current.dev || before.ino !== current.ino || before.mtimeMs !== current.mtimeMs || before.ctimeMs !== current.ctimeMs
+            || parent.dev !== currentParent.dev || parent.ino !== currentParent.ino
+            || digest(await readFile(await artifactPath(root, plan.path))) !== plan.previousHash
+            || digest(await readFile(temporary)) !== digest(bytes))
+            throw new ParameterAssetError('parameter_asset_index_conflict');
+        const temporaryPath = plan.path.slice(0, plan.path.lastIndexOf('/') + 1) + temporary.slice(temporary.lastIndexOf('/') + 1);
+        const checkedStage = await lstat(await artifactPath(root, temporaryPath));
+        if (checkedStage.dev !== stagedStat.dev || checkedStage.ino !== stagedStat.ino || checkedStage.nlink !== 1)
+            throw new ParameterAssetError('parameter_asset_index_conflict');
+        await rename(temporary, target);
+        published = true;
+        return { path: plan.path, contentHash: digest(bytes), size: bytes.length };
+    }
+    catch (error) {
+        if (error instanceof ParameterAssetError)
+            throw error;
+        throw new ParameterAssetError('parameter_asset_index_write_failed');
+    }
+    finally {
+        await staged?.close();
+        await file.close();
+        if (!published)
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+    }
+}

package/dist/workspace-runtime/workspaces/parameters.js

@@ -0,0 +1,329 @@
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { posix, relative, resolve, sep } from 'node:path';
+import JSON5 from 'json5';
+import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, validateParameterChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
+import { InvalidWorkspacePathError, writeWorkspaceFile, } from './files.js';
+import { editJson5Paths, ParameterEditError } from './json5-edit.js';
+import { prepareParameterAssetRegistration, writeParameterAssetRegistration } from './parameter-assets.js';
+const MANIFEST_PATH = '.playcraft/workspace.json';
+const DEFAULT_SCHEMA_PATH = 'src/theme/theme.schema.json5';
+const THEME_INDEX_PATH = 'src/theme/index.ts';
+const THEME_ROOT = 'src/theme';
+export async function readWorkspaceParameters(root, revisions) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const located = await locateParameterFiles(root);
+        const before = await sourceFingerprint(root, located);
+        const document = await readParameterDocuments(root, revisions, located);
+        const after = await sourceFingerprint(root, await locateParameterFiles(root));
+        if (before === after)
+            return parameterDocumentSchema.parse({ ...document, sourceFingerprint: after });
+    }
+    throw new ParameterEditError('parameter_source_changed');
+}
+async function sourceFingerprint(root, located, ownIndexWrite) {
+    const selectedIndex = located.dataPath ? posix.join(posix.dirname(located.dataPath), 'index.ts') : undefined;
+    const sources = await Promise.all([
+        located.schemaPath ? readOptionalText(root, located.schemaPath) : undefined,
+        located.schemaPath ? readOptionalText(root, platformI18nPath(located.schemaPath)) : undefined,
+        readOptionalText(root, MANIFEST_PATH),
+        readOptionalText(root, THEME_INDEX_PATH),
+        selectedIndex ? readOptionalText(root, selectedIndex) : undefined,
+    ]);
+    const hashes = sources.map(text => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
+    if (ownIndexWrite) {
+        // Only our exact staged registry bytes may differ from the baseline. An external edit,
+        // including a schema/manifest change during the write callback, still fails the old guard.
+        if (selectedIndex !== ownIndexWrite.path || hashes[4] !== ownIndexWrite.contentHash)
+            throw new ParameterEditError('parameter_source_conflict');
+        hashes[4] = ownIndexWrite.previousHash;
+    }
+    return createHash('sha256').update(JSON.stringify({
+        schemaPath: located.schemaPath ?? null,
+        dataPath: located.dataPath ?? null,
+        themeId: located.themeId ?? null,
+        sources: hashes,
+    })).digest('hex');
+}
+async function readParameterDocuments(root, revisions, located) {
+    if (located.errors.some((item) => item.reason === 'parameter_manifest_invalid')) {
+        return parameterDocumentSchema.parse({ status: 'invalid', errors: located.errors });
+    }
+    if (!located.schemaPath) {
+        return parameterDocumentSchema.parse({
+            status: 'missing',
+            ...(located.errors.length > 0 ? { errors: located.errors } : {}),
+        });
+    }
+    const schemaFile = await readOptionalJson5(root, located.schemaPath);
+    if (schemaFile.status === 'missing') {
+        return parameterDocumentSchema.parse({
+            status: 'missing',
+            schemaPath: located.schemaPath,
+            themeId: located.themeId,
+        });
+    }
+    if (schemaFile.status === 'invalid') {
+        return parameterDocumentSchema.parse({
+            status: 'invalid',
+            schemaPath: located.schemaPath,
+            themeId: located.themeId,
+            errors: [{ path: located.schemaPath, reason: schemaFile.reason }],
+        });
+    }
+    const i18nPath = platformI18nPath(located.schemaPath);
+    const platformFile = await readOptionalJson5(root, i18nPath);
+    const schemaDocument = {
+        schemaPath: located.schemaPath,
+        themeId: located.themeId,
+        schema: schemaFile.value,
+        schemaHash: schemaFile.contentHash,
+        schemaRevision: revisions[located.schemaPath]?.revision ?? 0,
+        ...(platformFile.status === 'ok' ? { platformI18n: platformFile.value, platformI18nPath: i18nPath } : {}),
+    };
+    if (platformFile.status === 'invalid') {
+        return parameterDocumentSchema.parse({
+            ...schemaDocument,
+            status: 'invalid',
+            errors: [{ path: i18nPath, reason: platformFile.reason }],
+        });
+    }
+    if (!located.dataPath) {
+        return parameterDocumentSchema.parse({
+            ...schemaDocument,
+            status: 'schema_only',
+            ...(located.errors.length > 0 ? { errors: located.errors } : {}),
+        });
+    }
+    const dataFile = await readOptionalJson5(root, located.dataPath);
+    if (dataFile.status === 'missing') {
+        return parameterDocumentSchema.parse({
+            ...schemaDocument,
+            status: 'schema_only',
+            dataPath: located.dataPath,
+        });
+    }
+    if (dataFile.status === 'invalid') {
+        return parameterDocumentSchema.parse({
+            ...schemaDocument,
+            status: 'invalid',
+            dataPath: located.dataPath,
+            errors: [{ path: located.dataPath, reason: dataFile.reason }],
+        });
+    }
+    return parameterDocumentSchema.parse({
+        ...schemaDocument,
+        status: 'ready',
+        dataPath: located.dataPath,
+        data: dataFile.value,
+        dataHash: dataFile.contentHash,
+        dataRevision: revisions[located.dataPath]?.revision ?? 0,
+    });
+}
+export async function patchWorkspaceParameters(root, revisions, payload, observed, options = {}) {
+    const parsed = parameterPatchPayloadSchema.parse(payload);
+    const document = await readWorkspaceParameters(root, revisions);
+    if (document.status === 'invalid')
+        throw new ParameterEditError('parameter_document_invalid');
+    if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
+        throw new ParameterEditError('parameter_data_missing');
+    }
+    if ((parsed.sourceFingerprint && parsed.sourceFingerprint !== document.sourceFingerprint)
+        || (observed && observed.dataPath !== document.dataPath)) {
+        throw new ParameterEditError('parameter_source_conflict');
+    }
+    const changes = 'changes' in parsed ? parsed.changes : [{ fieldPath: parsed.fieldPath, value: parsed.value }];
+    for (const change of changes) {
+        const validationError = validateParameterChange(document.schema, document.data, change);
+        if (validationError)
+            throw new ParameterEditError(validationError);
+    }
+    const source = await readOptionalText(root, document.dataPath);
+    if (source === undefined)
+        throw new ParameterEditError('parameter_data_missing');
+    if (observed && createHash('sha256').update(source).digest('hex') !== observed.contentHash) {
+        throw new ParameterEditError('revision_conflict');
+    }
+    const next = editJson5Paths(source, changes);
+    JSON5.parse(next);
+    if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX) {
+        throw new ParameterEditError('parameter_document_invalid');
+    }
+    const current = await locateParameterFiles(root);
+    if (await sourceFingerprint(root, current) !== document.sourceFingerprint) {
+        throw new ParameterEditError('parameter_source_conflict');
+    }
+    const catalog = parameterCatalog(document.schema, document.data);
+    const bindings = changes.flatMap(change => {
+        if (change.op === 'remove' || typeof change.value !== 'string' || !change.value)
+            return [];
+        const field = catalog.find(entry => entry.key === change.fieldPath.join('.'));
+        return field?.asset ? [{ value: change.value, asset: field.asset }] : [];
+    });
+    const registration = await prepareParameterAssetRegistration(root, document.dataPath, bindings);
+    // Register first: a failed sparse save can leave an unused asset, never a dangling saved reference.
+    const additionalWrites = [];
+    let ownIndexWrite;
+    if (registration) {
+        const written = await writeParameterAssetRegistration(root, registration);
+        additionalWrites.push(written);
+        ownIndexWrite = { path: written.path, previousHash: registration.previousHash, contentHash: written.contentHash };
+        await options.onAdditionalWrite?.(written);
+    }
+    if (await sourceFingerprint(root, await locateParameterFiles(root), ownIndexWrite) !== document.sourceFingerprint)
+        throw new ParameterEditError('parameter_source_conflict');
+    const latest = await readOptionalText(root, document.dataPath);
+    if (latest !== source)
+        throw new ParameterEditError('revision_conflict');
+    const written = await writeWorkspaceFile(root, document.dataPath, next);
+    return { ...written, ...(additionalWrites.length ? { additionalWrites } : {}) };
+}
+async function locateParameterFiles(root) {
+    const manifest = await readOptionalJson5(root, MANIFEST_PATH);
+    if (manifest.status === 'invalid') {
+        return { errors: [{ path: MANIFEST_PATH, reason: 'parameter_manifest_invalid' }] };
+    }
+    if (manifest.status === 'ok') {
+        const declared = declaredPaths(manifest.value);
+        if (!declared) {
+            return { errors: [{ path: MANIFEST_PATH, reason: 'parameter_manifest_invalid' }] };
+        }
+        if (declared.schemaPath || declared.dataPath)
+            return { ...declared, errors: [] };
+        if (declared.themeId) {
+            return {
+                schemaPath: DEFAULT_SCHEMA_PATH,
+                dataPath: `${THEME_ROOT}/${declared.themeId}/theme.data.json5`,
+                themeId: declared.themeId,
+                errors: [],
+            };
+        }
+    }
+    const schemaExists = (await readOptionalJson5(root, DEFAULT_SCHEMA_PATH)).status !== 'missing';
+    const theme = await readDeclaredTheme(root);
+    const dataPath = theme
+        ? `${THEME_ROOT}/${theme}/theme.data.json5`
+        : await uniqueThemeDataPath(root);
+    if (!schemaExists) {
+        return { themeId: theme, errors: [] };
+    }
+    if (!theme && (await listThemeDataFiles(root)).length > 1) {
+        return {
+            schemaPath: DEFAULT_SCHEMA_PATH,
+            errors: [{ path: THEME_INDEX_PATH, reason: 'theme_data_ambiguous' }],
+        };
+    }
+    return {
+        schemaPath: DEFAULT_SCHEMA_PATH,
+        dataPath,
+        themeId: theme,
+        errors: [],
+    };
+}
+function declaredPaths(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const parameters = value.parameters;
+    if (parameters === undefined)
+        return {};
+    if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters))
+        return undefined;
+    const record = parameters;
+    if (Object.keys(record).some((key) => !['schemaPath', 'dataPath', 'themeId'].includes(key))) {
+        return undefined;
+    }
+    const schemaPath = record.schemaPath === undefined ? undefined : workspaceRelativePathSchema.safeParse(record.schemaPath);
+    const dataPath = record.dataPath === undefined ? undefined : workspaceRelativePathSchema.safeParse(record.dataPath);
+    const themeId = record.themeId === undefined
+        ? undefined
+        : typeof record.themeId === 'string' && record.themeId.trim() && record.themeId.length <= 128
+            ? record.themeId.trim()
+            : undefined;
+    if (record.schemaPath !== undefined && !schemaPath?.success)
+        return undefined;
+    if (record.dataPath !== undefined && !dataPath?.success)
+        return undefined;
+    if (record.themeId !== undefined && !themeId)
+        return undefined;
+    return {
+        schemaPath: schemaPath?.success ? schemaPath.data : undefined,
+        dataPath: dataPath?.success ? dataPath.data : undefined,
+        themeId,
+    };
+}
+async function readDeclaredTheme(root) {
+    const contents = await readOptionalText(root, THEME_INDEX_PATH);
+    if (!contents)
+        return undefined;
+    const text = contents.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+    const match = text.match(/export\s+\{\s*default\s*\}\s+from\s+['"]\.\/([^'"]+)['"]/);
+    const themeId = match?.[1]?.trim();
+    return themeId && workspaceRelativePathSchema.safeParse(`${THEME_ROOT}/${themeId}/theme.data.json5`).success
+        ? themeId
+        : undefined;
+}
+async function uniqueThemeDataPath(root) {
+    const files = await listThemeDataFiles(root);
+    return files.length === 1 ? files[0] : undefined;
+}
+async function listThemeDataFiles(root) {
+    try {
+        const rootReal = await realpath(root);
+        const themeRoot = resolve(rootReal, ...THEME_ROOT.split('/'));
+        const entries = await readdir(themeRoot, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const relativePath = `${THEME_ROOT}/${entry.name}/theme.data.json5`;
+            if ((await readOptionalText(root, relativePath)) !== undefined)
+                files.push(relativePath);
+        }
+        return files;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function readOptionalJson5(root, relativePath) {
+    const text = await readOptionalText(root, relativePath);
+    if (text === undefined)
+        return { status: 'missing' };
+    try {
+        return { status: 'ok', value: JSON5.parse(text), contentHash: createHash('sha256').update(text).digest('hex') };
+    }
+    catch {
+        return { status: 'invalid', reason: 'parameter_document_invalid' };
+    }
+}
+async function readOptionalText(root, relativePath) {
+    const parsed = workspaceRelativePathSchema.safeParse(relativePath);
+    if (!parsed.success)
+        return undefined;
+    try {
+        const rootReal = await realpath(root);
+        const target = resolve(rootReal, ...parsed.data.split('/'));
+        const text = await readFile(target, 'utf8');
+        const existing = await realpath(target);
+        const rel = relative(rootReal, existing);
+        if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || rel.startsWith('..')) {
+            throw new InvalidWorkspacePathError(relativePath);
+        }
+        if (Buffer.byteLength(text, 'utf8') > WORKSPACE_FILE_CONTENT_MAX) {
+            throw new ParameterEditError('parameter_document_invalid');
+        }
+        return text;
+    }
+    catch (error) {
+        if (error instanceof ParameterEditError || error instanceof InvalidWorkspacePathError)
+            throw error;
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function platformI18nPath(schemaPath) {
+    return [...schemaPath.split('/').slice(0, -1), 'i18n.platform.json5'].join('/');
+}