@playcraft/cli 0.1.71 → 0.1.72

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

@@ -4,20 +4,47 @@ 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 { WORKSPACE_REMIX_REFERENCES_MANIFEST, starterTemplateTreeHashInput, remixReferenceContentHashInput, workspaceStarterTemplateSnapshotSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { excludeFromGit } from '../workspaces/dependencies.js';
-import { batchReferenceEnvExamples, batchReferenceMetadata } from '../workspaces/remix-references.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']);
+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, 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/') && !path.startsWith('.playcraft/skill-selections/');
+    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/') &&
+        !path.startsWith('.playcraft/skill-selections/'));
 }
 /** Git keeps only the executable bit, so the digest must not depend on umask or group-write bits. */
 function snapshotMode(mode) {
@@ -30,7 +57,13 @@ function inside(root, path) {
 export function digestFiles(files) {
     const hash = createHash('sha256');
     for (const [path, file] of files)
-        hash.update(path).update('\0').update(String(file.mode)).update('\0').update(file.body).update('\0');
+        hash
+            .update(path)
+            .update('\0')
+            .update(String(file.mode))
+            .update('\0')
+            .update(file.body)
+            .update('\0');
     return hash.digest('hex');
 }
 /** Files Git will accept. Credentials, caches and node_modules are left out. */
@@ -38,13 +71,15 @@ 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 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, referenceExamples))
             continue;
         const full = join(source, path);
