universal-dev-standards 6.3.3 → 6.3.4

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.3
-translation_version: 6.3.3
+source_version: 6.3.4
+translation_version: 6.3.4
 last_synced: 2026-08-07
 status: current
 ---
@@ -17,6 +17,13 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.4] - 2026-08-07
+
+### Fixed
+
+- **`uds deps` 指名了一个 npm 不会安装的版本。** 解析字段原本取「所有已发布版本中满足声明范围的最高版本」。那是 semver 的规则，不是 npm 的：`npm-pick-manifest` 在 `latest` dist-tag 满足范围时优先采用它，存在的目的正是不让带着普通版本号的 `next` 或 `beta` 发布落到只要了一个 caret 的人身上。以 `@anthropic-ai/claude-agent-sdk` 实测（`latest = 0.3.223`、`next = 0.3.224`）：命令回报 0.3.224，而 `npm install …@^0.3` 实际装 0.3.223。**那个字段存在的全部目的就是说出「安装会拿到什么」，而它指名了没有任何安装会拿到的东西。** 现改为单次 `npm view` 同时取版本清单与 dist-tags，套用 npm 自己的优先顺序；`latest` 落在范围外时退回「范围内最高版本」——锁在旧 major 的项目仍得到诚实的答案。两个分支各有测试覆盖。
+- 前两个版本修的是这个命令的**措辞**，这一版修的是它的**算术**。值得直说：先前那些修正只是让一个错的数字变得更好读。
+
 ## [6.3.3] - 2026-08-07
 
 ### Fixed

package/bundled/locales/zh-CN/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.3.3 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.4 | **发布日期**: 2026-07-31 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 

package/bundled/locales/zh-TW/CHANGELOG.md

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.3.3
-translation_version: 6.3.3
+source_version: 6.3.4
+translation_version: 6.3.4
 last_synced: 2026-08-07
 status: current
 ---
@@ -17,6 +17,13 @@ status: current
 
 ## [Unreleased]
 
+## [6.3.4] - 2026-08-07
+
+### Fixed
+
+- **`uds deps` 指名了一個 npm 不會安裝的版本。** 解析欄位原本取「所有已發布版本中滿足宣告範圍的最高版本」。那是 semver 的規則，不是 npm 的：`npm-pick-manifest` 在 `latest` dist-tag 滿足範圍時優先採用它，存在的目的正是不讓帶著普通版本號的 `next` 或 `beta` 發布落到只要了一個 caret 的人身上。以 `@anthropic-ai/claude-agent-sdk` 實測（`latest = 0.3.223`、`next = 0.3.224`）：指令回報 0.3.224，而 `npm install …@^0.3` 實際裝 0.3.223。**那個欄位存在的全部目的就是說出「安裝會拿到什麼」，而它指名了沒有任何安裝會拿到的東西。** 現改為單次 `npm view` 同時取版本清單與 dist-tags，套用 npm 自己的優先順序；`latest` 落在範圍外時退回「範圍內最高版本」——鎖在舊 major 的專案仍得到誠實的答案。兩個分支各有測試覆蓋。
+- 前兩個版本修的是這個指令的**措辭**，這一版修的是它的**算術**。值得直說：先前那些修正只是讓一個錯的數字變得更好讀。
+
 ## [6.3.3] - 2026-08-07
 
 ### Fixed

package/bundled/locales/zh-TW/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
 
-**版本**: 6.3.3 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.3.4 | **發布日期**: 2026-07-31 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
 
 語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流，確保不同技術堆疊之間的一致性、品質和可維護性。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.3.3",
+  "version": "6.3.4",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/utils/dependency-resolution.js

@@ -38,6 +38,12 @@
  * silently answer a different question for anyone who does not install from
  * the public registry, and would answer it confidently.
  *
+ * **And it applies npm's resolution rule, not semver's.** The highest version
+ * satisfying a range is *not* what npm installs: npm prefers the `latest`
+ * dist-tag whenever it satisfies, so a `next` or `beta` publish carrying an
+ * ordinary version number does not land on people. Getting this wrong made the
+ * tool name a version no consumer receives — see `resolveViaNpm`.
+ *
  * **A registry lookup that fails is never folded into "consistent".** It
  * becomes `unverifiable` and makes the whole check non-zero. A tool whose
  * "everything is fine" and "I could not find out" look the same is worse than
