@playcraft/cli 0.0.56 → 0.0.57

package/README.md

@@ -93,23 +93,20 @@ playcraft remix start \
 
 ### 6. 将 Remix 源码 clone 到本地
 
+完整步骤（登录 → clone → commit → push）见：
+
+- [Remix 本地 Clone / Commit / Push](../../docs/cli/remix-local-clone-push.md)
+
 ```bash
 playcraft login
-# 本地开发建议直连 backend，避免经前端代理缓冲 Git pack
-export PLAYCRAFT_API_URL=http://localhost:3001
-
 # 推荐：粘贴 Remix 详情页 / Editor / 工蜂分支页 URL
 playcraft remix clone '<remix-detail-or-editor-or-gongfeng-url>' --install
 
-# 兼容：显式 project + branch
-playcraft remix clone \
-  --project-id <project-id> \
-  --branch remix/your-branch \
-  --install
-
 cd <cloned-dir>
 npm run dev          # external 引擎
-git push             # 经 PlayCraft Git 代理写回 Remix 分支（禁止推 main）
+git add -A && git commit -m "…"
+playcraft remix pull # 需要同步远端时
+playcraft remix push # 不要裸 git push/pull（尤其 Windows）
 ```
 
 完整的 Remix 子命令、参数、图片传输、自动化输出及故障处理说明见：

package/REMIX.md

@@ -24,6 +24,8 @@ playcraft remix start
 playcraft remix prompt
 playcraft remix run
 playcraft remix clone
+playcraft remix pull
+playcraft remix push
 playcraft git-credential
 ```
 
@@ -36,6 +38,8 @@ playcraft git-credential
 | 向已有 Remix 发送需求        | `playcraft remix prompt`                                                        |
 | 创建 Remix 并立即运行 Agent  | `playcraft remix run`                                                           |
 | **Clone Remix 源码到本地**   | `playcraft remix clone <详情页/Editor/工蜂 URL>` 或 `--project-id` + `--branch` |
+| **Pull 远端 Remix**          | `playcraft remix pull`（推荐；Windows 勿直接 `git pull`）                       |
+| **Push 回 Remix 分支**       | `playcraft remix push`（推荐；Windows 勿直接 `git push`）                       |
 | 查询已有 Remix 列表          | `playcraft tools list-remixes`；当前没有 `playcraft remix list`                 |
 | 给本地项目应用引擎模板       | `playcraft remix init-template`                                                 |
 
@@ -725,6 +729,8 @@ playcraft remix start --project-id <project-id> --branch <remix-branch> --open
 
 登录后可将 Remix 源码经 **PlayCraft Backend Git Smart HTTP 代理**克隆到本机，无需工蜂凭据。平台服务账号 Token 不会下发到 CLI。
 
+> **上手文档（推荐先读）**：[Remix 本地 Clone / Commit / Push](../../docs/cli/remix-local-clone-push.md)
+
 ### 14.1 Clone
 
 ```bash
@@ -772,17 +778,23 @@ playcraft remix clone \
 - **external（Phaser / Three.js）**：`npm install && npm run dev`（可用 `--install` / `--dev`）
 - **PlayCanvas**：使用 `playcraft start --project <id>`，不是 Vite
 
-### 14.3 Push 回 Remix
+### 14.3 Pull / Push
 
 在克隆目录内：
 
 ```bash
+# 同步远端（例如沙箱 Save 之后）
+playcraft remix pull
+
+# 本地改完并 commit 后写回
 git add -A
 git commit -m "local changes"
-git push
+playcraft remix push
 ```
 
-服务端强制：
+**不要**依赖裸 `git pull` / `git push`（尤其 Windows + Git Credential Manager 会弹窗）。二者与 clone 一样注入 `Authorization: Bearer`，并禁用本命令的 credential helper。
+
+服务端强制（push）：
 
 - 只能 push 到 URL 对应的 Remix 分支
 - 禁止 push `main` / `master` / 项目默认分支
@@ -791,11 +803,11 @@ git push
 
 ### 14.4 与云端沙箱同时写
 
