@playcraft/cli 0.1.36-beta1 → 0.1.38-beta

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

@@ -0,0 +1,251 @@
+import { execFile } from 'node:child_process';
+import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, batchSourceSnapshotSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { prepareWorkspaceCheckout } from './prepare.js';
+import { WorkspaceContextError } from './context-error.js';
+import { scheduleDependencyInstall } from './dependencies.js';
+import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
+import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
+import { writeWorkspaceCliContext } from './cli-context.js';
+import { attachWorkspaceRemote } from './git.js';
+import { ensureWorkspaceArtifactInstructions } from './instructions.js';
+export { WorkspaceContextError } from './context-error.js';
+const exec = promisify(execFile);
+export function revisionScope(state, workspaceId, directoryName = 'basic') {
+    return state.config.workspaceMode === 'multi' ? `${workspaceId}:${directoryName}` : undefined;
+}
+export function workspaceSessions(state, workspaceId, directoryName = 'basic') {
+    return state.journal
+        .listSessions()
+        .filter((item) => state.config.workspaceMode !== 'multi' || (item.workspaceId === workspaceId && (item.directoryName ?? 'basic') === directoryName));
+}
+export async function workspaceRoot(state, workspaceId, directoryName = 'basic') {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    if (!/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    if (directoryName !== 'basic' && !state.journal.getWorkspace(workspaceId)?.directories?.some(directory => directory.directoryName === directoryName))
+        throw new WorkspaceContextError('workspace_directory_not_registered');
+    return checkedDirectory(state, workspaceId, directoryName);
+}
+async function checkedDirectory(state, workspaceId, directoryName = 'basic') {
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const container = join(parent, workspaceId);
+    const containerStat = await lstat(container).catch(error => { throw new WorkspaceContextError('workspace_not_prepared', { cause: error }); });
+    if (!containerStat?.isDirectory() || containerStat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const target = join(container, directoryName);
+    try {
+        const stat = await lstat(target);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            relative(container, await realpath(target)) !== directoryName) {
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        }
+        const stateDir = await realpath(state.config.stateDir);
+        if (stateDir === target || stateDir.startsWith(`${target}/`))
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        return target;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceContextError)
+            throw error;
+        throw new WorkspaceContextError('workspace_not_prepared', { cause: error });
+    }
+}
+/** Registers a fixed directory; optional first creation is restricted to its trusted binding. */
+export async function workspaceContainerRoot(state, workspaceId) {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const container = join(parent, workspaceId);
+    const stat = await lstat(container).catch(error => { throw new WorkspaceContextError('workspace_not_prepared', { cause: error }); });
+    if (!stat?.isDirectory() || stat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const stateDir = await realpath(state.config.stateDir);
+    if (stateDir === container || stateDir.startsWith(`${container}/`))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    return container;
+}
+export async function sessionWorkspaceRoot(state, workspaceId, directoryName = 'basic') {
+    return directoryName === 'root' ? workspaceContainerRoot(state, workspaceId) : workspaceRoot(state, workspaceId, directoryName);
+}
+export async function workspaceContextFromRoot(state, cwd) {
+    const parent = await realpath(state.config.workspaceRoot);
+    const parts = relative(parent, cwd).split('/');
+    if (parts.length !== 1 && parts.length !== 2)
+        throw new WorkspaceContextError('workspace_not_registered');
+    const workspaceId = parts[0];
+    const directoryName = parts.length === 1 ? 'root' : parts[1];
+    if (await sessionWorkspaceRoot(state, workspaceId, directoryName) !== cwd)
+        throw new WorkspaceContextError('workspace_not_registered');
+    return { workspaceId, directoryName };
+}
+export async function registerWorkspace(state, input, leaseFence, preparation, readOnlyBasic = false, sourceSnapshot) {
+    if (state.config.workspaceMode !== 'multi')
+        throw new WorkspaceContextError('multi_workspace_unavailable');
+    const parsed = workspaceRegistrationSchema.safeParse(input);
+    if (!parsed.success)
+        throw new WorkspaceContextError('invalid_workspace_registration');
+    const binding = parsed.data;
+    return state.journal.exclusive(`workspace:${binding.workspaceId}`, async () => {
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        state.acceptedLeaseFence = leaseFence;
+        await state.journal.setAcceptedLeaseFence(leaseFence);
+        const existing = state.journal.getWorkspace(binding.workspaceId);
+        const preservedLocalBasic = binding.targetKind !== 'standalone' && binding.preserveLocalBasic === true;
+        const localUpgrade = preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
+        // A standalone workspace promoted to a project's main keeps its checkout and gains that remote.
+        const remoteUpgrade = !preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
+        if (existing && !sameWorkspaceRegistration(existing, binding) && !localUpgrade && !remoteUpgrade)
+            throw new WorkspaceContextError('workspace_binding_conflict');
+        const attachMarker = join(state.config.stateDir, 'workspace-remote-attach', `${binding.workspaceId}.json`);
+        const existingByDir = new Map((existing?.directories ?? []).map(item => [item.directoryName, item]));
+        const directories = binding.directories
+            ? binding.directories.map(item => {
+                const local = existingByDir.get(item.directoryName);
+                return local && local.remixId === item.remixId && local.status === 'ready' && item.status === 'pending'
+                    ? { ...item, status: 'ready', sourceCommit: item.sourceCommit ?? local.sourceCommit }
+                    : item;
+            })
+            : existing?.directories;
+        if (sourceSnapshot) {
+            const snapshot = batchSourceSnapshotSchema.parse(sourceSnapshot);
+            if (!readOnlyBasic || snapshot.sourceWorkspaceId !== binding.workspaceId)
+                throw new WorkspaceContextError('invalid_workspace_registration');
+            // Production restores its assigned result from durable bytes, without touching basic.
+            const parent = await realpath(state.config.workspaceRoot);
+            await mkdir(join(parent, binding.workspaceId), { mode: 0o2770 }).catch(error => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            });
+            const registered = { ...binding, directories };
+            await state.journal.putWorkspace(registered);
+            await workspaceContainerRoot(state, binding.workspaceId);
+            return registered;
+        }
+        if (directories?.some(directory => directory.directoryName === 'basic' && directory.status === 'reclaimed')) {
+            // Registration publishes trusted identity. Only an explicit basic ensure restores the checkout.
+            const parent = await realpath(state.config.workspaceRoot);
+            const container = join(parent, binding.workspaceId);
+            await mkdir(container, { mode: 0o2770 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+            const registered = { ...binding, directories };
+            await state.journal.putWorkspace(registered);
+            await workspaceContainerRoot(state, binding.workspaceId);
+            return registered;
+        }
+        let root;
+        try {
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        catch (error) {
+            if (existing && error instanceof WorkspaceContextError && error.message === 'workspace_not_prepared')
+                throw new WorkspaceContextError('workspace_recovery_required');
+            if (!preparation || !(error instanceof WorkspaceContextError) || error.message !== 'workspace_not_prepared')
+                throw error;
+            await prepareWorkspaceCheckout(state, binding, preparation, leaseFence);
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        const git = async (...args) => (await exec('git', ['-C', root, ...args], {
+            timeout: 5000,
+            maxBuffer: 64 * 1024,
+            env: {
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+                GIT_CONFIG_NOSYSTEM: '1',
+                GIT_CONFIG_GLOBAL: '/dev/null',
+            },
+        })).stdout.trim();
+        // Unfinished if it failed part way: the marker outlives the journal entry written below.
+        if (binding.targetKind === 'main' && !preservedLocalBasic && (remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
+            if (preparation?.mode !== 'clone' || !state.gitCredentials)
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
+            await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
+            // The credential helper only serves a workspace the journal knows to be bound.
+            await state.journal.putWorkspace({ ...binding, directories });
+            try {
+                await state.gitCredentials.configure(binding, preparation);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            }
+            try {
+                await attachWorkspaceRemote(root, binding.repositoryUrl, binding.branchName);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_remote_attach_failed');
+            }
+            await rm(attachMarker, { force: true });
+        }
+        try {
+            let checkoutMatches;
+            if (binding.targetKind === 'standalone' || preservedLocalBasic) {
+                const gitDirectory = await lstat(join(root, '.git'));
+                checkoutMatches = gitDirectory.isDirectory() && !gitDirectory.isSymbolicLink()
+                    && (await git('rev-parse', '--absolute-git-dir')) === join(root, '.git')
+                    && (await git('remote')) === '';
+            }
+            else {
+                checkoutMatches = (await git('config', '--get', 'remote.origin.url')) === binding.repositoryUrl
+                    && (await git('symbolic-ref', '--short', 'HEAD')) === binding.branchName;
+            }
+            if ((await realpath(await git('rev-parse', '--show-toplevel'))) !== root || !checkoutMatches) {
+                throw new WorkspaceContextError('workspace_checkout_mismatch');
+            }
+        }
+        catch (error) {
+            if (error instanceof WorkspaceContextError)
+                throw error;
+            throw new WorkspaceContextError('workspace_not_prepared');
+        }
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        if (readOnlyBasic || preservedLocalBasic) {
+            await state.journal.putWorkspace({ ...binding, directories });
+            return binding;
+        }
+        if (preparation?.mode === 'clone' && (preparation.transport?.kind === 'git-gateway-v2' || isLocalWorkspaceGitAuthMode(preparation.authMode))) {
+            if (!state.gitCredentials)
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            try {
+                await state.gitCredentials.configure(binding, preparation);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            }
+        }
+        try {
+            await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), workspacePlatformSkillAccess(state, binding.workspaceId), { optionalPlatformDefaults: true });
+        }
+        catch {
+            throw new WorkspaceContextError('workspace_skills_unavailable');
+        }
+        await writeWorkspaceCliContext(root, binding.workspaceId);
+        await ensureWorkspaceArtifactInstructions(root);
+        await state.journal.putWorkspace({ ...binding, directories });
+        try {
+            await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));
+        }
+        catch { /* Skills reads and native turns diagnose missing artifacts; files and source repair remain available. */ }
+        // Runs in the background; every registration rechecks it, so reopening retries a failed install.
+        void scheduleDependencyInstall(state, revisionScope(state, binding.workspaceId), root);
+        return binding;
+    });
+}

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

@@ -0,0 +1,301 @@
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { WORKSPACE_REMIX_REFERENCE_MAX_BYTES, WORKSPACE_REMIX_REFERENCE_MAX_FILES, WORKSPACE_REMIX_REFERENCES_DIRECTORY, WORKSPACE_REMIX_REFERENCES_MANIFEST, remixReferenceContentHashInput, workspaceDirectoryNameSchema, workspaceRemixReferenceExportSchema, workspaceRemixReferenceSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { isCredentialFile } from './git.js';
+const exec = promisify(execFile);
+const RECEIPT = '.reference.json';
+const ATTRIBUTES = '.gitattributes';
+const SNAPSHOT_ATTRIBUTES = '* -filter -text -ident -working-tree-encoding -eol\n';
+const INERT_DIRECTORY = '_source_metadata';
+const MANIFEST_MAX_BYTES = 16 * 1024 * 1024;
+const EXCLUDED = new Set(['.git', 'node_modules', '.next', '.cache', '.tmp', '.turbo', '.pnpm-store', '.ssh', '.aws']);
+const INERT = new Set(['.agents', '.claude', '.codex', '.cursor', '.playcraft', '.gitignore', '.gitattributes',
+    '.gitmodules', 'agents.md', 'claude.md', 'gemini.md', '.cursorrules', '.mcp.json']);
+const locks = new Map();
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+export class RemixReferenceError extends Error {
+    constructor(code) { super(code); this.name = 'RemixReferenceError'; }
+}
+async function safeDirectory(root, relative = '', create = false) {
+    let current = root;
+    for (const segment of relative.split('/').filter(Boolean)) {
+        current = join(current, segment);
+        if (create)
+            await mkdir(current, { mode: 0o755 }).catch((error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            });
+        const info = await lstat(current);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new RemixReferenceError('remix_reference_path_conflict');
+    }
+    return current;
+}
+async function readFileSafely(root, path, limit) {
+    await safeDirectory(root, dirname(path) === '.' ? '' : dirname(path));
+    const handle = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > limit)
+            throw new RemixReferenceError('remix_reference_changed');
+        const data = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < data.length) {
+            const { bytesRead } = await handle.read(data, length, data.length - length, length);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+        }
+        const after = await handle.stat();
+        if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+            throw new RemixReferenceError('remix_reference_changed');
+        return data.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function identity(snapshot) {
+    const { source, contentHash } = snapshot;
+    return hash(JSON.stringify([source.environment, source.projectUuid, source.branchName, source.commit, contentHash]));
+}
+function referencePath(referenceId, commit) {
+    return `${WORKSPACE_REMIX_REFERENCES_DIRECTORY}/${referenceId.slice(0, 20)}-${commit.slice(0, 12)}`;
+}
+/** Project instructions and Git filters remain readable source material without becoming active configuration. */
+function materializedPath(sourcePath) {
+    const parts = sourcePath.split('/').map(part => part.toLowerCase());
+    if (parts.some(part => EXCLUDED.has(part)) || isCredentialFile(sourcePath) ||
+        parts.some(part => ['.npmrc', '.yarnrc', '.netrc', '.git-credentials'].includes(part)))
+        return undefined;
+    if (parts[0] === INERT_DIRECTORY || parts[0] === RECEIPT)
+        throw new RemixReferenceError('remix_reference_path_conflict');
+    if (parts.some(part => INERT.has(part)))
+        return `${INERT_DIRECTORY}/${hash(sourcePath)}.txt`;
+    return sourcePath;
+}
+async function readManifest(root) {
+    try {
+        const value = JSON.parse((await readFileSafely(root, WORKSPACE_REMIX_REFERENCES_MANIFEST, MANIFEST_MAX_BYTES)).toString('utf8'));
+        if (value?.version !== 1 || !Array.isArray(value.items) || value.items.length > 100)
+            throw new RemixReferenceError('remix_reference_manifest_invalid');
+        const items = value.items.map((item) => workspaceRemixReferenceSchema.parse(item));
+        if (new Set(items.map(item => item.referenceId)).size !== items.length)
+            throw new RemixReferenceError('remix_reference_manifest_invalid');
+        return items;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        if (error instanceof RemixReferenceError)
+            throw error;
+        throw new RemixReferenceError('remix_reference_manifest_invalid');
+    }
+}
+function validateRecord(record, directoryName) {
+    if (record.directoryName !== directoryName || record.referenceId !== identity(record) ||
+        record.path !== referencePath(record.referenceId, record.source.commit) || record.name !== record.source.name)
+        throw new RemixReferenceError('remix_reference_manifest_invalid');
+    const paths = new Set();
+    for (const file of record.files) {
+        if (file.path !== materializedPath(file.sourcePath) || paths.has(file.path.toLowerCase()))
+            throw new RemixReferenceError('remix_reference_manifest_invalid');
+        paths.add(file.path.toLowerCase());
+    }
+    if ((record.omittedFiles ?? []).some(file => materializedPath(file.path) !== undefined))
+        throw new RemixReferenceError('remix_reference_manifest_invalid');
+    const originalFiles = [...record.files.map(file => ({ ...file, path: file.sourcePath })), ...(record.omittedFiles ?? [])];
+    if (originalFiles.length > WORKSPACE_REMIX_REFERENCE_MAX_FILES || new Set(originalFiles.map(file => file.path.toLowerCase())).size !== originalFiles.length ||
+        hash(remixReferenceContentHashInput(originalFiles)) !== record.contentHash ||
+        originalFiles.reduce((sum, file) => sum + file.size, 0) > WORKSPACE_REMIX_REFERENCE_MAX_BYTES)
+        throw new RemixReferenceError('remix_reference_manifest_invalid');
+}
+async function verifyReference(root, record, directoryName) {
+    validateRecord(record, directoryName);
+    const target = await safeDirectory(root, record.path);
+    const receipt = JSON.parse((await readFileSafely(target, RECEIPT, MANIFEST_MAX_BYTES)).toString('utf8'));
+    if (JSON.stringify(workspaceRemixReferenceSchema.parse(receipt)) !== JSON.stringify(record))
+        throw new RemixReferenceError('remix_reference_changed');
+    if ((await readFileSafely(target, ATTRIBUTES, 256)).toString('utf8') !== SNAPSHOT_ATTRIBUTES)
+        throw new RemixReferenceError('remix_reference_changed');
+    const expected = new Set([RECEIPT, ATTRIBUTES, ...record.files.map(file => file.path)]);
+    const walk = async (directory, prefix = '') => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink())
+                throw new RemixReferenceError('remix_reference_changed');
+            if (entry.isDirectory())
+                await walk(await safeDirectory(target, path), path);
+            else if (!entry.isFile() || !expected.delete(path))
+                throw new RemixReferenceError('remix_reference_changed');
+        }
+    };
+    await walk(target);
+    if (expected.size)
+        throw new RemixReferenceError('remix_reference_changed');
+    for (const file of record.files) {
+        const bytes = await readFileSafely(target, file.path, file.size);
+        if (bytes.length !== file.size || hash(bytes) !== file.sha256)
+            throw new RemixReferenceError('remix_reference_changed');
+    }
+}
+/** Reads revalidate the snapshot, so changed/deleted files cannot silently remain attached to a turn. */
+export async function listWorkspaceRemixReferences(root, directoryName = 'basic') {
+    workspaceDirectoryNameSchema.parse(directoryName);
+    const rootReal = await realpath(root);
+    const items = await readManifest(rootReal);
+    for (const item of items)
+        await verifyReference(rootReal, item, directoryName);
+    return items;
+}
+export async function resolveWorkspaceRemixReference(root, directoryName, referenceId, snapshotHash) {
+    workspaceDirectoryNameSchema.parse(directoryName);
+    try {
+        const rootReal = await realpath(root);
+        const item = (await readManifest(rootReal)).find(item => item.referenceId === referenceId);
+        if (!item)
+            throw new RemixReferenceError('context_remix_reference_unavailable');
+        if (item.contentHash !== snapshotHash)
+            throw new RemixReferenceError('context_remix_reference_changed');
+        await verifyReference(rootReal, item, directoryName);
+        return item;
+    }
+    catch (error) {
+        if (error instanceof RemixReferenceError && error.message.startsWith('context_'))
+            throw error;
+        throw new RemixReferenceError('context_remix_reference_changed');
+    }
+}
+async function trackReference(root, record) {
+    const environment = { PATH: process.env.PATH, HOME: root, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0' };
+    const gitOptions = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root];
+    const paths = [WORKSPACE_REMIX_REFERENCES_MANIFEST, `${record.path}/${RECEIPT}`, `${record.path}/${ATTRIBUTES}`,
+        ...record.files.map(file => `${record.path}/${file.path}`)];
+    // Reject higher-priority repository attributes before Git can execute a conversion filter.
+    const attributes = await new Promise((resolve, reject) => {
+        const child = execFile('git', [...gitOptions, 'check-attr', '-z', '--stdin', 'filter', 'text', 'ident', 'working-tree-encoding', 'eol'], {
+            timeout: 60_000, maxBuffer: 40 * 1024 * 1024, env: environment, encoding: 'utf8',
+        }, (error, stdout) => error ? reject(error) : resolve(stdout));
+        child.stdin?.end(`${paths.join('\0')}\0`);
+    });
+    const fields = attributes.split('\0');
+    if (fields.length !== paths.length * 15 + 1)
+        throw new RemixReferenceError('remix_reference_git_attributes');
+    for (let index = 0; index < fields.length - 1; index += 3) {
+        const [path, attribute, value] = fields.slice(index, index + 3);
+        if (path === WORKSPACE_REMIX_REFERENCES_MANIFEST && (attribute === 'text' || attribute === 'eol'))
+            continue;
+        if (value !== 'unset' && value !== 'unspecified')
+            throw new RemixReferenceError('remix_reference_git_attributes');
+    }
+    // A source file may have been tracked despite its old ignore rules. Track this approved snapshot explicitly.
+    await exec('git', [...gitOptions,
+        '--literal-pathspecs', 'add', '--force', '--', record.path, WORKSPACE_REMIX_REFERENCES_MANIFEST], {
+        timeout: 60_000, maxBuffer: 1024 * 1024,
+        env: environment,
+    });
+}
+async function importReference(root, directoryName, input, assertCurrent) {
+    workspaceDirectoryNameSchema.parse(directoryName);
+    const parsed = workspaceRemixReferenceExportSchema.safeParse(input);
+    if (!parsed.success)
+        throw new RemixReferenceError('invalid_remix_reference');
+    const snapshot = parsed.data;
+    if (snapshot.contentHash !== hash(remixReferenceContentHashInput(snapshot.files)))
+        throw new RemixReferenceError('remix_reference_changed');
+    const plannedFiles = snapshot.files.map(file => {
+        const bytes = Buffer.from(file.content, 'base64');
+        if (bytes.toString('base64') !== file.content || bytes.length !== file.size || hash(bytes) !== file.sha256)
+            throw new RemixReferenceError('remix_reference_changed');
+        if (bytes.subarray(0, 128).toString('utf8').startsWith('version https://git-lfs.github.com/spec/v1'))
+            throw new RemixReferenceError('remix_reference_external_resource');
+        return { ...file, bytes, targetPath: materializedPath(file.path) };
+    });
+    const files = plannedFiles.filter(file => file.targetPath !== undefined);
+    if (!files.length)
+        throw new RemixReferenceError('remix_reference_empty');
+    const rootReal = await realpath(root);
+    const referenceId = identity(snapshot);
+    const path = referencePath(referenceId, snapshot.source.commit);
+    const items = await readManifest(rootReal);
+    await safeDirectory(rootReal, '.playcraft', true);
+    let record = items.find(item => item.referenceId === referenceId);
+    if (record) {
+        await verifyReference(rootReal, record, directoryName);
+        assertCurrent();
+        await trackReference(rootReal, record);
+        return record;
+    }
+    if (items.length >= 100)
+        throw new RemixReferenceError('remix_reference_limit');
+    await safeDirectory(rootReal, WORKSPACE_REMIX_REFERENCES_DIRECTORY, true);
+    const target = join(rootReal, path);
+    const existing = await lstat(target).catch((error) => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (existing) {
+        // A complete published directory is its recovery receipt when the process died before writing the manifest.
+        if (!existing.isDirectory() || existing.isSymbolicLink())
+            throw new RemixReferenceError('remix_reference_path_conflict');
+        record = workspaceRemixReferenceSchema.parse(JSON.parse((await readFileSafely(rootReal, `${path}/${RECEIPT}`, MANIFEST_MAX_BYTES)).toString('utf8')));
+        if (record.referenceId !== referenceId)
+            throw new RemixReferenceError('remix_reference_path_conflict');
+        await verifyReference(rootReal, record, directoryName);
+    }
+    else {
+        record = workspaceRemixReferenceSchema.parse({ referenceId, directoryName, path, name: snapshot.source.name,
+            source: snapshot.source, contentHash: snapshot.contentHash, importedAt: new Date().toISOString(),
+            files: files.map(file => ({ path: file.targetPath, sourcePath: file.path, sha256: file.sha256, size: file.size })),
+            omittedFiles: plannedFiles.filter(file => file.targetPath === undefined).map(file => ({ path: file.path, sha256: file.sha256, size: file.size })) });
+        const stage = await mkdtemp(join(dirname(rootReal), '.remix-reference-'));
+        try {
+            for (const file of files) {
+                assertCurrent();
+                await safeDirectory(stage, dirname(file.targetPath) === '.' ? '' : dirname(file.targetPath), true);
+                await writeFile(join(stage, file.targetPath), file.bytes, { flag: 'wx', mode: 0o644 });
+            }
+            await writeFile(join(stage, RECEIPT), JSON.stringify(record), { flag: 'wx', mode: 0o644 });
+            await writeFile(join(stage, ATTRIBUTES), SNAPSHOT_ATTRIBUTES, { flag: 'wx', mode: 0o644 });
+            await chmod(stage, 0o755);
+            assertCurrent();
+            await safeDirectory(rootReal, WORKSPACE_REMIX_REFERENCES_DIRECTORY);
+            if (await lstat(target).catch(() => undefined))
+                throw new RemixReferenceError('remix_reference_path_conflict');
+            await rename(stage, target);
+        }
+        finally {
+            await rm(stage, { recursive: true, force: true });
+        }
+    }
+    const serialized = JSON.stringify({ version: 1, items: [...items, record] });
+    if (Buffer.byteLength(serialized) > MANIFEST_MAX_BYTES)
+        throw new RemixReferenceError('remix_reference_limit');
+    await safeDirectory(rootReal, '.playcraft', true);
+    const temporary = join(rootReal, '.playcraft', `.remix-references-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, serialized, { flag: 'wx', mode: 0o644 });
+        assertCurrent();
+        await safeDirectory(rootReal, '.playcraft');
+        await rename(temporary, join(rootReal, WORKSPACE_REMIX_REFERENCES_MANIFEST));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    await trackReference(rootReal, record);
+    return record;
+}
+export async function importWorkspaceRemixReference(root, directoryName, snapshot, assertCurrent = () => { }) {
+    const previous = locks.get(root) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(() => importReference(root, directoryName, snapshot, assertCurrent));
+    locks.set(root, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (locks.get(root) === current)
+            locks.delete(root);
+    }
+}

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

@@ -0,0 +1,31 @@
+import { readWorkspaceFile } from './files.js';
+import { revisionScope, workspaceRoot } from './registry.js';
+/** Observe native/manual edits before checking an editor's conditional write. */
+export async function withObservedFile(state, workspaceId, path, action, directoryName = 'basic') {
+    const scope = revisionScope(state, workspaceId, directoryName);
+    return state.journal.exclusive(`file:${scope ?? 'single'}:${path}`, async () => {
+        const records = state.journal.fileRevisions(scope);
+        const previous = records[path];
+        let file;
+        try {
+            file = await readWorkspaceFile(await workspaceRoot(state, workspaceId, directoryName), path, records);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const hash = file?.contentHash ?? '';
+        const revision = previous ? previous.revision + (previous.contentHash === hash ? 0 : 1) : 0;
+        if ((!previous && file) || (previous && previous.contentHash !== hash)) {
+            await state.journal.putFileRevision(path, { revision, contentHash: hash }, scope);
+        }
+        return action({ file: file ? { ...file, revision } : undefined, revision });
+    });
+}
+export async function readObservedFile(state, workspaceId, path, directoryName = 'basic') {
+    return withObservedFile(state, workspaceId, path, async ({ file }) => {
+        if (!file)
+            throw Object.assign(new Error('file_not_found'), { code: 'ENOENT' });
+        return file;
+    }, directoryName);
+}