@playcraft/cli 0.1.9 → 0.1.10

package/README.md

@@ -141,6 +141,17 @@ playcraft login --url https://your-playcraft.example.com
 
 登录成功后，`tools`、`recommend`、`fix-ids` 等所有需要后端 API 的命令均无需额外配置，直接使用。
 
+账号提示待激活时，使用同一目标环境及已保存的个人访问令牌主动激活：
+
+```bash
+playcraft login --activate
+playcraft login --activate --url https://your-playcraft.example.com
+```
+
+也可通过 `PLAYCRAFT_TOKEN` 提供个人访问令牌。激活只发送一次请求，成功后重新执行原业务命令；该动作不会打开浏览器或续签令牌。目标服务须已接入身份服务的激活入口；封禁、停用账号及沙箱执行令牌不能用于激活。
+
+若本地、全局或环境变量配置冲突，激活会要求明确指定 `--url`、所需的 `PLAYCRAFT_ENV` 和对应的个人访问令牌。
+
 ### 沙箱环境（CI / Agent）
 
 在沙箱或 CI 中可通过 `.playcraft.json` 或环境变量配置：

package/dist/auth/account-activation.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadGlobalConfig } from '../config.js';
+import { accountActivationMessage } from './messages.js';
+export const ACCOUNT_PENDING_ACTIVATION = 'account_pending_activation';
+export class AccountActivationError extends Error {
+    code;
+    status;
+    retryable = false;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AccountActivationError';
+    }
+}
+export function responseErrorCode(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const { error, code } = payload;
+    return typeof error?.code === 'string' ? error.code : typeof code === 'string' ? code : undefined;
+}
+export function pendingAccountActivationError(status, payload) {
+    return status === 403 && responseErrorCode(payload) === ACCOUNT_PENDING_ACTIVATION
+        ? new AccountActivationError(ACCOUNT_PENDING_ACTIVATION, `${ACCOUNT_PENDING_ACTIVATION}: ${accountActivationMessage('pending')}`, status)
+        : undefined;
+}
+export function parseErrorPayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function localActivationConfig() {
+    for (const path of [
+        join(process.cwd(), '.playcraft.json'),
+        '/project/.playcraft.json',
+        join(homedir(), '.playcraft.json'),
+    ]) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const config = JSON.parse(readFileSync(path, 'utf8'));
+            if (config && typeof config === 'object' && !Array.isArray(config))
+                return config;
+        }
+        catch {
+            // Follow the existing local credential lookup when a file is unreadable.
+        }
+    }
+    return {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function activationBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new Error();
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        throw new AccountActivationError('INVALID_ACTIVATION_TARGET', accountActivationMessage('invalidTarget'));
+    }
+}
+function savedTokenForTarget(config, rawUrl, target, environment) {
+    if (!rawUrl || (stringValue(config.env)?.trim() || '') !== environment)
+        return undefined;
+    try {
+        return activationBaseUrl(rawUrl) === target ? stringValue(config.token) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizedSavedUrl(raw) {
+    try {
+        return raw ? activationBaseUrl(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function activateAccount(options, defaultBaseUrl) {
+    const local = localActivationConfig();
+    const global = loadGlobalConfig();
+    const localUrl = stringValue(local.apiUrl);
+    const globalUrl = stringValue(global.backendUrl) || stringValue(global.url);
+    const explicitUrl = options.url || process.env.PLAYCRAFT_API_URL || process.env.PLAYCRAFT_URL;
+    const target = activationBaseUrl(explicitUrl || localUrl || globalUrl || defaultBaseUrl);
+    const explicitToken = options.token || process.env.PLAYCRAFT_TOKEN || process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const savedUrls = [normalizedSavedUrl(localUrl), normalizedSavedUrl(globalUrl)].filter(Boolean);
+    const savedTokens = [stringValue(local.token), stringValue(global.token)].filter(Boolean);
+    const environmentsConflict = savedUrls.length === 2 &&
+        savedUrls[0] === savedUrls[1] &&
+        (stringValue(local.env)?.trim() || '') !== (stringValue(global.env)?.trim() || '');
+    const environmentTokensConflict = process.env.PLAYCRAFT_TOKEN &&
+        process.env.PLAYCRAFT_SANDBOX_TOKEN &&
+        process.env.PLAYCRAFT_TOKEN !== process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const environmentUrlsConflict = process.env.PLAYCRAFT_API_URL &&
+        process.env.PLAYCRAFT_URL &&
+        normalizedSavedUrl(process.env.PLAYCRAFT_API_URL) !==
+            normalizedSavedUrl(process.env.PLAYCRAFT_URL);
+    if ((!explicitUrl && new Set(savedUrls).size > 1) ||
+        (!explicitToken && new Set(savedTokens).size > 1) ||
+        (environmentsConflict && !process.env.PLAYCRAFT_ENV) ||
+        (environmentTokensConflict && !options.token) ||
+        (environmentUrlsConflict && !options.url)) {
+        throw new AccountActivationError('AMBIGUOUS_ACTIVATION_TARGET', accountActivationMessage('ambiguous'));
+    }
+    const environment = (process.env.PLAYCRAFT_ENV ||
+        (!explicitUrl ? (localUrl ? stringValue(local.env) : stringValue(global.env)) : '') ||
+        '').trim();
+    const token = explicitToken ||
+        savedTokenForTarget(local, localUrl, target, environment) ||
+        savedTokenForTarget(global, globalUrl, target, environment);
+    if (!token)
+        throw new AccountActivationError('AUTH_REQUIRED', accountActivationMessage('missingToken'));
+    if (!/^playcraft_pat_[A-Za-z0-9_-]{32}$/.test(token)) {
+        throw new AccountActivationError('INVALID_ACTIVATION_TOKEN', accountActivationMessage('invalidToken'));
+    }
+    let response;
+    try {
+        response = await fetch(`${target}/api/settings/personal-access-tokens/activate`, {
+            method: 'POST',
+            redirect: 'error',
+            signal: AbortSignal.timeout(30_000),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(environment ? { 'playcraft-env': environment } : {}),
+            },
+        });
+    }
+    catch {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'));
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new AccountActivationError('ACTIVATION_FAILED', accountActivationMessage('failed'), response.status);
+    }
+    const result = await response.json().catch(() => undefined);
+    if (!result ||
+        typeof result !== 'object' ||
+        result.accountStatus !== 'active') {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'), response.status);
+    }
+    console.log(accountActivationMessage('success'));
+}

package/dist/auth/messages.js

@@ -0,0 +1,30 @@
+const messages = {
+    en: {
+        activateOption: 'Explicitly activate the account using the current personal access token',
+        tokenOption: 'Personal access token for --activate (or use PLAYCRAFT_TOKEN)',
+        pending: 'Account activation is required. Run `playcraft login --activate` with the same token and target environment, then rerun your command.',
+        success: 'Account activated. Rerun your original command to continue.',
+        missingToken: 'No personal access token matches this target environment. Provide PLAYCRAFT_TOKEN or log in to this environment first.',
+        invalidToken: 'Account activation requires a personal access token. A sandbox token cannot activate an account.',
+        ambiguous: 'Activation credentials or target environments conflict. Specify --url, PLAYCRAFT_ENV when needed, and an explicit personal access token using --token or PLAYCRAFT_TOKEN.',
+        invalidTarget: 'Use a web service base address (http:// or https://) without credentials, a query, or a fragment.',
+        failed: 'Account activation failed. Check the target environment and token before trying again.',
+        unavailable: 'Account activation could not be confirmed. Check your account status before explicitly trying again.',
+    },
+    zh: {
+        activateOption: '明确使用当前个人访问令牌激活账号',
+        tokenOption: '用于 --activate 的个人访问令牌（也可使用 PLAYCRAFT_TOKEN）',
+        pending: '账号需要激活。请使用同一令牌和目标环境主动运行 `playcraft login --activate`，然后重新执行原命令。',
+        success: '账号已激活，请重新执行原命令继续。',
+        missingToken: '没有与目标环境匹配的个人访问令牌。请提供 PLAYCRAFT_TOKEN，或先登录此环境。',
+        invalidToken: '激活账号需要个人访问令牌，沙箱令牌不能用于激活账号。',
+        ambiguous: '激活凭据或目标环境存在冲突。请明确指定 --url、所需的 PLAYCRAFT_ENV，并通过 --token 或 PLAYCRAFT_TOKEN 提供个人访问令牌。',
+        invalidTarget: '激活目标必须是网页服务基址（http:// 或 https://），不能包含凭据、查询参数或片段。',
+        failed: '账号激活失败，请检查目标环境和令牌后再尝试。',
+        unavailable: '无法确认账号是否已激活。请先检查账号状态，再主动决定是否重试。',
+    },
+};
+export function accountActivationMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/commands/login.js

@@ -2,6 +2,7 @@ import http from 'http';
 import { exec } from 'child_process';
 import crypto from 'crypto';
 import { saveGlobalConfig, loadGlobalConfig } from '../config.js';
+import { activateAccount } from '../auth/account-activation.js';
 /** 默认云端 Portal（Next.js `/cli-auth` 与 API 同源时的基址；可通过 --url 或 PLAYCRAFT_URL 覆盖） */
 export const DEFAULT_PLAYCRAFT_CLOUD_BASE = 'https://playcraft.aix.intlgame.com';
 const CALLBACK_PORT = 3456;
@@ -100,6 +101,10 @@ export async function renewExistingToken(options) {
     }
 }
 export async function loginCommand(options) {
+    if (options.activate) {
+        await activateAccount(options, DEFAULT_PLAYCRAFT_CLOUD_BASE);
+        return;
+    }
     const backendUrl = resolveLoginBaseUrl(options);
     const callbackPort = options.callbackPort ?? CALLBACK_PORT;
     const globalConfig = loadGlobalConfig();

package/dist/commands/workspace-runtime.js

@@ -14,7 +14,7 @@ export async function runWorkspaceRuntimeServe(configPath) {
         return;
     }
     try {
-        const runtime = await startWorkspaceRuntime(config);
+        const runtime = await startWorkspaceRuntime(config, { configPath });
         console.log(JSON.stringify({
             status: 'listening',
             url: runtime.url,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { accountActivationMessage } from './auth/messages.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -66,6 +67,8 @@ program
     .command('login')
     .description('登录 PlayCraft 账号并获取 CLI token')
     .option('--url <url>', 'Portal / API 基址（默认 https://playcraft.aix.intlgame.com，可用环境变量 PLAYCRAFT_URL 覆盖）')
+    .option('--activate', accountActivationMessage('activateOption'))
+    .option('--token <token>', accountActivationMessage('tokenOption'))
     .action(async (options) => {
     const { loginCommand } = await import('./commands/login.js');
     await loginCommand(options);

package/dist/utils/agent-api-client.js

@@ -5,6 +5,7 @@ import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
 import { beginToolOperation } from './tool-operation-journal.js';
+import { AccountActivationError, parseErrorPayload, pendingAccountActivationError, } from '../auth/account-activation.js';
 /**
  * 判断 token 是否为用户 PAT（Personal Access Token）。
  * PAT 以 "playcraft_pat_" 开头；沙箱 JWT 为三段式 base64。
@@ -86,6 +87,14 @@ export class AgentApiClient {
                 signal: AbortSignal.timeout(30_000),
             });
             if (!capabilityResponse.ok) {
+                if (capabilityResponse.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await capabilityResponse.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
                 await capabilityResponse.body?.cancel();
                 throw new ToolRequestError(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
             }
@@ -108,6 +117,14 @@ export class AgentApiClient {
             });
             if (res.headers.get(AGENT_TOOL_OPERATION_HEADERS.protocol) !== AGENT_TOOL_OPERATION_PROTOCOL ||
                 res.headers.get(AGENT_TOOL_OPERATION_HEADERS.requestId) !== operation.requestId) {
+                if (res.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await res.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
                 await res.body?.cancel();
                 // Possibly an instance that ignores identities: a rerun may only read the receipt.
                 operation.requireReceipt();
@@ -115,6 +132,9 @@ export class AgentApiClient {
             }
             if (!res.ok) {
                 const text = await res.text().catch(() => res.statusText);
+                const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+                if (pending)
+                    throw pending;
                 const code = errorCode(text);
                 if (res.status === 409 && code === 'business_operation_in_progress')
                     throw new ToolRequestError(`API 409: ${text}\nTool request ${operation.requestId} is still running. Rerun the ` +
@@ -141,7 +161,7 @@ export class AgentApiClient {
             return result;
         }
         catch (error) {
-            if (error instanceof ToolRequestError)
+            if (error instanceof ToolRequestError || error instanceof AccountActivationError)
                 throw error;
             throw new Error(`${error instanceof Error ? error.message : String(error)}\n${operation.settledOnly
                 ? `Tool request ${operation.requestId}; record: ${operation.file}. Its settled result is not available yet.`
@@ -164,6 +184,9 @@ export class AgentApiClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => res.statusText);
+            const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
             throw new Error(`API ${res.status}: ${text}`);
         }
         return res.json();

package/dist/utils/playcraft-http-client.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { pendingAccountActivationError } from '../auth/account-activation.js';
 export class PlayCraftApiError extends Error {
     code;
     status;
@@ -95,19 +96,20 @@ export class PlayCraftHttpClient {
                 }
                 if (!response.ok) {
                     const error = payload?.error;
-                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
-                    const message = typeof error?.message === 'string'
+                    const pending = pendingAccountActivationError(response.status, payload);
+                    const code = pending?.code ?? (typeof error?.code === 'string' ? error.code : statusCode(response.status));
+                    const message = pending?.message ?? (typeof error?.message === 'string'
                         ? error.message
                         : typeof payload?.message === 'string'
                             ? payload.message
                             : typeof payload === 'string'
                                 ? payload
-                                : response.statusText || 'PlayCraft request failed';
+                                : response.statusText || 'PlayCraft request failed');
                     throw new PlayCraftApiError({
                         code,
                         message,
                         status: response.status,
-                        details: error?.details ?? payload,
+                        details: pending ? { loginCommand: 'playcraft login --activate' } : error?.details ?? payload,
                         retryable: response.status >= 500,
                     });
                 }

package/dist/utils/tool-operation-journal.js

@@ -56,8 +56,10 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
         createdAt: now,
         updatedAt: now,
     };
+    let createdNew = false;
     try {
         writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
+        createdNew = true;
     }
     catch (error) {
         if (error.code !== 'EEXIST')
@@ -81,6 +83,8 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
         update({ holder });
     return {
         requestId,
+        /** This call created the identity; a refusal cannot settle an older unknown operation. */
+        createdNew,
         /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
         settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
         file,

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

@@ -58,7 +58,7 @@ export async function runPreviewPublish(state, operation, root) {
     const outputDir = join(root, OUTPUT_FOLDER, operation.operationId);
     const output = { log: '' };
     try {
-        await ensureDependencies(state, workspaceId, root);
+        await ensureDependencies(state, workspaceId, root, output);
         await excludeFromGit(root, `/${OUTPUT_FOLDER}/`);
         await excludeFromGit(root, `/${BUILDER_TEMP_FOLDER}/`);
         await buildPreview(state, root, outputDir, operation.operationId, output);
@@ -137,11 +137,13 @@ export function previewFailureCode(error) {
  * Codex added since the workspace opened is installed first. A running install is joined rather
  * than started twice; a failed one is retried once here.
  */
-async function ensureDependencies(state, workspaceId, root) {
+async function ensureDependencies(state, workspaceId, root, output) {
     await scheduleDependencyInstall(state, workspaceId, root);
-    const status = readDependencies(state, workspaceId).status;
-    if (status !== 'ready' && status !== 'none')
+    const dependencies = readDependencies(state, workspaceId);
+    if (dependencies.status !== 'ready' && dependencies.status !== 'none') {
+        output.log = [dependencies.error, dependencies.logTail].filter(Boolean).join('\n');
         throw new PreviewFailure('dependencies_not_ready');
+    }
 }
 async function buildPreview(state, root, outputDir, operationId, output) {
     // Tests replace the build; the real one needs a project and the published CLI.

package/dist/workspace-runtime/serve.js

@@ -33,11 +33,15 @@ export async function startWorkspaceRuntime(config, options = {}) {
     try {
         journal = new RuntimeJournal(config.stateDir);
         await journal.load();
+        const previousEpoch = journal.storedRuntimeEpoch();
+        const previousGroup = journal.executionGroup();
+        const previousIdentityMatches = journal.epochsSnapshot().some((epoch) => epoch.runtime_id === config.runtimeId && epoch.generation === config.generation && epoch.runtime_epoch === previousEpoch);
         await recoverInterruptedInstalls(journal);
         await recoverInterruptedPreviews(journal);
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
         const state = {
             config: { ...config, protocolMinor: negotiated.protocolMinor },
+            configPath: options.configPath,
             journal,
             acceptedLeaseFence: journal.acceptedLeaseFence(),
             gitAvailable: await probeGitBinary(),
@@ -63,8 +67,28 @@ export async function startWorkspaceRuntime(config, options = {}) {
         try {
             await native?.start?.();
             const group = native?.executionProcess?.();
-            if (group)
-                await journal.noteExecutionGroup(group);
+            if (group) {
+                let previousStopped = false;
+                if (previousGroup.pid && previousGroup.pid !== group.pid) {
+                    try {
+                        process.kill(previousGroup.pid, 0);
+                    }
+                    catch (error) {
+                        previousStopped = error.code === 'ESRCH';
+                    }
+                }
+                // The supervisor advances the trusted config epoch only after stopping the old
+                // native group. Reconfirm its recorded PID before publishing that replacement.
+                if (previousIdentityMatches && previousEpoch !== undefined && config.runtimeEpoch > previousEpoch && previousStopped) {
+                    await journal.writeExecutionEpoch({
+                        runtimeEpoch: state.runtimeEpoch, ...group, previousPid: previousGroup.pid, stopConfirmed: true,
+                    });
+                    await journal.replaceSessions(journal.listSessions().map((session) => ({ ...session, recoverability: 'history_only' })));
+                }
+                else {
+                    await journal.noteExecutionGroup(group);
+                }
+            }
         }
         catch (error) {
             const code = error instanceof Error ? error.message : '';

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

@@ -767,7 +767,7 @@ async function executeTerminalCreate(state, scopeKey, operation, payload) {
 }
 /** The branch a registered workspace is bound to; the single-workspace mode has none. */
 function boundBranch(state, operation) {
-    return operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId)?.branchName : undefined;
+    return operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId)?.branchName ?? undefined : undefined;
 }
 function gitErrorCode(error) {
     return error instanceof GitWorkspaceError ? error.code : 'git_command_failed';

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

@@ -0,0 +1,19 @@
+import { chmod, rename, writeFile } from 'node:fs/promises';
+import { applySandboxEndpointPatch } from '@playcraft/common/cloud-workspace/runtime';
+/** Persist the new addresses, then publish them to the running process. A restart is not required. */
+export async function applyRuntimeEndpointPatch(state, patch) {
+    const next = applySandboxEndpointPatch(state.config, patch);
+    const changed = next.callbackUrl !== state.config.callbackUrl || next.modelProxyUrl !== state.config.modelProxyUrl;
+    const result = { changed, callbackUrl: next.callbackUrl, modelProxyUrl: next.modelProxyUrl };
+    if (!changed)
+        return result;
+    if (!state.configPath) {
+        throw new Error('endpoint_config_path_missing');
+    }
+    const temporary = `${state.configPath}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, state.configPath);
+    state.config = next;
+    return result;
+}

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

@@ -3,6 +3,7 @@ import { registerWorkspace, revisionScope, workspaceRoot, WorkspaceContextError
 import { randomUUID } from 'node:crypto';
 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 { applyRuntimeEndpointPatch } from './endpoints.js';
 import { canExecuteKind, executeOperation } from './dispatch.js';
 import { InvalidWorkspacePathError, listWorkspaceFiles, } from '../workspaces/files.js';
 import { materializeRemoteSnapshot } from '../workspaces/file-snapshot.js';
@@ -61,6 +62,15 @@ export async function handleRuntimeRequest(state, request, response) {
             writeJson(response, 200, { workspaceId: binding.workspaceId, status: 'registered' });
             return;
         }
+        if (request.method === 'POST' && url.pathname === '/runtime/endpoints') {
+            try {
+                writeJson(response, 200, await applyRuntimeEndpointPatch(state, await readJson(request)));
+            }
+            catch {
+                writeError(response, runtimeError('invalid_config', 'endpoint_patch_rejected'));
+            }
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/handshake') {
             writeJson(response, 200, handshake(state));
             return;
@@ -101,7 +111,11 @@ export async function handleRuntimeRequest(state, request, response) {
         if (request.method === 'GET' && url.pathname === '/runtime/files') {
             if (writeDestroyed(state, response))
                 return;
-            writeJson(response, 200, await listWorkspaceFiles(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined), state.journal.fileRevisions(revisionScope(state, url.searchParams.get('workspaceId') ?? undefined))));
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            const root = await workspaceRoot(state, workspaceId);
+            const listed = await listWorkspaceFiles(root, state.journal.fileRevisions(revisionScope(state, workspaceId)));
+            console.log(`[workspace-files] GET /runtime/files workspaceId=${workspaceId ?? '-'} root=${root} files=${listed.files.length}`);
+            writeJson(response, 200, listed);
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/file') {

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

@@ -77,6 +77,8 @@ export class WorkspaceGitCredentialBroker {
     }
     async configure(binding, preparation) {
         preparation = workspacePreparationSchema.parse(preparation);
+        if (binding.targetKind === 'standalone' || preparation.mode !== 'clone')
+            throw new Error('git_access_denied');
         const transport = preparation.transport;
         const isDirect = isLocalWorkspaceGitAuthMode(preparation.authMode);
         if (!isDirect && transport?.kind !== 'git-gateway-v2')
@@ -118,7 +120,7 @@ export class WorkspaceGitCredentialBroker {
             || typeof input.path !== 'string')
             throw new Error('git_access_denied');
         const binding = this.state.journal.getWorkspace(input.workspaceId);
-        if (!binding)
+        if (!binding || binding.targetKind === 'standalone')
             throw new Error('git_access_denied');
         const cloneUrl = `${input.protocol}://${input.host}/${input.path}`;
         const direct = await this.direct.get(binding);
@@ -177,6 +179,8 @@ export class WorkspaceGitCredentialBroker {
             throw new Error('git_broker_unavailable');
         }
         const preparation = workspacePreparationSchema.parse(await response.json());
+        if (preparation.mode !== 'clone')
+            throw new Error('git_access_denied');
         const matched = preparation.transport && matchWorkspaceGitGatewayCloneUrl(preparation.transport.cloneUrl, this.state.config.gitGatewayOrigins, binding.repositoryUrl);
         if (this.closed || this.state.journal.destroyed() || this.state.runtimeEpoch !== epoch
             || JSON.stringify(this.state.journal.getWorkspace(binding.workspaceId)) !== JSON.stringify(binding)

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

@@ -4,15 +4,19 @@ import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs
 import { join } from 'node:path';
 import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceContextError } from './context-error.js';
-/** The caller holds the Workspace lock. Only an absent, never-published checkout may be cloned. */
+/** The caller holds the Workspace lock. Only an absent, never-published directory may be prepared. */
 export async function prepareWorkspaceCheckout(state, binding, input, leaseFence) {
     const preparation = workspacePreparationSchema.safeParse(input);
     if (!preparation.success)
         throw new WorkspaceContextError('invalid_workspace_preparation');
-    const source = parseCloneSource(binding.repositoryUrl);
-    const direct = isLocalWorkspaceGitAuthMode(preparation.data.authMode);
-    if (direct && (!isLocalWorkspaceGitEnvironment(state.config.environment) || !preparation.data.directAccess
-        || preparation.data.directAccess.repositoryUrl !== binding.repositoryUrl))
+    const standalone = binding.targetKind === 'standalone';
+    if (standalone !== (preparation.data.mode === 'empty'))
+        throw new WorkspaceContextError('invalid_workspace_preparation');
+    const clone = preparation.data.mode === 'clone' ? preparation.data : undefined;
+    const source = binding.repositoryUrl ? parseCloneSource(binding.repositoryUrl) : undefined;
+    const direct = isLocalWorkspaceGitAuthMode(clone?.authMode);
+    if (direct && (!isLocalWorkspaceGitEnvironment(state.config.environment) || !clone?.directAccess
+        || clone.directAccess.repositoryUrl !== binding.repositoryUrl))
         throw new WorkspaceContextError('workspace_git_gateway_unavailable');
     const parent = await realpath(state.config.workspaceRoot);
     const target = join(parent, binding.workspaceId);
@@ -42,15 +46,15 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         await writeReceipt(receiptPath, receipt);
         await rm(staging, { recursive: true, force: true });
         await mkdir(staging, { mode: 0o700 });
-        const access = preparation.data.gitAccess;
-        const credential = preparation.data.directAccess ?? access;
+        const access = clone?.gitAccess;
+        const credential = clone?.directAccess ?? access;
         const now = Date.now();
         if (access &&
             (Date.parse(access.issuedAt) > now || Date.parse(access.expiresAt) <= now + 10_000)) {
             await rm(staging, { recursive: true, force: true });
             throw new WorkspaceContextError('workspace_git_access_expired');
         }
-        const transport = preparation.data.transport;
+        const transport = clone?.transport;
         if (transport && !matchWorkspaceGitGatewayCloneUrl(transport.cloneUrl, state.config.gitGatewayOrigins, binding.repositoryUrl).ok) {
             await rm(staging, { recursive: true, force: true });
             throw new WorkspaceContextError('workspace_git_gateway_unavailable');
@@ -76,20 +80,25 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
             }
         }
         try {
-            await runGit(['check-ref-format', '--branch', binding.branchName], env, deadline);
-            await runGit([
-                'clone',
-                '--no-checkout',
-                '--single-branch',
-                '--branch',
-                binding.branchName,
-                '--',
-                binding.repositoryUrl,
-                staging,
-            ], env, deadline);
-            // Checkout never receives the temporary credential and never invokes repository hooks or global filters.
-            clearCloneSecrets(env);
-            await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
+            if (standalone) {
+                await runGit(['init', '--initial-branch=main', staging], env, deadline);
+            }
+            else {
+                await runGit(['check-ref-format', '--branch', binding.branchName], env, deadline);
+                await runGit([
+                    'clone',
+                    '--no-checkout',
+                    '--single-branch',
+                    '--branch',
+                    binding.branchName,
+                    '--',
+                    binding.repositoryUrl,
+                    staging,
+                ], env, deadline);
+                // Checkout never receives the temporary credential and never invokes repository hooks or global filters.
+                clearCloneSecrets(env);
+                await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
+            }
             assertCurrent();
             receipt.status = 'ready';
             await writeReceipt(receiptPath, receipt);

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

@@ -46,7 +46,7 @@ async function checkedDirectory(state, workspaceId) {
         throw new WorkspaceContextError('workspace_not_prepared');
     }
 }
-/** Registers a fixed checkout; optional first creation is restricted to its trusted binding. */
+/** Registers a fixed directory; optional first creation is restricted to its trusted binding. */
 export async function registerWorkspace(state, input, leaseFence, preparation) {
     if (state.config.workspaceMode !== 'multi')
         throw new WorkspaceContextError('multi_workspace_unavailable');
@@ -87,9 +87,18 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
             },
         })).stdout.trim();
         try {
-            if ((await realpath(await git('rev-parse', '--show-toplevel'))) !== root ||
-                (await git('config', '--get', 'remote.origin.url')) !== binding.repositoryUrl ||
-                (await git('symbolic-ref', '--short', 'HEAD')) !== binding.branchName) {
+            let checkoutMatches;
+            if (binding.targetKind === 'standalone') {
+                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');
             }
         }
@@ -102,7 +111,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
             throw new WorkspaceContextError('runtime_destroyed');
         if (leaseFence < state.acceptedLeaseFence)
             throw new WorkspaceContextError('stale_lease');
-        if (preparation?.transport?.kind === 'git-gateway-v2' || isLocalWorkspaceGitAuthMode(preparation?.authMode)) {
+        if (preparation?.mode === 'clone' && (preparation.transport?.kind === 'git-gateway-v2' || isLocalWorkspaceGitAuthMode(preparation.authMode))) {
             if (!state.gitCredentials)
                 throw new WorkspaceContextError('workspace_git_gateway_unavailable');
             try {

package/package.json

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

package/project-template-v2/.playcraft/skills.lock.json

@@ -4,147 +4,147 @@
     {
       "skillRef": "platform/playcraft-3d-flip-sprite",
       "version": "1.0.0",
-      "artifactHash": "bfea71413bf9f0b57eda4c79c1c9e5d73061becaf9c1ece066ffcc32890ad1ea",
+      "artifactHash": "95183007861a4dae5b67440ea9beed1c360eb616d17e4aa04b97383cc2b63516",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-3d-flip-sprite"
     },
     {
       "skillRef": "platform/playcraft-asset-management",
       "version": "1.0.0",
-      "artifactHash": "11ae4c6b1e9e9cb8639e22cfc9568f70cc7fc526bb9632e601e2886ba50fb0f3",
+      "artifactHash": "27209dba24f6e1851dc83682fbd24165894c802794c797cac32d8871f740cf14",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-asset-management"
     },
     {
       "skillRef": "platform/playcraft-build",
       "version": "1.0.0",
-      "artifactHash": "7fbd4ba060efc9409e8da9aa7d4edfe2cdb2734de7a497b79299a7061cacf3ac",
+      "artifactHash": "2ca96916041bcc04ee48e827599dd819072e67a626bf59a1c20281f337e4063a",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-build"
     },
     {
       "skillRef": "platform/playcraft-code-editor",
       "version": "1.0.0",
-      "artifactHash": "4db2b7e60762ba0ccc249ea4023dcb81701dac38d54af0e6757b5337ea489a32",
+      "artifactHash": "abcc9aafe2b15adb8de62eb89921dbcb35c7dc634055b937fe34bdf83ca6685d",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-code-editor"
     },
     {
       "skillRef": "platform/playcraft-create-remix",
       "version": "1.0.0",
-      "artifactHash": "76f7cfd4b7441184805e07550f687651225a3baf27e306f0ee7c4347e58f3f19",
+      "artifactHash": "8d2a4d4d096433ccec090f1003c050471ddfbc50d69c1c0c66f88424b52bacf6",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-create-remix"
     },
     {
       "skillRef": "platform/playcraft-deploy",
-      "version": "1.0.0",
-      "artifactHash": "e619cee8bea40b2a0c9b69a02d387369a3628a73c0a0504b3c92b1330bc12e86",
+      "version": "1.0.1",
+      "artifactHash": "31ac7f90d93606eb40c2113d56204e09b97ecd9e49b910b2ce05445b824ccfdc",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-deploy"
     },
     {
       "skillRef": "platform/playcraft-iteration-methodology",
-      "version": "1.0.0",
-      "artifactHash": "42c5219f6f8a8d63787efeef6da8522cf7400442dc75dc8dee6d0c49b0ed28b7",
+      "version": "1.1.0",
+      "artifactHash": "f67a2f1806e08a48a903408383a06802622da3760d24d72a0dcbbea202349be2",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-iteration-methodology"
     },
     {
       "skillRef": "platform/playcraft-platform-intro",
       "version": "1.0.0",
-      "artifactHash": "d32001cff62516d343707fdbe4812ed9dde6651c749f2aadc848d06196f07c15",
+      "artifactHash": "b37f6b0515a79822f5f69519fcddd1182d420b90eb9ba40298bb1ed73eced281",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-platform-intro"
     },
     {
       "skillRef": "platform/playcraft-prefab",
       "version": "1.0.0",
-      "artifactHash": "7089e5b346ce99dbc25f61e2645e67fce057e6a108445975c99a03b062c84007",
+      "artifactHash": "a4a991302922d6846a2e313dc4cd4514f54820040dc2166ccc864803053c1ea5",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-prefab"
     },
     {
       "skillRef": "platform/playcraft-project-management",
       "version": "1.0.0",
-      "artifactHash": "32459786cdd17ece2df094be1f13387802325191531939c40c1ddfde3590a17b",
+      "artifactHash": "e7e4bffe80e0737362a5cac4234056a7d7fb048f0c8b5e41041e61ee914495e3",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-project-management"
     },
     {
       "skillRef": "platform/playcraft-remix-workflow",
-      "version": "1.0.0",
-      "artifactHash": "07a25c34042dabbde9a166d4e49c977dd8b2459eff27c9c1bc9cafe0a56a08ef",
+      "version": "1.0.1",
+      "artifactHash": "23807ff591b4bd08c87daa4e9b2c9900b0505e4f2f601c47de51a96d6ebbed19",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-remix-workflow"
     },
     {
       "skillRef": "platform/playcraft-save",
-      "version": "1.0.0",
-      "artifactHash": "100d6d66ac449bc8b7f183b8165587bcef6bb5d138d2ddfa07035f229275bc3d",
+      "version": "1.0.1",
+      "artifactHash": "6d42c681f91f849603bf3c4f235411ea05189a0d5e3ca1d3a8f92b69e536bdd1",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-save"
     },
     {
       "skillRef": "platform/playcraft-template-upgrade-merge",
       "version": "1.0.0",
-      "artifactHash": "459e87e02c45b5a859d1c79daf0c53cd7ee9426d6d55ef8d1156a052e557a52f",
+      "artifactHash": "354da60f395f3eb7a267db667783344f54567e12abcfec454b269193a5af1cb6",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-template-upgrade-merge"
     },
     {
       "skillRef": "platform/sound-effects",
       "version": "1.0.0",
-      "artifactHash": "3a2235197c23ca5b38c46fbb0ff1686f509c094ba206f199f78cdd5f1a07aa95",
+      "artifactHash": "a6ba7ea91ddbf4f5a04ae8340a69c3725c5d97b239e8636bf64886928e8dd1da",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__sound-effects"
     },
     {
       "skillRef": "remix/playcraft-adsdk",
       "version": "1.0.0",
-      "artifactHash": "9b2e784b167372c6d3e14a3636dac2af8cf64af46c1bef1e082b77c0db51a9c2",
+      "artifactHash": "0de877b122246ed5c665a893f8dc408282007d0950b0f6c44876f87ceddb519f",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-adsdk"
     },
     {
       "skillRef": "remix/playcraft-audio-generation",
       "version": "1.0.0",
-      "artifactHash": "0f171e4e739d3b1a5b1f00a0b20cf13d0897c69c9d4e30dd3477acd6b982c8c8",
+      "artifactHash": "8d1b035b289545ca8fd6c247b9417bf34bddf5a26b31e114c35d001aa3a9ebf0",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-audio-generation"
     },
     {
       "skillRef": "remix/playcraft-dist-publish",
       "version": "1.0.0",
-      "artifactHash": "0c2396be7fed8b1a0fa2990eee2a23ed9b6abe02ead68c15648f45de7c11e254",
+      "artifactHash": "9a00acc9b3b6f140f276032b722bbe7bbf3a9b1fa61fe71cb65913ebcd118772",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-dist-publish"
     },
     {
       "skillRef": "remix/playcraft-image-generation",
       "version": "1.0.0",
-      "artifactHash": "a7bd5e50c62250f9c84c600239a57d71f197b88d4dedfa9eec6befc10cb4239a",
+      "artifactHash": "91bec2422c750d9d47d5be2796ec5aaffb48de561f2c2d8b92112f37d576f489",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-generation"
     },
     {
       "skillRef": "remix/playcraft-image-processing",
       "version": "1.0.0",
-      "artifactHash": "137ce0b8b76d591148dc0158b5e38abc2fc17f04471fc0d027b0a19d3dde709d",
+      "artifactHash": "d845c067bed103c3d1d3f145b1cb8246ffbd6a9ae91efcfbce2eae456819212d",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-processing"
     },
     {
       "skillRef": "remix/playcraft-prefab",
       "version": "1.0.0",
-      "artifactHash": "eb1de9851f842e475bb2ae8bb239d5f9b5ab6bd28fe0c83ae96d8570e1a8b814",
+      "artifactHash": "3cce28f5b67398fffaaa6295d27cf514c8e1e1e998d142524facaff7d2c25561",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-prefab"
     },
     {
       "skillRef": "remix/playcraft-remix-workflow",
       "version": "1.0.0",
-      "artifactHash": "cf5ed218579d49887d6bf2c5f4eb7512ea86684984f57546676df2d6378cd054",
+      "artifactHash": "e2a59c61ef5b094a821fbbab3b0f65f906bfc0dfda6f3d8c0b33a6f460dd0963",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-remix-workflow"
     }