@playcraft/cli 0.1.57-beta → 0.1.59-beta

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

@@ -33,6 +33,42 @@ export function editJson5Paths(source, changes) {
     JSON5.parse(next);
     return next;
 }
+/** Replace complete language records while preserving every unrelated authored member. */
+export function editJson5StringRecords(source, changes) {
+    const parsed = JSON5.parse(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new ParameterEditError('parameter_document_invalid');
+    if (new Set(changes.map(change => change.key)).size !== changes.length)
+        throw new ParameterEditError('parameter_changes_overlap');
+    let next = source;
+    for (const change of changes) {
+        if (!change.key || ['__proto__', 'prototype', 'constructor'].includes(change.key))
+            throw new ParameterEditError('parameter_value_invalid');
+        const object = readJson5Object(next, skipTrivia(next, 0, next.length));
+        const memberIndex = object.members.findIndex(member => member.name === change.key);
+        const member = object.members[memberIndex];
+        if ('op' in change) {
+            if (!member)
+                continue;
+            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);
+            for (const span of spans)
+                next = next.slice(0, span.start) + next.slice(span.end);
+        }
+        else {
+            if (!change.value || typeof change.value !== 'object' || Array.isArray(change.value) || Object.values(change.value).some(value => typeof value !== 'string'))
+                throw new ParameterEditError('parameter_value_invalid');
+            if (!member)
+                next = editJson5Paths(next, [{ fieldPath: [change.key], value: '' }]);
+            const span = findJson5ValueSpan(next, [change.key]);
+            if (!span)
+                throw new ParameterEditError('parameter_field_missing');
+            next = next.slice(0, span.start) + JSON.stringify(change.value) + next.slice(span.end);
+        }
+    }
+    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]);

package/dist/workspace-runtime/workspaces/library-attachments.js

