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

package/src/utils/git-hooks.js

@@ -11,6 +11,7 @@
  * adopters (asiaostrich-telemetry-server, asiaostrich-telemetry-client,
  * machine-setup): all three have `.husky/pre-commit` calling `npx uds check`,
  * none has `core.hooksPath` set, and the hook has never once run.
+ * (That `npx uds check` form was itself replaced — see buildPreCommitBlock.)
  *
  * Fix: set `core.hooksPath` directly ourselves. This is exactly what husky's
  * own `index.js` does internally (verified against husky ^9.1.7's source:
@@ -94,7 +95,7 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
     return {
       wired: false,
       reason: `git core.hooksPath is already set to "${configured}"`,
-      hint: `UDS will not override an existing core.hooksPath. Confirm the hook script there also runs \`npx uds check\`, or switch it yourself: git config --local core.hooksPath ${targetRelDir}`
+      hint: `UDS will not override an existing core.hooksPath. Confirm the hook script there also runs \`universal-dev-standards check\` (the installed CLI — not the short name "uds", which on the npm registry is an unrelated package), or switch it yourself: git config --local core.hooksPath ${targetRelDir}`
     };
   }
 
@@ -107,7 +108,7 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
     return {
       wired: false,
       reason: '.git/hooks/pre-commit already exists',
-      hint: 'UDS will not overwrite or bypass an existing .git/hooks/pre-commit. Add "npx uds check" to it manually, or remove it and re-run `uds init`.'
+      hint: 'UDS will not overwrite or bypass an existing .git/hooks/pre-commit. Add a "universal-dev-standards check" line to it manually (it needs the UDS CLI installed in this project or on PATH), or remove it and re-run `uds init`.'
     };
   }
 
@@ -126,10 +127,133 @@ export function wireGitHooksPath(projectPath, targetRelDir) {
   }
 }
 
