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.
Files changed (46) hide show
  1. package/bin/uds.js +8 -1
  2. package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
  3. package/bundled/core/secret-management-standards.md +13 -1
  4. package/bundled/hooks/validate-commit-msg.mjs +52 -9
  5. package/bundled/locales/zh-CN/CHANGELOG.md +3 -3
  6. package/bundled/locales/zh-CN/README.md +1 -1
  7. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  8. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -1
  9. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +4 -3
  10. package/bundled/locales/zh-TW/CHANGELOG.md +3 -3
  11. package/bundled/locales/zh-TW/README.md +1 -1
  12. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  13. package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
  14. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -1
  15. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +4 -3
  16. package/package.json +1 -1
  17. package/src/commands/audit.js +28 -1
  18. package/src/commands/check.js +72 -3
  19. package/src/commands/compile.js +37 -4
  20. package/src/commands/config.js +28 -19
  21. package/src/commands/init.js +59 -28
  22. package/src/commands/release-messages.js +228 -0
  23. package/src/commands/release.js +72 -72
  24. package/src/commands/spec.js +4 -2
  25. package/src/commands/update.js +114 -12
  26. package/src/compilers/claude-code-compiler.js +9 -1
  27. package/src/i18n/messages.js +96 -0
  28. package/src/installers/hooks-installer.js +1 -1
  29. package/src/mcp/server.js +9 -3
  30. package/src/prompts/init.js +17 -17
  31. package/src/reconciler/plan-executor.js +63 -5
  32. package/src/reconciler/recorded-versions.js +49 -0
  33. package/src/uninstallers/hook-uninstaller.js +9 -1
  34. package/src/uninstallers/skills-uninstaller.js +10 -3
  35. package/src/utils/available-standards-report.js +25 -4
  36. package/src/utils/available-standards.js +13 -3
  37. package/src/utils/build-manifest.js +1 -1
  38. package/src/utils/commit-message-judge.js +38 -9
  39. package/src/utils/friction-detector.js +23 -11
  40. package/src/utils/git-hooks.js +106 -4
  41. package/src/utils/integration-generator.js +75 -49
  42. package/src/utils/legacy-hook-migration.js +121 -2
  43. package/src/utils/sdd-header.js +11 -0
  44. package/src/utils/spinner.js +14 -4
  45. package/src/utils/standard-validator.js +3 -2
  46. package/standards-registry.json +10 -8
@@ -26,6 +26,7 @@ import { execSync } from 'child_process';
26
26
  import { createHash } from 'crypto';
27
27
  import { resolveReleaseWorkflow, VALID_MODES } from '../utils/release-config.js';
28
28
  import { formatGitTag, parseRCVersion, isStableVersion } from '../utils/version-promote.js';
29
+ import { releaseText } from './release-messages.js';
29
30
 
30
31
  // Default deployment environments (overridable via release-config.yaml release.environments)
31
32
  const DEFAULT_ENVIRONMENTS = ['development', 'staging', 'canary', 'preview', 'production'];
@@ -43,7 +44,7 @@ function loadReleaseConfig(projectPath) {
43
44
  try {
44
45
  return yaml.load(readFileSync(configPath, 'utf-8'));
45
46
  } catch (err) {
46
- console.log(chalk.yellow(`⚠ release-config.yaml 解析失敗: ${err.message}`));
47
+ console.log(chalk.yellow(releaseText().configParseFailed(err.message)));
47
48
  return null;
48
49
  }
49
50
  }