@@ -11,6 +11,7 @@ async function safeDirectory(root, path, create = false) {
     let directory = root;
     for (const part of path.split('/').filter(Boolean)) {
         directory = join(directory, part);
+        // shared
         if (create)
             await mkdir(directory, { mode: 0o755 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -173,12 +174,14 @@ async function importAttachment(root, body) {
     if (!record) {
         const temporary = join(uploads, `.import-${randomUUID()}`);
         const target = join(uploads, id);
+        // shared
         await mkdir(temporary, { mode: 0o755 });
         try {
             for (const file of files) {
                 const parent = dirname(file.path);
                 if (parent !== '.')
                     await safeDirectory(temporary, parent, true);
+                // shared
                 await writeFile(join(temporary, file.path), file.bytes, { flag: 'wx', mode: 0o644 });
             }
             const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}`;
@@ -236,6 +239,7 @@ async function importAttachment(root, body) {
     record.clientRequestIds = [...new Set([...record.clientRequestIds, clientRequestId])];
     record.unbound ||= !sessionId;
     const tempMetadata = join(metadata, `.import-${randomUUID()}.json`);
+    // shared
     await writeFile(tempMetadata, JSON.stringify(record), { flag: 'wx', mode: 0o644 });
     await rename(tempMetadata, join(metadata, `${id}.json`));
     await chmod(join(uploads, id), 0o755);

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

@@ -38,3 +38,5 @@ Report JSON (JavaScript Object Notation, JavaScript 对象表示法) contract (n
 - 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.
 `;
+/** Initialization strategy comes from the locked skill; report validation stays platform-owned. */
+export const PARAMETER_AGENT_REPORT_PROTOCOL = PARAMETER_AGENT_PROTOCOL.slice(PARAMETER_AGENT_PROTOCOL.indexOf('Report JSON'));

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

@@ -17,6 +17,7 @@ async function taskDirectory(state, workspaceId, directoryName, root) {
     }
     const scope = [state.config.environment, state.config.userId, state.config.runtimeId, workspaceId, directoryName];
     const directory = join(parent, parameterDigest(JSON.stringify(scope)));
+    // private
     await mkdir(directory, { recursive: true, mode: 0o700 });
     if ((await lstat(parent)).isSymbolicLink() || (await lstat(directory)).isSymbolicLink())
         throw new ParameterAgentError('parameter_agent_state_invalid');
@@ -47,6 +48,7 @@ export async function writePrivateParameterTask(state, task, root) {
     const directory = await taskDirectory(state, task.record.workspaceId, task.record.directoryName, root);
     const record = parameterAgentTaskRecordSchema.parse(task.record);
     const temporary = join(directory, `.${record.taskId}.${randomUUID()}.tmp`);
+    // private
     await writeFile(temporary, JSON.stringify({ ...task, record }), { mode: 0o600 });
     await rename(temporary, join(directory, `${record.taskId}.json`));
 }

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

@@ -1,9 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { parameterAgentReportSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, parameterCatalog, stableStringify, validateParameterChange, } from '@playcraft/common/cloud-workspace/runtime';
+import { parameterAgentReportSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, parameterI18nCatalog, stableStringify, validateParameterChange, validateParameterI18nChange, } from '@playcraft/common/cloud-workspace/runtime';
 import { readWorkspaceParameters } from './parameters.js';
 import { revisionScope } from './registry.js';
 import { runDeveloperCommand } from './developer-command.js';
-import { PARAMETER_AGENT_PROTOCOL } from './parameter-agent-protocol.js';
+import { PARAMETER_AGENT_PROTOCOL, PARAMETER_AGENT_REPORT_PROTOCOL } from './parameter-agent-protocol.js';
+import { inspectParameterInitialization } from './parameter-initialization.js';
+import { inspectParameterProductionCheck, prepareParameterProductionCheck } from './parameter-production.js';
 import { ParameterAgentError, parameterDigest, parameterInputSnapshot, readParameterAgentFile } from './parameter-agent-inputs.js';
 import { listPrivateParameterTaskIds, parameterTaskWorkspace, readPrivateParameterTask, writePrivateParameterTask } from './parameter-agent-store.js';
 export { ParameterAgentError } from './parameter-agent-inputs.js';
@@ -58,14 +60,19 @@ async function inspectReport(root, task, snapshot) {
     }
     return report;
 }
-export async function prepareParameterAgentTask(state, operation, value, root) {
+export async function prepareParameterAgentTask(state, operation, value, root, options = {}) {
     const request = parameterAgentTaskRequestSchema.parse(value);
     if (operation.kind !== 'session.turn' || operation.clientRequestId !== request.taskId)
         throw new ParameterAgentError('parameter_agent_task_identity_invalid');
     const owner = scope(state, operation);
+    const skill = request.action === 'initialize' ? options.initializationSkill : undefined;
+    if (request.action === 'initialize' && (!skill || !skill.entryKey || !/^[a-f0-9]{64}$/.test(skill.lockHash) || !skill.path))
+        throw new ParameterAgentError('parameter_initialization_skill_unavailable');
     const existing = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, request.taskId, root);
     if (existing && (existing.record.sessionId !== owner.sessionId || !current(state, existing) || stableStringify(existing.request) !== stableStringify(request)))
         throw new ParameterAgentError('parameter_agent_task_conflict');
+    if (existing && skill && (existing.record.initializationSkill?.entryKey !== skill.entryKey || existing.record.initializationSkill.lockHash !== skill.lockHash))
+        throw new ParameterAgentError('parameter_initialization_skill_changed');
     const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
     if (request.sourceFingerprint && request.sourceFingerprint !== document.sourceFingerprint)
         throw new ParameterAgentError('parameter_source_conflict');
@@ -84,7 +91,7 @@ export async function prepareParameterAgentTask(state, operation, value, root) {
     const timestamp = now();
     const task = existing ?? {
         request, initialDigest: initial.digest, instanceToken: state.instanceToken,
-        record: { version: 1, taskId: request.taskId, action: request.action, ...(request.goal ? { goal: request.goal } : {}), ...owner, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, status: 'running', reportPath: reportPath(request.taskId), checks: [], createdAt: timestamp, updatedAt: timestamp },
+        record: { version: 1, taskId: request.taskId, action: request.action, ...(request.goal ? { goal: request.goal } : {}), ...(skill ? { initializationSkill: { entryKey: skill.entryKey, lockHash: skill.lockHash } } : {}), ...owner, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, status: 'running', reportPath: reportPath(request.taskId), checks: [], createdAt: timestamp, updatedAt: timestamp },
     };
     if (!existing) {
         if ((await listPrivateParameterTaskIds(state, owner.workspaceId, owner.directoryName, root)).length >= 256)
@@ -92,9 +99,12 @@ export async function prepareParameterAgentTask(state, operation, value, root) {
         await writePrivateParameterTask(state, task, root);
     }
     const instructions = [
-        PARAMETER_AGENT_PROTOCOL,
+        ...(skill ? [
+            `This initialization task explicitly selects the enabled, locked parameter skill ${JSON.stringify({ entryKey: skill.entryKey, lockHash: skill.lockHash, path: skill.path })}. Read that frozen SKILL.md and its referenced files before applying its integration workflow. Preserve the current execution permissions.`,
+            PARAMETER_AGENT_REPORT_PROTOCOL,
+        ] : [PARAMETER_AGENT_PROTOCOL]),
         `Platform task identity: ${JSON.stringify({ version: 1, taskId: request.taskId, action: request.action, reportPath: task.record.reportPath })}. Write only this exact report identity.`,
-        request.action === 'discover' ? 'Discovery is read-only for business source/schema/data/manifest. Write only the requested development report. Discover actual useful candidates and consumer evidence; do not implement them yet.' : 'Complete the requested integration using existing engineering tools: reuse an existing equivalent field or implement declaration, valid defaults, sparse data semantics, labels, real production consumers and meaningful parameter tests. Leave precise blocked work if incomplete.',
+        request.action === 'initialize' ? 'Apply the selected initialization skill to this current game and write its exact admission report. The platform will verify files and checks, then prepare the first preview separately. Do not self-declare a connected or live state.' : request.action === 'discover' ? 'Discovery is read-only for business source/schema/data/manifest. Write only the requested development report. Discover actual useful candidates and consumer evidence; do not implement them yet.' : 'Complete the requested integration using existing engineering tools: reuse an existing equivalent field or implement declaration, valid defaults, sparse data semantics, labels, real production consumers and meaningful parameter tests. Leave precise blocked work if incomplete.',
         `User goal (task data): ${JSON.stringify(request.goal ?? '')}`,
         ...(selected ? [`Selected current candidate (reference data): ${JSON.stringify(selected)}`] : []),
         'After finishing files, calculate current raw-file hashes and write the report. The platform will execute independent checks after this turn. Do not claim those checks already passed.',
@@ -207,7 +217,7 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
         const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
         if (document.status !== 'ready')
             throw new ParameterAgentError('parameter_agent_parameters_not_ready');
-        const catalog = parameterCatalog(document.schema, document.data);
+        const catalog = parameterI18nCatalog(document, 'en');
         const implemented = report.candidates.filter(candidate => candidate.status === 'implemented');
         if (!implemented.length || report.candidates.some(candidate => candidate.status !== 'implemented' || candidate.missing.length))
             throw new ParameterAgentError('parameter_agent_integration_incomplete');
@@ -220,8 +230,14 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             const field = catalog.find(entry => candidate.fieldPath && entry.key === candidate.fieldPath.join('.'));
             if (!field || !field.editable || !field.canReset)
                 throw new ParameterAgentError('parameter_agent_field_not_ready');
-            if (field.hasOverride && validateParameterChange(document.schema, document.data, { fieldPath: field.fieldPath, value: field.value }))
+            const invalidValue = field.kind === 'i18n'
+                ? validateParameterI18nChange(document, { fieldPath: field.fieldPath, locale: 'en', value: String(field.value ?? '') })
+                : field.hasOverride && validateParameterChange(document.schema, document.data, { fieldPath: field.fieldPath, value: field.value });
+            if (invalidValue)
                 throw new ParameterAgentError('parameter_agent_field_not_ready');
+            if (field.kind === 'i18n' && document.runtimeI18n &&
+                (!evidence.has(document.runtimeI18n.globalPath) || (document.runtimeI18n.themeHash && !evidence.has(document.runtimeI18n.themePath))))
+                throw new ParameterAgentError('parameter_agent_evidence_missing');
             if (!candidate.consumers.length)
                 throw new ParameterAgentError('parameter_agent_consumer_missing');
         }
@@ -230,11 +246,17 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             if (typeof packageData.scripts?.[script] !== 'string' || !packageData.scripts[script].trim())
                 throw new ParameterAgentError('parameter_agent_check_script_missing');
         }
+        const initialization = task.request.action === 'initialize'
+            ? await inspectParameterInitialization(root, document, report) : undefined;
         task.instanceToken = state.instanceToken;
-        await update(state, task, { status: 'checking', checks: [], error: undefined, receiptId: undefined, sourceDigest: before.digest }, root);
+        await update(state, task, { status: 'checking', checks: [], error: undefined, receiptId: undefined, productionCheck: undefined, sourceDigest: before.digest }, root);
         const scripts = ['test:parameters', 'build', ...(typeof packageData.scripts?.typecheck === 'string' ? ['typecheck'] : [])];
+        let productionPlan;
+        let productionEvidence;
         for (const script of scripts) {
             assertActive();
+            if (initialization && script === 'build')
+                productionPlan = await prepareParameterProductionCheck(root);
             const controller = new AbortController();
             const abort = () => controller.abort();
             options.signal?.addEventListener('abort', abort, { once: true });
@@ -269,16 +291,23 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             await writePrivateParameterTask(state, task, root);
             if (outcome.code !== 0 || outcome.timedOut || outcome.canceled)
                 throw new ParameterAgentError(outcome.timedOut ? 'parameter_agent_check_timeout' : outcome.canceled ? 'parameter_agent_check_canceled' : 'parameter_agent_check_failed');
+            if (productionPlan && script === 'build')
+                productionEvidence = await inspectParameterProductionCheck(productionPlan, assertActive);
         }
         assertActive();
         const after = await parameterInputSnapshot(root);
         if (after.digest !== before.digest || parameterDigest(await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024)) !== task.reportHash)
             throw new ParameterAgentError('parameter_agent_inputs_changed');
-        return update(state, task, { status: 'verified', sourceDigest: after.digest, receiptId: randomUUID(), error: undefined }, root);
+        if (initialization && initialization !== await inspectParameterInitialization(root, document, report))
+            throw new ParameterAgentError('parameter_agent_inputs_changed');
+        if (productionPlan && stableStringify(productionEvidence) !== stableStringify(await inspectParameterProductionCheck(productionPlan, assertActive)))
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        return update(state, task, { status: 'verified', sourceDigest: after.digest, receiptId: randomUUID(), error: undefined,
+            ...(productionEvidence ? { productionCheck: { ...productionEvidence, checkedAt: now() } } : {}) }, root);
     }
     catch (cause) {
         const code = errorCode(cause);
         const status = code === 'ENOENT' ? 'missing' : /stale|changed|expired/.test(code) ? 'stale' : /(?:not_ready|incomplete|consumer_missing|script_missing|evidence_missing)$/.test(code) ? 'needs-verification' : /report_|evidence_invalid|path_invalid/.test(code) ? 'invalid' : 'failed';
-        return update(state, task, { status, error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code, receiptId: undefined }, root);
+        return update(state, task, { status, error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code, receiptId: undefined, productionCheck: undefined }, root);
     }
 }

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

@@ -159,6 +159,7 @@ export async function writeParameterAssetRegistration(root, plan) {
             throw new ParameterAssetError('parameter_asset_index_conflict');
         const parent = await lstat(dirname(target));
         const bytes = Buffer.from(plan.content);
+        // private
         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);

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

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+const ownerSchema = z.object({ kind: z.literal('playcraft.parameter-skill.v1'), pid: z.number().int().positive(), token: z.string().uuid() }).strict();
+export const PARAMETER_SKILL_TRANSACTION = 'parameter-initialization-skill.transaction.json';
+const transactionSchema = z.object({ version: z.literal(1), owner: ownerSchema,
+    templateHash: z.string().regex(/^[a-f0-9]{64}$/), artifactHash: z.string().regex(/^[a-f0-9]{64}$/), sourceAdded: z.boolean(),
+    originalDeclaration: z.string().nullable(), originalLock: z.string().nullable(),
+    nextDeclaration: z.string(), nextLock: z.string(),
+}).strict();
+export async function readParameterSkillTransactionFile(path, maximum = 8 * 1024 * 1024) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > maximum)
+            throw new Error('workspace_skills_parameter_recovery_conflict');
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function parseOwner(bytes) {
+    try {
+        return ownerSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch {
+        throw Object.assign(new Error('workspace_skills_parameter_recovery_conflict'), { code: 'EEXIST' });
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function removeExact(path, expected) {
+    const current = await readParameterSkillTransactionFile(path);
+    if (current === undefined || !current.equals(expected))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    await rm(path);
+}
+/** Each dead recovery owner has its own exclusive successor, avoiding an unchecked lease takeover. */
+async function recoveryClaim(management, previous, claims, depth = 0) {
+    if (depth > 32)
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const path = join(management, `parameter-initialization-${previous.token}.recovery.lock`);
+    const owner = { kind: 'playcraft.parameter-skill.v1', pid: process.pid, token: randomUUID() };
+    const bytes = Buffer.from(JSON.stringify(owner));
+    // private: lease identities and crash recovery records belong to the controller.
+    try {
+        await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+        claims.push({ path, bytes });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const existing = await readParameterSkillTransactionFile(path, 4096);
+        if (!existing)
+            throw error;
+        const held = parseOwner(existing);
+        if (alive(held.pid))
+            throw error;
+        claims.push({ path, bytes: existing });
+        await recoveryClaim(management, held, claims, depth + 1);
+    }
+}
+export async function acquireParameterSkillLease(management, recover) {
+    const path = join(management, 'skills-write.lock');
+    const owner = { kind: 'playcraft.parameter-skill.v1', pid: process.pid, token: randomUUID() };
+    const bytes = Buffer.from(JSON.stringify(owner));
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            // private
+            await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+            return { owner, release: () => removeExact(path, bytes) };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const previousBytes = await readParameterSkillTransactionFile(path, 4096);
+            if (!previousBytes)
+                throw error;
+            const previous = parseOwner(previousBytes);
+            if (alive(previous.pid))
+                throw error;
+            const claims = [];
+            let claimed = false;
+            try {
+                await recoveryClaim(management, previous, claims);
+                claimed = true;
+                const current = await readParameterSkillTransactionFile(path, 4096);
+                if (!current?.equals(previousBytes) || alive(previous.pid))
+                    throw new Error('workspace_skills_parameter_recovery_conflict');
+                const marker = join(management, PARAMETER_SKILL_TRANSACTION);
+                const transactionBytes = await readParameterSkillTransactionFile(marker);
+                if (transactionBytes) {
+                    let transaction;
+                    try {
+                        transaction = transactionSchema.parse(JSON.parse(transactionBytes.toString('utf8')));
+                    }
+                    catch {
+                        throw new Error('workspace_skills_parameter_recovery_conflict');
+                    }
+                    if (transaction.owner.pid !== previous.pid || transaction.owner.token !== previous.token)
+                        throw new Error('workspace_skills_parameter_recovery_conflict');
+                    await recover(transaction);
+                    await removeExact(marker, transactionBytes);
+                }
+                await removeExact(path, previousBytes);
+            }
+            finally {
+                if (claimed)
+                    for (const claim of claims.reverse())
+                        await removeExact(claim.path, claim.bytes);
+            }
+        }
+    }
+    throw new Error('workspace_skills_parameter_recovery_conflict');
+}
+export async function writeParameterSkillTransaction(management, transaction) {
+    const path = join(management, PARAMETER_SKILL_TRANSACTION);
+    const bytes = Buffer.from(JSON.stringify(transactionSchema.parse(transaction)));
+    if (await readParameterSkillTransactionFile(path))
+        throw new Error('workspace_skills_parameter_recovery_conflict');
+    const temporary = `${path}.${transaction.owner.token}.tmp`;
+    try {
+        // private
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return () => removeExact(path, bytes);
+}