@playcraft/cli 0.1.1 → 0.1.3

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

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 import { writePlaycraftCodexConfig } from './config-toml.js';
 import { createJsonRpcStdioClient } from './jsonrpc-stdio.js';
 import { projectNativeThread } from '@playcraft/common/cloud-workspace/runtime';
-import { collectedEvent } from './native-adapter.js';
+import { collectedEvent, NativePreparationError } from './native-adapter.js';
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -74,8 +74,20 @@ export function createCodexAppServerAdapter(options) {
         startPromise ??= start();
         await startPromise;
     }
+    async function threadConfig(cwd) {
+        try {
+            return await options.modelBroker?.threadConfig(cwd) ?? {};
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : '';
+            throw new NativePreparationError(['model_config_required', 'model_callback_insecure',
+                'model_credential_scope_mismatch', 'workspace_not_registered'].includes(reason)
+                ? reason : 'model_credential_unavailable');
+        }
+    }
     async function start() {
-        const token = await readToken(options);
+        await options.modelBroker?.start();
+        const token = options.modelBroker ? 'workspace-broker-managed' : await readToken(options);
         const bin = options.command || process.env.PLAYCRAFT_CODEX_BIN || (launcherSocket ? '/usr/local/bin/codex' : 'codex');
         const { command, prefix } = spawnCommand(bin);
         const args = [...prefix, ...(options.args ?? ['app-server'])];
@@ -98,7 +110,9 @@ export function createCodexAppServerAdapter(options) {
                 processId: `codex-${randomUUID()}`,
                 runtimeEpoch: executionEpoch,
                 argv: [command, ...args],
-                cwd: options.config.workspaceRoot,
+                // The launcher admits the dev home, not the shared /workspaces root.
+                // Each thread supplies its registered workspace separately.
+                cwd: options.config.workspaceMode === 'multi' ? '/home/playcraft-dev' : options.config.workspaceRoot,
                 env: { CODEX_HOME: homeDir, OPENAI_API_KEY: token },
             });
         }