-/** Does `filePath` contain the marker UDS writes into a hook it manages? */
+// ─────────────────────────────────────────────────────────────────────────────
+// What UDS writes into `.husky/pre-commit`.
+//
+// 🔴 This used to be the single line `npx uds check`. `npx` resolves a bare
+// command name from node_modules/.bin and PATH first, and only when neither has
+// it does it go to the npm registry — and the registry package named `uds` is
+// NOT this project (it is an unrelated package by another maintainer, no
+// `bin`, last published 2022). So a clone with no UDS installed had a commit
+// hook that asked npm for a stranger's package by name. It failed today only
+// because that package has no executable; the day its owner publishes one with a
+// `uds` bin, every adopter's every commit runs the stranger's code.
+//
+// Measured 2026-09-30 against a local fake registry that logs each request
+// (npm 10.9.9, 11.20.0, 12.1.0 — identical): `npx --no-install uds` STILL fetches
+// the package metadata for `uds` (GET /uds), so `--no-install` is not a fix; and
+// `npx --no-install --package=universal-dev-standards uds` does not find a
+// GLOBAL install at all (it goes to the registry for our own name and fails).
+// Neither is usable, so the hook does not involve npm at all: it looks in this
+// project's node_modules/.bin, then on PATH, and it looks for the bin named
+// after the full package name — `universal-dev-standards` is a name only this
+// project can publish, `uds` is a name anyone's package can also claim.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** First line of the block UDS writes (also the marker older UDS versions wrote). */
+export const UDS_HOOK_MARKER = '# UDS Standard Check';
+/** Last line of the block — lets uninstall remove the whole block, not guess line by line. */
+export const UDS_HOOK_END_MARKER = '# End UDS Standard Check';
+/** The bin every UDS release has shipped since the rename; named after the package on purpose. */
+export const UDS_BIN_NAME = 'universal-dev-standards';
+/** A hook line that runs the UDS check — the old short form or the current full-name form. */
+export const UDS_CHECK_COMMAND_RE = /\b(?:uds|universal-dev-standards)\s+check\b/;
+
+/**
+ * Any place a hook script runs the bare name `uds` through a package runner
+ * (npx, bunx, pnpm dlx, yarn dlx, npm exec ...). Broader than the two exact lines UDS
+ * ever wrote (see legacy-hook-migration.js): this finds lines to TELL the
+ * adopter about, not lines UDS may change.
+ */
+export const BARE_UDS_RUNNER_RE = /\b(?:npx|bunx|pnpx|pnpm\s+dlx|yarn\s+dlx|npm\s+exec|npm\s+x)\s+(?:-\S+\s+)*uds\b/;
+
+/** Does this hook script still run the bare name `uds` through a package runner? */
+export function hasBareUdsRunner(content) {
+  return typeof content === 'string' && content.split('\n').some((l) => BARE_UDS_RUNNER_RE.test(l));
+}
+
+/** Does hook script `content` run the UDS check, in either the old or the current form? */
+export function hookRunsUdsCheck(content) {
+  return typeof content === 'string' && UDS_CHECK_COMMAND_RE.test(content);
+}
+
+/**
+ * The block `uds init` appends to `.husky/pre-commit` (and `uds update` swaps in
+ * for the old one-liner). POSIX sh; runs in git-bash on Windows.
+ *
+ * - The subshell keeps the PATH change from leaking into the adopter's own
+ *   commands in the same hook file.
+ * - `|| exit $?` makes both outcomes stop the commit even when the adopter has
+ *   put more commands after this block. Without it the "not installed" branch
+ *   would be a silent skip of the check, which is what this must never be.
+ * - Not installed: say what is missing and how to fix it, exit non-zero. It
+ *   neither skips the check nor downloads anything.
+ *
+ * @param {{args?: string, hookFile?: string}} [opts]
+ *   args     — extra arguments to keep on the check command
+ *              (e.g. `--standard checkin-standards`, which older UDS versions wrote).
+ *   hookFile — the file the block is written into, named in the "blocked" message so
+ *              it points at the file the adopter actually has (default `.husky/pre-commit`;
+ *              the native hook passes `.git/hooks/pre-commit`).
+ * @returns {string} the block, LF line endings, ending with a newline
+ */
+export function buildPreCommitBlock({ args = '', hookFile = '.husky/pre-commit' } = {}) {
+  const cmd = args ? `${UDS_BIN_NAME} check ${args}` : `${UDS_BIN_NAME} check`;
+  return [
+    UDS_HOOK_MARKER,
+    '# Runs the UDS CLI installed in this project (node_modules/.bin) or on PATH.',
+    '# It never asks npm to fetch anything: the short name "uds" on the npm registry',
+    '# belongs to an unrelated package, and npx would download and run it.',
+    '(',
+    '  PATH="$PWD/node_modules/.bin:$PATH"',
+    `  if command -v ${UDS_BIN_NAME} >/dev/null 2>&1; then`,
+    `    ${cmd}`,
+    '    exit $?',
+    '  fi',
+    `  echo "[UDS] Pre-commit check cannot run: the UDS CLI (${UDS_BIN_NAME}) is not installed." >&2`,
+    `  echo "[UDS] Install it:  npm install --save-dev ${UDS_BIN_NAME}   (or: npm install -g ${UDS_BIN_NAME})" >&2`,
+    `  echo "[UDS] This commit is blocked until it is installed, or until you remove this block from ${hookFile}." >&2`,
+    '  exit 1',
+    ') || exit $?',
+    UDS_HOOK_END_MARKER,
+    ''
+  ].join('\n');
+}
+
+/**
+ * Remove the block buildPreCommitBlock() writes — from the marker line through
+ * the end-marker line, inclusive — and nothing else. A block whose end marker is
+ * gone (the adopter cut into it) is left alone: what remains of it is no longer
+ * provably UDS's, and the caller's line-level fallback deals with the lines it can name.
+ * @returns {{content: string, removed: boolean}}
+ */
+export function stripUdsHookBlock(content) {
+  const lines = content.split('\n');
+  const out = [];
+  let removed = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === UDS_HOOK_MARKER) {
+      let end = -1;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === UDS_HOOK_END_MARKER) { end = j; break; }
+        // Another marker before an end marker means this block is not well-formed.
+        if (lines[j].trim() === UDS_HOOK_MARKER) break;
+      }
+      if (end !== -1) {
+        i = end;
+        removed = true;
+        continue;
+      }
+    }
+    out.push(lines[i]);
+  }
+  return { content: out.join('\n'), removed };
+}
+
+/** Does `filePath` contain a hook line UDS manages (the old one-liner or the current block)? */
 function hasUdsMarker(filePath) {
   try {
-    return readFileSync(filePath, 'utf-8').includes('uds check');
+    return hookRunsUdsCheck(readFileSync(filePath, 'utf-8'));
   } catch {
     return false;
   }
@@ -225,7 +349,7 @@ export function stripLegacyHuskyShLine(content) {
  * @param {string} projectPath
  * @returns {{relevant: boolean, wired?: boolean, hookFile?: string,
  *   configuredHooksPath?: string|null, effectiveHooksDir?: string|null,
- *   legacyV8?: boolean, missingShebang?: boolean}}
+ *   legacyV8?: boolean, missingShebang?: boolean, legacyBareUds?: boolean}}
  *   `relevant: false` means there is nothing UDS-managed to report on (no
  *   hook file, or hooks-dir could not be determined — never guess "unwired"
  *   from a failed lookup).
