@playcraft/cli 0.1.2 → 0.1.4

package/dist/workspace-runtime/codex/launcher-client.js

@@ -39,6 +39,7 @@ export async function startLauncherProcess(input) {
     const stderr = new PassThrough();
     const events = new EventEmitter();
     let exited = false;
+    let exitCode;
     let buffer = '';
     let identity;
     let stopPromise;
@@ -56,7 +57,7 @@ export async function startLauncherProcess(input) {
         if (exited)
             return;
         exited = true;
-        events.emit('exit');
+        events.emit('exit', exitCode);
     }
     socket.setEncoding('utf8');
     const pid = await new Promise((resolve, reject) => {
@@ -97,8 +98,10 @@ export async function startLauncherProcess(input) {
                             stream.once('drain', () => socket.resume());
                         }
                     }
-                    else if (frame.event === 'exit')
+                    else if (frame.event === 'exit') {
+                        exitCode = typeof frame.code === 'number' ? frame.code : null;
                         exit();
+                    }
                     else
                         throw new Error('launcher_invalid_frame');
                 }
@@ -128,7 +131,7 @@ export async function startLauncherProcess(input) {
         stderr,
         onExit(listener) {
             if (exited)
-                queueMicrotask(listener);
+                queueMicrotask(() => listener(exitCode));
             else
                 events.once('exit', listener);
         },

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

@@ -137,6 +137,19 @@ export class RuntimeJournal {
     async putManagedWrite(record) {
         await this.run('upsertRecord', { bucket: 'managed_writes', key: record.writeId, body: record });
     }
+    getWorkspaceDependencies(workspaceId) {
+        return this.snapshot.workspaceDependencies[workspaceId];
+    }
+    listWorkspaceDependencies() {
+        return Object.values(this.snapshot.workspaceDependencies);
+    }
+    async putWorkspaceDependencies(record) {
+        await this.run('upsertRecord', {
+            bucket: 'workspace_dependencies',
+            key: record.workspaceId,
+            body: record,
+        });
+    }
     fileRevisions(workspaceId) {
         return { ...(workspaceId ? this.snapshot.workspaceFileRevisions[workspaceId] ?? {} : this.snapshot.fileRevisions) };
     }
@@ -355,6 +368,7 @@ function emptySnapshot() {
         fileRevisions: {},
         approvals: {},
         managedWrites: {},
+        workspaceDependencies: {},
         executionGroup: { stopConfirmed: false, replaced: false },
         lastSourceSequence: 0,
         acceptedLeaseFence: 0,

package/dist/workspace-runtime/persistence/sqlite-worker.js

@@ -705,6 +705,7 @@ function dump(database) {
         fileRevisions: bucketObject(database, 'file_revisions'),
         approvals: bucketObject(database, 'approvals'),
         managedWrites: bucketObject(database, 'managed_writes'),
+        workspaceDependencies: bucketObject(database, 'workspace_dependencies'),
         fileCheckpointId: metaString(database, 'file_checkpoint_id') || undefined,
         consistentCheckpointId: metaString(database, 'consistent_checkpoint_id') || undefined,
         executionGroup: executionGroup(database),

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 { recoverInterruptedInstalls } from './workspaces/dependencies.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -31,6 +32,7 @@ export async function startWorkspaceRuntime(config, options = {}) {
     try {
         journal = new RuntimeJournal(config.stateDir);
         await journal.load();
+        await recoverInterruptedInstalls(journal);
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
         const state = {
             config: { ...config, protocolMinor: negotiated.protocolMinor },

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

@@ -2,12 +2,12 @@ import { withObservedFile } from '../workspaces/revisions.js';
 import { revisionScope, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { checkpointRecordSchema, fileWritePayloadSchema, gitCommitPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { checkpointRecordSchema, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
 import { NativePreparationError } from '../codex/native-adapter.js';
 import { disposeTerminalHost } from './terminal-host.js';
 import { captureWorkspaceTree, materializeSnapshot, publishFileSnapshot, } from '../workspaces/file-snapshot.js';
 import { InvalidWorkspacePathError, resolveWorkspaceFile, restoreWorkspaceFiles, snapshotWorkspaceFiles, writeWorkspaceFile, } from '../workspaces/files.js';
-import { GitWorkspaceError, commitWorkspaceGit, pushWorkspaceGit } from '../workspaces/git.js';
+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 { executionGroupRestarted } from './execution-group.js';
@@ -26,6 +26,9 @@ const LOCAL_KINDS = new Set([
     'file.write',
     'git.commit',
     'git.push',
+    'git.stage',
+    'git.unstage',
+    'git.discard',
     'terminal.create',
     'parameter.patch',
 ]);
@@ -88,6 +91,9 @@ async function executeScopedOperation(state, scopeKey, operation, payload) {
     if (operation.kind === 'git.push') {
         return executeGitPush(state, scopeKey, current, payload);
     }
+    if (operation.kind === 'git.stage' || operation.kind === 'git.unstage' || operation.kind === 'git.discard') {
+        return executeGitIndex(state, scopeKey, current, payload);
+    }
     if (operation.kind === 'terminal.create') {
         return executeTerminalCreate(state, scopeKey, current, payload);
     }
@@ -620,6 +626,30 @@ async function executeGitPush(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: gitErrorCode(error) }));
     }
 }
+const GIT_INDEX_CHANGES = {
+    'git.stage': { run: stageWorkspaceGit, event: 'git.staged' },
+    'git.unstage': { run: unstageWorkspaceGit, event: 'git.unstaged' },
+    'git.discard': { run: discardWorkspaceGit, event: 'git.discarded' },
+};
+/** Stage, unstage and discard share a payload; each records its own event so the browser refreshes. */
+async function executeGitIndex(state, scopeKey, operation, payload) {
+    const change = GIT_INDEX_CHANGES[operation.kind];
+    const parsed = gitPathsPayloadSchema.safeParse(payload);
+    if (!parsed.success) {
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_git_paths' }));
+    }
+    try {
+        await change.run(await workspaceRoot(state, operation.workspaceId), parsed.data);
+        const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
+        await recordNativeEvents(state, accepted, [
+            { type: change.event, payload: { paths: parsed.data.paths }, occurredAt: new Date().toISOString() },
+        ]);
+        return persist(state, scopeKey, transitionOperation(accepted, 'completed'));
+    }
+    catch (error) {
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: gitErrorCode(error) }));
+    }
+}
 async function executeParameterPatch(state, scopeKey, operation, payload) {
     const parsed = parameterPatchPayloadSchema.safeParse(payload);
     if (!parsed.success) {

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

@@ -1,13 +1,14 @@
 import { readObservedFile, withObservedFile } from '../workspaces/revisions.js';
 import { registerWorkspace, revisionScope, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { randomUUID } from 'node:crypto';
-import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, hashOperationPayload, instanceRebuildRequestSchema, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, instanceRebuildRequestSchema, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { canExecuteKind, executeOperation } from './dispatch.js';
 import { InvalidWorkspacePathError, listWorkspaceFiles, } from '../workspaces/files.js';
 import { materializeRemoteSnapshot } from '../workspaces/file-snapshot.js';
-import { GitWorkspaceError, readWorkspaceGitDiff, readWorkspaceGitGraph, readWorkspaceGitStatus, } from '../workspaces/git.js';
+import { GitWorkspaceError, readWorkspaceGitDiff, readWorkspaceGitFile, readWorkspaceGitGraph, readWorkspaceGitStatus, } from '../workspaces/git.js';
 import { readWorkspaceParameters } from '../workspaces/parameters.js';
+import { readDependencies } from '../workspaces/dependencies.js';
 import { desktopHost, desktopRoute } from './desktop-host.js';
 import { terminalHost } from './terminal-host.js';
 export async function handleRuntimeRequest(state, request, response) {
@@ -131,6 +132,23 @@ export async function handleRuntimeRequest(state, request, response) {
             await writeGitRead(state, response, async () => readWorkspaceGitDiff(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
             return;
         }
+        if (request.method === 'GET' && url.pathname === '/runtime/git/file') {
+            const ref = gitFileRefSchema.safeParse(url.searchParams.get('ref'));
+            if (!ref.success) {
+                writeJson(response, 400, { error: 'invalid_git_ref' });
+                return;
+            }
+            await writeGitRead(state, response, async () => readWorkspaceGitFile(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined), url.searchParams.get('path') ?? '', ref.data));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/dependencies') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            await workspaceRoot(state, workspaceId);
+            writeJson(response, 200, readDependencies(state, workspaceId ?? 'workspace'));
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/git/graph') {
             await writeGitRead(state, response, async () => readWorkspaceGitGraph(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
             return;

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

@@ -0,0 +1,229 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { startLauncherProcess } from '../codex/launcher-client.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-';
+/**
+ * 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
+ * sandbox and the install runs as the development user.
+ */
+const INSTALL_COMMAND = 'pnpm install --reporter=append-only --config.confirm-modules-purge=false';
+/** Installs whenever there is a package.json; the hash says whether a finished install is current. */
+export async function planInstall(root) {
+    const manifest = await readOptional(join(root, 'package.json'));
+    if (manifest === undefined)
+        return { kind: 'skip' };
+    const lock = (await readOptional(join(root, 'pnpm-lock.yaml'))) ?? '';
+    return {
+        kind: 'install',
+        lockHash: createHash('sha256').update(manifest).update('\0').update(lock).digest('hex'),
+    };
+}
+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.
+ */
+export function scheduleDependencyInstall(state, workspaceId, root) {
+    const inFlight = running.get(state) ?? new Map();
+    running.set(state, inFlight);
+    if (inFlight.has(workspaceId))
+        return;
+    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);
+}
+/** Settles every install started in this process; used by tests and shutdown. */
+export async function settleDependencyInstalls(state) {
+    await Promise.all([...(running.get(state)?.values() ?? [])]);
+}
+export function readDependencies(state, workspaceId) {
+    return state.journal.getWorkspaceDependencies(workspaceId) ?? { workspaceId, status: 'pending' };
+}
+/**
+ * An install cut off by a restart left no process behind (the launcher stops the group when its
+ * connection closes), so its status and write lease are closed rather than left in progress.
+ */
+export async function recoverInterruptedInstalls(journal) {
+    const now = new Date().toISOString();
+    for (const record of journal.listWorkspaceDependencies()) {
+        if (record.status !== 'installing')
+            continue;
+        await journal.putWorkspaceDependencies({
+            ...record,
+            status: 'failed',
+            error: 'interrupted',
+            finishedAt: now,
+        });
+    }
+    for (const write of journal.listManagedWrites()) {
+        if (write.writeId.startsWith(WRITE_PREFIX) && !write.stoppedAt) {
+            await journal.putManagedWrite({ ...write, stoppedAt: now });
+        }
+    }
+}
+async function installOnce(state, workspaceId, root) {
+    const plan = await planInstall(root);
+    const current = state.journal.getWorkspaceDependencies(workspaceId);
+    if (plan.kind === 'skip') {
+        if (current?.status !== 'none') {
+            await state.journal.putWorkspaceDependencies({
+                workspaceId,
+                status: 'none',
+                finishedAt: new Date().toISOString(),
+            });
+        }
+        return;
+    }
+    if (current?.status === 'ready' &&
+        current.lockHash === plan.lockHash &&
+        (await isDirectory(join(root, 'node_modules')))) {
+        return;
+    }
+    await excludeFromGit(root);
+    const startedAt = new Date().toISOString();
+    const writeId = `${WRITE_PREFIX}${workspaceId}-${randomUUID()}`;
+    // A checkpoint waits for this write: node_modules is half written until the install ends.
+    await state.journal.putManagedWrite({ writeId, workspaceId, source: 'background', startedAt });
+    await state.journal.putWorkspaceDependencies({
+        workspaceId,
+        status: 'installing',
+        startedAt,
+    });
+    let outcome;
+    try {
+        outcome = await runInstall(state, workspaceId, root);
+    }
+    finally {
+        await state.journal.putManagedWrite({
+            writeId,
+            workspaceId,
+            source: 'background',
+            startedAt,
+            stoppedAt: new Date().toISOString(),
+        });
+    }
+    const ok = outcome.code === 0 && !outcome.timedOut;
+    await state.journal.putWorkspaceDependencies({
+        workspaceId,
+        status: ok ? 'ready' : 'failed',
+        ...(ok
+            ? { lockHash: plan.lockHash }
+            : { error: outcome.timedOut ? 'install_timeout' : `install_exit_${outcome.code ?? 'lost'}` }),
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        logTail: tail(outcome.log),
+    });
+}
+/**
+ * Runs as the development user through the launcher, so the packages belong to the same user as
+ * Codex and its own later installs. Without a launcher (local runs and tests) it runs directly.
+ */
+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));
+        }
+    });
+    await pending;
+    return { code, timedOut, log };
+}
+/** A local-only ignore, never committed: the change list must not fill up with installed packages. */
+async function excludeFromGit(root) {
+    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/'))
+        return;
+    await appendFile(path, `${current && !current.endsWith('\n') ? '\n' : ''}/node_modules/\n`);
+}
+function tail(log) {
+    return log.split('\n').slice(-LOG_TAIL_LINES).join('\n').slice(-LOG_TAIL_MAX_CHARS);
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await lstat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,8 +1,8 @@
 import { spawn } from 'node:child_process';
-import { readFile, realpath, stat } from 'node:fs/promises';
+import { lstat, readFile, realpath, stat, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, relative, resolve, sep } from 'node:path';
-import { gitDiffSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
 const GIT_DIFF_MAX_BYTES = 1024 * 1024;
 const GIT_PREFIX = [
     '-c',
@@ -42,15 +42,96 @@ export async function readWorkspaceGitStatus(root) {
         ahead = Number.parseInt(right ?? '0', 10) || 0;
     }
     const porcelain = await git(rootReal, ['status', '--porcelain=v1', '--untracked-files=all', '-z']);
+    // Line counts are a convenience; a repository without commits still lists its files.
+    const [staged, unstaged] = await Promise.all([
+        gitAllowFail(rootReal, ['diff', '--cached', '--numstat', '-z']),
+        gitAllowFail(rootReal, ['diff', '--numstat', '-z']),
+    ]);
+    const stagedCounts = staged.code === 0 ? parseNumstat(staged.stdout) : new Map();
+    const unstagedCounts = unstaged.code === 0 ? parseNumstat(unstaged.stdout) : new Map();
     return gitStatusSchema.parse({
         initialized: true,
         branch,
         ahead,
         behind,
         hasUpstream: upstream.code === 0,
-        files: parsePorcelain(porcelain),
+        files: parsePorcelain(porcelain).map((entry) => ({
+            ...entry,
+            ...(stagedCounts.has(entry.path) ? { staged: stagedCounts.get(entry.path) } : {}),
+            ...(unstagedCounts.has(entry.path) ? { unstaged: unstagedCounts.get(entry.path) } : {}),
+        })),
     });
 }
+/**
+ * One file as stored in the last commit or in the index. Reads the blob as is, without filters,
+ * so the browser compares exactly what Git holds.
+ */
+export async function readWorkspaceGitFile(root, path, ref) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths([path]);
+    const object = ref === 'HEAD' ? `HEAD:${path}` : `:${path}`;
+    const absent = gitFileContentSchema.parse({ path, ref, exists: false, binary: false, content: '' });
+    const size = await gitAllowFail(rootReal, ['cat-file', '-s', object]);
+    if (size.code !== 0)
+        return absent;
+    if (Number.parseInt(size.stdout.trim(), 10) > WORKSPACE_FILE_CONTENT_MAX) {
+        throw new GitWorkspaceError('git_file_too_large', path);
+    }
+    const blob = await gitAllowFail(rootReal, ['cat-file', 'blob', object]);
+    if (blob.code !== 0)
+        return absent;
+    // Git treats a NUL byte as the mark of binary content; so does the diff view.
+    const binary = blob.stdout.includes('\0');
+    return gitFileContentSchema.parse({ path, ref, exists: true, binary, content: binary ? '' : blob.stdout });
+}
+/** Adds the paths to the index, including deletions. */
+export async function stageWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    await git(rootReal, ['--literal-pathspecs', 'add', '-A', '--', ...payload.paths]);
+}
+/** Returns the paths' index entries to the last commit, leaving the work tree alone. */
+export async function unstageWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    const head = await gitAllowFail(rootReal, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    if (head.code === 0) {
+        await git(rootReal, ['--literal-pathspecs', 'restore', '--staged', '--', ...payload.paths]);
+    }
+    else {
+        // Before the first commit there is nothing to restore from; the entries are simply removed.
+        await git(rootReal, ['--literal-pathspecs', 'rm', '--cached', '-r', '-q', '--ignore-unmatch', '--', ...payload.paths]);
+    }
+}
+/**
+ * Throws away work-tree changes: tracked files return to their staged content, untracked files are
+ * deleted. Staged content is never touched, so a staged change survives a discard.
+ */
+export async function discardWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    const others = await git(rootReal, ['--literal-pathspecs', 'ls-files', '--others', '--exclude-standard', '-z', '--', ...payload.paths]);
+    const untracked = new Set(others.split('\0').filter((path) => path.length > 0));
+    const tracked = payload.paths.filter((path) => !untracked.has(path));
+    if (tracked.length > 0) {
+        await git(rootReal, ['--literal-pathspecs', 'restore', '--worktree', '--', ...tracked]);
+    }
+    for (const path of untracked) {
+        const target = resolve(rootReal, path);
+        // The parent must resolve inside the workspace, so a symlinked directory cannot redirect the delete.
+        assertInsideRoot(rootReal, join(await realpath(dirname(target)), basename(target)));
+        if ((await lstat(target)).isDirectory())
+            throw new GitWorkspaceError('invalid_workspace_path', path);
+        await unlink(target);
+    }
+}
+function assertWorkspacePaths(paths) {
+    for (const relativePath of paths) {
+        if (!workspaceRelativePathSchema.safeParse(relativePath).success) {
+            throw new GitWorkspaceError('invalid_workspace_path', relativePath);
+        }
+    }
+}
 export async function readWorkspaceGitDiff(root) {
     const rootReal = await ensureWorkspaceGit(root);
     const vsHead = await gitAllowFail(rootReal, ['diff', '--no-color', 'HEAD']);
@@ -92,12 +173,11 @@ function splitLogLine(line) {
 }
 export async function commitWorkspaceGit(root, payload) {
     const rootReal = await ensureWorkspaceGit(root);
-    if (payload.paths && payload.paths.length > 0) {
-        for (const relativePath of payload.paths) {
-            if (!workspaceRelativePathSchema.safeParse(relativePath).success) {
-                throw new GitWorkspaceError('invalid_workspace_path', relativePath);
-            }
-        }
+    if (payload.stagedOnly) {
+        // The index is the commit; nothing is added.
+    }
+    else if (payload.paths && payload.paths.length > 0) {
+        assertWorkspacePaths(payload.paths);
         await git(rootReal, ['add', '--', ...payload.paths]);
     }
     else {
@@ -202,6 +282,28 @@ function parsePorcelain(raw) {
     }
     return files;
 }
+/**
+ * `diff --numstat -z`: `added<TAB>removed<TAB>path<NUL>`, or for a rename an empty path followed by
+ * `old<NUL>new<NUL>`. Binary files report `-` and are left out.
+ */
+function parseNumstat(raw) {
+    const counts = new Map();
+    const parts = raw.split('\0');
+    for (let index = 0; index < parts.length; index += 1) {
+        const match = /^(\d+|-)\t(\d+|-)\t(.*)$/s.exec(parts[index] ?? '');
+        if (!match)
+            continue;
+        let path = match[3];
+        if (path === '') {
+            path = parts[index + 2] ?? '';
+            index += 2;
+        }
+        if (match[1] === '-' || !path)
+            continue;
+        counts.set(path, { added: Number(match[1]), removed: Number(match[2]) });
+    }
+    return counts;
+}
 async function git(root, args, timeoutMs = 15000) {
     const result = await gitAllowFail(root, args, timeoutMs);
     if (result.code !== 0) {
@@ -227,17 +329,18 @@ function gitEnv() {
 function runGitProcess(cwd, args, timeoutMs) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', args, { cwd, env: gitEnv(), windowsHide: true });
-        let stdout = '';
-        let stderr = '';
+        // Chunks are decoded together; a character split across two chunks would otherwise be corrupted.
+        const stdout = [];
+        const stderr = [];
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
             reject(new GitWorkspaceError('git_command_failed', 'timeout'));
         }, timeoutMs);
         child.stdout.on('data', (chunk) => {
-            stdout += String(chunk);
+            stdout.push(Buffer.from(chunk));
         });
         child.stderr.on('data', (chunk) => {
-            stderr += String(chunk);
+            stderr.push(Buffer.from(chunk));
         });
         child.on('error', (error) => {
             clearTimeout(timer);
@@ -249,7 +352,11 @@ function runGitProcess(cwd, args, timeoutMs) {
         });
         child.on('close', (code) => {
             clearTimeout(timer);
-            resolve({ stdout, stderr, code: code ?? 1 });
+            resolve({
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                code: code ?? 1,
+            });
         });
     });
 }

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

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { isLocalWorkspaceGitAuthMode, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { prepareWorkspaceCheckout } from './prepare.js';
 import { WorkspaceContextError } from './context-error.js';
+import { scheduleDependencyInstall } from './dependencies.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId) {
@@ -112,6 +113,8 @@ 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);
         return binding;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.2",
-    "@playcraft/common": "^0.1.2",
+    "@playcraft/build": "^0.1.4",
+    "@playcraft/common": "^0.1.4",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",