@playcraft/cli 0.1.4 → 0.1.6

package/dist/commands/build.js

@@ -450,6 +450,7 @@ export async function buildCommand(projectPath, options) {
         const shouldRunPlayableOnly = options.mode === 'playable';
         // 验证平台
         const validPlatforms = [
+            'playcraft',
             'facebook',
             'snapchat',
             'ironsource',
@@ -473,6 +474,7 @@ export async function buildCommand(projectPath, options) {
         // 注：Facebook 在 Phaser（playable-scripts devkit）下的产物格式由其 devkit 输入配置决定（恒为 ZIP），
         //     平台侧不在此处做引擎判断。
         const platformFormatConfig = {
+            playcraft: { formats: ['html'], default: 'html' },
             facebook: { formats: ['html', 'zip'], default: 'html' },
             applovin: { formats: ['html'], default: 'html' },
             ironsource: { formats: ['html'], default: 'html' },
@@ -584,8 +586,11 @@ export async function buildCommand(projectPath, options) {
                     console.log(pc.dim('   无主题目录，跳过主题选择'));
                 }
             }
-            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填
-            if (!options.storeUrls) {
+            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填；通用预览（playcraft）不面向渠道，可不填
+            if (selectedPlatform === 'playcraft' && !options.storeUrls) {
+                console.log(pc.dim('\nℹ️  通用预览不需要商店地址'));
+            }
+            else if (!options.storeUrls) {
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));
                 const storeUrlAnswer = await inquirer.prompt([
@@ -636,8 +641,8 @@ export async function buildCommand(projectPath, options) {
                 // 未指定格式，使用默认值
                 options.format = formatConfig.default;
             }
-            // 如果命令行未传入 storeUrls，交互式输入（必填）
-            if (!options.storeUrls) {
+            // 如果命令行未传入 storeUrls，交互式输入（必填）；通用预览（playcraft）不面向渠道，可不填
+            if (!options.storeUrls && options.platform !== 'playcraft') {
                 spinner.stop();
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));

package/dist/workspace-runtime/persistence/journal.js

@@ -98,6 +98,9 @@ export class RuntimeJournal {
     getOperationById(operationId) {
         return Object.values(this.snapshot.operations).find((operation) => operation.operationId === operationId);
     }
+    listOperations() {
+        return Object.entries(this.snapshot.operations).map(([scopeKey, operation]) => ({ scopeKey, operation }));
+    }
     getReceipt(key) {
         return this.snapshot.receipts[key];
     }

package/dist/workspace-runtime/previews/publish.js

@@ -0,0 +1,237 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, open, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PREVIEW_HTML_MAX_BYTES, PREVIEW_LOG_TAIL_MAX, previewPublishResultSchema, previewReservationSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { excludeFromGit, readDependencies, scheduleDependencyInstall, } from '../workspaces/dependencies.js';
+import { runDeveloperCommand } from '../workspaces/developer-command.js';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { classifyPreviewOutput, findExternalLocalReferences } from './single-file.js';
+const BUILD_TIMEOUT_MS = 10 * 60_000;
+/** Build output and the builder's own scratch folder live in the checkout, hidden from Git. */
+const OUTPUT_FOLDER = '.playcraft-preview-out';
+const BUILDER_TEMP_FOLDER = '.playcraft-temp';
+/**
+ * The generic single-file build. `--mode full` keeps the builder from asking which stages to run.
+ * Group-writable output lets the control user, a member of the development group, remove it.
+ */
+const BUILD_COMMAND = 'umask 002 && playcraft build --mode full --platform playcraft --format html';
+class PreviewFailure extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const running = new WeakMap();
+/**
+ * Checks what can be checked before the operation is accepted. The build itself runs later in
+ * `runPreviewPublish`; the dispatch request returns as soon as the operation is accepted.
+ */
+export async function previewWorkspaceRoot(state, operation) {
+    if (!operation.workspaceId || !/^[A-Za-z0-9_-]+$/.test(operation.operationId)) {
+        throw new PreviewFailure('invalid_preview_publish');
+    }
+    return workspaceRoot(state, operation.workspaceId);
+}
+/** Tracks a background publish so tests and shutdown can wait for it. */
+export function trackPreviewPublish(state, task) {
+    const tasks = running.get(state) ?? new Set();
+    running.set(state, tasks);
+    const tracked = task.finally(() => tasks.delete(tracked));
+    tasks.add(tracked);
+}
+export async function settlePreviewPublishes(state) {
+    await Promise.all([...(running.get(state) ?? [])]);
+}
+/** A publish cut off by a restart has no build left running; it is closed rather than left accepted. */
+export async function recoverInterruptedPreviews(journal) {
+    for (const { scopeKey, operation } of journal.listOperations()) {
+        if (operation.kind !== 'preview.publish' || operation.status !== 'accepted')
+            continue;
+        await journal.putOperation(scopeKey, transitionOperation(operation, 'interrupted', { error: 'preview_interrupted' }));
+    }
+}
+export async function runPreviewPublish(state, operation, root) {
+    const workspaceId = operation.workspaceId;
+    const outputDir = join(root, OUTPUT_FOLDER, operation.operationId);
+    const output = { log: '' };
+    try {
+        await ensureDependencies(state, workspaceId, root);
+        await excludeFromGit(root, `/${OUTPUT_FOLDER}/`);
+        await excludeFromGit(root, `/${BUILDER_TEMP_FOLDER}/`);
+        await buildPreview(state, root, outputDir, operation.operationId, output);
+        const bytes = await readSingleHtml(outputDir);
+        if (bytes.byteLength > PREVIEW_HTML_MAX_BYTES)
+            throw new PreviewFailure('preview_not_single_file');
+        if (findExternalLocalReferences(bytes.toString('utf8')).length > 0) {
+            throw new PreviewFailure('preview_not_single_file');
+        }
+        const contentDigest = createHash('sha256').update(bytes).digest('hex');
+        const contentMd5 = createHash('md5').update(bytes).digest('base64');
+        const source = await sourceRevision(root);
+        const reserved = previewReservationSchema.parse(await postControl(state, '/runtime/internal/preview-reservations', {
+            workspaceId,
+            operationId: operation.operationId,
+            contentDigest,
+            contentMd5,
+            sizeBytes: bytes.byteLength,
+            gitHead: source.head,
+            dirty: source.dirty,
+            cliVersion: state.config.cliVersion,
+        }));
+        if (!reserved.alreadyUploaded) {
+            const uploaded = await fetch(reserved.uploadUrl, {
+                method: 'PUT',
+                redirect: 'error',
+                signal: AbortSignal.timeout(120_000),
+                headers: {
+                    'content-type': 'text/html; charset=utf-8',
+                    'content-md5': contentMd5,
+                    'content-length': String(bytes.byteLength),
+                },
+                body: new Uint8Array(bytes),
+            });
+            await uploaded.body?.cancel();
+            if (!uploaded.ok)
+                throw new PreviewFailure('preview_upload_failed');
+        }
+        const published = previewPublishResultSchema.parse(await postControl(state, '/runtime/internal/preview-completions', {
+            workspaceId,
+            operationId: operation.operationId,
+            artifactId: reserved.artifactId,
+            expectedPublishRevision: reserved.expectedPublishRevision,
+            logTail: tail(output.log),
+        }));
+        if (published.status === 'conflict')
+            throw new PreviewFailure('publish_conflict');
+        return published;
+    }
+    catch (error) {
+        const code = error instanceof PreviewFailure ? error.code : 'preview_build_failed';
+        if (code !== 'publish_conflict') {
+            await postControl(state, '/runtime/internal/preview-failures', {
+                workspaceId,
+                operationId: operation.operationId,
+                error: code,
+                logTail: tail(output.log || (error instanceof Error ? error.message : '')),
+            }).catch(() => undefined);
+        }
+        throw new PreviewFailure(code);
+    }
+    finally {
+        await rm(outputDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export function previewFailureCode(error) {
+    const code = error instanceof PreviewFailure
+        ? error.code
+        : error instanceof Error && /^[a-z_]+$/.test(error.message)
+            ? error.message
+            : 'preview_build_failed';
+    return code.slice(0, 256);
+}
+/**
+ * Checks the install against the current manifest and lockfile before building, so a package
+ * Codex added since the workspace opened is installed first. A running install is joined rather
+ * than started twice; a failed one is retried once here.
+ */
+async function ensureDependencies(state, workspaceId, root) {
+    await scheduleDependencyInstall(state, workspaceId, root);
+    const status = readDependencies(state, workspaceId).status;
+    if (status !== 'ready' && status !== 'none')
+        throw new PreviewFailure('dependencies_not_ready');
+}
+async function buildPreview(state, root, outputDir, operationId, output) {
+    // Tests replace the build; the real one needs a project and the published CLI.
+    const planned = process.env.PLAYCRAFT_PREVIEW_BUILD_COMMAND || BUILD_COMMAND;
+    const outcome = await runDeveloperCommand(state, {
+        processId: `preview-${operationId}`,
+        cwd: root,
+        command: `${planned} --output ${shellQuote(outputDir)} .`,
+        timeoutMs: BUILD_TIMEOUT_MS,
+        onOutput: (chunk) => {
+            output.log = (output.log + String(chunk)).slice(-64 * 1024);
+        },
+    });
+    if (outcome.code !== 0)
+        throw new PreviewFailure('preview_build_failed');
+}
+/** Reads the one HTML file without following links, so the uploaded bytes are what was checked. */
+async function readSingleHtml(outputDir) {
+    const listed = await readdir(outputDir, { withFileTypes: true }).catch(() => {
+        throw new PreviewFailure('preview_not_single_file');
+    });
+    const entries = listed.map((entry) => ({
+        name: entry.name,
+        kind: entry.isSymbolicLink() ? 'symlink' : entry.isFile() ? 'file' : 'dir',
+    }));
+    const classified = classifyPreviewOutput(entries);
+    if (!classified.ok)
+        throw new PreviewFailure('preview_not_single_file');
+    const source = join(outputDir, classified.entry);
+    const stat = await lstat(source);
+    if (!stat.isFile())
+        throw new PreviewFailure('preview_not_single_file');
+    const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function sourceRevision(root) {
+    const head = await git(root, ['rev-parse', 'HEAD']);
+    const status = await git(root, ['status', '--porcelain']);
+    const revision = head.stdout.trim();
+    if (head.code !== 0 || !/^[0-9a-f]{7,64}$/i.test(revision))
+        return { dirty: true };
+    return { head: revision, dirty: status.code !== 0 || status.stdout.trim().length > 0 };
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (chunk) => {
+            stdout = (stdout + String(chunk)).slice(-8_000);
+        });
+        child.once('error', () => resolve({ code: null, stdout }));
+        child.once('close', (code) => resolve({ code, stdout }));
+    });
+}
+async function postControl(state, path, body) {
+    const endpoint = new URL(path, state.config.callbackUrl);
+    const local = endpoint.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname);
+    if (endpoint.protocol !== 'https:' && !local)
+        throw new PreviewFailure('preview_upload_failed');
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(60_000),
+        headers: {
+            authorization: `Bearer ${state.config.controlToken}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            runtimeId: state.config.runtimeId,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            ...body,
+        }),
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const record = (payload && typeof payload === 'object' ? payload : {});
+        const reason = typeof record.reason === 'string' ? record.reason : typeof record.error === 'string' ? record.error : '';
+        throw new PreviewFailure(/^[a-z_]{1,64}$/.test(reason) ? reason : 'preview_upload_failed');
+    }
+    return payload;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function tail(value) {
+    return value.slice(-PREVIEW_LOG_TAIL_MAX);
+}

package/dist/workspace-runtime/previews/single-file.js

@@ -0,0 +1,35 @@
+const LOCAL_ATTR = /<(?:script|img|link|source|video|audio|iframe)\b[^>]*?\b(?:src|href)\s*=\s*["']([^"']+)["']/gi;
+const CSS_URL = /url\(\s*["']?([^"')]+)["']?\s*\)/gi;
+/** A reference the sealed document would load from the local build, not from the network or inline data. */
+export function findExternalLocalReferences(html) {
+    const found = new Set();
+    for (const expression of [LOCAL_ATTR, CSS_URL]) {
+        expression.lastIndex = 0;
+        for (const match of html.matchAll(expression)) {
+            const value = (match[1] ?? '').trim();
+            if (isLocalReference(value))
+                found.add(value);
+        }
+    }
+    return [...found];
+}
+export function classifyPreviewOutput(entries) {
+    if (entries.length !== 1)
+        return { ok: false };
+    const only = entries[0];
+    if (!only || only.kind !== 'file' || !only.name.toLowerCase().endsWith('.html'))
+        return { ok: false };
+    if (only.name.includes('/') || only.name.includes('\\') || only.name === '.' || only.name === '..') {
+        return { ok: false };
+    }
+    return { ok: true, entry: only.name };
+}
+function isLocalReference(value) {
+    if (!value || value.startsWith('#') || value.startsWith('data:') || value.startsWith('blob:'))
+        return false;
+    if (/^(https?:|mailto:|javascript:)/i.test(value))
+        return false;
+    if (value.startsWith('//'))
+        return false;
+    return true;
+}

package/dist/workspace-runtime/serve.js

@@ -14,6 +14,7 @@ import { RuntimeProcessLock } from './server/lock.js';
 import { probeGitBinary } from './workspaces/git.js';
 import { WorkspaceGitCredentialBroker } from './workspaces/git-credential-broker.js';
 import { WorkspaceModelBroker } from './codex/model-broker.js';
+import { recoverInterruptedPreviews } from './previews/publish.js';
 import { recoverInterruptedInstalls } from './workspaces/dependencies.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
@@ -33,6 +34,7 @@ export async function startWorkspaceRuntime(config, options = {}) {
         journal = new RuntimeJournal(config.stateDir);
         await journal.load();
         await recoverInterruptedInstalls(journal);
+        await recoverInterruptedPreviews(journal);
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
         const state = {
             config: { ...config, protocolMinor: negotiated.protocolMinor },

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

@@ -10,6 +10,7 @@ import { InvalidWorkspacePathError, resolveWorkspaceFile, restoreWorkspaceFiles,
 import { GitWorkspaceError, commitWorkspaceGit, discardWorkspaceGit, pushWorkspaceGit, stageWorkspaceGit, unstageWorkspaceGit, } from '../workspaces/git.js';
 import { ParameterEditError } from '../workspaces/json5-edit.js';
 import { patchWorkspaceParameters, readWorkspaceParameters } from '../workspaces/parameters.js';
+import { previewFailureCode, previewWorkspaceRoot, runPreviewPublish, trackPreviewPublish, } from '../previews/publish.js';
 import { executionGroupRestarted } from './execution-group.js';
 import { probeProcess, spawnBackgroundWriter, stopBackgroundWriter, } from '../processes/managed-writes.js';
 const CONVERSATION_KINDS = new Set([
@@ -31,6 +32,7 @@ const LOCAL_KINDS = new Set([
     'git.discard',
     'terminal.create',
     'parameter.patch',
+    'preview.publish',
 ]);
 export function canExecuteKind(state, kind) {
     if (LOCAL_KINDS.has(kind))
@@ -51,8 +53,9 @@ export async function executeOperation(state, scopeKey, operation, payload) {
     const checkpointId = asRecord(payload).checkpointId;
     const checkpointRun = () => operation.kind.startsWith('checkpoint.') && typeof checkpointId === 'string'
         ? state.journal.exclusive(`checkpoint:${checkpointId}`, run) : run();
-    if (['runtime.destroy', 'session.interrupt', 'session.approval.respond'].includes(operation.kind))
+    if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'preview.publish'].includes(operation.kind)) {
         return run();
+    }
     return state.journal.exclusive(`workspace:${revisionScope(state, operation.workspaceId) ?? 'single'}`, checkpointRun);
 }
 function workspaceTurnAllowed(state) {
@@ -100,6 +103,9 @@ async function executeScopedOperation(state, scopeKey, operation, payload) {
     if (operation.kind === 'parameter.patch') {
         return executeParameterPatch(state, scopeKey, current, payload);
     }
+    if (operation.kind === 'preview.publish') {
+        return executePreviewPublish(state, scopeKey, current);
+    }
     if (!state.native?.ready()) {
         return persist(state, scopeKey, transitionOperation(current, 'failed', { error: 'capability_unavailable' }));
     }
@@ -694,6 +700,26 @@ async function executeParameterPatch(state, scopeKey, operation, payload) {
         }
     }).catch((error) => persist(state, scopeKey, transitionOperation(operation, 'failed', { error: parameterPatchError(error) })));
 }
+/**
+ * A preview build takes minutes, so the request returns once the operation is accepted; Runtime
+ * reads the final state back by operation id. A request the sandbox cannot serve fails at once.
+ */
+async function executePreviewPublish(state, scopeKey, operation) {
+    let root;
+    try {
+        root = await previewWorkspaceRoot(state, operation);
+    }
+    catch (error) {
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: previewFailureCode(error) }));
+    }
+    const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
+    trackPreviewPublish(state, runPreviewPublish(state, accepted, root).then(async () => {
+        await persist(state, scopeKey, transitionOperation(accepted, 'completed'));
+    }, async (error) => {
+        await persist(state, scopeKey, transitionOperation(accepted, 'failed', { error: previewFailureCode(error) }));
+    }).catch(() => undefined));
+    return accepted;
+}
 async function executeTerminalCreate(state, scopeKey, operation, payload) {
     const parsed = terminalCreatePayloadSchema.safeParse(payload ?? {});
     if (!parsed.success) {

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

@@ -264,7 +264,7 @@ function handshake(state) {
         if (item.name === 'artifacts.singleFile') {
             return destroyed
                 ? capability('artifacts.singleFile', false, 'runtime_destroyed')
-                : capability('artifacts.singleFile', false, 'capability_not_implemented');
+                : capability('artifacts.singleFile', true);
         }
         return item;
     });
@@ -559,8 +559,6 @@ async function handleTerminalIdentity(state, request, response, remainder) {
 function unavailableReason(state, kind) {
     if (state.journal.destroyed())
         return 'runtime_destroyed';
-    if (kind === 'preview.publish')
-        return 'capability_not_implemented';
     return state.nativeError ?? 'adapter_not_started';
 }
 function sessionHistoryPath(pathname) {

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

@@ -1,13 +1,14 @@
-import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { appendFile, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { appendFile, lstat, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
 import { join } from 'node:path';
-import { startLauncherProcess } from '../codex/launcher-client.js';
+import { launcherSocket, runDeveloperCommand } from './developer-command.js';
 /** Long enough for a cold store on a game template; a stuck registry must not hold the write lease. */
 const INSTALL_TIMEOUT_MS = 10 * 60_000;
 const LOG_TAIL_LINES = 50;
 const LOG_TAIL_MAX_CHARS = 8_000;
 const WRITE_PREFIX = 'dependencies-';
+const SHARE_WAIT_MS = 60_000;
 /**
  * Projects are managed with pnpm. It follows pnpm-lock.yaml when the lockfile matches, never
  * prompts, and writes plain lines to the log. Package scripts run: the workspace is the user's own
@@ -27,21 +28,24 @@ export async function planInstall(root) {
 }
 const running = new WeakMap();
 /**
- * Starts the install after a workspace is registered and returns at once; opening the workspace
- * never waits for it. Registering again retries a failed install and reinstalls after the
- * manifest or lockfile changed. One install runs per workspace at a time.
+ * Starts the install after a workspace is registered; opening the workspace never waits for it.
+ * Registering again retries a failed install and reinstalls after the manifest or lockfile
+ * changed. One install runs per workspace at a time: a second call gets the running one. The
+ * returned task settles when that install has finished or been found current.
  */
 export function scheduleDependencyInstall(state, workspaceId, root) {
     const inFlight = running.get(state) ?? new Map();
     running.set(state, inFlight);
-    if (inFlight.has(workspaceId))
-        return;
+    const existing = inFlight.get(workspaceId);
+    if (existing)
+        return existing;
     const task = installOnce(state, workspaceId, root)
         .catch((error) => {
         console.error(`[workspace-runtime] dependency install for ${workspaceId} failed to run`, error);
     })
         .finally(() => inFlight.delete(workspaceId));
     inFlight.set(workspaceId, task);
+    return task;
 }
 /** Settles every install started in this process; used by tests and shutdown. */
 export async function settleDependencyInstalls(state) {
@@ -102,7 +106,12 @@ async function installOnce(state, workspaceId, root) {
     });
     let outcome;
     try {
-        outcome = await runInstall(state, workspaceId, root);
+        // Through the launcher the install runs as the development group, which cannot enter the
+        // checkout until Runtime has opened it; a local install runs as the owner and need not wait.
+        const shared = !launcherSocket(state) || (await waitUntilShared(root));
+        outcome = shared
+            ? await runInstall(state, workspaceId, root)
+            : { code: undefined, timedOut: false, log: '', error: 'workspace_not_shared' };
     }
     finally {
         await state.journal.putManagedWrite({
@@ -119,7 +128,10 @@ async function installOnce(state, workspaceId, root) {
         status: ok ? 'ready' : 'failed',
         ...(ok
             ? { lockHash: plan.lockHash }
-            : { error: outcome.timedOut ? 'install_timeout' : `install_exit_${outcome.code ?? 'lost'}` }),
+            : {
+                error: outcome.error ??
+                    (outcome.timedOut ? 'install_timeout' : `install_exit_${outcome.code ?? 'lost'}`),
+            }),
         startedAt,
         finishedAt: new Date().toISOString(),
         logTail: tail(outcome.log),
@@ -132,81 +144,57 @@ async function installOnce(state, workspaceId, root) {
 async function runInstall(state, workspaceId, root) {
     // Tests replace the install; a real registry is never reached from them.
     const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || INSTALL_COMMAND;
-    const command = `{ ${planned}; } </dev/null 2>&1`;
     const logDir = join(state.config.stateDir, 'dependency-logs');
     await mkdir(logDir, { recursive: true, mode: 0o700 });
     const logPath = join(logDir, `${workspaceId}.log`);
     await writeFile(logPath, `$ ${planned}\n`, { mode: 0o600 });
     let log = '';
     let pending = Promise.resolve();
-    const record = (chunk) => {
-        const text = String(chunk);
-        log = (log + text).slice(-64 * 1024);
-        pending = pending.then(() => appendFile(logPath, text)).catch(() => undefined);
-    };
-    const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
-    const launched = socketPath && state.config.workspaceMode === 'multi'
-        ? await startLauncherProcess({
-            socketPath,
-            processId: `${WRITE_PREFIX}${workspaceId}`,
-            runtimeEpoch: state.runtimeEpoch,
-            argv: ['/usr/bin/bash', '-lc', command],
-            cwd: root,
-            env: {},
-        })
-        : undefined;
-    launched?.stdin?.end();
-    const local = launched
-        ? undefined
-        : spawn('bash', ['-lc', command], {
-            cwd: root,
-            detached: true,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-    const stdout = launched?.stdout ?? local.stdout;
-    const stderr = launched?.stderr ?? local.stderr;
-    stdout.on('data', record);
-    stderr.on('data', record);
-    let timedOut = false;
-    const code = await new Promise((resolve) => {
-        const timer = setTimeout(() => {
-            timedOut = true;
-            if (launched)
-                void launched.stop().catch(() => undefined);
-            else if (local?.pid) {
-                try {
-                    process.kill(-local.pid, 'SIGKILL');
-                }
-                catch {
-                    /* already gone */
-                }
-            }
-        }, INSTALL_TIMEOUT_MS);
-        const finish = (value) => {
-            clearTimeout(timer);
-            resolve(value);
-        };
-        if (launched)
-            launched.onExit(finish);
-        else {
-            local.once('error', () => finish(null));
-            local.once('close', (value) => finish(value));
-        }
+    const outcome = await runDeveloperCommand(state, {
+        processId: `${WRITE_PREFIX}${workspaceId}`,
+        cwd: root,
+        command: planned,
+        timeoutMs: INSTALL_TIMEOUT_MS,
+        onOutput: (chunk) => {
+            const text = String(chunk);
+            log = (log + text).slice(-64 * 1024);
+            pending = pending.then(() => appendFile(logPath, text)).catch(() => undefined);
+        },
     });
     await pending;
-    return { code, timedOut, log };
+    return { ...outcome, log };
+}
+/**
+ * The checkout is cloned private to the control user and opened to the development group by
+ * Runtime after registration. Group read, write and search on the root is the sign it is open.
+ */
+export async function waitUntilShared(root, timeoutMs = SHARE_WAIT_MS, intervalMs = 500) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            if (((await stat(root)).mode & 0o070) === 0o070)
+                return true;
+        }
+        catch {
+            /* not there yet */
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await delay(intervalMs);
+    }
 }
 /** A local-only ignore, never committed: the change list must not fill up with installed packages. */
-async function excludeFromGit(root) {
+/** Keeps sandbox-managed folders out of the Git panel without touching the project's .gitignore. */
+export async function excludeFromGit(root, entry = '/node_modules/') {
     const info = join(root, '.git', 'info');
     if (!(await isDirectory(join(root, '.git'))))
         return;
     await mkdir(info, { recursive: true });
     const path = join(info, 'exclude');
     const current = (await readOptional(path)) ?? '';
-    if (current.split('\n').some((line) => line.trim() === '/node_modules/'))
+    if (current.split('\n').some((line) => line.trim() === entry))
         return;
-    await appendFile(path, `${current && !current.endsWith('\n') ? '\n' : ''}/node_modules/\n`);
+    await appendFile(path, `${current && !current.endsWith('\n') ? '\n' : ''}${entry}\n`);
 }
 function tail(log) {
     return log.split('\n').slice(-LOG_TAIL_LINES).join('\n').slice(-LOG_TAIL_MAX_CHARS);

package/dist/workspace-runtime/workspaces/developer-command.js

@@ -0,0 +1,64 @@
+import { spawn } from 'node:child_process';
+import { startLauncherProcess } from '../codex/launcher-client.js';
+export function launcherSocket(state) {
+    const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+    return socketPath && state.config.workspaceMode === 'multi' ? socketPath : undefined;
+}
+/**
+ * Runs a shell command in the workspace as the development user through the launcher, so whatever
+ * it writes belongs to the same user as Codex. Without a launcher (local runs and tests) it runs
+ * directly as the owner. Output from both streams goes to `onOutput`.
+ */
+export async function runDeveloperCommand(state, input) {
+    const command = `{ ${input.command}; } </dev/null 2>&1`;
+    const socketPath = launcherSocket(state);
+    const launched = socketPath
+        ? await startLauncherProcess({
+            socketPath,
+            processId: input.processId,
+            runtimeEpoch: state.runtimeEpoch,
+            argv: ['/usr/bin/bash', '-lc', command],
+            cwd: input.cwd,
+            env: {},
+        })
+        : undefined;
+    launched?.stdin?.end();
+    const local = launched
+        ? undefined
+        : spawn('bash', ['-lc', command], {
+            cwd: input.cwd,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    const stdout = launched?.stdout ?? local.stdout;
+    const stderr = launched?.stderr ?? local.stderr;
+    stdout.on('data', input.onOutput);
+    stderr.on('data', input.onOutput);
+    let timedOut = false;
+    const code = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (launched)
+                void launched.stop().catch(() => undefined);
+            else if (local?.pid) {
+                try {
+                    process.kill(-local.pid, 'SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }, input.timeoutMs);
+        const finish = (value) => {
+            clearTimeout(timer);
+            resolve(value);
+        };
+        if (launched)
+            launched.onExit(finish);
+        else {
+            local.once('error', () => finish(null));
+            local.once('close', (value) => finish(value));
+        }
+    });
+    return { code, timedOut };
+}

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

@@ -114,7 +114,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
         }
         await state.journal.putWorkspace(binding);
         // Runs in the background; every registration rechecks it, so reopening retries a failed install.
-        scheduleDependencyInstall(state, binding.workspaceId, root);
+        void scheduleDependencyInstall(state, binding.workspaceId, root);
         return binding;
     });
 }

package/package.json

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