@playcraft/cli 0.1.57-beta → 0.1.59-beta

package/dist/workspace-runtime/workspaces/parameter-initialization-skill.js

@@ -0,0 +1,329 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, declarationDigest, dependencyDigest, PROJECT_SKILL_SOURCE_ROOTS, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { excludeFromGit } from './dependencies.js';
+import { ensureSharedDirectory, openSharedFile, shareIfNeeded } from './shared-write.js';
+import { acquireParameterSkillLease, readParameterSkillTransactionFile, writeParameterSkillTransaction } from './parameter-initialization-skill-transaction.js';
+export const PARAMETER_INITIALIZATION_SKILL = 'playcraft-runtime-parameters';
+const sourceRoot = `.agents/skills/${PARAMETER_INITIALIZATION_SKILL}`;
+const skillRef = `builtin/${PARAMETER_INITIALIZATION_SKILL}`;
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            throw new Error('workspace_skills_invalid');
+    }
+    await ensureSharedDirectory(root, current);
+    return current;
+}
+async function writeExclusiveShared(root, path, data) {
+    const handle = await openSharedFile(root, path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
+    try {
+        await handle.writeFile(data);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function optionalFile(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('workspace_skills_invalid');
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function installSource(root, files, token) {
+    const directory = join(root, sourceRoot);
+    const staging = await safeDirectory(root, `.playcraft/parameter-initialization-${token}`);
+    const temporary = join(staging, 'source');
+    await ensureSharedDirectory(root, temporary);
+    await safeDirectory(root, '.agents/skills');
+    try {
+        for (const file of files) {
+            if (dirname(file.path) !== '.')
+                await safeDirectory(temporary, dirname(file.path));
+            await writeExclusiveShared(root, join(temporary, file.path), file.content);
+        }
+        if (await lstat(directory).then(() => true, error => { if (error.code === 'ENOENT')
+            return false; throw error; }))
+            throw new Error('workspace_skills_parameter_conflict');
+        await rename(temporary, directory);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+}
+async function preserveArtifact(root, artifactHash, archive, token) {
+    const directory = await safeDirectory(root, '.playcraft/skill-artifacts');
+    const path = join(directory, `${artifactHash}.tar.gz`);
+    const existing = await readParameterSkillTransactionFile(path);
+    if (existing) {
+        if (!existing.equals(archive))
+            throw new Error('workspace_skills_digest_mismatch');
+        await shareIfNeeded(root, path);
+        return;
+    }
+    const temporary = `${path}.${token}.tmp`;
+    try {
+        await writeExclusiveShared(root, temporary, archive);
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function snapshot(originalDeclaration, originalLock) {
+    if ((originalDeclaration === undefined) !== (originalLock === null))
+        throw new Error('workspace_skills_invalid');
+    if (originalDeclaration !== undefined)
+        return validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), originalLock);
+    const declaration = { schemaVersion: 1, entries: [] };
+    return { declaration, lock: { lockVersion: 3, declarationHash: declarationDigest(declaration), entries: [] } };
+}
+function selectedSnapshot(previous, templateHash, artifactHash) {
+    const next = structuredClone(previous);
+    const matches = next.declaration.entries.filter(entry => entry.entryKey === PARAMETER_INITIALIZATION_SKILL
+        || entry.source.skillRef === skillRef || entry.source.kind === 'repository' && entry.source.root === sourceRoot);
+    if (matches.length > 1)
+        throw new Error('workspace_skills_parameter_conflict');
+    const existing = matches[0];
+    let selected;
+    if (existing) {
+        const locked = next.lock.entries.find(entry => entry.entryKey === existing.entryKey);
+        if (existing.source.kind !== 'repository' || existing.source.root !== sourceRoot
+            || existing.source.skillRef !== skillRef || existing.surface !== 'sandbox-agent' || existing.projectFiles?.length
+            || locked.dependencies.length || locked.revision.kind !== 'source' || locked.sourceTreeHash !== templateHash
+            || locked.revision.artifactHash !== artifactHash)
+            throw new Error('workspace_skills_parameter_conflict');
+        selected = existing;
+        selected.enabled = true;
+    }
+    else {
+        selected = { entryKey: PARAMETER_INITIALIZATION_SKILL, source: { kind: 'repository', root: sourceRoot, skillRef },
+            enabled: true, surface: 'sandbox-agent' };
+        const locked = { entryKey: selected.entryKey, sourceTreeHash: templateHash,
+            revision: { kind: 'source', skillRef, sourceRevision: `src-v1-sha256:${templateHash}`, artifactHash },
+            dependencies: [], dependencyLockHash: dependencyDigest([], []) };
+        next.declaration.entries.push(selected);
+        next.lock.entries.push(locked);
+    }
+    next.lock.declarationHash = declarationDigest(next.declaration);
+    validateProjectSkillsSnapshot(next.declaration, next.lock);
+    return { next, selected, sourceAdded: !existing };
+}
+async function cleanStaging(root, transaction, files, archive) {
+    const directory = join(root, '.playcraft', `parameter-initialization-${transaction.owner.token}`);
+    const expected = new Map(files.map(file => [`source/${file.path}`, Buffer.from(file.content)]));
+    const visit = async (path, relative = '') => {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+        if (stat.isDirectory()) {
+            if (relative && ![...expected.keys()].some(file => file.startsWith(`${relative}/`)))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+            for (const name of await readdir(path))
+                await visit(join(path, name), relative ? `${relative}/${name}` : name);
+        }
+        else {
+            const bytes = await readParameterSkillTransactionFile(path);
+            const wanted = expected.get(relative);
+            if (!bytes || !wanted || !wanted.subarray(0, bytes.length).equals(bytes))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+        }
+    };
+    if (await lstat(directory).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; })) {
+        await visit(directory);
+        await rm(directory, { recursive: true });
+    }
+    const temporaryFiles = [
+        ['skills.json', Buffer.from(transaction.nextDeclaration)], ['skills.lock.json', Buffer.from(transaction.nextLock)],
+        [`skill-artifacts/${transaction.artifactHash}.tar.gz`, archive],
+    ];
+    for (const [name, expectedBytes] of temporaryFiles) {
+        const path = join(root, '.playcraft', `${name}.${transaction.owner.token}.tmp`);
+        const bytes = await readParameterSkillTransactionFile(path);
+        if (bytes) {
+            if (!expectedBytes.subarray(0, bytes.length).equals(bytes))
+                throw new Error('workspace_skills_parameter_recovery_conflict');
+            await rm(path);
+        }
+    }
+}
+async function recoverTransaction(root, transaction, template, artifactHash, archive) {
+    if (transaction.templateHash !== template.sourceTreeHash || transaction.artifactHash !== artifactHash)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const originalDeclaration = transaction.originalDeclaration === null ? undefined : Buffer.from(transaction.originalDeclaration, 'base64');
+    if (originalDeclaration && originalDeclaration.toString('base64') !== transaction.originalDeclaration)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const previous = snapshot(originalDeclaration, transaction.originalLock);
+    const { next, selected, sourceAdded } = selectedSnapshot(previous, template.sourceTreeHash, artifactHash);
+    if (sourceAdded !== transaction.sourceAdded || `${canonicalProjectSkillsJson(next.declaration)}\n` !== transaction.nextDeclaration
+        || `${canonicalProjectSkillsJson(next.lock)}\n` !== transaction.nextLock)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const declarationPath = join(root, '.playcraft/skills.json'), lockPath = join(root, '.playcraft/skills.lock.json');
+    const declaration = await optionalFile(declarationPath), lock = await readProjectSkillsLockFile(root);
+    const oldDeclaration = declaration === undefined ? originalDeclaration === undefined : !!originalDeclaration?.equals(declaration);
+    const newDeclaration = declaration?.equals(Buffer.from(transaction.nextDeclaration));
+    const oldLock = lock === transaction.originalLock, newLock = lock === transaction.nextLock;
+    if (!(oldDeclaration && oldLock || newDeclaration && (oldLock || newLock)))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const sourceExists = await lstat(join(root, sourceRoot)).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; });
+    if (!sourceExists) {
+        if (!sourceAdded || !oldDeclaration || !oldLock)
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+    }
+    else {
+        if ((await readProjectSkillSource(root, selected)).sourceTreeHash !== template.sourceTreeHash)
+            throw new Error('workspace_skills_source_changed');
+        // The exact source and pair identify the interrupted import; finish only its recorded transition.
+        for (const [path, content] of [[declarationPath, transaction.nextDeclaration], [lockPath, transaction.nextLock]]) {
+            if ((await optionalFile(path))?.equals(Buffer.from(content)))
+                continue;
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                await writeExclusiveShared(root, temporary, content);
+                await rename(temporary, path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        }
+    }
+    await cleanStaging(root, transaction, template.files, archive);
+}
+/** A deliberate initialization selects one versioned project skill without synchronizing other sources. */
+export async function ensureParameterInitializationSkill(root) {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('workspace_skills_invalid');
+    const templateEntry = { entryKey: PARAMETER_INITIALIZATION_SKILL,
+        source: { kind: 'repository', root: `project-template/.claude/skills/${PARAMETER_INITIALIZATION_SKILL}`, skillRef },
+        enabled: true, surface: 'sandbox-agent' };
+    const template = await readProjectSkillSource(resolveCliPackageRoot(), templateEntry);
+    const archive = createCanonicalBundleArchive(template.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+    const artifactHash = digest(archive);
+    await excludeFromGit(root, '/.playcraft/skills/');
+    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
+    await excludeFromGit(root, '/.playcraft/skills-write.lock');
+    await excludeFromGit(root, '/.playcraft/parameter-initialization-*');
+    const management = await safeDirectory(root, '.playcraft');
+    const lease = await acquireParameterSkillLease(management, transaction => recoverTransaction(root, transaction, template, artifactHash, archive));
+    const staged = [];
+    let ownedSource = false, committed = false, cleanupAllowed = true;
+    let removeTransaction;
+    try {
+        const declarationPath = join(management, 'skills.json'), lockPath = join(management, 'skills.lock.json');
+        const originalDeclaration = await optionalFile(declarationPath);
+        const originalLock = await readProjectSkillsLockFile(root);
+        const previous = snapshot(originalDeclaration, originalLock);
+        const { next, selected, sourceAdded } = selectedSnapshot(previous, template.sourceTreeHash, artifactHash);
+        if (!sourceAdded) {
+            if ((await readProjectSkillSource(root, selected)).sourceTreeHash !== template.sourceTreeHash)
+                throw new Error('workspace_skills_source_changed');
+            await safeDirectory(root, sourceRoot);
+            for (const file of template.files) {
+                if (dirname(file.path) !== '.')
+                    await safeDirectory(root, `${sourceRoot}/${dirname(file.path)}`);
+                await shareIfNeeded(root, join(root, sourceRoot, file.path));
+            }
+        }
+        else {
+            for (const source of PROJECT_SKILL_SOURCE_ROOTS) {
+                const path = join(root, source, PARAMETER_INITIALIZATION_SKILL);
+                const exists = await lstat(path).then(() => true, error => {
+                    if (error.code === 'ENOENT')
+                        return false;
+                    throw error;
+                });
+                if (exists)
+                    throw new Error('workspace_skills_parameter_conflict');
+            }
+        }
+        if (canonicalProjectSkillsJson(previous) !== canonicalProjectSkillsJson(next)) {
+            removeTransaction = await writeParameterSkillTransaction(management, { version: 1, owner: lease.owner,
+                templateHash: template.sourceTreeHash, artifactHash, sourceAdded,
+                originalDeclaration: originalDeclaration?.toString('base64') ?? null, originalLock,
+                nextDeclaration: `${canonicalProjectSkillsJson(next.declaration)}\n`, nextLock: `${canonicalProjectSkillsJson(next.lock)}\n` });
+            if (sourceAdded) {
+                await installSource(root, template.files, lease.owner.token);
+                ownedSource = true;
+            }
+            await preserveArtifact(root, artifactHash, archive, lease.owner.token);
+            const pending = [];
+            for (const [path, value] of [[declarationPath, next.declaration], [lockPath, next.lock]]) {
+                const temporary = `${path}.${lease.owner.token}.tmp`;
+                staged.push(temporary);
+                await writeExclusiveShared(root, temporary, `${canonicalProjectSkillsJson(value)}\n`);
+                pending.push(temporary);
+            }
+            const currentDeclaration = await optionalFile(declarationPath);
+            if (currentDeclaration === undefined ? originalDeclaration !== undefined
+                : originalDeclaration === undefined || !currentDeclaration.equals(originalDeclaration))
+                throw new Error('skills_revision_conflict');
+            if (await readProjectSkillsLockFile(root) !== originalLock)
+                throw new Error('skills_revision_conflict');
+            await rename(pending[0], declarationPath);
+            try {
+                await rename(pending[1], lockPath);
+            }
+            catch (error) {
+                try {
+                    if (originalDeclaration === undefined)
+                        await rm(declarationPath, { force: true });
+                    else {
+                        const restore = `${declarationPath}.${randomUUID()}.tmp`;
+                        staged.push(restore);
+                        await writeExclusiveShared(root, restore, originalDeclaration);
+                        await rename(restore, declarationPath);
+                    }
+                }
+                catch (restoreError) {
+                    cleanupAllowed = false;
+                    throw restoreError;
+                }
+                throw error;
+            }
+        }
+        else
+            await preserveArtifact(root, artifactHash, archive, lease.owner.token);
+        committed = true;
+        await shareIfNeeded(root, declarationPath);
+        await shareIfNeeded(root, lockPath);
+        return { entryKey: selected.entryKey, lockHash: digest(canonicalProjectSkillsJson(next.lock)) };
+    }
+    finally {
+        if (cleanupAllowed && ownedSource && !committed) {
+            const entry = { entryKey: PARAMETER_INITIALIZATION_SKILL,
+                source: { kind: 'repository', root: sourceRoot }, enabled: true, surface: 'sandbox-agent' };
+            if ((await readProjectSkillSource(root, entry)).sourceTreeHash !== template.sourceTreeHash)
+                throw new Error('workspace_skills_source_changed');
+            await rm(join(root, sourceRoot), { recursive: true });
+        }
+        if (cleanupAllowed) {
+            for (const path of staged)
+                await rm(path, { force: true });
+            await removeTransaction?.();
+            await lease.release();
+        }
+    }
+}

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

@@ -0,0 +1,63 @@
+import JSON5 from 'json5';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { PREVIEW_RUNTIME_DIRECTORY, readPreviewRuntimeDistribution } from '../../preview-runtime/distribution.js';
+import { ParameterAgentError, parameterDigest, readParameterAgentFile } from './parameter-agent-inputs.js';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const path = (value) => workspaceRelativePathSchema.safeParse(value).success;
+async function input(root, file) {
+    try {
+        return await readParameterAgentFile(root, file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new ParameterAgentError('parameter_agent_preview_inputs_not_ready');
+        throw error;
+    }
+}
+/** Check admission inputs without building a preview, deleting outputs or declaring fields live. */
+export async function inspectParameterInitialization(root, document, report) {
+    const manifestBytes = await input(root, '.playcraft/workspace.json');
+    let manifest;
+    try {
+        manifest = record(JSON5.parse(manifestBytes.toString('utf8')));
+    }
+    catch {
+        throw new ParameterAgentError('parameter_agent_preview_manifest_not_ready');
+    }
+    const parameters = record(manifest?.parameters);
+    const preview = record(manifest?.previewRuntime);
+    const allowed = new Set(['version', 'buildScript', 'outputPath', 'reportPath', 'configContractVersion', 'entryPath', 'viteConfigPath', 'mountId', 'gameFilePaths']);
+    if (!parameters || parameters.schemaPath !== document.schemaPath || parameters.dataPath !== document.dataPath ||
+        !document.platformI18nPath || !preview || Object.keys(preview).some(key => !allowed.has(key)) || preview.version !== 1 ||
+        typeof preview.buildScript !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/.test(preview.buildScript) ||
+        !path(preview.outputPath) || !preview.outputPath.startsWith('.playcraft-editor-preview/') || !preview.outputPath.endsWith('.html') ||
+        !path(preview.reportPath) || !preview.reportPath.startsWith('.playcraft-editor-preview/') || !preview.reportPath.endsWith('.json') ||
+        typeof preview.configContractVersion !== 'string' || !preview.configContractVersion.length || preview.configContractVersion.length > 128 ||
+        !path(preview.entryPath) || (preview.viteConfigPath !== undefined && !path(preview.viteConfigPath)) ||
+        (preview.mountId !== undefined && (typeof preview.mountId !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(preview.mountId))) ||
+        !Array.isArray(preview.gameFilePaths) || preview.gameFilePaths.length > 256 || !preview.gameFilePaths.every(path))
+        throw new ParameterAgentError('parameter_agent_preview_manifest_not_ready');
+    const files = new Set(preview.gameFilePaths);
+    if (!files.has(preview.entryPath) || report.candidates.some(candidate => candidate.status === 'implemented' && !candidate.consumers.some(consumer => files.has(consumer.path))))
+        throw new ParameterAgentError('parameter_agent_preview_inputs_not_ready');
+    const packageData = JSON.parse((await input(root, 'package.json')).toString('utf8'));
+    if (typeof packageData.scripts?.[preview.buildScript] !== 'string' || !packageData.scripts[preview.buildScript].trim())
+        throw new ParameterAgentError('parameter_agent_preview_script_not_ready');
+    const hashes = [['.playcraft/workspace.json', parameterDigest(manifestBytes)]];
+    for (const file of [...files, preview.entryPath, ...(preview.viteConfigPath ? [preview.viteConfigPath] : [])])
+        hashes.push([file, parameterDigest(await input(root, file))]);
+    const trusted = await readPreviewRuntimeDistribution();
+    const copiedManifest = await input(root, `${PREVIEW_RUNTIME_DIRECTORY}/manifest.json`);
+    if (!copiedManifest.equals(trusted.manifestBytes))
+        throw new ParameterAgentError('parameter_agent_preview_sdk_not_ready');
+    hashes.push([`${PREVIEW_RUNTIME_DIRECTORY}/manifest.json`, parameterDigest(copiedManifest)]);
+    for (const [name, expected] of Object.entries(trusted.manifest.files)) {
+        const file = `${PREVIEW_RUNTIME_DIRECTORY}/${name}`;
+        const bytes = await input(root, file);
+        const actual = parameterDigest(bytes);
+        if (actual !== expected)
+            throw new ParameterAgentError('parameter_agent_preview_sdk_not_ready');
+        hashes.push([file, actual]);
+    }
+    return parameterDigest(JSON.stringify(hashes));
+}

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

@@ -0,0 +1,124 @@
+import { lstat, readdir, realpath, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import JSON5 from 'json5';
+import { z } from 'zod';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { ParameterAgentError, parameterDigest, readParameterAgentFile } from './parameter-agent-inputs.js';
+const reportPath = '.playcraft-editor-preview/release-report.json';
+const marker = /runtime\.parameters\.|playcraft-preview-storage:|__playcraft_preview_context__/i;
+const slash = (value) => value.replaceAll('\\', '/').replaceAll('\0', '').split('?')[0];
+const relativePath = z.string().refine(value => workspaceRelativePathSchema.safeParse(value).success);
+const reportSchema = z.object({
+    version: z.literal(1), target: z.literal('playable-release'), previewRuntimeExcluded: z.literal(true),
+    moduleIds: z.array(z.string().min(1).max(4096)).min(1).max(10000),
+    artifacts: z.array(z.object({ path: relativePath, sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict()).min(1).max(4096),
+}).strict();
+async function safePath(root, path, missing = false) {
+    let current = root;
+    const segments = path.split('/');
+    for (let index = 0; index < segments.length; index++) {
+        current = resolve(current, segments[index]);
+        const stat = await lstat(current).catch(error => {
+            if (missing && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (!stat)
+            continue;
+        if (stat.isSymbolicLink() || (index < segments.length - 1 && !stat.isDirectory()))
+            throw new ParameterAgentError('parameter_agent_production_path_not_ready');
+    }
+    return current;
+}
+/** Remove only the old fixed guard report; never follow its parents into source or delivery files. */
+export async function prepareParameterProductionCheck(root) {
+    try {
+        const base = await realpath(root);
+        const manifest = JSON5.parse((await readParameterAgentFile(base, '.playcraft/workspace.json')).toString('utf8'));
+        const entry = manifest.previewRuntime?.entryPath;
+        if (!workspaceRelativePathSchema.safeParse(entry).success)
+            throw new ParameterAgentError('parameter_agent_production_entry_not_ready');
+        const file = await safePath(base, reportPath, true);
+        const stat = await lstat(file).catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isFile() || stat.nlink !== 1))
+            throw new ParameterAgentError('parameter_agent_production_path_not_ready');
+        if (stat)
+            await unlink(file);
+        return { root: base, startedAt: Date.now(), previewEntry: slash(resolve(base, entry)), requestedPreviewEntry: slash(resolve(root, entry)) };
+    }
+    catch (error) {
+        if (error instanceof ParameterAgentError)
+            throw error;
+        throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+    }
+}
+/** Inspect the reported module boundary and every actual delivery file, not a claimed success flag. */
+export async function inspectParameterProductionCheck(plan, assertActive = () => { }) {
+    try {
+        assertActive();
+        const file = await safePath(plan.root, reportPath);
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.mtimeMs + 1 < plan.startedAt)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const bytes = await readParameterAgentFile(plan.root, reportPath);
+        const parsed = reportSchema.safeParse(JSON.parse(bytes.toString('utf8')));
+        if (!parsed.success)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const report = parsed.data;
+        const sdkRoot = slash(resolve(plan.root, '.playcraft/preview-runtime')) + '/';
+        for (const moduleId of report.moduleIds) {
+            const id = slash(moduleId);
+            if (id === plan.previewEntry || id === plan.requestedPreviewEntry || id.startsWith(sdkRoot) ||
+                /(?:^|\/)(?:@playcraft\/)?preview-runtime(?:\/|@|$)/.test(id) || /@playcraft\+preview-runtime@/.test(id))
+                throw new ParameterAgentError('parameter_agent_production_modules_not_ready');
+        }
+        const declared = new Map(report.artifacts.map(artifact => [artifact.path, artifact.sha256]));
+        if (declared.size !== report.artifacts.length || new Set(report.moduleIds).size !== report.moduleIds.length)
+            throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+        const output = await safePath(plan.root, 'dist');
+        if (!(await lstat(output)).isDirectory())
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        let count = 0;
+        let total = 0;
+        let directories = 0;
+        const walk = async (directory, prefix = '', depth = 0) => {
+            assertActive();
+            if (depth > 24 || ++directories > 4096)
+                throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            const entries = await readdir(directory, { withFileTypes: true });
+            if (entries.length > 4096)
+                throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            for (const entry of entries) {
+                assertActive();
+                const relative = prefix + entry.name;
+                if (!workspaceRelativePathSchema.safeParse(relative).success || entry.isSymbolicLink())
+                    throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                if (entry.isDirectory())
+                    await walk(resolve(directory, entry.name), relative + '/', depth + 1);
+                else if (entry.isFile()) {
+                    if (++count > 4096)
+                        throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                    const content = await readParameterAgentFile(plan.root, `dist/${relative}`, 50 * 1024 * 1024);
+                    total += content.byteLength;
+                    if (total > 128 * 1024 * 1024 || declared.get(relative) !== parameterDigest(content) || marker.test(content.toString()))
+                        throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+                }
+                else
+                    throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+            }
+        };
+        await walk(output);
+        if (count !== declared.size || parameterDigest(await readParameterAgentFile(plan.root, reportPath)) !== parameterDigest(bytes))
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        return { reportHash: parameterDigest(bytes), artifactCount: count, moduleCount: report.moduleIds.length };
+    }
+    catch (error) {
+        if (error instanceof ParameterAgentError || (error instanceof Error && error.name === 'AbortError'))
+            throw error;
+        throw new ParameterAgentError('parameter_agent_production_report_not_ready');
+    }
+}

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

@@ -2,9 +2,9 @@ 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 { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, parameterI18nCatalog, parameterRuntimeTranslations, PARAMETER_RUNTIME_LOCALES, validateParameterChange, validateParameterI18nChange, 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 { editJson5Paths, editJson5StringRecords, ParameterEditError } from './json5-edit.js';
 import { prepareParameterAssetRegistration, writeParameterAssetRegistration, } from './parameter-assets.js';
 import { themeAssetIndexFingerprint } from './theme-asset-index.js';
 const MANIFEST_PATH = '.playcraft/workspace.json';
@@ -32,6 +32,7 @@ async function sourceFingerprint(root, located, ownIndexWrite) {
         readOptionalText(root, MANIFEST_PATH),
         readOptionalText(root, THEME_INDEX_PATH),
         selectedIndex ? readOptionalText(root, selectedIndex) : undefined,
+        located.schemaPath ? readOptionalText(root, runtimeI18nGlobalPath(located.schemaPath)) : undefined,
     ]);
     const hashes = sources.map((text) => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
     const rawIndexHash = hashes[4];
@@ -106,6 +107,10 @@ async function readParameterDocuments(root, revisions, located) {
             ? { platformI18n: platformFile.value, platformI18nPath: i18nPath }
             : {}),
     };
+    const runtimeI18n = await readRuntimeI18n(root, revisions, located);
+    if (runtimeI18n.errors.length)
+        return parameterDocumentSchema.parse({ ...schemaDocument, status: 'invalid', errors: runtimeI18n.errors });
+    Object.assign(schemaDocument, runtimeI18n.document ? { runtimeI18n: runtimeI18n.document } : {});
     if (platformFile.status === 'invalid') {
         return parameterDocumentSchema.parse({
             ...schemaDocument,
@@ -148,6 +153,8 @@ async function readParameterDocuments(root, revisions, located) {
 export async function patchWorkspaceParameters(root, revisions, payload, observed, options = {}) {
     const parsed = parameterPatchPayloadSchema.parse(payload);
     const document = await readWorkspaceParameters(root, revisions);
+    if ('documentId' in parsed)
+        return patchWorkspaceParameterI18n(root, document, parsed, observed);
     if (document.status === 'invalid')
         throw new ParameterEditError('parameter_document_invalid');
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
@@ -169,7 +176,7 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     if (observed && createHash('sha256').update(source).digest('hex') !== observed.contentHash) {
         throw new ParameterEditError('revision_conflict');
     }
-    const next = editJson5Paths(source, changes);
+    const next = formatParameterData(document.dataPath, source, editJson5Paths(source, changes));
     JSON5.parse(next);
     if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX) {
         throw new ParameterEditError('parameter_document_invalid');
@@ -209,6 +216,91 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     const written = await writeWorkspaceFile(root, document.dataPath, next);
     return { ...written, ...(additionalWrites.length ? { additionalWrites } : {}) };
 }
+/** Strict data files must remain consumable by the project's original production importer. */
+function formatParameterData(path, source, edited) {
+    if (!/\.json$/i.test(path))
+        return edited;
+    const indentation = source.match(/^[\t ]+(?=")/m)?.[0] ?? (/[\r\n]/.test(source.trim()) ? '  ' : undefined);
+    const next = JSON.stringify(JSON5.parse(edited), (_key, value) => {
+        // Unknown authored values must not silently change from non-finite numbers into null.
+        if (typeof value === 'number' && !Number.isFinite(value))
+            throw new ParameterEditError('parameter_document_invalid');
+        return value;
+    }, indentation);
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    return next.replaceAll('\n', eol) + (source.endsWith('\n') ? eol : '');
+}
+async function readRuntimeI18n(root, revisions, located) {
+    if (!located.schemaPath || !located.dataPath)
+        return { errors: [] };
+    const globalPath = runtimeI18nGlobalPath(located.schemaPath);
+    const themePath = runtimeI18nThemePath(located.dataPath);
+    const [globalFile, themeFile] = await Promise.all([readOptionalJson5(root, globalPath), readOptionalJson5(root, themePath)]);
+    const errors = [];
+    if (globalFile.status === 'invalid')
+        errors.push({ path: globalPath, reason: globalFile.reason });
+    if (themeFile.status === 'invalid')
+        errors.push({ path: themePath, reason: themeFile.reason });
+    if (errors.length || globalFile.status === 'missing' && themeFile.status === 'missing')
+        return { errors };
+    return { errors, document: {
+            globalPath, themePath,
+            global: globalFile.status === 'ok' ? globalFile.value : {},
+            theme: themeFile.status === 'ok' ? themeFile.value : {},
+            ...(globalFile.status === 'ok' ? { globalHash: globalFile.contentHash } : {}),
+            ...(themeFile.status === 'ok' ? { themeHash: themeFile.contentHash } : {}),
+            globalRevision: revisions[globalPath]?.revision ?? 0,
+            themeRevision: revisions[themePath]?.revision ?? 0,
+            locales: [...PARAMETER_RUNTIME_LOCALES],
+        } };
+}
+async function patchWorkspaceParameterI18n(root, document, payload, observed) {
+    if (document.status !== 'ready' || !document.runtimeI18n)
+        throw new ParameterEditError('parameter_i18n_global_invalid');
+    const runtime = document.runtimeI18n;
+    if (payload.sourceFingerprint !== document.sourceFingerprint || observed && observed.dataPath !== runtime.themePath)
+        throw new ParameterEditError('parameter_source_conflict');
+    for (const change of payload.changes) {
+        const error = validateParameterI18nChange(document, change);
+        if (error)
+            throw new ParameterEditError(error);
+    }
+    const source = await readOptionalText(root, runtime.themePath);
+    if (observed && (source === undefined ? '' : createHash('sha256').update(source).digest('hex')) !== observed.contentHash)
+        throw new ParameterEditError('revision_conflict');
+    const globals = runtime.global;
+    const themes = runtime.theme;
+    const nextEntries = new Map();
+    const changedLocales = new Set();
+    for (const change of payload.changes) {
+        const field = parameterI18nCatalog(document, change.locale).find(entry => entry.key === change.fieldPath.join('.'));
+        const key = field.runtimeI18nKey;
+        const identity = JSON.stringify([key, change.locale]);
+        if (changedLocales.has(identity))
+            throw new ParameterEditError('parameter_changes_overlap');
+        changedLocales.add(identity);
+        const defaults = parameterRuntimeTranslations(globals[key]);
+        const previous = parameterRuntimeTranslations(themes[key]) ?? defaults;
+        const entry = nextEntries.get(key) ?? { ...previous };
+        entry[change.locale] = change.op === 'remove' ? defaults[change.locale] : change.value;
+        nextEntries.set(key, entry);
+    }
+    const edits = [...nextEntries].map(([key, value]) => PARAMETER_RUNTIME_LOCALES.every(locale => value[locale] === globals[key][locale]) ? { key, op: 'remove' } : { key, value });
+    const next = editJson5StringRecords(source ?? '{}\n', edits);
+    if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX)
+        throw new ParameterEditError('parameter_document_invalid');
+    if (await sourceFingerprint(root, await locateParameterFiles(root)) !== document.sourceFingerprint)
+        throw new ParameterEditError('parameter_source_conflict');
+    if (await readOptionalText(root, runtime.themePath) !== source)
+        throw new ParameterEditError('revision_conflict');
+    return writeWorkspaceFile(root, runtime.themePath, next);
+}
+function runtimeI18nGlobalPath(schemaPath) {
+    return posix.join(posix.dirname(schemaPath), 'i18n.runtime.json5');
+}
+function runtimeI18nThemePath(dataPath) {
+    return posix.join(posix.dirname(dataPath), 'theme.i18n.runtime.json5');
+}
 async function locateParameterFiles(root) {
     const manifest = await readOptionalJson5(root, MANIFEST_PATH);
     if (manifest.status === 'invalid') {