-同一 Remix 分支若已在沙箱打开并 Save，本机 `git push` 与沙箱 push 会互相覆盖。请避免两边同时写同一分支；push 成功后 backend 会 `BareRepoCache.invalidate`。
+同一 Remix 分支若已在沙箱打开并 Save，本机 `playcraft remix push` 与沙箱 push 会互相覆盖。请避免两边同时写同一分支；需要合并远端时先 `playcraft remix pull`。push 成功后 backend 会 `BareRepoCache.invalidate`。
 
 ### 14.5 `playcraft git-credential`
 
-供本机 `git pull` / `git push` 使用的 credential helper，从 `~/.playcraft/config.json` 读取 PAT。clone 后会自动写入仓库 `credential.helper`。
+clone 后仍可能写入仓库 `credential.helper`（兼容）。**日常请用 `playcraft remix pull` / `push`**，不要手动跑 `git-credential`。
 
 ---
 

package/dist/commands/remix.js

@@ -6,6 +6,8 @@ import { PlayCraftApiError, PlayCraftHttpClient, isPlayCraftApiError } from '../
 import { IMAGE_OPTION_HELP, buildReferenceImagesPrompt, readImageAttachments, uploadImageAttachments, } from '../utils/remix-image-attachments.js';
 import { initTemplateCommand } from '../remix/init-template.js';
 import { remixClone, gitCredentialCommand, isRemoteCloneSource } from '../remix/clone.js';
+import { remixPush } from '../remix/push.js';
+import { remixPull } from '../remix/pull.js';
 // Register autocomplete prompt
 inquirer.registerPrompt('autocomplete', autocomplete);
 const JSON_OUTPUT_HELP = '输出一条 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果';
@@ -1303,12 +1305,56 @@ export function registerRemixCommands(program) {
             handleCommandError('remix.clone', opts, undefined, error);
         }
     });
+    remix
+        .command('push')
+        .description('经 PlayCraft Git 代理推送当前 Remix（注入已登录 PAT，避免 Windows Git Credential Manager 弹窗）')
+        .argument('[git-args...]', '透传给 git push 的参数（可选）')
+        .option('--dir <path>', '仓库目录（默认当前目录）')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action(async (gitArgs, opts) => {
+        try {
+            await remixPush({
+                dir: opts.dir ? String(opts.dir) : undefined,
+                url: opts.url,
+                token: opts.token,
+                json: Boolean(opts.json),
+                gitArgs: Array.isArray(gitArgs) ? gitArgs.map(String) : [],
+            });
+        }
+        catch (error) {
+            handleCommandError('remix.push', opts, undefined, error);
+        }
+    });
+    remix
+        .command('pull')
+        .description('经 PlayCraft Git 代理拉取当前 Remix（注入已登录 PAT，避免 Windows Git Credential Manager 弹窗）')
+        .argument('[git-args...]', '透传给 git pull 的参数（可选）')
+        .option('--dir <path>', '仓库目录（默认当前目录）')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action(async (gitArgs, opts) => {
+        try {
+            await remixPull({
+                dir: opts.dir ? String(opts.dir) : undefined,
+                url: opts.url,
+                token: opts.token,
+                json: Boolean(opts.json),
+                gitArgs: Array.isArray(gitArgs) ? gitArgs.map(String) : [],
+            });
+        }
+        catch (error) {
+            handleCommandError('remix.pull', opts, undefined, error);
+        }
+    });
 }
