@playcraft/cli 0.1.48-beta → 0.1.50-beta

package/dist/workspace-runtime/workspaces/directory-mutations.js

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { directoryDeletePayloadSchema, directoryRenamePayloadSchema, hashOperationPayload, isMutableWorkspaceDirectoryPath, } from '@playcraft/common/cloud-workspace/runtime';
+import { safeAssetTransferDirectory, syncAssetTransferDirectory } from './asset-transfer-storage.js';
+export class DirectoryMutationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const fail = (code) => { throw new DirectoryMutationError(code); };
+const missing = (error) => error?.code === 'ENOENT';
+const identitySchema = z.object({ dev: z.number().nonnegative(), ino: z.number().nonnegative() }).strict();
+const receiptSchema = z.object({ operationId: z.string().min(1).max(128), kind: z.enum(['directory.rename', 'directory.delete']),
+    path: z.string(), newPath: z.string().optional(), revision: z.number().int().nonnegative(), recoveryPath: z.string().optional() }).strict();
+const recordSchema = z.object({ version: z.literal(1), scope: z.string(), operationId: z.string().min(1).max(128),
+    payloadHash: z.string().regex(/^[a-f0-9]{64}$/), kind: z.enum(['directory.rename', 'directory.delete']),
+    operationPayloadHash: z.string().regex(/^[a-f0-9]{64}$/), payload: z.unknown(),
+    path: z.string(), newPath: z.string().optional(), source: identitySchema, reservation: identitySchema.optional(),
+    revision: z.number().int().nonnegative(), phase: z.enum(['prepared', 'completed']), receipt: receiptSchema.optional() }).strict();
+async function identity(path) {
+    const stat = await lstat(path).catch(error => { if (!missing(error))
+        throw error; return undefined; });
+    if (!stat)
+        return undefined;
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(path) !== path)
+        fail('invalid_workspace_path');
+    return { dev: stat.dev, ino: stat.ino };
+}
+function same(left, right) { return Boolean(left && right && left.dev === right.dev && left.ino === right.ino); }
+/** Reject redirected entries and managed descendants too: renaming their parent must not bypass path protection. */
+async function validateTree(root, path) {
+    await safeAssetTransferDirectory(root, path);
+    const target = join(root, ...path.split('/'));
+    const original = await identity(target);
+    if (!original)
+        return fail('directory_not_found');
+    const visit = async (current, relative) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const child = join(current, entry.name), childPath = `${relative}/${entry.name}`;
+            const stat = await lstat(child);
+            if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()
+                || stat.isDirectory() && !isMutableWorkspaceDirectoryPath(childPath))
+                fail('invalid_workspace_path');
+            if (stat.isDirectory()) {
+                await safeAssetTransferDirectory(root, childPath);
+                await visit(child, childPath);
+            }
+        }
+    };
+    await visit(target, path);
+    if (!same(original, await identity(target)))
+        fail('directory_conflict');
+    return original;
+}
+async function saveRecord(directory, record) {
+    await safeAssetTransferDirectory(directory);
+    const temporary = join(directory, `${randomUUID()}.tmp`);
+    const file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(JSON.stringify(record));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await safeAssetTransferDirectory(directory);
+    await rename(temporary, join(directory, 'record.json'));
+    await syncAssetTransferDirectory(directory);
+}
+async function readRecord(directory) {
+    let handle;
+    try {
+        handle = await open(join(directory, 'record.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 64 * 1024)
+            fail('directory_recovery_required');
+        return recordSchema.parse(JSON.parse(await handle.readFile('utf8')));
+    }
+    catch {
+        return fail('directory_recovery_required');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function cleanupRemoved(directory, record) {
+    if (record.kind !== 'directory.delete' || !record.receipt?.recoveryPath)
+        return;
+    try {
+        await safeAssetTransferDirectory(directory);
+        const destination = join(directory, 'removed'), stored = await identity(destination);
+        if (stored) {
+            if (!same(stored, record.source))
+                return;
+            await rm(destination, { recursive: true, force: false });
+            await syncAssetTransferDirectory(directory);
+        }
+        delete record.receipt.recoveryPath;
+        await saveRecord(directory, record);
+    }
+    catch { /* A retained private backup is disclosed in the receipt, never mistaken for a fresh source. */ }
+}
+/** A durable identity-bound intent makes a retry independent of any directory recreated at the old path. */
+export async function mutateWorkspaceDirectory(root, kind, input, options) {
+    const parsed = kind === 'directory.rename' ? directoryRenamePayloadSchema.safeParse(input) : directoryDeletePayloadSchema.safeParse(input);
+    if (!parsed.success || !options.operationId || options.operationId.length > 128)
+        return fail('invalid_workspace_path');
+    const payload = parsed.data, newPath = 'newName' in payload
+        ? [...payload.path.split('/').slice(0, -1), payload.newName].join('/') : undefined;
+    if (newPath === payload.path)
+        return fail('directory_exists');
+    if ((await lstat(root)).isSymbolicLink())
+        return fail('invalid_workspace_path');
+    root = await realpath(root);
+    await safeAssetTransferDirectory(root);
+    const key = createHash('sha256').update(`${options.scope}\0${options.operationId}`).digest('hex');
+    const relativeDirectory = `.playcraft-temp/directory-mutations/${key}`;
+    const directory = options.recoverOnly
+        ? await safeAssetTransferDirectory(root, relativeDirectory).catch(error => { if (missing(error))
+            return undefined; throw error; })
+        : await safeAssetTransferDirectory(root, relativeDirectory, true);
+    if (!directory)
+        return undefined;
+    let record = await readRecord(directory);
+    const payloadHash = hashOperationPayload({ kind, payload });
+    if (record && (record.operationId !== options.operationId || record.scope !== options.scope || record.payloadHash !== payloadHash
+        || record.operationPayloadHash !== (options.operationPayloadHash ?? hashOperationPayload(input))
+        || record.path !== payload.path || record.kind !== kind || record.newPath !== newPath))
+        return fail('directory_recovery_required');
+    if (record?.phase === 'completed') {
+        const expected = { operationId: options.operationId, kind, path: payload.path, ...(newPath ? { newPath } : {}), revision: record.revision };
+        if (!record.receipt || Object.entries(expected).some(([key, value]) => record.receipt[key] !== value)
+            || record.receipt.recoveryPath && record.receipt.recoveryPath !== `${relativeDirectory}/removed`)
+            return fail('directory_recovery_required');
+        await cleanupRemoved(directory, record);
+        return record.receipt;
+    }
+    if (!record) {
+        if (options.recoverOnly)
+            return undefined;
+        let source;
+        try {
+            source = await validateTree(root, payload.path);
+        }
+        catch (error) {
+            if (missing(error))
+                return fail('directory_not_found');
+            throw error;
+        }
+        const revision = await options.observeRevision();
+        if (revision === undefined)
+            return fail('directory_revision_unavailable');
+        if (payload.expectedRevision !== undefined && payload.expectedRevision !== revision)
+            return fail('revision_conflict');
+        if (newPath && await lstat(join(root, ...newPath.split('/'))).then(() => true, error => { if (missing(error))
+            return false; throw error; }))
+            return fail('directory_exists');
+        record = { version: 1, scope: options.scope, operationId: options.operationId, payloadHash,
+            operationPayloadHash: options.operationPayloadHash ?? hashOperationPayload(input), payload, kind, path: payload.path,
+            ...(newPath ? { newPath } : {}), source, revision: revision + 1, phase: 'prepared' };
+        await saveRecord(directory, record);
+    }
+    const source = join(root, ...record.path.split('/'));
+    const destination = newPath ? join(root, ...newPath.split('/')) : join(directory, 'removed');
+    await safeAssetTransferDirectory(root, record.path.split('/').slice(0, -1).join('/'));
+    let destinationIdentity = await identity(destination);
+    if (!same(destinationIdentity, record.source)) {
+        if (!same(await identity(source), record.source))
+            return fail('directory_recovery_required');
+        await validateTree(root, record.path);
+        if (newPath) {
+            // Reserve an absent destination atomically; only our recorded empty placeholder may be replaced.
+            if (!destinationIdentity) {
+                await mkdir(destination, { mode: 0o700 }).catch(error => { if (error.code === 'EEXIST')
+                    return fail('directory_exists'); throw error; });
+                record.reservation = await identity(destination);
+                await saveRecord(directory, record);
+            }
+            else if (!same(destinationIdentity, record.reservation))
+                return fail('directory_exists');
+            destinationIdentity = await identity(destination);
+            if (!same(destinationIdentity, record.reservation) || (await readdir(destination)).length)
+                return fail('directory_exists');
+        }
+        else if (destinationIdentity)
+            return fail('directory_recovery_required');
+        await options.assertCurrent?.();
+        if (!same(await identity(source), record.source))
+            return fail('directory_conflict');
+        if (newPath && !same(await identity(destination), record.reservation))
+            return fail('directory_exists');
+        await rename(source, destination);
+        await syncAssetTransferDirectory(dirname(source));
+        await syncAssetTransferDirectory(dirname(destination));
+    }
+    await options.onDetached?.();
+    const receipt = { operationId: options.operationId, kind, path: record.path,
+        ...(newPath ? { newPath } : {}), revision: record.revision };
+    if (!newPath) {
+        // Mark the detach durably before recursive cleanup; a crash during cleanup cannot revive the old path.
+        receipt.recoveryPath = `${relativeDirectory}/removed`;
+    }
+    record = { ...record, phase: 'completed', receipt };
+    await saveRecord(directory, record);
+    await cleanupRemoved(directory, record);
+    return receipt;
+}
+/** Recover only an existing intent whose scope and original operation payload still agree. Never start new work. */
+export async function recoverWorkspaceDirectoryMutation(root, kind, options) {
+    if ((await lstat(root)).isSymbolicLink())
+        return fail('invalid_workspace_path');
+    root = await realpath(root);
+    const key = createHash('sha256').update(`${options.scope}\0${options.operationId}`).digest('hex');
+    const directory = await safeAssetTransferDirectory(root, `.playcraft-temp/directory-mutations/${key}`)
+        .catch(error => { if (missing(error))
+        return undefined; throw error; });
+    if (!directory)
+        return undefined;
+    const record = await readRecord(directory);
+    if (!record)
+        return undefined;
+    const payload = kind === 'directory.rename' ? directoryRenamePayloadSchema.safeParse(record.payload) : directoryDeletePayloadSchema.safeParse(record.payload);
+    if (!payload.success)
+        return fail('directory_recovery_required');
+    return mutateWorkspaceDirectory(root, kind, payload.data, { ...options, recoverOnly: true, observeRevision: async () => undefined });
+}

package/dist/workspace-runtime/workspaces/directory-revisions.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMutableWorkspaceDirectoryPath } from '@playcraft/common/cloud-workspace/runtime';
+import { listWorkspaceFiles } from './files.js';
+/** Reuse the listing's streamed hashes; only directory and preservation-marker metadata is sampled again. */
+export async function observeWorkspaceDirectories(root, journal, scope, listed) {
+    const previous = journal.fileRevisions(scope);
+    const result = listed ?? await listWorkspaceFiles(root, previous);
+    const directoryRevisions = {};
+    const fingerprints = new Map();
+    for (const path of result.directories ?? []) {
+        if (!isMutableWorkspaceDirectoryPath(path)
+            || result.unreadablePaths?.some(item => item === path || item.startsWith(`${path}/`)))
+            continue;
+        const stat = await lstat(join(root, ...path.split('/')));
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            continue;
+        const marker = await lstat(join(root, ...path.split('/'), '.gitkeep')).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return undefined;
+        });
+        fingerprints.set(path, JSON.stringify([path, stat.dev, stat.ino, stat.mtimeMs, stat.ctimeMs,
+            marker && [marker.dev, marker.ino, marker.size, marker.mtimeMs, marker.ctimeMs]]));
+    }
+    for (const [path] of fingerprints) {
+        const hash = createHash('sha256').update('directory\0');
+        for (const [child, metadata] of fingerprints)
+            if (child === path || child.startsWith(`${path}/`))
+                hash.update(metadata);
+        for (const file of result.files)
+            if (file.path.startsWith(`${path}/`))
+                hash.update(JSON.stringify([file.path, file.contentHash, file.size]));
+        const contentHash = hash.digest('hex');
+        const old = previous[path];
+        const revision = old ? old.revision + Number(old.contentHash !== contentHash) : 0;
+        if (!old || old.contentHash !== contentHash)
+            await journal.putFileRevision(path, { revision, contentHash }, scope);
+        directoryRevisions[path] = revision;
+    }
+    for (const file of result.files) {
+        const old = previous[file.path];
+        const revision = old ? old.revision + Number(old.contentHash !== file.contentHash) : 0;
+        if (!old || old.contentHash !== file.contentHash)
+            await journal.putFileRevision(file.path, { revision, contentHash: file.contentHash }, scope);
+        file.revision = revision;
+    }
+    // Retain tombstones so recreating the same path cannot satisfy an old revision.
+    const present = new Set([...result.files.map(file => file.path), ...(result.directories ?? [])]);
+    for (const [path, old] of Object.entries(previous)) {
+        if (old.contentHash && !present.has(path) && !result.unreadablePaths?.some(item => path === item || path.startsWith(`${item}/`)))
+            await journal.putFileRevision(path, { revision: old.revision + 1, contentHash: '' }, scope);
+    }
+    return { ...result, directoryRevisions };
+}

package/dist/workspace-runtime/workspaces/disk-snapshot.js

@@ -1,12 +1,12 @@
 import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
-import { WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+import { ASSET_TRANSFER_FILE_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
 export async function sampleDiskFile(path) {
     const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
         const before = await handle.stat();
-        if (!before.isFile() || before.size > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
+        if (!before.isFile() || before.size > ASSET_TRANSFER_FILE_MAX_BYTES)
             throw new Error('snapshot_body_missing');
         const digest = createHash('sha256');
         const chunk = Buffer.allocUnsafe(64 * 1024);
@@ -17,7 +17,7 @@ export async function sampleDiskFile(path) {
                 break;
             digest.update(chunk.subarray(0, bytesRead));
             position += bytesRead;
-            if (position > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
+            if (position > ASSET_TRANSFER_FILE_MAX_BYTES)
                 throw new Error('snapshot_body_missing');
         }
         const after = await handle.stat();

package/dist/workspace-runtime/workspaces/json5-edit.js

@@ -7,6 +7,127 @@ export class ParameterEditError extends Error {
         this.name = 'ParameterEditError';
     }
 }
+/** Apply local JSON5 (JSON5 Data Interchange Format，JSON5 数据交换格式) edits without serializing unrelated fields. */
+export function editJson5Paths(source, changes) {
+    const parsed = JSON5.parse(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ParameterEditError('parameter_document_invalid');
+    }
+    const paths = [];
+    for (const change of changes) {
+        if (change.fieldPath.length === 0 || change.fieldPath.some((key) => !key || ['__proto__', 'prototype', 'constructor'].includes(key))) {
+            throw new ParameterEditError('parameter_value_invalid');
+        }
+        if (paths.some((other) => other.every((key, index) => key === change.fieldPath[index])
+            || change.fieldPath.every((key, index) => key === other[index]))) {
+            throw new ParameterEditError('parameter_changes_overlap');
+        }
+        if (change.op !== 'remove' && typeof change.value === 'number' && !Number.isFinite(change.value)) {
+            throw new ParameterEditError('parameter_value_invalid');
+        }
+        paths.push(change.fieldPath);
+    }
+    let next = source;
+    for (const change of changes)
+        next = editJson5Object(next, skipTrivia(next, 0, next.length), change, 0);
+    JSON5.parse(next);
+    return next;
+}
+function editJson5Object(source, braceIndex, change, depth) {
+    const object = readJson5Object(source, braceIndex);
+    const memberIndex = object.members.findIndex((member) => member.name === change.fieldPath[depth]);
+    const member = object.members[memberIndex];
+    if (member && depth < change.fieldPath.length - 1) {
+        if (source[member.value.start] !== '{')
+            throw new ParameterEditError('parameter_value_invalid');
+        return editJson5Object(source, member.value.start, change, depth + 1);
+    }
+    if (change.op === 'remove') {
+        if (!member)
+            return source;
+        if (source[member.value.start] === '{' || source[member.value.start] === '[') {
+            throw new ParameterEditError('parameter_value_invalid');
+        }
+        const comma = member.comma ?? object.members[memberIndex - 1]?.comma;
+        const spans = [{ start: member.keyStart, end: member.value.end },
+            ...(comma === undefined ? [] : [{ start: comma, end: comma + 1 }])].sort((left, right) => right.start - left.start);
+        let next = source;
+        for (const span of spans)
+            next = `${next.slice(0, span.start)}${next.slice(span.end)}`;
+        return next;
+    }
+    if (member) {
+        if (source[member.value.start] === '{' || source[member.value.start] === '[') {
+            throw new ParameterEditError('parameter_value_invalid');
+        }
+        return `${source.slice(0, member.value.start)}${formatJson5Value(change.value, source.slice(member.value.start, member.value.end))}${source.slice(member.value.end)}`;
+    }
+    const objectIndent = lineIndent(source, braceIndex);
+    const first = object.members[0];
+    const firstIndent = first ? lineIndent(source, first.keyStart) : undefined;
+    const indentUnit = firstIndent && firstIndent.length > objectIndent.length
+        ? firstIndent.slice(objectIndent.length) : '  ';
+    const multiline = /[\r\n]/.test(source.slice(braceIndex, object.close));
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    const render = (index, indent) => {
+        const key = formatJson5Key(change.fieldPath[index]);
+        if (index === change.fieldPath.length - 1)
+            return `${key}: ${formatJson5Value(change.value, '')}`;
+        return multiline
+            ? `${key}: {${eol}${indent}${indentUnit}${render(index + 1, indent + indentUnit)},${eol}${indent}}`
+            : `${key}: { ${render(index + 1, indent + indentUnit)} }`;
+    };
+    let tailStart = object.close;
+    while (tailStart > braceIndex + 1 && /\s/.test(source[tailStart - 1]))
+        tailStart -= 1;
+    const last = object.members.at(-1);
+    const insertion = multiline
+        ? `${eol}${objectIndent}${indentUnit}${render(depth, objectIndent + indentUnit)},${eol}${objectIndent}`
+        : `${object.members.length > 0 ? ' ' : ''}${render(depth, objectIndent + indentUnit)}${last?.comma === undefined ? '' : ','}${source.slice(tailStart, object.close)}`;
+    let next = `${source.slice(0, tailStart)}${insertion}${source.slice(object.close)}`;
+    if (last && last.comma === undefined)
+        next = `${next.slice(0, last.value.end)},${next.slice(last.value.end)}`;
+    return next;
+}
+function readJson5Object(source, braceIndex) {
+    if (source[braceIndex] !== '{')
+        throw new ParameterEditError('parameter_document_invalid');
+    const close = balancedEnd(source, braceIndex, source.length) - 1;
+    const members = [];
+    let index = skipTrivia(source, braceIndex + 1, close);
+    while (index < close) {
+        const keyStart = index;
+        let keyEnd;
+        if (source[index] === '"' || source[index] === "'")
+            keyEnd = stringEnd(source, index, close);
+        else {
+            keyEnd = index;
+            while (keyEnd < close && !/[\s:/]/.test(source[keyEnd]))
+                keyEnd += 1;
+        }
+        const key = JSON5.parse(`{${source.slice(index, keyEnd)}: null}`);
+        const name = Object.keys(key)[0];
+        if (members.some((member) => member.name === name))
+            throw new ParameterEditError('parameter_document_invalid');
+        index = skipTrivia(source, keyEnd, close);
+        if (source[index] !== ':')
+            throw new ParameterEditError('parameter_document_invalid');
+        const value = scanValue(source, index + 1, close);
+        index = skipTrivia(source, value.end, close);
+        const comma = source[index] === ',' ? index : undefined;
+        members.push({ name, keyStart, value, comma });
+        if (comma === undefined && index < close)
+            throw new ParameterEditError('parameter_document_invalid');
+        index = skipTrivia(source, comma === undefined ? index : index + 1, close);
+    }
+    return { close, members };
+}
+function lineIndent(source, index) {
+    return source.slice(source.lastIndexOf('\n', index - 1) + 1, index).match(/^[\t ]*/)?.[0] ?? '';
+}
+function formatJson5Key(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
 export function replaceJson5Path(source, fieldPath, value) {
     const span = findJson5ValueSpan(source, fieldPath);
     if (!span)
@@ -17,6 +138,26 @@ export function replaceJson5Path(source, fieldPath, value) {
     }
     return `${source.slice(0, span.start)}${formatJson5Value(value, source.slice(span.start, span.end))}${source.slice(span.end)}`;
 }
+export function replaceJson5Paths(source, changes) {
+    const replacements = changes.map(({ fieldPath, value }) => {
+        const span = findJson5ValueSpan(source, fieldPath);
+        if (!span)
+            throw new ParameterEditError('parameter_field_missing');
+        const current = skipTrivia(source, span.start, span.end);
+        if (source[current] === '{' || source[current] === '[')
+            throw new ParameterEditError('parameter_value_invalid');
+        return { ...span, value: formatJson5Value(value, source.slice(span.start, span.end)) };
+    }).sort((left, right) => right.start - left.start);
+    let next = source;
+    let previousStart = source.length;
+    for (const replacement of replacements) {
+        if (replacement.end > previousStart)
+            throw new ParameterEditError('parameter_changes_overlap');
+        next = `${next.slice(0, replacement.start)}${replacement.value}${next.slice(replacement.end)}`;
+        previousStart = replacement.start;
+    }
+    return next;
+}
 export function findJson5ValueSpan(source, fieldPath) {
     const start = skipTrivia(source, 0, source.length);
     if (source[start] !== '{')
@@ -153,7 +294,9 @@ function formatJson5Value(value, previous) {
     if (typeof value === 'string') {
         const trimmed = previous.trim();
         if (trimmed.startsWith("'")) {
-            return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+            const escaped = value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")
+                .replace(/[\u0000-\u001f\u2028\u2029\ud800-\udfff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+            return `'${escaped}'`;
         }
         return JSON.stringify(value);
     }

package/dist/workspace-runtime/workspaces/operation-log.js

@@ -0,0 +1,23 @@
+import { join } from 'node:path';
+import { AppendOnlyLog } from './append-only-log.js';
+export const OPERATION_LOG_MAX_BYTES = 2 * 1024 * 1024;
+const TRUNCATED = '[playcraft] log truncated; showing the tail\n';
+const OPERATION_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+/** Full build output for one operation, kept outside the checkout and capped at 2 MiB. */
+export class OperationLogStore {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+    }
+    log(operationId) {
+        if (!OPERATION_ID.test(operationId))
+            throw new Error('invalid_operation_id');
+        return new AppendOnlyLog(join(this.stateDir, 'operation-logs', `${operationId}.log`), OPERATION_LOG_MAX_BYTES, TRUNCATED);
+    }
+    async append(operationId, text) {
+        await this.log(operationId).append(text);
+    }
+    async read(operationId, offset = 0) {
+        return this.log(operationId).read(offset);
+    }
+}

package/dist/workspace-runtime/workspaces/parameter-agent-inputs.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+export const parameterDigest = (content) => createHash('sha256').update(content).digest('hex');
+const skippedDirectories = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.vite', '.cache', '.playcraft-editor-preview', '.playcraft-delivery', '.playcraft-temp', 'parameter-admission']);
+const inputExtension = /\.(?:[cm]?[jt]sx?|json5?|ya?ml|html|css|scss|glsl|wgsl|vert|frag|toml)$/i;
+export class ParameterAgentError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'ParameterAgentError';
+    }
+}
+export function parameterInputPath(path) {
+    if (!workspaceRelativePathSchema.safeParse(path).success)
+        return false;
+    const segments = path.split('/');
+    if (segments.some(segment => skippedDirectories.has(segment)))
+        return false;
+    if (segments.some(segment => segment.startsWith('.') && segment !== '.playcraft'))
+        return false;
+    if (segments[0] === '.playcraft' && path !== '.playcraft/workspace.json')
+        return false;
+    if (segments.some(segment => /(?:secret|credential|private[-_.]?key|\.pem$|\.key$)/i.test(segment)))
+        return false;
+    return inputExtension.test(path);
+}
+export async function readParameterAgentFile(root, path, limit = 2 * 1024 * 1024) {
+    const parsed = workspaceRelativePathSchema.safeParse(path);
+    if (!parsed.success)
+        throw new ParameterAgentError('parameter_agent_path_invalid');
+    const base = await realpath(root);
+    let target = base;
+    const segments = parsed.data.split('/');
+    for (let index = 0; index < segments.length; index++) {
+        target = resolve(target, segments[index]);
+        const stat = await lstat(target);
+        if (stat.isSymbolicLink() || (index < segments.length - 1 ? !stat.isDirectory() : !stat.isFile()))
+            throw new ParameterAgentError('parameter_agent_path_invalid');
+        if (index === segments.length - 1 && stat.size > limit)
+            throw new ParameterAgentError('parameter_agent_input_too_large');
+    }
+    const rel = relative(base, await realpath(target));
+    if (rel === '..' || rel.startsWith(`..${sep}`))
+        throw new ParameterAgentError('parameter_agent_path_invalid');
+    const bytes = await readFile(target);
+    if (bytes.byteLength > limit)
+        throw new ParameterAgentError('parameter_agent_input_too_large');
+    return bytes;
+}
+export async function parameterInputSnapshot(root) {
+    const base = await realpath(root);
+    const sources = [];
+    let total = 0;
+    let directories = 0;
+    const walk = async (path, depth) => {
+        if (depth > 24 || ++directories > 4096)
+            throw new ParameterAgentError('parameter_agent_input_limit');
+        const entries = await readdir(resolve(base, path), { withFileTypes: true });
+        if (entries.length > 4096)
+            throw new ParameterAgentError('parameter_agent_input_limit');
+        for (const entry of entries) {
+            const child = path ? `${path}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (skippedDirectories.has(entry.name) || (entry.name.startsWith('.') && entry.name !== '.playcraft'))
+                    continue;
+                if (child.startsWith('.playcraft/'))
+                    continue;
+                await walk(child, depth + 1);
+            }
+            else if (entry.isFile() && parameterInputPath(child)) {
+                const bytes = await readParameterAgentFile(base, child);
+                total += bytes.byteLength;
+                if (total > 32 * 1024 * 1024 || sources.length >= 2048)
+                    throw new ParameterAgentError('parameter_agent_input_limit');
+                sources.push({ path: child, sha256: parameterDigest(bytes) });
+            }
+        }
+    };
+    await walk('', 0);
+    sources.sort((left, right) => left.path.localeCompare(right.path));
+    return { sources, digest: parameterDigest(JSON.stringify(sources)) };
+}

package/dist/workspace-runtime/workspaces/parameter-agent-protocol.js

@@ -0,0 +1,29 @@
+/** Versioned product protocol reference, compiled into the published CLI (Command Line Interface, 命令行接口). */
+export const PARAMETER_AGENT_PROTOCOL = `PlayCraft parameter integration protocol v1
+This is a product configuration reference, not a skill activation. Preserve the current project skill lock and permission/work modes.
+Work only in the current authorized engineering directory. Never edit Remix Editor or a different workspace directory.
+
+Configuration:
+- Reuse existing schema and sparse theme data. .playcraft/workspace.json may declare parameters:{schemaPath,dataPath,themeId}; preserve all unrelated manifest keys. parameters accepts only those three keys.
+- A schema already declares configurable fields. Do not add a parallel xplatform.parameter protocol. Reuse existing field paths and synonymous parameters first.
+- For a new project, create a schema, a sparse data file ({} is valid), matching platform text, and explicit manifest paths. Use gamePlay.preloaded / gamePlay.sections / gamePlay.settlement for the three-screen tree. Preserve existing project paths instead of migrating gratuitously.
+- Object nodes use type:object/properties; leaves declare a supported primitive type and a valid default. Preserve units, known bounds/enum and meaning; do not invent verified limits without code evidence. Basic leaves support string, finite number, integer, boolean and null. Do not add unsupported required/$ref/conditional composition merely for this workflow.
+- Missing theme values inherit schema defaults; editing creates a raw override and restoring defaults removes that override. Never flatten resolved values into theme.data. Preserve comments, unknown data and unrelated overrides.
+- Platform labels use i18n.platform.json5 beside the schema, same tree, with _self.title/description text for zh/en. Preserve xplatform.ext.readonly and xplatform.showIf/showIfAny. Resources (xplatform.value_type:path), multilingual references (i18n), arrays and complex structures retain their semantics; do not disguise them as primitive controls.
+
+Consumption and checks:
+- Modify real game consumers and the neutral configuration resolver, shared by production and preview. A schema-only field or a new getter with no real consumer is incomplete.
+- The development preview runtime is separate from advertising code. Do not route debugging through advertising configuration caches. Production must not depend on the preview runtime.
+- Instant capability requires real field registration and a version-matched preview handshake. Reports cannot declare live capability. A newly integrated field may require one preview build first.
+- Add or extend package.json script test:parameters with meaningful tests of schema/default/sparse overrides and real consumer behavior; changing the requested value must affect its consumer. Preserve an existing test script. Ensure the production build script build exists and succeeds. Optional typecheck is also run by the platform.
+- The platform independently runs only pnpm run test:parameters, pnpm run build, and optional pnpm run typecheck. Reports cannot choose executable commands. Do not replace checks with successful echo statements or self-reported flags.
+- Do not claim a complete production module isolation proof without a trustworthy module report. Passing build/checks proves only their stated coverage.
+
+Report JSON contract (no second copy of parameter values):
+{version:1,taskId:"<exact platform task id>",sources:[{path:"relative/input.ts",sha256:"<current raw-file SHA-256>"}],candidates:[{id:"stable-id",title:"User-facing title",description:"Optional purpose",fieldPath:["gamePlay","sections","board","speed"],origins:[{path:"relative/input.ts",line:1,summary:"Actual origin evidence"}],consumers:[{path:"src/game.ts",line:1,summary:"Actual production consumer and behavior"}],status:"candidate",missing:["Concrete incomplete steps"]}]}
+- Candidate status is exactly candidate, implemented, or blocked. Completed integration candidates use implemented with an empty missing array; discovery keeps candidates unimplemented.
+- Include current file digests for every origin and consumer, and the actual schema/data/platform labels/manifest/check scripts/package and lock files when present. Paths must stay inside the engineering directory. Do not read credentials, dependency trees or build outputs as evidence.
+- Summaries and source snippets are evidence claims, not proof of semantics. The platform checks current files, declared defaults, write support, and independently executed check exits.
+- No passed/ready/live/checks fields are accepted in the report. All implementation and validation statements remain claims until platform verification.
+- If blocked or partial, preserve reviewable changes and list concrete missing work. Do not overwrite later user edits or claim multi-file changes were atomic.
+`;