@playcraft/cli 0.1.34 → 0.1.36-beta1

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

@@ -1,236 +0,0 @@
-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, } 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(() => undefined);
-    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');
-    }
-}
-/** 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(() => undefined);
-    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) {
-    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 (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));
-        }
-        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/revisions.js

@@ -1,31 +0,0 @@
-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);
-}

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

@@ -1,40 +0,0 @@
-import { lstat, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { launcherSocket, runDeveloperCommand } from './developer-command.js';
-import { shareWorkspaceRepository } from './git.js';
-/**
- * Directories under `.git` this process cannot write: another user created them without group
- * write. Only their owner can change that, so they are reported rather than fixed here.
- */
-export async function foreignUnwritableGitDirectories(root) {
-    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
-    const found = [];
-    const visit = async (path) => {
-        const stat = await lstat(path).catch(() => undefined);
-        if (!stat?.isDirectory())
-            return;
-        if (stat.uid !== uid && (stat.mode & 0o020) === 0)
-            found.push(path);
-        for (const entry of await readdir(path).catch(() => []))
-            await visit(join(path, entry));
-    };
-    await visit(join(root, '.git'));
-    return found;
-}
-/**
- * Prepares a workspace repository for a Git write by this process: new directories become group
- * writable, and directories the development user already made without group write are opened by
- * that user through the launcher. Without a launcher (local runs) both users are the same.
- */
-export async function shareWorkspaceGit(state, root) {
-    await shareWorkspaceRepository(root).catch(() => undefined);
-    if (!launcherSocket(state) || !(await foreignUnwritableGitDirectories(root)).length)
-        return;
-    await runDeveloperCommand(state, {
-        processId: `git-share-${Date.now().toString(36)}`,
-        cwd: root,
-        command: 'find .git -type d -uid "$(id -u)" ! -perm -g+w -exec chmod g+ws {} +',
-        timeoutMs: 30_000,
-        onOutput: () => undefined,
-    }).catch(() => undefined);
-}

package/dist/workspace-runtime/workspaces/skill-artifact-loader.js

@@ -1,91 +0,0 @@
-import { createHash } from 'node:crypto';
-import { workspaceRoot } from './registry.js';
-import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
-const MAX_ARTIFACT_BYTES = 80 * 1024 * 1024;
-/** Requests an exact locked artifact using control identity; no storage credentials reach Codex. */
-export async function loadWorkspaceSkillArtifact(state, workspaceId, entry, directoryName = 'basic') {
-    await workspaceRoot(state, workspaceId, directoryName);
-    return requestWorkspaceSkillArtifact(state, workspaceId, entry);
-}
-async function requestWorkspaceSkillArtifact(state, workspaceId, entry) {
-    const epoch = state.runtimeEpoch;
-    if (state.journal.destroyed())
-        throw new Error('workspace_skills_unavailable');
-    const endpoint = platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts);
-    const response = await fetch(endpoint, {
-        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
-        headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
-        body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation,
-            runtimeEpoch: epoch, workspaceId, entryKey: entry.entryKey, revision: entry.revision }),
-    });
-    if (!response.ok || !response.body)
-        throw new Error('workspace_skills_artifact_unavailable');
-    const reader = response.body.getReader(), chunks = [];
-    let total = 0;
-    try {
-        while (true) {
-            const chunk = await reader.read();
-            if (chunk.done)
-                break;
-            total += chunk.value.byteLength;
-            if (total > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) + 4096)
-                throw new Error('workspace_skills_artifact_too_large');
-            chunks.push(chunk.value);
-        }
-    }
-    finally {
-        await reader.cancel().catch(() => undefined);
-    }
-    const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-    if (typeof result.content !== 'string' || result.artifactHash !== entry.revision.artifactHash
-        || result.content.length > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) || result.content.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(result.content))
-        throw new Error('workspace_skills_digest_mismatch');
-    const archive = Buffer.from(result.content, 'base64');
-    if (archive.byteLength > MAX_ARTIFACT_BYTES || archive.toString('base64') !== result.content || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
-        throw new Error('workspace_skills_unavailable');
-    return archive;
-}
-/** The platform independently authorizes the trusted binding, including an unpublished checkout. */
-export function workspacePlatformSkillAccess(state, workspaceId) {
-    return {
-        resolve: async (skillRefs) => {
-            const epoch = state.runtimeEpoch;
-            if (state.journal.destroyed())
-                throw new Error('workspace_skills_unavailable');
-            const response = await fetch(`${platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts)}/resolve`, {
-                method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
-                headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
-                body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation,
-                    runtimeEpoch: epoch, workspaceId, skillRefs }),
-            });
-            if (!response.ok) {
-                await response.body?.cancel();
-                throw new Error('workspace_skills_platform_unavailable');
-            }
-            if (!response.body)
-                throw new Error('workspace_skills_platform_unavailable');
-            const reader = response.body.getReader(), chunks = [];
-            let total = 0;
-            try {
-                while (true) {
-                    const part = await reader.read();
-                    if (part.done)
-                        break;
-                    total += part.value.byteLength;
-                    if (total > 1024 * 1024)
-                        throw new Error('workspace_skills_platform_unavailable');
-                    chunks.push(part.value);
-                }
-            }
-            finally {
-                await reader.cancel().catch(() => undefined);
-            }
-            if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
-                throw new Error('workspace_skills_unavailable');
-            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-        },
-        loadArtifact: entry => requestWorkspaceSkillArtifact(state, workspaceId, entry),
-    };
-}

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

