@playcraft/cli 0.1.69 → 0.1.70

package/dist/workspace-runtime/batch/content-changes.js

@@ -1,8 +1,11 @@
+import { WORKSPACE_REMIX_REFERENCES_DIRECTORY } from '@playcraft/common/cloud-workspace/runtime';
 import { gitRead } from './git.js';
 const reference = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const excludedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'docs', 'test', 'tests', '__tests__']);
 const contentExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|s[ac]ss|less|json5?|ya?ml|xml|glsl|wgsl|vert|frag|lua|py|svg|png|jpe?g|webp|avif|gif|bmp|mp[34]|wav|ogg|m4a|webm|glb|gltf|fbx|obj|bin|atlas|woff2?|ttf|otf)$/i;
 function contentPath(path) {
+    if (path.startsWith(`${WORKSPACE_REMIX_REFERENCES_DIRECTORY}/`))
+        return false;
     const parts = path.split('/');
     if (parts.some(part => part.startsWith('.') || excludedDirectories.has(part)))
         return false;

package/dist/workspace-runtime/batch/generate.js

@@ -100,7 +100,10 @@ export async function generateBatchMember(state, body) {
             const policy = memberExecutionPolicy(root, tempDir);
             await bindMemberPolicy(state, sessionId, policy, { runId: command.runId, ownerFence: command.ownerFence });
             const modelConfigId = command.model && /^[0-9a-f-]{36}$/i.test(command.model) ? command.model : undefined;
-            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) };
+            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}),
+                ...(command.remixReferences?.length ? { context: { files: [], skills: [], remixReferences: command.remixReferences.map(reference => ({
+                            ...reference, directoryName: command.directoryName,
+                        })) } } : {}) };
             const turnKey = operation(state, { kind: 'session.turn', clientRequestId: `batch-turn:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: turnPayload });
             const prior = state.journal.getOperation(turnKey.scopeKey);
             if (prior && prior.payloadHash !== turnKey.record.payloadHash)

package/dist/workspace-runtime/batch/prepare.js

@@ -14,6 +14,7 @@ import { processHasExited, runProcessGroup } from './processes.js';
 import { createInstallLog } from './install-log.js';
 import { stopMemberWriters } from './writer-proof.js';
 import { restoreBatchSkillArtifacts } from './skill-artifacts.js';
+import { rebindBatchRemixReferences } from '../workspaces/remix-references.js';
 import { filesystemObjectStore, memberStatus, readMember, readSnapshot, readStopMarker, serializeRun, sourceCacheDir, writeMember, } from './records.js';
 const BRANCH = /^remix\/draft-[a-f0-9]{16}$/;
 function hashCommand(value) {
@@ -191,11 +192,14 @@ export async function prepareBatchMember(state, body, options) {
                     const commit = command.resumeFromCommit ?? snapshot.commitHash;
                     await checkoutBranch(staging, command.branchName, commit, repositoryUrl);
                     await restoreBatchSkillArtifacts(sourceRoot, staging);
+                    await rebindBatchRemixReferences(staging, snapshot.sourceDirectoryName, command.directoryName, command.remixReferences ?? []);
                     const { rename } = await import('node:fs/promises');
                     await rename(staging, root);
                 }
-                else
+                else {
                     await restoreBatchSkillArtifacts(sourceRoot, root);
+                    await rebindBatchRemixReferences(root, snapshot.sourceDirectoryName, command.directoryName, command.remixReferences ?? []);
+                }
                 await registerWorkspaceDirectory(state, {
                     workspaceId: command.workspaceId,
                     directoryName: command.directoryName,

package/dist/workspace-runtime/batch/source-capture.js

@@ -4,15 +4,19 @@ import { lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from 'n
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { gzip, gunzip } from 'node:zlib';
 import { promisify } from 'node:util';
+import { WORKSPACE_REMIX_REFERENCES_MANIFEST } from '@playcraft/common/cloud-workspace/runtime';
 import { excludeFromGit } from '../workspaces/dependencies.js';
+import { batchReferenceEnvExamples, batchReferenceMetadata } from '../workspaces/remix-references.js';
 import { gitRead, gitWrite } from './git.js';
 const compress = promisify(gzip);
 const decompress = promisify(gunzip);
 const privateNames = new Set(['.git', 'node_modules', '.ssh', '.aws', '.azure', '.gnupg', '.codex', '.npm', '.pnpm-store',
     '.config', '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc', '.git-credentials', 'credentials.json', 'credentials', 'secrets',
     'id_rsa', 'id_ed25519', 'settings.local.json', '.playcraft.json', 'playcraft.config.json', '.playcraft-temp', '.playcraft-preview-out']);
-function included(path) {
-    return !path.split('/').some(name => privateNames.has(name) || /^\.env(?:$|\.)/.test(name) || /\.(?:pem|key|p12|pfx)$/.test(name))
+function included(path, referenceExamples) {
+    const parts = path.split('/');
+    return !parts.some((name, index) => privateNames.has(name) || (/^\.env(?:$|\.)/.test(name) &&
+        !(index === parts.length - 1 && referenceExamples.has(path))) || /\.(?:pem|key|p12|pfx)$/.test(name))
         && !path.startsWith('.playcraft/skills/');
 }
 /** Git keeps only the executable bit, so the digest must not depend on umask or group-write bits. */
@@ -32,10 +36,12 @@ export function digestFiles(files) {
 /** Files Git will accept. Credentials, caches and node_modules are left out. */
 export async function readSourceFiles(root) {
     const source = await realpath(root);
+    const referenceExamples = await batchReferenceEnvExamples(source);
+    const referenceRecords = await batchReferenceMetadata(source);
     const paths = new Set((await gitRead(source, ['ls-files', '--cached', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean));
     const files = new Map();
     for (const path of [...paths].sort()) {
-        if (!included(path))
+        if (!included(path, referenceExamples))
             continue;
         const full = join(source, path);
         const stat = await lstat(full).catch(error => {
@@ -55,6 +61,33 @@ export async function readSourceFiles(root) {
             await handle.close();
         }
     }
+    const manifestFile = files.get(WORKSPACE_REMIX_REFERENCES_MANIFEST);
+    if (manifestFile) {
+        try {
+            const manifest = JSON.parse(manifestFile.body.toString('utf8'));
+            if (manifest?.version === 1 && Array.isArray(manifest.items)) {
+                const withheld = [];
+                for (const record of referenceRecords) {
+                    for (const file of record.files) {
+                        const path = `${record.path}/${file.path}`;
+                        // A damaged reference may make an otherwise allowed example fail verification. That
+                        // is a reference-integrity error, not evidence that a protected path was withheld.
+                        const isExample = /^\.env\.(?:example|sample|template)$/i.test(path.split('/').pop() ?? '');
+                        if (paths.has(path) && !included(path, referenceExamples) &&
+                            (!isExample || !included(path, new Set([path]))) && (await lstat(join(source, path)).catch(() => undefined))?.isFile()) {
+                            withheld.push(record.referenceId);
+                            break;
+                        }
+                    }
+                }
+                delete manifest.batchPolicyWithheldReferenceIds;
+                if (withheld.length)
+                    manifest.batchPolicyWithheldReferenceIds = withheld;
+                files.set(WORKSPACE_REMIX_REFERENCES_MANIFEST, { ...manifestFile, body: Buffer.from(JSON.stringify(manifest)) });
+            }
+        }
+        catch { /* Preserve malformed legacy metadata without letting it block an unrelated batch. */ }
+    }
     return files;
 }
 /** A changing source must not silently lose files from the captured input. */
@@ -99,6 +132,12 @@ export async function captureIndependentSource(source, destination) {
         for (const entry of ['/.playcraft.json', '/playcraft.config.json', '/.playcraft/skills/', '/.playcraft-temp/'])
             await excludeFromGit(staging, entry);
         await gitWrite(staging, ['add', '-A', '.']);
+        // Imported reference files can be tracked in the source despite .gitignore. Preserve only
+        // their filtered staging paths, without changing ignore handling for other source files.
+        for (const path of ['.playcraft/remix-references.json', 'references/remixes']) {
+            if (await lstat(join(staging, path)).catch(() => undefined))
+                await gitWrite(staging, ['add', '--force', '-A', '--', path]);
+        }
         await gitWrite(staging, ['commit', '--allow-empty', '-m', 'Freeze batch source']);
         const commitHash = (await gitWrite(staging, ['rev-parse', 'HEAD'])).trim();
         await rename(staging, destination);

package/dist/workspace-runtime/server/http.js

@@ -201,6 +201,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 remixReferencesVersion: 1,
                 batchSourceFreezeRevision: 2,
                 batchSourcePublicationVersion: 1,
+                batchReferenceContextVersion: 1,
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
                 ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
                 ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),

package/dist/workspace-runtime/verify-artifact.js

@@ -48,6 +48,7 @@ export async function verifyRuntimeArtifact(expectedVersion) {
         assert.equal(identity.runtimeId, config.runtimeId);
         assert.equal(identity.batchSourceFreezeRevision, 2, 'built runtime lacks the required batch source freeze implementation');
         assert.equal(identity.batchSourcePublicationVersion, 1, 'built runtime lacks trusted batch source publication');
+        assert.equal(identity.batchReferenceContextVersion, 1, 'built runtime lacks batch reference context support');
     }
     finally {
         await runtime?.close();
@@ -56,5 +57,5 @@ export async function verifyRuntimeArtifact(expectedVersion) {
 }
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
     await verifyRuntimeArtifact(process.argv[2] ?? '');
-    console.log('Runtime artifact verified: batchSourceFreezeRevision=2, batchSourcePublicationVersion=1');
+    console.log('Runtime artifact verified: batchSourceFreezeRevision=2, batchSourcePublicationVersion=1, batchReferenceContextVersion=1');
 }

package/dist/workspace-runtime/workspaces/remix-references.js

@@ -115,12 +115,18 @@ function validateRecord(record, directoryName) {
         originalFiles.reduce((sum, file) => sum + file.size, 0) > WORKSPACE_REMIX_REFERENCE_MAX_BYTES)
         throw new RemixReferenceError('remix_reference_manifest_invalid');
 }
-async function verifyReference(root, record, directoryName) {
+async function verifyReferenceMetadata(root, record, directoryName, alternateDirectory) {
     validateRecord(record, directoryName);
     const target = await safeDirectory(root, record.path);
     const receipt = JSON.parse((await readFileSafely(target, RECEIPT, MANIFEST_MAX_BYTES)).toString('utf8'));
-    if (JSON.stringify(workspaceRemixReferenceSchema.parse(receipt)) !== JSON.stringify(record))
+    const parsedReceipt = workspaceRemixReferenceSchema.parse(receipt);
+    if (JSON.stringify(parsedReceipt) !== JSON.stringify(record)
+        && (!alternateDirectory || JSON.stringify(parsedReceipt) !== JSON.stringify({ ...record, directoryName: alternateDirectory })))
         throw new RemixReferenceError('remix_reference_changed');
+    return target;
+}
+async function verifyReference(root, record, directoryName, alternateDirectory) {
+    const target = await verifyReferenceMetadata(root, record, directoryName, alternateDirectory);
     if ((await readFileSafely(target, ATTRIBUTES, 256)).toString('utf8') !== SNAPSHOT_ATTRIBUTES)
         throw new RemixReferenceError('remix_reference_changed');
     const expected = new Set([RECEIPT, ATTRIBUTES, ...record.files.map(file => file.path)]);
@@ -144,6 +150,117 @@ async function verifyReference(root, record, directoryName) {
             throw new RemixReferenceError('remix_reference_changed');
     }
 }
+/** Metadata-verified records identify files excluded by the batch source safety policy. */
+export async function batchReferenceMetadata(root) {
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return [];
+    }
+    const verified = [];
+    for (const record of items) {
+        try {
+            await verifyReferenceMetadata(root, record, record.directoryName);
+            verified.push(record);
+        }
+        catch { /* An unrelated invalid reference cannot block source capture. */ }
+    }
+    return verified;
+}
+/** Only verified imported snapshots can retain credential-free .env examples in a batch freeze. */
+export async function batchReferenceEnvExamples(root) {
+    const examples = new Set();
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return examples;
+    }
+    for (const record of items) {
+        const files = record.files.filter(file => /^\.env\.(?:example|sample|template)$/i.test(file.path.split('/').pop() ?? '')
+            && !isCredentialFile(file.sourcePath));
+        if (!files.length)
+            continue;
+        try {
+            await verifyReference(root, record, record.directoryName);
+            for (const file of files)
+                examples.add(`${record.path}/${file.path}`);
+        }
+        catch { /* An unselected damaged reference must not stop freezing the project. */ }
+    }
+    return examples;
+}
+/** Rebind frozen source references inside a member checkout; content and source identities remain immutable. */
+export async function rebindBatchRemixReferences(root, sourceDirectory, memberDirectory, selected) {
+    workspaceDirectoryNameSchema.parse(sourceDirectory);
+    workspaceDirectoryNameSchema.parse(memberDirectory);
+    const rootReal = await realpath(root);
+    let items;
+    try {
+        items = await readManifest(rootReal);
+    }
+    catch (error) {
+        if (!selected.length)
+            return;
+        throw error;
+    }
+    for (const reference of selected) {
+        const record = items.find(item => item.referenceId === reference.referenceId);
+        if (reference.directoryName !== sourceDirectory || !record || record.contentHash !== reference.snapshotHash)
+            throw new RemixReferenceError('context_remix_reference_changed');
+    }
+    if (selected.length) {
+        const manifest = JSON.parse((await readFileSafely(rootReal, WORKSPACE_REMIX_REFERENCES_MANIFEST, MANIFEST_MAX_BYTES)).toString('utf8'));
+        if (Array.isArray(manifest.batchPolicyWithheldReferenceIds) && selected.some(reference => manifest.batchPolicyWithheldReferenceIds.includes(reference.referenceId)))
+            throw new RemixReferenceError('batch_reference_files_withheld');
+    }
+    // Selected references must be complete. Other records need only valid metadata to be rebound;
+    // their contents remain subject to the normal checks when the user later lists or selects them.
+    const rebound = [];
+    const writable = [];
+    for (const record of items) {
+        const isSelected = selected.some(reference => reference.referenceId === record.referenceId);
+        try {
+            if (record.directoryName !== sourceDirectory && record.directoryName !== memberDirectory)
+                throw new RemixReferenceError('remix_reference_manifest_invalid');
+            const alternate = record.directoryName === sourceDirectory ? memberDirectory : sourceDirectory;
+            if (isSelected)
+                await verifyReference(rootReal, record, record.directoryName, alternate);
+            else
+                await verifyReferenceMetadata(rootReal, record, record.directoryName, alternate);
+            const next = { ...record, directoryName: memberDirectory };
+            rebound.push(next);
+            writable.push(next);
+        }
+        catch (error) {
+            if (isSelected)
+                throw error;
+            rebound.push(record);
+        }
+    }
+    if (!items.length)
+        return;
+    const metadata = await safeDirectory(rootReal, '.playcraft');
+    const atomicWrite = async (destination, body) => {
+        const temporary = join(metadata, `.batch-reference-${randomUUID()}.tmp`);
+        try {
+            // shared
+            await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    };
+    for (const record of writable) {
+        const target = await safeDirectory(rootReal, record.path);
+        await atomicWrite(join(target, RECEIPT), JSON.stringify(record));
+    }
+    await atomicWrite(join(metadata, 'remix-references.json'), JSON.stringify({ version: 1, items: rebound }));
+}
 /** Reads revalidate the snapshot, so changed/deleted files cannot silently remain attached to a turn. */
 export async function listWorkspaceRemixReferences(root, directoryName = 'basic') {
     workspaceDirectoryNameSchema.parse(directoryName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.69",
+  "version": "0.1.70",
   "private": false,
   "type": "module",
   "engines": {
@@ -56,8 +56,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.69",
-    "@playcraft/common": "0.1.69",
+    "@playcraft/build": "0.1.70",
+    "@playcraft/common": "0.1.70",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",