universal-dev-standards 6.14.0-beta.11 → 6.14.0-beta.13
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.
- package/bin/uds.js +8 -1
- package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
- package/bundled/core/secret-management-standards.md +13 -1
- package/bundled/hooks/validate-commit-msg.mjs +52 -9
- package/bundled/locales/zh-CN/CHANGELOG.md +3 -3
- package/bundled/locales/zh-CN/README.md +1 -1
- package/bundled/locales/zh-CN/SECURITY.md +1 -1
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -1
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +4 -3
- package/bundled/locales/zh-TW/CHANGELOG.md +3 -3
- package/bundled/locales/zh-TW/README.md +1 -1
- package/bundled/locales/zh-TW/SECURITY.md +1 -1
- package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -1
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +4 -3
- package/package.json +1 -1
- package/src/commands/audit.js +28 -1
- package/src/commands/check.js +72 -3
- package/src/commands/compile.js +37 -4
- package/src/commands/config.js +28 -19
- package/src/commands/init.js +59 -28
- package/src/commands/release-messages.js +228 -0
- package/src/commands/release.js +72 -72
- package/src/commands/spec.js +4 -2
- package/src/commands/update.js +114 -12
- package/src/compilers/claude-code-compiler.js +9 -1
- package/src/i18n/messages.js +96 -0
- package/src/installers/hooks-installer.js +1 -1
- package/src/mcp/server.js +9 -3
- package/src/prompts/init.js +17 -17
- package/src/reconciler/plan-executor.js +63 -5
- package/src/reconciler/recorded-versions.js +49 -0
- package/src/uninstallers/hook-uninstaller.js +9 -1
- package/src/uninstallers/skills-uninstaller.js +10 -3
- package/src/utils/available-standards-report.js +25 -4
- package/src/utils/available-standards.js +13 -3
- package/src/utils/build-manifest.js +1 -1
- package/src/utils/commit-message-judge.js +38 -9
- package/src/utils/friction-detector.js +23 -11
- package/src/utils/git-hooks.js +106 -4
- package/src/utils/integration-generator.js +75 -49
- package/src/utils/legacy-hook-migration.js +121 -2
- package/src/utils/sdd-header.js +11 -0
- package/src/utils/spinner.js +14 -4
- package/src/utils/standard-validator.js +3 -2
- package/standards-registry.json +10 -8
package/bin/uds.js
CHANGED
|
@@ -233,7 +233,8 @@ program
|
|
|
233
233
|
.option('--apply', 'Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope')
|
|
234
234
|
.option('--force', 'Force update all files, ignoring hash comparison')
|
|
235
235
|
.option('--prune', 'Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write)')
|
|
236
|
-
.option('--rollback', 'Rollback to the most recent backup')
|
|
236
|
+
.option('--rollback', 'Rollback to the most recent backup (with the series of updates that follow from it)')
|
|
237
|
+
.option('--from <backup>', 'With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made')
|
|
237
238
|
.option('--add-standard <id>', 'With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available)', (value, previous) => [...previous, value], [])
|
|
238
239
|
.option('--claude-target <target>', 'Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall')
|
|
239
240
|
.option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
|
|
@@ -308,11 +309,17 @@ program
|
|
|
308
309
|
console.error(result.error);
|
|
309
310
|
process.exit(1);
|
|
310
311
|
}
|
|
312
|
+
// What was left out goes to stderr in a dry run, so stdout stays the JSON it has always been.
|
|
313
|
+
const note = result.dryRun ? console.error : console.log;
|
|
311
314
|
if (result.dryRun) {
|
|
312
315
|
console.log(JSON.stringify(result.config, null, 2));
|
|
313
316
|
} else {
|
|
314
317
|
console.log(`Compiled ${result.compiledCount} enforcement standard(s) for ${options.target}`);
|
|
315
318
|
}
|
|
319
|
+
for (const s of result.skipped || []) note(` Skipped ${s.id}: ${s.why}`);
|
|
320
|
+
if ((result.skipped || []).length > 0) {
|
|
321
|
+
note(' Install the hook scripts with \'uds update --with-hooks\' (or \'uds init --with-hooks\'), then compile again.');
|
|
322
|
+
}
|
|
316
323
|
});
|
|
317
324
|
|
|
318
325
|
program
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
id: secret-management-standards
|
|
5
5
|
title: Secret Management and Credential Hygiene Standards
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.1.0"
|
|
7
7
|
status: Active
|
|
8
8
|
tags: [secrets, vault, kms, sops, security, rotation, credential-management]
|
|
9
9
|
summary: |
|
|
@@ -67,9 +67,20 @@ requirements:
|
|
|
67
67
|
format (AKIA[0-9A-Z]{16}), PEM private key headers (-----BEGIN .* PRIVATE KEY),
|
|
68
68
|
generic API token patterns (api[_-]?key\s*[:=]\s*\S{16,}), and
|
|
69
69
|
connection strings containing passwords.
|
|
70
|
+
How the scanners are run is governed by pipeline-security-gates
|
|
71
|
+
(PSG-1 to PSG-3): PSG-1 the scan output MUST NOT contain the matched
|
|
72
|
+
secret value (file, line and rule name only); PSG-2 a scanner that
|
|
73
|
+
cannot run counts as a failed gate and MUST block the commit or
|
|
74
|
+
pipeline; PSG-3 every detection rule the team writes itself SHOULD have
|
|
75
|
+
a red sample (must be caught) and a green sample (must not be
|
|
76
|
+
reported), executed in a test.
|
|
70
77
|
level: MUST
|
|
78
|
+
references:
|
|
79
|
+
- pipeline-security-gates
|
|
71
80
|
examples:
|
|
72
81
|
- "`.pre-commit-config.yaml` includes `detect-secrets` hook; fails on AWS key pattern"
|
|
82
|
+
- "PSG-1: CI log shows `rule aws-access-key at config/dev.env:12`, never the key itself (gitleaks run with `--redact`)"
|
|
83
|
+
- "PSG-2: gitleaks binary missing in the CI image -> the job fails, it does not pass with no scan"
|
|
73
84
|
- "CI step: `gitleaks detect --source . --exit-code 1` blocks PR merge"
|
|
74
85
|
- "False positive whitelisted via `.secrets.baseline` with documented justification"
|
|
75
86
|
- "Developer receives pre-commit error: 'High confidence secret detected: AWS Access Key'"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Secret Management and Credential Hygiene Standards
|
|
2
2
|
|
|
3
|
-
> **Version**: 1.
|
|
3
|
+
> **Version**: 1.1.0 | **Status**: Active | **Updated**: 2026-10-12
|
|
4
4
|
> **AI-optimized version**: `ai/standards/secret-management-standards.ai.yaml`
|
|
5
5
|
> **Spec**: XSPEC-065 (cross-project/specs/XSPEC-065-uds-infrastructure-pack.md)
|
|
6
6
|
|
|
@@ -69,6 +69,14 @@ detected patterns: AWS access key format (`AKIA[0-9A-Z]{16}`), PEM private key
|
|
|
69
69
|
headers (`-----BEGIN .* PRIVATE KEY`), generic API token patterns
|
|
70
70
|
(`api[_-]?key\s*[:=]\s*\S{16,}`), and connection strings containing passwords.
|
|
71
71
|
|
|
72
|
+
How the scanners are run is governed by [`pipeline-security-gates`](./pipeline-security-gates.md), and the
|
|
73
|
+
three rules there apply to every scanner this requirement asks for: **PSG-1** — the scan output (terminal, CI log,
|
|
74
|
+
report file) MUST NOT contain the matched secret value, only the file, the line and the rule name; **PSG-2** — a
|
|
75
|
+
scanner that cannot run (not installed, crashed, no network for its rules) counts as a failed gate and MUST block the
|
|
76
|
+
commit or the pipeline, never let it through; **PSG-3** — every detection rule the team writes itself SHOULD have one
|
|
77
|
+
sample that must be caught (red) and one that must not be reported (green), executed in a test. The four minimum
|
|
78
|
+
patterns above are the rules PSG-3 applies to when a team writes its own.
|
|
79
|
+
|
|
72
80
|
### REQ-004 — Secret Injection
|
|
73
81
|
|
|
74
82
|
Secrets MUST be injected into application processes via environment variables or
|
|
@@ -91,6 +99,9 @@ secrets as read-only volumes with restrictive file permissions (0400 or 0600).
|
|
|
91
99
|
|
|
92
100
|
- **`iac-design-principles`** — secret backends (Vault/KMS state) are themselves
|
|
93
101
|
versioned, access-controlled infrastructure.
|
|
102
|
+
- **`pipeline-security-gates`** — PSG-1 to PSG-3 govern how the scanners of REQ-003 are run (no secret value in
|
|
103
|
+
their output, a scanner that cannot run blocks, red and green samples for self-written rules); the two standards
|
|
104
|
+
point at each other.
|
|
94
105
|
- **`audit-trail`** — rotation, access, and injection events are auditable
|
|
95
106
|
operations (REQ-002 mandates logging rotation events).
|
|
96
107
|
- **`pii-classification`** — credentials guarding TIER-1 PII inherit the strictest
|
|
@@ -107,4 +118,5 @@ secrets as read-only volumes with restrictive file permissions (0400 or 0600).
|
|
|
107
118
|
|
|
108
119
|
| Version | Date | Changes |
|
|
109
120
|
|---------|------|---------|
|
|
121
|
+
| v1.1.0 | 2026-10-12 | REQ-003 points to `pipeline-security-gates` PSG-1 to PSG-3 for how the scanners are run; integration section lists the cross-reference (XSPEC-475 OQ3) |
|
|
110
122
|
| v1.0.0 | 2026-06-17 | Initial — REQ-001~004: secret source options, rotation policy, hardcoded-secret prevention, secret injection (XSPEC-065) |
|
|
@@ -23,30 +23,73 @@
|
|
|
23
23
|
* @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-1)
|
|
24
24
|
*/
|
|
25
25
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
26
|
+
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
27
|
+
import { join } from 'node:path';
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Used only when the project has no commit-message option file: the Conventional Commits set. Same list `uds simulate
|
|
31
|
+
* -s commit-message` falls back to (FALLBACK_TYPES in cli/src/utils/commit-message-judge.js).
|
|
32
|
+
*/
|
|
33
|
+
const FALLBACK_TYPES = [
|
|
34
|
+
'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert',
|
|
29
35
|
];
|
|
30
36
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
)
|
|
37
|
+
/**
|
|
38
|
+
* The commit types the project allows: those listed by the commit-message option files installed in
|
|
39
|
+
* `.standards/options/` (a file whose `meta.parent` is `commit-message`), or the fallback set when there are none.
|
|
40
|
+
*
|
|
41
|
+
* XSPEC-482 R12: this was a fixed list that lacked `security`, so `uds simulate` (which reads these same files) passed
|
|
42
|
+
* `security(auth): rotate keys` and this hook refused it. The two now read one source. The hook has no YAML parser
|
|
43
|
+
* to lean on (it runs in the adopter's project with no dependencies), so it reads the two things it needs line by line:
|
|
44
|
+
* the `parent:` of the `meta:` block and the `- type:` entries under `types:`.
|
|
45
|
+
*
|
|
46
|
+
* @param {string} [root] - the project root; defaults to $CLAUDE_PROJECT_DIR or the working directory
|
|
47
|
+
* @returns {string[]}
|
|
48
|
+
*/
|
|
49
|
+
export function allowedTypes(root = process.env.CLAUDE_PROJECT_DIR || process.cwd()) {
|
|
50
|
+
const found = new Set();
|
|
51
|
+
const optionsDir = join(root, '.standards', 'options');
|
|
52
|
+
for (const dir of [optionsDir, join(optionsDir, 'commit-message')]) {
|
|
53
|
+
if (!existsSync(dir)) continue;
|
|
54
|
+
let names = [];
|
|
55
|
+
try { names = readdirSync(dir).filter((n) => n.endsWith('.ai.yaml')); } catch { continue; }
|
|
56
|
+
for (const name of names) {
|
|
57
|
+
let text = '';
|
|
58
|
+
try { text = readFileSync(join(dir, name), 'utf-8').replace(/\r\n/g, '\n'); } catch { continue; }
|
|
59
|
+
if (!/^\s+parent:\s*["']?commit-message["']?\s*$/m.test(text)) continue;
|
|
60
|
+
const lines = text.split('\n');
|
|
61
|
+
const start = lines.findIndex((l) => /^types:\s*$/.test(l));
|
|
62
|
+
if (start === -1) continue;
|
|
63
|
+
for (let i = start + 1; i < lines.length; i++) {
|
|
64
|
+
if (/^\S/.test(lines[i]) && !lines[i].startsWith('#')) break; // next top-level key
|
|
65
|
+
const m = /^\s*-\s+type:\s*["']?([^"'#\s][^"'#]*?)["']?\s*(?:#.*)?$/.exec(lines[i]);
|
|
66
|
+
if (m) found.add(m[1]);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return found.size > 0 ? [...found] : FALLBACK_TYPES;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const escapeRe = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
34
74
|
|
|
35
75
|
/**
|
|
36
76
|
* Validate a commit message against Conventional Commits format.
|
|
37
77
|
* @param {string} msg - The commit message to validate
|
|
78
|
+
* @param {string[]} [types] - the allowed types (default: the project's, see allowedTypes)
|
|
38
79
|
* @returns {boolean} true if valid
|
|
39
80
|
*/
|
|
40
|
-
export function validateCommitMessage(msg) {
|
|
81
|
+
export function validateCommitMessage(msg, types = allowedTypes()) {
|
|
41
82
|
if (!msg || typeof msg !== 'string') return false;
|
|
42
|
-
|
|
83
|
+
// `type(scope)!: subject`: scope and the breaking-change mark are optional, as in `uds simulate`.
|
|
84
|
+
const pattern = new RegExp(`^(${types.map(escapeRe).join('|')})(\\(.+\\))?!?:\\s.+`, 'u');
|
|
85
|
+
return pattern.test(msg.trim());
|
|
43
86
|
}
|
|
44
87
|
|
|
45
88
|
// CLI mode.
|
|
46
89
|
function complain(msg) {
|
|
47
90
|
console.error(`❌ Invalid commit message format: "${msg}"`);
|
|
48
91
|
console.error(` Expected: <type>(<scope>): <subject>`);
|
|
49
|
-
console.error(` Valid types: ${
|
|
92
|
+
console.error(` Valid types: ${allowedTypes().join(', ')}`);
|
|
50
93
|
}
|
|
51
94
|
|
|
52
95
|
/**
|
|
@@ -15,7 +15,7 @@ status: current
|
|
|
15
15
|
|
|
16
16
|
> **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
|
|
17
17
|
|
|
18
|
-
**版本**: 6.14.0-beta.
|
|
18
|
+
**版本**: 6.14.0-beta.13 (Pre-release) | **发布日期**: 2026-10-10 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
|
|
19
19
|
|
|
20
20
|
语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
|
|
21
21
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# UDS 功能参考手册
|
|
2
2
|
|
|
3
3
|
> Universal Development Standards - 完整功能文档
|
|
4
|
-
> Auto-generated | Last updated: 2026-10-
|
|
4
|
+
> Auto-generated | Last updated: 2026-10-13
|
|
5
5
|
|
|
6
6
|
**Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
|
|
7
7
|
|
|
@@ -155,7 +155,8 @@
|
|
|
155
155
|
| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
|
|
156
156
|
| `--force` | Force update all files, ignoring hash comparison |
|
|
157
157
|
| `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
|
|
158
|
-
| `--rollback` | Rollback to the most recent backup |
|
|
158
|
+
| `--rollback` | Rollback to the most recent backup (with the series of updates that follow from it) |
|
|
159
|
+
| `--from` | With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made |
|
|
159
160
|
| `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
|
|
160
161
|
| `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
|
|
161
162
|
| `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
|
|
@@ -557,7 +558,7 @@
|
|
|
557
558
|
| `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
|
|
558
559
|
| `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
|
|
559
560
|
| `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
|
|
560
|
-
| `secret-management-standards` | 1.
|
|
561
|
+
| `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
|
|
561
562
|
| `secure-op` | - | |
|
|
562
563
|
| `security-decision` | - | |
|
|
563
564
|
| `security-standards` | 1.1.0 | This standard defines comprehensive security guidelines for software development |
|
|
@@ -15,7 +15,7 @@ status: current
|
|
|
15
15
|
|
|
16
16
|
> **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
|
|
17
17
|
|
|
18
|
-
**版本**: 6.14.0-beta.
|
|
18
|
+
**版本**: 6.14.0-beta.13 (Pre-release) | **發布日期**: 2026-10-10 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
|
|
19
19
|
|
|
20
20
|
語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
|
|
21
21
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/secret-management-standards.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-10-12
|
|
6
|
+
source_hash: 0d663eb39b8a
|
|
7
7
|
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -65,6 +65,12 @@ staged 檔案,偵測到 pattern 即封鎖 commit;(2) **CI 管線掃描**—
|
|
|
65
65
|
(`AKIA[0-9A-Z]{16}`)、PEM 私鑰標頭(`-----BEGIN .* PRIVATE KEY`)、通用 API token
|
|
66
66
|
pattern(`api[_-]?key\s*[:=]\s*\S{16,}`),以及含密碼的連線字串。
|
|
67
67
|
|
|
68
|
+
掃描器如何執行由 [`pipeline-security-gates`](./pipeline-security-gates.md) 規範,其中三條規則適用於本需求要求的每個
|
|
69
|
+
掃描器:**PSG-1**——掃描輸出(終端機、CI 紀錄、報告檔)MUST NOT 包含被匹配到的機密值本身,只能指出檔案、行號與規則名稱;
|
|
70
|
+
**PSG-2**——無法執行的掃描器(未安裝、崩潰、規則無法取得)視同閘門失敗,MUST 阻斷 commit 或 pipeline,不得放行;
|
|
71
|
+
**PSG-3**——團隊自己撰寫的每條偵測規則 SHOULD 有一個必須被抓到(紅)與一個不得被誤報(綠)的樣本,並在測試中執行。
|
|
72
|
+
上述四種最低 pattern 即是團隊自寫規則時 PSG-3 所適用的規則。
|
|
73
|
+
|
|
68
74
|
### REQ-004 — 機密注入
|
|
69
75
|
|
|
70
76
|
機密 MUST 僅透過環境變數或掛載檔案注入應用程式程序。透過命令列參數傳遞機密為
|
|
@@ -85,6 +91,7 @@ volume,並使用限制性檔案權限(0400 或 0600)。
|
|
|
85
91
|
|
|
86
92
|
- **`iac-design-principles`**——機密後端(Vault/KMS 狀態)本身即是版本化、受存取
|
|
87
93
|
控制的基礎設施。
|
|
94
|
+
- **`pipeline-security-gates`**——PSG-1~PSG-3 規範 REQ-003 掃描器的執行方式(輸出不含機密值、掃描器跑不起來即阻斷、自寫規則要有紅綠樣本);兩份標準互相指向。
|
|
88
95
|
- **`audit-trail`**——輪替、存取與注入事件為可稽核操作(REQ-002 要求記錄輪替事件)。
|
|
89
96
|
- **`pii-classification`**——守護 TIER-1 PII 的憑證承襲最嚴格的處理控制。
|
|
90
97
|
- **`security-standards`**——本標準是更廣安全基線的憑證衛生面向。
|
|
@@ -98,4 +105,5 @@ volume,並使用限制性檔案權限(0400 或 0600)。
|
|
|
98
105
|
|
|
99
106
|
| 版本 | 日期 | 變更 |
|
|
100
107
|
|------|------|------|
|
|
108
|
+
| v1.1.0 | 2026-10-12 | REQ-003 指向 `pipeline-security-gates` 的 PSG-1~PSG-3(掃描器的執行方式);整合章節列出交叉引用(XSPEC-475 OQ3) |
|
|
101
109
|
| v1.0.0 | 2026-06-17 | 初版——REQ-001~004:機密來源選項、輪替政策、硬編碼機密防護、機密注入(XSPEC-065) |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# UDS 功能參考手冊
|
|
2
2
|
|
|
3
3
|
> Universal Development Standards - 完整功能文件
|
|
4
|
-
> Auto-generated | Last updated: 2026-10-
|
|
4
|
+
> Auto-generated | Last updated: 2026-10-13
|
|
5
5
|
|
|
6
6
|
**Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
|
|
7
7
|
|
|
@@ -155,7 +155,8 @@
|
|
|
155
155
|
| `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
|
|
156
156
|
| `--force` | Force update all files, ignoring hash comparison |
|
|
157
157
|
| `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
|
|
158
|
-
| `--rollback` | Rollback to the most recent backup |
|
|
158
|
+
| `--rollback` | Rollback to the most recent backup (with the series of updates that follow from it) |
|
|
159
|
+
| `--from` | With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made |
|
|
159
160
|
| `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
|
|
160
161
|
| `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
|
|
161
162
|
| `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
|
|
@@ -557,7 +558,7 @@
|
|
|
557
558
|
| `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
|
|
558
559
|
| `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
|
|
559
560
|
| `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
|
|
560
|
-
| `secret-management-standards` | 1.
|
|
561
|
+
| `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
|
|
561
562
|
| `secure-op` | - | |
|
|
562
563
|
| `security-decision` | - | |
|
|
563
564
|
| `security-standards` | 1.1.0 | This standard defines comprehensive security guidelines for software development |
|
package/package.json
CHANGED
package/src/commands/audit.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
14
|
import chalk from 'chalk';
|
|
15
|
-
import { checkbox, input } from '@inquirer/prompts';
|
|
15
|
+
import { checkbox, input, confirm } from '@inquirer/prompts';
|
|
16
16
|
import { createRequire } from 'node:module';
|
|
17
17
|
import { existsSync, readFileSync } from 'node:fs';
|
|
18
18
|
import { resolve as resolvePath } from 'node:path';
|
|
@@ -465,6 +465,33 @@ async function handleReport(auditResult, options, msg) {
|
|
|
465
465
|
|
|
466
466
|
const issue = formatIssueContent(filteredResult, userComments);
|
|
467
467
|
|
|
468
|
+
// XSPEC-482 R14g: what is about to be sent is shown in full, and sent only after a yes. The interactive path used to go
|
|
469
|
+
// from "your comments" straight to a public issue under the user's GitHub account, so the person never saw the text
|
|
470
|
+
// they were sending. `--yes` (CI, scripts) stays as it was, and a dry run already prints the same text.
|
|
471
|
+
if (!isDryRun && !submitAll) {
|
|
472
|
+
console.log();
|
|
473
|
+
console.log(chalk.bold(msg.reviewBeforeSend || 'This is the report that will be sent:'));
|
|
474
|
+
console.log(chalk.gray('─'.repeat(40)));
|
|
475
|
+
console.log(chalk.cyan(`Title: ${issue.title}`));
|
|
476
|
+
console.log(chalk.cyan(`Labels: ${issue.labels.join(', ')}`));
|
|
477
|
+
console.log(chalk.gray('─'.repeat(40)));
|
|
478
|
+
console.log(issue.body);
|
|
479
|
+
console.log(chalk.gray('─'.repeat(40)));
|
|
480
|
+
let send = false;
|
|
481
|
+
try {
|
|
482
|
+
send = await confirm({
|
|
483
|
+
message: msg.confirmSend || `Send this report as a public issue to ${REPO}?`, // wire:audit-report-confirms
|
|
484
|
+
default: false
|
|
485
|
+
});
|
|
486
|
+
} catch (err) {
|
|
487
|
+
if (!(err && err.name === 'ExitPromptError')) throw err;
|
|
488
|
+
}
|
|
489
|
+
if (!send) {
|
|
490
|
+
console.log(chalk.yellow(msg.notSent || 'Not sent. Nothing was submitted.'));
|
|
491
|
+
return;
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
|
|
468
495
|
if (isDryRun) {
|
|
469
496
|
console.log();
|
|
470
497
|
console.log(chalk.bold(msg.dryRunNotice || 'Dry run — no issue created'));
|
package/src/commands/check.js
CHANGED
|
@@ -315,6 +315,37 @@ function displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate)
|
|
|
315
315
|
}
|
|
316
316
|
}
|
|
317
317
|
|
|
318
|
+
/**
|
|
319
|
+
* `uds check --json` (without --standard / --i18n): run the whole check with its text held back, then print one JSON
|
|
320
|
+
* document. Held back means console output and anything written to stdout while it runs (a spinner, a warning from a
|
|
321
|
+
* helper); what the check decides is read from the report the main body fills in. The exit code is the one the text mode
|
|
322
|
+
* would give (`--ci` and a non-compliant project: 1).
|
|
323
|
+
* @param {Object} options
|
|
324
|
+
*/
|
|
325
|
+
async function checkAsJson(options) {
|
|
326
|
+
const report = { initialized: null, compliant: null };
|
|
327
|
+
const realWrite = process.stdout.write.bind(process.stdout);
|
|
328
|
+
const quiet = () => true;
|
|
329
|
+
const saved = { log: console.log, info: console.info, warn: console.warn };
|
|
330
|
+
process.stdout.write = quiet;
|
|
331
|
+
console.log = console.info = console.warn = () => {};
|
|
332
|
+
try {
|
|
333
|
+
await checkCommand({ ...options, _report: report });
|
|
334
|
+
} finally {
|
|
335
|
+
process.stdout.write = realWrite;
|
|
336
|
+
console.log = saved.log;
|
|
337
|
+
console.info = saved.info;
|
|
338
|
+
console.warn = saved.warn;
|
|
339
|
+
}
|
|
340
|
+
const completed = report.compliant !== null;
|
|
341
|
+
console.log(JSON.stringify({
|
|
342
|
+
success: report.compliant === true,
|
|
343
|
+
initialized: report.initialized,
|
|
344
|
+
completed,
|
|
345
|
+
...report
|
|
346
|
+
}, null, 2));
|
|
347
|
+
}
|
|
348
|
+
|
|
318
349
|
/**
|
|
319
350
|
* Check command - verify adoption status
|
|
320
351
|
* @param {Object} options - Command options
|
|
@@ -376,9 +407,20 @@ export async function checkCommand(options = {}) {
|
|
|
376
407
|
return;
|
|
377
408
|
}
|
|
378
409
|
|
|
410
|
+
// XSPEC-482 R9: `--json` is documented as "Output result in JSON format" and used to be honoured only together with
|
|
411
|
+
// `--standard` / `--i18n`; on its own it printed the human text. The checks below run unchanged with their text held
|
|
412
|
+
// back, and what they found is printed as one JSON document.
|
|
413
|
+
if (options.json && !options._report) {
|
|
414
|
+
await checkAsJson(options); // wire:check-json-prints-json
|
|
415
|
+
return;
|
|
416
|
+
}
|
|
417
|
+
|
|
379
418
|
// Phase 0: Initialization
|
|
380
419
|
const context = initializeCheckContext(projectPath);
|
|
381
|
-
if (!context)
|
|
420
|
+
if (!context) {
|
|
421
|
+
if (options._report) options._report.initialized = false;
|
|
422
|
+
return;
|
|
423
|
+
}
|
|
382
424
|
|
|
383
425
|
const { manifest, msg, common, repoInfo } = context;
|
|
384
426
|
|
|
@@ -389,7 +431,10 @@ export async function checkCommand(options = {}) {
|
|
|
389
431
|
// XSPEC-342 R1:先問 npm 最新,判斷「已裝標準」是否落後(離線則跳過,不誤用 CLI bundled 版本)。
|
|
390
432
|
// fetchLatestVersion 有 60s 模組級快取,故此處與下方 checkCliVersion 共兩次呼叫只打一次網路。
|
|
391
433
|
let standardsUpdate = null;
|
|
392
|
-
|
|
434
|
+
// XSPEC-482 R14e: UDS_NO_UPDATE_CHECK=1 is the documented switch for "do not ask the npm registry"; `check` asked
|
|
435
|
+
// anyway (and wrote ~/.uds/update-check.json) unless --offline was also given. The variable now counts as --offline here.
|
|
436
|
+
const offline = options.offline || process.env.UDS_NO_UPDATE_CHECK === '1'; // wire:check-honours-no-update-check
|
|
437
|
+
if (!offline) {
|
|
393
438
|
standardsUpdate = await checkForUpdates(manifest.upstream.version, {
|
|
394
439
|
checkBeta: manifest.upstream.version.includes('-')
|
|
395
440
|
});
|
|
@@ -399,7 +444,7 @@ export async function checkCommand(options = {}) {
|
|
|
399
444
|
displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate);
|
|
400
445
|
|
|
401
446
|
// Check for CLI updates from npm registry (unless --offline)
|
|
402
|
-
if (!
|
|
447
|
+
if (!offline) {
|
|
403
448
|
await checkCliVersion(repoInfo.standards.version);
|
|
404
449
|
}
|
|
405
450
|
|
|
@@ -592,6 +637,30 @@ export async function checkCommand(options = {}) {
|
|
|
592
637
|
integrationBlockStatus.missing.length === 0 &&
|
|
593
638
|
integrationBlockStatus.noMarkers.length === 0 &&
|
|
594
639
|
integrationBlockStatus.ambiguous.length === 0;
|
|
640
|
+
if (options._report) {
|
|
641
|
+
Object.assign(options._report, {
|
|
642
|
+
initialized: true,
|
|
643
|
+
compliant: allGood,
|
|
644
|
+
version: manifest.upstream?.version ?? null,
|
|
645
|
+
installed: manifest.upstream?.installed ?? null,
|
|
646
|
+
files: {
|
|
647
|
+
unchanged: fileStatus.unchanged.length,
|
|
648
|
+
modified: fileStatus.modified,
|
|
649
|
+
missing: fileStatus.missing,
|
|
650
|
+
retired: fileStatus.retired || []
|
|
651
|
+
},
|
|
652
|
+
skillIssues: skillIssues.length,
|
|
653
|
+
commandIssues: commandIssues.length,
|
|
654
|
+
integrationBlocks: {
|
|
655
|
+
modified: integrationBlockStatus.modified,
|
|
656
|
+
missing: integrationBlockStatus.missing,
|
|
657
|
+
noMarkers: integrationBlockStatus.noMarkers,
|
|
658
|
+
ambiguous: integrationBlockStatus.ambiguous
|
|
659
|
+
},
|
|
660
|
+
testChangeBlocked: !!testChange.blocked,
|
|
661
|
+
testGatesBlocked: !!testGates.blocked
|
|
662
|
+
});
|
|
663
|
+
}
|
|
595
664
|
if (allGood) {
|
|
596
665
|
console.log(chalk.green(msg.projectCompliant));
|
|
597
666
|
} else {
|
package/src/commands/compile.js
CHANGED
|
@@ -12,6 +12,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from
|
|
|
12
12
|
import { join } from 'path';
|
|
13
13
|
import { load } from 'js-yaml';
|
|
14
14
|
import { ClaudeCodeCompiler } from '../compilers/claude-code-compiler.js';
|
|
15
|
+
import { mergeHookArray, normalizeMatcher } from '../installers/hooks-installer.js';
|
|
15
16
|
|
|
16
17
|
const COMPILERS = {
|
|
17
18
|
'claude-code': ClaudeCodeCompiler,
|
|
@@ -37,6 +38,17 @@ function parseStandard(filePath) {
|
|
|
37
38
|
}
|
|
38
39
|
}
|
|
39
40
|
|
|
41
|
+
/**
|
|
42
|
+
* An entry an earlier `uds compile` wrote with an object matcher (`{ "tool": "Bash" }`) is brought to the string form.
|
|
43
|
+
* Only entries that run a UDS hook script (`node scripts/hooks/...`) are touched; any other entry is returned as it is.
|
|
44
|
+
*/
|
|
45
|
+
function repairUdsMatcher(entry) {
|
|
46
|
+
const command = entry && entry.hooks && entry.hooks[0] && entry.hooks[0].command;
|
|
47
|
+
if (typeof command !== 'string' || !command.startsWith('node scripts/hooks/')) return entry;
|
|
48
|
+
if (typeof entry.matcher === 'string' || entry.matcher === undefined) return entry;
|
|
49
|
+
return { ...entry, matcher: normalizeMatcher(entry.matcher) };
|
|
50
|
+
}
|
|
51
|
+
|
|
40
52
|
/**
|
|
41
53
|
* Compile enforcement standards into target-specific hook configurations.
|
|
42
54
|
*
|
|
@@ -72,10 +84,22 @@ export function compileStandards(projectPath, options = {}) {
|
|
|
72
84
|
.map((f) => parseStandard(join(standardsDir, f)))
|
|
73
85
|
.filter(Boolean);
|
|
74
86
|
|
|
87
|
+
// Only a standard whose hook script is really in the project is compiled. A settings.json entry for a script that
|
|
88
|
+
// is not there makes the tool fail on every call of that event (XSPEC-482 R4c); `uds init --with-hooks` /
|
|
89
|
+
// `uds update --with-hooks` skip such a standard and say so, and so does this.
|
|
90
|
+
const skipped = [];
|
|
91
|
+
const present = standards.filter((s) => {
|
|
92
|
+
if (s.enforcement == null) return true;
|
|
93
|
+
const script = s.enforcement.hook_script;
|
|
94
|
+
if (typeof script === 'string' && script && existsSync(join(projectPath, script))) return true; // wire:compile-skips-missing-script
|
|
95
|
+
skipped.push({ id: s.id || s._file, why: `hook script not found: ${script ?? '(none declared)'}` });
|
|
96
|
+
return false;
|
|
97
|
+
});
|
|
98
|
+
|
|
75
99
|
// Compile
|
|
76
100
|
const compiler = new CompilerClass();
|
|
77
|
-
const config = compiler.compile(
|
|
78
|
-
const compiledCount = compiler.filterEnforceable(
|
|
101
|
+
const config = compiler.compile(present);
|
|
102
|
+
const compiledCount = compiler.filterEnforceable(present).length;
|
|
79
103
|
|
|
80
104
|
// Write output (unless dry-run)
|
|
81
105
|
if (!options.dryRun && compiledCount > 0) {
|
|
@@ -96,8 +120,16 @@ export function compileStandards(projectPath, options = {}) {
|
|
|
96
120
|
}
|
|
97
121
|
}
|
|
98
122
|
|
|
99
|
-
// Merge hooks
|
|
100
|
-
|
|
123
|
+
// Merge hooks the way `uds update --with-hooks` does (XSPEC-482 R4a): the project's own entries, on the same event
|
|
124
|
+
// or not, stay exactly as they are, and an entry UDS already wrote is not written twice. This used to replace the
|
|
125
|
+
// whole array of every event the standards touched, which deleted a user's own hook on that event.
|
|
126
|
+
settings.hooks = settings.hooks || {};
|
|
127
|
+
for (const [event, entries] of Object.entries(settings.hooks)) {
|
|
128
|
+
settings.hooks[event] = (entries || []).map(repairUdsMatcher);
|
|
129
|
+
}
|
|
130
|
+
for (const [event, incoming] of Object.entries(config.hooks)) {
|
|
131
|
+
settings.hooks[event] = mergeHookArray(settings.hooks[event] || [], incoming); // wire:compile-merges-hooks
|
|
132
|
+
}
|
|
101
133
|
writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
|
|
102
134
|
}
|
|
103
135
|
|
|
@@ -105,6 +137,7 @@ export function compileStandards(projectPath, options = {}) {
|
|
|
105
137
|
success: true,
|
|
106
138
|
config,
|
|
107
139
|
compiledCount,
|
|
140
|
+
skipped,
|
|
108
141
|
dryRun: !!options.dryRun,
|
|
109
142
|
};
|
|
110
143
|
}
|