@@ -230,7 +244,8 @@ export function createCodexAppServerAdapter(options) {
             if (!rpc)
                 return false;
             try {
-                const result = await rpc.request('thread/resume', { threadId: input.threadId, cwd: input.cwd }, 30_000);
+                const result = await rpc.request('thread/resume', { threadId: input.threadId, cwd: input.cwd,
+                    ...await threadConfig(input.cwd ?? '') }, 30_000);
                 const resumedId = result.thread?.id ?? result.threadId;
                 if (resumedId !== input.threadId)
                     return false;
@@ -275,6 +290,7 @@ export function createCodexAppServerAdapter(options) {
             const result = await rpc.request('thread/start', {
                 cwd: input.cwd,
                 model,
+                ...await threadConfig(input.cwd),
             });
             const threadId = result.thread?.id;
             if (!threadId)
@@ -356,6 +372,7 @@ export function createCodexAppServerAdapter(options) {
                 await current.stop();
             child = undefined;
             live = undefined;
+            await options.modelBroker?.close();
         },
     };
 }

package/dist/workspace-runtime/codex/model-broker.js

@@ -0,0 +1,183 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { basename } from 'node:path';
+import { z } from 'zod';
+import { workspaceRoot } from '../workspaces/registry.js';
+const credentialSchema = z.object({
+    token: z.string().min(1), expiresAt: z.string().datetime(),
+    configId: z.string().uuid(), model: z.string().min(1).max(128),
+    claims: z.object({
+        environment: z.string(), userId: z.string(), workspaceId: z.string(), runtimeId: z.string(),
+        generation: z.number().int(), runtimeEpoch: z.number().int(),
+    }),
+});
+/** Keeps renewable execution credentials in control memory, outside Codex and project files. */
+export class WorkspaceModelBroker {
+    state;
+    server;
+    baseUrl = '';
+    entries = new Map();
+    pending = new Map();
+    requests = new Set();
+    constructor(state) {
+        this.state = state;
+    }
+    async start() {
+        if (this.server)
+            return;
+        const server = createServer({ maxHeaderSize: 8192 }, (request, response) => {
+            void this.forward(request, response);
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', resolve);
+        });
+        this.server = server;
+        const address = server.address();
+        if (!address || typeof address === 'string')
+            throw new Error('model_broker_unavailable');
+        this.baseUrl = `http://127.0.0.1:${address.port}`;
+    }
+    async threadConfig(cwd) {
+        const workspaceId = basename(cwd);
+        if (!this.server || await workspaceRoot(this.state, workspaceId) !== cwd)
+            throw new Error('workspace_not_registered');
+        let entry = this.entries.get(workspaceId);
+        if (!entry || entry.epoch !== this.state.runtimeEpoch) {
+            entry = { workspaceId, epoch: this.state.runtimeEpoch, capability: randomBytes(32).toString('base64url') };
+            this.entries.set(workspaceId, entry);
+        }
+        const credential = await this.credential(entry);
+        return {
+            model: credential.model,
+            modelProvider: 'playcraft_workspace',
+            config: {
+                'model_providers.playcraft_workspace': {
+                    name: 'PlayCraft Workspace', base_url: `${this.baseUrl}/${workspaceId}`,
+                    wire_api: 'responses', requires_openai_auth: false,
+                    http_headers: { Authorization: `Bearer ${entry.capability}` },
+                },
+            },
+        };
+    }
+    valid(entry) {
+        return Boolean(this.server && !this.state.journal.destroyed()
+            && this.state.runtimeEpoch === entry.epoch && this.state.journal.getWorkspace(entry.workspaceId)
+            && this.entries.get(entry.workspaceId) === entry);
+    }
+    async credential(entry) {
+        if (!this.valid(entry))
+            throw new Error('model_access_denied');
+        if (entry.credential && Date.parse(entry.credential.expiresAt) > Date.now() + 60_000)
+            return entry.credential;
+        let pending = this.pending.get(entry);
+        if (!pending) {
+            pending = this.renew(entry).finally(() => this.pending.delete(entry));
+            this.pending.set(entry, pending);
+        }
+        return pending;
+    }
+    async renew(entry) {
+        const config = this.state.config;
+        const endpoint = new URL('/runtime/internal/model-credentials', config.callbackUrl);
+        if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:'
+            && ['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname)))
+            throw new Error('model_callback_insecure');
+        const response = await fetch(endpoint, {
+            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000),
+            headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation,
+                runtimeEpoch: entry.epoch, workspaceId: entry.workspaceId }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.reason === 'model_config_required' ? 'model_config_required' : 'model_credential_unavailable');
+        }
+        const credential = credentialSchema.parse(await response.json());
+        const claims = credential.claims;
+        if (!this.valid(entry) || claims.workspaceId !== entry.workspaceId || claims.runtimeId !== config.runtimeId
+            || claims.userId !== config.userId || claims.environment !== config.environment
+            || claims.generation !== config.generation || claims.runtimeEpoch !== entry.epoch
+            || Date.parse(credential.expiresAt) <= Date.now() + 1000)
+            throw new Error('model_credential_scope_mismatch');
+        entry.credential = credential;
+        return credential;
+    }
+    async forward(request, response) {
+        const abort = new AbortController();
+        this.requests.add(abort);
+        const cancel = () => abort.abort();
+        response.once('close', cancel);
+        try {
+            const match = /^\/([0-9a-f-]{36})\/responses$/.exec(request.url ?? '');
+            const entry = match && this.entries.get(match[1]);
+            const presented = Buffer.from(request.headers.authorization ?? '');
+            const expected = Buffer.from(entry ? `Bearer ${entry.capability}` : '');
+            if (request.method !== 'POST' || !entry || !expected.length || presented.length !== expected.length
+                || !timingSafeEqual(presented, expected) || !this.valid(entry)) {
+                response.writeHead(403);
+                response.end();
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of request) {
+                size += chunk.length;
+                if (size > 16 * 1024 * 1024) {
+                    response.writeHead(413);
+                    response.end();
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+            const credential = await this.credential(entry);
+            if (!this.valid(entry))
+                throw new Error('model_access_denied');
+            const expires = setTimeout(cancel, Math.max(0, Date.parse(credential.expiresAt) - Date.now()));
+            try {
+                const upstream = await fetch(`${this.state.config.modelProxyUrl.replace(/\/+$/, '')}/v1/${credential.configId}/responses`, {
+                    method: 'POST', redirect: 'error', signal: abort.signal,
+                    headers: { authorization: `Bearer ${credential.token}`, 'content-type': 'application/json' },
+                    body: Buffer.concat(chunks),
+                });
+                if (upstream.status === 401 || upstream.status === 403)
+                    entry.credential = undefined;
+                response.writeHead(upstream.status, {
+                    'content-type': upstream.headers.get('content-type') ?? 'application/json', 'cache-control': 'no-store',
+                });
+                if (upstream.body)
+                    await pipeline(Readable.fromWeb(upstream.body), response);
+                else
+                    response.end();
+            }
+            finally {
+                clearTimeout(expires);
+            }
+        }
+        catch {
+            if (!response.headersSent) {
+                response.writeHead(503, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+                response.end(JSON.stringify({ error: { message: 'model_credential_unavailable', type: 'server_error' } }));
+            }
+            else
+                response.destroy();
+        }
+        finally {
+            response.off('close', cancel);
+            this.requests.delete(abort);
+        }
+    }
+    async close() {
+        const server = this.server;
+        this.server = undefined;
+        this.entries.clear();
+        for (const request of this.requests)
+            request.abort();
+        if (server) {
+            server.closeAllConnections();
+            await new Promise(resolve => server.close(() => resolve()));
+        }
+    }
+}

package/dist/workspace-runtime/codex/native-adapter.js

@@ -1,3 +1,6 @@
+/** Failure before a native request was sent; safe to report as failed instead of uncertain. */
+export class NativePreparationError extends Error {
+}
 export function nativeEvent(type, payload) {
     return { type, payload, occurredAt: new Date().toISOString() };
 }

package/dist/workspace-runtime/serve.js

@@ -13,6 +13,7 @@ import { handleExecutionGroupCrash } from './server/execution-group.js';
 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';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -31,17 +32,17 @@ export async function startWorkspaceRuntime(config, options = {}) {
         journal = new RuntimeJournal(config.stateDir);
         await journal.load();
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
-        const native = options.nativeAdapter ?? defaultNativeAdapter(config);
         const state = {
             config: { ...config, protocolMinor: negotiated.protocolMinor },
             journal,
             acceptedLeaseFence: journal.acceptedLeaseFence(),
             gitAvailable: await probeGitBinary(),
-            native,
+            native: options.nativeAdapter,
             runtimeEpoch: Math.max(config.runtimeEpoch, journal.storedRuntimeEpoch() ?? 0),
             executionQueue: Promise.resolve(),
             instanceToken: randomUUID(),
         };
+        const native = state.native ??= defaultNativeAdapter(state);
         await journal.bindRuntime({
             runtimeId: config.runtimeId,
             generation: config.generation,
@@ -61,8 +62,10 @@ export async function startWorkspaceRuntime(config, options = {}) {
             if (group)
                 await journal.noteExecutionGroup(group);
         }
-        catch {
-            /* conversation stays adapter_not_started until Codex handshake succeeds */
+        catch (error) {
+            const code = error instanceof Error ? error.message : '';
+            state.nativeError = code === 'model_proxy_token_missing' ? code : 'codex_start_failed';
+            console.error(`[workspace-runtime] ${state.nativeError}`);
         }
         const server = createServer((request, response) => {
             void handleRuntimeRequest(state, request, response);
@@ -135,11 +138,16 @@ function closeServer(server) {
 function formatHost(host) {
     return host.includes(':') ? `[${host}]` : host;
 }
-function defaultNativeAdapter(config) {
+function defaultNativeAdapter(state) {
+    const config = state.config;
     if (process.env.PLAYCRAFT_NATIVE_ADAPTER === 'loopback')
         return createLoopbackNativeAdapter();
-    if (process.env.PLAYCRAFT_NATIVE_ADAPTER === 'codex') {
-        return createCodexAppServerAdapter({ config });
+    const managed = config.workspaceMode === 'multi' && Boolean(process.env.PLAYCRAFT_LAUNCHER_SOCKET);
+    if (process.env.PLAYCRAFT_NATIVE_ADAPTER === 'codex'
+        || (!process.env.PLAYCRAFT_NATIVE_ADAPTER && managed)) {
+        return createCodexAppServerAdapter({ config,
+            ...(managed ? { modelBroker: new WorkspaceModelBroker(state) } : {}),
+        });
     }
     return undefined;
 }

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

@@ -2,11 +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';
@@ -25,6 +26,9 @@ const LOCAL_KINDS = new Set([
     'file.write',
     'git.commit',
     'git.push',
+    'git.stage',
+    'git.unstage',
+    'git.discard',
     'terminal.create',
     'parameter.patch',
 ]);
@@ -87,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);
     }
@@ -117,10 +124,19 @@ async function executeScopedOperation(state, scopeKey, operation, payload) {
 }
 async function executeCreate(state, scopeKey, operation) {
     const sessionId = required(operation.sessionId, 'sessionId');
-    const started = await native(state).startThread({
-        sessionId,
-        cwd: await workspaceRoot(state, operation.workspaceId),
-    });
+    let started;
+    try {
+        started = await native(state).startThread({
+            sessionId,
+            cwd: await workspaceRoot(state, operation.workspaceId),
+        });
+    }
+    catch (error) {
+        if (error instanceof NativePreparationError) {
+            return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: error.message }));
+        }
+        throw error;
+    }
     if (!started.threadId) {
         return persist(state, scopeKey, transitionOperation(operation, 'uncertain', { error: 'native_receipt_lost' }));
     }
@@ -610,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,12 +1,12 @@
 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 { desktopHost, desktopRoute } from './desktop-host.js';
 import { terminalHost } from './terminal-host.js';
@@ -131,6 +131,15 @@ 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/git/graph') {
             await writeGitRead(state, response, async () => readWorkspaceGitGraph(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
             return;
@@ -211,7 +220,7 @@ function handshake(state) {
         if (item.name === 'conversation') {
             if (conversationReady)
                 return capability('conversation', true);
-            return destroyed ? capability('conversation', false, 'runtime_destroyed') : item;
+            return capability('conversation', false, destroyed ? 'runtime_destroyed' : state.nativeError ?? 'adapter_not_started');
         }
         if (item.name === 'files') {
             return filesReady
@@ -543,7 +552,7 @@ function unavailableReason(state, kind) {
         return 'runtime_destroyed';
     if (kind === 'preview.publish')
         return 'capability_not_implemented';
-    return 'adapter_not_started';
+    return state.nativeError ?? 'adapter_not_started';
 }
 function sessionHistoryPath(pathname) {
     const match = pathname.match(/^\/runtime\/workspaces\/([^/]+)\/sessions\/([^/]+)\/history$/);

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/package.json

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