Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix(install): rewrite relative skill links for injected ecc namespace (#2399)

Gaurav Dubey0a926b45ba17
diff --git a/scripts/lib/install/apply.js b/scripts/lib/install/apply.js
index 6c4736858..6d5bb7171 100644
--- a/scripts/lib/install/apply.js
+++ b/scripts/lib/install/apply.js
@@ -5,6 +5,30 @@ const path = require('path');
const { writeInstallState } = require('../install-state');
const { filterMcpConfig, parseDisabledMcpServers } = require('../mcp-config');
+const { buildInstallIndex, isNamespacedSource, rewriteRelativeLinks } = require('./link-rewrite');
+
+function isMarkdownPath(filePath) {
+ return /\.(md|mdx|markdown)$/i.test(String(filePath || ''));
+}
+
+// Map every copy-file operation to { sourceRel, destRel } so relative links in
+// namespaced markdown can be rewritten to the file's actual installed location
+// (issue #2340). Returns null when the plan lacks the data needed to do so.
+function buildLinkIndexForPlan(plan) {
+ if (!plan || !plan.targetRoot || !Array.isArray(plan.operations)) {
+ return null;
+ }
+ const mappings = [];
+ for (const operation of plan.operations) {
+ if (operation.kind === 'copy-file' && operation.sourceRelativePath) {
+ mappings.push({
+ sourceRel: operation.sourceRelativePath,
+ destRel: path.relative(plan.targetRoot, operation.destinationPath),
+ });
+ }
+ }
+ return buildInstallIndex(mappings);
+}
function readJsonObject(filePath, label) {
let parsed;
@@ -118,6 +142,7 @@ function buildResolvedClaudeHooks(plan) {
function applyInstallPlan(plan) {
const resolvedClaudeHooksPlan = buildResolvedClaudeHooks(plan);
const disabledServers = parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS);
+ const linkIndex = buildLinkIndexForPlan(plan);
for (const operation of plan.operations) {
fs.mkdirSync(path.dirname(operation.destinationPath), { recursive: true });
@@ -149,6 +174,25 @@ function applyInstallPlan(plan) {
continue;
}
+ // Namespaced markdown (e.g. skills/<id> -> skills/ecc/<id>) needs its
+ // relative cross-directory links rewritten so they resolve after install
+ // (issue #2340). Files whose install path is unchanged (no namespace
+ // injected) and all non-markdown files stay on the byte-for-byte copy path.
+ if (
+ linkIndex
+ && operation.kind === 'copy-file'
+ && operation.sourceRelativePath
+ && isMarkdownPath(operation.destinationPath)
+ && isNamespacedSource(operation.sourceRelativePath, linkIndex)
+ ) {
+ const rewritten = rewriteRelativeLinks(
+ fs.readFileSync(operation.sourcePath, 'utf8'),
+ { sourceRel: operation.sourceRelativePath, index: linkIndex }
+ );
+ fs.writeFileSync(operation.destinationPath, rewritten, 'utf8');
+ continue;
+ }
+
fs.copyFileSync(operation.sourcePath, operation.destinationPath);
}
diff --git a/scripts/lib/install/link-rewrite.js b/scripts/lib/install/link-rewrite.js
new file mode 100644
index 000000000..53b1beb12
--- /dev/null
+++ b/scripts/lib/install/link-rewrite.js
@@ -0,0 +1,179 @@
+'use strict';
+
+const path = require('path');
+
+const posix = path.posix;
+
+// Matches inline markdown links and images: `](target)` / `](target "title")`.
+// We deliberately scope to the inline form because that is what skill/rule docs
+// use for cross-directory references. Reference-style and autolinks are left
+// untouched (they are rare in these files and carry higher false-positive risk).
+const INLINE_LINK_PATTERN = /(!?\]\()([^()\s]+)(\s+"[^"]*")?(\))/g;
+
+function toPosix(relativePath) {
+ return String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function stripTrailingSlash(value) {
+ return value.length > 1 ? value.replace(/\/+$/, '') : value;
+}
+
+// Build file + directory lookup maps from the plan's own file placements.
+// `fileMappings` is a list of { sourceRel, destRel } where both are paths
+// relative to the repo root and the install root respectively. The directory
+// map is derived by walking shared ancestors of each source/dest pair, which is
+// exact for prefix-insertion namespacing (e.g. `skills/x` -> `skills/ecc/x`):
+// the path suffix below the inserted segment is preserved, so ancestor `k`
+// of the source maps to the dest with the matching number of trailing
+// segments removed.
+function buildInstallIndex(fileMappings) {
+ const byFile = new Map();
+ const byDir = new Map();
+
+ for (const mapping of fileMappings || []) {
+ const sourceRel = toPosix(mapping.sourceRel);
+ const destRel = toPosix(mapping.destRel);
+ if (!sourceRel || !destRel) {
+ continue;
+ }
+
+ byFile.set(sourceRel, destRel);
+
+ const sourceParts = sourceRel.split('/');
+ const destParts = destRel.split('/');
+ // Map every source ancestor directory to its installed counterpart by
+ // removing the same count of trailing segments from the dest path.
+ for (let depth = 1; depth < sourceParts.length; depth += 1) {
+ const trailing = sourceParts.length - depth;
+ const destDepth = destParts.length - trailing;
+ if (destDepth < 1) {
+ continue;
+ }
+ const sourceDir = sourceParts.slice(0, depth).join('/');
+ const destDir = destParts.slice(0, destDepth).join('/');
+ // Only record real prefix-insertion mappings (suffix preserved). If a
+ // directory resolves to itself (no namespace change) we skip it so the
+ // rewriter leaves those links alone.
+ if (sourceDir !== destDir) {
+ byDir.set(sourceDir, destDir);
+ }
+ }
+ }
+
+ return { byFile, byDir };
+}
+
+function isExternalOrAnchor(target) {
+ return (
+ target === ''
+ || target.startsWith('#')
+ || target.startsWith('/')
+ || target.startsWith('mailto:')
+ || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target) // has a URL scheme (http:, https:, file:, ...)
+ );
+}
+
+// Resolve `target` (a relative link from `sourceDir`) to its repo-relative
+// path, then return the install-relative path it should point to, or null when
+// the target is not installed by this plan (leave such links untouched).
+function resolveInstalledTarget(target, sourceDir, index) {
+ const hadTrailingSlash = target.endsWith('/');
+ const resolved = stripTrailingSlash(toPosix(posix.normalize(posix.join(sourceDir, target))));
+
+ // Escapes the repo root (starts with `..`) -> not something we placed.
+ if (resolved === '' || resolved === '.' || resolved.startsWith('..')) {
+ return null;
+ }
+
+ if (!hadTrailingSlash && index.byFile.has(resolved)) {
+ return { installed: index.byFile.get(resolved), trailingSlash: false };
+ }
+ if (index.byDir.has(resolved)) {
+ return { installed: index.byDir.get(resolved), trailingSlash: hadTrailingSlash };
+ }
+ return null;
+}
+
+// True when the plan installs `sourceRel` at a different relative path than the
+// source (i.e. a namespace segment was injected, e.g. skills/x -> skills/ecc/x).
+// Callers use this to keep non-namespaced files on the byte-for-byte copy path.
+function isNamespacedSource(sourceRel, index) {
+ const normalizedSource = toPosix(sourceRel);
+ const installedSource = index && index.byFile.get(normalizedSource);
+ return Boolean(installedSource) && installedSource !== normalizedSource;
+}
+
+// Rewrite relative links in a single namespaced markdown file so they resolve
+// to the file's installed location. Returns the content unchanged when the
+// file itself was not namespaced or when no link needs adjustment. Pure: no IO.
+function rewriteRelativeLinks(content, options) {
+ const { sourceRel, index } = options || {};
+ const normalizedSource = toPosix(sourceRel);
+ const installedSource = index && index.byFile.get(normalizedSource);
+
+ // Only rewrite when the file's own install path gained/changed a namespace
+ // segment. If it lands at the same relative path, every link recomputes to
+ // itself, so there is nothing to do.
+ if (!installedSource || installedSource === normalizedSource) {
+ return content;
+ }
+
+ const installedSourceDir = posix.dirname(installedSource);
+ const sourceDir = posix.dirname(normalizedSource);
+ const lines = String(content).split('\n');
+ let inFence = false;
+
+ for (let i = 0; i < lines.length; i += 1) {
+ const fenceToggle = /^\s*(```|~~~)/.test(lines[i]);
+ if (fenceToggle) {
+ inFence = !inFence;
+ continue;
+ }
+ if (inFence) {
+ continue; // never rewrite inside fenced code blocks
+ }
+
+ lines[i] = lines[i].replace(
+ INLINE_LINK_PATTERN,
+ (match, open, target, title, close) => {
+ // Preserve any `#fragment` so anchors survive the rewrite.
+ const hashIdx = target.indexOf('#');
+ const pathPart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+ const fragment = hashIdx === -1 ? '' : target.slice(hashIdx);
+
+ if (isExternalOrAnchor(pathPart)) {
+ return match;
+ }
+
+ const resolution = resolveInstalledTarget(pathPart, sourceDir, index);
+ if (!resolution) {
+ return match;
+ }
+
+ let rewritten = posix.relative(installedSourceDir, resolution.installed);
+ if (rewritten === '') {
+ rewritten = '.';
+ }
+ if (resolution.trailingSlash && !rewritten.endsWith('/')) {
+ rewritten += '/';
+ }
+ // If the recomputed link points to the same place as the original
+ // (e.g. an intra-namespace `./sibling.md` whose endpoints both shift by
+ // the same prefix), keep the original text verbatim — including any
+ // leading `./` — so the rewrite stays a strict no-op where it must.
+ if (posix.normalize(rewritten) === posix.normalize(pathPart)) {
+ return match;
+ }
+ return `${open}${rewritten}${fragment}${title || ''}${close}`;
+ }
+ );
+ }
+
+ return lines.join('\n');
+}
+
+module.exports = {
+ buildInstallIndex,
+ isNamespacedSource,
+ rewriteRelativeLinks,
+};
diff --git a/tests/lib/install-link-rewrite.test.js b/tests/lib/install-link-rewrite.test.js
new file mode 100644
index 000000000..b4a75115d
--- /dev/null
+++ b/tests/lib/install-link-rewrite.test.js
@@ -0,0 +1,231 @@
+/**
+ * Tests for scripts/lib/install/link-rewrite.js — rewriting relative links in
+ * namespaced markdown so they resolve after install (issue #2340).
+ */
+
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+
+const {
+ buildInstallIndex,
+ isNamespacedSource,
+ rewriteRelativeLinks,
+} = require('../../scripts/lib/install/link-rewrite');
+const { createManifestInstallPlan } = require('../../scripts/lib/install-executor');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// A claude-style namespace placement: skills/<id> -> skills/ecc/<id> and
+// rules/<x> -> rules/ecc/<x>. Mirrors what the real adapter emits.
+function claudeNamespaceMappings() {
+ return [
+ { sourceRel: 'skills/react-patterns/SKILL.md', destRel: 'skills/ecc/react-patterns/SKILL.md' },
+ { sourceRel: 'skills/react-patterns/other.md', destRel: 'skills/ecc/react-patterns/other.md' },
+ { sourceRel: 'skills/react-patterns/sub/NOTE.md', destRel: 'skills/ecc/react-patterns/sub/NOTE.md' },
+ { sourceRel: 'rules/react/hooks.md', destRel: 'rules/ecc/react/hooks.md' },
+ { sourceRel: 'rules/react/testing.md', destRel: 'rules/ecc/react/testing.md' },
+ { sourceRel: 'rules/react/coding-style.md', destRel: 'rules/ecc/react/coding-style.md' },
+ ];
+}
+
+// An identity placement (non-namespacing adapter): source == dest.
+function identityMappings() {
+ return [
+ { sourceRel: 'skills/react-patterns/SKILL.md', destRel: 'skills/react-patterns/SKILL.md' },
+ { sourceRel: 'rules/react/hooks.md', destRel: 'rules/react/hooks.md' },
+ ];
+}
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` PASS ${name}`);
+ return true;
+ } catch (error) {
+ console.log(` FAIL ${name}`);
+ console.log(` Error: ${error.message}`);
+ // Preserve the full stack (source line + assertion diff) for diagnosis.
+ console.error(error.stack || error);
+ return false;
+ }
+}
+
+function runTests() {
+ console.log('Running install link-rewrite tests...\n');
+ let passed = 0;
+ let failed = 0;
+
+ const index = buildInstallIndex(claudeNamespaceMappings());
+
+ // Parametrize the canonical file-link case over all three affected skills so
+ // a regression in any one is caught (not just the first).
+ for (const skill of ['react-patterns', 'react-performance', 'react-testing']) {
+ if (test(`rewrites ../../rules file link for ${skill}`, () => {
+ const idx = buildInstallIndex([
+ { sourceRel: `skills/${skill}/SKILL.md`, destRel: `skills/ecc/${skill}/SKILL.md` },
+ { sourceRel: 'rules/react/hooks.md', destRel: 'rules/ecc/react/hooks.md' },
+ ]);
+ const before = 'See [rules](../../rules/react/hooks.md) for details.';
+ const after = rewriteRelativeLinks(before, { sourceRel: `skills/${skill}/SKILL.md`, index: idx });
+ assert.notStrictEqual(after, before, 'rewrite must change the broken link (not vacuous)');
+ assert.ok(
+ after.includes('](../../../rules/ecc/react/hooks.md)'),
+ `expected corrected link, got: ${after}`
+ );
+ assert.ok(!after.includes('](../../rules/'), 'broken depth must be gone');
+ })) passed++; else failed++;
+ }
+
+ if (test('rewrites a directory link and preserves the trailing slash', () => {
+ const before = '- Rules: [rules/react/](../../rules/react/)';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.notStrictEqual(after, before);
+ assert.ok(after.includes('](../../../rules/ecc/react/)'), `got: ${after}`);
+ })) passed++; else failed++;
+
+ if (test('leaves an intra-skill sibling link unchanged', () => {
+ const before = 'Look at [other](./other.md) nearby.';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.strictEqual(after, before, 'same-prefix relative path must be preserved');
+ })) passed++; else failed++;
+
+ if (test('leaves links to non-installed targets unchanged', () => {
+ const before = 'See [pkg](../../package.json) at the root.';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.strictEqual(after, before, 'never invent a path to a file the plan does not install');
+ })) passed++; else failed++;
+
+ if (test('leaves external urls, absolute paths, and anchors unchanged', () => {
+ const before = [
+ '[ext](https://example.com/rules/react/hooks.md)',
+ '[abs](/rules/react/hooks.md)',
+ '[mail](mailto:[email protected])',
+ '[anchor](#a-section)',
+ ].join('\n');
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.strictEqual(after, before);
+ })) passed++; else failed++;
+
+ if (test('preserves a #fragment on a rewritten link', () => {
+ const before = '[hooks](../../rules/react/hooks.md#use-effect)';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.ok(after.includes('](../../../rules/ecc/react/hooks.md#use-effect)'), `got: ${after}`);
+ })) passed++; else failed++;
+
+ if (test('does not rewrite links inside fenced code blocks', () => {
+ const before = [
+ '```md',
+ '[code](../../rules/react/hooks.md)',
+ '```',
+ '[prose](../../rules/react/hooks.md)',
+ ].join('\n');
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index });
+ assert.ok(after.includes('[code](../../rules/react/hooks.md)'), 'code-fence link must be untouched');
+ assert.ok(after.includes('[prose](../../../rules/ecc/react/hooks.md)'), 'prose link must be rewritten');
+ })) passed++; else failed++;
+
+ if (test('computes depth from path math for a nested skill file', () => {
+ // skills/react-patterns/sub/NOTE.md -> skills/ecc/react-patterns/sub/NOTE.md
+ // Source link is ../../../rules/react/hooks.md (3 up from sub/).
+ const before = '[r](../../../rules/react/hooks.md)';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/sub/NOTE.md', index });
+ assert.notStrictEqual(after, before, 'nested depth must be recomputed, not hardcoded');
+ assert.ok(after.includes('](../../../../rules/ecc/react/hooks.md)'), `got: ${after}`);
+ })) passed++; else failed++;
+
+ if (test('is a no-op for a non-namespacing (identity) placement', () => {
+ const idx = buildInstallIndex(identityMappings());
+ const before = '[r](../../rules/react/hooks.md)';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/react-patterns/SKILL.md', index: idx });
+ assert.strictEqual(after, before, 'identity placement must not touch any link');
+ })) passed++; else failed++;
+
+ if (test('is a no-op when the file itself is not in the plan', () => {
+ const before = '[r](../../rules/react/hooks.md)';
+ const after = rewriteRelativeLinks(before, { sourceRel: 'skills/not-installed/SKILL.md', index });
+ assert.strictEqual(after, before);
+ })) passed++; else failed++;
+
+ // Guards the apply-layer gate: only namespaced files leave the byte-copy
+ // path, so non-namespaced markdown is still copied verbatim.
+ if (test('isNamespacedSource flags only files whose install path changed', () => {
+ assert.strictEqual(
+ isNamespacedSource('skills/react-patterns/SKILL.md', index), true,
+ 'a namespaced skill file must be flagged'
+ );
+ const identity = buildInstallIndex(identityMappings());
+ assert.strictEqual(
+ isNamespacedSource('skills/react-patterns/SKILL.md', identity), false,
+ 'an identity-mapped file must stay on the byte-copy path'
+ );
+ assert.strictEqual(
+ isNamespacedSource('skills/not-in-plan/SKILL.md', index), false,
+ 'a file the plan does not install is not namespaced'
+ );
+ })) passed++; else failed++;
+
+ // Integration: real repo content + real claude plan. Every rewritten link in
+ // the three React skills must resolve to a destination the SAME plan installs.
+ if (test('real React skills: rewritten rules links resolve to installed targets', () => {
+ const fs = require('fs');
+ const plan = createManifestInstallPlan({
+ sourceRoot: REPO_ROOT,
+ homeDir: '/tmp/ecc-link-rewrite-it',
+ target: 'claude',
+ moduleIds: ['framework-language', 'rules-core'],
+ });
+ const mappings = plan.operations
+ .filter(op => op.kind === 'copy-file' && op.sourceRelativePath)
+ .map(op => ({
+ sourceRel: op.sourceRelativePath,
+ destRel: path.relative(plan.targetRoot, op.destinationPath),
+ }));
+ const realIndex = buildInstallIndex(mappings);
+ const installedDestRels = new Set(mappings.map(m => m.destRel.replace(/\\/g, '/')));
+
+ const extractLinks = text => {
+ const out = [];
+ const linkPattern = /\]\(([^()\s#]+)/g;
+ let m;
+ while ((m = linkPattern.exec(text)) !== null) {
+ out.push(m[1]);
+ }
+ return out;
+ };
+
+ let changedLinks = 0;
+ for (const skill of ['react-patterns', 'react-performance', 'react-testing']) {
+ const sourceRel = `skills/${skill}/SKILL.md`;
+ const content = fs.readFileSync(path.join(REPO_ROOT, sourceRel), 'utf8');
+ assert.ok(content.includes('](../../rules/'), `${sourceRel} should have a broken link pre-fix`);
+ const rewritten = rewriteRelativeLinks(content, { sourceRel, index: realIndex });
+ assert.ok(!rewritten.includes('](../../rules/'), `${sourceRel} still has the broken depth`);
+
+ // Only links we actually changed are validated here; cross-skill links to
+ // skills outside this module subset are legitimately left untouched.
+ const before = extractLinks(content);
+ const after = extractLinks(rewritten);
+ const installedSkillDir = path.posix.dirname(`skills/ecc/${skill}/SKILL.md`);
+ for (let i = 0; i < after.length; i += 1) {
+ if (after[i] === before[i]) {
+ continue;
+ }
+ const resolved = path.posix
+ .normalize(path.posix.join(installedSkillDir, after[i]))
+ .replace(/\/+$/, '');
+ const isFile = installedDestRels.has(resolved);
+ const isDir = [...installedDestRels].some(d => d.startsWith(`${resolved}/`));
+ assert.ok(isFile || isDir, `rewritten link ${after[i]} -> ${resolved} is not installed`);
+ changedLinks += 1;
+ }
+ }
+ assert.ok(changedLinks >= 3, `expected to verify rewritten links, changed ${changedLinks}`);
+ })) passed++; else failed++;
+
+ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+ process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();