@@ -1,189 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-import { load } from 'js-yaml';
-import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
-import { initializeLocalProjectSkills } from '../../project-skills/local-store.js';
-import { resolveCliPackageRoot } from '../../scaffold/compose.js';
-import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import.js';
-import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
-import { excludeFromGit } from './dependencies.js';
-/** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
-export async function readWorkspaceSkillSnapshot(root) {
-    const management = await lstat(join(root, '.playcraft'));
-    const declaration = join(root, '.playcraft/skills.json');
-    const stat = await lstat(declaration);
-    if (!management.isDirectory() || management.isSymbolicLink() || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
-        throw new Error('workspace_skills_invalid');
-    return validateProjectSkillsSnapshot(await readFile(declaration, 'utf8'), await readProjectSkillsLockFile(root));
-}
-/** Existing managed projects keep their exact selection. Legacy source folders are adopted once. */
-export async function ensureWorkspaceSkills(root, cache, access) {
-    await excludeFromGit(root, '/.playcraft/skills/');
-    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
-    const raw = await readProjectSkillsLockFile(root);
-    if (raw !== null) {
-        await readWorkspaceSkillSnapshot(root);
-        return;
-    }
-    const inventory = await inspectProjectSkills(root);
-    if (inventory.issues.length)
-        throw new Error('workspace_skills_invalid');
-    const names = new Set(inventory.discovered.map(entry => basename(entry.root)));
-    const platformNames = EMPTY_WORKSPACE_PLATFORM_SKILLS.filter(name => !names.has(name));
-    const selected = platformNames.length ? await selectPlatformSkillSnapshot(platformNames, access) : undefined;
-    const added = new Set();
-    await initializeLocalProjectSkills(root, cache, { enabledRoots: added, platform: selected,
-        prepareSources: async () => {
-            for (const name of EMPTY_WORKSPACE_REPOSITORY_SKILLS) {
-                if (names.has(name))
-                    continue;
-                await safeDirectory(root, '.agents/skills');
-                const source = `.agents/skills/${name}`;
-                await mkdir(join(root, source), { mode: 0o755 });
-                added.add(source);
-                const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
-                for (const child of await readdir(template))
-                    await cp(join(template, child), join(root, source, child), {
-                        recursive: true, force: false, errorOnExist: true,
-                    });
-            }
-        },
-        rollbackSources: async () => {
-            for (const source of added)
-                await rm(join(root, source), { recursive: true, force: true });
-        },
-    });
-}
-async function safeDirectory(root, path) {
-    let current = root;
-    for (const segment of path.split('/')) {
-        current = join(current, segment);
-        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(current);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
-            throw new Error('workspace_skills_invalid');
-    }
-    return current;
-}
-/** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
-async function lockedFiles(root, cache, entry, view, loadArtifact) {
-    const persistent = await safeDirectory(root, '.playcraft/skill-artifacts');
-    const saved = join(persistent, `${entry.revision.artifactHash}.tar.gz`);
-    const path = join(cache, `${entry.revision.artifactHash}.tar.gz`);
-    let archive;
-    try {
-        const stat = await lstat(saved);
-        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
-            throw new Error('workspace_skills_invalid_bundle');
-        archive = await readFile(saved);
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-        try {
-            archive = await readFile(path);
-        }
-        catch (cacheError) {
-            if (cacheError.code !== 'ENOENT')
-                throw cacheError;
-            const declaration = view.declaration.entries.find(item => item.entryKey === entry.entryKey);
-            if (entry.revision.kind === 'source' && declaration.source.kind === 'repository') {
-                const source = await readProjectSkillSource(root, declaration);
-                if (source.sourceTreeHash !== entry.sourceTreeHash)
-                    throw new Error('workspace_skills_source_changed');
-                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
-            }
-            else {
-                if (!loadArtifact)
-                    throw new Error('workspace_skills_artifact_unavailable');
-                archive = await loadArtifact(entry);
-            }
-        }
-    }
-    if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    const extracted = extractBundleArchive(archive);
-    if (extracted.issues.length)
-        throw new Error('workspace_skills_invalid_bundle');
-    if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    const temporary = `${saved}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
-        await rename(temporary, saved);
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
-    return extracted.files;
-}
-function metadata(entryKey, content) {
-    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
-    const parsed = frontmatter ? load(frontmatter[1]) : {};
-    const data = parsed && typeof parsed === 'object' ? parsed : {};
-    return { entryKey, name: typeof data.name === 'string' ? data.name : entryKey,
-        description: typeof data.description === 'string' ? data.description : '', content };
-}
-export async function readWorkspaceSkills(root, cache, loadArtifact) {
-    const snapshot = await readWorkspaceSkillSnapshot(root);
-    const skills = await Promise.all(snapshot.lock.entries.map(async (entry) => {
-        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
-        const body = files.find(file => file.path === 'SKILL.md');
-        if (!body)
-            throw new Error('workspace_skills_body_missing');
-        return metadata(entry.entryKey, body.data.toString('utf8'));
-    }));
-    return { ...snapshot, lockHash: createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex'), skills };
-}
-/** Read-only task generation lives outside source discovery and is omitted from Git/snapshots. */
-export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
-    const snapshot = await readWorkspaceSkillSnapshot(root);
-    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
-    const base = await safeDirectory(root, '.playcraft/skills');
-    const lockHash = createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex');
-    const generation = await safeDirectory(base, lockHash);
-    const skills = [];
-    const expectedFiles = new Set();
-    for (const entry of entries) {
-        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
-        for (const file of files) {
-            const target = join(generation, entry.entryKey, file.path);
-            const relative = join(entry.entryKey, file.path);
-            expectedFiles.add(relative);
-            await safeDirectory(generation, dirname(relative));
-            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
-                if (error.code !== 'EEXIST')
-                    throw error;
-                const stat = await lstat(target);
-                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
-                    throw new Error('workspace_skills_digest_mismatch');
-            });
-        }
-        const body = files.find(file => file.path === 'SKILL.md');
-        if (!body)
-            throw new Error('workspace_skills_body_missing');
-        const info = metadata(entry.entryKey, body.data.toString('utf8'));
-        skills.push({ name: info.name, description: info.description, skillRef: entry.revision.skillRef,
-            revision: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
-            path: join(generation, entry.entryKey, 'SKILL.md') });
-    }
-    const verifyTree = async (directory, relative = '') => {
-        for (const item of await readdir(directory, { withFileTypes: true })) {
-            const path = join(relative, item.name);
-            if (item.isSymbolicLink())
-                throw new Error('workspace_skills_invalid_bundle');
-            if (item.isDirectory()) {
-                if (![...expectedFiles].some(file => file.startsWith(`${path}/`)))
-                    throw new Error('workspace_skills_invalid_bundle');
-                await verifyTree(join(directory, item.name), path);
-            }
-            else if (!item.isFile() || !expectedFiles.has(path))
-                throw new Error('workspace_skills_invalid_bundle');
-        }
-    };
-    await verifyTree(generation);
-    return { declarationHash: snapshot.lock.declarationHash,
-        lockHash, skills };
-}