-        const stat = await lstat(full).catch(error => {
+        const stat = await lstat(full).catch((error) => {
             if (error.code === 'ENOENT')
                 return undefined;
             throw error;
@@ -73,8 +108,10 @@ export async function readSourceFiles(root) {
                         // 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()) {
+                        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;
                         }
@@ -83,10 +120,15 @@ export async function readSourceFiles(root) {
                 delete manifest.batchPolicyWithheldReferenceIds;
                 if (withheld.length)
                     manifest.batchPolicyWithheldReferenceIds = withheld;
-                files.set(WORKSPACE_REMIX_REFERENCES_MANIFEST, { ...manifestFile, body: Buffer.from(JSON.stringify(manifest)) });
+                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. */ }
+        catch {
+            /* Preserve malformed legacy metadata without letting it block an unrelated batch. */
+        }
     }
     return files;
 }
@@ -102,8 +144,121 @@ export async function filterUnstableFiles(root, files) {
     }
     return files;
 }
+const scaffoldFiles = new Set([
+    'AGENTS.md',
+    '.gitignore',
+    '.playcraft/skills.json',
+    '.playcraft/skills.lock.json',
+    '.playcraft/workspace-context.json',
+    '.playcraft/workspace.json',
+    WORKSPACE_REMIX_REFERENCES_MANIFEST,
+]);
+const scaffoldDirectories = [
+    '.agents/skills/',
+    '.playcraft/skills/',
+    '.playcraft/skill-artifacts/',
+    '.playcraft/skill-migrations/',
+    '.playcraft/skill-selections/',
+    'references/remixes/',
+];
+const ignoredDirectories = [
+    'node_modules/',
+    'dist/',
+    'dist-all/',
+    'coverage/',
+    '.playcraft-preview-out/',
+    '.playcraft-temp/',
+    '.tmp/',
+    '.temp/',
+    '.git/',
+    '.vscode/',
+    '.idea/',
+];
+function scaffoldPath(path) {
+    return scaffoldFiles.has(path) || scaffoldDirectories.some((prefix) => path.startsWith(prefix));
+}
+async function inspectSource(root, files) {
+    // Inspect ignored paths too: a user's .gitignore may otherwise hide a real project.
+    const ignored = (await gitRead(root, [
+        'ls-files',
+        '--others',
+        '--ignored',
+        '--exclude-standard',
+        '--directory',
+        '-z',
+    ]))
+        .split('\0')
+        .filter(Boolean);
+    const safeIgnored = ignored.every((path) => scaffoldPath(path) ||
+        ignoredDirectories.some((prefix) => path === prefix || path.startsWith(prefix)) ||
+        !included(path, new Set()) ||
+        /(?:^|\/)(?:\.DS_Store|Thumbs\.db)$/.test(path) ||
+        /\.(?:log|tmp)$/.test(path));
+    return {
+        empty: [...files.keys()].every(scaffoldPath),
+        safeIgnored,
+        ignoredDigest: createHash('sha256').update(JSON.stringify(ignored.sort())).digest('hex'),
+    };
+}
+/** Merge only the trusted engine files. Workspace instructions, skills, references and configuration remain authoritative. */
+export function mergeStarterTemplate(files, template) {
+    if ('error' in template)
+        throw new Error(template.error);
+    const result = workspaceStarterTemplateSnapshotSchema.safeParse(template.snapshot);
+    if (!result.success)
+        throw new Error('starter_template_invalid');
+    const snapshot = result.data;
+    if (createHash('sha256').update(remixReferenceContentHashInput(snapshot.files)).digest('hex') !==
+        snapshot.contentHash)
+        throw new Error('starter_template_invalid');
+    if (createHash('sha256').update(starterTemplateTreeHashInput(snapshot.files)).digest('hex') !==
+        template.treeHash)
+        throw new Error('starter_template_invalid');
+    const sourcePaths = new Set([...files.keys()].map((path) => path.toLowerCase()));
+    const added = [];
+    for (const file of snapshot.files) {
+        const { path } = file;
+        const mode = file.mode;
+        if (mode !== '100644' && mode !== '100755')
+            throw new Error('starter_template_invalid');
+        const body = Buffer.from(file.content, 'base64');
+        if (body.toString('base64') !== file.content ||
+            body.length !== file.size ||
+            createHash('sha256').update(body).digest('hex') !== file.sha256 ||
+            body
+                .subarray(0, 128)
+                .toString('utf8')
+                .startsWith('version https://git-lfs.github.com/spec/v1'))
+            throw new Error('starter_template_invalid');
+        const parts = path.split('/');
+        if (path === 'AGENTS.md' ||
+            parts[0] === '.claude' ||
+            parts[0] === '.agents' ||
+            parts[0] === '.playcraft' ||
+            parts[0] === 'references' ||
+            !included(path, new Set()))
+            continue;
+        if (path === '.gitignore' && files.has(path)) {
+            files.set(path, {
+                body: Buffer.concat([files.get(path).body, Buffer.from('\n'), body]),
+                mode: 0o644,
+            });
+            continue;
+        }
+        if (sourcePaths.has(path.toLowerCase()) ||
+            [...sourcePaths].some((existing) => existing.startsWith(`${path.toLowerCase()}/`) ||
+                path.toLowerCase().startsWith(`${existing}/`)))
+            throw new Error('starter_template_path_conflict');
+        files.set(path, { body, mode: mode === '100755' ? 0o755 : 0o644 });
+        sourcePaths.add(path.toLowerCase());
+        added.push(path);
+    }
+    if (!added.length)
+        throw new Error('starter_template_invalid');
+    return added;
+}
 /** Independent root commit. The source branch, index and config are never written. */
-export async function captureIndependentSource(source, destination) {
+export async function captureIndependentSource(source, destination, starterTemplate, identity) {
     const root = await realpath(source);
     if (await lstat(destination).catch(() => undefined))
         throw new Error('batch_source_destination_exists');
@@ -111,6 +266,56 @@ export async function captureIndependentSource(source, destination) {
     let files = await readSourceFiles(root);
     files = await filterUnstableFiles(root, files);
     const contentDigest = digestFiles(files);
+    const inspection = starterTemplate ? await inspectSource(root, files) : undefined;
+    const probePath = `${destination}.template-probe`;
+    const probe = identity && inspection
+        ? JSON.stringify({
+            version: 1,
+            identity,
+            root,
+            head: headBefore,
+            contentDigest,
+            ignoredDigest: inspection.ignoredDigest,
+        })
+        : undefined;
+    const existingProbe = await readFile(probePath, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (identity && starterTemplate && 'snapshot' in starterTemplate && !existingProbe)
+        throw new Error('batch_source_candidate_lost');
+    if (existingProbe && (!probe || existingProbe !== probe))
+        throw new Error('batch_source_changed');
+    if (inspection && !inspection.safeIgnored)
+        throw new Error('batch_source_ignored_files');
+    if (starterTemplate && inspection?.empty && 'error' in starterTemplate && probe) {
+        if (headBefore !== (await gitRead(root, ['rev-parse', '--verify', 'HEAD']).catch(() => '')) ||
+            digestFiles(await filterUnstableFiles(root, await readSourceFiles(root))) !== contentDigest ||
+            (await inspectSource(root, files)).ignoredDigest !== inspection.ignoredDigest)
+            throw new Error('batch_source_changed');
+        if (!existingProbe) {
+            // private
+            await mkdir(dirname(probePath), { recursive: true, mode: 0o700 });
+            // private
+            const handle = await open(probePath, 'wx', 0o600);
+            try {
+                await handle.writeFile(probe);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            const directory = await open(dirname(probePath), 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+    }
+    const templatePaths = starterTemplate && inspection?.empty ? mergeStarterTemplate(files, starterTemplate) : [];
     const staging = join(dirname(destination), `.batch-source-${randomUUID()}`);
     try {
         await mkdir(staging, { recursive: true });
@@ -122,16 +327,35 @@ export async function captureIndependentSource(source, destination) {
             await mkdir(dirname(full), { recursive: true });
             await writeFile(full, file.body, { mode: file.mode, flag: 'wx' });
         }
-        if (headBefore !== await gitRead(root, ['rev-parse', '--verify', 'HEAD']).catch(() => ''))
+        if (headBefore !== (await gitRead(root, ['rev-parse', '--verify', 'HEAD']).catch(() => '')))
             throw new Error('batch_source_changed');
         const after = await filterUnstableFiles(root, await readSourceFiles(root));
         if (digestFiles(after) !== contentDigest)
             throw new Error('batch_source_changed');
+        if (inspection) {
+            const last = await inspectSource(root, after);
+            if (last.empty !== inspection.empty || last.ignoredDigest !== inspection.ignoredDigest)
+                throw new Error('batch_source_changed');
+        }
         await excludeFromGit(staging);
         await excludeFromGit(staging, '/.env*');
-        for (const entry of ['/.playcraft.json', '/playcraft.config.json', '/.playcraft/skills/', '/.playcraft-temp/'])
+        for (const entry of [
+            '/.playcraft.json',
+            '/playcraft.config.json',
+            '/.playcraft/skills/',
+            '/.playcraft-temp/',
+        ])
             await excludeFromGit(staging, entry);
         await gitWrite(staging, ['add', '-A', '.']);
+        // The template owns its source files even when its ignore rules exclude them.
+        for (let i = 0; i < templatePaths.length; i += 100)
+            await gitWrite(staging, [
+                '--literal-pathspecs',
+                'add',
+                '--force',
+                '--',
+                ...templatePaths.slice(i, i + 100),
+            ]);
         // 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']) {
@@ -151,7 +375,11 @@ export async function archiveSource(root, meta) {
     const bundle = join(dirname(root), `.bundle-${randomUUID()}`);
     try {
         await gitWrite(root, ['bundle', 'create', bundle, 'HEAD']);
-        const body = JSON.stringify({ version: 1, ...meta, bundle: (await readFile(bundle)).toString('base64') });
+        const body = JSON.stringify({
+            version: 1,
+            ...meta,
+            bundle: (await readFile(bundle)).toString('base64'),
+        });
         return await compress(Buffer.from(body));
     }
     finally {
@@ -160,7 +388,10 @@ export async function archiveSource(root, meta) {
 }
 export async function restoreArchive(body, destination, expectedDigest) {
     const archive = JSON.parse((await decompress(body, { maxOutputLength: 512 * 1024 * 1024 })).toString());
-    if (archive.version !== 1 || archive.digest !== expectedDigest || !archive.commitHash || !archive.bundle)
+    if (archive.version !== 1 ||
+        archive.digest !== expectedDigest ||
+        !archive.commitHash ||
+        !archive.bundle)
         throw new Error('batch_snapshot_mismatch');
     const temporary = join(dirname(destination), `.bundle-${randomUUID()}`);
     await mkdir(temporary, { recursive: true });

package/dist/workspace-runtime/codex/app-server.js

@@ -31,6 +31,9 @@ function withModelShell(config, modelConfigId) {
     return { ...config, 'shell_environment_policy.set': { ...existing, PLAYCRAFT_MODEL_CONFIG_ID: modelConfigId } };
 }
 const ENGINEERING_BATCH_INSTRUCTIONS = [
+    'For a single replica, work directly in the current repository and preserve the user-provided references. Do not create a batch for a single replica.',
+    'If the repository is empty, initialize it using the default starter template before implementing the replica; preserve existing workspace metadata and files. If the template is unavailable, report the failure instead of substituting another template.',
+    'A repository is empty only when it has no user project files, including ignored files; workspace metadata, skills, references and attachments do not count as a project. For an empty repository, run playcraft references prepare-starter-template --json and merge the returned staged template into the current repository. Preserve existing files and workspace configuration, merge .gitignore without replacing it, preserve executable permissions, and report conflicts or preparation failures instead of overwriting files or creating a batch. Once finished, remove only the exact staging directory returned by the command.',
     'When the user requests multiple independent engineering variants, create a real platform batch using playcraft tools create-batch --prompt <the complete request, including constraints established in this conversation> --workspace-id <the trusted batch request workspaceId> --source-directory <the trusted batch request sourceDirectoryName> --client-request-id <the trusted batch request clientRequestId> --json.',
     'Distinguish independent variants from multiple assets, levels or themes within one engineering project. Use the current session directory supplied by the runtime as the batch source; do not infer it from a preview or another conversation.',
     'The platform freezes the current source and generates each planned variant in its own Remix directory. Submission authorizes automatic generation without another prompt approval. Keep the source unchanged for this batch; do not replace independent variants with theme switching in the source.',
@@ -314,6 +317,7 @@ export function createCodexAppServerAdapter(options) {
             const developerInstructions = [
                 'You coordinate PlayCraft batches. The workspace engineering directories are read-only in this conversation.',
                 `Workspace identity: ${scope}. Engineering source root: ${JSON.stringify(cwd)}. Default source directory: basic.`,
+                'For a single replica, direct the user to the engineering conversation for the intended repository; do not create a batch or edit an engineering directory from this coordinator.',
                 'For a request to create multiple independent variants, create a real platform batch using playcraft tools create-batch --prompt <the complete user request> --workspace-id <workspace identity> --source-directory <basic or the explicitly selected remix directory> --client-request-id <the current batch request context identity> --json.',
                 'The platform plans differences, freezes the selected source and generates independent Remix engineering directories. It automatically starts generation; no browser approval is required. Preserve the source files and source Git history.',
                 'Do not implement a batch as theme switching inside one engineering directory. Do not generate or repair engineering in this coordinator conversation; the platform production tasks own that work.',
@@ -416,7 +420,7 @@ export function createCodexAppServerAdapter(options) {
     }
     async function injectPreparedSkillContext(threadId, prepared) {
         const instructions = asRecord(prepared.params).developerInstructions;
-        if (!prepared.skillsHash || typeof instructions !== 'string')
+        if (typeof instructions !== 'string')
             return;
         if (threads.get(threadId)?.turnActive || [...approvals.values()].some(pending => owningThreadId(pending.threadId) === threadId))
             throw new NativePreparationError('skills_reload_pending');
@@ -425,7 +429,8 @@ export function createCodexAppServerAdapter(options) {
         try {
             await rpc.request('thread/inject_items', { threadId, items: [{ type: 'message', role: 'developer', content: [{
                                 type: 'input_text', text: [
-                                    `Current platform workspace skill lock: ${prepared.skillsHash}. This replaces only earlier platform workspace skill lock and allowlist declarations. Keep all other instructions and permissions in force.`,
+                                    ...(prepared.skillsHash ? [`Current platform workspace skill lock: ${prepared.skillsHash}. This replaces earlier platform workspace skill lock and allowlist declarations.`] : []),
+                                    'This replaces earlier platform batch routing instructions and platform starter-template instructions. Keep all other instructions and permissions in force.',
                                     instructions,
                                 ].join('\n\n'),
                             }] }] }, 30_000);