universal-dev-standards 6.14.0-beta.4 → 6.14.0-beta.6

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 (56) hide show
  1. package/bin/uds.js +9 -2
  2. package/bundled/ai/standards/commit-message.ai.yaml +6 -2
  3. package/bundled/ai/standards/full-coverage-testing.ai.yaml +46 -5
  4. package/bundled/core/full-coverage-testing.md +57 -3
  5. package/bundled/locales/zh-CN/CHANGELOG.md +54 -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/core/full-coverage-testing.md +61 -7
  9. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +4 -2
  10. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +10 -6
  11. package/bundled/locales/zh-TW/CHANGELOG.md +54 -3
  12. package/bundled/locales/zh-TW/README.md +1 -1
  13. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  14. package/bundled/locales/zh-TW/core/full-coverage-testing.md +61 -7
  15. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +4 -2
  16. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +10 -6
  17. package/bundled/templates/gates/check-anti-fake-tests.mjs +991 -0
  18. package/bundled/templates/gates/check-stubs.mjs +644 -0
  19. package/package.json +2 -2
  20. package/src/commands/audit.js +11 -0
  21. package/src/commands/check.js +124 -24
  22. package/src/commands/deps.js +31 -1
  23. package/src/commands/init.js +16 -0
  24. package/src/commands/simulate.js +20 -8
  25. package/src/commands/skills.js +42 -2
  26. package/src/commands/spec.js +14 -8
  27. package/src/commands/update.js +222 -21
  28. package/src/core/install-records.js +2 -1
  29. package/src/core/manifest.js +12 -10
  30. package/src/core/marketplace-sentinel.js +5 -0
  31. package/src/core/project-config.js +58 -38
  32. package/src/i18n/messages.js +77 -9
  33. package/src/reconciler/backup-locations.js +75 -0
  34. package/src/reconciler/backup-manager.js +435 -115
  35. package/src/reconciler/index.js +44 -5
  36. package/src/reconciler/install-roots.js +90 -0
  37. package/src/reconciler/plan-executor.js +23 -2
  38. package/src/uninstallers/hook-uninstaller.js +2 -1
  39. package/src/utils/command-hash-ownership.js +103 -0
  40. package/src/utils/commit-message-judge.js +137 -0
  41. package/src/utils/copier.js +21 -1
  42. package/src/utils/deps-applicability.js +25 -0
  43. package/src/utils/gate-scripts.js +141 -0
  44. package/src/utils/health-scorer.js +10 -7
  45. package/src/utils/installed-names-ownership.js +114 -0
  46. package/src/utils/sdd-header.js +65 -0
  47. package/src/utils/skill-hash-ownership.js +64 -0
  48. package/src/utils/skills-installer.js +12 -1
  49. package/src/utils/standard-validator.js +98 -27
  50. package/src/utils/test-change-check.js +160 -0
  51. package/src/utils/test-policy.js +214 -0
  52. package/src/utils/update-summary.js +29 -0
  53. package/src/vibe/micro-spec.js +15 -0
  54. package/standards-registry.json +7 -7
  55. package/bundled/extensions/languages/php/fat-free-patterns.md +0 -915
  56. package/bundled/extensions/languages/php/php-style.md +0 -693