@@ -252,6 +376,13 @@ export function checkPreCommitHookWiring(projectPath) {
     try { return !hasShebang(readFileSync(managedPath, 'utf-8')); } catch { return false; }
   })();
 
+  // Independent of wiring, like missingShebang: the file can be wired and still ask
+  // npm for the bare name `uds` (see buildPreCommitBlock). Only the husky file is
+  // examined — that is the one UDS wrote the old one-liner into.
+  const legacyBareUds = hasHuskyHook && (() => {
+    try { return hasBareUdsRunner(readFileSync(huskyHookPath, 'utf-8')); } catch { return false; }
+  })();
+
   const effectiveFile = join(effectiveHooksDir, 'pre-commit');
   let wired = false;
   if (existsSync(effectiveFile)) {
@@ -264,7 +395,7 @@ export function checkPreCommitHookWiring(projectPath) {
     }
   }
 
-  if (wired) return { relevant: true, wired: true, hookFile, missingShebang };
+  if (wired) return { relevant: true, wired: true, hookFile, missingShebang, legacyBareUds };
 
   const legacyV8 = hasHuskyHook && (() => {
     try { return hasLegacyHuskyShLine(readFileSync(huskyHookPath, 'utf-8')); } catch { return false; }
@@ -277,6 +408,7 @@ export function checkPreCommitHookWiring(projectPath) {
     configuredHooksPath: getLocalHooksPathConfig(projectPath),
     effectiveHooksDir,
     legacyV8,
-    missingShebang
+    missingShebang,
+    legacyBareUds
   };
 }

package/src/utils/hasher.js

@@ -532,6 +532,42 @@ export function computeIntegrationBlockHash(filePath) {
   }
 }
 
