universal-dev-standards 6.15.0 → 6.16.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/bin/uds.js +2 -0
  2. package/bundled/locales/zh-CN/CHANGELOG.md +34 -4
  3. package/bundled/locales/zh-CN/CLAUDE.md +2 -2
  4. package/bundled/locales/zh-CN/README.md +17 -14
  5. package/bundled/locales/zh-CN/SECURITY.md +1 -0
  6. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -1
  7. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +24 -2
  8. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +3 -1
  9. package/bundled/locales/zh-TW/CHANGELOG.md +34 -4
  10. package/bundled/locales/zh-TW/CLAUDE.md +2 -2
  11. package/bundled/locales/zh-TW/README.md +17 -14
  12. package/bundled/locales/zh-TW/SECURITY.md +1 -0
  13. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -1
  14. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +24 -2
  15. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +3 -1
  16. package/package.json +3 -3
  17. package/src/commands/skills.js +9 -0
  18. package/src/commands/update.js +223 -2
  19. package/src/reconciler/desired-state-calculator.js +11 -2
  20. package/src/utils/optional-skills-report.js +86 -0
  21. package/src/utils/optional-skills.js +20 -0
  22. package/src/utils/skill-selection.js +137 -0
  23. package/src/utils/skills-installer.js +11 -4
  24. package/standards-registry.json +7 -7
  25. package/src/core/agent-communication-protocol.js +0 -257
  26. package/src/flow/condition-evaluator.js +0 -86
  27. package/src/flow/flow-bundler.js +0 -80
  28. package/src/flow/flow-commands.js +0 -107
  29. package/src/flow/flow-engine.js +0 -154
  30. package/src/flow/flow-inheritance.js +0 -100
  31. package/src/flow/flow-parser.js +0 -104
  32. package/src/flow/flow-validator.js +0 -37
  33. package/src/flow/gate-checker.js +0 -82
  34. package/src/flow/gate-loader.js +0 -52
  35. package/src/missions/MissionManager.js +0 -533
  36. package/src/utils/e2e-analyzer.js +0 -471
  37. package/src/utils/e2e-detector.js +0 -132
  38. package/src/utils/hook-stats.js +0 -151
  39. package/src/utils/workflow-executor.js +0 -870
  40. package/src/utils/workflows-installer.js +0 -545
  41. package/src/vibe/auto-sweep.js +0 -349