-/** Register `playcraft git-credential` for local git pull/push after remix clone. */
+/** Register `playcraft git-credential`（clone 写入的 helper；拉/推请用 remix pull / push）. */
 export function registerGitCredentialCommand(program) {
     program
         .command('git-credential')
-        .description('Git credential helper：从登录配置提供 PlayCraft PAT')
+        .description('Git credential helper（一般勿手动调用；请用 playcraft remix pull / push）')
         .argument('[action]', 'get | store | erase', 'get')
         .action((action) => {
         gitCredentialCommand(action);

package/dist/remix/clone.js

@@ -200,7 +200,8 @@ export async function remixClone(options) {
     else {
         console.log('  playcraft start --project <project-id>   # PlayCanvas / 本地 Agent 预览');
     }
-    console.log('  git pull / git push   # 经 PlayCraft Git 代理（需已 login）');
+    console.log('  playcraft remix pull   # 拉取远端（沙箱 Save 后）');
+    console.log('  playcraft remix push   # 推回 Remix（Windows 勿直接 git push/pull）');
 }
 export { isRemoteCloneSource, resolveRemixCloneTarget };
 /**

package/dist/remix/local-git.js

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** @internal exported for tests */
+export function readRemixLocalMeta(repoDir) {
+    const metaPath = path.join(repoDir, '.playcraft.json');
+    if (!existsSync(metaPath)) {
+        throw new Error(`未找到 .playcraft.json（当前目录：${repoDir}）。请先在该目录执行 playcraft remix clone，或 cd 到 clone 得到的目录。`);
+    }
+    try {
+        const raw = JSON.parse(readFileSync(metaPath, 'utf8'));
+        const projectId = String(raw.projectId || '').trim();
+        const branch = String(raw.branch || '').trim();
+        const cloneUrl = String(raw.cloneUrl || '').trim();
+        if (!projectId || !branch || !cloneUrl) {
+            throw new Error('invalid_meta');
+        }
+        return {
+            schemaVersion: '1.0',
+            projectId,
+            branch,
+            cloneUrl,
+            clonedAt: typeof raw.clonedAt === 'string' ? raw.clonedAt : new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('.playcraft.json'))
+            throw error;
+        throw new Error(`.playcraft.json 无效或损坏：${metaPath}`);
+    }
+}
+/** @internal exported for tests */
+export function assertPlaycraftProxyRemote(cloneUrl) {
+    if (!cloneUrl.includes('/api/git/projects/')) {
+        throw new Error(`当前 .playcraft.json 的 cloneUrl 不是 PlayCraft Git 代理地址。\n` +
+            `请用 playcraft remix clone 重新克隆，不要改 remote 到工蜂 / 其它 Git 主机。\n` +
+            `cloneUrl: ${cloneUrl}`);
+    }
+}
+/**
+ * 运行带 PlayCraft PAT 的 git 子命令：注入 Bearer，并清空 credential.helper，
+ * 避免 Windows Git Credential Manager 弹窗。
+ */
+export function runAuthenticatedGit(gitCommandAndArgs, options) {
+    return spawnSync('git', [
+        '-c',
+        'credential.helper=',
+        '-c',
+        `http.extraHeader=Authorization: Bearer ${options.token}`,
+        ...gitCommandAndArgs,
+    ], {
+        cwd: options.cwd,
+        encoding: 'utf8',
+        stdio: options.pipe ? 'pipe' : 'inherit',
+    });
+}

package/dist/remix/pull.js

@@ -0,0 +1,64 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { assertPlaycraftProxyRemote, readRemixLocalMeta, runAuthenticatedGit, } from './local-git.js';
+/**
+ * 从 PlayCraft Git 代理拉取当前 Remix。
+ * 与 remix push 相同：注入 Bearer PAT，并禁用 credential.helper（避免 Windows GCM）。
+ */
+export async function remixPull(options = {}) {
+    const repoDir = path.resolve(options.dir?.trim() || process.cwd());
+    if (!existsSync(path.join(repoDir, '.git'))) {
+        throw new Error(`目录不是 Git 仓库：${repoDir}`);
+    }
+    const meta = readRemixLocalMeta(repoDir);
+    assertPlaycraftProxyRemote(meta.cloneUrl);
+    const client = new PlayCraftHttpClient({
+        url: options.url,
+        token: options.token,
+    });
+    const gitArgs = options.gitArgs?.length ? options.gitArgs : [];
+    const effectiveArgs = gitArgs.length > 0
+        ? gitArgs
+        : (() => {
+            const upstream = spawnSync('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], {
+                cwd: repoDir,
+                encoding: 'utf8',
+            });
+            if (upstream.status === 0 && upstream.stdout.trim()) {
+                return [];
+            }
+            return ['origin', meta.branch];
+        })();
+    if (!options.json) {
+        process.stderr.write(`[pull] ${meta.cloneUrl}\n`);
+        process.stderr.write(`[pull] branch=${meta.branch} dir=${repoDir}\n`);
+    }
+    const result = runAuthenticatedGit(['pull', ...effectiveArgs], {
+        cwd: repoDir,
+        token: client.token,
+        pipe: Boolean(options.json),
+    });
+    if (result.status !== 0) {
+        const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+        throw new Error(detail || `git pull 失败（exit ${result.status}）`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            schemaVersion: '1.0',
+            ok: true,
+            command: 'remix.pull',
+            requestId: client.requestId,
+            data: {
+                projectId: meta.projectId,
+                branch: meta.branch,
+                cloneUrl: meta.cloneUrl,
+                dir: repoDir,
+                gitArgs: effectiveArgs,
+            },
+        }));
+        return;
+    }
+    console.log(`✓ 已从 Remix 分支 ${meta.branch} 拉取`);
+}

