@skillctl/link-manager 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skillctl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './link-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './link-manager.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/link-manager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LinkManager (from PR5 patterns, implemented for PR6).
+ * Handles cross-platform linking: symlink (dir), junction (win), copy fallback.
+ * Safety: realpath verification to ensure targets point inside canonical store.
+ * Used by AgentAdapters' ensureTarget/removeTarget.
+ */
+import type { LinkMode } from '@skillctl/core';
+export interface LinkOptions {
+    mode?: LinkMode;
+    dryRun?: boolean;
+    force?: boolean;
+}
+export declare class LinkManager {
+    /**
+     * Ensure a link (or copy) from canonical skill dir to a target path (agent's skills dir entry).
+     * Creates parent dirs. Overwrites existing if force.
+     * Verifies after creation that realpath(target) resolves to canonical.
+     */
+    ensureLink(canonical: string, target: string, options?: LinkOptions): Promise<void>;
+    removeLink(target: string): Promise<void>;
+    /**
+     * Check if target currently points (via realpath) to the canonical.
+     */
+    isLinkedTo(canonical: string, target: string): Promise<boolean>;
+    /**
+     * Verify that a target (if exists) resolves inside the canonical store (prevent attacks).
+     * Returns true if safe or does not exist.
+     */
+    verifyTargetSafe(target: string, storeRoot: string): Promise<boolean>;
+    private copyDir;
+}
+export declare const linkManager: LinkManager;
+export declare function pathExists(p: string): Promise<boolean>;
+export { join, resolve as pathResolve } from 'node:path';
+export { homedir } from 'node:os';
+//# sourceMappingURL=link-manager.d.ts.map

package/dist/link-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-manager.d.ts","sourceRoot":"","sources":["../src/link-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,WAAW;IACtB;;;;OAIG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmEvF,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/C;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWrE;;;OAGG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAY7D,OAAO;CAKtB;AAGD,eAAO,MAAM,WAAW,aAAoB,CAAC;AAG7C,wBAAsB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO5D;AAED,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/link-manager.js

@@ -0,0 +1,143 @@
+/**
+ * LinkManager (from PR5 patterns, implemented for PR6).
+ * Handles cross-platform linking: symlink (dir), junction (win), copy fallback.
+ * Safety: realpath verification to ensure targets point inside canonical store.
+ * Used by AgentAdapters' ensureTarget/removeTarget.
+ */
+import { symlink, rm, stat, realpath, access, constants, cp as fsCp } from 'node:fs/promises';
+import { dirname, resolve as pathResolve } from 'node:path';
+import { ensureDir } from '@skillctl/core';
+export class LinkManager {
+    /**
+     * Ensure a link (or copy) from canonical skill dir to a target path (agent's skills dir entry).
+     * Creates parent dirs. Overwrites existing if force.
+     * Verifies after creation that realpath(target) resolves to canonical.
+     */
+    async ensureLink(canonical, target, options = {}) {
+        const mode = options.mode || (process.platform === 'win32' ? 'junction' : 'symlink');
+        const dry = !!options.dryRun;
+        if (dry) {
+            console.log(`[dry-run] would link ${canonical} -> ${target} (${mode})`);
+            return;
+        }
+        await ensureDir(dirname(target));
+        // cleanup existing
+        if (options.force) {
+            try {
+                await rm(target, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+        // Check if already correctly linked
+        if (await this.isLinkedTo(canonical, target)) {
+            return;
+        }
+        try {
+            if (mode === 'copy') {
+                await this.copyDir(canonical, target);
+                return;
+            }
+            if (mode === 'junction' || process.platform === 'win32') {
+                // Prefer junction on win for broader compat (no dev mode needed for junctions)
+                try {
+                    await symlink(canonical, target, 'junction');
+                }
+                catch (e) {
+                    if (e.code === 'EPERM' || e.code === 'EEXIST') {
+                        // fallback to copy with warning
+                        console.warn(`[link-manager] junction failed for ${target}, falling back to copy`);
+                        await this.copyDir(canonical, target);
+                        return;
+                    }
+                    throw e;
+                }
+            }
+            else {
+                // Unix dir symlink
+                await symlink(canonical, target, 'dir');
+            }
+            // verify
+            if (!(await this.isLinkedTo(canonical, target))) {
+                // cleanup bad link and fallback
+                await rm(target, { recursive: true, force: true }).catch(() => { });
+                console.warn(`[link-manager] link verification failed, falling back to copy for ${target}`);
+                await this.copyDir(canonical, target);
+            }
+        }
+        catch (err) {
+            // general fallback to copy on error (e.g. EPERM no dev mode)
+            if (mode !== 'copy') {
+                console.warn(`[link-manager] link error (${err.code || err.message}), fallback copy: ${target}`);
+                await this.copyDir(canonical, target);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    async removeLink(target) {
+        try {
+            const st = await stat(target).catch(() => null);
+            if (!st)
+                return;
+            // remove regardless of symlink/junction/dir
+            await rm(target, { recursive: true, force: true });
+        }
+        catch {
+            // best effort
+        }
+    }
+    /**
+     * Check if target currently points (via realpath) to the canonical.
+     */
+    async isLinkedTo(canonical, target) {
+        try {
+            // realpath follows symlinks/junctions
+            const targetReal = await realpath(target);
+            const canonReal = await realpath(canonical).catch(() => canonical);
+            return pathResolve(targetReal) === pathResolve(canonReal);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Verify that a target (if exists) resolves inside the canonical store (prevent attacks).
+     * Returns true if safe or does not exist.
+     */
+    async verifyTargetSafe(target, storeRoot) {
+        try {
+            const st = await stat(target);
+            if (!st)
+                return true;
+            const tReal = await realpath(target);
+            const storeReal = await realpath(storeRoot);
+            return tReal.startsWith(storeReal);
+        }
+        catch {
+            return true; // non existing ok
+        }
+    }
+    async copyDir(src, dest) {
+        await ensureDir(dest);
+        // Use recursive cp (node 16.7+)
+        await fsCp(src, dest, { recursive: true, force: true });
+    }
+}
+// Singleton for convenience
+export const linkManager = new LinkManager();
+// Also export low level helpers used by adapters if needed
+export async function pathExists(p) {
+    try {
+        await access(p, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { join, resolve as pathResolve } from 'node:path';
+export { homedir } from 'node:os';
+//# sourceMappingURL=link-manager.js.map

package/dist/link-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-manager.js","sourceRoot":"","sources":["../src/link-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@skillctl/link-manager",
+  "version": "0.2.0",
+  "description": "Link manager for symlinks, junctions, copies across agent adapters for skillctl",
+  "license": "MIT",
+  "author": "skillctl contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@skillctl/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "rimraf": "^5.0.7",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xFurti/skillctl.git",
+    "directory": "packages/link-manager"
+  },
+  "keywords": [
+    "link-manager",
+    "symlink",
+    "junction",
+    "skills",
+    "agent-skills"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "clean": "rimraf dist",
+    "lint": "tsc --noEmit",
+    "test": "node --test ./dist/test/*.test.js 2>&1 || echo 'run after build'"
+  }
+}