@@ -1,154 +0,0 @@
1
- /**
2
- * Flow Engine — SPEC-FLOW-001
3
- *
4
- * 流程執行引擎:狀態機 + 持久化 + 恢復。
5
- * 狀態格式與 workflow-state-protocol 相容。
6
- */
7
-
8
- import { join } from 'path';
9
-
10
- const STALE_DAYS_THRESHOLD = 7;
11
-
12
- /**
13
- * Flow Engine — 管理流程的執行狀態和生命週期。
14
- */
15
- export class FlowEngine {
16
- /**
17
- * @param {object} flow - 已解析的 Flow 物件
18
- * @param {object} options
19
- * @param {object} options.fs - 檔案系統操作(existsSync, readFileSync, writeFileSync, mkdirSync)
20
- * @param {string} options.stateDir - 狀態檔案目錄路徑
21
- */
22
- constructor(flow, options = {}) {
23
- this.flow = flow;
24
- this.fs = options.fs || defaultFs();
25
- this.stateDir = options.stateDir || '.workflow-state';
26
- this.statePath = join(this.stateDir, `flow-${flow.id}.json`);
27
- this.state = null;
28
- }
29
-
30
- /**
31
- * 啟動新的流程執行。
32
- * @returns {object} 初始狀態
33
- */
34
- start() {
35
- const firstStage = this.flow.stages[0];
36
- this.state = {
37
- workflow: this.flow.id,
38
- current_phase: firstStage.id,
39
- status: 'in-progress',
40
- updated: new Date().toISOString(),
41
- phases_completed: []
42
- };
43
- this._save();
44
- return this.state;
45
- }
46
-
47
- /**
48
- * 完成當前 stage,進入下一個。
49
- * @param {string} stageId - 完成的 stage ID
50
- */
51
- completeStage(stageId) {
52
- if (!this.state) return;
53
-
54
- this.state.phases_completed.push(stageId);
55
- this.state.updated = new Date().toISOString();
56
-
57
- const stageIds = this.flow.stages.map(s => s.id);
58
- const currentIdx = stageIds.indexOf(stageId);
59
- const nextIdx = currentIdx + 1;
60
-
61
- if (nextIdx >= stageIds.length) {
62
- this.state.status = 'completed';
63
- this.state.current_phase = stageId;
64
- } else {
65
- this.state.current_phase = stageIds[nextIdx];
66
- }
67
-
68
- this._save();
69
- }
70
-
71
- /**
72
- * 放棄流程。
73
- */
74
- abandon() {
75
- if (!this.state) return;
76
- this.state.status = 'abandoned';
77
- this.state.updated = new Date().toISOString();
78
- this._save();
79
- }
80
-
81
- /**
82
- * 檢查是否有可恢復的流程。
83
- * @returns {{resumable: boolean, currentPhase?: string, flowName?: string, stale?: boolean, staleDays?: number}}
84
- */
85
- checkResumable() {
86
- if (!this.fs.existsSync(this.statePath)) {
87
- return { resumable: false };
88
- }
89
-
90
- try {
91
- const content = this.fs.readFileSync(this.statePath, 'utf-8');
92
- const saved = JSON.parse(content);
93
-
94
- if (saved.status !== 'in-progress') {
95
- return { resumable: false };
96
- }
97
-
98
- const updatedDate = new Date(saved.updated);
99
- const now = new Date();
100
- const diffDays = Math.floor((now - updatedDate) / (1000 * 60 * 60 * 24));
101
-
102
- return {
103
- resumable: true,
104
- currentPhase: saved.current_phase,
105
- flowName: saved.workflow,
106
- stale: diffDays >= STALE_DAYS_THRESHOLD,
107
- staleDays: diffDays
108
- };
109
- } catch {
110
- return { resumable: false };
111
- }
112
- }
113
-
114
- /**
115
- * 從儲存的狀態恢復流程。
116
- * @returns {object} 恢復的狀態
117
- */
118
- resume() {
119
- const content = this.fs.readFileSync(this.statePath, 'utf-8');
120
- this.state = JSON.parse(content);
121
- return this.state;
122
- }
123
-
124
- /**
125
- * 儲存狀態到檔案。
126
- * @private
127
- */
128
- _save() {
129
- if (!this.state || !this.flow.config?.state_persistence) {
130
- // 如果 state_persistence 未定義,預設啟用
131
- if (this.flow.config && this.flow.config.state_persistence === false) {
132
- return;
133
- }
134
- }
135
-
136
- try {
137
- if (!this.fs.existsSync(this.stateDir)) {
138
- this.fs.mkdirSync(this.stateDir, { recursive: true });
139
- }
140
- this.fs.writeFileSync(this.statePath, JSON.stringify(this.state, null, 2));
141
- } catch {
142
- // 靜默失敗,不阻礙流程執行
143
- }
144
- }
145
- }
146
-
147
- function defaultFs() {
148
- return {
149
- existsSync: () => false,
150
- readFileSync: () => '',
151
- writeFileSync: () => {},
152
- mkdirSync: () => {}
153
- };
154
- }
@@ -1,100 +0,0 @@
1
- /**
2
- * Flow Inheritance — SPEC-FLOW-001
3
- *
4
- * 解析 extends/overrides/insert 語義,合併繼承鏈。
5
- */
6
-
7
- const MAX_INHERITANCE_DEPTH = 5;
8
-
9
- /**
10
- * 解析繼承鏈並合併為最終 Flow。
11
- * @param {object} flow - 子 flow
12
- * @param {Record<string, object>} flowRegistry - 所有可用 flow 的 id → flow 對映
13
- * @param {number} depth - 當前深度(內部用)
14
- * @returns {object} 合併後的 flow
15
- */
16
- export function resolveInheritance(flow, flowRegistry, depth = 0) {
17
- if (!flow.extends) {
18
- return structuredClone(flow);
19
- }
20
-
21
- if (depth >= MAX_INHERITANCE_DEPTH) {
22
- throw new Error(`繼承深度超過 ${MAX_INHERITANCE_DEPTH} 層限制(flow: ${flow.id})`);
23
- }
24
-
25
- const baseFlow = flowRegistry[flow.extends];
26
- if (!baseFlow) {
27
- throw new Error(`Base flow "${flow.extends}" 不存在(flow: ${flow.id})`);
28
- }
29
-
30
- // 遞迴解析 base flow 的繼承
31
- const resolvedBase = resolveInheritance(baseFlow, flowRegistry, depth + 1);
32
-
33
- // 從 base 開始合併
34
- const merged = structuredClone(resolvedBase);
35
- merged.id = flow.id;
36
- merged.name = flow.name;
37
- merged.extends = flow.extends;
38
-
39
- // 處理 overrides
40
- if (flow.overrides) {
41
- for (const override of flow.overrides) {
42
- applyOverride(merged, override);
43
- }
44
- }
45
-
46
- // 處理 insert
47
- if (flow.insert) {
48
- for (const insertion of flow.insert) {
49
- applyInsert(merged, insertion);
50
- }
51
- }
52
-
53
- return merged;
54
- }
55
-
56
- /**
57
- * 套用 override 到 merged flow。
58
- * @param {object} merged - 合併中的 flow
59
- * @param {object} override - override 定義
60
- */
61
- function applyOverride(merged, override) {
62
- const stage = merged.stages.find(s => s.id === override.stage);
63
- if (!stage) return;
64
-
65
- // add_steps
66
- if (override.add_steps) {
67
- stage.steps = [...stage.steps, ...override.add_steps];
68
- }
69
-
70
- // remove_steps
71
- if (override.remove_steps) {
72
- stage.steps = stage.steps.filter(
73
- step => !override.remove_steps.includes(step.command)
74
- );
75
- }
76
-
77
- // modify_gates
78
- if (override.modify_gates) {
79
- if (!stage.gates) stage.gates = [];
80
- for (const gateModification of override.modify_gates) {
81
- const existingGate = stage.gates.find(g => g.ref === gateModification.ref);
82
- if (existingGate) {
83
- Object.assign(existingGate, gateModification);
84
- } else {
85
- stage.gates.push(gateModification);
86
- }
87
- }
88
- }
89
- }
90
-
91
- /**
92
- * 在指定 stage 後插入新 stage。
93
- * @param {object} merged - 合併中的 flow
94
- * @param {object} insertion - insert 定義
95
- */
96
- function applyInsert(merged, insertion) {
97
- const afterIdx = merged.stages.findIndex(s => s.id === insertion.after);
98
- if (afterIdx === -1) return;
99
- merged.stages.splice(afterIdx + 1, 0, structuredClone(insertion.stage));
100
- }
@@ -1,104 +0,0 @@
1
- /**
2
- * Flow YAML Parser — SPEC-FLOW-001
3
- *
4
- * 解析 .flow.yaml 內容為 Flow 物件,包含 schema 驗證和預設值填充。
5
- */
6
-
7
- import * as yaml from 'js-yaml';
8
-
9
- const DEFAULT_CONFIG = {
10
- enforcement: 'suggest',
11
- allow_skip_optional: true,
12
- state_persistence: true,
13
- gate_timeout: 30
14
- };
15
-
16
- const MAX_GATE_TIMEOUT = 600;
17
-
18
- /**
19
- * 解析 Flow YAML 字串為 Flow 物件。
20
- * @param {string} yamlContent - Flow YAML 內容
21
- * @returns {object} 解析後的 Flow 物件
22
- * @throws {Error} YAML 語法錯誤或必填欄位缺失
23
- */
24
- export function parseFlow(yamlContent) {
25
- let raw;
26
- try {
27
- raw = yaml.load(yamlContent);
28
- } catch (err) {
29
- throw new Error(`Flow YAML 語法錯誤: ${err.message}`);
30
- }
31
-
32
- if (!raw || typeof raw !== 'object') {
33
- throw new Error('Flow YAML 內容無效:必須為物件');
34
- }
35
-
36
- // 必填:id
37
- if (!raw.id) {
38
- throw new Error('Flow YAML 缺少必填欄位: id');
39
- }
40
-
41
- // 必填:stages(除非有 extends)
42
- if (!raw.stages && !raw.extends) {
43
- throw new Error('Flow YAML 缺少必填欄位: stages(或使用 extends 繼承)');
44
- }
45
-
46
- // 驗證 stages 結構
47
- if (raw.stages) {
48
- validateStages(raw.stages);
49
- }
50
-
51
- // 填充預設值
52
- const config = { ...DEFAULT_CONFIG, ...(raw.config || {}) };
53
- if (config.gate_timeout > MAX_GATE_TIMEOUT) {
54
- config.gate_timeout = MAX_GATE_TIMEOUT;
55
- }
56
-
57
- if (raw.stages) {
58
- raw.stages = raw.stages.map(stage => ({
59
- ...stage,
60
- steps: stage.steps.map(step => ({
61
- required: true,
62
- ...step
63
- }))
64
- }));
65
- }
66
-
67
- return {
68
- ...raw,
69
- config
70
- };
71
- }
72
-
73
- /**
74
- * 驗證 stages 陣列結構。
75
- * @param {Array} stages
76
- * @throws {Error} 結構不合法
77
- */
78
- function validateStages(stages) {
79
- if (!Array.isArray(stages) || stages.length === 0) {
80
- throw new Error('Flow YAML stages 必須為非空陣列');
81
- }
82
-
83
- const seenIds = new Set();
84
-
85
- for (const stage of stages) {
86
- // stage.id 唯一性
87
- if (seenIds.has(stage.id)) {
88
- throw new Error(`Flow YAML stages 有重複的 stage id: duplicate "${stage.id}"`);
89
- }
90
- seenIds.add(stage.id);
91
-
92
- // steps 必填
93
- if (!stage.steps || !Array.isArray(stage.steps) || stage.steps.length === 0) {
94
- throw new Error(`Stage "${stage.id}" 缺少必填欄位: steps(至少一個 step)`);
95
- }
96
-
97
- // 每個 step 必須有 command
98
- for (const step of stage.steps) {
99
- if (!step.command) {
100
- throw new Error(`Stage "${stage.id}" 的 step 缺少必填欄位: command`);
101
- }
102
- }
103
- }
104
- }
@@ -1,37 +0,0 @@
1
- /**
2
- * Flow Validator — SPEC-FLOW-001
3
- *
4
- * 驗證已解析的 Flow 物件的邏輯正確性(命令引用、stage 一致性等)。
5
- */
6
-
7
- /**
8
- * 驗證 Flow 物件的邏輯正確性。
9
- * @param {object} flow - 已解析的 Flow 物件
10
- * @param {object} options - 驗證選項
11
- * @param {string[]} options.availableCommands - 可用的命令清單
12
- * @returns {Array<{type: string, message: string, suggestions?: string[]}>} 錯誤清單
13
- */
14
- export function validateFlow(flow, options = {}) {
15
- const errors = [];
16
- const { availableCommands = [] } = options;
17
-
18
- if (!flow.stages) {
19
- return errors;
20
- }
21
-
22
- for (const stage of flow.stages) {
23
- if (!stage.steps) continue;
24
-
25
- for (const step of stage.steps) {
26
- if (availableCommands.length > 0 && !availableCommands.includes(step.command)) {
27
- errors.push({
28
- type: 'invalid_command',
29
- message: `命令 ${step.command} 不存在(stage: ${stage.id})`,
30
- suggestions: availableCommands
31
- });
32
- }
33
- }
34
- }
35
-
36
- return errors;
37
- }
@@ -1,82 +0,0 @@
1
- /**
2
- * Gate Checker — SPEC-FLOW-001
3
- *
4
- * 執行閘門檢查並回傳結果。
5
- */
6
-
7
- const MAX_TIMEOUT = 600;
8
- const DEFAULT_TIMEOUT = 30;
9
-
10
- /**
11
- * 執行閘門的所有 checks。
12
- * @param {object} gate - Gate 物件
13
- * @param {object} options
14
- * @param {Function} options.executor - 命令執行器 (run, opts) => Promise<{exitCode, stdout}>
15
- * @param {number} [options.defaultTimeout=30] - 預設 timeout 秒數
16
- * @returns {Promise<{passed: boolean, blocking: boolean, message?: string, suggest?: string[], error?: string}>}
17
- */
18
- export async function checkGate(gate, options = {}) {
19
- const { executor, defaultTimeout = DEFAULT_TIMEOUT } = options;
20
- const isInfo = gate.type === 'info';
21
- const isBlocking = gate.type === 'blocking';
22
-
23
- for (const check of gate.checks) {
24
- let timeout = check.timeout || defaultTimeout;
25
- if (timeout > MAX_TIMEOUT) {
26
- timeout = MAX_TIMEOUT;
27
- }
28
-
29
- try {
30
- const result = await executor(check.run, { timeout });
31
-
32
- if (check.expect === 'exit_code_0' && result.exitCode !== 0) {
33
- if (isInfo) {
34
- return { passed: true, blocking: false };
35
- }
36
- return {
37
- passed: false,
38
- blocking: isBlocking,
39
- message: gate.on_failure?.message,
40
- suggest: gate.on_failure?.suggest
41
- };
42
- }
43
- } catch (err) {
44
- if (isInfo) {
45
- return { passed: true, blocking: false };
46
- }
47
- return {
48
- passed: false,
49
- blocking: isBlocking,
50
- error: err.message.includes('TIMEOUT')
51
- ? `Gate "${gate.id}" 執行超時(timeout: ${timeout}s)`
52
- : err.message,
53
- message: gate.on_failure?.message,
54
- suggest: gate.on_failure?.suggest
55
- };
56
- }
57
- }
58
-
59
- return { passed: true, blocking: isBlocking };
60
- }
61
-
62
- /**
63
- * 驗證閘門移除是否合法。
64
- * @param {object[]} baseGates - 基底 flow 的 gates
65
- * @param {string[]} removedGateIds - 要移除的 gate IDs
66
- * @returns {Array<{type: string, message: string}>} 錯誤清單
67
- */
68
- export function validateGateRemoval(baseGates, removedGateIds) {
69
- const errors = [];
70
-
71
- for (const gateId of removedGateIds) {
72
- const baseGate = baseGates.find(g => g.id === gateId);
73
- if (baseGate && baseGate.removable === false) {
74
- errors.push({
75
- type: 'non_removable_gate',
76
- message: `閘門 "${gateId}" 為強制要求,不可移除(removable: false)`
77
- });
78
- }
79
- }
80
-
81
- return errors;
82
- }
@@ -1,52 +0,0 @@
1
- /**
2
- * Gate Loader — SPEC-FLOW-001
3
- *
4
- * 載入和解析 .gate.yaml 閘門定義。
5
- */
6
-
7
- import * as yaml from 'js-yaml';
8
-
9
- /**
10
- * 從 YAML 字串載入 gate 定義。
11
- * @param {string} yamlContent - Gate YAML 內容
12
- * @returns {object} Gate 物件
13
- * @throws {Error} 必填欄位缺失
14
- */
15
- export function loadGate(yamlContent) {
16
- const raw = yaml.load(yamlContent);
17
-
18
- if (!raw || typeof raw !== 'object') {
19
- throw new Error('Gate YAML 內容無效');
20
- }
21
-
22
- if (!raw.id) {
23
- throw new Error('Gate YAML 缺少必填欄位: id');
24
- }
25
-
26
- if (!raw.checks || !Array.isArray(raw.checks) || raw.checks.length === 0) {
27
- throw new Error(`Gate "${raw.id}" 缺少必填欄位: checks(至少一個 check)`);
28
- }
29
-
30
- return {
31
- removable: true,
32
- ...raw
33
- };
34
- }
35
-
36
- /**
37
- * 從行內定義建立 gate 物件。
38
- * @param {object} inlineDef - 行內閘門定義(type, run, expect)
39
- * @returns {object} Gate 物件
40
- */
41
- export function loadInlineGate(inlineDef) {
42
- return {
43
- id: `inline-${Date.now()}`,
44
- name: 'Inline Gate',
45
- type: inlineDef.type || 'blocking',
46
- removable: true,
47
- checks: [{
48
- run: inlineDef.run,
49
- expect: inlineDef.expect
50
- }]
51
- };
52
- }