package/dist/remix/push.js

@@ -0,0 +1,70 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { assertPlaycraftProxyRemote, readRemixLocalMeta, runAuthenticatedGit, } from './local-git.js';
+export { assertPlaycraftProxyRemote, readRemixLocalMeta } from './local-git.js';
+/**
+ * Push 当前 Remix 仓库到 PlayCraft Git 代理。
+ *
+ * 故意不用 `git push` + credential.helper：Windows 上 Git Credential Manager
+ * 经常抢走鉴权并弹窗。这里与 clone 一样，用一次性 `http.extraHeader` 注入 PAT，
+ * 并清空本命令的 credential.helper，避免 GCM 介入。
+ */
+export async function remixPush(options = {}) {
+    const repoDir = path.resolve(options.dir?.trim() || process.cwd());
+    if (!existsSync(path.join(repoDir, '.git'))) {
+        throw new Error(`目录不是 Git 仓库：${repoDir}`);
+    }
+    const meta = readRemixLocalMeta(repoDir);
+    assertPlaycraftProxyRemote(meta.cloneUrl);
+    const client = new PlayCraftHttpClient({
+        url: options.url,
+        token: options.token,
+    });
+    const gitArgs = options.gitArgs?.length ? options.gitArgs : [];
+    // 默认推当前分支；不强制改用户已设的 upstream。若无 upstream 且未传参数，
+    // 用 meta.branch 设 -u，避免「没有 upstream」报错。
+    const effectiveArgs = gitArgs.length > 0
+        ? gitArgs
+        : (() => {
+            const upstream = spawnSync('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], {
+                cwd: repoDir,
+                encoding: 'utf8',
+            });
+            if (upstream.status === 0 && upstream.stdout.trim()) {
+                return [];
+            }
+            return ['-u', 'origin', meta.branch];
+        })();
+    if (!options.json) {
+        process.stderr.write(`[push] ${meta.cloneUrl}\n`);
+        process.stderr.write(`[push] branch=${meta.branch} dir=${repoDir}\n`);
+    }
+    const result = runAuthenticatedGit(['push', ...effectiveArgs], {
+        cwd: repoDir,
+        token: client.token,
+        pipe: Boolean(options.json),
+    });
+    if (result.status !== 0) {
+        const detail = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+        throw new Error(detail || `git push 失败（exit ${result.status}）`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            schemaVersion: '1.0',
+            ok: true,
+            command: 'remix.push',
+            requestId: client.requestId,
+            data: {
+                projectId: meta.projectId,
+                branch: meta.branch,
+                cloneUrl: meta.cloneUrl,
+                dir: repoDir,
+                gitArgs: effectiveArgs,
+            },
+        }));
+        return;
+    }
+    console.log(`✓ 已推送到 Remix 分支 ${meta.branch}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.56",
+  "version": "0.0.57",
   "private": false,
   "type": "module",
   "engines": {
@@ -45,8 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.56",
-    "@playcraft/common": "^0.0.56",
+    "@playcraft/build": "^0.0.57",
+    "@playcraft/common": "^0.0.57",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",