universal-dev-standards 6.14.1-beta.2 → 6.15.0-beta.1

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 (63) hide show
  1. package/bin/uds.js +2 -2
  2. package/bundled/ai/standards/developer-memory.ai.yaml +2 -2
  3. package/bundled/ai/standards/full-coverage-testing.ai.yaml +6 -4
  4. package/bundled/ai/standards/project-context-memory.ai.yaml +2 -2
  5. package/bundled/core/developer-memory.md +1 -1
  6. package/bundled/core/full-coverage-testing.md +4 -2
  7. package/bundled/core/open-work-tracking.md +13 -0
  8. package/bundled/core/project-context-memory.md +1 -1
  9. package/bundled/locales/COVERAGE.md +5 -4
  10. package/bundled/locales/zh-CN/CHANGELOG.md +53 -4
  11. package/bundled/locales/zh-CN/README.md +2 -2
  12. package/bundled/locales/zh-CN/SECURITY.md +3 -3
  13. package/bundled/locales/zh-CN/core/full-coverage-testing.md +5 -3
  14. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +4 -4
  15. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -0
  16. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +8 -3
  17. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +5 -4
  18. package/bundled/locales/zh-CN/skills/README.md +2 -1
  19. package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +1 -1
  20. package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +7 -7
  21. package/bundled/locales/zh-CN/skills/open-work-assistant/SKILL.md +133 -0
  22. package/bundled/locales/zh-TW/CHANGELOG.md +53 -4
  23. package/bundled/locales/zh-TW/README.md +2 -2
  24. package/bundled/locales/zh-TW/SECURITY.md +3 -3
  25. package/bundled/locales/zh-TW/core/developer-memory.md +3 -3
  26. package/bundled/locales/zh-TW/core/full-coverage-testing.md +5 -3
  27. package/bundled/locales/zh-TW/core/open-work-tracking.md +13 -2
  28. package/bundled/locales/zh-TW/core/project-context-memory.md +3 -3
  29. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +4 -4
  30. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -0
  31. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +8 -3
  32. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +5 -4
  33. package/bundled/locales/zh-TW/skills/README.md +2 -1
  34. package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +7 -7
  35. package/bundled/locales/zh-TW/skills/open-work-assistant/SKILL.md +133 -0
  36. package/bundled/skills/.claude-plugin/plugin.json +1 -1
  37. package/bundled/skills/README.md +2 -1
  38. package/bundled/skills/dev-workflow-guide/SKILL.md +4 -4
  39. package/bundled/skills/open-work-assistant/SKILL.md +127 -0
  40. package/bundled/templates/gates/check-anti-fake-tests.mjs +183 -23
  41. package/bundled/templates/gates/check-stubs.mjs +85 -16
  42. package/package.json +2 -2
  43. package/src/commands/audit.js +4 -1
  44. package/src/commands/check.js +55 -6
  45. package/src/commands/config.js +2 -3
  46. package/src/commands/init.js +10 -3
  47. package/src/commands/update.js +239 -43
  48. package/src/i18n/messages.js +87 -0
  49. package/src/installers/hooks-installer.js +32 -5
  50. package/src/installers/skills-installer.js +45 -0
  51. package/src/reconciler/backup-locations.js +3 -2
  52. package/src/reconciler/backup-manager.js +14 -11
  53. package/src/reconciler/plan-executor.js +51 -7
  54. package/src/utils/copier.js +13 -8
  55. package/src/utils/flush-and-exit.js +37 -0
  56. package/src/utils/group-errors.js +65 -0
  57. package/src/utils/integration-generator.js +14 -5
  58. package/src/utils/skill-hash-ownership.js +33 -0
  59. package/src/utils/skill-link-rewriter.js +184 -0
  60. package/src/utils/skills-installer.js +115 -11
  61. package/src/utils/transient-fs.js +168 -14
  62. package/standards-registry.json +10 -19
  63. package/bundled/ai/standards/open-work-tracking.ai.yaml +0 -466
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Print a list of per-file errors with each cause once (board #81).
3
+ *
4
+ * The installers report a failure as one string, `<file>: <cause>`. When one thing is wrong for every file - the folder
5
+ * `.standards/` cannot be created, so every standard fails with the same two-hundred-word message - the list repeated that
6
+ * message 50 and more times (about 64 KB), and the one line that said what was different (the locale pack, the
7
+ * integration file) was lost among them.
8
+ *
9
+ * Errors are grouped by their cause, the text after the first `": "`. Only a cause that is word for word the same is
10
+ * merged: a message that names the file it was about (`Could not copy "a" to "b"`) differs for each file and stays a
11
+ * line of its own, so nothing is hidden that was told apart before. A string without `": "` is never merged.
12
+ */
13
+
14
+ /** How many file names a merged group shows. The count is always the full count. */
15
+ export const SAMPLE_NAMES = 3;
16
+
17
+ /**
18
+ * @param {Array<string>} errors - `<file>: <cause>` strings, in the order they happened
19
+ * @returns {Array<{cause: string, labels: string[], texts: string[]}>} groups in the order of their first member; a group
20
+ * with `labels.length === 1` is a single error and `texts[0]` is the string it came as
21
+ */
22
+ export function groupErrorsByCause(errors) {
23
+ const groups = new Map();
24
+ errors.forEach((error, index) => {
25
+ const text = String(error);
26
+ const at = text.indexOf(': ');
27
+ const label = at > 0 ? text.slice(0, at) : null;
28
+ const cause = at > 0 ? text.slice(at + 2) : text;
29
+ const key = label === null ? `\u0000unlabelled-${index}` : cause;
30
+ if (!groups.has(key)) groups.set(key, { cause, labels: [], texts: [] });
31
+ const group = groups.get(key);
32
+ group.labels.push(label ?? text);
33
+ group.texts.push(text);
34
+ });
35
+ return [...groups.values()];
36
+ }
37
+
38
+ /** Fill `{name}` placeholders in one pass (a value that contains `{x}` is not filled twice). */
39
+ function fill(template, values) {
40
+ return template.replace(/\{(\w+)\}/g, (whole, key) => (Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : whole));
41
+ }
42
+
43
+ /**
44
+ * The lines to print: a single error as it came, a merged group as its cause followed by how many files it hit.
45
+ * @param {Array<string>} errors
46
+ * @param {{installErrorsAffectedAll?: string, installErrorsAffectedFirst?: string}} [words] - the two sentences, in the CLI's language (English when missing)
47
+ * @param {string} [indent] - put in front of every line
48
+ * @returns {string[]}
49
+ */
50
+ export function formatGroupedErrors(errors, words, indent = ' ') {
51
+ const lines = [];
52
+ for (const group of groupErrorsByCause(errors)) {
53
+ if (group.labels.length === 1) {
54
+ lines.push(`${indent}${group.texts[0]}`);
55
+ continue;
56
+ }
57
+ const shown = group.labels.slice(0, SAMPLE_NAMES);
58
+ const template = shown.length === group.labels.length
59
+ ? (words?.installErrorsAffectedAll || '-> {count} files affected: {names}')
60
+ : (words?.installErrorsAffectedFirst || '-> {count} files affected, the first {shown}: {names}');
61
+ lines.push(`${indent}${group.cause}`);
62
+ lines.push(`${indent} ${fill(template, { count: group.labels.length, shown: shown.length, names: shown.join(', ') })}`);
63
+ }
64
+ return lines;
65
+ }
@@ -2508,6 +2508,17 @@ function byLanguage(language, en, zhTw, zhCn) {
2508
2508
  return language === 'zh-cn' ? zhCn : zhTw;
2509
2509
  }
2510
2510
 
2511
+ /**
2512
+ * Is this manifest `standards` entry an option file? Options are paths, and a path reaches here in two spellings:
2513
+ * `ai/options/<group>/<name>.ai.yaml` and `options/<group>/<name>.md`. Testing for `/options/` alone caught the first
2514
+ * and missed the second, so a human-format option was listed as `.standards/<name>.md`, a file that does not exist.
2515
+ * @param {string} entry
2516
+ * @returns {boolean}
2517
+ */
2518
+ function isOptionEntry(entry) {
2519
+ return /(^|[\\/])options[\\/]/.test(String(entry));
2520
+ }
2521
+
2511
2522
  /**
2512
2523
  * Generate minimal standards reference for minimal content mode
2513
2524
  * @param {string[]} installedStandards - List of installed standard file paths
@@ -2538,7 +2549,7 @@ export function generateMinimalStandardsReference(
2538
2549
  // real adopter's AGENTS.md, directly under a line telling the agent it must
2539
2550
  // read them.
2540
2551
  for (const standardPath of installedStandards) {
2541
- const isOption = standardPath.includes('/options/') || standardPath.includes('\\options\\');
2552
+ const isOption = isOptionEntry(standardPath);
2542
2553
  const filename = resolveStandardFilename(standardPath, standardsFormat);
2543
2554
 
2544
2555
  // An entry we cannot resolve is not written out as if it were a path. A
@@ -3430,9 +3441,7 @@ export function generateStandardsIndex(installedStandards, format, language = 'z
3430
3441
  const resolvable = installedStandards.filter((e) => resolveStandardFilename(e, standardsFormat));
3431
3442
  const unresolved = installedStandards.filter((e) => !resolveStandardFilename(e, standardsFormat));
3432
3443
  const total = resolvable.length;
3433
- const optionCount = resolvable.filter(
3434
- (p) => p.includes('/options/') || p.includes('\\options\\')
3435
- ).length;
3444
+ const optionCount = resolvable.filter(isOptionEntry).length;
3436
3445
  const coreCount = total - optionCount;
3437
3446
 
3438
3447
  const heading = '## Installed Standards Index';
@@ -3979,7 +3988,7 @@ export function generateAgentsMdSummary(config = {}) {
3979
3988
  for (const entry of installedStandards) {
3980
3989
  const filename = resolveStandardFilename(entry, format);
3981
3990
  if (!filename?.endsWith(suffix)) continue;
3982
- const isOption = entry.includes('/options/') || entry.includes('\\options\\');
3991
+ const isOption = isOptionEntry(entry);
3983
3992
  const dir = isOption ? '.standards/options' : '.standards';
3984
3993
  blockLines.push(`- \`${dir}/${filename}\` — ${filename.replace(suffix, '')}`);
3985
3994
  }
@@ -50,6 +50,39 @@ export function pruneForeignSkillHashes(manifest, shipped = new Set(getAvailable
50
50
  return dropped.sort();
51
51
  }
52
52
 
53
+ /**
54
+ * Record what a skills install just wrote, REPLACING the old records of the skills it rewrote.
55
+ *
56
+ * The installer deletes the top-level files a skill no longer ships (`installSingleSkill`, XSPEC-382 R7),
57
+ * and `result.allFileHashes` describes the folder as it is afterwards. Callers used to `Object.assign` that
58
+ * onto `manifest.skillHashes`, which only ever adds and overwrites: the records of the files just deleted
59
+ * stayed, and `uds check` called each of them missing — 15 of them on VibeOps (140 recorded, 125 on disk),
60
+ * and the only thing that cleared them was a hand edit of the manifest. (dev-platform #46)
61
+ *
62
+ * Scope is exactly the skills the installer reports as installed (`<agent>/<level>/<skill>/`). A skill the
63
+ * run did not touch, or one whose install failed, keeps its records: nothing was rewritten there, so the old
64
+ * records still describe the disk.
65
+ *
66
+ * @param {Object} manifest - Project manifest; `skillHashes` is created when absent. Mutated.
67
+ * @param {{ allFileHashes?: Object, installations?: Array<{agent?: string, level?: string, installed?: string[]}> }} result
68
+ * What `installSkillsToMultipleAgents` returned
69
+ */
70
+ export function replaceSkillHashesForInstalled(manifest, result) {
71
+ if (!result?.allFileHashes) return;
72
+ if (!manifest.skillHashes) manifest.skillHashes = {};
73
+ const hashes = manifest.skillHashes;
74
+ for (const inst of result.installations || []) {
75
+ if (!inst?.agent || !inst?.level) continue;
76
+ for (const name of inst.installed || []) {
77
+ const prefix = `${inst.agent}/${inst.level}/${name}/`;
78
+ for (const key of Object.keys(hashes)) {
79
+ if (key.startsWith(prefix)) delete hashes[key];
80
+ }
81
+ }
82
+ }
83
+ Object.assign(hashes, result.allFileHashes);
84
+ }
85
+
53
86
  /**
54
87
  * Which skill files `uds check` has to report: the missing and the changed ones, as one list.
55
88
  *
@@ -0,0 +1,184 @@
1
+ /**
2
+ * Rewrite the relative links of a skill file that point at places which do not exist once the skill is installed
3
+ * (dev-platform #61, decision 214A; #47 fixed one skill by hand). Slash command files go through the same function
4
+ * (dev-platform #62): the only thing that differs is the question "does the install put a file there?", which a
5
+ * caller answers with `ctx.isInstalledLink` instead of the skill-folder pair (`skillName` + `isInstalledSkillFile`).
6
+ *
7
+ * A skill source file links to its neighbours the way the UDS source repo is laid out: `../../core/x.md`,
8
+ * `../../../../skills/y/SKILL.md`, `../../locales/zh-TW/...`. Installed, the skill sits in
9
+ * `<project>/<agent folder>/skills/<name>/` and the repo around it is gone, so most of those links open nothing.
10
+ * This module decides, link by link, whether the link still lands on a file that the same install puts on disk.
11
+ * If it does, the link is kept as written. If it does not, it becomes the GitHub address of the file the author
12
+ * meant (`https://github.com/AsiaOstrich/universal-dev-standards/blob/main/<repo path>`), anchor kept.
13
+ *
14
+ * The source files in the UDS repo are not touched; this runs where the installer writes the file
15
+ * (`resolveSkillFiles`), so installing, planning and `uds check` all see the same content.
16
+ *
17
+ * The module has no file access on purpose: what the install will contain is passed in as a question
18
+ * (`isInstalledSkillFile`), so the answer is the installer's and not a second copy of its rules here.
19
+ *
20
+ * Scope and limits:
21
+ * - Markdown inline links and images, `[label]: target` definitions. Links inside fenced code blocks and inline
22
+ * code spans are examples, not links, and are left alone.
23
+ * - Absolute URLs, `mailto:`, `//host`, `/abs/path` and bare `#anchor` links are not relative links.
24
+ * - A link whose target leaves the repo root (cannot be mapped to a repo path) is left unchanged and reported.
25
+ *
26
+ * @module utils/skill-link-rewriter
27
+ */
28
+
29
+ import { posix, join } from 'path';
30
+ import { existsSync } from 'fs';
31
+
32
+ export const UDS_REPO_BLOB_BASE = 'https://github.com/AsiaOstrich/universal-dev-standards/blob/main/';
33
+ export const UDS_REPO_TREE_BASE = 'https://github.com/AsiaOstrich/universal-dev-standards/tree/main/';
34
+
35
+ /** Top-level folders of the UDS repo that the npm package carries (cli/scripts/prepack.mjs): absence there is real. */
36
+ const PACKAGED_DIRS = ['core', 'ai', 'locales', 'skills', 'templates', 'extensions'];
37
+
38
+ /**
39
+ * The "does this repo path exist?" question `rewriteOutsideLinks` asks, answered from one or more folders that hold
40
+ * a copy of the UDS repo layout (the npm package's `bundled/`, a checkout). One definition, used by the installer and
41
+ * by the self-adoption generator, so the two cannot answer differently.
42
+ *
43
+ * `true` when any root has the path. When none has it: `false` for a folder the package carries (the link is
44
+ * dead in the source), `undefined` for the rest (`docs/`, `.standards/`, `LICENSE`: not part of the package, so
45
+ * "not found" says nothing about whether the repo has it).
46
+ *
47
+ * @param {string[]} roots
48
+ * @returns {(repoPath: string) => (boolean|undefined)}
49
+ */
50
+ export function createRepoPathProbe(roots) {
51
+ return (repoPath) => {
52
+ const parts = repoPath.split('/');
53
+ if (roots.some((root) => existsSync(join(root, ...parts)))) return true;
54
+ return PACKAGED_DIRS.includes(parts[0]) ? false : undefined;
55
+ };
56
+ }
57
+
58
+ /** A link target that is not a relative file reference (URL with scheme, `//host`, absolute path, bare anchor). */
59
+ export function isNotRelativeTarget(target) {
60
+ return target === '' || target.startsWith('#') || target.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(target);
61
+ }
62
+
63
+ // Alternatives are tried left to right at each position, so code is consumed before a link inside it can match.
64
+ // A fence that is never closed is NOT treated as code to the end of the file (CommonMark would): in the shipped
65
+ // skills that is always a nesting slip of the author's (a ```markdown block holding ```bash blocks), and the
66
+ // reference list after it is meant as links.
67
+ const FENCED_CODE = '^[ \\t]*(`{3,}|~{3,})[^\\n]*\\n[\\s\\S]*?^[ \\t]*\\2[`~]*[ \\t]*$';
68
+ const INLINE_CODE = '(`+)[^`\\n]*?\\4(?!`)';
69
+ const LABEL = '\\[(?:[^\\[\\]]|\\[[^\\]]*\\])*\\]';
70
+ const INLINE_LINK = `(!?${LABEL})\\(\\s*(<[^>\\n]*>|[^)\\s]+)((?:\\s+(?:"[^"\\n]*"|'[^'\\n]*'))?)\\s*\\)`;
71
+ const DEFINITION = '^([ ]{0,3}\\[[^\\]\\n]+\\]:[ \\t]*)(<[^>\\n]*>|\\S+)';
72
+
73
+ function buildScanner() {
74
+ return new RegExp(`(${FENCED_CODE})|(${INLINE_CODE})|${INLINE_LINK}|${DEFINITION}`, 'gm');
75
+ }
76
+
77
+ /**
78
+ * @typedef {Object} RewriteReport
79
+ * @property {string} text - the file content after rewriting
80
+ * @property {Array<{from: string, to: string, repoPath: string}>} rewritten - links turned into GitHub addresses
81
+ * @property {string[]} kept - relative links that still land on an installed file, left as written
82
+ * @property {string[]} unresolved - relative links that leave the repo root; left unchanged
83
+ * @property {string[]} leftAlone - relative links that do not land on an installed file but name nothing real in the
84
+ * UDS repo either (placeholders of a template, links that were already dead in the source); left unchanged
85
+ */
86
+
87
+ /**
88
+ * @param {string} text - markdown content of one file of the skill
89
+ * @param {Object} ctx
90
+ * @param {string} [ctx.skillName] - the skill the file belongs to (its installed folder name). Required unless
91
+ * `isInstalledLink` is given.
92
+ * @param {string} ctx.sourcePath - repo path (posix, relative to the repo root) of the file the content came from,
93
+ * e.g. `skills/commit-standards/SKILL.md` or `locales/zh-TW/skills/commit-standards/SKILL.md`. Relative links in
94
+ * the file were written against this location.
95
+ * @param {(skill: string, fileName: string) => boolean} [ctx.isInstalledSkillFile] - whether the install puts
96
+ * `<skills folder>/<skill>/<fileName>` on disk
97
+ * @param {(installedPath: string) => boolean} [ctx.isInstalledLink] - replaces the two options above: given the link
98
+ * path (anchor removed, normalized, relative to the folder the installed file sits in), whether the install puts a
99
+ * file there. Slash commands use it: they are installed flat, `<commands folder>/<name>.md`, with no skill folder.
100
+ * @param {(repoPath: string) => (boolean|undefined)} [ctx.repoPathExists] - whether a repo path exists in the UDS
101
+ * source this install reads from; `undefined` when that cannot be told (the path is not part of the package)
102
+ * @returns {RewriteReport}
103
+ */
104
+ export function rewriteOutsideLinks(text, ctx) {
105
+ const rewritten = [];
106
+ const kept = [];
107
+ const unresolved = [];
108
+ const leftAlone = [];
109
+
110
+ const decide = (rawTarget) => {
111
+ // `<...>` is the markdown way to write a target that has spaces in it.
112
+ const bracketed = rawTarget.startsWith('<') && rawTarget.endsWith('>');
113
+ const target = bracketed ? rawTarget.slice(1, -1) : rawTarget;
114
+ const hashAt = target.indexOf('#');
115
+ const pathPart = hashAt === -1 ? target : target.slice(0, hashAt);
116
+ const anchor = hashAt === -1 ? '' : target.slice(hashAt);
117
+ if (isNotRelativeTarget(target) || pathPart === '') return null;
118
+
119
+ // 1. Does the link still work from the installed folder? For a skill it is resolved against the skills folder,
120
+ // where the skill is `<skillName>/`, and works only when it lands on `<skill>/<file>` that this install writes.
121
+ // A caller whose files are not in a skill folder (slash commands) answers the question itself.
122
+ if (ctx.isInstalledLink) {
123
+ if (ctx.isInstalledLink(posix.normalize(pathPart))) { // wire:command-link-keep-if-installed
124
+ kept.push(rawTarget);
125
+ return null;
126
+ }
127
+ } else {
128
+ const installed = posix.normalize(posix.join(ctx.skillName, pathPart));
129
+ const parts = installed.split('/');
130
+ if (!installed.startsWith('..') && parts.length === 2 && parts[1] !== '' && ctx.isInstalledSkillFile(parts[0], parts[1])) { // wire:skill-link-keep-if-installed
131
+ kept.push(rawTarget);
132
+ return null;
133
+ }
134
+ }
135
+
136
+ // 2. It does not. The author wrote it against the source layout; turn that location into a GitHub address.
137
+ const sourceDir = posix.dirname(ctx.sourcePath);
138
+ const repoPath = posix.normalize(posix.join(sourceDir, pathPart));
139
+ if (repoPath.startsWith('..') || repoPath === '.' || repoPath.startsWith('/')) {
140
+ unresolved.push(rawTarget);
141
+ return null;
142
+ }
143
+ // Only a link that points at something real in the UDS repo gets an address.
144
+ // - A link that stays inside the skill's own folder (`docs/`, `CONTRIBUTING.md`, in the README and documentation
145
+ // templates of documentation-guide) is usually a placeholder meant for the adopter's own project: it names
146
+ // nothing in UDS, and a GitHub address for it would be a new dead link. It is rewritten only when the file
147
+ // is really there in the source (a subfolder the installer does not copy, for example).
148
+ // - A link that leaves the skill's folder is rewritten unless UDS can see that the target is not there.
149
+ // "Cannot see" (undefined) is not "not there": `docs/` and `.standards/` are not in the npm package.
150
+ const exists = ctx.repoPathExists ? ctx.repoPathExists(repoPath.replace(/\/+$/, '')) : undefined;
151
+ const staysInsideSkill = repoPath.startsWith(`${sourceDir}/`);
152
+ if (staysInsideSkill ? exists !== true : exists === false) {
153
+ leftAlone.push(rawTarget);
154
+ return null;
155
+ }
156
+ const base = repoPath.endsWith('/') ? UDS_REPO_TREE_BASE : UDS_REPO_BLOB_BASE;
157
+ const url = `${base}${repoPath}${anchor}`;
158
+ rewritten.push({ from: rawTarget, to: url, repoPath });
159
+ return bracketed ? `<${url}>` : url;
160
+ };
161
+
162
+ const scan = (source) => source.replace(buildScanner(), (...args) => {
163
+ const match = args[0];
164
+ // Capture groups: 1 fenced code (2 its fence), 3 inline code (4 its backticks), 5/6/7 inline link, 8/9 definition.
165
+ if (args[1] !== undefined || args[3] !== undefined) return match;
166
+ if (args[5] !== undefined) {
167
+ // The label can hold a link of its own (a badge image inside a link): look inside it too.
168
+ const bang = args[5].startsWith('!') ? '!' : '';
169
+ const inner = args[5].slice(bang.length + 1, -1);
170
+ const scannedInner = scan(inner);
171
+ const replacement = decide(args[6]);
172
+ if (replacement === null && scannedInner === inner) return match;
173
+ return `${bang}[${scannedInner}](${replacement === null ? args[6] : replacement}${args[7] || ''})`;
174
+ }
175
+ if (args[8] !== undefined) {
176
+ const replacement = decide(args[9]);
177
+ return replacement === null ? match : `${args[8]}${replacement}`;
178
+ }
179
+ return match;
180
+ });
181
+ const out = scan(text);
182
+
183
+ return { text: out, rewritten, kept, unresolved, leftAlone };
184
+ }
@@ -24,6 +24,7 @@ import {
24
24
  import { computeDirectoryHashes, computeFileHash, normalizeLineEndings } from './hasher.js';
25
25
  import { isLocalizedLocale } from './locale.js';
26
26
  import { getSkillsSourceDir } from './skills-source.js';
27
+ import { rewriteOutsideLinks, createRepoPathProbe } from './skill-link-rewriter.js';
27
28
  import { t } from '../i18n/messages.js';
28
29
 
29
30
  // Get the CLI package root directory
@@ -406,22 +407,27 @@ export function resolveSkillFiles(skillName, locale = 'en') {
406
407
  // Taking the union — locale file where it exists, English where it does not —
407
408
  // is also what makes the content comparison usable: without it those skills
408
409
  // would report as changed on every upgrade forever. (XSPEC-382 R7)
409
- const names = new Map(); // fileName -> absolute source path
410
- const collect = (dir) => {
410
+ const names = new Map(); // fileName -> { path: absolute source path, repoPath: where that file sits in the UDS repo }
411
+ const collect = (dir, repoDir) => {
411
412
  if (!existsSync(dir)) return;
412
413
  for (const fileName of readdirSync(dir)) {
413
414
  const sourcePath = join(dir, fileName);
414
415
  // Subdirectories are skipped — matching what the installer has always done.
415
416
  if (statSync(sourcePath).isDirectory()) continue;
416
- if (!names.has(fileName)) names.set(fileName, sourcePath);
417
+ if (!names.has(fileName)) names.set(fileName, { path: sourcePath, repoPath: `${repoDir}/${fileName}` });
417
418
  }
418
419
  };
419
- collect(sourceDir); // locale first, so it wins
420
- if (sourceDir !== enSourceDir) collect(enSourceDir);
420
+ // The repo location is what the relative links inside each file were written against (see rewriteOutsideLinks).
421
+ const enRepoDir = `skills/${skillName}`;
422
+ const localeRepoDir = sourceDir !== enSourceDir
423
+ ? `locales/${basename(dirname(dirname(sourceDir)))}/skills/${skillName}`
424
+ : null;
425
+ collect(sourceDir, localeRepoDir || enRepoDir); // locale first, so it wins
426
+ if (sourceDir !== enSourceDir) collect(enSourceDir, enRepoDir);
421
427
 
422
428
  const files = [];
423
- for (const [name, sourcePath] of names) {
424
- files.push({ name, content: readFileSync(sourcePath, 'utf-8') });
429
+ for (const [name, source] of names) {
430
+ files.push({ name, content: readFileSync(source.path, 'utf-8'), repoPath: source.repoPath });
425
431
  }
426
432
 
427
433
  if (needsFrontmatterMerge) {
@@ -432,9 +438,68 @@ export function resolveSkillFiles(skillName, locale = 'en') {
432
438
  }
433
439
  }
434
440
 
441
+ // Links that point out of the skill folder at places this install does not create (the UDS repo's `core/`,
442
+ // `locales/`, another language's copy of the skill ...) become GitHub addresses; links that still land on a file
443
+ // this install writes stay as they are. Done here, on the final content, so the installer writes it, the planner
444
+ // hashes it and `uds check` compares against it from the one answer. (dev-platform #61)
445
+ const siblingFiles = new Map(); // skill -> Set of file names its install writes
446
+ const isInstalledSkillFile = (skill, fileName) => {
447
+ if (!siblingFiles.has(skill)) {
448
+ siblingFiles.set(skill, skill === skillName
449
+ ? new Set(files.map((f) => f.name))
450
+ : new Set(listSkillFileNames(skill, locale)));
451
+ }
452
+ return siblingFiles.get(skill).has(fileName);
453
+ };
454
+ const linkRewrites = [];
455
+ for (const file of files) {
456
+ if (!file.name.endsWith('.md')) continue;
457
+ const report = rewriteOutsideLinks(file.content, { // wire:skill-links-rewritten
458
+ skillName, sourcePath: file.repoPath, isInstalledSkillFile, repoPathExists: udsRepoPathExists
459
+ });
460
+ file.content = report.text;
461
+ linkRewrites.push({
462
+ file: file.name, rewritten: report.rewritten, kept: report.kept,
463
+ unresolved: report.unresolved, leftAlone: report.leftAlone
464
+ });
465
+ }
466
+
435
467
  // Sorted so a hash over this list depends on content, not on directory order.
436
468
  files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
437
- return { files, fallbackToEn, error: null };
469
+ return { files: files.map(({ name, content }) => ({ name, content })), fallbackToEn, error: null, linkRewrites };
470
+ }
471
+
472
+ /**
473
+ * Whether a repo path (relative to the UDS repo root, posix) exists in the copy of UDS this CLI reads skills from:
474
+ * the npm package's `bundled/` folder or, in a checkout, the repo. Three-valued, see `createRepoPathProbe`.
475
+ */
476
+ const udsRepoPathExists = createRepoPathProbe([BUNDLED_DIR, join(CLI_ROOT, '..')]);
477
+
478
+ /**
479
+ * The file names an install of `skillName` writes into its folder (locale file where there is one, English
480
+ * otherwise; top-level files only). Empty when UDS does not ship that skill. Answers "will this sibling link
481
+ * still land on a file?" for `resolveSkillFiles`, from the same source selection the install itself uses.
482
+ *
483
+ * @param {string} skillName
484
+ * @param {string} locale
485
+ * @returns {string[]}
486
+ */
487
+ function listSkillFileNames(skillName, locale) {
488
+ const enDir = join(SKILLS_LOCAL_DIR, skillName);
489
+ if (!existsSync(join(enDir, 'SKILL.md'))) return []; // not a skill UDS installs (a folder like _shared, workflows)
490
+ const names = new Set();
491
+ const addFrom = (dir) => {
492
+ if (!existsSync(dir)) return;
493
+ for (const fileName of readdirSync(dir)) {
494
+ if (!statSync(join(dir, fileName)).isDirectory()) names.add(fileName);
495
+ }
496
+ };
497
+ if (isLocalizedLocale(locale)) {
498
+ const packDir = findLocalePackSkillsDir(locale);
499
+ if (packDir) addFrom(join(packDir, skillName));
500
+ }
501
+ addFrom(enDir);
502
+ return [...names];
438
503
  }
439
504
 
440
505
  /**
@@ -703,10 +768,17 @@ export async function installCommandsForAgent(agent, level = 'project', commandN
703
768
  */
704
769
  export function resolveCommandContent(cmdName, agent, locale = 'en') {
705
770
  let sourcePath = join(COMMANDS_LOCAL_DIR, `${cmdName}.md`);
771
+ // Where the source file sits in the UDS repo: the relative links inside it were written against that place.
772
+ let repoPath = `skills/commands/${cmdName}.md`;
706
773
 
707
774
  if (isLocalizedLocale(locale)) {
708
- const localizedPath = join(getLocalizedCommandsSourceDir(locale), `${cmdName}.md`);
709
- if (existsSync(localizedPath)) sourcePath = localizedPath;
775
+ const localizedDir = getLocalizedCommandsSourceDir(locale);
776
+ const localizedPath = join(localizedDir, `${cmdName}.md`);
777
+ if (existsSync(localizedPath)) {
778
+ sourcePath = localizedPath;
779
+ // .../locales/<locale>/skills/commands -> <locale>
780
+ repoPath = `locales/${basename(dirname(dirname(localizedDir)))}/skills/commands/${cmdName}.md`;
781
+ }
710
782
  // else: fall back to English source
711
783
  }
712
784
 
@@ -715,8 +787,12 @@ export function resolveCommandContent(cmdName, agent, locale = 'en') {
715
787
  }
716
788
 
717
789
  try {
790
+ // Links that point out of the install become GitHub addresses BEFORE the per-agent conversion, so the Gemini
791
+ // TOML wraps the finished text and every agent gets the same links. Done here, in the one function the
792
+ // installer writes from, the planner hashes and `uds check` compares against. (dev-platform #62)
793
+ const rewritten = rewriteCommandLinks(readFileSync(sourcePath, 'utf-8'), agent, repoPath); // wire:command-links-rewritten
718
794
  return {
719
- content: transformCommandForAgent(readFileSync(sourcePath, 'utf-8'), cmdName, agent),
795
+ content: transformCommandForAgent(rewritten, cmdName, agent),
720
796
  error: null
721
797
  };
722
798
  } catch (error) {
@@ -724,6 +800,34 @@ export function resolveCommandContent(cmdName, agent, locale = 'en') {
724
800
  }
725
801
  }
726
802
 
803
+ /**
804
+ * The commands this install puts in a commands folder, by file name as installed. Commands are installed flat
805
+ * (`<commands folder>/<name><ext>`), every available command for every agent (the English list; a locale without a
806
+ * translation of one falls back to English for that file). Gemini CLI's files are `.toml`, so no `.md` name is among them.
807
+ *
808
+ * @param {string} agent
809
+ * @returns {Set<string>}
810
+ */
811
+ function installedCommandFileNames(agent) {
812
+ const ext = getCommandFileExtension(agent);
813
+ return new Set(getAvailableCommandNames().map((name) => `${name}${ext}`));
814
+ }
815
+
816
+ /**
817
+ * `rewriteOutsideLinks` for one command file. A command sits in `<agent commands folder>/`, next to the other
818
+ * commands and nothing else (no `core/`, no skill folders; the skills folder is a different, optional install).
819
+ * A link to another command's `.md` file stays relative when this agent's files are `.md`; everything else that
820
+ * leaves the file becomes the GitHub address of what the author meant.
821
+ */
822
+ function rewriteCommandLinks(text, agent, repoPath) {
823
+ const installedNames = installedCommandFileNames(agent);
824
+ return rewriteOutsideLinks(text, {
825
+ sourcePath: repoPath,
826
+ isInstalledLink: (installedPath) => installedNames.has(installedPath), // flat folder: a bare file name only
827
+ repoPathExists: udsRepoPathExists
828
+ }).text;
829
+ }
830
+
727
831
  /**
728
832
  * Content hash of a resolved command.
729
833
  *