@hongmaple0820/scale-engine 0.20.0 → 0.21.0

package/README.md

@@ -17,6 +17,18 @@ SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探
 npm：https://www.npmjs.com/package/@hongmaple0820/scale-engine
 语言：[中文](README.md) | [English](README.en.md)
 
+## 🌐 社区与推广
+
+### 链接
+
+| 平台 | 链接 | 说明 |
+|------|------|------|
+| 🌐 **官网** | [https://scale-os.vercel.app](https://scale-os.vercel.app) | 在线配置器 + 完整文档 |
+| 📦 **GitHub** | [https://github.com/hongmaple0820/scale-os](https://github.com/hongmaple0820/scale-os) | 源码 + Issues + PR |
+| 🔧 **Gitee** | [https://gitee.com/hongmaple/scale-engine](https://gitee.com/hongmaple/scale-engine) | 国内镜像 |
+| 📦 **npm** | [https://www.npmjs.com/package/@hongmaple0820/scale-engine](https://www.npmjs.com/package/@hongmaple0820/scale-engine) | 包下载 |
+| 🧰 **项目脚手架** | [https://github.com/hongmaple0820/project-scaffold](https://github.com/hongmaple0820/project-scaffold) | 工程化工作流实践脚手架 |
+
 ## 它解决什么问题
 
 AI 编码真正难的不是“写代码”，而是持续稳定地遵守工程纪律：
@@ -90,6 +102,30 @@ scale --version
 
 需要 Node.js 20 或更高版本。
 
+## 更新工作流
+
+SCALE 把升级分成三层：CLI 自身、已生成到项目里的 governance pack 文件、第三方 skills/MCP/CLI 能力。默认只检查和生成计划，不自动覆盖用户改过的文件，也不自动安装第三方工具。
+
+```bash
+scale upgrade check --dir .
+scale upgrade plan --dir . --html
+scale upgrade apply --dir . --confirm
+scale upgrade rollback --dir .
+scale tools outdated --dir .
+scale skill outdated --dir .
+```
+
+升级原则：
+
+- `scale upgrade check` 读取 `.scale/governance.lock.json`，判断当前项目是干净、缺文件、模板过期，还是存在本地改动。
+- `scale upgrade plan` 生成非破坏性计划；遇到用户改过的生成文件时标记 `manual-review`。
+- `scale upgrade apply --confirm` 只恢复缺失生成文件和刷新锁文件，先写 `.scale/backups/upgrade-*` 回滚点。
+- `scale upgrade rollback` 只撤回最近一次 SCALE 管理的安全应用。
+- `scale tools outdated` 和 `scale skill outdated` 只列出更新面、来源、信任等级和安全策略，不做自动安装。
+- 第三方社区来源默认人工评审，高权限桌面自动化默认阻断自动升级。
+
+详细说明见 [升级管理](docs/UPGRADE_MANAGEMENT.md)。
+
 ## Governance Pack
 
 在已有项目中安装治理工作流：

package/dist/api/cli.js

@@ -37,6 +37,7 @@ import { WorkflowEngine } from '../workflow/WorkflowEngine.js';
 import { resolveVerificationTargets, } from '../workflow/VerificationProfile.js';
 import { writeGovernanceTemplates } from '../workflow/GovernanceTemplates.js';
 import { computeGovernanceDrift } from '../workflow/GovernanceLock.js';
+import { applyUpgradePlan, createThirdPartyUpdateReport, createUpgradeCheckReport, createUpgradePlanReport, rollbackLatestUpgrade, writeUpgradePlanHtml, } from '../workflow/UpgradeManager.js';
 import { createGovernanceRoiReport } from '../governance/GovernanceRoi.js';
 import { evaluateProgressiveGovernance, normalizeGovernanceMode } from '../governance/ProgressiveGovernance.js';
 import { baselineEngineeringStandards, doctorEngineeringStandards, scanEngineeringStandards, settleEngineeringStandards, } from '../workflow/EngineeringStandards.js';
@@ -2505,6 +2506,133 @@ const governance = defineCommand({
     subCommands: { diff: governanceDiff, mode: governanceModeCommand, roi: governanceRoiCommand },
 });
 // ============================================================================
+// upgrade command - Safe workflow/template/capability update planning
+// ============================================================================
+const upgradeCheck = defineCommand({
+    meta: { name: 'check', description: 'Check SCALE workflow, governance pack, and third-party capability update status' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        'target-version': { type: 'string', description: 'Target SCALE Engine version; defaults to the running CLI version' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = createUpgradeCheckReport({
+            projectDir: args.dir,
+            targetScaleVersion: args['target-version'] ? String(args['target-version']) : undefined,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log('SCALE Upgrade Check');
+        console.log(`  Project: ${report.projectDir}`);
+        console.log(`  Status: ${report.status}`);
+        console.log(`  SCALE Engine: ${report.scaleEngine.currentVersion ?? 'none'} -> ${report.scaleEngine.latestVersion}`);
+        console.log(`  Governance pack: ${report.governancePack.id ?? 'none'} v${report.governancePack.currentVersion ?? 'none'} -> v${report.governancePack.latestVersion ?? 'none'}`);
+        console.log(`  Generated files: ${report.generatedFiles.clean} clean, ${report.generatedFiles.changed} changed, ${report.generatedFiles.missing} missing`);
+        console.log(`  Third-party policy: ${report.thirdParty.policy}; review required: ${report.thirdParty.reviewRequired}`);
+        console.log('  Next:');
+        for (const command of report.recommendedCommands)
+            console.log(`    ${command}`);
+    },
+});
+const upgradePlan = defineCommand({
+    meta: { name: 'plan', description: 'Create a non-destructive SCALE upgrade plan' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        'target-version': { type: 'string', description: 'Target SCALE Engine version; defaults to the running CLI version' },
+        html: { type: 'boolean', default: false, description: 'Write .scale/reports/upgrade-plan.html' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = createUpgradePlanReport({
+            projectDir: args.dir,
+            targetScaleVersion: args['target-version'] ? String(args['target-version']) : undefined,
+        });
+        const htmlPath = args.html ? writeUpgradePlanHtml(report) : undefined;
+        if (args.json) {
+            console.log(JSON.stringify({ ...report, htmlPath }, null, 2));
+            return;
+        }
+        console.log('SCALE Upgrade Plan');
+        console.log(`  Project: ${report.projectDir}`);
+        console.log(`  Status: ${report.status}`);
+        console.log(`  Apply mode: ${report.applyMode}`);
+        if (report.blockers.length > 0) {
+            console.log('  Blockers:');
+            for (const blocker of report.blockers)
+                console.log(`    [${blocker.code}] ${blocker.path ?? ''} ${blocker.message}`);
+        }
+        console.log('  Steps:');
+        for (const step of report.steps) {
+            const path = step.path ? ` ${step.path}` : '';
+            const command = step.command ? ` -> ${step.command}` : '';
+            console.log(`    [${step.risk}] ${step.action}${path}: ${step.reason}${command}`);
+        }
+        if (htmlPath)
+            console.log(`  HTML: ${htmlPath}`);
+    },
+});
+const upgradeApply = defineCommand({
+    meta: { name: 'apply', description: 'Guarded entrypoint for applying an upgrade plan' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        confirm: { type: 'boolean', default: false, description: 'Confirm that the current plan was reviewed' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const result = applyUpgradePlan({
+            projectDir: args.dir,
+            confirm: isTruthyFlag(args.confirm),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        console.log('SCALE Upgrade Apply');
+        console.log(`  Applied: ${result.applied}`);
+        console.log(`  Reason: ${result.reason}`);
+        console.log(`  Apply mode: ${result.plan.applyMode}`);
+        if (result.backup)
+            console.log(`  Backup: ${result.backup.manifestPath}`);
+        for (const path of result.changedFiles)
+            console.log(`  changed: ${path}`);
+        if (!result.ok)
+            process.exitCode = 1;
+    },
+});
+const upgradeRollback = defineCommand({
+    meta: { name: 'rollback', description: 'Explain rollback state for SCALE upgrades' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const result = rollbackLatestUpgrade({ projectDir: args.dir });
+        if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        console.log('SCALE Upgrade Rollback');
+        console.log(`  Applied: ${result.applied}`);
+        console.log(`  Reason: ${result.reason}`);
+        if (result.backup)
+            console.log(`  Backup: ${result.backup.manifestPath}`);
+        for (const path of result.restoredFiles)
+            console.log(`  restored: ${path}`);
+        if (!result.ok)
+            process.exitCode = 1;
+    },
+});
+const upgrade = defineCommand({
+    meta: { name: 'upgrade', description: 'Safe update planning for SCALE workflow, generated templates, skills, MCP, and CLI tools' },
+    subCommands: { check: upgradeCheck, plan: upgradePlan, apply: upgradeApply, rollback: upgradeRollback },
+});
+// ============================================================================
 // assets command - Resource lifecycle governance
 // ============================================================================
 const assetsScan = defineCommand({
@@ -4167,6 +4295,30 @@ const skillRecommendCommand = defineCommand({
             console.log(`  - ${reason}`);
     },
 });
+const skillOutdatedCommand = defineCommand({
+    meta: { name: 'outdated', description: 'List skill update surfaces without installing or upgrading anything' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = createThirdPartyUpdateReport('skill');
+        if (args.json) {
+            console.log(JSON.stringify({ ...report, projectDir: resolve(String(args.dir ?? PROJECT_DIR)) }, null, 2));
+            return;
+        }
+        console.log('\nSCALE Skill Outdated');
+        console.log(`  Policy: ${report.policy}`);
+        console.log(`  Skills: ${report.summary.total}`);
+        console.log(`  Review required: ${report.reviewRequired}`);
+        for (const entry of report.entries) {
+            console.log(`  [${entry.updatePolicy}] ${entry.id} trust=${entry.trust} latest=${entry.latestVersion}`);
+            if (entry.source)
+                console.log(`    source: ${entry.source}`);
+            console.log(`    reason: ${entry.reason}`);
+        }
+    },
+});
 const skill = defineCommand({
     meta: { name: 'skill', description: 'Skill discovery and management' },
     subCommands: {
@@ -4178,6 +4330,7 @@ const skill = defineCommand({
         safety: skillSafetyCommand,
         radar: skillRadarCommand,
         recommend: skillRecommendCommand,
+        outdated: skillOutdatedCommand,
     },
 });
 // ============================================================================
@@ -4423,9 +4576,34 @@ const toolEvidenceCommand = defineCommand({
             process.exitCode = 1;
     },
 });
+const toolOutdatedCommand = defineCommand({
+    meta: { name: 'outdated', description: 'List MCP, browser, desktop, and external CLI update surfaces without installing anything' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = createThirdPartyUpdateReport(['cli', 'mcp', 'browser', 'desktop']);
+        if (args.json) {
+            console.log(JSON.stringify({ ...report, projectDir: resolve(String(args.dir ?? PROJECT_DIR)) }, null, 2));
+            return;
+        }
+        console.log('\nSCALE Tool Outdated');
+        console.log(`  Policy: ${report.policy}`);
+        console.log(`  Tools: ${report.summary.total}`);
+        console.log(`  Review required: ${report.reviewRequired}`);
+        console.log(`  Blocked: ${report.summary.blocked}`);
+        for (const entry of report.entries) {
+            console.log(`  [${entry.updatePolicy}] ${entry.id} category=${entry.category} trust=${entry.trust} latest=${entry.latestVersion}`);
+            if (entry.source)
+                console.log(`    source: ${entry.source}`);
+            console.log(`    reason: ${entry.reason}`);
+        }
+    },
+});
 const tool = defineCommand({
     meta: { name: 'tool', description: 'Skills, MCP, browser, desktop, and external CLI governance' },
-    subCommands: { policy: toolPolicyCommand, doctor: toolDoctorCommand, plan: toolPlanCommand, run: toolRunCommand, evidence: toolEvidenceCommand },
+    subCommands: { policy: toolPolicyCommand, doctor: toolDoctorCommand, plan: toolPlanCommand, run: toolRunCommand, evidence: toolEvidenceCommand, outdated: toolOutdatedCommand },
 });
 // ============================================================================
 // agent commands — Multi-Agent 协作系统 (Phase 9)
@@ -4604,6 +4782,7 @@ const main = defineCommand({
         evolve,
         stats,
         preflight,
+        upgrade,
         governance,
         codegraph,
         eval: evalCommand,
@@ -4621,6 +4800,7 @@ const main = defineCommand({
         diagnose,
         tdd,
         tool,
+        tools: tool,
         skill,
         skills: skill,
         agent,