scene-capability-engine 3.6.57 → 3.6.59

package/docs/zh/releases/v3.6.58.md

@@ -0,0 +1,27 @@
+# v3.6.58 发布说明
+
+发布日期：2026-03-19
+
+## 重点变化
+
+- 增加了面向 MagicBall 的规范化交付与工程投影契约，包括 `sce scene delivery show` 以及 `app engineering preview|ownership|open|import|scaffold` 这一组命令。
+- 增加了 phase-1 多项目只读契约：`sce project portfolio show`、`sce project target resolve`、`sce project supervision show`。
+- 同步更新了 MagicBall 集成文档、CLI 示例、前端状态映射、检查清单、问题跟踪、README 和发版检查清单，明确这些 project/engineering 能力已经是稳定集成输入。
+- 增加了发布期的 MagicBall project-contract 审计，使发布流程同时检查 engineering 与 multi-project 契约漂移。
+
+## 验证
+
+- `npx jest tests/unit/commands/app-mode.test.js --runInBand`
+- `npx jest tests/unit/commands/scene-delivery.test.js --runInBand`
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-engineering-contract-audit.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npm run audit:magicball-project-contract`
+- `npm run audit:magicball-engineering-contract`
+- `npm run test:release`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## 发布说明
+
+- 这个补丁版把最近的 MagicBall/IDE 投影工作真正固化成了正式发布线，而不是停留在本地补丁栈。工程侧现在通过一组明确文档化的契约暴露了交付投影，以及保守的工程 readiness、ownership、open/import、scaffold 包络；多项目侧则新增了由引擎负责的项目组合视图、目标项目预解析能力和按项目聚焦的监督快照，适配层不再需要自行从本地 workspace 状态拼装所谓“项目真相”。配套的 MagicBall 文档与发布审计也一起更新，后续无论是 npm 安装新版还是本机切换版本，都不会静默丢失这组集成能力。

package/docs/zh/releases/v3.6.59.md

@@ -0,0 +1,18 @@
+# v3.6.59 发布说明
+
+发布日期：2026-03-19
+
+## 重点变化
+
+- 发布了一个仅用于对齐的补丁版，使 npm 包、仓库 tag 与发布分支都指向同一份最终仓库状态。
+- MagicBall 的 delivery、engineering 与 multi-project 契约能力与 `v3.6.58` 保持完全一致，没有新增运行时能力变化。
+
+## 验证
+
+- `npm run audit:release-docs`
+- `node scripts/git-managed-gate.js --fail-on-violation --json`
+- 通过 `prepublishOnly` 执行 `npm publish --access public`
+
+## 发布说明
+
+- 这个补丁版不引入新的运行时行为，也不改变适配层合同。它的目的只是消除发版状态歧义：在共享项目问题投影快照于发版后写回仓库后，再给出一个严格对齐 npm/tag/仓库状态的正式版本。如果你要求 npm、tag、GitHub 发布线完全一致，应以后续的 `v3.6.59` 作为标准版本。

package/lib/app/engineering-scaffold-service.js

@@ -0,0 +1,154 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_ENGINEERING_SCAFFOLD_ENTRIES = Object.freeze([
+  'README.md',
+  'config',
+  'steering',
+  'knowledge',
+  'specs'
+]);
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeOverwritePolicy(value) {
+  const candidate = normalizeString(value).toLowerCase();
+  if (!candidate) {
+    return 'missing-only';
+  }
+  if (['never', 'missing-only', 'explicit'].includes(candidate)) {
+    return candidate;
+  }
+  throw new Error(`invalid overwrite policy: ${value}`);
+}
+
+async function pathExists(fileSystem, targetPath) {
+  try {
+    return await fileSystem.pathExists(targetPath);
+  } catch (error) {
+    return false;
+  }
+}
+
+async function copyEntryRecursive(sourcePath, targetPath, state, options) {
+  const { fileSystem, overwritePolicy } = options;
+  const sourceStat = await fileSystem.stat(sourcePath);
+
+  if (sourceStat.isDirectory()) {
+    const exists = await pathExists(fileSystem, targetPath);
+    if (exists) {
+      state.skippedDirectoryCount += 1;
+      if (overwritePolicy === 'never') {
+        return;
+      }
+    } else {
+      await fileSystem.ensureDir(targetPath);
+      state.createdDirectoryCount += 1;
+    }
+
+    const entries = (await fileSystem.readdir(sourcePath)).sort();
+    for (const entry of entries) {
+      await copyEntryRecursive(
+        path.join(sourcePath, entry),
+        path.join(targetPath, entry),
+        state,
+        options
+      );
+    }
+    return;
+  }
+
+  const exists = await pathExists(fileSystem, targetPath);
+  if (exists) {
+    if (overwritePolicy === 'explicit') {
+      await fileSystem.ensureDir(path.dirname(targetPath));
+      await fileSystem.copy(sourcePath, targetPath, {
+        overwrite: true,
+        errorOnExist: false
+      });
+      state.createdFileCount += 1;
+      return;
+    }
+    state.skippedFileCount += 1;
+    return;
+  }
+
+  await fileSystem.ensureDir(path.dirname(targetPath));
+  await fileSystem.copy(sourcePath, targetPath, {
+    overwrite: false,
+    errorOnExist: true
+  });
+  state.createdFileCount += 1;
+}
+
+async function scaffoldEngineeringWorkspace(options = {}) {
+  const workspacePath = normalizeString(options.workspacePath);
+  if (!workspacePath) {
+    throw new Error('workspacePath is required');
+  }
+
+  const fileSystem = options.fileSystem || fs;
+  const templateRoot = options.templateRoot
+    ? path.resolve(options.templateRoot)
+    : path.resolve(__dirname, '../../template/.sce');
+  const overwritePolicy = normalizeOverwritePolicy(options.overwritePolicy);
+  const scaffoldEntries = Array.isArray(options.entries) && options.entries.length > 0
+    ? options.entries
+    : DEFAULT_ENGINEERING_SCAFFOLD_ENTRIES;
+  const result = {
+    workspacePath,
+    createdDirectoryCount: 0,
+    skippedDirectoryCount: 0,
+    failedDirectoryCount: 0,
+    createdFileCount: 0,
+    skippedFileCount: 0,
+    failedFileCount: 0,
+    overwritePolicy
+  };
+  const scaffoldRoot = path.join(workspacePath, '.sce');
+  const scaffoldRootExists = await pathExists(fileSystem, scaffoldRoot);
+
+  if (scaffoldRootExists) {
+    result.skippedDirectoryCount += 1;
+    if (overwritePolicy === 'never') {
+      return result;
+    }
+  } else {
+    await fileSystem.ensureDir(scaffoldRoot);
+    result.createdDirectoryCount += 1;
+  }
+
+  for (const entry of scaffoldEntries) {
+    const sourcePath = path.join(templateRoot, entry);
+    const targetPath = path.join(scaffoldRoot, entry);
+    if (!await pathExists(fileSystem, sourcePath)) {
+      throw new Error(`engineering scaffold template entry is missing: ${entry}`);
+    }
+    try {
+      await copyEntryRecursive(sourcePath, targetPath, result, {
+        fileSystem,
+        overwritePolicy
+      });
+    } catch (error) {
+      const targetExists = await pathExists(fileSystem, targetPath);
+      if (targetExists) {
+        result.failedFileCount += 1;
+      } else {
+        result.failedDirectoryCount += 1;
+      }
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  DEFAULT_ENGINEERING_SCAFFOLD_ENTRIES,
+  normalizeOverwritePolicy,
+  scaffoldEngineeringWorkspace
+};