@@ -68,18 +74,30 @@ import semver from 'semver';
 const DEFAULT_CONCURRENCY = 8;
 
 /**
- * Run `npm view <name>@<range> version --json` and return the highest version
- * that satisfies the range.
+ * Return the version an install of `range` would actually receive.
+ *
+ * **This deliberately reproduces npm's rule, not semver's.** The obvious
+ * implementation — take the highest published version satisfying the range —
+ * is wrong, and wrong in the direction this module exists to catch. npm's
+ * resolver (`npm-pick-manifest`) prefers the `latest` dist-tag whenever it
+ * satisfies the range, and only falls back to the maximum otherwise. That rule
+ * exists so a `next` or `beta` publish does not land on people who asked for a
+ * caret.
+ *
+ * Measured on 2026-08-07: `@anthropic-ai/claude-agent-sdk` published
+ * `latest = 0.3.223` and `next = 0.3.224`, both ordinary semver strings, both
+ * satisfying `^0.3`. The maximum-satisfying rule named 0.3.224;
+ * `npm install @anthropic-ai/claude-agent-sdk@^0.3` installs 0.3.223. **The
+ * earlier implementation reported a version no consumer receives** — in the one
+ * column whose entire purpose is to say what they receive.
  *
- * npm prints a bare JSON string when exactly one version matches and a JSON
- * array when several do. The array is in publish order, **not** semver order —
- * a backport released after a major bump appears last while being the lowest
- * version — so the maximum is computed with semver rather than by taking the
- * final element. Guessing here would produce a confident wrong answer, which
- * is the failure mode this whole module exists to detect.
+ * Versions and tags are read in a single `npm view` call. The version list is
+ * in publish order, **not** semver order — a backport released after a major
+ * bump appears last while being the lowest version — so the fallback maximum is
+ * computed with semver rather than by taking the final element.
  */
 async function resolveViaNpm(name, range, run) {
-  const { code, stdout, stderr } = await run(['view', `${name}@${range}`, 'version', '--json']);
+  const { code, stdout, stderr } = await run(['view', name, 'versions', 'dist-tags', '--json']);
 
   if (code !== 0) {
     const detail = (stderr || stdout || '').split('\n').find((l) => l.trim()) ?? '';
@@ -93,13 +111,30 @@ async function resolveViaNpm(name, range, run) {
     throw new Error(`npm view returned output that is not JSON: ${stdout.slice(0, 120)}`);
   }
 
-  if (typeof parsed === 'string') return parsed;
-  if (Array.isArray(parsed) && parsed.length > 0) {
-    const max = semver.maxSatisfying(parsed, range);
-    if (max) return max;
-    throw new Error(`no version in [${parsed.join(', ')}] satisfies ${range}`);
+  // npm flattens the response when only one of the requested fields exists on
+  // the package, so neither key can be assumed present. A package with exactly
+  // one published version reports `versions` as a bare string.
+  const versions = Array.isArray(parsed?.versions)
+    ? parsed.versions
+    : typeof parsed?.versions === 'string'
+      ? [parsed.versions]
+      : Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === 'string'
+          ? [parsed]
+          : [];
+  const tags = parsed?.['dist-tags'] ?? {};
+
+  if (versions.length === 0) throw new Error('npm view returned no versions');
+
+  const latest = tags.latest;
+  if (typeof latest === 'string' && semver.valid(latest) && semver.satisfies(latest, range)) {
+    return latest;
   }
-  throw new Error('npm view returned no version');
+
+  const max = semver.maxSatisfying(versions, range);
+  if (max) return max;
+  throw new Error(`no published version of ${name} satisfies ${range}`);
 }
 
 /**

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "6.3.3",
+  "version": "6.3.4",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "6.3.3"
+      "version": "6.3.4"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "6.3.3",
+      "version": "6.3.4",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -2236,7 +2236,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "6.3.3",
+      "version": "6.3.4",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2248,7 +2248,7 @@
       "id": "verification-oracle",
       "name": "Verification Oracle Standards",
       "nameZh": "驗證 Oracle 標準",
-      "version": "6.3.3",
+      "version": "6.3.4",
       "source": {
         "human": "core/verification-oracle.md",
         "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2260,7 +2260,7 @@
       "id": "model-provenance",
       "name": "Model Provenance Policy Standards",
       "nameZh": "模型來源政策標準",
-      "version": "6.3.3",
+      "version": "6.3.4",
       "source": {
         "human": "core/model-provenance.md",
         "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2272,7 +2272,7 @@
       "id": "resource-cost-boundary",
       "name": "Resource / Cost Boundary Declaration Standards",
       "nameZh": "資源／成本邊界宣告標準",
-      "version": "6.3.3",
+      "version": "6.3.4",
       "source": {
         "human": "core/resource-cost-boundary.md",
         "ai": "ai/standards/resource-cost-boundary.ai.yaml"