@fenglimg/cocos-state-controller 0.1.0

package/bin/csc.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * csc — @fenglimg/cocos-state-controller 分发/同步 CLI 入口。
+ *
+ * P0: 命令路由骨架。各子命令在后续阶段填充：
+ *   install / diff / doctor → P3   update → P4   sync → P5
+ *   migrate / skill        → P6    核心数据层 / 三方引擎 → P1 / P2
+ *
+ * 设计：入口只做 argv 路由 + help/version；命令实现落 lib/commands/*（P1 起建）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const installMod = require('../lib/commands/install');
+const diffMod = require('../lib/commands/diff');
+const doctorMod = require('../lib/commands/doctor');
+const updateMod = require('../lib/commands/update');
+const syncMod = require('../lib/commands/sync');
+const migrateMod = require('../lib/commands/migrate');
+const skillMod = require('../lib/commands/skill');
+const lockMod = require('../lib/lock');
+const baselineMod = require('../lib/baseline');
+
+/** @typedef {(args: string[]) => (number|void|Promise<number|void>)} CommandHandler */
+
+/** 极简 flag 解析：--key value / --flag。 */
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+/** 后续阶段把这些占位换成 require('../lib/commands/<cmd>')。 */
+function notYetImplemented(name, phase) {
+  return function () {
+    console.error(`csc ${name}: 尚未实现（${phase}）`);
+    return 2;
+  };
+}
+
+function cmdInstall(args) {
+  const { flags } = parseFlags(args);
+  const payloadRoot = path.join(__dirname, '..');
+  const targetRoot = process.cwd();
+  const pkg = require(path.join(payloadRoot, 'package.json'));
+  const installPaths = { ...installMod.DEFAULT_INSTALL_PATHS };
+  if (flags['runtime-path']) installPaths.runtime = flags['runtime-path'];
+  if (flags['panel-path']) installPaths.panel = flags['panel-path'];
+  if (flags.version) console.error('注意：--version 跨版本安装自 P4 起支持，当前用 CLI 自带版本净荷。');
+
+  const r = installMod.install({ payloadRoot, targetRoot, packageVersion: pkg.version, installPaths });
+  if (r.collisions.length) {
+    console.error('✗ uuid 撞车，已中止安装（未改任何文件）：');
+    for (const c of r.collisions) {
+      console.error(`  ${c.uuid}\n    包→ ${c.packageDest}\n    冲突← ${c.consumerFiles.join(', ')}`);
+    }
+    console.error('请重生成本地冲突方的 uuid（绝不动包的），再重试。');
+    return 1;
+  }
+  console.log(`✓ 安装 ${r.copied.length} 个文件 → ${targetRoot}`);
+  if (!r.cocos) console.warn('⚠ 未探测到 Cocos 版本（project.json）');
+  else if (!r.cocosSupported) console.warn(`⚠ Cocos ${r.cocos.version} 不在 2.4.x 支持范围（仅警告）`);
+  else console.log(`  Cocos ${r.cocos.version} ✓`);
+  console.log('→ 重启 Cocos 编辑器以加载面板');
+  return 0;
+}
+
+function cmdDiff() {
+  let r;
+  try {
+    r = diffMod.diffInstalled(process.cwd());
+  } catch (e) {
+    console.error('✗ ' + e.message);
+    return 1;
+  }
+  const total = r.added.length + r.removed.length + r.modified.length;
+  if (!total) {
+    console.log('无差异（与装的版本一致）');
+    return 0;
+  }
+  r.added.forEach((p) => console.log(`+ ${p}`));
+  r.removed.forEach((p) => console.log(`- ${p}`));
+  r.modified.forEach((p) => console.log(`~ ${p}`));
+  console.log(`\n共 ${total} 项（+${r.added.length} -${r.removed.length} ~${r.modified.length}）`);
+  return 0;
+}
+
+function cmdDoctor() {
+  const r = doctorMod.doctor(process.cwd());
+  const icon = { ok: '✓', warn: '⚠', fail: '✗', skipped: '·' };
+  for (const c of r.checks) console.log(`${icon[c.status] || '?'} ${c.name}: ${c.detail}`);
+  console.log(`\n体检${r.ok ? '通过' : '发现问题'}`);
+  return r.ok ? 0 : 1;
+}
+
+function cmdUpdate(args) {
+  const { flags } = parseFlags(args);
+  const targetRoot = process.cwd();
+  const lock = lockMod.readLock(targetRoot);
+  if (!lock) {
+    console.error('✗ 未安装：先 csc install');
+    return 1;
+  }
+  const pkg = require(path.join(__dirname, '..', 'package.json')).name;
+  let basePayloadRoot;
+  let newPayloadRoot;
+  try {
+    // base = lock 记录的 vX pristine；new = 目标版本（默认 latest）。本地 dogfood 可用 --base-payload/--new-payload 覆盖。
+    basePayloadRoot = flags['base-payload'] || baselineMod.reconstructBaseline({ pkg, version: lock.packageVersion });
+    newPayloadRoot = flags['new-payload'] || baselineMod.reconstructBaseline({ pkg, version: flags.version || 'latest' });
+  } catch (e) {
+    console.error('✗ 取净荷失败（跨版本 update 需包已发布到 npm）：' + e.message);
+    return 1;
+  }
+
+  const r = updateMod.update({ targetRoot, basePayloadRoot, newPayloadRoot, newVersion: flags.version });
+  const R = r.results;
+  console.log(
+    `更新到 v${r.packageVersion}：clean ${R.clean.length} / merged ${R.merged.length} / ` +
+      `conflict ${R.conflict.length} / added ${R.added.length} / removed ${R.removed.length}`
+  );
+  if (r.hasConflict) {
+    console.warn('⚠ 冲突文件（含 <<<< 标记），需人工/AI 解：');
+    R.conflict.forEach((p) => console.warn('  ' + p));
+    return 1;
+  }
+  return 0;
+}
+
+function cmdSync(args) {
+  const { flags } = parseFlags(args);
+  if (!flags.upstream) {
+    console.error('用法: csc sync --upstream [--output patch.diff]');
+    return 1;
+  }
+  const targetRoot = process.cwd();
+  const lock = lockMod.readLock(targetRoot);
+  if (!lock) {
+    console.error('✗ 未安装：先 csc install');
+    return 1;
+  }
+  const pkg = require(path.join(__dirname, '..', 'package.json')).name;
+  let basePayloadRoot;
+  try {
+    basePayloadRoot = flags['base-payload'] || baselineMod.reconstructBaseline({ pkg, version: lock.packageVersion });
+  } catch (e) {
+    console.error('✗ 取基线失败（需包已发布到 npm）：' + e.message);
+    return 1;
+  }
+
+  const r = syncMod.sync({ targetRoot, basePayloadRoot });
+  if (!r.hasChanges) {
+    console.log('无上行改动（与装的版本一致）');
+    return 0;
+  }
+  if (flags.output && typeof flags.output === 'string') {
+    fs.writeFileSync(flags.output, r.patch);
+    console.log(`patch 写入 ${flags.output}`);
+  } else {
+    process.stdout.write(r.patch);
+  }
+  console.error(
+    `\n// 改动 modified ${r.summary.modified} / added ${r.summary.added} / removed ${r.summary.removed}` +
+      '（交上行 PR skill 据 §4 漂移政策取舍 + 开 GitHub PR）'
+  );
+  return 0;
+}
+
+function cmdMigrate(args) {
+  const { flags, positional } = parseFlags(args);
+  if (!positional.length) {
+    console.error('用法: csc migrate <prefab|dir...> [--write] [--backup] [--allow-remote]');
+    return 1;
+  }
+  const packageRoot = path.join(__dirname, '..');
+  const r = migrateMod.migrate({
+    targets: positional,
+    projectRoot: process.cwd(),
+    packageRoot,
+    write: !!flags.write,
+    backup: !!flags.backup,
+    allowRemote: !!flags['allow-remote'],
+  });
+  if (!r.ok) {
+    console.error('✗ remote bundle 默认拒绝迁移（迁 V2-cid 会崩仅 V1 runtime 的老客户端）：');
+    r.blocked.forEach((b) => console.error(`  ${b.file} — ${b.reason}`));
+    console.error('确认全客户端已铺 V1+V2 共存 runtime 后，加 --allow-remote 重试。');
+    return 1;
+  }
+  if (r.output) process.stdout.write(r.output);
+  if (r.blocked.length) console.warn(`⚠ ${r.blocked.length} 个 remote bundle 文件已放行（--allow-remote）`);
+  return 0;
+}
+
+function cmdSkill(args) {
+  const [sub, ...rest] = args;
+  if (sub !== 'install') {
+    console.error('用法: csc skill install [--target claude|codex|all]');
+    return 1;
+  }
+  const { flags } = parseFlags(rest);
+  const packageRoot = path.join(__dirname, '..');
+  const r = skillMod.skillInstall({ packageRoot, projectRoot: process.cwd(), target: flags.target || 'all' });
+  console.log(`✓ 安装 ${r.installed.length} 个 skill 目标：`);
+  r.installed.forEach((t) => console.log('  ' + t));
+  return 0;
+}
+
+/** @type {Record<string, { phase: string, summary: string, handler: CommandHandler }>} */
+const COMMANDS = {
+  install: { phase: 'P3', summary: '拷净荷 + 写 .meta + 写 .csc/lock.json + uuid 撞车预检 + 提示重启编辑器',
+    handler: cmdInstall },
+  update: { phase: 'P4', summary: '取新版净荷：未改的覆盖 / 改过的三方合并；更新 lock',
+    handler: cmdUpdate },
+  diff: { phase: 'P3', summary: 'consumer 当前 vs 装的版本 pristine（归一化后）列 新增/删除/修改',
+    handler: cmdDiff },
+  doctor: { phase: 'P3', summary: '体检：文件齐全 / .meta uuid / uuid 撞车 / V1 cid 残留 / Cocos 版本 / lock 一致',
+    handler: cmdDoctor },
+  migrate: { phase: 'P6', summary: '确定性 prefab V1→V2 迁移引擎（remote bundle 默认拒绝）',
+    handler: cmdMigrate },
+  sync: { phase: 'P5', summary: '重建 vX 基线 + 反归一化 + 三方 diff → 输出 patch（交 AI Skill 开 PR）',
+    handler: cmdSync },
+  skill: { phase: 'P6', summary: '分发 skills 到 .claude/.codex',
+    handler: cmdSkill },
+  uninstall: { phase: 'P3', summary: '按 lock 移除 managed 文件 + .csc/（回退）',
+    handler: notYetImplemented('uninstall', 'P3') }
+};
+
+function printVersion() {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  console.log(`${pkg.name} ${pkg.version}`);
+  return 0;
+}
+
+function printHelp() {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  console.log(`${pkg.name} — csc CLI\n`);
+  console.log('用法: csc <command> [options]\n');
+  console.log('命令:');
+  const width = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
+  for (const [name, { phase, summary }] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(width)}  [${phase}] ${summary}`);
+  }
+  console.log('\n  --help, -h      显示此帮助');
+  console.log('  --version, -v   显示版本');
+  return 0;
+}
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return printHelp();
+  if (cmd === '--version' || cmd === '-v') return printVersion();
+
+  const entry = COMMANDS[cmd];
+  if (!entry) {
+    console.error(`未知命令: ${cmd}\n`);
+    printHelp();
+    return 1;
+  }
+  const code = await entry.handler(rest);
+  return typeof code === 'number' ? code : 0;
+}
+
+main(process.argv.slice(2))
+  .then((code) => { process.exitCode = code; })
+  .catch((err) => {
+    console.error('csc 致命错误:', err && err.stack ? err.stack : err);
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@fenglimg/cocos-state-controller",
+  "version": "0.1.0",
+  "description": "Cocos Creator State Controller — 状态控制器组件 + 分发/同步 CLI (csc)",
+  "license": "MIT",
+  "author": "fenglimg <fenglimg90@gmail.com>",
+  "homepage": "https://github.com/fenglimg/cocos-state-controller#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fenglimg/cocos-state-controller.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fenglimg/cocos-state-controller/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cocos",
+    "cocos-creator",
+    "state-controller",
+    "state-machine",
+    "csc",
+    "cli"
+  ],
+  "bin": {
+    "csc": "bin/csc.js"
+  },
+  "files": [
+    "bin/",
+    "assets/script/controller/",
+    "packages/state-controller-v2-panel/",
+    "tools/migration/",
+    "tools/state-controller-sync-manifest.json",
+    "skills/cocos-state-controller/",
+    "skills/cocos-scv2-migrate/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "eslint assets/ --ext .ts,.js",
+    "lint:fix": "eslint assets/ --ext .ts,.js --fix",
+    "migrate:v1-to-v2": "node tools/migration/migrate-prefab-v1-to-v2.js",
+    "test": "cd tests && npx jest",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0"
+  },
+  "lint-staged": {
+    "assets/**/*.ts": [
+      "eslint --fix"
+    ]
+  }
+}

package/packages/state-controller-v2-panel/README.md

@@ -0,0 +1,80 @@
+# State Controller Panel — Wave 3 scaffold (本期)
+
+> 状态: 骨架就绪 (Claude), Panel UI 待 Gemini 接入
+> 设计文档: `.workflow/active/wave3-runtime-capability/PANEL-BRIEF-v0.2.md`
+
+## 目录结构
+
+```
+packages/state-controller-v2-panel/
+├── package.json          Cocos 2.x 插件清单 (dockable panel 配置)
+├── main.js               入口, 响应 :open / :close
+├── scene-accessor.js     scene-script, IPC 路由层, 调 lib/handlers.js
+├── lib/handlers.js       纯函数业务层, 单测覆盖 (tests/panel/handlers.test.ts)
+└── panel/                ⬅ Gemini 接 UI 在这里
+    ├── build.js          cocos 面板生命周期 (Polymer-style register)
+    ├── template.html     panel HTML
+    ├── styles.css        样式
+    └── logic.js          UI 交互逻辑
+```
+
+## IPC 契约 (panel → scene-accessor)
+
+panel/build.js 用 `Editor.Ipc.sendToPanel('scene', 'state-controller-v2-panel:<msg>', payload, callback)`
+向 scene-script 发请求, 路由名见下表 (与 scene-accessor.js 的 message handler 一一对应):
+
+| 消息名 | payload | 返回 (result) | 作用 |
+|---|---|---|---|
+| `state-controller-v2-panel:list-ctrls` | (空) | `[{uuid, ctrlId, ctrlName}]` | Panel 打开时, 列场景所有 StateController |
+| `state-controller-v2-panel:get-ctrl-snapshot` | `{uuid}` | `CtrlSnapshot` | 拉某 ctrl 完整数据 (states 列表 + 当前 index + recording 等) |
+| `state-controller-v2-panel:set-selected-index` | `{uuid, index}` | `boolean` | 切预览中的 state |
+| `state-controller-v2-panel:set-state-by-id` | `{uuid, stateId}` | `boolean` | 用稳定 stateId 切换 |
+| `state-controller-v2-panel:set-home-page` | `{uuid, stateIdOrName}` | `boolean` | 设默认启动状态 (-1 清除) |
+| `state-controller-v2-panel:set-recording` | `{uuid, isRecording}` | `boolean` | 开/关录制 |
+| `state-controller-v2-panel:add-state` | `{uuid, name}` | `stateId number, -1 失败` | 新增 state |
+| `state-controller-v2-panel:remove-state` | `{uuid, index}` | `boolean` | 删 state (至少保留 1 个) |
+| `state-controller-v2-panel:add-property` | `{ctrlUuid, selectUuid, propType}` | `boolean` | 手动加 prop |
+| `state-controller-v2-panel:dispose-all-bridges` | (空) | `true` | Panel 关闭时调, 解所有广播桥 |
+
+## 广播事件 (scene-accessor → panel)
+
+scene-accessor 收到 capability 事件后, 经 `Editor.Ipc.sendToPanel('state-controller-v2-panel', '<event>', payload)`:
+
+| 事件名 | payload | 触发时机 |
+|---|---|---|
+| `state-controller-v2-panel:on-state-changed` | `{ctrlId, fromState, toState, fromName, toName}` | EventCapability stateChanged |
+| `state-controller-v2-panel:on-recording-changed` | `{ctrlId, isRecording}` | startRecording / stopRecording |
+| `state-controller-v2-panel:on-data-changed` | `{ctrlId}` | add/remove state, add prop 等本期所有数据变 |
+
+## CtrlSnapshot 结构
+
+```js
+{
+    ctrlId: number,
+    ctrlName: string,
+    selectedIndex: number,
+    selectedStateId: number,
+    homePageStateId: number,        // -1 = 未设
+    isRecording: boolean,
+    states: [
+        { index: number, stateId: number, name: string },
+        // ...
+    ]
+}
+```
+
+## 给 Gemini 的实装要点
+
+1. **不要碰 lib/handlers.js / scene-accessor.js**. 这两层是 Claude 维护的 IPC + 业务函数, 已有
+   测试覆盖 (tests/panel/handlers.test.ts 15 case + sceneAccessor.smoke.test.ts 2 case).
+2. **新建 panel/ 子目录** (template.html / styles.css / logic.js / build.js).
+   build.js 是 cocos 2.x Polymer-style 入口, 参考 `packages/ccc-smart-component-manager/panel/`
+   实现风格.
+3. **UI 布局参照** `PANEL-BRIEF-v0.2.md` §1 wireframe + §4 槽位映射表.
+4. **缩略图实装** 参照 brief §5 (RenderTexture + LRU 缓存). 本期可仅留占位 (灰底 + 状态名),
+   不实装真截图; 用 `// TODO Wave 3 后期: 实装缩略图` 标记位置.
+5. **W4/W5 扩展位置** 全部 `// TODO Wave 4` / `// TODO Wave 5` 占位, 不写死布局.
+6. **不引入 React/Vue/带 bundler 框架**. Polymer-style webcomponent 或 vanilla DOM 都行.
+7. **测试**: UI 层 Claude 不写测试, 由 Gemini 自行在编辑器内实测. 但 IPC 调用要走
+   scene-accessor 的固定路由名, 不要绕开 (绕开就丢了 broadcast 桥).
+8. **Panel 关闭** 时 build.js 必须调 `dispose-all-bridges`, 否则会泄漏 capability 注册.