+/**
+ * Hash everything in an integration file that is OUTSIDE the UDS marker block.
+ *
+ * `computeIntegrationBlockHash` answers "did anyone edit what UDS manages?".
+ * This answers the opposite question, which `uds uninstall` needs: "is anything
+ * outside the block something other than what UDS itself wrote?". A file UDS
+ * created from nothing (AGENTS.md's `# AGENTS.md` / `> Auto-generated by ...`
+ * header and its trailing sections, CLAUDE.md's leading guidance) has plenty of
+ * text outside the markers, and that text alone cannot tell "generated by UDS"
+ * from "typed by the adopter" — only a hash recorded when UDS created the file,
+ * compared with the same hash now, can.
+ *
+ * Line endings are normalized (same reason as every other hash here) and each
+ * side is trimmed, so an editor adding a trailing newline is not "a user edit".
+ *
+ * @param {string} filePath - Absolute file path
+ * @returns {{hash: string, size: number}|null} null when the file cannot be read,
+ *   has no marker block, or has an ambiguous marker pair (no proof is available)
+ */
+export function computeOutsideBlockHash(filePath) {
+  try {
+    const content = normalizeLineEndings(readFileSync(filePath, 'utf-8'));
+    const { before, blockContent, after } = extractBlockContent(content, detectFormat(filePath));
+    if (!blockContent) return null;
+    const outside = `${before.trim()}\n\u0000\n${after.trim()}`;
+    return {
+      hash: `sha256:${createHash('sha256').update(outside).digest('hex')}`,
+      size: Buffer.byteLength(outside, 'utf-8')
+    };
+  } catch {
+    // Includes AmbiguousMarkerError: with two marker pairs there is no single
+    // "outside", so there is nothing to prove anything with.
+    return null;
+  }
+}
+
 /**
  * Compare integration block hash with stored hash info
  * @param {string} filePath - Absolute file path

package/src/utils/integration-generator.js

@@ -3202,8 +3202,14 @@ export function writeIntegrationFile(tool, config, projectPath) {
   try {
     let content = generateIntegrationContent({ ...config, tool });
 
+    // Whether this call CREATES the file (as opposed to merging into one that was
+    // already there). Only a file UDS created from nothing can later be proven
+    // to be wholly UDS's — see core/install-records.js. Taken from the existence
+    // check that already gates the merge below, before anything is written.
+    const created = !existsSync(filePath);
+
     // Handle merge if file exists
-    if (existsSync(filePath)) {
+    if (!created) {
       const existingContent = readFileSync(filePath, 'utf-8');
 
       if (config.mergeStrategy) {
@@ -3242,6 +3248,7 @@ export function writeIntegrationFile(tool, config, projectPath) {
       success: true,
       path: fileName, // Return relative path for consistency
       absolutePath: filePath,
+      created,
       blockHashInfo // Contains: blockHash, blockSize, fullHash, fullSize
     };
   } catch (error) {
@@ -3584,8 +3591,8 @@ export function parseStandardsIndexCount(content) {
 export function wrapWithMarkers(content, format) {
   const markers = UDS_MARKERS[format] || UDS_MARKERS.markdown;
   const warning = format === 'plaintext'
-    ? '# WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds init\' or \'npx uds update\' to modify.'
-    : '<!-- WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds init\' or \'npx uds update\' to modify. -->';
+    ? '# WARNING: This block is managed by UDS. DO NOT manually edit. Use \'npx universal-dev-standards init\' or \'npx universal-dev-standards update\' to modify.'
+    : '<!-- WARNING: This block is managed by UDS. DO NOT manually edit. Use \'npx universal-dev-standards init\' or \'npx universal-dev-standards update\' to modify. -->';
   // 冪等：warning 位於 markers **內部**，而 extractMarkedContent 取出的內容也含它，
   // 於是重新包裝會疊出第二份（dev-platform CLAUDE.md 實測 178/179 兩行完全相同）。
   // 這裡先剝掉內容開頭既有的 warning，不論上游哪條路徑造成都能修掉。
@@ -3949,7 +3956,7 @@ export function generateAgentsMdSummary(config = {}) {
       blockLines.push(`- \`${dir}/${filename}\` — ${filename.replace(suffix, '')}`);
     }
   } else {
-    blockLines.push('No standards installed yet. Run `npx uds init` to install.');
+    blockLines.push('No standards installed yet. Run `npx universal-dev-standards init` to install.');
   }
 
   lines.push(wrapWithMarkers(blockLines.join('\n'), 'markdown'));
@@ -3976,12 +3983,14 @@ export function generateAgentsMdSummary(config = {}) {
  */
 export function writeAgentsMdSummary(config, projectPath) {
   const filePath = join(projectPath, 'AGENTS.md');
-
   try {
     let content = generateAgentsMdSummary({ ...config, projectPath });
 
+    // See writeIntegrationFile: true only when this call creates the file.
+    const created = !existsSync(filePath);
+
     // Handle merge if file exists (preserve user content outside markers)
-    if (existsSync(filePath)) {
+    if (!created) {
       const existingContent = readFileSync(filePath, 'utf-8');
       const newParts = extractMarkedContent(content, 'markdown');
       if (newParts.content) {
@@ -3997,6 +4006,7 @@ export function writeAgentsMdSummary(config, projectPath) {
       success: true,
       path: 'AGENTS.md',
       absolutePath: filePath,
+      created,
       blockHashInfo
     };
   } catch (error) {

package/src/utils/legacy-hook-migration.js

@@ -0,0 +1,112 @@
+/**
+ * Migrate the pre-commit hook line older UDS versions wrote
+ * (`npx uds check`) to the block current UDS writes.
+ *
+ * Why it exists: every adopter who ran `uds init` before this fix has
+ * `.husky/pre-commit` asking `npx` to run the bare name `uds`. `npx` looks in
+ * node_modules/.bin and PATH first and otherwise asks the npm registry — where
+ * `uds` is an unrelated package that is not ours (see buildPreCommitBlock in
+ * git-hooks.js for the measurements). Fixing what `uds init` writes today does
+ * nothing for the hooks already on disk, so `uds update` swaps them.
+ *
+ * ⚠️ THIS FILE RECOGNISES the old text; it must never EMIT it. The regression
+ * guard (tests/unit/no-bare-uds-npx.test.js) lists this file as the one place
+ * a bare-name npx string is allowed, and says why. Nothing here may write one.
+ *
+ * What counts as "UDS wrote this line" — exact equality, not a pattern:
+ * only the two shapes UDS has ever generated, and only directly under the
+ * marker comment UDS put above them.
+ *   2026-02-04 .. 2026-03-04   npx uds check --standard checkin-standards
+ *   2026-03-04 .. this fix     npx uds check
+ * (from `git log -S` on the writer in cli/src/commands/init.js.) A line an
+ * adopter edited, or wrote themselves, is NOT swapped: it cannot be proven to be
+ * ours, and a hook that runs the adopter's own arguments is theirs to change.
+ * It is reported, with the exact line number and what to write instead.
+ *
+ * @module utils/legacy-hook-migration
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { buildPreCommitBlock, UDS_HOOK_MARKER, BARE_UDS_RUNNER_RE, hasBareUdsRunner } from './git-hooks.js';
+import { getFileRecord, proveUnchanged, recordFile, newRecorder, RECORD_KINDS } from '../core/install-records.js';
+
+/** The exact command lines UDS itself has written under the marker, and the extra arguments each carried. */
+const UDS_WRITTEN_LEGACY_LINES = new Map([
+  ['npx uds check', ''],
+  ['npx uds check --standard checkin-standards', '--standard checkin-standards']
+]);
+
+/**
+ * Swap the legacy hook line UDS wrote in `.husky/pre-commit` for the current block.
+ *
+ * @param {string} projectPath
+ * @param {{plan?: boolean, manifest?: object|null}} [opts]
+ *   plan     — report what would change, write nothing
+ *   manifest — read only to see whether the file was provably UDS's before the
+ *              swap (so the install record can follow it); may be null
+ * @returns {{
+ *   state: 'none'|'migrated'|'would-migrate'|'kept'|'error',
+ *   replaced: number,           // legacy UDS-written lines swapped (or that would be)
+ *   kept: Array<{line: number, text: string}>, // bare-name lines UDS cannot prove it wrote
+ *   recorder: object|null,      // fold into the manifest when non-null
+ *   error?: string
+ * }}
+ */
+export function migrateLegacyHuskyHook(projectPath, { plan = false, manifest = null } = {}) {
+  const rel = '.husky/pre-commit';
+  const abs = join(projectPath, '.husky', 'pre-commit');
+  const none = { state: 'none', replaced: 0, kept: [], recorder: null };
+  if (!existsSync(abs)) return none;
+
+  let content;
+  try {
+    content = readFileSync(abs, 'utf-8');
+  } catch (e) {
+    return { ...none, state: 'error', error: e.message };
+  }
+  if (!hasBareUdsRunner(content)) return none;
+
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split('\n');
+  const out = [];
+  const kept = [];
+  let replaced = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i].replace(/\r$/, '');
+    const next = i + 1 < lines.length ? lines[i + 1].replace(/\r$/, '').trim() : null;
+    // Marker line directly followed by a line UDS is known to have written.
+    if (text.trim() === UDS_HOOK_MARKER && next !== null && UDS_WRITTEN_LEGACY_LINES.has(next)) {
+      const block = buildPreCommitBlock({ args: UDS_WRITTEN_LEGACY_LINES.get(next) });
+      // block ends with '\n'; drop that so the surrounding line join supplies it.
+      out.push(...block.replace(/\n$/, '').split('\n').map((l) => l + (eol === '\r\n' ? '\r' : '')));
+      replaced += 1;
+      i += 1; // the legacy command line is consumed
+      continue;
+    }
+    if (BARE_UDS_RUNNER_RE.test(text)) kept.push({ line: i + 1, text: text.trim() });
+    out.push(lines[i]);
+  }
+
+  if (replaced === 0) return { state: 'kept', replaced: 0, kept, recorder: null };
+
+  if (plan) return { state: 'would-migrate', replaced, kept, recorder: null };
+
+  // Was the whole file provably UDS's until now? Then the swap must not cost it
+  // that proof: re-record the new content, or uninstall falls back from "delete
+  // the file UDS created" to "strip lines".
+  let recorder = null;
+  const wasProven = !!manifest && !!getFileRecord(manifest, rel) && proveUnchanged(manifest, projectPath, rel).state === 'proven';
+
+  try {
+    writeFileSync(abs, out.join('\n'), 'utf-8');
+  } catch (e) {
+    return { state: 'error', replaced: 0, kept, recorder: null, error: e.message };
+  }
+  if (wasProven) {
+    recorder = newRecorder();
+    recordFile(recorder, projectPath, rel, RECORD_KINDS.GIT_HOOK);
+  }
+  return { state: 'migrated', replaced, kept, recorder };
+}

package/src/utils/locale.js

@@ -32,6 +32,24 @@ export function displayLanguageToLocale(displayLanguage) {
   return LOCALE_MAP[displayLanguage.toLowerCase()] || 'en';
 }
 
+/**
+ * Normalise a requested display language and say whether it is supported.
+ *
+ * `uds init --locale zh-CN` used to install English and exit 0: the value was compared case-sensitively
+ * further down, so the upper-case spelling silently missed every Chinese branch. An unsupported value such
+ * as `fr` did the same — English, exit 0, nothing said. The caller still falls back to English for an
+ * unsupported value, but now it can say so.
+ * @param {string|undefined|null} requested - what the user, install.yaml or the environment asked for
+ * @returns {{ displayLanguage: string|undefined|null, supported: boolean }}
+ */
+export function normalizeRequestedLocale(requested) {
+  if (typeof requested !== 'string' || requested.trim() === '') {
+    return { displayLanguage: requested, supported: true };
+  }
+  const displayLanguage = requested.trim().toLowerCase();
+  return { displayLanguage, supported: Object.prototype.hasOwnProperty.call(LOCALE_MAP, displayLanguage) };
+}
+
 /**
  * Check if a locale requires localized skill installation.
  * English locale uses the default source, no localization needed.
@@ -67,6 +85,7 @@ export function detectLocaleFromStandards(projectPath) {
 
 export default {
   displayLanguageToLocale,
+  normalizeRequestedLocale,
   isLocalizedLocale,
   detectLocaleFromStandards,
   LOCALE_MAP