universal-dev-standards 6.14.1 → 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.
- package/bin/uds.js +2 -2
- package/bundled/ai/standards/developer-memory.ai.yaml +2 -2
- package/bundled/ai/standards/full-coverage-testing.ai.yaml +6 -4
- package/bundled/ai/standards/project-context-memory.ai.yaml +2 -2
- package/bundled/core/developer-memory.md +1 -1
- package/bundled/core/full-coverage-testing.md +4 -2
- package/bundled/core/open-work-tracking.md +13 -0
- package/bundled/core/project-context-memory.md +1 -1
- package/bundled/locales/COVERAGE.md +5 -4
- package/bundled/locales/zh-CN/CHANGELOG.md +49 -4
- package/bundled/locales/zh-CN/README.md +2 -2
- package/bundled/locales/zh-CN/SECURITY.md +1 -0
- package/bundled/locales/zh-CN/core/full-coverage-testing.md +5 -3
- package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +4 -4
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -0
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +8 -3
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +5 -4
- package/bundled/locales/zh-CN/skills/README.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +1 -1
- package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +7 -7
- package/bundled/locales/zh-CN/skills/open-work-assistant/SKILL.md +133 -0
- package/bundled/locales/zh-TW/CHANGELOG.md +49 -4
- package/bundled/locales/zh-TW/README.md +2 -2
- package/bundled/locales/zh-TW/SECURITY.md +1 -0
- package/bundled/locales/zh-TW/core/developer-memory.md +3 -3
- package/bundled/locales/zh-TW/core/full-coverage-testing.md +5 -3
- package/bundled/locales/zh-TW/core/open-work-tracking.md +13 -2
- package/bundled/locales/zh-TW/core/project-context-memory.md +3 -3
- package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +4 -4
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -0
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +8 -3
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +5 -4
- package/bundled/locales/zh-TW/skills/README.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +7 -7
- package/bundled/locales/zh-TW/skills/open-work-assistant/SKILL.md +133 -0
- package/bundled/skills/README.md +2 -1
- package/bundled/skills/dev-workflow-guide/SKILL.md +4 -4
- package/bundled/skills/open-work-assistant/SKILL.md +127 -0
- package/bundled/templates/gates/check-anti-fake-tests.mjs +183 -23
- package/bundled/templates/gates/check-stubs.mjs +85 -16
- package/package.json +2 -2
- package/src/commands/audit.js +4 -1
- package/src/commands/check.js +55 -6
- package/src/commands/config.js +2 -3
- package/src/commands/init.js +10 -3
- package/src/commands/update.js +239 -43
- package/src/i18n/messages.js +87 -0
- package/src/installers/hooks-installer.js +32 -5
- package/src/installers/skills-installer.js +45 -0
- package/src/reconciler/backup-locations.js +3 -2
- package/src/reconciler/backup-manager.js +14 -11
- package/src/reconciler/plan-executor.js +51 -7
- package/src/utils/copier.js +13 -8
- package/src/utils/flush-and-exit.js +37 -0
- package/src/utils/group-errors.js +65 -0
- package/src/utils/integration-generator.js +14 -5
- package/src/utils/skill-hash-ownership.js +33 -0
- package/src/utils/skill-link-rewriter.js +184 -0
- package/src/utils/skills-installer.js +115 -11
- package/src/utils/transient-fs.js +168 -14
- package/standards-registry.json +10 -19
- 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 =
|
|
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 =
|
|
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
|
-
|
|
420
|
-
|
|
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,
|
|
424
|
-
files.push({ name, content: readFileSync(
|
|
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
|
|
709
|
-
|
|
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(
|
|
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
|
*
|