@@ -76,24 +77,23 @@ function manifestReleaseMode(projectPath) {
76
77
  */
77
78
  function resolveReleaseMode(projectPath, releaseConfig) {
78
79
  const fileMode = releaseConfig?.release?.mode;
80
+ const text = releaseText();
79
81
  if (fileMode) {
80
- return { config: releaseConfig, source: 'config', reason: `模式 ${fileMode} 來自 .standards/release-config.yaml。` };
82
+ return { config: releaseConfig, source: 'config', reason: text.modeFromConfig(fileMode) };
81
83
  }
82
- const fileMissing = releaseConfig === null
83
- ? '找不到 .standards/release-config.yaml(或它無法解析)'
84
- : '.standards/release-config.yaml 沒有指定 release.mode';
84
+ const fileMissing = releaseConfig === null ? text.configMissing : text.configNoMode;
85
85
  const recorded = manifestReleaseMode(projectPath); // wire:release-mode-from-manifest
86
86
  if (recorded) {
87
87
  return {
88
88
  config: { ...(releaseConfig ?? {}), release: { ...(releaseConfig?.release ?? {}), mode: recorded } },
89
89
  source: 'manifest',
90
- reason: `${fileMissing};模式 ${recorded} 取自 .standards/manifest.json 的 options.release_mode。`
90
+ reason: text.modeFromManifest(fileMissing, recorded)
91
91
  };
92
92
  }
93
93
  return {
94
94
  config: releaseConfig,
95
95
  source: 'default',
96
- reason: `${fileMissing},.standards/manifest.json 也沒有記錄 options.release_mode,所以使用預設的 ci-cd。`
96
+ reason: text.modeDefault(fileMissing)
97
97
  };
98
98
  }
99
99
 
@@ -201,9 +201,9 @@ export async function releaseCommand(subcommand, args, options) {
201
201
  switch (subcommand) {
202
202
  case 'promote':
203
203
  if (!workflow.hasPromote) {
204
- console.log(chalk.red('promote 子命令僅在 manual 或 hybrid 模式下可用。'));
205
- console.log(chalk.gray(' 目前模式: ' + workflow.type));
206
- console.log(chalk.gray(' 使用 `uds config --type release_mode` 切換模式'));
204
+ console.log(chalk.red(releaseText().promoteOnly));
205
+ console.log(chalk.gray(releaseText().currentMode(workflow.type)));
206
+ console.log(chalk.gray(releaseText().switchMode));
207
207
  explainMode();
208
208
  return;
209
209
  }
@@ -212,8 +212,8 @@ export async function releaseCommand(subcommand, args, options) {
212
212
 
213
213
  case 'deploy':
214
214
  if (!workflow.hasDeploy) {
215
- console.log(chalk.red('deploy 子命令僅在 manual 或 hybrid 模式下可用。'));
216
- console.log(chalk.gray(' 目前模式: ' + workflow.type));
215
+ console.log(chalk.red(releaseText().deployOnly));
216
+ console.log(chalk.gray(releaseText().currentMode(workflow.type)));
217
217
  explainMode();
218
218
  return;
219
219
  }
@@ -222,7 +222,7 @@ export async function releaseCommand(subcommand, args, options) {
222
222
 
223
223
  case 'manifest':
224
224
  if (!workflow.hasManifest) {
225
- console.log(chalk.red('manifest 子命令僅在 manual 或 hybrid 模式下可用。'));
225
+ console.log(chalk.red(releaseText().manifestOnly));
226
226
  explainMode();
227
227
  return;
228
228
  }
@@ -231,7 +231,7 @@ export async function releaseCommand(subcommand, args, options) {
231
231
 
232
232
  case 'verify':
233
233
  if (!workflow.hasManifest) {
234
- console.log(chalk.red('verify 子命令僅在 manual 或 hybrid 模式下可用。'));
234
+ console.log(chalk.red(releaseText().verifyOnly));
235
235
  explainMode();
236
236
  process.exitCode = EXIT_CANNOT_VERIFY; // nothing was verified; 0 would read as "verified"
237
237
  return;
@@ -255,22 +255,22 @@ export async function releaseCommand(subcommand, args, options) {
255
255
  async function handlePromote(targetVersion, projectPath) {
256
256
 
257
257
  if (!targetVersion) {
258
- console.log(chalk.red('請指定目標 stable 版本號。'));
259
- console.log(chalk.gray(' 用法: uds release promote 1.2.0'));
258
+ console.log(chalk.red(releaseText().promoteNeedVersion));
259
+ console.log(chalk.gray(releaseText().promoteUsage));
260
260
  return;
261
261
  }
262
262
 
263
263
  // Verify this is a valid stable version (no pre-release suffix)
264
264
  if (targetVersion.includes('-')) {
265
- console.log(chalk.red('目標版本不應包含 pre-release 後綴。'));
266
- console.log(chalk.gray(` 請使用: uds release promote ${targetVersion.split('-')[0]}`));
265
+ console.log(chalk.red(releaseText().noPrerelease));
266
+ console.log(chalk.gray(releaseText().useInstead(targetVersion.split('-')[0])));
267
267
  return;
268
268
  }
269
269
 
270
270
  // Validate stable semver format (catches typos like 1.a.0, 1.2, abc)
271
271
  if (!isStableVersion(targetVersion)) {
272
- console.log(chalk.red(`版本格式無效: ${targetVersion}`));
273
- console.log(chalk.gray(' 需為 stable semver(X.Y.Z),例如: uds release promote 1.2.0'));
272
+ console.log(chalk.red(releaseText().badVersion(targetVersion)));
273
+ console.log(chalk.gray(releaseText().needStable));
274
274
  return;
275
275
  }
276
276
 
@@ -279,26 +279,26 @@ async function handlePromote(targetVersion, projectPath) {
279
279
  const parsed = currentVersion ? parseRCVersion(currentVersion) : null;
280
280
 
281
281
  console.log();
282
- console.log(chalk.bold('Release Promote: RC → Stable'));
282
+ console.log(chalk.bold(releaseText().promoteTitle));
283
283
  console.log(chalk.gray('─'.repeat(40)));
284
284
 
285
285
  if (parsed) {
286
- console.log(chalk.gray(` 目前版本: ${currentVersion}`));
287
- console.log(chalk.gray(` 晉升目標: ${targetVersion}`));
286
+ console.log(chalk.gray(releaseText().currentVersion(currentVersion)));
287
+ console.log(chalk.gray(releaseText().promoteTarget(targetVersion)));
288
288
  } else {
289
- console.log(chalk.gray(` 晉升目標: ${targetVersion}`));
289
+ console.log(chalk.gray(releaseText().promoteTarget(targetVersion)));
290
290
  }
291
291
 
292
292
  // This command only prints. It writes no promotion record and creates no git tag, so it must not say it did.
293
293
  const tag = formatGitTag(targetVersion);
294
294
  console.log();
295
- console.log(chalk.yellow('這個指令不會建立晉升紀錄,也不會建立 Git tag;它只列出下一步要執行的事。'));
295
+ console.log(chalk.yellow(releaseText().promotePrintsOnly));
296
296
  console.log();
297
- console.log(chalk.cyan('下一步(由你執行):'));
298
- console.log(chalk.gray(` 1. 更新版本檔案為 ${targetVersion}`));
299
- console.log(chalk.gray(` 2. git tag ${tag}`));
300
- console.log(chalk.gray(' 3. 從此 commit 重新打包'));
301
- console.log(chalk.gray(' 4. 執行 uds release deploy production 記錄部署'));
297
+ console.log(chalk.cyan(releaseText().nextStepsHeader));
298
+ console.log(chalk.gray(releaseText().step1(targetVersion)));
299
+ console.log(chalk.gray(releaseText().step2(tag)));
300
+ console.log(chalk.gray(releaseText().step3));
301
+ console.log(chalk.gray(releaseText().step4));
302
302
  }
303
303
 
304
304
  /**
@@ -307,10 +307,10 @@ async function handlePromote(targetVersion, projectPath) {
307
307
  async function handleDeploy(environment, options, projectPath) {
308
308
 
309
309
  if (!environment) {
310
- console.log(chalk.red('請指定部署環境。'));
311
- console.log(chalk.gray(' 用法: uds release deploy staging'));
312
- console.log(chalk.gray(' 用法: uds release deploy staging --result passed'));
313
- console.log(chalk.gray(' 用法: uds release deploy production'));
310
+ console.log(chalk.red(releaseText().deployNeedEnv));
311
+ console.log(chalk.gray(releaseText().deployUsage1));
312
+ console.log(chalk.gray(releaseText().deployUsage2));
313
+ console.log(chalk.gray(releaseText().deployUsage3));
314
314
  return;
315
315
  }
316
316
 
@@ -318,9 +318,9 @@ async function handleDeploy(environment, options, projectPath) {
318
318
  const deployConfig = loadReleaseConfig(projectPath);
319
319
  const allowedEnvironments = configuredEnvironmentNames(deployConfig) || DEFAULT_ENVIRONMENTS;
320
320
  if (!allowedEnvironments.includes(environment)) {
321
- console.log(chalk.red(`未知的部署環境: ${environment}`));
322
- console.log(chalk.gray(` 允許的環境: ${allowedEnvironments.join(', ')}`));
323
- console.log(chalk.gray(' 自訂環境請在 .standards/release-config.yaml 設定 release.environments'));
321
+ console.log(chalk.red(releaseText().unknownEnv(environment)));
322
+ console.log(chalk.gray(releaseText().allowedEnvs(allowedEnvironments.join(', '))));
323
+ console.log(chalk.gray(releaseText().customEnvHint));
324
324
  return;
325
325
  }
326
326
 
@@ -335,11 +335,11 @@ async function handleDeploy(environment, options, projectPath) {
335
335
  result: options.result,
336
336
  });
337
337
  if (updatedCount === 0) {
338
- console.log(chalk.yellow(`⚠ 找不到 ${currentVersion} 在 ${environment} 的部署紀錄`));
338
+ console.log(chalk.yellow(releaseText().noDeployRecord(currentVersion, environment)));
339
339
  return;
340
340
  }
341
341
  saveDeployments(projectPath, updated);
342
- console.log(chalk.green(`✓ 已更新 ${currentVersion} 在 ${environment} 的結果: ${options.result}`));
342
+ console.log(chalk.green(releaseText().resultUpdated(currentVersion, environment, options.result)));
343
343
  return;
344
344
  }
345
345
 
@@ -351,7 +351,7 @@ async function handleDeploy(environment, options, projectPath) {
351
351
  });
352
352
  if (warnings.length > 0) {
353
353
  console.log();
354
- console.log(chalk.yellow('⚠ 警告:'));
354
+ console.log(chalk.yellow(releaseText().warningHeader));
355
355
  for (const w of warnings) {
356
356
  console.log(chalk.yellow(` - ${w}`));
357
357
  }
@@ -369,14 +369,14 @@ async function handleDeploy(environment, options, projectPath) {
369
369
  deployments.push(record);
370
370
  saveDeployments(projectPath, deployments);
371
371
 
372
- console.log(chalk.green(`✓ 已記錄部署: ${currentVersion} → ${environment}`));
373
- console.log(chalk.gray(` 部署者: ${record.deployer}`));
374
- console.log(chalk.gray(` 時間: ${record.date}`));
372
+ console.log(chalk.green(releaseText().deployRecorded(currentVersion, environment)));
373
+ console.log(chalk.gray(releaseText().deployer(record.deployer)));
374
+ console.log(chalk.gray(releaseText().time(record.date)));
375
375
 
376
376
  if (environment === 'staging') {
377
377
  console.log();
378
- console.log(chalk.cyan('後續步驟:'));
379
- console.log(chalk.gray(' 測試完成後執行:'));
378
+ console.log(chalk.cyan(releaseText().followUp));
379
+ console.log(chalk.gray(releaseText().afterTesting));
380
380
  console.log(chalk.gray(' uds release deploy staging --result passed'));
381
381
  }
382
382
  }
@@ -401,12 +401,12 @@ async function handleManifest(versionArg, options, projectPath) {
401
401
  const manifestPath = join(projectPath, 'build-manifest.json');
402
402
  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
403
403
 
404
- console.log(chalk.green('✓ build-manifest.json 已產生'));
405
- console.log(chalk.gray(` 版本: ${manifest.version}`));
406
- console.log(chalk.gray(` Commit: ${manifest.commit}`));
407
- console.log(chalk.gray(` 分支: ${manifest.branch}`));
408
- console.log(chalk.gray(` 建置者: ${manifest.builder}`));
409
- console.log(chalk.gray(` 時間: ${manifest.build_date}`));
404
+ console.log(chalk.green(releaseText().manifestWritten));
405
+ console.log(chalk.gray(releaseText().mVersion(manifest.version)));
406
+ console.log(chalk.gray(releaseText().mCommit(manifest.commit)));
407
+ console.log(chalk.gray(releaseText().mBranch(manifest.branch)));
408
+ console.log(chalk.gray(releaseText().mBuilder(manifest.builder)));
409
+ console.log(chalk.gray(releaseText().mTime(manifest.build_date)));
410
410
  }
411
411
 
412
412
  /**
@@ -421,8 +421,8 @@ async function handleVerify(projectPath, options = {}) {
421
421
  const manifestPath = join(projectPath, 'build-manifest.json');
422
422
 
423
423
  if (!existsSync(manifestPath)) {
424
- console.log(chalk.red('找不到 build-manifest.json'));
425
- console.log(chalk.gray(' 請先執行 uds release manifest'));
424
+ console.log(chalk.red(releaseText().noManifest));
425
+ console.log(chalk.gray(releaseText().runManifestFirst));
426
426
  return EXIT_CANNOT_VERIFY;
427
427
  }
428
428
 
@@ -430,7 +430,7 @@ async function handleVerify(projectPath, options = {}) {
430
430
  try {
431
431
  manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
432
432
  } catch {
433
- console.log(chalk.red('build-manifest.json 格式不正確'));
433
+ console.log(chalk.red(releaseText().badManifest));
434
434
  return EXIT_CANNOT_VERIFY;
435
435
  }
436
436
  const currentCommit = getGitCommit();
@@ -440,7 +440,7 @@ async function handleVerify(projectPath, options = {}) {
440
440
  const artifactPath = options.artifact || null;
441
441
  if (artifactPath) {
442
442
  if (!existsSync(artifactPath)) {
443
- console.log(chalk.red(`找不到 artifact:${artifactPath}`));
443
+ console.log(chalk.red(releaseText().noArtifact(artifactPath)));
444
444
  return EXIT_CANNOT_VERIFY;
445
445
  }
446
446
  actualChecksum = createHash('sha256').update(readFileSync(artifactPath)).digest('hex');
@@ -449,14 +449,14 @@ async function handleVerify(projectPath, options = {}) {
449
449
  const result = verifyManifest(manifest, currentCommit, { actualChecksum });
450
450
 
451
451
  if (result.valid) {
452
- console.log(chalk.green('✓ Manifest 驗證通過'));
453
- console.log(chalk.gray(` 版本: ${manifest.version}`));
454
- console.log(chalk.gray(` Commit: ${manifest.commit} (一致)`));
452
+ console.log(chalk.green(releaseText().verifyPassed));
453
+ console.log(chalk.gray(releaseText().mVersion(manifest.version)));
454
+ console.log(chalk.gray(releaseText().commitSame(manifest.commit)));
455
455
  if (actualChecksum && manifest.checksum?.package) {
456
- console.log(chalk.gray(` Checksum: ${actualChecksum} (一致)`));
456
+ console.log(chalk.gray(releaseText().checksumSame(actualChecksum)));
457
457
  }
458
458
  } else {
459
- console.log(chalk.red('✗ Manifest 驗證失敗'));
459
+ console.log(chalk.red(releaseText().verifyFailed));
460
460
  for (const err of result.errors) {
461
461
  console.log(chalk.red(` - ${err}`));
462
462
  }
@@ -473,9 +473,9 @@ async function handleVerify(projectPath, options = {}) {
473
473
  );
474
474
 
475
475
  if (stagingPassed) {
476
- console.log(chalk.green(' Staging: 已通過 ✓'));
476
+ console.log(chalk.green(releaseText().stagingPassed));
477
477
  } else {
478
- console.log(chalk.yellow(' Staging: 未通過或無紀錄'));
478
+ console.log(chalk.yellow(releaseText().stagingNone));
479
479
  }
480
480
 
481
481
  return result.valid ? 0 : EXIT_VERIFY_FAILED;
@@ -486,21 +486,21 @@ async function handleVerify(projectPath, options = {}) {
486
486
  */
487
487
  function showReleaseHelp(workflow) {
488
488
  console.log();
489
- console.log(chalk.bold('uds release — 版本發布管理'));
489
+ console.log(chalk.bold(releaseText().helpTitle));
490
490
  console.log(chalk.gray('─'.repeat(40)));
491
- console.log(chalk.gray(` 目前模式: ${workflow.type}`));
491
+ console.log(chalk.gray(releaseText().currentMode(workflow.type)));
492
492
  console.log();
493
493
 
494
494
  if (workflow.hasPromote) {
495
- console.log(chalk.cyan(' 可用子命令:'));
496
- console.log(chalk.gray(' promote <version> RC → Stable 晉升'));
497
- console.log(chalk.gray(' deploy <env> 記錄部署紀錄'));
498
- console.log(chalk.gray(' deploy <env> --result 更新測試結果'));
499
- console.log(chalk.gray(' manifest 產生 build-manifest.json'));
500
- console.log(chalk.gray(' verify [--artifact <path>] 驗證 manifest 一致性(含 checksum 比對)'));
495
+ console.log(chalk.cyan(releaseText().subcommands));
496
+ console.log(chalk.gray(releaseText().helpPromote));
497
+ console.log(chalk.gray(releaseText().helpDeploy));
498
+ console.log(chalk.gray(releaseText().helpDeployResult));
499
+ console.log(chalk.gray(releaseText().helpManifest));
500
+ console.log(chalk.gray(releaseText().helpVerify));
501
501
  } else {
502
- console.log(chalk.gray(' CI/CD 模式下,請使用 /release start 和 /release finish'));
503
- console.log(chalk.gray(' 切換到手動模式: uds config --type release_mode'));
502
+ console.log(chalk.gray(releaseText().helpCiCd));
503
+ console.log(chalk.gray(releaseText().helpSwitch));
504
504
  }
505
505
  console.log();
506
506
  }
@@ -146,7 +146,9 @@ export async function specListCommand(options = {}) {
146
146
  // default (XSPEC-456 R5): an SDD spec whose header could not be read used to be listed as `draft`.
147
147
  const unparsed = t('spec.statusUnparsed', 'format: SDD (status not parsed)');
148
148
  const statusLabel = (spec) => spec.status ?? unparsed;
149
- const statusWidth = Math.max(12, ...specs.map((spec) => statusLabel(spec).length + 1));
149
+ // XSPEC-475 R8: the width follows the statuses that were READ. The "not parsed" sentence is longer than any status, and it
150
+ // used to stretch the whole column (and the rule under it) for every row because of one spec whose header could not be read.
151
+ const statusWidth = Math.max(12, ...specs.filter((spec) => spec.status).map((spec) => spec.status.length + 1)); // [mutation-anchor:status-width]
150
152
  const ruleWidth = 70 + (statusWidth - 12);
151
153
 
152
154
  console.log(chalk.gray('─'.repeat(ruleWidth)));
@@ -169,7 +171,7 @@ export async function specListCommand(options = {}) {
169
171
 
170
172
  console.log(
171
173
  spec.id.slice(0, 34).padEnd(35) +
172
- statusColor(statusLabel(spec).padEnd(statusWidth)) +
174
+ statusColor(statusLabel(spec).padEnd(Math.max(statusWidth, statusLabel(spec).length + 1))) +
173
175
  (spec.type ?? '-').padEnd(10) +
174
176
  spec.title.slice(0, 25)
175
177
  );
@@ -60,7 +60,7 @@ import { detectAITools } from '../utils/detector.js';
60
60
  import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks } from '../installers/hooks-installer.js';
61
61
  import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
62
62
  import { installGateScripts, gateStandardInstalled, GATE_SCRIPTS } from '../utils/gate-scripts.js';
63
- import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
63
+ import { migrateLegacyHuskyHook, migrateHuskyBlockWithoutCi, migrateOlderNativeHook } from '../utils/legacy-hook-migration.js';
64
64
  import {
65
65
  promptSkillsInstallLocation,
66
66
  promptCommandsInstallation
@@ -76,6 +76,7 @@ import {
76
76
  cleanupBackups
77
77
  } from '../reconciler/index.js';
78
78
  import { stepWritePaths } from '../reconciler/install-roots.js';
79
+ import { alignRecordedVersions, alignUpstreamVersion } from '../reconciler/recorded-versions.js';
79
80
  import { restoreSingleFile } from './check.js';
80
81
  import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
81
82
  import { resolveIntegrationFile, SUPPORTED_AI_TOOLS, getToolFormat } from '../core/constants.js';
@@ -513,6 +514,11 @@ export async function updateCommand(options) {
513
514
  migrateLegacyPreCommitHook(projectPath, manifest, { plan: !!options.plan });
514
515
  }
515
516
 
517
+ if (options.from && !options.rollback) {
518
+ console.log(chalk.yellow(' ! --from names the backup for --rollback; without --rollback it does nothing and is ignored.'));
519
+ console.log();
520
+ }
521
+
516
522
  // Handle --rollback option (DSR). It restores a whole backup, so a scope
517
523
  // flag cannot narrow it — say so rather than appearing to honour it.
518
524
  if (options.rollback) {
@@ -520,7 +526,7 @@ export async function updateCommand(options) {
520
526
  console.log(chalk.yellow(' ! --rollback restores a complete backup; --skills/--commands cannot narrow it and are ignored.'));
521
527
  console.log();
522
528
  }
523
- await handleRollback(projectPath);
529
+ await handleRollback(projectPath, options);
524
530
  return;
525
531
  }
526
532
 
@@ -1940,7 +1946,6 @@ export function migrateLegacyPreCommitHook(projectPath, manifest, { plan = false
1940
1946
  if (r.state === 'error') {
1941
1947
  console.log(chalk.yellow(` ${msg.hookMigrateFailed.replace('{error}', r.error)}`));
1942
1948
  console.log();
1943
- return r;
1944
1949
  }
1945
1950
  if (r.state === 'migrated') console.log(chalk.green(` ${msg.hookMigrated}`));
1946
1951
  if (r.state === 'would-migrate') console.log(chalk.cyan(` ${msg.hookWouldMigrate}`));
@@ -1954,6 +1959,30 @@ export function migrateLegacyPreCommitHook(projectPath, manifest, { plan = false
1954
1959
  // this the record persisted just above would be overwritten by the older copy.
1955
1960
  Object.assign(manifest, mergeRecorderInto(manifest, r.recorder));
1956
1961
  }
1962
+
1963
+ // XSPEC-482 R3 + R5: hooks that run the check and cannot stop a commit - the husky block that runs `check`
1964
+ // without `--ci`, and the native hook of 5.x .. 6.13.1 / the betas. Same treatment as above: only a text UDS
1965
+ // provably wrote is replaced, anything else is named and left alone, and --plan lists it.
1966
+ const huskyCi = migrateHuskyBlockWithoutCi(projectPath, { plan, manifest });
1967
+ if (huskyCi.state === 'error') console.log(chalk.yellow(` ${msg.hookMigrateFailed.replace('{error}', huskyCi.error)}`));
1968
+ if (huskyCi.state === 'migrated') console.log(chalk.green(` ${msg.hookHuskyCiMigrated}`)); // wire:update-migrates-husky-ci
1969
+ if (huskyCi.state === 'would-migrate') console.log(chalk.cyan(` ${msg.hookHuskyCiWouldMigrate}`));
1970
+
1971
+ const native = migrateOlderNativeHook(projectPath, { plan }); // wire:update-migrates-native-hook
1972
+ const nativeFrom = native.from === 'legacy-6.11' ? msg.hookNativeFromLegacy : msg.hookNativeFromWithoutCi;
1973
+ if (native.state === 'error') console.log(chalk.yellow(` ${msg.hookNativeFailed.replace('{error}', native.error)}`));
1974
+ if (native.state === 'migrated') console.log(chalk.green(` ${msg.hookNativeMigrated.replace('{from}', nativeFrom)}`));
1975
+ if (native.state === 'would-migrate') console.log(chalk.cyan(` ${msg.hookNativeWouldMigrate.replace('{from}', nativeFrom)}`));
1976
+ for (const k of native.kept) {
1977
+ console.log(chalk.yellow(` ${msg.hookNativeKept.replace('{line}', k.line).replace('{text}', k.text)}`));
1978
+ }
1979
+ if (huskyCi.state !== 'none' || native.state !== 'none') console.log();
1980
+ for (const extra of [huskyCi.recorder, native.recorder]) {
1981
+ if (extra) {
1982
+ persistRecorder(projectPath, extra);
1983
+ Object.assign(manifest, mergeRecorderInto(manifest, extra));
1984
+ }
1985
+ }
1957
1986
  return r;
1958
1987
  }
1959
1988
 
@@ -2724,13 +2753,21 @@ async function planSkills(projectPath, manifest, options) {
2724
2753
  return;
2725
2754
  }
2726
2755
 
2756
+ // XSPEC-482 R7: "unchanged" needs the files to agree too, as `uds update --plan` judges them - a recorded version
2757
+ // equal to the shipped one says nothing about a skill file that was deleted or edited.
2758
+ const skillActions = await skillActionsOf(projectPath);
2759
+
2727
2760
  let changed = 0;
2728
2761
  for (const inst of installations) {
2729
2762
  const info = getInstalledSkillsInfoForAgent(inst.agent, inst.level, projectPath);
2730
2763
  const current = info?.version || 'unknown';
2731
2764
  const dir = getSkillsDirForAgent(inst.agent, inst.level, projectPath);
2732
- if (current === latestVersion) {
2765
+ const differing = skillActions.filter((a) => a.details?.metadata?.agent === inst.agent && (a.details?.metadata?.level || 'project') === inst.level);
2766
+ if (current === latestVersion && differing.length === 0) {
2733
2767
  console.log(chalk.gray(` = ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} — unchanged`));
2768
+ } else if (current === latestVersion) {
2769
+ changed++;
2770
+ console.log(chalk.yellow(` ~ ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} — ${differing.length} skill file(s) differ from what this UDS ships ${dir}`));
2734
2771
  } else {
2735
2772
  changed++;
2736
2773
  console.log(chalk.yellow(` ~ ${getAgentDisplayName(inst.agent)} (${inst.level}): v${current} → v${latestVersion} ${dir}`));
@@ -2759,21 +2796,44 @@ async function planCommands(projectPath, manifest, options) {
2759
2796
  return;
2760
2797
  }
2761
2798
 
2799
+ // XSPEC-482 R7: ask the reconciler, the same question `uds update --plan` answers, instead of saying "would be
2800
+ // reinstalled" for every installation whatever is on disk. A project that is current used to get "51 command(s)
2801
+ // would be reinstalled" here, "unchanged" from `--plan --skills` and "No changes" from `--plan`.
2802
+ const actions = await commandActionsOf(projectPath);
2803
+
2804
+ let changed = 0;
2762
2805
  for (const inst of installations) {
2763
2806
  const agent = typeof inst === 'string' ? inst : inst.agent;
2764
2807
  const level = typeof inst === 'string' ? 'project' : (inst.level || 'project');
2765
2808
  const info = getInstalledCommandsForAgent(agent, level, projectPath);
2766
2809
  const dir = getCommandsDirForAgent(agent, level, projectPath);
2767
- console.log(chalk.yellow(` ~ ${getAgentDisplayName(agent)} (${level}): ${info?.count || 0} command(s) would be reinstalled ${dir}`));
2810
+ const differing = actions.filter((a) => a.details?.metadata?.agent === agent && (a.details?.metadata?.level || 'project') === level);
2811
+ if (differing.length === 0) {
2812
+ console.log(chalk.gray(` = ${getAgentDisplayName(agent)} (${level}): ${info?.count || 0} command(s) — unchanged`));
2813
+ } else {
2814
+ changed++;
2815
+ console.log(chalk.yellow(` ~ ${getAgentDisplayName(agent)} (${level}): ${differing.length} command file(s) would be written or removed ${dir}`)); // wire:plan-commands-asks-reconciler
2816
+ }
2768
2817
  }
2769
2818
 
2770
2819
  console.log();
2771
- console.log(`Summary: ${installations.length} installation(s) would be reinstalled.`);
2820
+ console.log(`Summary: ${changed} installation(s) would be reinstalled, ${installations.length - changed} unchanged.`);
2772
2821
  console.log(chalk.gray(` Locale that would be used: ${resolveLocale(manifest, projectPath, options)}`));
2773
- console.log(chalk.gray(' Run `uds update --apply --yes --commands` to apply.'));
2822
+ if (changed > 0) console.log(chalk.gray(' Run `uds update --apply --yes --commands` to apply.'));
2774
2823
  console.log();
2775
2824
  }
2776
2825
 
2826
+ /** The reconciler's plan actions for skill and command files (what `uds update --plan` would list). */
2827
+ async function commandActionsOf(projectPath) {
2828
+ const { plan } = await reconcilerPlan(projectPath, {});
2829
+ return plan.actions.filter((a) => a.category === 'command');
2830
+ }
2831
+
2832
+ async function skillActionsOf(projectPath) {
2833
+ const { plan } = await reconcilerPlan(projectPath, {});
2834
+ return plan.actions.filter((a) => a.category === 'skill');
2835
+ }
2836
+
2777
2837
  async function updateSkillsOnly(projectPath, manifest, options) {
2778
2838
  const msg = t().commands.update;
2779
2839
  const repoInfo = getRepositoryInfo();
@@ -3576,20 +3636,37 @@ function printPaths(prefix, paths, limit, colour) {
3576
3636
  * updates, then say, item by item, what was restored, what was removed, and what was NOT put back.
3577
3637
  * It never ends in "successful" while any of those lists is not empty (XSPEC-454 R1).
3578
3638
  */
3579
- async function handleRollback(projectPath) {
3639
+ async function handleRollback(projectPath, options = {}) {
3580
3640
  const backups = listBackups(projectPath);
3581
3641
  if (backups.length === 0) {
3582
3642
  console.log(chalk.yellow('No backups found. Nothing to rollback.'));
3583
3643
  console.log();
3644
+ if (options.from) process.exitCode = 1;
3584
3645
  return;
3585
3646
  }
3586
3647
 
3587
- const latest = backups[0];
3648
+ // XSPEC-482 R11: `--from` names the one backup to restore. The default picks the newest series, and a backup an older
3649
+ // UDS made is never in it (it records no manifest hash to chain on), so without this there was no way to reach it.
3650
+ let chosen = null;
3651
+ if (options.from) {
3652
+ const wanted = String(options.from).replace(/\\/g, '/').replace(/\/+$/, '');
3653
+ const leaf = (id) => id.slice(id.lastIndexOf('/') + 1);
3654
+ chosen = backups.find((b) => b.backupId === wanted) || backups.find((b) => leaf(b.backupId) === leaf(wanted));
3655
+ if (!chosen) {
3656
+ console.log(chalk.red(`No backup named "${options.from}". Backups in this project:`));
3657
+ for (const b of backups) console.log(chalk.gray(` ${b.backupId} (${b.createdAt || 'no date'})`));
3658
+ console.log();
3659
+ process.exitCode = 1;
3660
+ return;
3661
+ }
3662
+ }
3663
+
3664
+ const latest = chosen || backups[0];
3588
3665
  console.log(chalk.cyan(`Rolling back from: ${latest.backupId}`));
3589
3666
  console.log(chalk.gray(` Created: ${latest.createdAt}`));
3590
3667
  console.log();
3591
3668
 
3592
- const result = rollbackLast(projectPath);
3669
+ const result = rollbackLast(projectPath, chosen ? chosen.backupId : undefined);
3593
3670
 
3594
3671
  for (const step of result.steps || []) {
3595
3672
  console.log(chalk.cyan(`${step.backupId}${step.label ? ` (${step.label})` : ''}`));
@@ -3607,7 +3684,16 @@ async function handleRollback(projectPath) {
3607
3684
  console.log(chalk.gray(` ${result.steps.length} consecutive updates were undone together (each one started from where the previous one ended).`));
3608
3685
  }
3609
3686
  if (result.olderBackups > 0) {
3610
- console.log(chalk.gray(` ${result.olderBackups} older backup(s) are not part of that series (something else changed the project in between) and were left alone.`));
3687
+ // Say the true reason. A backup an older UDS made records no manifest hash, so there is nothing to tell whether it
3688
+ // continues the series; one that does carry the hash and still does not match means something else changed the project.
3689
+ const inSeries = (result.steps || []).length;
3690
+ const next = backups[inSeries];
3691
+ const why = next && !next.postManifestHash
3692
+ ? 'it was made by an older UDS, which did not record what links one backup to the next, so it cannot be joined to the series'
3693
+ : 'something else changed the project after it was made';
3694
+ console.log(chalk.gray(` ${result.olderBackups} older backup(s) are not part of that series (${why}) and were left alone.`));
3695
+ console.log(chalk.gray(' To restore one of them on its own: `uds update --rollback --from <backup>`. They are:'));
3696
+ for (const b of backups.slice(inSeries)) console.log(chalk.gray(` ${b.backupId} (${b.createdAt || 'no date'})`)); // wire:rollback-names-older-backups
3611
3697
  }
3612
3698
 
3613
3699
  if (result.errors.length > 0) {
@@ -3702,7 +3788,11 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3702
3788
  // XSPEC-454 R2: nothing to apply, but the manifest may still list skill files UDS never installed
3703
3789
  // (they only ever get corrected by a write, and an up-to-date project has none coming).
3704
3790
  const current = readManifest(projectPath);
3705
- if (current && (pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0) writeManifest(current, projectPath);
3791
+ // XSPEC-475 R6: nothing to apply means the files are what this UDS ships; the recorded versions say so too.
3792
+ let aligned = current ? alignRecordedVersions(current).changed : false; // wire:up-to-date-aligns-versions
3793
+ // XSPEC-482 R6: the same for the standards version, which only an executed plan used to record.
3794
+ if (current && alignUpstreamVersion(current).changed) aligned = true; // wire:up-to-date-aligns-upstream
3795
+ if (current && ((pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0 || aligned)) writeManifest(current, projectPath);
3706
3796
  console.log(chalk.green('Everything is up to date. No changes needed.'));
3707
3797
  // XSPEC-458 R2: "up to date" is about the files UDS manages; say what UDS ships that is not managed here.
3708
3798
  printAvailableStandardsSection(planResult.manifest, { phase: 'apply' });
@@ -3757,6 +3847,18 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3757
3847
  }
3758
3848
  }
3759
3849
 
3850
+ if (!result.success) {
3851
+ // XSPEC-482 R10: say what a partly failed run left behind and the way to finish it.
3852
+ console.log();
3853
+ console.log(chalk.yellow(
3854
+ 'Not everything was applied. The overall version record did not advance, and a skills or commands batch that failed keeps its ' +
3855
+ 'old version record; a batch that succeeded has already recorded its new version. ' +
3856
+ 'Fix the cause, then run `uds update --apply` again: it completes what is left.'
3857
+ ));
3858
+ // XSPEC-482 R2: a failed action is a failed run. CI and scripts read the exit code, not the colour of a line.
3859
+ process.exitCode = 1; // wire:apply-fails-exit-1
3860
+ }
3861
+
3760
3862
  // XSPEC-458 R2: the count of what UDS ships and this project lacks, with the command that installs one.
3761
3863
  printAvailableStandardsSection(result.manifest || planResult.manifest, { phase: 'apply' });
3762
3864
  console.log();
@@ -8,6 +8,7 @@
8
8
  */
9
9
 
10
10
  import { BaseCompiler } from './base-compiler.js';
11
+ import { normalizeMatcher } from '../installers/hooks-installer.js';
11
12
 
12
13
  const DEFAULT_MATCHERS = {
13
14
  UserPromptSubmit: '',
@@ -27,7 +28,14 @@ export class ClaudeCodeCompiler extends BaseCompiler {
27
28
 
28
29
  for (const std of enforceable) {
29
30
  const { hook_script, trigger } = std.enforcement;
30
- const matcher = std.enforcement.matcher ?? DEFAULT_MATCHERS[trigger] ?? '';
31
+ // Claude Code's matcher is a string (https://code.claude.com/docs/en/hooks, "Matcher patterns"). A standard may
32
+ // declare it as an object (`matcher: { tool: Write, path: "src/**/*.ts" }`); that used to be written to
33
+ // settings.json as the object, which the documented format has no place for (XSPEC-482 R4). Same reduction
34
+ // `uds init --with-hooks` and `uds update --with-hooks` apply, so the three write one format.
35
+ const declared = std.enforcement.matcher;
36
+ const matcher = declared === undefined || declared === null
37
+ ? (DEFAULT_MATCHERS[trigger] ?? '')
38
+ : normalizeMatcher(declared); // wire:compile-matcher-is-a-string
31
39
 
32
40
  if (!hooks[trigger]) {
33
41
  hooks[trigger] = [];