@@ -65,6 +65,7 @@ export const messages = {
65
65
  error: 'Failed to generate spec',
66
66
  listTitle: 'Micro-Specs',
67
67
  noSpecs: 'No micro-specs found.',
68
+ statusUnparsed: 'format: SDD (status not parsed)',
68
69
  createHint: 'Create one with: uds spec create "your intent"',
69
70
  total: 'Total',
70
71
  noId: 'Error: Please provide a spec ID.',
@@ -709,6 +710,12 @@ export const messages = {
709
710
  seeGuide: 'See: https://github.com/AsiaOstrich/universal-dev-standards/blob/main/adoption/ADOPTION-GUIDE.md'
710
711
  },
711
712
 
713
+ // deps command (XSPEC-456 R6)
714
+ deps: {
715
+ notApplicableNoPackageJson: 'Not applicable: there is no package.json, so nothing was checked',
716
+ notApplicableNoRuntimeDeps: 'Not applicable: this package declares no runtime dependencies, so nothing was checked'
717
+ },
718
+
712
719
  // skills command
713
720
  skills: {
714
721
  title: 'Universal Dev Standards - Installed Skills',
@@ -721,6 +728,7 @@ export const messages = {
721
728
  manualInstallDeprecated: '⚠ Manual installation is deprecated.',
722
729
  manualInstallHint: 'Consider migrating to Plugin Marketplace.',
723
730
  totalUniqueSkills: 'Total unique skills',
731
+ skillFilesTracked: '`uds check` tracks {files} skill files for these skills (it counts files across every tool, not skills).',
724
732
  recommendation: 'Recommendation: Migrate to Plugin Marketplace',
725
733
  benefits: 'Benefits: Automatic updates, better integration',
726
734
  migrateCommand: 'To migrate, run:'
@@ -781,9 +789,12 @@ export const messages = {
781
789
  // Diff display
782
790
  couldNotReadFile: 'Could not read current file.',
783
791
  couldNotDetermineSource2: 'Could not determine original source path.',
784
- fetchingOriginal: 'Fetching original from GitHub...',
785
- couldNotFetchOriginal: 'Could not fetch original content.',
786
- rateLimited: 'GitHub API rate limit exceeded. Please wait a few minutes and try again.',
792
+ // XSPEC-453 R1: the original is the copy inside the installed package; nothing is downloaded.
793
+ diffBaseline: 'Comparing against the original files in the installed UDS package (version {version}); no network is used. To see what UDS itself changed since, run `uds update --plan`.',
794
+ diffBaselineVersionDiffers: 'Note: these standards were installed from UDS {installed}, but the package now installed is {version}. A file UDS changed between the two shows up below as a difference even if you did not touch it; `uds update --plan` lists those.',
795
+ diffNone: 'No modified files, so there is nothing to diff.',
796
+ noOriginalInPackage: 'This version of the package has no original for {file} (expected {source} in UDS {version}), so it cannot be compared. Nothing was downloaded; reinstall or upgrade universal-dev-standards.',
797
+ couldNotReadOriginal: 'Could not read the packaged original of {file}.',
787
798
  diffOriginal: '--- Original',
788
799
  diffCurrent: '+++ Current',
789
800
  diffTruncated: '... (diff truncated, showing first 20 changes)',
@@ -862,6 +873,11 @@ export const messages = {
862
873
  // Final status
863
874
  projectCompliant: '✓ Project is compliant with standards',
864
875
  issuesDetected: '⚠ Some issues detected. Review above for details.',
876
+ skillsIntegrityFix: ' Skill files listed above are missing or were changed: run `uds update --apply --skills` to reinstall them.',
877
+ commandsIntegrityFix: ' Command files listed above are missing or were changed: run `uds update --apply --commands` to reinstall them.',
878
+ commandsStaleRecordsIgnored: ' {count} command record(s) ignored: they describe commands UDS does not ship.',
879
+ commandsElsewhereIgnored: ' {count} command record(s) ignored: those commands are installed at user level, shared by every project, so this project\'s check does not vouch for them.',
880
+ skillsStaleRecordsIgnored: ' {count} skill record(s) ignored: they describe files UDS did not install (e.g. your own skills, or folders an old UDS copied in and later removed).',
865
881
  // Installation prompts
866
882
  offerSkillsInstallation: 'Skills Installation',
867
883
  offerCommandsInstallation: 'Commands Installation',
@@ -920,6 +936,8 @@ export const messages = {
920
936
  userCommentsPrompt: 'Additional comments (optional):',
921
937
  reportTitle: 'UDS Audit Feedback',
922
938
  dryRunNotice: 'Dry run — no issue created',
939
+ offlineNoSubmit: 'Offline mode: the report is not submitted.',
940
+ offlineDryRunHint: ' Use --dry-run to preview it, or run again without --offline to submit.',
923
941
  ghNotFound: 'gh CLI not found, using browser deeplink',
924
942
  copiedToClipboard: 'Full report copied to clipboard',
925
943
  urlTruncated: 'Report too long for URL, summary used. Full report on clipboard.',
@@ -1059,6 +1077,9 @@ export const messages = {
1059
1077
  syncedIntegrations: 'Synced {count} integration files',
1060
1078
  prunedOrphanedBlockHashes: 'Pruned {count} orphaned integration hash(es): {files}',
1061
1079
  droppedRetiredHashes: 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:',
1080
+ droppedForeignSkillHashes: 'Dropped {count} skill record(s) that do not describe files UDS installed.',
1081
+ droppedForeignCommandHashes: 'Dropped {count} command record(s) for commands UDS does not ship.',
1082
+ droppedForeignNames: 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.',
1062
1083
  // Success
1063
1084
  updateSuccess: '✓ Standards updated successfully!',
1064
1085
  versionUpdated: 'Version: {current} → {latest}',
@@ -1136,6 +1157,9 @@ export const messages = {
1136
1157
  skillsUpdatedWithErrors: 'Updated Skills with {errors} errors',
1137
1158
  updatingCommands: 'Updating Commands...',
1138
1159
  commandsUpdated: 'Updated Commands for {count} AI tools',
1160
+ // XSPEC-454 R4: the number of tools and the number of commands are different numbers and need different slots.
1161
+ // `commandsUpdated` above counts TOOLS; feeding it the command count printed "51 AI tools" for one tool.
1162
+ commandsUpdatedCounts: 'Updated {commands} commands for {tools} AI tool(s): {locations}',
1139
1163
  commandsUpdatedWithErrors: 'Updated Commands with {errors} errors',
1140
1164
  // New standards detection
1141
1165
  newStandardsFound: '{count} new standard(s) available for your level:',
@@ -1337,6 +1361,7 @@ export const messages = {
1337
1361
  error: '生成規格失敗',
1338
1362
  listTitle: '微規格列表',
1339
1363
  noSpecs: '沒有找到微規格。',
1364
+ statusUnparsed: '格式:SDD(狀態未解析)',
1340
1365
  createHint: '使用以下命令建立:uds spec create "您的意圖"',
1341
1366
  total: '總計',
1342
1367
  noId: '錯誤:請提供規格 ID。',
@@ -1981,6 +2006,12 @@ export const messages = {
1981
2006
  seeGuide: '參閱:https://github.com/AsiaOstrich/universal-dev-standards/blob/main/adoption/ADOPTION-GUIDE.md'
1982
2007
  },
1983
2008
 
2009
+ // deps command (XSPEC-456 R6)
2010
+ deps: {
2011
+ notApplicableNoPackageJson: '不適用:沒有 package.json,未檢查任何東西',
2012
+ notApplicableNoRuntimeDeps: '不適用:這個套件沒有宣告執行期相依,未檢查任何東西'
2013
+ },
2014
+
1984
2015
  // skills command
1985
2016
  skills: {
1986
2017
  title: '通用開發標準 - 已安裝的 Skills',
@@ -1993,6 +2024,7 @@ export const messages = {
1993
2024
  manualInstallDeprecated: '⚠ 手動安裝已棄用。',
1994
2025
  manualInstallHint: '建議遷移到 Plugin Marketplace。',
1995
2026
  totalUniqueSkills: '唯一 Skills 總數',
2027
+ skillFilesTracked: '`uds check` 追蹤這些技能的 {files} 個技能檔案(它計的是所有工具的檔案數,不是技能數)。',
1996
2028
  recommendation: '建議:遷移到 Plugin Marketplace',
1997
2029
  benefits: '好處:自動更新、更好的整合',
1998
2030
  migrateCommand: '遷移指令:'
@@ -2053,9 +2085,12 @@ export const messages = {
2053
2085
  // Diff display
2054
2086
  couldNotReadFile: '無法讀取目前檔案。',
2055
2087
  couldNotDetermineSource2: '無法判斷原始來源路徑。',
2056
- fetchingOriginal: '從 GitHub 取得原始檔案...',
2057
- couldNotFetchOriginal: '無法取得原始內容。',
2058
- rateLimited: 'GitHub API 請求頻率超過限制,請稍候幾分鐘後再試。',
2088
+ // XSPEC-453 R1:原稿取自所裝套件內的檔,不下載。
2089
+ diffBaseline: '比對基準:已安裝的 UDS 套件內的原始檔(版本 {version}),不連網。要看 UDS 之後改了什麼,請執行 `uds update --plan`。',
2090
+ diffBaselineVersionDiffers: '注意:這些標準是從 UDS {installed} 安裝的,但目前安裝的套件是 {version}。兩版之間 UDS 自己改過的檔,即使你沒動,也會在下方列成差異;`uds update --plan` 可列出這些。',
2091
+ diffNone: '沒有被修改的檔案,因此沒有差異可顯示。',
2092
+ noOriginalInPackage: '此版本的套件沒有 {file} 的原稿(預期是 UDS {version} 內的 {source}),因此無法比對。未下載任何東西;請重新安裝或升級 universal-dev-standards。',
2093
+ couldNotReadOriginal: '無法讀取 {file} 的套件內原稿。',
2059
2094
  diffOriginal: '--- 原始',
2060
2095
  diffCurrent: '+++ 目前',
2061
2096
  diffTruncated: '...(差異已截斷,僅顯示前 20 個變更)',
@@ -2134,6 +2169,11 @@ export const messages = {
2134
2169
  // Final status
2135
2170
  projectCompliant: '✓ 專案符合標準',
2136
2171
  issuesDetected: '⚠ 偵測到一些問題。請檢視上方詳情。',
2172
+ skillsIntegrityFix: ' 上方列出的技能檔遺失或被改過:執行 `uds update --apply --skills` 重新安裝。',
2173
+ commandsIntegrityFix: ' 上方列出的斜線命令檔遺失或被改過:執行 `uds update --apply --commands` 重新安裝。',
2174
+ commandsStaleRecordsIgnored: ' 已忽略 {count} 筆命令紀錄:它們描述的是 UDS 不出貨的命令。',
2175
+ commandsElsewhereIgnored: ' 已忽略 {count} 筆命令紀錄:這些命令裝在使用者層級(所有專案共用),本專案的檢查不為它們背書。',
2176
+ skillsStaleRecordsIgnored: ' 已忽略 {count} 筆技能紀錄:它們描述的不是 UDS 安裝的檔案(例如你自己的技能,或舊版 UDS 誤拷入、後來已移除的資料夾)。',
2137
2177
  // Installation prompts
2138
2178
  offerSkillsInstallation: 'Skills 安裝',
2139
2179
  offerCommandsInstallation: '斜線命令安裝',
@@ -2190,6 +2230,8 @@ export const messages = {
2190
2230
  userCommentsPrompt: '補充說明(選填):',
2191
2231
  reportTitle: 'UDS 審計回饋',
2192
2232
  dryRunNotice: '預覽模式 — 未建立 issue',
2233
+ offlineNoSubmit: '離線模式:不提交回報。',
2234
+ offlineDryRunHint: ' 要預覽內容請加 --dry-run;要提交請拿掉 --offline 再執行。',
2193
2235
  ghNotFound: '未找到 gh CLI,使用瀏覽器連結',
2194
2236
  copiedToClipboard: '完整報告已複製至剪貼簿',
2195
2237
  urlTruncated: '報告過長無法放入 URL,已使用摘要。完整報告已複製至剪貼簿。',
@@ -2326,6 +2368,9 @@ export const messages = {
2326
2368
  syncedIntegrations: '已同步 {count} 個整合檔案',
2327
2369
  prunedOrphanedBlockHashes: '已清除 {count} 個孤兒整合雜湊:{files}',
2328
2370
  droppedRetiredHashes: '已清掉 {count} 筆 manifest 紀錄——這些檔案 UDS 已不再出貨,而且本來就已經不在了:',
2371
+ droppedForeignSkillHashes: '已清掉 {count} 筆技能紀錄——它們描述的不是 UDS 安裝的檔案。',
2372
+ droppedForeignCommandHashes: '已清掉 {count} 筆命令紀錄——UDS 不出貨這些命令。',
2373
+ droppedForeignNames: '已從 manifest 清掉 {count} 個技能/命令名稱——UDS 不出貨,或並未安裝。',
2329
2374
  // Success
2330
2375
  updateSuccess: '✓ 標準更新成功!',
2331
2376
  versionUpdated: '版本:{current} → {latest}',
@@ -2403,6 +2448,7 @@ export const messages = {
2403
2448
  skillsUpdatedWithErrors: '更新 Skills 時發生 {errors} 個錯誤',
2404
2449
  updatingCommands: '更新斜線命令中...',
2405
2450
  commandsUpdated: '已為 {count} 個 AI 工具更新斜線命令',
2451
+ commandsUpdatedCounts: '已為 {tools} 個 AI 工具更新 {commands} 個斜線命令:{locations}',
2406
2452
  commandsUpdatedWithErrors: '更新斜線命令時發生 {errors} 個錯誤',
2407
2453
  // New standards detection
2408
2454
  newStandardsFound: '有 {count} 個新標準可供您的等級使用:',
@@ -2604,6 +2650,7 @@ export const messages = {
2604
2650
  error: '生成规格失败',
2605
2651
  listTitle: '微规格列表',
2606
2652
  noSpecs: '没有找到微规格。',
2653
+ statusUnparsed: '格式:SDD(状态未解析)',
2607
2654
  createHint: '使用以下命令创建:uds spec create "您的意图"',
2608
2655
  total: '总计',
2609
2656
  noId: '错误:请提供规格 ID。',
@@ -3264,6 +3311,12 @@ export const messages = {
3264
3311
  runCheck: '执行 `uds check` 验证采用状态'
3265
3312
  },
3266
3313
 
3314
+ // deps command (XSPEC-456 R6)
3315
+ deps: {
3316
+ notApplicableNoPackageJson: '不适用:没有 package.json,未检查任何东西',
3317
+ notApplicableNoRuntimeDeps: '不适用:这个包没有声明运行时依赖,未检查任何东西'
3318
+ },
3319
+
3267
3320
  // skills command
3268
3321
  skills: {
3269
3322
  title: '通用开发标准 - 已安装的 Skills',
@@ -3276,6 +3329,7 @@ export const messages = {
3276
3329
  manualInstallDeprecated: '⚠ 手动安装已弃用。',
3277
3330
  manualInstallHint: '建议迁移到 Plugin Marketplace。',
3278
3331
  totalUniqueSkills: '唯一 Skills 总数',
3332
+ skillFilesTracked: '`uds check` 跟踪这些技能的 {files} 个技能文件(它计的是所有工具的文件数,不是技能数)。',
3279
3333
  recommendation: '建议:迁移到 Plugin Marketplace',
3280
3334
  benefits: '好处:自动更新、更好的集成',
3281
3335
  migrateCommand: '迁移指令:'
@@ -3336,9 +3390,12 @@ export const messages = {
3336
3390
  // Diff display
3337
3391
  couldNotReadFile: '无法读取当前文件。',
3338
3392
  couldNotDetermineSource2: '无法确定原始源路径。',
3339
- fetchingOriginal: '从 GitHub 获取原始文件...',
3340
- couldNotFetchOriginal: '无法获取原始内容。',
3341
- rateLimited: 'GitHub API 请求频率超过限制,请稍候几分钟后再试。',
3393
+ // XSPEC-453 R1:原稿取自所装包内的文件,不下载。
3394
+ diffBaseline: '比对基准:已安装的 UDS 包内的原始文件(版本 {version}),不联网。要查看 UDS 之后改了什么,请执行 `uds update --plan`。',
3395
+ diffBaselineVersionDiffers: '注意:这些标准是从 UDS {installed} 安装的,但当前安装的包是 {version}。两个版本之间 UDS 自己改过的文件,即使你没动,也会在下方列为差异;`uds update --plan` 可列出这些。',
3396
+ diffNone: '没有被修改的文件,因此没有差异可显示。',
3397
+ noOriginalInPackage: '此版本的包没有 {file} 的原稿(预期是 UDS {version} 内的 {source}),因此无法比对。未下载任何内容;请重新安装或升级 universal-dev-standards。',
3398
+ couldNotReadOriginal: '无法读取 {file} 的包内原稿。',
3342
3399
  diffOriginal: '--- 原始',
3343
3400
  diffCurrent: '+++ 当前',
3344
3401
  diffTruncated: '...(差异已截断,显示前 20 处更改)',
@@ -3417,6 +3474,11 @@ export const messages = {
3417
3474
  // Final status
3418
3475
  projectCompliant: '✓ 项目符合标准',
3419
3476
  issuesDetected: '⚠ 检测到一些问题。详情请查看上文。',
3477
+ skillsIntegrityFix: ' 上方列出的技能文件缺失或被改过:运行 `uds update --apply --skills` 重新安装。',
3478
+ commandsIntegrityFix: ' 上方列出的斜杠命令文件缺失或被改过:运行 `uds update --apply --commands` 重新安装。',
3479
+ commandsStaleRecordsIgnored: ' 已忽略 {count} 条命令记录:它们描述的是 UDS 不发布的命令。',
3480
+ commandsElsewhereIgnored: ' 已忽略 {count} 条命令记录:这些命令装在用户级(所有项目共用),本项目的检查不为它们背书。',
3481
+ skillsStaleRecordsIgnored: ' 已忽略 {count} 条技能记录:它们描述的不是 UDS 安装的文件(例如你自己的技能,或旧版 UDS 误拷入、后来已移除的文件夹)。',
3420
3482
  // Installation prompts
3421
3483
  offerSkillsInstallation: 'Skills 安装',
3422
3484
  offerCommandsInstallation: '斜线命令安装',
@@ -3469,6 +3531,8 @@ export const messages = {
3469
3531
  userCommentsPrompt: '补充说明(选填):',
3470
3532
  reportTitle: 'UDS 审计反馈',
3471
3533
  dryRunNotice: '预览模式 — 未创建 issue',
3534
+ offlineNoSubmit: '离线模式:不提交回报。',
3535
+ offlineDryRunHint: ' 要预览内容请加 --dry-run;要提交请去掉 --offline 再运行。',
3472
3536
  ghNotFound: '未找到 gh CLI,使用浏览器链接',
3473
3537
  copiedToClipboard: '完整报告已复制到剪贴板',
3474
3538
  urlTruncated: '报告过长无法放入 URL,已使用摘要。完整报告已复制到剪贴板。',
@@ -3517,6 +3581,9 @@ export const messages = {
3517
3581
  syncedIntegrations: '已同步 {count} 个集成文件',
3518
3582
  prunedOrphanedBlockHashes: '已清除 {count} 个孤儿集成哈希:{files}',
3519
3583
  droppedRetiredHashes: '已清掉 {count} 笔 manifest 记录——这些文件 UDS 已不再发布,而且本来就已经不在了:',
3584
+ droppedForeignSkillHashes: '已清掉 {count} 条技能记录——它们描述的不是 UDS 安装的文件。',
3585
+ droppedForeignCommandHashes: '已清掉 {count} 条命令记录——UDS 不发布这些命令。',
3586
+ droppedForeignNames: '已从 manifest 清掉 {count} 个技能/命令名称——UDS 不发布,或并未安装。',
3520
3587
  // Success
3521
3588
  updateSuccess: '✓ 标准更新成功!',
3522
3589
  versionUpdated: '版本:{current} → {latest}',
@@ -3594,6 +3661,7 @@ export const messages = {
3594
3661
  skillsUpdatedWithErrors: '更新 Skills 时发生 {errors} 个错误',
3595
3662
  updatingCommands: '正在更新斜线命令...',
3596
3663
  commandsUpdated: '已为 {count} 个 AI 工具更新斜线命令',
3664
+ commandsUpdatedCounts: '已为 {tools} 个 AI 工具更新 {commands} 个斜线命令:{locations}',
3597
3665
  commandsUpdatedWithErrors: '更新斜线命令时发生 {errors} 个错误',
3598
3666
  // New standards detection
3599
3667
  newStandardsFound: '有 {count} 个新标准可用于您的级别:',
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Where UDS update backups live (XSPEC-456 R7).
3
+ *
4
+ * New backups all go into ONE folder, `.uds-backups/`, one subfolder per backup. Backups made before
5
+ * XSPEC-456 R7 are single folders named `.uds-backup-<time>-<NNNN>` directly in the project root; they are
6
+ * not moved and are still backups. A `backupId` is the backup folder's path relative to the project root
7
+ * (`.uds-backups/<time>-<NNNN>` or `.uds-backup-<time>-<NNNN>`), so everything that joins it onto the project
8
+ * root works for both.
9
+ *
10
+ * @module reconciler/backup-locations
11
+ */
12
+
13
+ import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'fs';
14
+ import { join } from 'path';
15
+
16
+ /** The one folder new backups go into. */
17
+ export const BACKUPS_DIR = '.uds-backups';
18
+ /** Backups made before XSPEC-456 R7: one folder each, directly in the project root. */
19
+ export const LEGACY_BACKUP_PREFIX = '.uds-backup-';
20
+
21
+ let counter = 0;
22
+
23
+ /** A fresh backup id, relative to the project root. The counter orders two backups made in the same millisecond. */
24
+ export function newBackupId() {
25
+ const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
26
+ return `${BACKUPS_DIR}/${timestamp}-${String(++counter).padStart(4, '0')}`;
27
+ }
28
+
29
+ /**
30
+ * Make sure `.uds-backups/` exists and hides itself from git.
31
+ *
32
+ * WHY THIS IS NOT A LINE IN THE ADOPTER'S .gitignore. We create this directory in someone else's repository;
33
+ * making it disappear is our job, but editing their .gitignore to do it is not - that file is theirs, it may
34
+ * be generated, and a tool appending to it on every update is a worse trade than the problem. A `*` inside
35
+ * the folder ignores everything in it (this file included, which is fine: git reads .gitignore whether or
36
+ * not it is tracked), so `git status` and `git add -A` never see a backup, and nothing outside is touched.
37
+ *
38
+ * WHY IT EXISTS. Nothing ignored the backup folders, so `git add -A` in two sibling repos committed them:
39
+ * EngramGraph's 0.8.0 release commit took in 5 backups - 360 files, 73,992 lines - and dev-platform took one.
40
+ * Both were public. (Until XSPEC-456 R7 each backup carried its own copy of this file.)
41
+ *
42
+ * Git is not the only thing that reads a project folder: indexers, IDE search and grep do not look at
43
+ * .gitignore, which is why the backups share ONE folder name that is easy to exclude (the update summary
44
+ * says so).
45
+ *
46
+ * @param {string} projectPath
47
+ * @param {string[]} errors - Receives an error message when it did not work
48
+ */
49
+ export function ensureBackupsDir(projectPath, errors) {
50
+ const dir = join(projectPath, BACKUPS_DIR);
51
+ try {
52
+ mkdirSync(dir, { recursive: true });
53
+ const ignoreFile = join(dir, '.gitignore');
54
+ if (!existsSync(ignoreFile)) writeFileSync(ignoreFile, '*\n', 'utf8');
55
+ } catch (err) {
56
+ // A backup that git can see still beats no backup - the caller records this and carries on.
57
+ errors.push(`Failed to write ${BACKUPS_DIR}/.gitignore: ${err.message}`);
58
+ }
59
+ }
60
+
61
+ /** Ids of the backups in the shared folder. */
62
+ export function sharedBackupIds(projectPath) {
63
+ const dir = join(projectPath, BACKUPS_DIR);
64
+ if (!existsSync(dir)) return [];
65
+ return readdirSync(dir, { withFileTypes: true })
66
+ .filter((entry) => entry.isDirectory())
67
+ .map((entry) => `${BACKUPS_DIR}/${entry.name}`);
68
+ }
69
+
70
+ /** Add the ids of the backups an older UDS left in the project root to `into`. */
71
+ export function addLegacyBackupIds(projectPath, into) {
72
+ for (const entry of readdirSync(projectPath, { withFileTypes: true })) {
73
+ if (entry.isDirectory() && entry.name.startsWith(LEGACY_BACKUP_PREFIX)) into.push(entry.name);
74
+ }
75
+ }